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/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`.
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