task: mark implementation classes as @internal across all submodules

Frank Mablyrequested to merge
issue/domain-3584261:3584261-mark-internal-classes into 3.x

Summary

Add @internal PHPDoc tag to implementation classes that define their own constructor across domain and all submodules. Mark all hook classes as final. Add @final to DomainNegotiationContext. Add @phpstan-ignore comments to legacy hook stubs and submodule classes that reference internal classes.

Classes without their own constructor are NOT marked @internal since their constructor signature is inherited and not ours to break.

What changed

  • 55 classes marked @internal (services, event subscribers, path processors, access checkers, and other classes with custom constructors)
  • 16 hook classes marked final (hook classes are implementation details, never meant to be extended)
  • 1 class marked @final (DomainNegotiationContext - injectable but not extendable)
  • 58 @phpstan-ignore comments added to .module/.install files for legacy hook stubs calling internal classes
  • 2 @phpstan-ignore-next-line on submodule classes extending internal parents (DomainConfigUILanguageManager, DomainSourceElementManager)
  • domain_config_test.install: replaced @phpstan-ignore-next-line with @var interface type hints

Public API (NOT marked @internal)

  • All *Interface files
  • DomainNegotiationContext (@final)
  • Base classes extended by submodules: DomainBlockBase, DomainControllerBase, DomainCommands, DomainAccessControlHandler, DomainElementManager, DomainConfigLanguageManager
  • Extensible Views access plugins: DomainAccessContent, DomainAccessEditor, DomainContentAccess, DomainEditorAccess
  • Action base classes: DomainAccessActionBase, DomainSourceActionBase
  • DomainSourceElementManager, DomainConfigMigration
  • All exception classes, traits, event constants/objects
  • All classes without a custom constructor (entities, forms, controllers, plugins, constraints, etc.)

Verification

  • PHPStan: 0 errors (full analysis)
  • PHPStan on external modules (domain_extras, domain_redirect, domain_shorturl, domain_path): 0 @internal-related regressions
  • PHPCS: 0 errors
Edited by Frank Mably

Merge request reports