Typescript Generator Bundle Laravel Package

Product Decisions This Supports

• Contract ownership: deciding whether PHP DTOs/request models become the single source of truth for frontend/backend API shapes, instead of hand-maintained TypeScript interfaces that drift every sprint. This package is the cheapest way to test that hypothesis before committing to a schema-first rewrite.
• Build vs. buy for type sync: choosing between (a) adopting a generator, (b) funding an internal Artisan command, or (c) migrating to OpenAPI/JSON Schema with openapi-typescript. The honest read: for a Laravel stack, this is a reference implementation for option (b), not a drop-in for option (a) — it is a Symfony Bundle with no Laravel auto-discovery, no extra.laravel wiring, and no Artisan command.
• Roadmap sequencing for typed clients: if the frontend is TypeScript, codegen can unblock typed API consumers a quarter or more ahead of a schema-first migration, which is a multi-sprint platform effort.
• Feature-level delivery decisions: any story that adds or changes a payload can ship with regenerated interfaces, cutting "works in Postman, breaks in the SPA" defects and the review overhead of manual type diffs.
• Use cases: admin dashboards, Inertia/SPA frontends backed by Laravel, internal tools, and any surface where the PHP model is authoritative and the consumer is TypeScript.
• What it does not decide: it is not a contract-governance tool, not an API documentation source, and not a substitute for runtime validation. Those remain separate decisions.

When to Consider This Package

Consider it when:

• You want a fast, low-cost proof that PHP-derived TypeScript generation removes a real class of bugs in your codebase, before spending on a platform migration.
• Your PHP models are DTO-shaped — typed properties, explicit types, little magic — so reflection produces something faithful.
• You accept extracting or wrapping the generator behind an Artisan command rather than consuming the Symfony bundle directly.
• You will commit generated output and enforce a CI drift check.
• Governance tolerance is high: internal tooling, where a single-maintainer dependency is acceptable and MIT licensing makes forking legally unencumbered.

Look elsewhere when:

• You need a Laravel dependency, not a reference. A Symfony Bundle cannot be composer require'd into Laravel and work — no bundle registration, no Symfony DI compilation, no tag-based command discovery. Budget a day or two of extraction work; verify first whether the bundle wraps a framework-free core library you can depend on directly (that changes effort by an order of magnitude).
• OpenAPI/JSON Schema is already your contract — generate from the schema, not from implementation classes.
• You need maintenance guarantees, SLAs, or broad framework coverage. 16 stars, 0 dependents, composite score 0.43, and a bus factor of one signal real abandonment risk.
• Your models are Eloquent entities with relations and lazy proxies — extraction will be lossy and will leak persistence concerns into the frontend.
• The API is public or high-stakes, where type correctness outweighs setup speed.
• Nullable and union handling that silently yields any would fail your tsconfig strict/noImplicitAny settings.

The dominant risk to price in: silent type drift. An unmaintained reflector facing PHP 8.2/8.3 constructs (enums, readonly, unions, promoted params) will emit TypeScript that compiles fine and is wrong at runtime — the worst failure mode. A golden-file test catches changes, not incorrect mappings; pair with runtime validation at the boundary if correctness matters.

How to Pitch It (Stakeholders)

To executives: a small MIT-licensed tool that turns our PHP models into TypeScript interfaces automatically, eliminating a recurring class of frontend/backend integration bugs and removing manual type maintenance from every API change. Cost is effectively zero and the risk is contained — it runs at build time as a console command, never in production request paths. Recommend funding a one-sprint spike, not a platform standard, until it proves out on one bounded module.

To engineering: be straight about the mismatch. This is a Symfony command, not a Laravel package — no auto-discovery, no Artisan integration. The underlying capability (reflect over PHP classes, emit .ts interfaces) is framework-agnostic; the delivery is Symfony glue. The cheap path is a half-day spike in a throwaway Symfony skeleton pointed at a few representative DTOs to answer the quality and type-mapping questions, then — if output is acceptable — lift the generator into app/Support/TypeGen behind a thin php artisan types:generate --namespace=App\\Data --out=resources/js/types/generated.ts. Add a golden-file test; that is the single most valuable piece of engineering here, because it converts an unmaintained dependency into pinned, verifiable behavior. Vendored the core unmodified so upstream fixes can be pulled if they arrive.

The trade we're accepting, stated plainly: low adoption signals (16 stars, 0 dependents, one maintainer) mean we own the reflection logic against every PHP minor upgrade — a few hours per release, permanently, and invisible on any roadmap. Mitigate by keeping the fork thin (glue plus a single centralized type-mapping table), naming an explicit internal owner, and documenting "generated file, do not edit; regenerate with X." Enforce regeneration via a CI drift check, not convention. On the frontend side, get explicit agreement that generated types are authoritative — without that, teams maintain parallel hand-written interfaces and the tool becomes pure overhead.

Bottom line: the problem is real and this is the right shape of solution for the wrong framework. Fund a one-day spike; treat any durable artifact as a small, well-tested in-house Artisan command with this repo as its starting point and design reference.