Ogen Laravel Package

Getting Started

zolteam/ogen is an OpenAPI-driven code generation package for Laravel: you keep an OpenAPI spec in your repo and generate typed PHP artifacts (clients, DTOs, and/or request builders) from it, rather than hand-writing HTTP wrappers. Treat it as a dev-time tool, not a runtime dependency.

Minimal setup:

composer require --dev zolteam/ogen
php artisan vendor:publish --tag=ogen-config   # confirm tag in README

Then:

1. Drop your spec in the repo (e.g. openapi.yaml at the project root or resources/openapi/).
2. Point the published config (config/ogen.php) at the spec path, output namespace, and output directory — these are the three settings you will touch 95% of the time.
3. Run the generator (typically an artisan command such as php artisan ogen:generate; verify the exact signature against the README, since command naming is the first thing that drifts between versions).
4. Inspect the generated directory and confirm PSR-4 autoloading covers the output namespace before wiring anything up.

Where to look first: the config file (it documents the available knobs better than the README usually does), then the command's --help, then the generated output itself — reading one generated class tells you more about the package's conventions than any docs page.

First real use case: generating a typed client for a third-party API you consume (payments, CRM, shipping). This is the lowest-risk entry point because the spec is externally maintained, the blast radius is contained to one service class, and you get immediate value from IDE autocompletion and static analysis on request/response shapes.

Implementation Patterns

Spec-first, generated-code-second. Commit the spec, commit the generated output, and never edit generated files by hand. The diff of a regenerated directory is your review artifact — if a spec change produces a surprising diff, that is a bug caught at review time rather than in production.

Treat generated code as a vendor boundary. Don't call generated clients directly from controllers or models. Wrap each generated client in a thin Laravel service class, bind it in a service provider, and let the rest of the app depend on your interface:

final class BillingClient
{
    public function __construct(private readonly \Generated\Billing\Client $client) {}

    public function charge(ChargeRequest $request): ChargeResult { /* ... */ }
}

This gives you one place to swap the generated implementation, add retries/timeouts, or fall back to a hand-written client if the generator disappoints.

Drive base URLs from config, not from generated defaults. Generated constructors usually take a base URI. Resolve it from config('services.billing.base_url') (or equivalent) inside the service provider so staging/production switching stays in env vars.

Use it in tests via Laravel's HTTP fake. If the generated client is built on the framework's HTTP client, Http::fake() works unchanged. If it ships its own transport, fake at your service-class boundary instead and keep the generated layer out of your test surface.

CI drift check. Add a pipeline step that regenerates and fails on diff:

php artisan ogen:generate
git diff --exit-code -- app/Generated

This is the single highest-value integration: it prevents "spec updated, code silently stale" rot, which is the standard failure mode of every codegen tool.

Versioned specs side by side. If you consume multiple upstreams, keep one spec and one output namespace per upstream rather than merging into a mega-spec. Regeneration cost and diff noise both scale badly otherwise.

Gotchas and Tips

This package is unvetted. Zero stars and zero dependents means no community stress-testing: no one has hit the weird spec edge cases for you. Pin an exact version in composer.json, read the generated output before it reaches production, and be prepared to fork or vendor it. Budget for the possibility that you maintain it yourself.

Verify capability before committing architecture. Confirm which OpenAPI versions are supported (3.0 vs 3.1 differ meaningfully — nullable, oneOf, and JSON Schema semantics all shift), and whether it targets client generation, server stub generation, or both. Getting this wrong after the spec is written is expensive.

Never hand-edit generated files. Put a header comment and a .gitattributes entry marking the directory as generated, and consider a pre-commit hook that rejects edits to it. The moment one hand-patch lands, regeneration becomes a merge conflict generator.

Nullable vs optional is the classic codegen trap. OpenAPI distinguishes "field absent" from "field present but null"; many generators collapse this into a single nullable property. Check how the generated DTOs model optional keys before you build validation around them.

Enums and date formats drift. Generated enum classes go stale silently when upstream adds a value. Generated DateTime hydration often assumes RFC 3339. Test both against real upstream payloads early.

Autoload and namespace setup. The most common first-run failure is generated code landing outside composer.json's PSR-4 map. Run composer dump-autoload after changing output paths, and keep the output directory stable — moving it is a breaking change for every import.

Debugging approach. When output is wrong, reduce to a minimal spec reproducing the issue and diff the spec against the generated class. Most generator bugs are template bugs, and templates are usually publishable or overridable — check whether the package exposes custom templates or post-generation hooks; that is the escape hatch that determines whether you can live with the tool long-term.

Keep the generator out of production. --dev install plus a build step that ships the generated classes is cleaner than running codegen on deploy, which introduces a failure mode (generator unavailable, spec missing) you don't need at 3am.