Craftcms

Craft CMS 5 — Extending (Plugins & Modules)

Reference for extending Craft CMS 5 through plugins and modules. Covers everything from elements and services to controllers, migrations, fields, and events.

This skill is scoped to extending Craft — building plugins, modules, custom element types, field types, and backend integrations. For site/platform development (content modeling, sections, entry types, Twig templating, plugin selection), see the craft-site skill.

Companion Skills — Always Load Together

When this skill triggers, also load:

• craft-php-guidelines — PHPDoc standards, section headers, naming conventions, class organization, ECS/PHPStan, verification checklist. Required for any PHP code.
• ddev — All commands run through DDEV. Required for running ECS, PHPStan, scaffolding, and tests.
• craft-garnish — When working on CP JavaScript, asset bundles, or interactive CP components. Covers Garnish's class system, UI widgets (Modal, HUD, DisclosureMenu, Select), drag system, and the Craft.* JS class pattern.

Documentation

• Extend guide: https://craftcms.com/docs/5.x/extend/
• Class reference: https://docs.craftcms.com/api/v5/
• Generator: https://craftcms.com/docs/5.x/extend/generator.html

Use WebFetch on specific doc pages when a reference file doesn't cover enough detail.

Common Pitfalls (Cross-Cutting)

• Always use addSelect() in beforePrepare() — it's the Craft convention and safely additive when multiple extensions contribute columns.
• Queue workers run in primary site context — use ->site('*') for cross-site queries.
• Including id in getConfig() — project config uses UIDs, never database IDs.
• Business logic in models or controllers — services are where logic belongs.
• Modules need manual template root, translation, and controllerNamespace registration — nothing is automatic.
• DateTimeHelper in elements/queries, Carbon in services — never mix in the same class.
• Hardcoding /admin in CP URLs — cpTrigger is configurable. Use UrlHelper::cpUrl() in PHP, cpUrl() in Twig.
• Passing $request->getBodyParams() directly to savePluginSettings() on split-settings pages — only submitted keys persist, other settings are silently dropped. Load the full settings model first, update properties, then save.

Reference Files

Read the relevant reference file(s) for your task. Multiple files often apply together.

Task examples:

