Sky Laravel Package

Getting Started

Sky is a content layer, not a CMS platform: it ships Eloquent models for posts, pages, tags, and categories, Filament admin resources to author them, and front-end routing/views to render them. You own the templates, SEO, media, and permissions.

1. Confirm the stack gate before installing. Sky is tightly coupled to Filament. If your app has no Filament panel, stop — the value proposition largely disappears and a plain Laravel content package is the better comparison.

composer require lara-zeus/sky:^5.0.1

Pin ^5.0.1, not ^5.0.0. The 5.0.1 release contains a fix for content retrieval in posts and pages (#268); ^5.0.0 admits the release containing that bug.

2. Publish and migrate.

php artisan vendor:publish --tag=zeus-sky-config
php artisan vendor:publish --tag=zeus-sky-migrations
php artisan vendor:publish --tag=zeus-sky-views   # theme/templates
php artisan migrate

Check the package's own README / src/SkyServiceProvider.php for the exact tag names in v5 — they shifted alongside the v5 docs restructure.

3. Register the panel plugin in your Filament PanelProvider (typically ->plugin(SkyPlugin::make())). This is what surfaces Posts/Pages/Tags/Categories in the admin nav.

4. Where to look first, in order:

• config/zeus-sky.php — model bindings, route/prefix settings, disk, and any toggle for package-provided routes.
• The published migrations — this is your actual schema; read it before writing queries or adding columns.
• src/Models/ — Post, Page, Tag, Category. Confirm field names, scopes, and relationships rather than guessing.
• The published views — your override surface and the thing most likely to go stale.
• The package routes file — you need to know whether Sky registers public routes or expects you to.

5. First use case (the 1–3 day spike): create one Page and one Post inside Filament, hit the public URL, and confirm both render through your layout. That single end-to-end path is the only meaningful proof of fit.

// tests/Feature/ContentSmokeTest.php
public function test_post_and_page_render(): void
{
    $post = Post::factory()->create(['slug' => 'hello']);
    $page = Page::factory()->create(['slug' => 'about']);

    $this->get("/blog/{$post->slug}")->assertOk()->assertSee($post->title);
    $this->get("/{$page->slug}")->assertOk()->assertSee($page->title);
}

Implementation Patterns

Wrap content access behind your own boundary. Do not let Zeus\Sky\Models\Post leak into controllers, Blade templates, and API resources. Introduce a thin repository or query service returning your own DTOs (or at least a narrow interface). This is the cheap insurance policy against the package's small maintainer base and zero dependent packages — swapping the content source later becomes a one-file change instead of a grep-and-pray refactor.

interface ContentRepository
{
    public function publishedPost(string $slug): ?PostData;
    public function latestPosts(int $limit = 10): Collection;
}

Own the routes. Prefer explicit application routes using route–model binding by slug over relying on the package's catch-all. Package catch-alls collide with your existing / {slug} pages and make ordering bugs painful.

Route::get('/blog/{post:slug}', PostController::class)->name('blog.show');
Route::get('/tag/{tag:slug}', TagController::class)->name('tag.show');
Route::get('/{page:slug}', PageController::class)->where('slug', '.*')->name('page.show');

Register catch-all page routes last, after all other route files.

Theme by composing, not editing. Publish the views, then make your layout the outer shell and include Sky's partials inside it. Keep overrides shallow — one layout plus a handful of partials. If you find yourself rewriting the package's views wholesale, you have effectively forked it and every upgrade becomes a manual diff.

{{-- resources/views/blog/show.blade.php --}}
<x-app-layout>
    @include('sky::partials.post-header', ['post' => $post])
    <article class="prose">{!! $post->renderedContent() !!}</article>
    @include('sky::partials.taxonomy', ['post' => $post])
</x-app-layout>

Eager-load taxonomy. Tags and categories are relationships; a post listing without eager loading produces an N+1 per row. Bake it into the repository:

Post::query()->with(['tags', 'categories'])->published()->latest('published_at')->paginate(12);

Model rendered output, not raw markup. Decide once whether the body field holds HTML or Markdown, then normalize in one place — an accessor, a presenter, or a Blade component. Do not scatter {!! !!} across templates; every one is a sanitization decision made accidentally.

Cache the hot path, invalidate with observers. Post/page reads are near-static. Cache rendered fragments keyed by slug + updated_at, and bust on save/delete via model observers. This is where a simple CMS earns its keep under traffic.

Authorization belongs to you. Sky supplies the admin UI; it does not supply your editorial policy. Use Filament policies and panel access gates to control who can author, publish, or edit others' content. If you need approval workflow or scheduling, plan it as a separate backlog item — nothing in v5.0.1 moves in that direction.

Seed realistic content in local dev. Ten posts across three tags and two categories exposes template, pagination, and empty-state bugs far earlier than a single hand-typed record.

Gotchas and Tips

The description and the code may disagree. Public metadata for this package has described a "Spotlight-style command palette," while the release notes and migrations describe a posts/pages CMS. Resolve this by reading composer.json, the service provider, and the migrations in the exact tag you install — never by trusting a summary. This is a documentation-hygiene risk, and it's cheap to close in five minutes.

Patch releases can change rendered output. #268 fixes content retrieval in posts and pages. After upgrading, run php artisan view:clear && php artisan config:clear && php artisan cache:clear, then actually load one real post and one real page. A green CI build will not catch a rendering regression in content you didn't assert on — which is the whole argument for the smoke test above. If you published views before upgrading, diff them against the new package versions.

Published views are a fork you must maintain. Record every published file, and on each upgrade diff it against vendor/lara-zeus/sky/resources/views. Keeping the override list short and documented from day one is the difference between a 20-minute upgrade and a lost afternoon.

Never edit package migrations after running them. Add your own migrations for extra columns (featured image, SEO fields, author). If you need behavioral change on the model, prefer a subclass bound in config or your own service over patching vendor code.

Filament majors are a hard constraint. A Filament major mismatch silently removes the admin UI. Treat a composer solve that bumps Filament as a stop-and-review event, not a routine composer update.

Route collisions and 404s are the most common first-day failure. A package-registered catch-all can shadow your app's routes, or vice versa. Check php artisan route:list before debugging templates.

Escaping and sanitization are not solved for you. Rendering authored HTML through {!! !!} is an XSS surface. Decide whether to trust authors (staff-only panel) or run a sanitizer (e.g. HTML Purifier) at render time, and document the choice. Verify what Sky's own views do before you assume they did it.

Media and disks are your responsibility. Confirm the configured disk, run php artisan storage:link, and handle image resizing yourself — there is no transformation pipeline in the package.

Slugs are permanent URLs. Changing a post's slug breaks inbound links and any cached fragments. Add a redirect table or a slug_history column early; retrofitting it after launch is unpleasant.

Zero dependents means you are the canary. There is no downstream ecosystem catching upgrade breakage for you. Pin versions, keep the repository abstraction, and keep the smoke test in CI. Do the same for content safety: mysqldump the content tables on a schedule — Sky does not ship export or backup tooling.

Extension points, in order of preference: Filament plugin configuration → config-level model swaps → view overrides → model subclassing/observers → events. Vendor patches are not on that list.