shopware-php-code

name	shopware-php-code
description	Apply Shopware PHP/server-side coding guidance. Use when editing PHP under src/Core, src/Administration, or src/Storefront — including migrations, API schema, deprecations, or BC-sensitive code.
license	MIT

Shopware PHP Code

Prefer the existing Shopware extension point over a new abstraction.

Structure

• Keep application/domain services hexagonal: controllers, CLI commands, subscribers, and handlers translate infrastructure details (Request, IO, database, filesystem, HTTP) into plain inputs before calling services.
• Services must not perform direct infrastructure work or depend on framework objects. Depend on narrow abstractions instead, such as repositories, filesystem interfaces, HTTP clients, or gateways.
• Where code legitimately touches the local filesystem, inject and use the Symfony Filesystem component instead of raw PHP functions like mkdir, file_put_contents, copy, unlink, or rmdir. It throws IOException instead of warnings plus false returns, handles recursive operations, and keeps the dependency mockable.
• Services must be unit-testable without external systems; test infrastructure adapters with integration tests.
• Mark infrastructure adapters @internal by default.
• Mark supported/public concrete classes as @final when they are not intended for extension.
• Use a real final class for simple value objects/structs that do not need extension, decoration, or mocking; use @final for supported services where tests or framework mechanics may still need to subclass/mock them.
• Do not add @final to classes already marked @internal; the internal marker is enough for implementation details.
• Do not repeat @internal on constructors or methods inside an @internal class.
• Prefer existing Shopware extension mechanisms over new provider interfaces when they already express the contract, for example Twig inheritance, DAL entities, Admin API routes, or explicit Twig blocks.
• Be conservative with DTOs/value objects. Add one only when it expresses a meaningful domain concept, crosses a real boundary, or simplifies a public contract. Prefer scalars or arrays for simple internal data, and do not create DTOs solely to model private handoffs inside one class.
• For transparent struct-style value objects, prefer public readonly properties over private properties plus trivial getters.
• Name the arguments when a call passes several values that do not describe themselves — true, false, 0, 1, [], null — or when naming lets you skip defaults you only passed in order to reach a later argument. Leave a short, self-explaining call positional.

Public Surface

• For new feature designs, explicitly separate the BC-promised public surface from internal implementation services. Document public REST/Admin/Store API contracts, DAL entities, template context, and supported extension points; mark controllers, subscribers, loaders, renderers, and discovery services @internal unless they are intended extension points.

API Schema

• When adding core Admin API or Store API action routes, add the matching OpenAPI JSON schema under src/Core/Framework/Api/ApiDefinition/Generator/Schema/<AdminApi|StoreApi>/paths.
• Run tests/integration/Core/Framework/ApiRoutesHaveASchemaTest.php for new or changed core API routes to catch missing paths, method mismatches, and stale schema entries.
• The HTTP route contract can be public even when the PHP controller class is internal; document those separately.

Deprecations

• Use a BC-change attribute from Shopware\Core\Framework\Deprecation\BCChange for a planned major-version change to supported API when there is no replacement to migrate to today. It is planning metadata, not a deprecation: keep the API usable until the announced version and do not use @deprecated reason:* markers.
• Use the most specific attribute. CallSiteCompatibilityChange means calling the method can break (including parent:: calls from subclasses); ExtenderCompatibilityChange means an overriding declaration or inheritance relationship can break. Attributes that implement both affect both audiences.
• Use @deprecated only when functionality is actually removed or has a replacement that external code must migrate to. Executable deprecated paths need Feature::triggerDeprecationOrThrow(); when an attribute's legacy usage is detectable at runtime (BecomesAbstract, NewRequiredParameter, ParameterRemoval, or ParameterTypeNarrowing), add the same conditional signal unless the method is framework-invoked.
• Keep attribute values machine-readable: use a vX.Y.Z version, parameter names without $, ::class for class references, and the real default value for NewOptionalParameter.
• Core code should never trigger self-deprecation notices. If core must keep calling deprecated behavior for BC, wrap that call with Feature::silent($majorFlag, static fn () => ...) so the deprecation notice is suppressed, the code path is explicitly tied to the major feature flag, and the branch will disappear when the flag is removed.
• Do not mark DI service definitions as deprecated while Shopware core still references that service id anywhere. Internal DI references still trigger container deprecations and spam logs during warmup/compile. Deprecate the PHP API or class if needed, but only add the DI <deprecated> service tag once core no longer uses that service internally.
• When adding an @deprecated annotation to executable PHP code, add a matching Feature::triggerDeprecationOrThrow() in the deprecated code path unless the deprecation uses an explicit exception reason supported by the PHPStan deprecation rule.
• Do not leave new Shopware core code paths calling deprecated functionality. Move internal callers to the replacement API/service and keep legacy behavior only in focused BC tests.
• For private implementation cleanup reminders, do not add method-level deprecations. Use a short inline comment near the branch or code that should be removed later, with enough detail to simplify the future cleanup.

Migrations

• Use the exact current Unix timestamp for new migration class names, file names, and getCreationTimestamp() values. Do not use placeholder or rounded timestamps.
• Do not add tests for empty/no-op updateDestructive() implementations; cover meaningful migration behavior in update() or destructive migrations that actually change state.

Detailed Guidelines

• Read coding-guidelines/core/internal.md and coding-guidelines/core/final-and-internal.md when marking PHP API surface as internal, final, or supported for extension.
• Read coding-guidelines/core/extendability.md and coding-guidelines/core/decorator-pattern.md when adding or changing extension points.
• Read coding-guidelines/core/database-migations.md when adding or changing migrations.
• Read coding-guidelines/core/feature-flags.md when adding feature-flagged behavior, deprecations, or BC branches.
• Read coding-guidelines/core/6.5-new-php-language-features.md when reaching for a newer language feature, named arguments included.