# Content-modeling starter — Craft 5 (section + entry type + Matrix-as-entries)

A known-good shape for modeling a "flexible content page" in Craft 5. Adapt the handles.
Craft 5 stores this in **Project Config** (`config/project/*.yaml`) — build it in the
Control Panel, then commit the generated YAML. This file documents the *intended shape*;
it is not itself applied.

## Target structure

```
Section: "Pages"  (type: Structure — nestable, ordered)
└── Entry Type: "page"
    ├── Field: title            (built-in)
    ├── Field: heading          (Plain Text, global, reusable)
    ├── Field: seoDescription   (Plain Text)
    └── Field: body             (Matrix — Craft 5: stores NESTED ENTRIES)
        ├── Entry Type: "richText"   → field: text   (CKEditor)
        ├── Entry Type: "imageBlock" → field: image  (Assets, limit 1)
        └── Entry Type: "callout"    → field: body   (Plain Text), style (Dropdown)
```

Key Craft 5 facts baked into this shape:

- **Matrix `body` holds entries, not "blocks".** Each nested entry has an **entry type**
  (`richText`, `imageBlock`, `callout`). Branch on `block.type.handle` in Twig.
- **Fields are global.** `heading`, `text`, `image` etc. are defined once and reused across
  any field layout. Reuse the same `text` field in multiple entry types rather than cloning.
- An entry type can be **shared across sections** with a per-section alias (name/handle
  override) if you want the same shape exposed in, say, both "Pages" and "Landing Pages".

## Rendering it (template `_layouts/page.twig` + section template)

```twig
{% set page = craft.entries().section('pages').slug(craft.app.request.segment(1)).with(['body']).one() %}
{% if not page %}{% exit 404 %}{% endif %}

<h1>{{ page.heading ?: page.title }}</h1>

{% for block in page.body.all() %}
  {% switch block.type.handle %}
    {% case 'richText' %}
      <div class="prose">{{ block.text }}</div>
    {% case 'imageBlock' %}
      {% set img = block.image.one() %}
      {% if img %}<figure><img src="{{ img.url }}" alt="{{ img.alt }}"></figure>{% endif %}
    {% case 'callout' %}
      <aside class="callout callout--{{ block.style.value }}">{{ block.body }}</aside>
  {% endswitch %}
{% endfor %}
```

## Project Config notes

- After creating the above in the CP, the schema lands in `config/project/` as YAML.
  Commit it. On deploy, `php craft up` applies it.
- Don't hand-edit Project Config YAML for structural changes — make them in the CP and let
  Craft serialize, to keep UIDs consistent.
- Environment-specific values (asset base URLs, API keys) belong in `.env` /
  `config/general.php`, never in Project Config.

# GraphQL, Headless & Plugin Development (Craft 5)

Load this for decoupled/headless setups or when building a plugin/module.

## GraphQL / headless

Craft ships a first-party GraphQL API. Flow:

1. **Define a schema** in the Control Panel (GraphQL → Schemas). Scope it to the sections, entry types, asset volumes, etc. the frontend may read.
2. **Generate a token** per schema. The **public schema** serves anonymous requests; private schemas require a Bearer token.
3. **Endpoint**: `/api` by default (configurable). POST GraphQL queries; auth via `Authorization: Bearer <token>`.
4. **CORS**: set allowed origins for the headless frontend (Next.js/Nuxt/Astro).

Example query against entries (note the Craft 5 entry/entry-type model):

```graphql
query Posts {
  entries(section: "blog", limit: 10, orderBy: "postDate DESC") {
    title
    slug
    ... on blog_article_Entry {
      postDate
      featuredImage { url }
      author { fullName }
    }
  }
}
```

The fragment type name follows `{section}_{entryType}_Entry`. Nested Matrix entries resolve as their own entry types under the Matrix field.

### When NOT to use GraphQL

- Small number of fixed endpoints → the **Element API** plugin (custom JSON routes) is simpler.
- Server-rendered Twig site → no API layer needed at all.

## Plugin vs module

| Build a… | When |
|----------|------|
| **Module** | Project-specific code, no distribution (`modules/` in the app) |
| **Plugin** | Reusable/distributable via the Plugin Store (Composer package) |

Both extend Craft via Yii 2 components: services, controllers, element types, field types, widgets, behaviors, events.

## Plugin anatomy

```
my-plugin/
├── composer.json          # type: craft-plugin, autoload PSR-4
├── src/
│   ├── Plugin.php         # init(), registers services & event handlers
│   ├── services/          # business logic (injectable)
│   ├── controllers/       # CP + site request handlers
│   ├── elements/          # custom element types
│   ├── fields/            # custom field types
│   └── migrations/        # install + content migrations
└── README.md
```

Key registration patterns in `Plugin::init()`:

```php
// Register a service
$this->setComponents(['myService' => MyService::class]);

// Hook an event
Event::on(
    Entries::class,
    Entries::EVENT_AFTER_SAVE_ENTRY,
    function (EntryEvent $e) { /* ... */ }
);

// Register a Twig extension
Craft::$app->view->registerTwigExtension(new MyTwigExtension());
```

