Allow Url objects to specify the Domain as an option

Hi @idebr, can you give a few use cases (besides source domain) for this feature?

Isn't domain_source supposed to do that automatically? 🤔

Analysis

The DomainSourcePathProcessor already supports an explicit domain_target_id URL option that bypasses the entity field lookup. So you can already do:

$url->setOption('domain_target_id', 'example_com');

But this only works when domain_source is installed, since the path processor lives entirely in that submodule. The base domain module has no outbound path processor at all.

The core rewriting logic in DomainSourcePathProcessor is just two lines:

$options['base_url'] = $source_domain->getPath();

$options['absolute'] = TRUE;

The proposal would split the 664-line processor into two concerns:

1. Base domain module — a lightweight outbound path processor that reads a domain option from the URL and rewrites base_url + absolute. No entity awareness, no route matching — just "if a domain is specified, use it."
2. domain_source module — keeps all the entity/route/field logic, but instead of rewriting the URL itself, it sets $options['domain'] and lets the base processor handle the rewrite.

This would allow any custom code to target a specific domain on a Url object without needing domain_source enabled — covering the use cases described (canonical URLs, cross-domain search links, card overlays).

Considerations

• The domain_source processor also handles language negotiation re-processing, destination parameter rewriting, and alter hooks (hook_domain_source, hook_domain_source_path). Those would stay in domain_source.
• Processor priority ordering matters — the base domain processor would need to run after domain_source sets the option but before the final URL is built.
• The existing domain_target_id option could be kept for BC, with the new domain option accepting either a domain entity or a machine name.

Summary

Added a lightweight outbound path processor to the base domain module, enabling any code to target a specific domain on a Url object without installing domain_source:

$url->setOption('domain', 'example_com');
// or
$url->setOption('domain', $domainEntity);

Commit 1: feat: #3574800 Allow Url objects to specify the Domain as an option

New file domain/src/HttpKernel/DomainPathProcessor.php implements OutboundPathProcessorInterface:

• Checks for a domain URL option
• Accepts either a DomainInterface entity or machine name string
• Sets $options['base_url'] and $options['absolute'] = TRUE when valid
• Adds the domain entity as a cacheable dependency (cache tag invalidation when the domain changes)
• Skips external URLs and gracefully handles invalid/missing domain values
• Single dependency: EntityTypeManagerInterface (autowired)

New kernel test file domain/tests/src/Kernel/DomainPathProcessorTest.php with 7 test methods covering:

• Rewrite with string machine name
• Rewrite with DomainInterface entity
• No-op when domain option is absent
• External URL skipped
• Invalid domain string handled gracefully
• Invalid option type handled gracefully
• NULL bubbleable metadata handled

Modified domain/domain.services.yml registers the service as domain.path_processor with path_processor_outbound tag at priority 80 — runs after domain_source (90).

DomainSourcePathProcessor was not changed in this commit.

Commit 2: Delegate URL rewriting from DomainSourcePathProcessor to DomainPathProcessor

DomainSourcePathProcessor (priority 90) no longer rewrites base_url/absolute itself. Instead, when a source domain differs from the active domain, it sets $options['domain'] = $source and lets DomainPathProcessor (priority 80) handle the actual URL rewriting.

Changes in DomainSourcePathProcessor::processOutbound():

• Early return if $options['domain'] is already set — avoids double-processing.
• Replaced $options['base_url'] = rtrim($source->getPath(), '/') + $options['absolute'] = TRUE + addCacheContexts(['url.site']) with $options['domain'] = $source.

Commit 3: Move cross-domain URL rewriting features to DomainPathProcessor

Language negotiation re-processing and destination parameter handling are not domain_source-specific — they apply to any cross-domain URL rewrite. Moving them into DomainPathProcessor ensures any code setting $options['domain'] automatically gets these features.

DomainPathProcessor (domain module)

