Blost Laravel Laravel Package

Getting Started

Install and publish everything in one pass:

composer require "corpuscom/blost-laravel:^1.0"
php artisan vendor:publish --provider="Corpuscom\BlostLaravel\BlostServiceProvider"
php artisan migrate

The service provider is auto-discovered, so there is no config/app.php step. vendor:publish is the single most important command in the package — it gives you the config file (connector token, route/prefix and pagination settings), the migration, and the Blade templates you will almost certainly need to override. Publish the config first, then read it top to bottom before writing any code; it is the map of everything else.

Where to look first, in order:

1. config/blost.php (name may differ slightly — whatever lands in config/) for the connector token and route prefix.
2. vendor/corpuscom/blost-laravel/src/ for the Article model, the published-scope logic, and the controllers behind the public pages.
3. vendor/corpuscom/blost-laravel/resources/views/ before you copy templates into resources/views/vendor/..., so you override the smallest surface possible.

First use case: the zero-UI path. Configure the token, run the migration, publish two articles through the bundle's publishing API (shared with corpuscom/blost-bundle), then hit the public listing route. That single loop — publish via API, read via Blade — validates token auth, the UUID primary key, UTC date handling, and the scheduled-visibility scope at once. Only after that loop is green should you start overriding views or mounting your own routes.

Implementation Patterns

Treat the publishing API as the write path, Eloquent as the read path. The package deliberately splits these: writes go through corpuscom/blost-bundle's shared authenticated API, reads go through Eloquent and Blade. Day-to-day, that means your app should not be creating Article records directly in application code. If you need synthetic or seeded content, publish through the API rather than mass-inserting rows, otherwise you will drift from whatever fields and invariants the bundle enforces.

Wrap reads in a scope, not in controller conditionals. Scheduled visibility implies a query constraint (roughly where('published_at', '<=', now())). Do not re-implement it per controller. Confirm the exact scope name in the source and use it consistently, including in your own custom queries, sitemaps, feeds, and search endpoints — anything that queries articles without the scope will leak future-dated posts.

Cache with a short TTL around publication boundaries. Because visibility changes on a timestamp rather than on a write, a cached listing will not invalidate itself when a post goes live. Either cache with a TTL shorter than your typical scheduling granularity, or key the cache by the next scheduled publish time for the collection.

Override templates by publishing, not by editing vendor. Blade resolution prefers resources/views/vendor/... for published namespaces, so copy only the listing and detail templates you intend to change. Keep a diff of the published originals so you can spot changes when you upgrade within ^1.0.

Mount the public routes under your own prefix if /blog is already taken. Publishing the config should expose the route prefix; change it there rather than wrapping the package routes in a group, so internal route names and generated links stay consistent.

For a headless or Inertia front end, skip the Blade layer entirely and expose your own controller that uses the model plus the published scope, keeping pagination on the query builder so links() semantics survive if you later add a view. The package's public pages remain useful as a reference implementation and as a smoke test that the connector is configured correctly.

Media is referenced, not mirrored. Upload assets to your own storage/CDN and publish absolute URLs. Build a small helper or accessor for image URLs so a future CDN migration is a one-line change rather than a content rewrite through the API.

Gotchas and Tips

• UUID primary key changes your assumptions. Expect $incrementing = false, $keyType = 'string', and route model binding on a non-integer key. findOrFail, whereKey, and relation foreign keys must be string-typed; orderBy('id') is meaningless as a chronology, so order by published_at and add a tiebreaker for stable pagination.
• UTC everywhere, convert at the edges. Dates are stored and exposed in UTC. A post scheduled for "Monday morning" means Monday morning UTC unless you convert in your own layer. The classic bug is a post that appears a day early or late for a non-UTC audience — verify the scope and any date formatting in the templates against your app timezone.
• Pagination drift. Ordering by a nullable or non-unique published_at can duplicate or skip rows across pages. Add a secondary sort key (the UUID is fine as a tiebreaker) in any custom listing query.
• Editorial HTML is trusted, and that is the whole security model. The package renders article HTML unescaped, which is correct for trusted editors and catastrophic if the publishing API is reachable by anyone else. Treat the connector token as a secret, keep it in .env and out of version control, rotate it, and never expose a write proxy to a browser. If any author is untrusted, sanitize on ingest or before render — do not rely on the package.
• Run the migration before touching the routes. A freshly installed package with an unrun migration fails at query time, not at boot, so the error surfaces as a 500 on the listing page rather than an obvious setup failure.
• Version-coupled to the bundle. corpuscom/blost-bundle ^1.0 is a hard requirement; a bundle minor release can change the payload shape your app depends on. Pin the bundle explicitly in composer.json if you are not prepared to test its upgrades, and read its changelog rather than only this package's.
• Route and view name collisions. Auto-discovery plus public routes means a pre-existing /blog route or a blog.index route name will conflict silently. Check php artisan route:list after install.
• Debugging the connector: a 401 is almost always a missing or stale token after a config cache rebuild; a 422 is payload shape, which is a bundle concern. php artisan config:clear before concluding anything about auth.
• Extension points worth knowing: the Eloquent model (scopes, accessors for excerpts and reading time), the published config, the published views, and the API surface behind the bundle. There is no documented repository or event layer here, so avoid reaching into package internals — everything you need should be reachable through those four.
• Upgrade discipline inside ^1.0: re-publish and diff the config and views after each bump; published copies do not track vendor changes automatically, so a new config key will simply be absent and fall back to a default you never saw.