Typescript Generator Bundle Laravel Package

Product Decisions This Supports

• Build vs. buy for the PHP↔TypeScript contract layer: this package replaces hand-maintained .ts interface files (or a bespoke codegen script) with attribute-driven generation from your existing PHP classes. The 1.0.0 tag is the first signal that this is a supported dependency rather than a prototype, so it can now be evaluated as a real "buy" option against ~1–2 weeks of internal codegen work.
• Feature scoping for typed frontends: the new TypeScriptMe PHP Attribute makes contract declaration opt-in and co-located with the DTO/model it describes. That turns "we should type our API payloads" from a cross-team migration project into an incremental, file-by-file adoption — a much smaller roadmap item to schedule.
• CI/CD and developer-environment roadmap: "executable from host or container" means the generator can run both locally (pre-commit, editor-adjacent) and in Docker-based CI. This supports a decision to add a generated-types drift check to the pipeline rather than relying on review discipline.
• Release-gate policy for generated artifacts: "prevent interface generation if it fails to create package.json" converts a silent partial-output failure into a hard stop. That supports gating frontend builds on successful generation instead of debugging phantom type mismatches downstream.
• Known-gap tracking: the TypeScriptBaseInterface fix for unknown property types tells you the tool degrades gracefully on loosely-typed or untyped properties. Useful when scoping rollout to legacy modules where PHP type coverage is incomplete — you can sequence adoption by type-coverage maturity rather than waiting for a full typing pass.

When to Consider This Package

Adopt when:

• You run a Laravel/PHP backend with a TypeScript frontend (Inertia + Vue/React, a separate SPA, or a typed API client) and currently duplicate payload shapes by hand.
• Contract drift is a recurring defect source — mismatches between PHP responses and TS types that only surface at runtime or in QA.
• You want generation as a build step, not a runtime dependency: the host/container parity and the package.json failure guard both point at a CI-first workflow.
• Your team is comfortable annotating classes with PHP 8 attributes and wants contracts declared next to the source of truth rather than in a central schema file.
• You are pre-1.0 on an internal codegen script and want to retire maintenance overhead. The phpstan / php-cs / rector pass in this release is a reasonable proxy for maintainer rigor.

Look elsewhere when:

• Your API is already described by OpenAPI/JSON Schema and generated clients (e.g. openapi-typescript) — you'd be introducing a second source of truth.
• You need runtime validation of payloads, not just compile-time types; this is a generation tool, not a validator.
• The backend is not Laravel or not PHP — the attribute/class-discovery model is framework-shaped.
• You require a long support runway: 1.0.0 is the first stable tag, so treat it as a young dependency and confirm maintainer responsiveness and a release cadence before putting it on a critical path.
• Your PHP classes are largely untyped and you cannot invest in annotating them; generation quality tracks your type coverage.

How to Pitch It (Stakeholders)

To executives: Our PHP backend and TypeScript frontend describe the same data twice, and every divergence is a bug that escapes to QA or production. This package generates the TypeScript definitions directly from the PHP classes we already maintain, so there is one source of truth and no manual sync. It reached its first stable release (1.0.0), which is the point at which it becomes reasonable to depend on. Cost is a dependency plus a small amount of class annotation; the alternative is building and indefinitely maintaining equivalent codegen in-house.

To engineering: Attribute-driven interface generation from existing PHP classes, runnable identically on host and in the container, which makes a "generated types are stale" check a straightforward CI gate. This release adds the TypeScriptMe attribute for co-located, opt-in contract declaration; fixes TypeScriptBaseInterface for unknown property types so partially-typed legacy classes don't break generation; and fails fast when package.json can't be written rather than emitting partial output. Codebase passes phpstan, php-cs and rector. Adoption is incremental — annotate one DTO, generate, commit — so we can pilot on a single module and measure drift-defect reduction before wider rollout.