• Added dependencies: ConfigFactoryInterface, DomainNegotiationContext, ?LanguageNegotiatorInterface
• Added methods: isLanguageNegotiationEnabled(), isSameLanguageNegotiationConfig(), processLanguageNegotiationOutbound(), isDestinationDomainEnabled(), processDestinationParameter(), reset()
• processOutbound() now runs cross-domain features (language negotiation + destination parameter) after resolving the domain and before setting base_url/absolute
• Refined cache metadata: addCacheableDependency($domain) is added unconditionally (cache tag invalidation when the domain entity changes); url.site cache context is added only when destination parameter processing is active (the only output that includes the current domain's host)

DomainSourcePathProcessor (domain_source module)

• Removed the $languageNegotiator constructor parameter and LanguageNegotiatorInterface import
• Removed all four cached properties and five methods related to language negotiation and destination parameter handling
• Simplified reset() — no longer clears language-related caches

Settings migration

• Settings moved from domain_source.settings to domain.settings:
  • source_language_negotiation → language_negotiation
  • allow_destination_domain → allow_destination_domain
• Config schema and install defaults updated in both modules
• Form elements moved from DomainSourceSettingsForm to DomainSettingsForm, wrapped in a closed-by-default "Experimental features" details group
• Labels updated: "source domain" → "target domain"

Update hooks

• domain_update_10002() — Initializes language_negotiation and allow_destination_domain in domain.settings (defaults to FALSE)
• domain_source_update_10004() — Migrates values from domain_source.settings to domain.settings and clears the old keys

Tests

• DomainSourceLanguageNegotiationTest: config references updated to domain.settings:language_negotiation; clearCaches() now also resets domain.path_processor
• DomainSourceDestinationKernelTest: config and service references updated to domain.settings / domain.path_processor

Documentation and DomainSourceToken Simplification

Two new documentation commits added:

1. Documentation pages (docs/)

New page docs/domain/index.md documents the Domain module's cross-domain URL rewriting:

• The $options['domain'] URL option usage with machine name string or DomainInterface entity
• How DomainPathProcessor::processOutbound() resolves the domain, applies features, rewrites URLs, and adds cache metadata
• Integration with Domain Source — DomainSourcePathProcessor sets $options['domain'] and delegates
• Experimental features documentation:
  • Language negotiation for cross-domain URLs — re-runs LanguageNegotiationUrl in the target domain's context when configs differ
  • Domain-scoped destination redirects — adds destination_domain query parameter for cross-domain redirect accuracy

Updated page docs/domain_source/index.md:

• Simplified to describe delegation via $options['domain']
• New Token section documents [node:canonical-source-domain-url] token — useful when canonical route is added to Excluded entity route suffixes
• Cross-domain features now reference Domain module documentation

mkdocs.yml — Added the "Domain" nav entry.

2. Simplify DomainSourceToken

Refactored to use $options['domain'] mechanism instead of getExcludedRoutes() logic.

Before: The token checked if canonical was in excluded routes. If excluded, it manually built the URL via Domain::buildUrl(). Otherwise, it called toUrl()->setAbsolute()->toString() and relied on the path processor.

After: The token sets $url->setOption('domain', $source) on the Url object and lets DomainPathProcessor handle rewriting. This works regardless of exclude_routes configuration — when DomainSourcePathProcessor encounters a URL with $options['domain'] already set, it returns immediately.

Uses $url->setAbsolute()->toString(TRUE) to get a GeneratedUrl object (which extends BubbleableMetadata) instead of a plain string. This captures all cache metadata from the URL generation chain — including the domain entity's cache tags added by DomainPathProcessor. The URL string is extracted via getGeneratedUrl() and all cache metadata is merged into the token's $bubbleable_metadata via merge().

Removed:

• ConfigFactoryInterface dependency
• $excludedRoutes property
• getExcludedRoutes() method

The DomainSourceTokenTest passes (1 test, 8 assertions).

BC Breaking Changes Analysis

Analysis of the full changeset from #3574800 (5 commits) evaluated as a single before/after comparison.

Medium

1. Public API removed from DomainSourceToken

• Public property $excludedRoutes — removed
• Public method getExcludedRoutes() — removed
• Constructor __construct(ConfigFactoryInterface) — removed entirely

Impact: Any code accessing the property, calling the method, or instantiating/subclassing DomainSourceToken will break.

Low

2. Constructor changes in DomainSourcePathProcessor

• ?LanguageNegotiatorInterface $languageNegotiator (last parameter) — removed
• $pathMatcher and $sourceHelper — swapped ($sourceHelper is now before $pathMatcher, positioning $pathMatcher last for easier future removal)

Impact: Only affects subclasses calling parent::__construct() with positional arguments; normal DI autowiring is unaffected.

Summary