• "Build a custom element type" → read elements.md + element-index.md + fields.md + migrations.md + cp.md
• "Add a webhook endpoint" → read controllers.md + events.md
• "Create a queue job that syncs elements" → read queue-jobs.md + elements.md + debugging.md
• "Add a settings page with form fields" → read controllers.md + cp.md + architecture.md
• "Register a custom field type" → read fields.md + events.md
• "Fix PHPStan errors" → read quality.md
• "Add a dashboard widget" → read cp.md (Dashboard Widgets) + events.md (Widget Types section)
• "Expose template variables for plugin users" → read events.md (Twig Extensions section)
• "Attach custom methods to entries" → read events.md (Behaviors section)
• "Build a CP utility page" → read events.md (Utilities section) + cp.md
• "Set up Vite for a plugin's CP assets" → read plugin-vite.md + load craft-garnish skill
• "Add drag-to-reorder or interactive JS to a CP page" → load craft-garnish skill
• "Write CP JavaScript for a custom field type" → read fields.md + load craft-garnish skill
• "Build a headless Craft API" → read graphql.md + load craft-site skill for headless.md
• "Configure preview for a Next.js front-end" → load craft-site skill for headless.md
• "Set up Pest tests for a plugin" → read testing.md
• "Write a test for a controller action" → read testing.md
• "Configure Redis for caching and sessions" → read config-app.md
• "Set up environment variables for production" → read config-bootstrap.md
• "Find a GeneralConfig setting" → read config-general.md
• "Read a config value in plugin code (App::env, parseEnv, GeneralConfig)" → read config-bootstrap.md + config-general.md
• "Check if allowAdminChanges is enabled in plugin code" → read config-general.md + cp.md (Read-Only Mode)
• "Resolve env vars in plugin settings ($MYAPIKEY)" → read config-bootstrap.md (App::parseEnv)
• "Understand CRAFT_* env var conventions" → read config-bootstrap.md
• "Configure mail transport / SMTP" → read config-app.md
• "Set up custom URL routes" → read config-bootstrap.md
• "Configure search to find short words" → read config-app.md
• "Set up GraphQL tokens and schemas" → read graphql.md + config-general.md
• "Set up caching for a high-traffic site" → read caching.md
• "Register custom permissions for my plugin" → read permissions.md
• "Check user permissions in templates" → read permissions.md
• "Set up plugin editions / feature gating" → read architecture.md (Plugin Editions section)
• "Upgrade a plugin from Craft 4 to 5" → read quality.md (Rector section)
• "Set up CI for a Craft plugin" → read quality.md (CI/CD Integration section)
• "Create sections or fields in a migration" → read migrations.md (Content Migrations section)
• "Set up database read replicas" → read config-app.md (Database Replicas section)
• "Register a module in app.php" → read config-app.md (Module Registration section)
• "Create a custom validator" → read architecture.md (Custom Validators section)
• "Create a custom filesystem type" → read events.md (Filesystem Types section)
• "Build a custom condition rule for an element index" → read cp.md (Condition Builders section)
• "Build a tri-state on/inherit/off control" → read cp.md (CP UI Patterns — Tri-State Inheritance)
• "Add tabbed settings page to a plugin" → read cp.md (Tabbed Settings Pages)
• "Show an 'overrides global' warning on a field" → read cp.md (CP UI Patterns — Field Warning Parameter)
• "What CSS variables does Craft CP use?" → read cp.md (CP UI Patterns — Craft CSS Custom Properties)
• "Set up pre-commit hooks for code quality" → read quality.md (Pre-Commit Hooks section)
• "Restrict element access by user group" → read element-authorization.md + permissions.md
• "Scope CP element index by permission" → read element-authorization.md (Layer 3: Query Scoping)
• "Add authorization events to a custom element" → read element-authorization.md + elements.md
• "Build defense-in-depth for a security plugin" → read element-authorization.md (Defense Patterns)
• "Force-logout a user from all devices" → read sessions-and-auth.md (Plugin Patterns)
• "Understand how Craft sessions work" → read sessions-and-auth.md
• "Implement password reset required" → read sessions-and-auth.md (passwordResetRequired Gap)
• "Add a column to the Users element index" → read element-index.md (Extending Element Indexes via Events)
• "Add a bulk action to an element index" → read element-index.md (Adding a custom bulk action)
• "Add a custom sidebar source to the element index" → read element-index.md (Adding a sidebar source)
• "Build a custom field type" → read field-types-custom.md + fields.md
• "Build a relation field type" → read field-types-custom.md (Relation Fields)
• "Add a condition rule to the entry index" → read conditions.md + element-index.md
• "Build a custom condition rule" → read conditions.md
• "Send email from a plugin" → read email.md
• "Register a custom system message" → read email.md (Registering Custom System Messages)
• "Configure SMTP transport" → read config-app.md + email.md
• "Deploy Craft CMS to production" → read deployment.md
• "Set up CI/CD for a Craft project" → read deployment.md (CI/CD Patterns)
• "Zero-downtime deploy" → read deployment.md (Zero-Downtime)
• "Roll back a failed deploy" → read deployment.md (Rollback Strategies)
• "Work with drafts and revisions" → read drafts-revisions.md
• "Create a draft programmatically" → read drafts-revisions.md (Creating Drafts)
• "Skip side effects for drafts in afterSave" → read drafts-revisions.md (Plugin Considerations)
• "Add generated fields to a custom element" → read elements.md (Generated Fields)
• "Customize how my element appears as a chip or card" → read element-index.md (Element Display Modes)
• "Make plugin settings read-only when allowAdminChanges is off" → read cp.md (Read-Only Mode)

