Smart Api Bundle Laravel Package

Getting Started

Install the package with Composer and publish any package config if your version provides it. Then locate the two main extension points: the validation map (where request body rules are declared) and the normalizer/processor registrations.

First use case: validate a JSON request body where one or two fields are optional and should fall back to a default instead of failing. Define the validation map for that endpoint, attach the new default option to the optional rule, and leave $throwOnUndefined enabled initially so missing required fields fail loudly during development.

Start by reading:

1. The package README section on request rules and the validation map.
2. The normalizer contract and processor contract.
3. The config/defaults for $throwOnUndefined and rule-level default.

A minimal flow looks like:

// Conceptual shape; use the package's exact rule syntax.
final class CreateUserRequest
{
    protected array $validationMap = [
        'name' => ['required', 'string'],
        'nickname' => [
            'rules' => ['string', 'max:255'],
            'default' => 'anonymous',
        ],
        'age' => ['nullable', 'integer'],
    ];
}

Use this package first for API endpoints with partial payloads, imported data, or frontend forms where the difference between “missing” and “invalid” matters.

Implementation Patterns

Use a validation map per request type or endpoint. Keep the map close to the controller/action or in a dedicated request class if the package supports it, so required fields, defaults, and undefined-field behavior are visible in one place.

Common day-to-day patterns:

• Optional fields with defaults: attach default to rules for fields that may be omitted. Use defaults for presentation or backward-compatible behavior, not for domain invariants that should always be supplied by the client.
• Strict vs. permissive endpoints: keep $throwOnUndefined = true for public APIs and machine-to-machine contracts. Set it to false for internal or legacy endpoints that may send partial bodies, where removing undefined parameters is acceptable.
• Normalize before validate: register normalizers for trimming strings, casting scalar types, normalizing enums, or converting empty strings to null. Since v1.1 runs normalizers before validation, normalizers should accept raw input and avoid assuming validated data.
• Processor ordering: define processors in the same order you want them executed. Treat the validation map order as meaningful and avoid relying on implicit ordering.
• Controller integration: validate the body before authorization-sensitive work or side effects, then pass only validated data to actions/services. If the package removes undefined parameters, downstream code should use the validated payload rather than the original request.
• Testing matrix: cover each endpoint with missing optional fields, missing required fields, invalid types, and normalizer edge cases. Assert both $throwOnUndefined modes if the endpoint can be configured either way.

A typical workflow:

1. Define the validation map.
2. Add normalizers for raw input cleanup.
3. Attach default to optional rules.
4. Decide $throwOnUndefined per request or config.
5. Add processors in explicit order.
6. Assert the resulting body content in feature tests.

Gotchas and Tips

• default and $throwOnUndefined interact. A rule-level default may prevent an exception for a missing value, while $throwOnUndefined controls whether undefined parameters are rejected or removed. Test the combination explicitly; do not assume one overrides the other in every case.
• Removing undefined parameters changes the request shape. With $throwOnUndefined = false, downstream has(), filled(), array_key_exists(), and array access checks may behave differently than before validation. Use the validated body consistently.
• Normalizers now run before validation. Existing normalizers that expected validated or typed input may break. They should handle raw strings, arrays, nulls, and unexpected shapes without throwing unrelated exceptions.
• Processor order is now map order. If processors depend on each other, make that dependency explicit. A processor that previously ran earlier or later due to implicit ordering may now see different input.
• Normalizer failures are not validation failures. An exception in a normalizer happens before validation errors are collected. Validate defensively inside normalizers or let the package’s exception handling surface the problem.
• Debug missing fields with strict mode. Temporarily set $throwOnUndefined = true to expose keys that are being silently removed. Once the client contract is fixed, switch back to the intended mode.
• Keep defaults in the request layer. Rule-level defaults are useful for request compatibility, but they can hide upstream bugs. Log or monitor when defaults are applied if the field is business-critical.
• Clear config caches after changes. If defaults or $throwOnUndefined are config-driven, run the Laravel config cache refresh in deployment and test with cached config enabled.
• Extension points: custom normalizers and processors are the right place for reusable input cleanup and post-validation transformation. Keep side effects out of normalizers; reserve processors for ordered transformations or side effects that must happen after validation.