Studio Laravel Package

Getting Started

Studio is a presentation layer, not a blogging engine. It ships controllers, routes, Blade views and compiled CSS that read from Canvas (cnvs/canvas) models. If Canvas isn't installed and seeded with at least one published post, Studio will render empty or error pages — install Canvas first, run its install command, migrate, and create an admin user before touching Studio.

Minimal path:

composer require cnvs/studio
php artisan vendor:publish --provider="Studio\StudioServiceProvider"
php artisan storage:link

Laravel's package auto-discovery registers the service provider, which in turn loads Studio's routes, views and config. Publish everything on the first pass (config, views, assets) — the exact --tag values vary by release, so run php artisan vendor:publish --provider="Studio\StudioServiceProvider" with no tag once and inspect what lands.

Where to look first, in order:

1. config/studio.php — route prefix/domain, middleware, and any theme toggles. This is the only knob you can turn without editing code.
2. The package's route file (vendor/cnvs/studio/routes/) — tells you exactly which URIs Studio claims (/, /posts/{slug}, tag/topic indexes, search, RSS).
3. vendor/cnvs/studio/resources/views/ — the layout and partials you'll be overriding.
4. vendor/cnvs/studio/src/Http/Controllers/ — the queries feeding each view.

First use case: get the blog index rendering at / (or blog/), confirm one post detail page loads with its featured image, then confirm the tag and topic archive pages resolve. That five-minute smoke test catches 90% of installation problems.

Implementation Patterns

Keep Canvas on a separate path. Canvas's admin lives under its own canvas.path config (default /canvas). Studio's reads live at the root or a prefix. Never let these two collide — set canvas.path to something explicit in config/canvas.php before you publish Studio, and delete the default welcome.blade.php route stub from routes/web.php so Studio's index can claim /.

Override views, not vendor files. Published Blade views land in resources/views/vendor/studio/ and take precedence over the package copies. This is the sanctioned customization point: copy layouts/app.blade.php and pages/post.blade.php, swap the compiled stylesheet for your own Vite/Tailwind build, and leave vendor/ untouched so composer update stays safe.

Route overriding for behaviour changes. When you need different queries (featured posts, pinned content, a curated home page), don't patch the package controller. Create App\Http\Controllers\BlogController that mirrors the package's method signature, then re-declare the route with the same name after the package routes are registered — or disable Studio's route loading and write your own route group that points at your controllers. Named-route overrides are the cleanest hook because Studio's views call route('studio.post', $post) internally.

Pull Canvas models directly for custom sections. Canvas\Post::published()->latest()->take(3)->get() with ->with('tags', 'topic') is all Studio does under the hood. Any additional homepage block — a newsletter strip, a "popular" rail using Canvas's view counts, a topic grid — should query the models yourself inside your own controller and hand the data to a published partial. Don't try to bend Studio's existing views into serving multiple data shapes.

Analytics and events. Canvas fires a PostViewed-style event/records a view row when a post is shown. Studio's post controller triggers it. If you replace that controller, remember to dispatch it or your view counts silently stop incrementing — a classic "why is my analytics dashboard frozen" bug after a refactor.

Feed and SEO. Studio typically exposes an RSS route. Sitemaps and OpenGraph tags are best added by overriding the layout's <head> partial rather than editing each page view. If you're running multi-language or multi-domain, wrap Studio's routes in a middleware group via config/studio.php's middleware array rather than editing the routes file.

Deployment. Commit the published views. Run php artisan config:cache and view:cache in the deploy pipeline, and make sure storage:link runs after every deploy — Canvas stores post images on the public disk and Studio's templates reference asset('storage/...').

Gotchas and Tips

The package name and namespace disagree. You install cnvs/studio but every class lives under Studio\. When running vendor:publish --provider=, quote the fully-qualified class name ("Studio\StudioServiceProvider") — a typo here silently publishes nothing and you'll spend an hour wondering why your overrides aren't taking effect.

Published views permanently shadow the package. Once resources/views/vendor/studio/ exists, package view updates are invisible to you. This is a feature, but it means upgrading Studio is a manual diff exercise. Before updating, snapshot the published tree; after updating, re-publish to a scratch directory and diff against yours.

Version compat is the biggest risk. This is a small, low-traffic package with zero known dependents. Its compiled Tailwind assets and Blade syntax predate @vite, Laravel 10/11 conventions, and Tailwind 4. Expect to patch a webpack.mix-era stylesheet, replace @php blocks that use removed helpers, and possibly adjust the service provider for newer Laravel. Pin the version in composer.json and treat composer update as a manual review event.

Route ordering bites. If your app already declares Route::get('/', ...) — or a catch-all — before Studio's routes load, you'll get your page instead of the blog. Check with php artisan route:list and grep for studio; the URI column tells you instantly whether the package routes even registered. Conversely, if Studio loads first, its catch-all post route can swallow your /about page. Explicit prefixes solve both.

Drafts disappear silently. Studio queries the published scope, which keys off published_at <= now(). Timezone mismatches between the app and the database will make a post "published in the admin" but invisible on the site. Verify with Post::published()->count() in tinker.

Pagination styling. Studio's paginate() calls use Laravel's default pagination views. Under Tailwind you must add Paginator::useTailwind() in a service provider, or your "Older posts" links render as unstyled bullet lists.

Cache layers hide your edits. Published views plus a cached view path is a reliable source of "my change did nothing." The standard triage: php artisan view:clear && php artisan config:clear && php artisan route:clear. If it still fails, check resources/views/vendor/ for a stray copy you forgot you made.

Images 404 after deploy. Two culprits: the storage symlink was never created, or Canvas's storage disk config points to a bucket while Studio's templates hardcode asset('storage/...'). Override the image partial to use Storage::disk(config('canvas.storage.disk'))->url($path) if you're on S3.

Real extension point: fork the controller, not the package. Anything beyond CSS and markup should live in your app. The package's controllers are thin enough that reimplementing one is usually faster and far more maintainable than patching vendor code — and it means the next composer update can't break you.