0xDarkMatter/craftcms-ops

Craft CMS Operations

Authoritative reference for Craft CMS 5.x development: content modeling, Twig templating, element-query optimization, GraphQL/headless setups, plugin development, and the Craft 4 → 5 migration. Craft is a self-hosted PHP application built on Yii 2, backed by MySQL or PostgreSQL.

Version note (verified against craftcms.com/docs/5.x, 2026-06): Craft 5 is current; Craft 6 exists. The defining Craft 5 change is that Matrix is now an entries-based field — Matrix "blocks" are gone, replaced by nested entries with entry types. Fields are globally reusable across all field layouts. Don't ship Craft 3/4 "Matrix block" guidance.

---

Craft 5 architecture at a glance

| Concept | What it is | Craft 5 change | |---------|-----------|----------------| | Section | Container exposing entry types + URL rules | Three kinds: Single, Channel, Structure | | Entry Type | Atomic unit of content (fields, title, slug) | Now global + reusable across sections, with per-section aliases | | Entry | An instance of an entry type | Can be top-level or nested (inside Matrix/CKEditor) | | Field | Reusable input attached via field layouts | Globally reusable — no per-field-instance duplication | | Matrix field | Repeatable nested content | Now stores entries (entry types), not "blocks". Nesting supported natively | | Project Config | Version-controlled schema (config/project/) | Source of truth for sections/fields/settings |

Section types

| Type | Use for | Has URLs? | Hierarchy? | |------|---------|-----------|-----------| | Single | One-off pages (home, about) | Optional fixed URI | No | | Channel | Streams (blog, news, products) | Yes, per-entry-type URI format | No | | Structure | Nested/ordered content (docs, nav) | Yes | Yes (drag-to-order, levels) |

---

Element queries (the 80/20)

Everything readable in Craft is an element (entries, assets, users, categories, tags). You fetch them with element queries.

{# Channel entries, newest first #}
{% set posts = craft.entries()
  .section('blog')
  .type('article')
  .orderBy('postDate DESC')
  .limit(10)
  .all() %}

{# Eager-load relations to kill N+1 #}
{% set posts = craft.entries()
  .section('blog')
  .with(['author', 'featuredImage', 'categories'])
  .all() %}

{# Single entry by slug #}
{% set page = craft.entries().section('pages').slug('about').one() %}

{# Relations: entries related to a given category #}
{% set related = craft.entries().relatedTo(category).all() %}

| Need | Method | |------|--------| | Filter by section | .section('handle') | | Filter by entry type | .type('handle') | | Eager-load relations | .with(['field', 'field.subfield']) | | Status | .status('live') / .status(['live','expired']) | | One vs many | .one() / .all() / .count() / .exists() | | Pagination | {% paginate query as pageInfo, entries %} | | Eager-load nested Matrix entries | .with(['matrixField']) then loop nested entries |

Eager-loading nested entries (Craft 5): because Matrix content is now entries, eager-load the Matrix field then iterate the nested entries by their entry type:

{% set page = craft.entries().section('pages').with(['body']).one() %}
{% for block in page.body.all() %}
  {% switch block.type.handle %}
    {% case 'text' %}{{ block.richText }}
    {% case 'image' %}{{ block.image.one().url }}
  {% endswitch %}
{% endfor %}

See references/twig-and-queries.md for the full query parameter catalog, pagination, and Twig patterns.

---

Twig conventions

| Pattern | Rule | |---------|------| | Private templates | Prefix with _ (_layouts/, _partials/) so they're not directly routable | | Layout inheritance | {% extends '_layouts/base' %} + {% block content %} | | Reusable markup | {% include '_partials/card' with { entry: entry } %} or {{ include() }} | | Avoid logic in templates | Push business logic to a module/plugin service, not Twig | | Caching | {% cache %} — only after queries are optimized, never to mask N+1 |

---

Headless / GraphQL

Craft ships a GraphQL API for decoupled frontends (Next.js, Nuxt, Astro, etc.).

| Concern | Approach | |---------|----------| | Schema | Define GraphQL schemas + scopes in Control Panel; generate a token per schema | | Auth | Bearer token per schema; public schema for anonymous reads | | Alternative | Element API plugin for custom JSON endpoints when GraphQL is overkill | | CORS | Configure allowed origins for the headless frontend | | Eager loading | GraphQL resolves relations efficiently; still design queries to avoid over-fetching |

See references/graphql-and-plugins.md for schema setup, query shape, and plugin/module development.

---

Performance decision table

| Symptom | Fix | |---------|-----| | Slow listing pages | Eager-load with .with([...]) — the #1 Craft perf bug is N+1 inside loops | | Repeated identical render | {% cache %} tag (after query optimization) | | Whole-site cache needed | Blitz plugin (static page caching, granular invalidation) | | Slow orderBy on custom field | Ensure the underlying column/field is indexed | | Heavy asset transforms | Pre-generate transforms; use Imgix/CDN |

---

Project Config & deployment

• Project Config (config/project/*.yaml) is the version-controlled source of truth for sections, fields, entry types, settings. Commit it.
• Apply on deploy: php craft up (runs migrations + applies project config).
• Environment-specific values go in .env and config/general.php (use App::env() / getenv()).
• Data transformations belong in content migrations, not manual DB edits.

---

Craft 4 → 5 upgrade checklist

| Area | What changed | Action | |------|--------------|--------| | Matrix | Blocks → entries with entry types | Templates iterating .type.handle mostly survive; re-check block-type field handles | | Fields | Now globally reusable | Expect field/entry-type proliferation post-upgrade — consolidate duplicates | | Content storage | Reworked internal storage | Run php craft up; test queries on staging | | PHP/DB | Craft 5 needs PHP 8.2+ | Verify host before upgrading | | Plugins | Many need a Craft 5-compatible release | Audit plugin compatibility first |

Full upgrade guidance: https://craftcms.com/docs/5.x/upgrade.html

---

Common gotchas

| Gotcha | Why | Fix | |--------|-----|-----| | N+1 queries in loops | Element relations lazy-load | Always .with([...]) before iterating | | {% cache %} masking slow queries | Cache hides, doesn't fix | Optimize queries first, cache second | | Business logic in Twig | Hard to test/reuse | Move to a module/plugin service | | Project Config drift in teams | Out-of-band CP edits | Treat config/project/ as source of truth; php craft up on deploy | | Untested migrations to prod | Data loss risk | Test on staging clone first | | Over-using Matrix | Complexity + perf cost | Use simpler structures when nesting isn't needed | | Calling old "Matrix block" APIs | Removed in Craft 5 | Use entry/entry-type APIs |

---

Assets

| File | Use | |------|-----| | assets/entry-type-field-layout.md | Annotated content-modeling starter: section + entry type + field layout + Matrix-as-entries shape, mapped to Project Config |

---

See also

• laravel-ops — shared PHP/Composer/Twig-adjacent tooling, Eloquent patterns for comparison
• sql-ops — index strategy behind slow orderBy/relation queries
• nginx-ops — serving Craft, caching headers, reverse proxy for headless

Key external resources

• Craft CMS 5.x Docs
• Entries reference
• Matrix fields (Craft 5)
• Eager-loading
• GraphQL API
• Upgrading from Craft 4
• Coding guidelines
• Blitz plugin · nystudio107 blog · Craft Stack Exchange