Follow the official [coding guidelines](https://craftcms.com/docs/5.x/extend/coding-guidelines.html) — namespacing, service-layer separation, and event-driven extension are expected idioms.

## Migrations

| Migration kind | Purpose |
|----------------|---------|
| **Install migration** | Schema a plugin needs on install (`migrations/Install.php`) |
| **Plugin migration** | Schema changes between plugin versions |
| **Content migration** | Project data transformations (`php craft migrate/create`) — version-controlled, run via `php craft up` |

Always test migrations on a staging clone before production.

## Integration points

| Concern | Common choices |
|---------|----------------|
| Frontend frameworks | Next.js, Nuxt, Astro, Gatsby via GraphQL / Element API |
| Hosting | Servd, Fortrabbit, Laravel Forge; DDEV for local |
| Assets | AWS S3, Google Cloud Storage, Imgix transforms |
| Search | Algolia, Elasticsearch via plugins |
| Commerce | Craft Commerce |
| Caching | Blitz (static pages), Redis, Cloudflare |

# Twig & Element Queries — deep dive (Craft 5)

Load this when writing non-trivial templates, debugging N+1, or building pagination.

## Element query parameter catalog

Every element type (entries, assets, users, categories, tags) shares a query builder. Common parameters for `craft.entries()`:

| Parameter | Purpose | Example |
|-----------|---------|---------|
| `.section()` | One or more section handles | `.section(['blog','news'])` |
| `.type()` | Entry type handle | `.type('article')` |
| `.id()` | Specific element id(s) | `.id(42)` |
| `.slug()` | By slug | `.slug('about')` |
| `.status()` | `live`, `pending`, `expired`, `disabled` | `.status(['live','expired'])` |
| `.orderBy()` | Sort | `.orderBy('postDate DESC')` |
| `.limit()` / `.offset()` | Slice | `.limit(10).offset(20)` |
| `.search()` | Full-text via search index | `.search('keyword')` |
| `.relatedTo()` | Relationship queries | `.relatedTo(category)` |
| `.with()` | Eager-load relations | `.with(['author','image'])` |
| `.site()` | Target a specific site (multi-site) | `.site('en')` |
| `.unique()` | Dedupe across sites | `.unique()` |

Terminators: `.all()`, `.one()`, `.count()`, `.exists()`, `.ids()`, `.nth(n)`, `.collect()` (returns a Collection).

## Eager loading (kill N+1)

The single most common Craft performance bug is querying relations inside a loop. Always eager-load:

```twig
{# BAD — one query per entry for author #}
{% for entry in craft.entries().section('blog').all() %}
  {{ entry.author.one().fullName }}
{% endfor %}

{# GOOD — eager-load up front #}
{% set posts = craft.entries().section('blog').with(['author']).all() %}
{% for entry in posts %}
  {{ entry.author.fullName }}
{% endfor %}
```

Nested paths work: `.with(['author.userPhoto', 'categories', 'body'])`.

### Eager-loading nested Matrix entries (Craft 5)

Matrix content is now nested *entries*. Eager-load the Matrix field, then branch on `block.type.handle`:

```twig
{% set page = craft.entries().section('pages').slug(slug).with(['body']).one() %}
{% for block in page.body.all() %}
  {% switch block.type.handle %}
    {% case 'richText' %}
      {{ block.text }}
    {% case 'imageBlock' %}
      {% set img = block.image.one() %}
      {% if img %}<img src="{{ img.url }}" alt="{{ img.alt }}">{% endif %}
    {% case 'callout' %}
      <aside>{{ block.body }}</aside>
  {% endswitch %}
{% endfor %}
```

To eager-load relations *inside* nested entries, use a nested path through the Matrix handle (e.g. `.with(['body.image'])`).

## Pagination

```twig
{% set query = craft.entries().section('blog').orderBy('postDate DESC') %}
{% paginate query.limit(12) as pageInfo, entries %}

{% for entry in entries %}
  {{ entry.title }}
{% endfor %}

{% if pageInfo.prevUrl %}<a href="{{ pageInfo.prevUrl }}">Previous</a>{% endif %}
{% if pageInfo.nextUrl %}<a href="{{ pageInfo.nextUrl }}">Next</a>{% endif %}
```

`pageInfo` exposes `.currentPage`, `.totalPages`, `.total`, `.first`, `.last`, `.getRangeUrls()`.

## Template organization

| Convention | Detail |
|------------|--------|
| Private templates | Prefix `_` (`_layouts/`, `_partials/`, `_macros/`) so Craft won't route to them directly |
| Layout inheritance | `{% extends '_layouts/base' %}`, fill `{% block %}` regions |
| Includes | `{% include '_partials/card' with { entry } only %}` — `only` isolates scope |
| Macros | `{% macro %}` / `{% import %}` for repeated markup helpers |
| Embeds | `{% embed %}` when you need to override blocks inside an included template |

## Caching

```twig
{% cache %}
  {# expensive, rarely-changing markup #}
{% endcache %}

{% cache unless craft.app.config.general.devMode %}...{% endcache %}
{% cache for 1 week %}...{% endcache %}
{% cache using key entry.id %}...{% endcache %}
```

Rules:
- Cache *after* eager-loading and query optimization, never instead of it.
- `{% cache %}` does not cache the query result tags it wraps if they contain `{% nocache %}` regions.
- For full static-page caching with smart invalidation, reach for **Blitz** rather than hand-rolled `{% cache %}`.

## Multi-site

| Need | Approach |
|------|----------|
| Query a specific site | `.site('handle')` |
| Query all sites | `.site('*')` then `.unique()` to dedupe shared elements |
| Current site in template | `craft.app.sites.currentSite` |
| Localized URLs | `entry.url` resolves per-site; `craft.entries().id(x).site('fr').one().url` for the other locale |

Content can be propagated or per-site editable per field/section setting; design the section's propagation method up front.