Typescript Generator Laravel Package

Getting Started

Verify before you build on it. This bundle is archived, has zero dependents and no external adoption trail, so treat the repository itself — not any blog post — as the documentation. Budget 20 minutes to read it before wiring it into a build pipeline.

1. Install from the repo, not from a version constraint. Since it is archived and unpublished/untagged in practice, pin a commit hash:

   "repositories": [{ "type": "vcs", "url": "https://github.com/vinatis/typescript-generator-bundle" }],
   "require-dev": { "vinatis/typescript-generator": "dev-main#<sha>" }
   

2. Register the bundle in config/bundles.php (it must come after FrameworkBundle), then check whether it ships a recipe. No recipe means you create the config file yourself — read src/DependencyInjection/Configuration.php for the real key names rather than guessing.

3. Find the entry point. The three files that tell you everything:

   • src/Command/ — the console command name and its options (--dry-run, --output, --filter).
   • src/DependencyInjection/Configuration.php — output path, source paths, naming strategy.
   • README.md — often the only spec for the mapping rules.

   bin/console list | grep -i typescript
   bin/console <command> --help
   

4. First use case: one PHP backed enum → one TS enum. Pick a low-risk enum already used on the frontend (a status, a country list, a shipping mode). Point the config at it, generate into assets/types/generated/, and diff the output by hand. If the shape matches what you would have written manually, you have understood the bundle.

5. Only then move to DTOs/interfaces and route or translation generation, one source type at a time.

Implementation Patterns

Decide the source of truth up front. The bundle is a one-way PHP → TypeScript projection. Anything you hand-edit in the output directory will be destroyed on the next run. Two viable models:

• Commit generated files — assets/types/generated/ is tracked, CI regenerates and fails on git diff --exit-code. Best when frontend devs work without a PHP runtime.
• Generate at build time — output goes to .gitignore, and a prebuild script runs the console command. Best for monorepo/Docker setups where PHP is always available.

Hook generation into existing lifecycle events rather than asking people to remember a command:

"scripts": {
  "post-install-cmd": ["@typescript-generate"],
  "post-update-cmd": ["@typescript-generate"]
}

A Makefile target or a docker compose run --rm php bin/console ... wrapper works equally well; the point is that developers never invoke it manually.

Keep generated output dependency-free. Generated enums and interfaces should import nothing — no import { Foo } from '../../services/foo'. If the bundle emits imports, that is a signal it is generating more than types, and you should restrict it to the enum/DTO subset.

Emit a barrel file (index.ts) re-exporting everything under generated/, so application code writes import type { OrderStatus } from '@/types' and never depends on the generator's file layout. If the bundle does not produce one, generate it in the same script — it is a five-line loop.

Use generated enums as the single source for UI vocabularies: select options, badge colour maps (Record<OrderStatus, string>), i18n key suffixes, and router param types. This is where the bundle pays for itself — a new enum case breaks the frontend build instead of silently rendering undefined.

Prefer as const objects over enum if the project uses isolatedModules or a bundler with verbatimModuleSyntax. If the generator only emits enum, wrap the output in a small post-processing step rather than fighting the bundle — it is archived and will not accept the feature request.

Sequence it in CI after composer install and before tsc --noEmit, so a PHP enum change fails the frontend typecheck in the same pipeline run.

Gotchas and Tips

• It is archived. No security patches, no PHP 8.3/8.4 or Symfony 7 compatibility work, ever. Vendor the package into src/ or fork it under your org the moment it becomes load-bearing; otherwise a routine Symfony upgrade will strand you with a bundle that no longer boots.
• Configuration is cached. After touching the config YAML, run bin/console cache:clear before concluding the option "doesn't work". Most first-hour confusion here is a stale container.
• Symfony version ceiling. Check composer.json's symfony/* constraints before installing. An archived bundle almost certainly caps at the Symfony version current when it was last touched; a hard cap will block your upgrade path.
• Naming collisions. PHP namespaces flatten into a single TS output directory. Two Status enums in different namespaces will overwrite each other or fail silently. Grep the output for duplicate filenames after the first full run.
• Case conversion is opinionated and lossy. SCREAMING_SNAKE values, PascalCase type names and acronym handling (VATRate → VatRate?) are configurable but rarely perfectly. Snapshot-test a handful of representative types so a config tweak doesn't silently rename every export.
• Type fidelity gaps. \DateTimeInterface and value objects typically become string, nullable properties may become optional instead of T | null, and collections may lose their generics. Document the known-approximate mappings in the repo, or the frontend team will trust them as exact.
• Output path is relative to the project root, not to the config file or the command's CWD. In Docker, a host-mounted volume with a different working directory will write to an unexpected place — verify with find . -newer composer.json -name '*.ts' after the first run.
• Never point the output at a source directory you also hand-write in. Use generated/ as a dedicated subtree and add it to .prettierignore/.eslintignore so lint autofixes don't create spurious diffs against regeneration.
• Debugging checklist: -vvv for the underlying exception, bin/console debug:container | grep -i typescript to confirm the extension loaded, and bin/console debug:config <alias> to see how your YAML resolved. If the command is absent, the bundle is not in config/bundles.php — the most common install failure.
• Extension points are limited by design. Expect to extend via your own console command that calls the generator service, or via post-processing the emitted files, rather than via Symfony tags or events. Confirm what services are public before relying on decoration.