Problem

The domain_path module does not distinguish between public API classes and internal implementation details. This makes refactoring difficult because any change is a potential BC break.

Follows the same approach as the domain module (#3584261).

Proposal

Add @internal to implementation classes across domain_path and domain_path_pathauto submodule.

Public API (no @internal)

  • DomainAliasManagerInterface
  • DomainAliasRepositoryInterface
  • DomainPathAliasInterface
  • DomainAliasStorageHelperInterface

Internal (add @internal)

All other classes: repository, manager, helper, entity, list builder, event subscriber, forms, hooks, path processor, field types/widgets, validation constraints, and domain_path_pathauto classes.

Issue fork domain_path-3584294

Command icon Show commands

Start within a Git clone of the project using the version control instructions.

Or, if you do not have SSH keys set up on git.drupalcode.org:

About issue forks

Comments

mably created an issue. See original summary.

mably opened merge request !105

mably’s picture

mably commented
Status: Active » Needs review
mably’s picture

mably commented

API boundary annotations

Implementation classes are now marked with the following annotations:

  • @internal on all implementation classes (services, plugins, constraints, etc.): signals that these are not part of the public API and may change without notice between minor releases. External code should type-hint against interfaces (DomainAliasManagerInterface, DomainAliasRepositoryInterface, DomainPathAliasInterface) rather than concrete classes.
  • @final on DomainPathHelper: this utility class should not be extended but is not internal. External code can inject and use it via the domain_path.helper service. No interface is needed because there is no valid use case for providing an alternative implementation.
  • final (PHP keyword) on all OOP hook classes (DomainPathFormHooks, DomainPathEntityHooks, DomainPathPathautoHooks): hook classes are discovered by HookCollectorPass via #[Hook] attributes on the declared class. Extending them does not re-discover the parent hooks, so subclassing is functionally useless.

How to customize behavior

To customize domain path form behavior, implement hook_form_alter() or hook_form_FORM_ID_alter() in your own module. To customize entity hooks, implement the corresponding hooks.

If you have a use case that cannot be addressed through hooks and requires a new extension point, please open an issue in the domain_path issue queue and we will evaluate whether to expose a new interface or service.

mably opened merge request !109

  • mably committed d46dcc22 on 3.x 
    task: #3584294 Mark implementation classes with @internal to clarify...

  • mably committed 80e1b763 on 2.x 
    task: #3584294 Mark implementation classes with @internal to clarify...
mably’s picture

mably commented
Status: Needs review » Fixed

Now that this issue is closed, review the contribution record.

As a contributor, attribute any organization that helped you, or if you volunteered your own time.

Maintainers, credit people who helped resolve this issue.

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.