Ng Model Generator Bundle Laravel Package

Getting Started

Framework reality check before anything else: despite the vendor-neutral name, this is a Symfony bundle, not a Laravel package. It consumes API Platform resource metadata (Symfony DI, ResourceMetadataFactory, serializer property metadata) and emits Angular TypeScript models. There is no service provider, no Artisan command, no config publish. If your backend is Laravel, you cannot "just install" this — you either run it as a sidecar in a small Symfony app pointed at the same metadata, or treat the repo as a reference implementation of the "API-metadata → TS models" pattern and drive your own generator from an OpenAPI export.

Minimal steps in a Symfony + API Platform host:

1. Add the repo as a Composer VCS source (it lives on gitlab.irstea.fr, not Packagist), then composer require irstea/ng-model-generator-bundle. Pin to a commit SHA — assume no tags and no semver.
2. Register the bundle in config/bundles.php:

   Irstea\NgModelGeneratorBundle\NgModelGeneratorBundle::class => ['all' => true],
   

   Verify after composer require — private bundles almost never ship a Flex recipe, so this is usually manual.
3. Add config: target output directory, namespace/file prefix, and resource include/exclude filters.
4. Run the generator command (the actual name lives in src/Command/ — commonly something like ng-model:generate; confirm, don't guess).

Where to look first, in order:

• README.md / description.md for the command name and config keys — then cross-check against code, private-bundle docs go stale.
• src/Command/ — the entry point. This tells you exactly what it reads (metadata) and writes (files, where).
• src/DependencyInjection/Configuration.php — the authoritative config tree: output path, resource filters, template options. Trust this over docs.
• Resources/ or templates/ — the templates shaping the emitted .ts. This is where the actual TypeScript conventions live.

First use case to validate: pick one representative entity — a few scalars, one relation, one nullable field, one enum. Run the generator, open the emitted .ts, and confirm it compiles under your Angular strict settings. Do this before wiring anything into CI or a second entity. You are validating output quality, not just "it ran."

Implementation Patterns

Config-driven mapping is the main lever. The bundle is a mapping engine: Doctrine/API Platform metadata on one side, TypeScript type conversion on the other. Do the type work in config and templates, not in post-processing scripts — that keeps the mapping reviewable and re-runnable.

• Whitelist resources explicitly rather than generating-everything. A config that lists the API resources you actually expose prevents accidental leakage of internal entities into the frontend model set.
• Own the templates. Override the emitted templates to match your Angular conventions: interface vs class, readonly fields, enums as const enum or string unions, dates as string vs Date. This is the cleanest extension point and avoids patching generator internals.
• Treat output as read-only and mark it. Add a "generated — do not edit" header in the template and gitignore or commit deliberately — pick one, don't drift. Hand-edits get silently clobbered on the next run.

The regeneration workflow that actually holds up:

1. Generation is a build step, not an occasional manual run — a Makefile target, Composer script, or CI job.
2. Drift check in CI: regenerate against current metadata and git diff --exit-code. If metadata changed and models didn't, the pipeline fails and the schema change surfaces in code review instead of in production.
3. Contract test: compile the generated models under Angular strict mode, and spot-check field presence/optionality against a live API response for at least one resource.

Sidecar pattern (Laravel or non-Symfony host). Run a minimal Symfony app containing the bundle against the same API Platform metadata, emit .ts into the Angular repo as a CI artifact. Keeps the host app untouched, preserves the original design's fidelity, at the cost of a second deployable and version-skew risk (see below).

Integration tip: wrap the raw command behind your own thin script so the invocation, config path, and output dir are fixed in one place. When (not if) you fork the emitter, that wrapper is the swap point — the calling code and CI don't change.

Gotchas and Tips

• Wrong framework, correct diagnosis. The biggest trap is assuming Laravel applicability because it appeared in a PHP package list. No NgModelGeneratorServiceProvider exists. Confirm Symfony + API Platform before spending an hour on install.
• Private forge + no tags. gitlab.irstea.fr may require auth or be unreachable from CI. Mirror the repo internally and pin a SHA. Set "minimum-stability" / prefer-stable appropriately for an untagged VCS dependency.
• License unknown. Verify terms and fork/redistribution rights before shipping generated code anywhere external. Gate adoption on this.
• Silent divergence is the failure mode to design against. API Platform metadata changes — serializer groups, normalization context, denormalization hints — can produce stale or wrong models with no error, because TypeScript still compiles. The CI drift check and a strict-mode compile gate are your only real guards.
• Serializer groups control the field set. If a property is missing from generated models, check the resource's normalization groups first, not the bundle config. This trip-up costs the most debugging time.
• Nullability and readOnly. Generated optional fields must map to ?: / | null correctly, or you get runtime undefined in Angular that strict mode won't catch at the boundary. Add these cases to your first-use-case validation.
• Enums, relations, polymorphism. These are the mappings most likely to be naive or incomplete. Test each one on a representative resource before trusting a whole model set.
• Skipped resources fail silently. No error surface when the generator can't resolve a resource — you ship a partial model set. Verify the emitted file count against your whitelist.
• Version skew (sidecar mode). The sidecar's Symfony/API Platform versions must track the main app's; a mismatch feeds the generator the wrong metadata. Pin both.
• Strict-mode breakage on Angular upgrades. Generated output is a build artifact under your compiler settings — treat Angular major bumps as a task that includes regenerating and re-verifying models.
• Debugging playbook: inspect the actual metadata the generator sees (dump the API Platform resource metadata for the failing resource), run the command in dry-run/verbose if available, then read the template that renders the file. Almost every bug is in the template or the input metadata, not the mapping layer.
• Extension points, in order of preference: override templates → config filters/mappings → decorate the metadata service → fork. Only fork when the emitter logic itself is wrong, and when you do, strip the bundle wiring and expose a single standalone command so it's ownable long-term.

Bottom line for a Laravel developer: this is not a dependency you adopt; it's a pattern to learn from. Default to openapi-typescript/orval on an exported OpenAPI spec — maintained, framework-agnostic, and covers more than models. Reach for this bundle only on a genuine Symfony + API Platform + Angular stack, with a named internal owner and a documented exit path.