| Task | Read | |------|------| | Element core: lifecycle, queries, status, authorization, drafts, revisions, propagation, field layouts, events | references/elements.md | | Element index: sources, table/card attributes, sort, conditions, actions, exporters, sidebar, metadata, extending via events (columns, sources, bulk actions, condition rules, sort) | references/element-index.md | | Services, models, records, project config, MemoizableArray, events, API clients, custom validators | references/architecture.md | | Controllers: CP CRUD, webhooks, API endpoints, action routing, authorization | references/controllers.md | | CP templates, form macros, admin changes, VueAdminTable, asset bundles, CP layout, permissions. For CP JavaScript interactions, also load craft-garnish skill. | references/cp.md | | Database migrations, Install.php, foreign keys, indexes, idempotency, deployment | references/migrations.md | | Queue jobs, BaseJob, TTR, retry, progress, batch jobs, site context | references/queue-jobs.md | | Console commands, arguments, options, progress bars, output helpers, resave actions | references/console-commands.md | | Debugging, performance, query strategy, profiling, Xdebug, caching, logging | references/debugging.md | | PHPStan, ECS, code review checklist | references/quality.md | | Testing: Pest setup, element factories, HTTP/queue/DB assertions, mocking, multi-site, console, events | references/testing.md | | Field types, native fields, BaseNativeField, field layout elements, FieldLayoutBehavior | references/fields.md | | Events: registration, lifecycle, naming conventions, custom events, behaviors, Twig extensions, utilities, widgets, filesystems, discovering events | references/events.md | | GraphQL types, queries, mutations, directives, schema components, resolvers | references/graphql.md | | Plugin Vite: VitePluginService, CP asset bundles, HMR, TypeScript, Vue in CP | references/plugin-vite.md | | Headless & hybrid: headlessMode, GraphQL API, CORS, preview tokens, front-end frameworks | craft-site skill references/headless.md | | GeneralConfig (system, routing, security, users, sessions, search, assets, images) | references/config-general.md | | GeneralConfig (content, templates, performance, GC, localization, headless, GraphQL, accessibility, preview, dev, dangerous interactions) | references/config-general-extended.md | | App config: cache, session, queue, mutex, mailer/SMTP, search, logging, CORS, DB replicas, web/console split | references/config-app.md | | Config bootstrap: env vars, aliases, priority order, fluent API, custom.php, db.php, routes.php, htmlpurifier | references/config-bootstrap.md | | Caching: template cache tag, data cache, static caching (Blitz), CDN, layered strategy, invalidation | references/caching.md | | Permissions: built-in handles, user groups, custom registration, Twig/PHP checking, authorization events, strategies | references/permissions.md | | Element authorization: four-layer defense model, authorization events, can*() methods, EVENTBEFOREPREPARE query scoping, controller enforcement | references/element-authorization.md | | Sessions & auth internals: dual-layer session model, auth tokens, session invalidation, passwordResetRequired, elevated sessions, plugin patterns | references/sessions-and-auth.md | | Custom field types: build pattern, value lifecycle, settings, input HTML, validation, search, GraphQL, relation fields | references/field-types-custom.md | | Conditions framework: BaseCondition, ElementCondition, custom condition rules, registering rules, condition builder UI | references/conditions.md | | Email system: system messages, custom messages, programmatic sending, templates, events, testing | references/email.md | | Deployment: standard pipeline, project config deploy, zero-downtime, CI/CD, rollback, environment management | references/deployment.md | | Drafts & revisions: draft types, provisional drafts, autosave, applying, merge, revisions, plugin considerations | references/drafts-revisions.md |

Plugin vs Module Differences

Plugins and modules share the same architecture patterns. The differences are in bootstrapping and registration:

| Feature | Plugin | Module | |---------|--------|--------| | CP template root | Automatic (by handle) | Manual via EVENT_REGISTER_CP_TEMPLATE_ROOTS | | Site template root | Manual via event | Same — manual for both | | Translation category | Automatic (by handle) | Manual PhpMessageSource in init() | | Settings model | Built-in createSettingsModel() | Env vars, config files, or private plugin (_ prefix) | | Install migration | migrations/Install.php | Content migrations only | | Console commands | Automatic controllerNamespace | Must set before parent::init(), must be bootstrapped | | CP nav section | $hasCpSection = true | EVENT_REGISTER_CP_NAV_ITEMS | | Project config | Settings auto-tracked | Manual ProjectConfig::set() only | | Namespace alias | Automatic via Composer | Must call Craft::setAlias() |

Module Template Root Registration

use craft\events\RegisterTemplateRootsEvent;
use craft\web\View;

Event::on(View::class, View::EVENT_REGISTER_CP_TEMPLATE_ROOTS,
    function(RegisterTemplateRootsEvent $event) {
        $event->roots['my-module'] = __DIR__ . '/templates';
    }
);

Module Translation Registration

Craft::$app->i18n->translations['my-module'] = [
    'class' => \craft\i18n\PhpMessageSource::class,
    'sourceLanguage' => 'en',
    'basePath' => __DIR__ . '/translations',
    'allowOverrides' => true,
];

Module Console Command Registration

public function init()
{
    Craft::setAlias('@mymodule', __DIR__);

    if (Craft::$app->getRequest()->getIsConsoleRequest()) {
        $this->controllerNamespace = 'modules\\mymodule\\console\\controllers';
    } else {
        $this->controllerNamespace = 'modules\\mymodule\\controllers';
    }

    parent::init(); // MUST come after setting controllerNamespace
}

The module must be bootstrapped in config/app.php for console commands to be discoverable.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sublimate-toe9304
• Source: sublimate-toe9304/craftcms-claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.