Download the PHP package oi-lab/oi-laravel-ts without Composer

OI Laravel TypeScript Generator

A Laravel package that automatically generates TypeScript interfaces from your Eloquent models, complete with relationships, custom casts, and DataObjects support.

Features

• Automatic Interface Generation: Converts Eloquent models to TypeScript interfaces
• Relationship Support: Handles all Laravel relationship types (HasOne, HasMany, BelongsTo, etc.)
• Custom Casts: Supports Laravel custom casts and automatically detects DataObjects
• DTO Support: Emits interfaces for spatie/laravel-data style DTOs (no dependency required), with enum literal unions and nested DTOs
• PHPDoc Support: Reads PHPDoc annotations for complex types
• Watch Mode: Monitor your models directory and regenerate on changes
• Namespace Filters: Exclude third-party models entirely, or promote them to extension interfaces
• Smart Primary Key Types: UUID / ULID keys are typed as string, integer keys as number
• Configurable: Extensive configuration options for customization
• JSON-LD Support: Optional support for JSON-LD data structures

Architecture

This package uses a modular architecture with clear separation of concerns, organized in two main pipelines:

Pipeline 1: Eloquent Analysis

• Eloquent: Facade for model analysis and schema generation
• ModelDiscovery: Discovers all Eloquent models in the application
• TypeExtractor: Extracts type information from models
• CastTypeResolver: Resolves custom Laravel casts to TypeScript types
• RelationshipResolver: Detects and extracts relationship metadata
• DataObjectAnalyzer: Analyzes PHP DataObject classes
• PhpToTypeScriptConverter: Converts PHP types to TypeScript
• SchemaBuilder: Orchestrates schema building for all models

Pipeline 2: TypeScript Generation

• Convert: Main orchestrator coordinating the conversion process
• TypeScriptTypeConverter: Handles schema to TypeScript type conversion
• DataObjectProcessor: Processes PHP DataObjects and generates their interfaces
• DataClassResolver / DataClassAnalyzer / DataClassProcessor: Discover, analyze and emit spatie/laravel-data style DTOs
• ModelInterfaceGenerator: Generates TypeScript interfaces for Laravel models
• ImportManager: Manages TypeScript import statements
• JsonLdGenerator: Generates JSON-LD support interfaces

For detailed architecture documentation, see ARCHITECTURE.md.

Requirements

• PHP 8.2+
• Laravel 11.0+, 12.0+, or 13.0+

Installation

Local Development

For local development, add this to your main project's composer.json:

Then:

Configuration

Publish the configuration file:

This creates config/oi-laravel-ts.php with the following options:

Usage

Basic Generation

Generate TypeScript interfaces from your models:

This will scan all models in app/Models and generate a TypeScript file at the configured output path.

Watch Mode

Automatically regenerate when models change:

Example Output

Given a Laravel model:

The package generates:

Advanced Features

Custom Properties

Add properties that aren't in your database schema:

DataObject Support

The package automatically detects and converts custom DataObjects:

DTO Support (spatie/laravel-data)

Register the namespaces holding your Data Transfer Objects and every DTO is emitted as an I{ClassName} interface. Detection is structural — no dependency on spatie/laravel-data is required:

Property names are kept verbatim (camelCase), backed enums become literal unions, nested DTOs become I{Name}, and typed arrays declared via a property @var Foo[] annotation become IFoo[].

The interface describes the JSON the DTO produces, so ? and | null mean different things: ? marks a key that may be absent (an Optional / Lazy property), | null a key that is always present but may hold null. A default value makes nothing optional. See data_nullable_style to fall back to the legacy rendering.

By default DTO interfaces coexist with the Eloquent model interfaces. To make a DTO the single source of truth for its model — suppressing the model's own I{Model} interface — enable data_replaces_model. The model is inferred from the DTO's fromModel() factory, or set explicitly via data_for_model:

Note: with data_replaces_model enabled, a relationship on another model that points to a replaced model will reference an interface that is no longer generated.

Discriminated Unions

A DTO whose one property decides the type of another — a block whose template_key decides its props — can be emitted as a discriminated union, so TypeScript narrows the second when you test the first:

I{X}{Property}Map types a registry keyed on the discriminant: const renderers: { [K in keyof IBlockDataPropsMap]: Renderer<IBlockDataPropsMap[K]> }.

Model Attributes From the Database

With use_database_schema (default), a model's interface lists every column of its table except hidden ones, typed from the cast or the column, and nullable columns render as col?: T | null. Enum casts become literal unions, and Attribute accessors in $appends are typed from their @return Attribute<TGet, TSet> annotation. Generation still works without a database: the model's $fillable is used instead.

Type Aliases Instead of Interfaces

An interface has no implicit index signature, so IFoo is not assignable to Record<string, unknown> — which Inertia's useForm / useHttp require of their data. Set 'declaration_style' => 'type' to emit export type IFoo = {...}; and pass generated shapes to form helpers as they are.

Namespace Filters

Exclude third-party or package models from the schema entirely:

Models in these namespaces are dropped — including when reached through a relationship — and any relationship field pointing to them is stripped from other interfaces.

Alternatively, turn package model variants into extension interfaces:

For each extended model whose short name matches a base model in the schema, the generator emits:

UUID / ULID Primary Keys

Primary key types are resolved automatically. Models using HasUuids, HasUlids, or declaring $keyType = 'string' generate id: string instead of id: number:

Import External Types

Reference external TypeScript types:

Generates:

Examples

Complete Workflow

1. Define your models with relationships and casts
2. Configure custom properties if needed

3. Run the generator:

4. Use the generated interfaces in your TypeScript code:

Integration with Inertia.js

Testing

This package includes comprehensive test coverage with 142 tests and 344 assertions.

Run Tests

Test Coverage

• ✅ Type conversion (PHP → TypeScript)
• ✅ Model analysis and schema building
• ✅ Relationship detection (HasMany, BelongsTo, etc.)
• ✅ Custom cast resolution
• ✅ DataObject handling
• ✅ DTO (spatie/laravel-data) generation, enums and nested DTOs
• ✅ TypeScript interface generation
• ✅ Namespace exclusion and extension interfaces
• ✅ UUID / ULID primary key type resolution
• ✅ Integration tests for full pipeline

For detailed testing documentation, see TESTING.md.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

When contributing:

1. Write tests for new features
2. Ensure all tests pass: vendor/bin/pest
3. Follow existing code style
4. Update documentation as needed

License

This package is open-source software licensed under the MIT license.

Credits

Olivier Lacombe - Creator and maintainer

Olivier is a Product & Technology Director based in Montpellier, France, with over 20 years of experience innovating in UX/UI and emerging technologies. He specializes in guiding enterprises toward cutting-edge digital solutions, combining user-centered design with continuous optimization and artificial intelligence integration.

Projects & Resources:

• OI Dev Docs - Documentation for all Open Source OI Lab packages
• OnAI - Training courses and masterclasses on generative AI for businesses
• Promptr - Prompt engineering Management Platform

Support

For support, please open an issue on the GitHub repository.