Laravel Resource Modifier Laravel Package

Getting Started

This release is a rename plus a platform bump, not a feature release. Package moves from toneflix-code/laravel-resource-modifier to toneflix/laravel-resource-modifier, and the root namespace moves from ToneflixCode\ResourceModifier to Toneflix\ResourceModifier.

Requirements before you start: PHP ^8.3 (or 8.4) and Laravel 12 or 13. If you are on Laravel 10/11 or PHP 8.1/8.2, stay on the 1.x line — 2.0.0 will not install.

Upgrade path (do this in one branch, one commit):

composer remove toneflix-code/laravel-resource-modifier
composer require toneflix/laravel-resource-modifier:^2.0

Then, in order:

1. Rewrite imports (app/, config/, database/, tests/):

   grep -rl 'ToneflixCode\\ResourceModifier' app config database routes tests \
     | xargs sed -i 's/ToneflixCode\\ResourceModifier/Toneflix\\ResourceModifier/g'
   

2. Re-publish the config (the vendor publish tag and config file are tied to the new vendor name) and delete the old published copy so you don't end up with two config files referencing different namespaces.

3. php artisan config:clear && composer dump-autoload.

First use case: pick one resource/endpoint that currently hand-assembles its JSON (or overrides toArray() with a pile of conditionals) and move that shaping logic into a modifier. Keep the change scoped to a single endpoint so you can verify the new namespace wiring before rolling out broadly.

Implementation Patterns

Migration shim while you cut over. If the rename touches many files and you can't land it atomically, add a temporary alias in a service provider so old imports keep resolving during the migration window:

// AppServiceProvider::register() — DELETE once migration is done
class_alias(\Toneflix\ResourceModifier\ServiceProvider::class, \ToneflixCode\ResourceModifier\ServiceProvider::class);

Treat this as a strictly time-boxed hack; it hides incomplete migrations and will confuse the next reader.

Centralise modifiers instead of editing resources. Put modifiers in a dedicated namespace (e.g. App\Http\Resources\Modifiers) and register them in one place. That gives you a single grep target for "what shape does this endpoint return" and keeps JsonResource classes thin — the resource stays a field-mapping concern, the modifier owns the transformation policy.

Apply at the resource layer, not the model. Modifiers belong on the output contract. Accessors and model methods leak into other consumers (queues, console commands, internal services) and make the API shape impossible to reason about in isolation.

Version-pin and matrix-test. Require ^2.0 explicitly rather than *. Update your CI matrix to Laravel 12/13 × PHP 8.3/8.4 and drop the old cells in the same PR, otherwise you'll get green builds on a runtime the package no longer supports.

Testing. Assert on the JSON shape, not the modifier internals: $this->getJson('/api/...')->assertJsonStructure([...]). If you use Testbench/Pest locally, note the package's own toolchain (testbench ^10.11|^11.1, pest ^4) is dev-only and does not constrain your application's test setup.

Gotchas and Tips

• Both packages can coexist silently. Because the namespace changed, a half-finished migration still autoloads and runs — you just keep executing the old, unmaintained code path. After upgrading, verify with composer show | grep resource-modifier that only toneflix/laravel-resource-modifier is present, and grep for ToneflixCode to catch stragglers in docblocks, string-based class references, and config values (which the sed above will miss if they're in .env or the DB).
• Stale published config is the #1 upgrade failure. The old config file survives composer remove. If it's still auto-loaded, you'll get missing-class errors or, worse, silently ignored settings. Delete the old file before re-publishing.
• Clear caches aggressively. config:cache, route:cache, and opcache can all serve pre-rename state. Also clear PHPStan/Psalm/IDE index caches — static analysers will happily report "class not found" for weeks after a clean install.
• composer remove before composer require. Doing it in the other order leaves both installed and Composer won't warn you.
• The PHP 8.3 floor is the real blocker for most teams, not Laravel 13. Check your deploy images, CI runners, and any shared base Dockerfile before opening the upgrade PR — a failed composer update in CI is a much cheaper discovery than a failed deploy.
• Laravel 13 support is forward-looking. If you're still on Laravel 12, 2.0.0 is functionally equivalent to 1.1.5 apart from the rename. Don't schedule the upgrade alongside other risky changes; treat it as a mechanical, low-value-diff migration.
• Extension points are unchanged in spirit — any custom modifiers or subclasses you wrote against the old namespace need the same import rewrite, and any class ... extends referencing the old base classes must be updated or they silently fall out of the modifier pipeline.