Sylius Article Bundle Laravel Package

Getting Started

This release is a patch-level feature bump on a pre-1.0 package (v0.7.0), so treat the API as unstable and pin the exact version in composer.json before upgrading.

1. composer update to pull v0.7.0, then check whether the package ships new migrations:

   php artisan vendor:publish --tag=yourpackage-migrations
   php artisan migrate
   

2. Look first at the published config file and the Category model. The two changes in this release both live there: the new code attribute and the route-binding logic behind the category 404 fix.
3. Clear caches immediately after upgrading — the 404 fix very likely touches route model binding or route registration:

   php artisan route:clear && php artisan config:clear && php artisan cache:clear
   

4. First use case: create a category with a code, attach an article, and request the category URL. If it resolves instead of 404ing, the upgrade is behaving. Then verify existing categories (which will have a null code) still resolve.

Implementation Patterns

Use code as the stable identifier, slug as the SEO surface. The most natural pattern is to let code be the machine-facing key (API payloads, internal links, imports) and keep slug for public URLs. If the package's route binding now prefers code, decide deliberately which one wins and override resolveRouteBinding() on your extended model if you need slug-based URLs preserved.

Backfill before you enforce uniqueness. The migration almost certainly adds a nullable code column. Existing rows will be null. Backfill in a separate migration or command, then add the unique index — otherwise you get a failed migration on any non-empty production table.

Category::whereNull('code')->each(function ($category) {
    $category->update(['code' => Str::slug($category->name)]);
});

Seed codes explicitly. Update your category seeders and factories so tests and local environments exercise the new field rather than relying on it being nullable.

Wrap category lookups in your own resolver. If you expose categories via an API or a menu builder, centralise lookup behind a repository or scope (Category::byCode($code)) rather than scattering where('code', ...) calls. This insulates you from the next binding change in a 0.x release.

Cache invalidation on save. Category trees are a common caching target and a new identifying field is an easy way to serve stale keys. Key your cache on code where you previously keyed on id or slug, and bust on saved/deleted model events.

Gotchas and Tips

• Pre-1.0 churn. A minor bump adding a column and changing 404 behaviour is a reminder that 0.x minor versions are effectively breaking. Pin with "vendor/package": "0.7.*" and read the changelog before every bump.
• The 404 fix may change resolution semantics. If you previously worked around the category 404 by registering a custom route or overriding the controller, that workaround can now conflict with the package's own binding. Remove overrides and re-test rather than layering both.
• Route and config caching bite hardest here. Deployments that run route:cache will not pick up the fix until caches are rebuilt. Add cache clears to your deploy script if they are not already there.
• Mass assignment. If you extend the package's Category model, add code to $fillable (or $guarded) yourself — published models are not updated by composer update, so your copy will silently drop the field.
• Validation. Add a unique:categories,code rule plus a max length matching the migration; the package is unlikely to ship form request validation for you.
• Debugging 404s. Use php artisan route:list --path=categories to confirm the route and its binding, and Route::getBindingCallback() behaviour via a quick dd() in a tinker session on resolveRouteBinding. Check whether a null code on legacy rows is the actual cause before assuming the package is at fault.
• Extension points. Prefer subclassing the category model and rebinding it in a service provider over editing published files, so future 0.x releases remain mergeable.