Coasterframework Laravel Package

Getting Started

1. Check compatibility first in composer.json before installing. The last release was 2020, so expect Laravel 6–8 era constraints and PHP 7.x/8.0. Do not assume it works on Laravel 10/11 without a fork.
2. Install via Composer:

   composer require web-feet/coasterframework
   

3. Register the service provider if your Laravel version does not auto-discover it. Look in src/ for the main provider, likely CoasterServiceProvider, and any facade aliases.
4. Publish config, migrations, assets, and views:

   php artisan vendor:publish --provider="Coaster\CoasterServiceProvider"
   php artisan migrate
   php artisan storage:link
   

   Inspect the publish tags if the provider uses tagged publishing.
5. Look first at:
   • config/coaster.php for admin prefix, auth guard, theme paths, media disks, and middleware.
   • routes/ for the admin and front-end slug routes.
   • resources/views/ for theme/layout conventions.
   • database/migrations/ for page, block, menu, and media tables.
6. Create an admin user using the package seeder/command or by inserting into the users table with the expected guard/role. Visit the configured admin URL, usually /admin.
7. First use case: create a page in the admin, assign a template/theme, add editable blocks, then visit the page slug on the front end. This validates routing, block rendering, theme resolution, and asset publishing in one pass.

Implementation Patterns

• Theme-first rendering: Treat Coaster as a page/block provider. Put Blade templates under the configured theme path and map page templates to views. Keep package views unpublished unless you need to override admin or front-end partials.
• Block composition: Render page blocks in your layout rather than hard-coding content. For reusable content, create custom block types by extending the package’s base block class, registering the type in config/admin, and providing an edit view plus a front-end Blade partial.
• Slug routing: Let Coaster resolve page slugs, but register its catch-all/front-end route after your application’s explicit routes. This prevents CMS pages from swallowing /api, auth, or custom controller routes.
• Menus and navigation: Use the package menu models/helpers if available, or build a recursive Blade partial from the menu table. Cache the rendered menu and invalidate it when menu items change.
• Admin integration: Configure the admin middleware/guard in config/coaster.php. If you need custom admin screens, prefer package events, config-driven menu entries, or overriding published views rather than editing vendor files.
• Caching: Cache rendered page/block output keyed by page ID and locale. Clear cache on page/block save via model events or the package’s hooks. In development, disable CMS caching so edits appear immediately.
• Existing Laravel app integration: Install Coaster alongside your app, keep CMS routes under a prefix or separate domain, and use your existing auth guard for admin access. Share layouts where practical, but avoid coupling business logic to CMS block views.
• Deployment workflow: Publish assets during deploy, run migrations intentionally, rebuild config/view caches, and ensure the media disk is writable and linked. Pin the package version in composer.lock.

Gotchas and Tips

• Maintenance risk: Last release 2020 and only 30 stars. Audit the code before production use, pin the exact version, and be prepared to fork for Laravel/PHP compatibility.
• GPL-3.0: This is a copyleft license. If you distribute a derivative or SaaS-facing modifications, get legal review. Internal use is usually simpler, but do not ignore the license.
• Laravel version traps: Service provider auto-discovery, facade aliases, middleware APIs, and model factories changed across Laravel versions. Check composer.json constraints and test install in a throwaway app first.
• Route conflicts: The CMS slug route is the most common breakage. Run php artisan route:list and confirm ordering. Prefix the admin route and keep the front-end fallback last.
• Config cache quirks: Changes to config/coaster.php will not apply while config is cached. Run php artisan config:clear and php artisan view:clear when debugging theme or admin behavior.
• Migration conflicts: Review published migrations before running them in an existing database. Table names like pages, blocks, and menus may collide; rename or isolate the CMS database if needed.
• Asset and media issues: Missing admin CSS usually means assets were not published or the public path is wrong. Missing images usually mean storage:link was not run or the configured disk permissions are wrong.
• Auth/guard mismatch: Admin login may assume the default web guard. If you use a custom guard, configure it explicitly and verify middleware on the admin route group.
• Debugging checklist: Check storage/logs/laravel.log, run route:list, inspect published config, verify migrations ran, clear caches, and use tinker to inspect page/block records. Confirm the active theme path matches the configured value.
• Extension points: Prefer custom block types, theme views, config values, middleware, and model events over editing vendor code. Publish only the views/config you actually need to override, and document overrides for future upgrades.