Core Laravel Package

Getting Started

Bolt is a Symfony-based CMS, not a Laravel package — the first real decision is how it sits relative to your Laravel app, because that choice constrains everything after it:

• Headless backend — Bolt owns content modelling and the editing UI; Laravel consumes content over HTTP and renders with Blade/Inertia/Livewire. Best default when you already have a Laravel app.
• Standalone full-stack — Bolt renders everything with Twig on its own vhost/subdomain. Cheapest to run, least code sharing.
• Embedded alongside — same server, separate app, shared auth via reverse proxy or SSO. Only worth it if editors need a single sign-on story.

Minimal steps to a working instance:

1. composer create-project into its own directory (do not drop it into an existing Laravel composer.json — the Symfony/Doctrine dependency tree will fight you).
2. Configure DB and mail in .env, run the schema/migration step once.
3. Open /bolt for the admin UI and confirm the version reads 6.1.9.
4. Publish one throwaway content type with 3–4 fields, create a record in the admin, and read it back from your consumer. That round-trip validates the integration mode before you invest in modelling.

Where to look first, in order:

• config/contenttypes.yaml — this is the schema-as-code of your entire CMS. Everything (admin forms, routing, storage, templates) derives from it. Read it before writing a line of PHP.
• config/taxonomy.yaml — categories/tags/tagsets; set these up early so editors self-serve.
• templates/ — Twig theme files, if you're using the full-stack mode.
• src/ only when you need an extension point; patching core is a tax you'll pay on every frequent patch release.

First use case to validate: one content type, one listing query, one detail query, rendered in your app. If that feels clunky, change the integration mode now — not after 15 content types exist.

Implementation Patterns

Content types are your schema, treat them like migrations. Commit contenttypes.yaml, review changes in PRs, and lint it in CI:

bin/console lint:yaml config
bin/console lint:twig templates
bin/console lint:xliff translations
bin/console doctrine:schema:validate --skip-sync

Mirror the field names into a Laravel-side DTO or cast layer so a renamed field fails a test instead of silently returning null in production.

Model by concern, not by page. article, author, category — never homepage or landing-page-v2. Compose pages in the consumer. This single habit decides whether the CMS is still pleasant at month six.

Wrap Bolt behind one service in Laravel. A BoltContentRepository (or similar) with typed methods per content type, rather than HTTP calls scattered through controllers. Put caching in that layer:

Cache::remember("bolt:article:{$id}:{$locale}", 300, fn () => $this->fetch($id));

Bolt reads are cheap but not free, and almost all your traffic is the same handful of records. Short TTL plus explicit invalidation on publish (webhook or a scheduled warmer) covers it.

Query deliberately. Bolt is Doctrine-backed; use Bolt's own query API rather than hand-rolling DQL. Filter by status and taxonomy at the source, not in PHP after the fact — you'll otherwise ship unpublished drafts to a listing page.

Editorial workflow is a config problem. Statuses, taxonomies and the admin UI's roles/permissions cover most approval flows. If they don't, that's an extension point (custom console command, Twig extension, event listener) — not a fork.

Auth: keep it boring. Don't try to make Bolt read Laravel sessions. Either keep two user tables (usually fine — editors are few) or front /bolt with a reverse proxy that enforces Laravel auth and injects a trusted header.

Deploy as immutable build output. Build admin assets in your pipeline, treat vendor/ and compiled public assets as artifacts, and run the schema/migration step as a distinct one-shot deploy phase — not per web node.

Gotchas and Tips

• 6.1.9 is a dependency-bump release only. Every changelog entry is a Dependabot chore(deps)/chore(deps-dev) bump (axios, undici, ip-address, source-map-js, brace-expansion, compression, proxy-addr, shell-quote). No features, no deprecations, no breaking changes — a normal patch upgrade. But note these are JavaScript dependencies landing in Bolt's admin front end: if you vendor or rebuild compiled assets, rebuild after upgrading or you'll keep shipping the old bundles and wonder why the changelog didn't match your symptoms.
• Version drift is the real risk in the 6.x line. Patches are almost entirely dependency churn, so the meaningful question isn't "what changed in 6.1.9" but "am I still on a supported minor." Pin ^6.1, let patches flow, and read the changelog between minors — that's where behaviour moves.
• Don't translate Laravel idioms. No Eloquent, no service providers, no facades, no Blade in core. Any tutorial showing $model->save() after composer require is about something else entirely.
• Two caches, both surprising. Symfony's PHP cache and whatever HTTP cache sits in front. Edited content type YAML that "didn't apply" is nearly always a stale cache — clear it before debugging anything else. Same for Twig changes in production.
• Debug order for "content isn't showing": YAML syntax (bin/console lint:yaml config) → cache clear → record status/permissions → the query in your consumer. It's the first or second step nine times out of ten.
• Patching core is a maintenance tax. With releases every few weeks, any local core edit must be re-applied constantly. Prefer custom console commands, Twig extensions, and event listeners.
• Bolt's own quality gates are a useful template. vendor/bin/rector process, vendor/bin/ecs check src, vendor/bin/phpstan analyse, composer validate --strict — mirror this discipline in any extension or bridge code you write.
• Upgrade discipline: automate patch upgrades in CI, run a smoke test that does a real content read, keep a rollback tag. If an upgrade is ever not boring, that's a signal to check what else drifted.
• Contribution policy: Bolt does not accept autonomous/AI-generated PRs — a human must be able to explain every change. Relevant if you plan to upstream fixes rather than fork.