craft-php-guidelines

Craft CMS 5 PHP Guidelines

Complete PHP coding standards and conventions for Craft CMS 5 plugin and module development. These extend Craft's official coding guidelines with project-specific conventions.

Core principles: PHPDocs on everything — classes, methods, and properties — regardless of type hints. No declare(strict_types=1) in plugin source files (matching Craft core convention).

Companion Skills — Always Load Together

• craftcms — Architecture patterns, element lifecycle, controllers, events, migrations. Required for any Craft plugin or module development.
• ddev — All commands run through DDEV. Required for running ECS, PHPStan, scaffolding, and tests.

Documentation

• Official coding guidelines: https://craftcms.com/docs/5.x/extend/coding-guidelines.html
• Class reference: https://docs.craftcms.com/api/v5/
• Generator reference: https://craftcms.com/docs/5.x/extend/generator.html

When unsure about a convention, WebFetch the coding guidelines page for the authoritative answer.

Common Pitfalls

• addSelect() is the convention in beforePrepare() — safely additive when multiple extensions contribute columns.
• $_instances is not a Craft convention — private properties use underscore prefix but meaningful names like $_items, $_sections.
• Records use the same class name as models (namespace distinguishes). Alias when importing both: use ...\records\MyEntity as MyEntityRecord;.
• Queue jobs have no "Job" suffix — ResaveElements, not ResaveElementsJob.
• declare(strict_types=1) is NOT used in plugin source files. Only in standalone config files like ecs.php.
• @author goes on classes and methods only — never on properties. (Craft core puts @author at the class level only; placing it on methods too is this project's house convention, not core style.)
• Don't use string|null — use ?string (short nullable notation).
• Forget parent::defineRules() and you lose all inherited validation.
• Using [$this, '_validateFoo'] callable arrays or inline closures in defineRules() — Craft core uses string method names: [['attr'], 'validateAttr']. The validator method is public, no underscore — Yii invokes it by name.
• DateTimeHelper in elements/queries, Carbon in services — never mix in the same class.
• Parsing a raw DB datetime with strtotime() or new DateTime() — those columns are naive UTC strings and the process timezone is system.timeZone, so the result is off by the full offset on any non-UTC install. Parse with an explicit UTC zone. See Date Handling below.
• Missing @throws chains — document exceptions from called methods too, not just your own throws.
• Using magic property access ($plugin->settings, $app->view) instead of explicit getters ($plugin->getSettings(), $app->getView()) — PHPStan can't resolve __get() calls, so magic access passes at runtime but fails static analysis. Always use explicit getters for Yii2 components and Craft plugin properties.
• Calling Craft-specific methods directly on Craft::$app (Craft::$app->getConfig()) — PHPStan can't resolve them because the static type is Yii's base union. Narrow with a typed local: /** @var \craft\web\Application $app */ $app = Craft::$app;. Don't use @phpstan-ignore-line.
• Duplicating contract constants as private const across multiple classes with "keep in lockstep" comments — PHPStan can't detect drift. Declare public const on the owning service, reference as OwnerService::CONSTANT_NAME everywhere else. This applies specifically to permission handles: a handle like 'my-plugin:manage-settings' is a contract string referenced from registration (EVENT_REGISTER_PERMISSIONS), the controller gate (requirePermission()), and the nav check (->can()); a bare literal drifts silently and a typo passes for admins (who hold every permission) while denying everyone else. Declare it as a public const on the controller that enforces it — SettingsController::PERMISSION_MANAGE_SETTINGS — and reference the const everywhere. (Craft core uses bare literals here; the const is a deliberately stricter house rule. See the craftcms skill's permissions.md.)
• Writing the same authorization check separately in a CP controller, a console command, and a GraphQL resolver — they drift, and the surface that drifts is the one nobody tests. One shared gate method called by every surface, with a test per surface. Console is not exempt (a documented cron path with no permission check is an unauthenticated capability), and GraphQL schema scope is not the plugin's permission matrix. See references/authorization-parity.md.
• Assuming Craft prevents self-approval / self-review — it has no such concept, and peer permissions are the opposite axis. Write the guard into the shared gate, orthogonal to role checks, with an explicit bypass permission. See references/authorization-parity.md.
• Shipping ../* path repositories in a plugin's composer.json — resolution works only on the author's disk. Unpublished sibling deps get a vcs entry; Packagist deps need nothing; composer.lock stays gitignored for plugins. Prove it with composer config --global repositories (expect empty) then a no-lock composer update --dry-run. See references/tooling.md (Composer Hygiene).
• Using Db::parseParam() for a literal comparison — a leading or trailing * becomes a SQL LIKE wildcard, so a uniqueness check on a stored pattern silently becomes a prefix match. Use a raw andWhere(['col' => $value]). See the craftcms skill's architecture.md.
• Registering EVENT_REGISTER_ELEMENT_TYPES / EVENT_REGISTER_FIELD_TYPES inside a getIsCpRequest() (or other request-context) branch in init() — component-type registration must run in every context (CP, console, site) or the type disappears from getAllElementTypes() in console/queue requests, and Gc::hardDeleteElements() silently stops purging its trashed rows. Register unconditionally; only CP-rendering/routing (URL rules, asset bundles, nav) may be gated. See the craftcms skill's events.md → "Registration scope".