Laravel Json Schema Laravel Package

Getting Started

Start by confirming which layer exposes the new normalizeWithJsonSerializable option: typically the package config file after php artisan vendor:publish, or the validation/normalization entry point if your integration passes options per call. The default is true, so existing applications should behave exactly as before after upgrading to v3.0.1.

First practical use case: keep the default for normal Laravel request validation where payloads may contain Eloquent models, API resources, or custom JsonSerializable objects. Only reach for normalizeWithJsonSerializable => false when you have measured memory pressure from extremely large payloads and can guarantee the data being normalized does not rely on Laravel-specific JsonSerializable behavior.

Look first at:

• the package config file for the new flag,
• the normalization/validation call site used by your form requests or middleware,
• any code path that passes Eloquent models or JsonModel instances into validation.

Implementation Patterns

Use the default true path for day-to-day Laravel work. It preserves drop-in compatibility and correctly handles unusual JsonSerializable contracts such as Eloquent models and JsonModel instances.

For high-volume or large-payload endpoints, switch to false selectively rather than globally. Prefer an environment-driven config value or a dedicated validation path for those endpoints, for example:

// config/package.php
'normalize_with_json_serializable' => env('JSON_NORMALIZE_WITH_SERIALIZABLE', true),

Then disable it only where payloads are large and already plain arrays/scalars:

JSON_NORMALIZE_WITH_SERIALIZABLE=false

When using the fast Opis\Helper::toJson path, normalize model data explicitly before validation. For example, convert Eloquent models with ->toArray() or a resource before handing the payload to the validator. This keeps behavior predictable and avoids relying on implicit JsonSerializable handling.

Good integration points:

• Form requests: keep default behavior unless the request is known to carry very large JSON documents.
• Middleware: disable the flag only for specific high-throughput routes.
• Queued jobs and artisan commands: benchmark both modes if they process large JSON payloads, because memory profile is the main difference.
• API ingestion endpoints: validate the incoming JSON as arrays/scalars, then map to models after validation.

Gotchas and Tips

The main pitfall is silently losing Laravel-specific serialization behavior. With normalizeWithJsonSerializable => false, the package uses Opis’s Helper::toJson path, which is faster and less memory intensive but does not honor unusual JsonSerializable contracts such as Eloquent models or JsonModel. If a payload contains those objects, validation may see a different structure than expected.

Test both modes with representative payloads, especially:

• Eloquent models with hidden/appended attributes,
• API resources,
• custom JsonSerializable classes,
• nested models and collections.

Remember to clear cached config after changing the flag:

php artisan config:clear

If you cannot override the option per call, avoid changing the global default just to optimize one large endpoint. Use a separate config value, environment variable, or dedicated service path instead.

For debugging, compare the normalized JSON produced by both modes. A validation failure that appears only after disabling the flag usually means the payload depended on JsonSerializable behavior rather than plain array/scalar data.

Treat false as an optimization, not a default. Measure memory and response time before and after. The default true is the safe drop-in choice for existing applications upgrading to v3.0.1.