Download the PHP package gaiatools/laravel-type-bridge without Composer

Gaia Tools Laravel Type Bridge

A Laravel package for generating TypeScript/JavaScript enums and frontend translation files from your Laravel app.

Features

• Automatically discover and generate frontend enums from PHP backed enums
• Opt-in enum generation using the #[GenerateEnum] attribute
• Flexible discovery via configurable paths (supports Modules or custom structures)
• Generate TypeScript or JavaScript output
• Support for translation file generation (TS, JS, or JSON)
• Configurable backed-enum discovery toggle and excludes

Requirements

• PHP 8.2 or higher
• Laravel 11.x orhigher

Installation

Install the package via Composer:

Publish the configuration file:

Smart config publishing

Or Laravel config publishing

Configuration

See config/type-bridge.php for all configuration options and inline documentation.

Supported translation engines

The translator utilities generated by this package can work with multiple i18n libraries through a tiny "engine" interface (an object exposing t(key: string): string). Out of the box we support:

• i18next
• react-i18next (uses the same i18next engine)
• vue-i18n

Tip: In config/type-bridge.php you can set i18n_library to control how translation keys are generated/organized for your target library. The default i18next also covers react-i18next.

Usage

Basic Enum Generation

Create a backed enum in your Laravel application:

Generate the frontend enum (TypeScript by default):

This will create a TypeScript file at resources/js/enums/generated/Status.ts:

To generate JavaScript instead of TypeScript:

Check mode (CI drift detection)

Validate that your previously generated frontend enum files are still in sync with the current PHP enums without writing any files. This is ideal for CI to detect drift.

Run:

Behavior:

• Discovers current PHP enums and computes the expected frontend entries.
• Loads the previously generated frontend files from your configured output path.
• Compares both keys and values.
  • New case → reported as added (green in decorated terminals)
  • Removed case → reported as removed (red in decorated terminals)
  • Changed value → reported as both remove (old) and add (new) on the same row
• Exit codes:
  • 0 when everything is in sync
  • 1 when any difference is detected (suitable for failing CI)

Notes:

• --format controls which frontend files to compare against by extension (ts or js). If omitted, the command uses your configured type-bridge.output_format.
• Each drifted enum is shown as its own table with the fully-qualified class name as the header, to avoid ambiguity when multiple enums share a short name.
• Cases with the same key are matched onto the same row so value changes are immediately readable side-by-side. Pure additions or removals appear on their own row with - in the empty column.
• When an enum has both unmatched removals and unmatched additions, a warning is shown — this may indicate a rename where frontend references need to be updated manually.

Examples

In sync:

Differences found (new case added to the PHP enum):

Value change:

Possible rename (unmatched removal and addition):

Output (resources/js/enums/generated/Status.js):

Dirty mode (generate only new/changed enums)

Generate only enums that are missing or out of sync with the frontend output, using the same drift criteria as --check. This is useful for incremental builds or large projects.

Run:

Behavior:

• Computes diffs exactly like --check (missing files, added/removed cases, or changed values).
• Writes only the enums that are dirty.
• Prints No dirty enums found. when everything is already in sync.

Opt-in Enum Generation

Use the #[GenerateEnum] attribute to explicitly mark enums for generation:

Enum Groups (derived exports)

Enum groups let you export curated subsets or mappings alongside the base enum. Groups are defined by public static methods and are only included when you opt-in via #[GenerateEnum(includeMethods: [...])].

Rules:

• Each listed method must be public static with zero parameters.
• The method must return an array.
• A sequential array becomes a group array unless it contains only enum cases; arrays of enum cases become a group record keyed by case name.
• An associative array becomes a group record.
• Values may be enum cases, backed values that match a case, or scalar/null literals.
• The group name is the method name converted to StudlyCase and must not collide with the enum name or other groups.

Example:

Generated output (TypeScript):

Available Commands

Generate Everything (enums + translations + translators)

Generate Enums

Generate Translations

Translation output examples (for locale en):

• TypeScript (resources/js/lang/generated/en.ts)

Publish Translator Utilities (frontend helpers)

These reusable helpers are required by the generated enum translators. Run once to publish them into your frontend source tree.

Defaults (can be changed in config/type-bridge.php → enum_translators.*):

• utils_composables_output_path: resources/js/composables
• utils_lib_output_path: resources/js/lib

The file extensions follow your type-bridge.output_format (ts by default).

Generate Enum Translators

Generate per-enum translator composables/functions that map enum values to translated labels using your configured i18n library.

By default files are written to:

• resources/js/composables/generated (config: enum_translators.translator_output_path)

Dry-run output columns:

• Enum: FQCN of the PHP enum
• Prefix: Translation key prefix that will be used
• In FE generation set: Whether this enum is part of your frontend enums set
• Has translations: Whether any translations exist for that prefix

Only enums that are both in the FE generation set and have translations are eligible for generation.

Global translation engine setup (app.ts/js)

The generated translators call a global engine. You must configure it once during your app bootstrapping by calling configureTranslationEngine.

TypeScript (app.ts / main.ts / app.tsx)

JavaScript (app.js / main.js)

Once configured, any generated translator like useStatusTranslator() will use the global engine automatically:

Using the translator utilities

After publishing the utilities and generating translators, you can translate enum values in the frontend.

Global engine configuration (once at app bootstrap) is required. See “Global translation engine setup” above. You can also use the lightweight wrappers from lib/translators:

Manual configuration using i18next works similarly:

Example: translating a generated enum

If you generated the Status enum and have translations under the Status.* namespace, you can build a translator on the fly:

You can also override the engine for a specific translator call:

Notes and configuration

• Configure your target i18n library via type-bridge.i18n_library (supports i18next and vue-i18n).
• Control where generated translator files and utilities are written via enum_translators.* keys in config/type-bridge.php:
  • translator_output_path
  • utils_composables_output_path / utils_composables_import_path
  • utils_lib_output_path / utils_lib_import_path

• The generators respect type-bridge.output_format for TS/JS.

• JavaScript (resources/js/lang/generated/en.js)

• JSON (resources/js/lang/generated/en.json)

GenerateEnum Attribute Options

The #[GenerateEnum] attribute accepts the following options:

• requiresComments (bool): Include PHPDoc comments in generated output

License

MIT