Skip to content

michtio/craftcms-claude-skills / skills/craft-php-guidelines

craft-php-guidelines

Verified

Craft CMS 5 PHP coding standards and conventions. ALWAYS load when writing, editing, reviewing, or discussing any PHP in a Craft plugin or module — even small edits. Also when running ECS, PHPStan, or scaffolding with ddev craft make. Covers: PHPDoc blocks (@author, @since, @throws chains), section headers (=========), class organization, naming conventions (services, queue jobs, records, events, enums), defineRules() and validation, beforePrepare() and addSelect(), MemoizableArray, DateTimeHelper vs Carbon, strict_types/declare(strict_types=1), short nullable notation (?string), typed properties, void returns, control flow (early returns, match over switch), CP Twig template conventions, form macros, translations (Craft::t), ECS/PHPStan config, scaffolding commands, and the verification checklist.

references/naming-conventions.md

View on GitHub
# Naming Conventions

## General Naming

| Thing | Convention | Example |
|-------|-----------|---------|
| Namespace | All lowercase | `vendor\pluginhandle` |
| Class | StudlyCase | `MyEntity` |
| Method | camelCase | `getEntityById()` |
| Private method | Underscore prefix | `_registerCpUrlRules()` |
| Yii-invoked method | Public, **no** underscore | `validateSiteSettings()` — see exception below |
| Property | camelCase | `$entityId` |
| Private property | Underscore prefix | `$_items` |
| Constant | UPPER_SNAKE_CASE | `EVENT_BEFORE_SAVE` |
| Table constant | Craft format | `{{%pluginhandle_items}}` |
| Event constant | Before/after pattern | `EVENT_BEFORE_SAVE_ITEM` |
| Config path | Dot-separated | `pluginhandle.items` |
| Enum | StudlyCase | `BulkOperationStatus` |
| Enum case | PascalCase | `Processing` |

## File Structure Naming

| Type | Convention | Example |
|------|-----------|---------|
| Plugin entry | Named after the plugin | `Cockpit.php`, `Typesense.php`, `PasswordPolicy.php` |
| Element | Singular | `Entry.php`, `Asset.php`, `User.php` |
| Element query | Singular + Query | `EntryQuery.php`, `AssetQuery.php` |
| Element action | Action verb, no suffix | `Delete.php`, `Duplicate.php`, `SetStatus.php` |
| Element condition | Domain + ConditionRule | `SectionConditionRule.php`, `TypeConditionRule.php` |
| Element exporter | Descriptive, no suffix | `Expanded.php`, `Raw.php` |
| Model | Singular | `Section.php`, `Volume.php`, `EntryType.php` |
| Record | Same name as model | `Section.php`, `Volume.php` (namespace distinguishes) |
| Service (resource) | Plural | `Entries.php`, `Volumes.php`, `Users.php` |
| Service (utility) | Domain noun | `Auth.php`, `Search.php`, `Gc.php` |
| Controller (resource) | Plural + Controller | `EntriesController.php`, `SectionsController.php` |
| Controller (action) | Domain + Controller | `AppController.php`, `AuthController.php` |
| Console controller | Domain + Controller | `SyncController.php`, `ResaveController.php` |
| Queue job | Action verb phrase, no suffix | `ResaveElements.php`, `UpdateSearchIndex.php` |
| Event | Domain + Event | `SectionEvent.php`, `VolumeEvent.php` |
| Register event | Register + Domain + Event | `RegisterUrlRulesEvent.php` |
| Define event | Define + Domain + Event | `DefineHtmlEvent.php`, `DefineRulesEvent.php` |
| Validator | Domain + Validator | `HandleValidator.php`, `UniqueValidator.php` |
| Helper | Domain (suffix optional) | `Db.php`, `Cp.php`, `ArrayHelper.php` |
| Enum | Descriptive name | `PropagationMethod.php`, `CmsEdition.php` |
| Migration | Timestamped | `m240101_000000_add_column.php` |
| Install migration | `Install.php` | `Install.php` |

## Record Aliasing

When importing both model and record in the same file, alias the record:

```php
use vendor\myplugin\models\MyEntity;
use vendor\myplugin\records\MyEntity as MyEntityRecord;
```

## Visibility Exception: Yii-Invoked Methods

Methods that Yii invokes by name from outside the class are **public with no underscore prefix**, even if they feel "internal." Yii resolves these by string name on the object — private or underscore-prefixed methods won't be found.

This applies to:
- **Inline validator methods** referenced from `defineRules()` — `'validateSiteSettings'`
- **`when` callables** in validator rules — `[$this, 'hasMaxRows']`
- **Event handler methods** referenced as strings in config
- **Behavior callables** referenced by name

General principle: any method Yii invokes by name is part of the public API surface.
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall