Weave Code
Paragon Laravel Package
kirschbaum-development/paragon
Paragon, by Kirschbaum Development, is a lightweight Laravel package that adds a clean, expressive API for common PHP application needs, helping you keep code organized, consistent, and easy to maintain across projects.
A Laravel package for generating enum-like objects in typescript based on PHP enum classes.
Frequently asked questions about Paragon
- What is Paragon and what does it do in a Laravel application?
- Paragon is a Laravel package that reads your PHP enum classes and generates matching TypeScript enum-like objects for your frontend code. Instead of hand-maintaining status, role, or workflow vocabularies twice, you treat the PHP enums as the contract and let the generator produce the TypeScript mirror. It runs at build time as a Composer dev dependency, so nothing is added to your production runtime.
- How do I install Paragon in a Laravel project?
- Install it as a Composer dev dependency, publish its config file, and list the source paths that contain your enum classes. Then run the package's Artisan command to emit the TypeScript files into the directory your frontend build already picks up. Confirm the exact command name and config keys against the README for the version you install, and start on ^1.2.1 rather than ^1.2.0.
- Which Laravel, PHP, and TypeScript versions does Paragon support?
- Paragon consumes PHP enum classes, so PHP 8.1 or newer is the baseline requirement. The exact Laravel and Node/TypeScript support matrix should be verified against the README and release notes for your chosen version before you commit a roadmap slot. Do that check in a short spike instead of assuming compatibility from the package blurb alone.
- Should I commit the generated TypeScript files or generate them during the build?
- Both approaches work, but you must decide deliberately because the generator will happily write correct output into the wrong place and still report success. Committing artifacts makes drift visible in code review, while generating per build requires the codegen step to run before tsc. Whichever you choose, put the output directory under a named owner.
- How does Paragon handle quotes, backslashes, and template literals inside enum values?
- Earlier releases emitted malformed TypeScript when values contained quotes, backslashes, newlines, or template-literal syntax, which is why v1.2.1 exists. Treat that fix as hardening rather than proof of full coverage. Add regression fixtures for backticks, dollar-brace sequences, nested quoting, and Unicode line separators before trusting values influenced by config or tenant data.
- Can I use Paragon as a CI drift gate between PHP enums and TypeScript output?
- A dry-run or check mode that fails when generated output differs from committed artifacts is the natural CI fit, but whether Paragon exposes one should be confirmed in the command source. If it does not, you can still regenerate in CI and assert a clean git diff. Either way, wire the check before TypeScript compilation so a stale artifact cannot reach a build.
- Are Paragon's generated files byte-identical across macOS, Linux, and CI?
- That is something to test rather than assume. Codegen that is not reproducible across platforms produces diff noise, and the first reviewer who tires of it will disable the tool. Run generation on each platform in your matrix and compare output hashes before making the artifacts load-bearing.
- What happens with enum methods, TypeScript reserved words, or duplicate enum names across source paths?
- The naming and collision policy for TypeScript reserved words and same-named enums in different source paths is something to verify in the README and src. Likewise, confirm whether enum methods are evaluated at generation time and what the contract is for non-scalar or non-deterministic return values. If either answer is unclear, keep generated method output out of your public type surface.
- How does Paragon compare with generating TypeScript types from an OpenAPI spec?
- If an OpenAPI or typed-client toolchain already owns your contract surface, Paragon is a second generator covering a strict subset of it and you should probably decline it to avoid two sources of truth. Paragon is strongest when a Laravel backend feeds an Inertia, Vue, React, or mobile client and enum vocabularies are currently hand-maintained. It adds little when the frontend is server-rendered and reads PHP directly.
- Is Paragon safe to rely on long term for something like permissions or entitlement tiers?
- It is a small package with limited stars, a single primary maintainer, and a thin test surface, so supply-chain risk is real even though MIT licensing and deterministic text output make exit cheap. It is a reasonable implementation choice against an established pattern rather than an architectural change. Avoid making it load-bearing for a security-critical vocabulary without a fork-and-vendor fallback recorded.
Weaver
How can I help you explore Laravel packages today?