Problem/Motivation

The 2.x codebase does not meet current Drupal coding standards / best practices, and has
accumulated several inconsistencies:

  • Legacy annotation-based plugin discovery. Both the module's own
    Shortcode plugin type (@Shortcode(...), discovered via
    Drupal\shortcode\Annotation\Shortcode) and its two Filter plugins
    (@Filter(...)) still use docblock annotations instead of PHP attributes.
  • Manual create() boilerplate everywhere. Every
    ContainerFactoryPluginInterface plugin (Shortcode,
    ShortcodeCorrector, ShortcodeBase, BlockShortcode,
    ImageShortcode) hand-writes a create() method, even though
    Drupal\Core\Plugin\PluginBase::create() (parent of both FilterBase and
    ShortcodeBase) already autowires constructor arguments via reflection.
  • A dependency injection violation inherited by every shortcode plugin.
    ShortcodeBase::getMediaFileUrl() / getImageProperties() call
    Media::load() statically instead of injecting entity_type.manager, and
    this media-specific code is inherited by every shortcode plugin regardless of whether it
    touches media.
  • Deprecated API usage. 9 of the 11 shortcode plugins import the deprecated
    Drupal\Core\Language\Language class instead of
    Drupal\Core\Language\LanguageInterface.
  • Procedural-style caching inside a service class.
    ShortcodeService uses drupal_static() three times for memoization
    despite already being a container singleton, where plain instance properties would do.
  • Inconsistent core_version_requirement. All three
    .info.yml files (shortcode, shortcode_basic_tags,
    shortcode_example) declare ^9.3 || ^10 || ^11, but the code already
    uses #[Hook] attributes, which require Drupal 11.1+ — the stated floor is already
    false.
  • Redundant procedural hook shims. shortcode.module and
    shortcode_basic_tags.module each contain a thin #[LegacyHook]-wrapped
    procedural function that just forwards to the equivalent OOP #[Hook] method via
    \Drupal::service(...) — unnecessary, since Drupal's hook-attribute discovery finds
    the OOP methods directly.
  • Dead code and docblock bugs. ShortcodeService::isBool() is
    unused, there are stray commented-out debug lines, and shortcode.module /
    shortcode_basic_tags.module each had a duplicate/misplaced @file
    docblock (an empty one at the top of the file, a populated one floating elsewhere, in one case
    inside a class body).
  • Missing strict typing. Most files lack
    declare(strict_types=1); and full param/return type hints on
    process()/tips()/settingsForm() overrides.

Steps to reproduce

Not applicable — this is a code-quality/modernization task, not a bug. For evidence, see:

  • src/Plugin/Filter/Shortcode.php, src/Plugin/Filter/ShortcodeCorrector.php — annotations + manual create().
  • src/Plugin/ShortcodeBase.php — static Media::load(), manual create().
  • src/ShortcodeService.php — drupal_static() usage, unused isBool().
  • shortcode_basic_tags/src/Plugin/Shortcode/*.php — deprecated Language class usage.
  • shortcode.info.yml, shortcode_basic_tags/shortcode_basic_tags.info.yml, shortcode_example/shortcode_example.info.yml — core_version_requirement.

Proposed resolution

  1. Plugin discovery: add a new Drupal\shortcode\Attribute\Shortcode PHP attribute (mirroring today's annotation fields). ShortcodePluginManager discovers both the new attribute and the legacy @Shortcode annotation simultaneously, so third-party modules with un-migrated Shortcode plugins keep working. This module's own plugins (shortcode_basic_tags, shortcode_example) and its two Filter plugins are converted to attributes (#[Filter(...)] / #[Shortcode(...)]) now.
  2. DI/autowiring: delete all hand-written create() methods; rely on PluginBase::create()'s built-in autowiring. Add two FQCN service aliases to shortcode.services.yml (Drupal\shortcode\ShortcodeService: '@shortcode', Drupal\shortcode\ShortcodePluginManager: '@plugin.manager.shortcode'), the same pattern core uses for its own services, so plain type-hinted constructors resolve without needing #[Autowire] attributes. Convert all plugin constructors to promoted, typed properties.
  3. Extract media handling: new MediaUrlResolverInterface/MediaUrlResolver service (injecting entity_type.manager, no static calls), injected into ShortcodeBase; ImageShortcode drops its redundant separate entity-type-manager injection.
  4. Deprecated API cleanup: Language → LanguageInterface everywhere; replace drupal_static() with instance properties; remove isBool() and stray debug comments.
  5. Type safety: add declare(strict_types=1); and full param/return types across all plugin classes; fix the duplicate/misplaced @file docblocks.
  6. Remove legacy hook shims: delete the procedural #[LegacyHook] wrappers; keep only the OOP #[Hook] methods.
  7. Bump core_version_requirement to ^11.1 || ^12 on all three .info.yml files.
  8. Harden the parser: add Unit test coverage for ShortcodeService::process() (nesting, self-closing tags, escaping, unknown/disabled tags) as a safety net, then decompose the method into smaller named private steps with no behavior change.

No change to shortcode syntax, rendered markup, or the settings-form UI is intended. The existing Functional test suite (ShortcodeTest) is the regression baseline throughout.

Remaining tasks

  • [ ] Add Shortcode PHP attribute class; wire dual attribute/annotation discovery in ShortcodePluginManager.
  • [ ] Convert Filter/ShortcodeCorrector to #[Filter(...)]; convert all shortcode_basic_tags and shortcode_example plugins to #[Shortcode(...)].
  • [ ] Add FQCN service aliases; delete manual create() methods module-wide; promote/type constructors.
  • [ ] Extract MediaUrlResolver service; update ShortcodeBase and ImageShortcode.
  • [ ] Replace deprecated Language class usage with LanguageInterface.
  • [ ] Replace drupal_static() with instance properties in ShortcodeService; remove dead code.
  • [ ] Add declare(strict_types=1); and full type hints module-wide; fix duplicate/misplaced @file docblocks.
  • [ ] Remove legacy procedural hook shims.
  • [ ] Bump core_version_requirement in all three .info.yml files.
  • [ ] Add Unit tests for ShortcodeService::process(); decompose the method.
  • [ ] Full regression pass: existing Functional ShortcodeTest must keep passing unchanged.

User interface changes

None.

API changes

  • New Drupal\shortcode\Attribute\Shortcode PHP attribute for declaring Shortcode plugins (existing @Shortcode annotation continues to work — no break for third-party Shortcode plugins).
  • New MediaUrlResolverInterface/MediaUrlResolver service.
  • ShortcodeBase's constructor signature changes (adds the injected MediaUrlResolverInterface; drops manual create()) — a break only for third-party code that extends ShortcodeBase and overrides create()/__construct() directly; plugins that only override process()/tips() are unaffected.
  • core_version_requirement raised to ^11.1 || ^12 (drops previously-inaccurate claimed support for ^9.3/^10).

Data model changes

None.

Issue fork shortcode-3621461

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:

Comments

denes.szabo created an issue. See original summary.

denes.szabo’s picture

Status: Active » 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.

denes.szabo’s picture

Assigned: denes.szabo » Unassigned
Status: Fixed » Closed (fixed)