Blog Bundle Laravel Package

Getting Started

1. Check your constraint compatibility before installing. v5 requires Symfony 6 or 7, which means PHP 8.1+ (Symfony 6) or PHP 8.2+ (Symfony 7). Laravel 9/10 resolve Symfony 6.x, Laravel 11 resolves Symfony 7.x. If you're on Laravel 8 or anything pinning symfony/*:^5, stop here — v5 will not install.
2. Install and publish:

   composer require <vendor>/<package>:^5.0
   php artisan vendor:publish --provider="<Vendor>\<Package>\ServiceProvider"
   php artisan migrate
   

3. Look first at the new API surface. This is the headline feature of v5 and the thing that replaces the removed Sonata Admin UI. Run php artisan route:list --path=api (or whatever prefix the package registers) and read the API controllers/requests directory. That route table is effectively your new "admin panel" contract.
4. First use case: wire a read-only listing into your app — hit the blog index endpoint from a controller or Inertia page, verify the JSON shape, then exercise create/update through the API. Getting the payload shape confirmed early tells you whether you can use the package as-is or need to override resources.

If you were previously on v4, budget the upgrade as a rewrite of your admin layer, not a dependency bump.

Implementation Patterns

Treat v5 as headless-first. With Sonata Admin gone, the package is now a content backend plus an HTTP API. The idiomatic integration is:

• Build your own admin on top of it. A Filament resource, Nova resource, or a small Inertia/Blade CRUD that calls the package API is the intended replacement. If the package publishes its Eloquent models and migrations, direct Eloquent access is also viable and simpler than HTTP round-trips for same-process admin screens.
• Override, don't fork. Extend the package's API controllers and swap the container binding in a service provider when you need custom validation, eager-loading, or response shaping. This keeps you upgradeable across 5.x.
• Secure the API explicitly. Register the routes behind your own middleware group (auth:sanctum, throttle, a policy per blog/post) rather than trusting package defaults. Content-management endpoints should never be internet-facing unauthenticated.
• Wrap it in a repository/service class in your app (BlogRepository) that talks to the package instead of scattering API calls or model queries through controllers. When the API shape shifts in 5.1, you change one class.
• Feature-test the endpoints, not just your wrappers: $this->postJson('/api/blogs', [...])->assertCreated() catches payload contract drift on upgrade.

Gotchas and Tips

• This is a hard breaking release. Removing Sonata Admin deletes services, routes, and classes. Grep your app/, custom packages, and any Composer-adjacent code for Sonata references before upgrading — leftover service definitions will fatal at container boot, not at a helpful line.
• Composer conflicts are the most likely first failure, not the package itself. Diagnose with composer why-not symfony/http-foundation '^6.0' and composer show -t to see what dragged in Symfony 5.
• The API is brand new and therefore thin. Assume sparse docs, no pagination caps, possibly no authorization or rate limiting baked in, and an unstable payload shape. Read the controllers before exposing anything. Pin ^5.0.x and watch 5.1 for contract changes.
• Confirm whether routes auto-register. If the API routes register from the service provider, they may be live the moment you composer require — check before deploying to staging with a public URL.
• Run php artisan config:cache and route:cache after publishing, and verify the package's route file is cacheable (no closures referencing non-serializable services).
• Debugging order: php artisan route:list --path=api → php artisan about (confirms Laravel/Symfony resolution) → storage/logs/laravel.log → composer show -t. Most "package is broken" reports at major-version boundaries are actually version-resolution or cached-config issues.
• Extension points to prefer over patching: published config (model/resource mapping), published migrations, container bindings for controllers/repositories, and published views. Anything you edit inside vendor/ becomes a permanent upgrade tax.
• Add a regression test around whatever admin functionality you rebuild. That test is your safety net the next time this package does a major bump.