/craft-project-setup

Scaffolding

• Entry file and class name match the plugin handle in PascalCase: handle forum → src/Forum.php / class Forum; handle userProfile → src/UserProfile.php / class UserProfile. Never ship src/Plugin.php / class Plugin — the Craft starter defaults to that, but every plugin's main class would then be Plugin, distinguished only by namespace alias (ambiguous in multi-plugin source trees, grep-unfriendly).
• composer.json extra.class must point to the renamed FQN (e.g. "class": "vendor\\handle\\Handle"). Update it whenever the entry class is renamed.
• Always use ddev craft make <type> --with-docblocks to scaffold new components. Never manually create boilerplate that the generator handles.
• After scaffolding, customize: add section headers, @author {{authorName}}, @since version, @throws chains, and project naming conventions.
• Available generators: element-type, service, controller, command, queue-job, model, record, field-type, validator, widget-type, utility, asset-bundle, behavior, twig-extension, element-action, element-condition-rule, element-exporter, gql-directive.
• Plugins with 2+ services use src/services/ServicesTrait.php. Each typed accessor (getX(): X) narrows Yii's Component::get() return (signed ?object) with assert($component instanceof X) so PHPStan level 8 resolves the type. The trait owns the @property X $name tags on its class-level docblock — never duplicate them as @property-read on the main plugin class.
• Event listeners, URL rule registration, and plugin lifecycle overrides (getSettingsResponse(), getReadOnlySettingsResponse(), createSettingsModel()) belong in src/base/PluginTrait.php — never inline in the main plugin class.
• The main plugin class stays a thin shell: property declarations, use ServicesTrait; use PluginTrait;, and an init() that calls parent::init(), sets self::$plugin, registers the namespace alias, and invokes the private _register* methods on the trait. Its class-level docblock describes what the plugin does — never an enumeration of services it registers (the trait owns that map).