Ci4Orm Laravel Package

Getting Started

This package is still pre-1.0 (v0.0.9), so treat the public API as unstable and pin the exact version in composer.json rather than using a caret constraint that could silently pull v0.1.0.

1. composer require <vendor>/<package> — again, pin it: "<vendor>/<package>": "0.0.9".
2. Check whether the service provider is auto-discovered (extra.laravel.providers in the package's composer.json). If not, register it manually in bootstrap/providers.php (Laravel 11+) or config/app.php.
3. Look for a publishable config: php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" --tag=config. Read the config file before touching any code — most pre-1.0 packages put their behavioral switches there.
4. Read the source of the new validate function first. At this version there is likely no dedicated docs site, and the changelog entry ("add validate function") tells you nothing about the signature, return type, or failure mode. The class itself is the documentation.

First use case: the highest-leverage starting point is calling validate on the same input you'd otherwise hand to Laravel's Validator. Wire it into a single form request or controller action, run it against both a passing and a failing payload, and observe exactly what comes back (boolean, validated array, exception, or result object). Everything downstream depends on that one observation.

Implementation Patterns

Wrap it in a form request. Don't call validate ad hoc in controllers. Put it in rules() or in a withValidator/after hook so the failure path is a standard Laravel ValidationException and redirects/422 JSON responses keep working for free.

public function rules(): array
{
    return [
        'payload' => [new PackageValidationRule()],
    ];
}

Keep it out of the request layer when it's domain logic. If validate is validating a domain object (an import row, a webhook body, a queued job's payload), bind it behind an interface in a small service class so jobs and console commands can reuse it without faking an HTTP request:

$this->app->bind(Validator::class, PackageValidator::class);

Validate at the boundary, once. The common failure mode is validating on ingest and again before persistence. Pick the edge — job dispatch, controller, or command — and let the rest of the app trust the data.

Pair it with artisan for bulk work. If you're validating CSV imports or seeded data, loop in a command with $this->components->task() per row so failures are legible instead of a wall of exceptions.

Test the contract, not the implementation. Since the API is pre-1.0, write tests that assert your expectations (valid input passes, invalid input produces a specific exception or false) rather than asserting internal method calls. When v0.1.0 lands, those tests are your upgrade checklist.

Gotchas and Tips

• v0.0.9 is a warning, not a number. Under semver, anything can change in a 0.x minor bump. Pin exact versions and read the diff of every release — this changelog entry is a single line and communicates almost nothing about backward compatibility.
• The validate function's failure mode is the whole integration. Does it throw, return false, or return a result object with errors? Does it throw Laravel's ValidationException (so @error and $errors work) or a package-specific exception (so you must map it yourself)? Confirm this before writing any calling code.
• Check whether it returns validated data or just a verdict. "Validate" packages often discard unknown keys, or mutate/coerce types. If it returns a filtered array, use that for persistence rather than the original request input — otherwise you've validated one thing and saved another.
• Config caching bites pre-1.0 packages. If you publish and edit config, run php artisan config:clear locally and remember config:cache in deploy. Packages that read env() directly outside config files will break under config:cache — worth a grep.
• Debug by isolating. When a validation fails unexpectedly, dump the raw input immediately before the call. Most surprises are upstream: TrimStrings/ConvertEmptyStringsToNull middleware, or a cast that changed the type between the request and the validator.
• Watch for silent passes. A validator that returns "valid" for input it doesn't understand (unknown keys, wrong shape) is worse than one that throws. Add a negative test with a deliberately malformed payload to confirm it actually rejects.
• Extension point: if the package exposes a rule registry, macro, or Validator::extend-style hook, prefer it over forking. Forking a 0.0.x package means you own every future merge.