Layouts Contentful Laravel Package

Getting Started

• Install into a Symfony app, not plain Laravel. composer require netgen/layouts-contentful pulls in netgen/layouts-core and a Contentful delivery SDK. The package ships a Symfony bundle (NetgenLayoutsContentfulBundle), which you register in config/bundles.php alongside the core Layouts bundle(s). If your project is Laravel-first, this integration is not plug-and-play — you'd need the Symfony framework components and an actual Netgen Layouts installation underneath. Treat it as a Symfony bundle you happen to consume from a Laravel-adjacent codebase (e.g., a sub-application), not a Laravel package.
• Configure the Contentful client first. Set space_id, environment (defaults to master in Contentful, but the SDK can quietly 404 if you omit it), and an access_token. Use a delivery token in production and a preview token plus preview: true in staging/editor environments. Keep both in env vars.
• Where to look first in the repo: the bundle's DependencyInjection/Configuration.php (the config tree you'll actually be editing), the collection query handler / block handler services (this is what turns a Layouts block into a Contentful API call), and any ItemView/value-converter classes (this is what maps a Contentful entry to a Twig template). Those three files tell you 80% of what the package does.
• First use case: register a block definition in netgen_layouts config that uses the Contentful collection query type, pointing at one content type (e.g. article). Render that block in a layout, then render each entry with an item view template you supply. Once that loop works end-to-end, the rest of the package is variations on it.

Implementation Patterns

• Block definitions + collection queries. The integration's main job is exposing Contentful content types as queryable collections for Layouts blocks. Define block definitions in netgen_layouts.block_definitions and let the Contentful collection query handler resolve entries at render time. Keep one block definition per content type rather than one generic "Contentful block" — it makes the admin UI understandable and the caching granular.
• Item view mapping per content type. Register view types (in netgen_layouts config or via a design) that map each Contentful content type to a Twig template. This is where you normalize fields, handle missing optional fields, and render assets. Resist the urge to make a single mega-template; one template per content type scales much better when marketing adds fields.
• Explicit field contracts. Contentful is schema-less at the field level from PHP's perspective — entries come back as arrays/Entry objects. Define a small typed DTO or resolver class per content type so templates don't do defensive isset() gymnastics. This also gives you one place to update when a content model changes.
• Locale wiring. If the Layouts site is multilingual, map each site/locale to a Contentful locale code and pass it into the query. The Contentful locale codes are things like en-US, de-DE, and they must match exactly; don't assume en works.
• Preview mode. Wire an environment toggle so editors can flip preview on and see draft/unpublished entries inside Layouts. This is the single feature that makes the integration tolerable for content teams — without it, every change is a publish-and-wait loop.
• Cache tagging + webhooks. Netgen Layouts has its own cache layer. Tag rendered blocks/item views with the Contentful entry IDs (and content type ID) they used, then add a small webhook endpoint that Contentful calls on publish/unpublish/delete and clears the matching tags. This is not provided out of the box — you implement the endpoint and the listener.
• Rich text rendering. Contentful rich text comes back as a JSON document, not HTML. Wire a renderer (the official contentful/rich-text PHP packages or a custom Twig extension) and register it as a Twig function/filter so templates can do {{ entry.richText|contentful_rich_text }}.
• Asset URL helpers. Contentful asset URLs support a transformation query string (?w=&h=&fm=webp&q=80). Add a Twig helper that builds these from an asset + a size preset; don't sprinkle raw images.ctfassets.net URLs across templates.
• Custom collection query handlers. If you need filtering, full-text search, or reference resolution beyond what the built-in handler exposes, subclass/extend it rather than fighting block config. This is the intended extension point.

Gotchas and Tips

• Not a Laravel package. There is no service provider, no facade, no Laravel config publish. Everything is Symfony DI. Budget time for that if your team is Laravel-native. This is the biggest single risk with adoption.
• Tiny project, thin docs. With ~11 stars and 0 dependents, expect to read source rather than find tutorials. Pin the version and be prepared to fork for small fixes; there's no large community to lean on.
• Environment field is easy to forget. Contentful's SDK defaults can silently hit master. If you use separate environments for staging/prod, set environment explicitly in both configs.
• Preview token in prod is a leak. Guard preview: true behind an environment check, and never let a preview token end up in a cached response. Content teams will copy config between environments.
• Reference depth. Contentful's include parameter controls how many levels of linked entries/assets come back hydrated. Anything deeper than the default (usually 1–2) is not resolved — you'll get stub objects. Either set include depth or build a resolver that fetches referenced entries by ID.
• Rate limits & latency. Every block render can be an API call. In practice you must cache aggressively (page/block cache) and only bypass it for preview. Watch preview API quota specifically — it's much tighter than the delivery API.
• Missing fields across locales/content types. Entries legitimately lack fields (unset in one locale, or added to the content model after older entries were created). Templates that assume field existence will 500 on the one entry nobody tested. Null-coalesce everywhere, or normalize in your DTO.
• Cache invalidation is on you. Layouts won't know an entry changed unless you tell it. If you skip the Contentful webhook → cache-clear listener, editors will file "changes aren't showing up" bugs within a week.
• Failure modes are opaque. If Contentful is unreachable or a token is wrong, the collection query will throw deep in the render pipeline — sometimes producing a blank block rather than an obvious error. Wrap the collection query handler in try/catch with a logger call and a fallback empty result, and add a health-check command that hits the Contentful space once on deploy.
• Testing. There's no sandbox mode. Use a separate small Contentful space for integration tests, or mock the SDK client in a Symfony test container. Don't point tests at the production space — webhook storms and rate limits are real.
• Extending: the clean extension points are the collection query handler (for custom filtering), the item view provider (for custom field mapping), and Twig extensions (for rich text/assets). Avoid patching the bundle's services directly in services.yaml — override with a compiler pass or explicit decorator so upgrades stay portable.