michtio/craftcms-claude-skills / skills/craft-php-guidelines
craft-php-guidelines
VerifiedCraft 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 18.3 KB |
| references/authorization-parity.md | markdown | 11.4 KB |
| references/class-organization.md | markdown | 7.4 KB |
| references/naming-conventions.md | markdown | 3.4 KB |
| references/phpdoc-standards.md | markdown | 2.4 KB |
| references/templates-and-patterns.md | markdown | 4.6 KB |
| references/tooling.md | markdown | 7.9 KB |
references/phpdoc-standards.md
View on GitHub# PHPDoc Standards
PHPDocs on every class, method, and property. No exceptions.
## Class Docblocks
```php
/**
* The Items service provides APIs for managing plugin entities.
*
* An instance of the service is available via `MyPlugin::$plugin->getItems()`.
*
* @property-read SomeType $thing
*
* @author <Author Name>
* @since 5.0.0
*/
```
## Method Docblocks
```php
/**
* Returns the item matching the given ID.
*
* @param int $id the item ID
* @return Item|null
* @throws InvalidConfigException if the service is not initialized
*
* @author <Author Name>
* @since 5.0.0
*/
```
- Full sentence description, proper capitalization and punctuation.
- `@param` / `@return`: no capitalization, no ending punctuation. (The official Craft guideline says this, but core itself routinely capitalizes `@param`/`@return` descriptions; this project follows the official guideline as its house rule — lowercase, unpunctuated.)
- `@throws`: document every thrown exception, **including uncaught exceptions from called methods**.
- `@author` and `@since` at the bottom, after a blank line. (Craft *core* puts `@author` at the class level only — not on methods. Repeating it on each method is this project's house convention, not core style.)
## Property Docblocks
`@author` is NOT used on properties — only on classes and methods. Properties use `@var` and `@since`:
```php
/**
* @var MemoizableArray<Item>|null
* @see _items()
*/
private ?MemoizableArray $_items = null;
/**
* @var int|null The parent entity this item belongs to.
*
* @since 5.0.0
*/
public ?int $parentId = null;
```
## Constant Docblocks
Follow Craft core pattern — `@event` for event constants, `@since` always:
```php
/**
* @event ItemEvent The event that is triggered before an item is saved.
* @since 5.0.0
*/
public const EVENT_BEFORE_SAVE_ITEM = 'beforeSaveItem';
```
## `@inheritdoc` Rule
Only when the parent class or interface has a meaningful doc comment. Otherwise write a full docblock.
## Type References
- Public service methods: reference interfaces (`ElementInterface`, not `Element`).
- Inline `@var` tags: reference implementations.
- Use `bool`/`int`, not `boolean`/`integer`.
- Use `static` as return type for chainable methods.
- Use typed arrays in docblocks: `ElementInterface[]`.
- Always import classnames in docblocks — never fully qualified names.
- For iterables, specify key and value types: `@param array<int, MyObject> $items`.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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 implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |