Download the PHP package brunoscode/laravel-ts-annotations without Composer

Laravel TS Annotations

Generate TypeScript types from PHP attributes and emit them to .ts files with a single Artisan command — for Laravel apps with a typed frontend.

Keeping PHP and a typed frontend in sync usually means one of two compromises: infer TypeScript from PHP types (and lose union types, template literals, and generics), or route everything through a Swagger/OpenAPI intermediary (indirect and verbose). This package skips both — you attach the TypeScript you want, in PHP, and generate .ts with one command. Three annotation styles give you three levels of control:

• #[TS] — write real TypeScript verbatim when you need unions, templates, or generics
• #[TSType] — auto-infer from PHP property types for simple DTOs and data classes
• #[TSEnum] — auto-generate TypeScript enums from PHP backed or unit enums

Table of Contents

• Requirements
• Installation
• Quick Start
• Usage
• Resources, Collections, and Inertia
• Ordering in the Output File
• File Preservation
• Laravel Boost
• Configuration
• Roadmap
• Testing
• Changelog
• Credits
• Contributing
• License

Requirements

Installation

Publish the config file:

Quick Start

Usage

#[TS] — raw TypeScript

Write any TypeScript verbatim. Use this when you need union types, template literals, generics, or any construct that can't be inferred from PHP types.

Usable on classes and on individual methods. #[TS] is repeatable — stack it as many times as needed.

On controller methods — keeps each type next to the action it describes:

Heredoc indentation: Place the closing TS marker at the same indentation level as the type body. PHP strips that many leading spaces from every line, giving zero-based indentation in the output.

#[TSType] — auto-infer from class properties

Inspects all public non-static properties (including promoted constructor params) via Reflection and maps PHP types to TypeScript. The readonly modifier is preserved.

Only properties declared on the class itself are emitted — properties inherited from a parent class are skipped. Annotate the parent with #[TSType] too if you need its properties in a separate type.

Generates:

PHP → TypeScript type mapping:

Only the exact Carbon/Collection FQCNs above are remapped. A different class named Collection (e.g. your own App\Support\Collection) falls through to the short-name rule and becomes the literal Collection, not unknown[].

Use the optional name parameter to override the TypeScript identifier:

#[TSEnum] — auto-generate from PHP enums

Reads enum cases and their backing values automatically. No body to write.

Targeting a specific output file

All three annotations accept an output parameter:

The key must match one defined in config/ts-annotations.php.

Run the generator

Resources, Collections, and Inertia

Laravel Resources give you explicit control over the shape of data sent to the frontend — they transform Eloquent models rather than leaking raw attributes. Annotating them with #[TS] keeps that contract in sync with your TypeScript automatically.

1. Define the resource shape

Keeping the annotation on the Resource rather than the controller means the type and the transformation logic live together. If you tighten toArray, you update the #[TS] block in the same file.

2. Annotate controller methods for Inertia

The default config injects two generic helpers at the top of every generated file:

Reference them directly in the #[TS] attribute on each controller method that renders an Inertia page:

3. Generated TypeScript

4. Consume in an Inertia component

CollectionResource<T> and PaginatedResource<T> are injected via the imports key in config/ts-annotations.php. Customise them there or add any other shared helpers your app needs.

Ordering in the Output File

Entries follow file-scan order across classes. Within a single class they are emitted in this fixed order:

1. Class-level #[TS] attributes
2. #[TSEnum] (only on enums)
3. #[TSType] (inferred from the class)
4. Method-level #[TS] attributes, sorted by line number

There is no global grouping by attribute type. A #[TSEnum] in a class that is scanned before a #[TS] resource appears first in the output. The result looks grouped only when your scan paths are themselves ordered by kind (e.g. Http, then Enum, then Data) — that grouping comes from scan order, not from an intrinsic sort.

Each entry is preceded by a source comment:

File Preservation

The generator only touches the section between the two marker comments. Everything outside the markers — manual imports, custom types, hand-written utilities — is left untouched on every run.

If a file doesn't exist yet, it is created from scratch. If it exists but has no markers, the generated block is appended at the end.

Laravel Boost

This package ships a Laravel Boost skill. If you use Boost, run:

and select brunoscode/laravel-ts-annotations when prompted. The skill teaches your AI agent how to use #[TS], #[TSType], and #[TSEnum] attributes, run ts:generate, and manage the generated output.

Configuration

Roadmap

Planned, not yet shipped:

• --watch flag for automatic regeneration on file change

Testing

Changelog

Please see CHANGELOG.md for what has changed recently.

Credits

• BrunosCode
• All Contributors

Contributing

Contributions are welcome! Please submit a pull request or open an issue to discuss what you would like to change.

License

The MIT License (MIT). Please see License File for more information.