Coastercms Laravel Package

Getting Started

Coaster is a full CMS shipped as a Laravel package — you install it into an existing Laravel app rather than running it as a standalone product. That shape drives everything about how you use it day to day: it owns the database schema, the admin routes, the front-end routing, and the theme layer, and your job is to shape content and templates inside those boundaries.

Minimal path:

composer require web-feet/coastercms
# Laravel 5.5+ auto-discovers the service provider; otherwise add
# CoasterCms\CoasterCmsServiceProvider::class to config/app.php
php artisan vendor:publish --provider="CoasterCms\CoasterCmsServiceProvider"
php artisan migrate
php artisan coaster:install     # seeds admin user, roles, default data

Then configure the essentials in config/coaster.php (or .env): database connection, the admin URL prefix (default /admin — change it before you go live), upload paths/disks, mail settings for form submissions, and the active theme name. Log in at /admin, and the first thing to build is a theme, because pages, templates and blocks all hang off it.

Where to look first:

• config/coaster.php — every behaviour toggle lives here; read it end to end once.
• The coaster:* artisan commands (php artisan list | grep coaster) — install, update, theme and asset tasks.
• The admin UI itself: Themes → Templates → Blocks → Pages is the actual mental model of the CMS.

First use case — a brochure site. Create a theme, add a page template called home with two blocks (hero_image of type image, intro of type wysiwyg), create a page using that template, and render it from the theme's layout:

{{-- resources/views/themes/your-theme/templates/home.blade.php --}}
@extends('themes.your-theme.layouts.app')

@section('content')
    <img src="{{ Coaster::block('hero_image') }}" alt="">
    {!! Coaster::block('intro') !!}
@endsection

That single loop — template → blocks → page content → Blade render — is 80% of what you'll do.

Implementation Patterns

Theme-first development. Themes are self-contained directories (views plus assets) registered with Coaster. Treat the theme as your application's presentation layer and keep business logic out of it. Build layouts with standard Blade (@extends, @section, @include), then expose editable regions as blocks. Override any packaged view by publishing and mirroring the path rather than editing vendor files.

Blocks as the content contract. Define block slots in the template, let editors fill them per page. Prefer many small, single-purpose blocks (cta_text, cta_link, cta_image) over one giant WYSIWYG field — it keeps the admin form usable and the output predictable. Wrap optional blocks so a missing value doesn't break layout:

@if (Coaster::block('cta_text'))
    <a href="{{ Coaster::block('cta_link') }}">{{ Coaster::block('cta_text') }}</a>
@endif

Global settings vs. page content. Site-wide values (logo, phone number, footer copy, analytics ID) belong in Coaster's settings store, read via Coaster::setting('key'), not duplicated across pages. If a value must change per-locale or per-section, it's a block, not a setting.

Menus. Define menus in admin and render with Coaster::menu('main'); loop the returned items to build <ul>/<li> markup with active-state checks. Don't hardcode navigation in Blade — editors will ask for it within a week.

Forms. Use the built-in form builder for contact/enquiry flows: it handles field definitions, validation, submissions storage and email templates. Only drop to a custom controller when you need integrations (CRM push, payment, webhooks) — and then post to the builder's endpoint or replicate its validation rules rather than reinventing storage.

Custom routes and controllers. Coaster registers a catch-all for page URLs, so order matters. Register your custom routes before Coaster's routes load, or exclude their paths in config. Keep custom endpoints under a distinct prefix (/api, /account) to avoid ever colliding with a page slug.

Deployment. Treat content as data, code as code. In CI/CD: composer install, php artisan migrate --force, run the Coaster update command, then clear caches. Never let editors run migrations; never deploy a theme change without the corresponding template/block definitions, or existing pages will render with empty blocks.

Gotchas and Tips

Licence is the big one. Coaster is GPL-3.0. Running it as an internal site or a hosted service is generally fine, but shipping a commercial product that includes or derives from it obliges you to release that product under GPL. If your business model is closed-source distribution, stop here and pick an MIT-licensed alternative — no amount of architectural cleverness fixes this later.

Maintenance risk is real. Last release November 2020, Laravel 8 era, zero dependents. It will not install cleanly on Laravel 9+ without patching, and you are effectively adopting a fork. Budget for pinning laravel/framework to a supported version, and decide up front whether you'll vendor the package into your repo (allowing local patches) or rely on a fork you control. Vendoring is usually the pragmatic choice.

Schema ownership. The package publishes and owns a large set of migrations and models. Avoid adding foreign keys or columns to its tables; put your own data in your own tables and reference Coaster pages by ID or slug. Upgrades get much easier.

Caching bites. Blocks, settings and menus are cached. After changing block definitions, theme files or config, clear the application cache — stale block output after a template edit is the most common "it's broken" false alarm. In development, disable the cache in config/coaster.php so you're not clearing it constantly.

Assets and uploads. Upload paths and disks are configurable but the default writes into public/. On ephemeral filesystems (containers, Heroku-style hosts) those uploads vanish on redeploy — point the disk at S3 or a persistent volume early. Also confirm storage:link and image-thumbnail generation have write access.

Admin URL exposure. Change the admin prefix from /admin and restrict it (IP allowlist, basic auth at the edge, or a middleware) before launch. It's a known, documented CMS path.

Permissions. Coaster ships roles/permissions for admin users; map them to real responsibilities (editor, publisher, developer) rather than handing everyone super-admin. Verify that "publish" and "delete" are separate capabilities if your workflow needs review.

Extension points, in order of preference: theme view overrides → global settings → custom block types → custom routes/controllers → forking the package. The further down that list you go, the more upgrade pain you're buying. And before writing any custom feature, check the admin config and the coaster:* commands — the thing you're about to build is often already a toggle.