Eloquent Middleware Laravel Package

Getting Started

jsonmapper/eloquent-middleware plugs into JsonMapper’s middleware pipeline so JSON payloads can hydrate Eloquent models instead of plain DTOs. Install it with Composer, then check the README and src/ for the exact middleware namespace and registration API. In Laravel, package discovery should register any service provider automatically; otherwise add it to config/app.php.

Typical first setup:

use JsonMapper\JsonMapperFactory;
use JsonMapper\Middleware\EloquentMiddleware;
use App\Models\User;

$mapper = (new JsonMapperFactory())->bestFit();
$mapper->addMiddleware(new EloquentMiddleware());

$user = $mapper->map(json_decode($payload), User::class);
$user->save();

Start with a simple import/webhook use case: take an API JSON object, map it to a model, inspect $user->getAttributes(), then persist. This confirms attribute mapping, casts, and mass-assignment behavior before you build larger ingestion flows.

Implementation Patterns

• Centralize mapper setup in a service provider or small factory class. Register the Eloquent middleware once and reuse the configured mapper.
• Pair it with JsonMapper’s case-conversion middleware when API keys are snake_case or camelCase but your model attributes differ. Register case conversion before the Eloquent middleware.
• Use it at the boundary between transport data and persistence: validate incoming JSON first, then map to models. Avoid passing untrusted payloads directly into models with sensitive attributes.
• For creates, map to a fresh model and call save(). For updates, map the payload, then apply attributes to an existing model or use updateOrCreate() with the mapped attribute array.
• Map nested JSON manually. The middleware handles model attributes; it does not automatically build Eloquent relationship graphs. Use setRelation() or explicit related-model creation for hasMany/belongsTo data.
• Lean on Eloquent casts for dates, enums, arrays, and encrypted values. Ensure the JSON shape matches what the cast expects.
• For batch imports, validate and map inside a transaction, then use upsert() or updateOrCreate() to avoid duplicate rows and excessive queries.
• In tests, assert mapped attributes with getAttributes(), verify casts with getCasts()/attribute access, and assert database state after save().

Gotchas and Tips

• Release 2.1.0 is a CI-only maintenance release: Travis CI was replaced by GitHub Actions. There are no runtime, API, or configuration changes to account for.
• Eloquent models created this way are unsaved: exists is false, timestamps are not populated until save(), and model events fire at persistence time, not mapping time.
• Be explicit about mass-assignment behavior. If the middleware uses forceFill() or raw attribute assignment, $fillable/$guarded may be bypassed. Validate and whitelist input at the boundary.
• $guarded = ['*'] is the Eloquent default and can block fill(). Know whether the middleware force-fills or respects guarding; inspect $model->isDirty() and getAttributes() when debugging.
• Casts are lazy. getAttributes() returns raw attributes, while toArray() may expose hidden/appended attributes and cast values. Use raw attributes for debugging and comparison.
• Nested objects can confuse JsonMapper and Eloquent attributes: JsonMapper may try to instantiate classes, while Eloquent expects scalar or array attributes. Add JsonMapper handlers for Carbon, enums, or custom value objects where needed.
• Middleware order matters. Put key normalization before Eloquent mapping and keep debug middleware last when diagnosing.
• Clear Laravel’s config cache after changing service-provider or mapper configuration: php artisan config:clear/config:cache.
• Extension points are the middleware itself and JsonMapper handlers. For custom hydration rules, subclass or wrap the middleware rather than modifying vendor code.
• When debugging, inspect getAttributes(), getCasts(), getDirty(), and the mapped model class before saving. Enable JsonMapper’s debug middleware to see how JSON keys map to properties.