Boom Core Laravel Package

Getting Started

BoomCMS core is the engine, not the whole car. It supplies the page tree, templates/chunks, assets, people/permissions, admin routes, and the CMS UI; you still need a Laravel app, a theme, and a site record. If you are starting from zero, use the boomcms/boom application skeleton and treat boom-core as the dependency you read when you need to change behavior. If you are adding it to an existing Laravel app, expect to wire up more than a typical package.

Minimal path:

composer require boomcms/boom-core

Register BoomCMS\Core\Providers\BoomServiceProvider if your Laravel version does not auto-discover it, then publish and migrate:

php artisan vendor:publish --provider="BoomCMS\Core\Providers\BoomServiceProvider"
php artisan migrate

Look for install/seed commands under src/Console and route definitions in the service provider or package routes/ directory. You need at least one Site, one admin Person, and a template before the CMS is useful. The admin normally lives under /cms; confirm with:

php artisan route:list | grep -i cms

Where to look first, in order:

1. src/BoomCMS/Core/Providers/BoomServiceProvider.php — container bindings, route registration, view namespaces, middleware.
2. config/boomcms.php — disks, templates path, asset config, auth/people settings.
3. database/migrations — the real schema for pages, chunks, URLs, assets, people, groups, roles.
4. src/BoomCMS/Core/Page — Page, Chunk, Template, and URL resolution; this is the heart of day-to-day work.
5. Tests — with thin docs, tests are the most reliable usage reference.

First real use case: make one editable page. Define a template with named chunks, create a page using it, and render the chunks in Blade. A representative template definition looks like this (mirror an existing template in your version rather than inventing the format):

// themes/example/templates/default/template.php
return [
    'name'   => 'Default',
    'chunks' => [
        'title' => ['type' => 'text'],
        'body'  => ['type' => 'richtext'],
        'hero'  => ['type' => 'image'],
    ],
];

<h1>{!! $page->getChunk('title')->render() !!}</h1>
{!! $page->getChunk('body')->render() !!}

Once that renders and the admin editor can save it, you understand the core loop: template → chunks → page → URL.

Implementation Patterns

Template and chunk rendering. Keep presentation in theme Blade files and let BoomCMS own the editable regions. A layout template renders the page shell, and each page template declares the chunks the editor exposes. Render chunks with render() rather than raw getContent() so chunk types (rich text, image, asset) can format themselves consistently. Reuse a shared layout for header/footer/nav so editors do not get a separate chunk set on every template.

Page operations through the service, not raw models. Creating, moving, publishing, and deleting pages has side effects: URL records, cache invalidation, permissions, and events. Use the page repository/service exposed by the BoomCMS facade or container rather than Page::create() directly:

$parent = BoomCMS::getPageByUrl('/');
$page = BoomCMS::pages()->create([
    'title'    => 'About us',
    'parent'   => $parent->getId(),
    'template' => 'default',
]);
$page->publish();

Names differ by major version; confirm signatures in src/BoomCMS/Core/Page. The important pattern is to let the package own state transitions.

Front-end routing. BoomCMS resolves a request path to a page via its URL table. For normal CMS pages, rely on the package route. When you need custom controllers (a contact form, an API-backed listing), resolve the page yourself, pass it into your view, and keep the same 404 semantics for unpublished pages. Do not build a parallel slug system — you will fight the URL table.

Assets. Treat assets as first-class records, not file paths. Upload through the asset manager, attach asset IDs to chunks, and generate display URLs/thumbnails through the asset object. This keeps replacements working: an editor can swap the image behind an existing chunk without touching the template.

Permissions. BoomCMS has its own people/groups/roles model. Check permissions in custom admin controllers and hide admin UI with the same checks. Do not assume Laravel's default User model or guard is the CMS identity — BoomCMS typically uses its own person provider and guard. Mixing the two is a common source of "logged in but forbidden" bugs.

Admin extension. Add custom admin screens as normal Laravel routes wrapped in the package's admin middleware, and register menu entries through config or the package's menu/event hooks. For custom chunk types, implement the chunk class, register it, and provide the editor view/JS the admin expects. Keep custom admin code in your app, not in vendor/.

Import and maintenance scripts. Artisan commands are the safest way to bulk-create pages, migrate content, or sync from a legacy system. Wrap batches in transactions, publish explicitly, and clear page/URL caches at the end. Use php artisan tinker to prototype against real models, then move the code into a command.

Multi-site. Resolve the site before querying pages, and scope every lookup by site. Do not assume a single global page tree; URLs and page IDs are site-scoped in a multi-site install.

Gotchas and Tips

• It is not a drop-in package. Missing published views, assets, or theme files usually shows up as a blank admin or broken editor, not a clear error. Publish everything and verify the public asset symlink.
• Docs are thin; source and tests are canonical. With a small community, expect few Stack Overflow answers. Budget time for reading src/ and tests, and pin a known-good version in composer.json.
• Version drift is real. BoomCMS has changed template/chunk formats and namespaces across majors. Copy patterns from the exact version you installed, and check Laravel version constraints before upgrading either side.
• Renaming chunks orphans data. Chunk content is stored against chunk names. Renaming body to content in a template without migrating the database makes existing content disappear from the editor.
• Draft vs published vs visible. The public route generally serves live pages; preview requires an authenticated admin. If a page 404s on the front end, check publish state and URL records before debugging routing.
• URL uniqueness and moves. Moving a page can change its URL and cascade to children. Do it through the page service so URL records and caches stay consistent; avoid editing the urls table by hand.
• Cache invalidation after programmatic edits. Scripts that write pages directly may leave stale URL/page caches. Clear the package cache (and Laravel cache, if configured) after imports.
• Asset storage quirks. Check the configured disk, storage:link, and thumbnail generation. Large uploads and non-image assets are where configuration mistakes surface first.
• Do not mix auth guards. CMS people are not Laravel users by default. Use the BoomCMS auth/person APIs for admin checks and keep app-level auth separate.
• Watch N+1 queries in navigation. Rendering a full page tree with chunks and URLs can generate many queries. Eager-load children, URLs, and chunks for menus and sitemaps.
• Extension points: service container bindings, chunk type registration, admin menu hooks, and events around page publish/move are the clean seams. Prefer them over editing vendor files, which you will lose on the next composer update.
• Back up before upgrades. This is a content-bearing CMS with migrations across several tables; a database dump is cheaper than reconstructing a page tree.