Domain Country Path
Extends the Domain module to support country-based URL path prefixes, allowing multiple domains to share the same hostname while being distinguished by a path prefix.
country_path
Install
composer require 'drupal/country_path:8.x-1.10'
Overview
Domain Country Path is an extension for the Domain module that enables country or region-specific URL path prefixes on multi-country websites. Instead of using different hostnames or subdomains for each country (e.g., usa.example.com, france.example.com), this module allows you to use path prefixes (e.g., example.com/usa, example.com/france) while maintaining separate domain contexts.
The module automatically handles URL processing both inbound (stripping the country prefix for internal routing) and outbound (adding the prefix to generated URLs). It also provides a custom language negotiation plugin that properly handles language detection when country paths are in use, ensuring both country paths and language prefixes work together seamlessly (e.g., example.com/usa/en, example.com/france/fr).
Domain Country Path integrates with Domain Alias module when available, extending alias patterns to support country path suffixes. It also provides a dedicated cache context (url.country) for proper cache variation based on the active country/domain.
Features
- Country-based URL path prefixes that allow multiple domains to share a single hostname (e.g., example.com/usa, example.com/france)
- Automatic inbound path processing that strips country prefixes for proper Drupal routing
- Automatic outbound path processing that adds country prefixes to all generated URLs
- Custom language negotiation plugin (country-path-language-url) that handles language detection with country path prefixes
- Cache context (url.country) for proper cache variations based on active country/domain
- Integration with Domain Alias module for country-aware alias patterns
- Extended Domain entity forms with country path configuration fields
- Automatic domain detection based on URL path prefix in addition to hostname
Use Cases
Multi-country e-commerce site with single hostname
An e-commerce site wants to serve different countries (USA, France, Germany) from a single hostname (shop.example.com) but with country-specific content and settings. Using Domain Country Path, they configure domains as shop.example.com/usa, shop.example.com/france, and shop.example.com/de. Each country has its own domain context for content visibility, pricing, and settings, while sharing the same hostname.
Regional content with language variations
A company website needs to serve content to different regions with multiple languages. For example, shop.example.com/usa/en (USA English), shop.example.com/france/fr (France French), shop.example.com/france/en (France English). The module handles the country prefix while Drupal's language system handles the language prefix, resulting in clean URL structures.
Simplified DNS management for multi-region sites
Instead of managing multiple DNS records for country-specific subdomains (usa.example.com, france.example.com), a single DNS entry for example.com serves all countries through path prefixes. This simplifies SSL certificate management and DNS configuration while maintaining separate domain contexts for each country.
Tips
- When entering a hostname with a country path in the domain form, use a forward slash to separate them (e.g., example.com/usa). The module parses this automatically.
- The country path prefix becomes the first segment of all URLs for that domain, appearing before any language prefix.
- Domain Alias patterns that end with a wildcard (*) should not include the country path as it will be added automatically.
- The module provides the 'url.country' cache context - use this in custom code when rendering content that varies by country.
- For best performance, enable page caching with the url.country cache context to cache pages per country.
Technical Details
Admin Pages 2
/admin/config/domain
Extended domain listing that displays the country path suffix alongside each domain's hostname. The list shows domains with their full path (e.g., example.com/usa) as clickable links that navigate to that domain context.
/admin/config/domain/add
Extended domain creation form that accepts hostnames with country path suffixes. When entering a hostname like 'example.com/usa', the module automatically parses and stores the hostname (example.com) and country path (usa) separately.
Hooks 5
hook_domain_request_alter
Alters the domain detection to support path-based country prefixes. Checks the URL path for a country prefix and loads the corresponding domain if found.
hook_entity_type_build
Overrides the Domain entity class with CountryPathDomain to modify the preSave behavior for hostname validation.
hook_entity_type_alter
Overrides Domain and Domain Alias entity form handlers with custom forms that support country path parsing.
hook_form_alter
Modifies domain and domain alias forms to support country path input in the hostname field.
hook_language_types_info_alter
Adds the country-path-language-url negotiator to the fixed enabled URL language negotiators for proper multilingual support.
Troubleshooting 4
Ensure the domain is properly configured with the country path. Edit the domain and enter the hostname with the path suffix (e.g., example.com/usa). Verify the domain appears correctly in the domain list with the full path.
Ensure the Language module is installed and the 'Country Path Language Handler URL' negotiator is enabled. The module automatically activates this on installation, but you can verify at /admin/config/regional/language/detection.
When creating aliases for domains with country paths, ensure non-wildcard patterns include the country path suffix (e.g., example.org/usa). Wildcard patterns (e.g., *.example.com) should not include the country path as it will be added automatically.
Ensure the 'url.country' cache context is being applied. The module adds this automatically to outbound URLs. If you have custom caching logic, add 'url.country' to your cache contexts.
Security Notes 3
- The module validates country path patterns to prevent invalid characters and security issues.
- Hostname validation is extended to allow forward slashes only for country path separation.
- The module does not add any new permissions - it relies on existing Domain module permissions for access control.