spatie/typescript-transformer

The spatie/typescript-transformer package converts PHP structures like classes and enums into TypeScript types.

To mark a class for transformation, use the #[TypeScript] attribute. The transformer maps PHP types to their TypeScript equivalents (e.g., int to number, nullable types to unions with null).

For string-backed enums, the transformer generates a TypeScript union type of the enum values.

#[TypeScript]
class User
{
    public int $id;
    public string $name;
    public ?string $address;
}

Converts to:

export type User = {
    id: number;
    name: string;
    address: string | null;
}

And enums:

enum Languages: string
{
    case TYPESCRIPT = 'typescript';
    case PHP = 'php';
}

Converts to:

export type Languages = 'typescript' | 'php';

The extension automatically picks up all public properties from your Data classes and resolves their types. This includes support for complex types defined via docblocks. A standard Data class with public properties will be converted into a corresponding TypeScript type where PHP types (like string, int, ?string) are mapped to TypeScript types (like string, number, string | null).

use Spatie\LaravelData\Data;

class UserData extends Data
{
    public function __construct(
        public string $name,
        public string $email,
        public int $age,
        public ?string $avatar,
    ) {
    }
}

Generates:

export type UserData = {
    name: string;
    email: string;
    age: number;
    avatar: string | null;
};

Properties marked with the #[Hidden] attribute (from either the spatie/typescript-transformer or spatie/laravel-data packages) will be excluded from the generated TypeScript type.

use Spatie\LaravelData\Data;
use Spatie\LaravelData\Attributes\Hidden;

class UserData extends Data
{
    public function __construct(
        public string $name,
        #[Hidden]
        public string $password,
    ) {
    }
}

Generates:

export type UserData = {
    name: string;
};

The extension respects Laravel Data's #[MapOutputName] and #[MapName] attributes. If a property has a mapped output name, the TypeScript property will use that mapped name instead of the PHP property name.

use Spatie\LaravelData\Data;
use Spatie\LaravelData\Attributes\MapOutputName;

class UserData extends Data
{
    public function __construct(
        #[MapOutputName('full_name')]
        public string $name,
        public string $email,
    ) {
    }
}

Generates:

export type UserData = {
    full_name: string;
    email: string;
};

The TypeScript transformer follows a five-step pipeline to convert PHP code into TypeScript types:

1. Search: It scans your application for PHP classes.
2. Reflection: It creates a ReflectionClass for every discovered class.
3. Transformation: It passes these ReflectionClass instances through a list of registered Transformers. Each transformer attempts to convert the class into a TypeScript type.
4. Filtering: If a transformer successfully processes a class, it is added to a list for writing; otherwise, the class is ignored.
5. Writing: The collected list of transformed types is written to TypeScript files using a configured Writer.

Transformers are executed in the order they are registered. If one transformer cannot handle a specific class, the framework moves to the next one in the list.

The package uses a tree of TypeScript nodes to represent TypeScript types internally. These nodes can be composed to build complex type structures, such as aliases, objects, unions, and primitives. You can use these nodes to programmatically define types that the transformer will then output as valid TypeScript code.

All available nodes are located in the Spatie\TypeScriptTransformer\TypeScript namespace.

use Spatie\TypeScriptTransformer\TypeScriptNodes;

new TypeScriptAlias(
    new TypeScriptIdentifier('User'),
    new TypeScriptObject([
        new TypeScriptProperty('id', new TypeScriptNumber()),
        new TypeScriptProperty('name', new TypeScriptString()),
        new TypeScriptProperty('address', new TypeScriptUnion([
            new TypeScriptString(),
            new TypeScriptNull(),
        ])),
    ]),
);

The TypeScript transformer uses a PhpNodeCollection to maintain a persistent registry of PhpClassNode objects. These nodes contain PHP reflection data for classes, interfaces, and enums, keyed by their Fully Qualified Class Name (FQCN).

This collection is essential for maintaining state during watch mode: when a PHP file changes, the PhpNodeCollection automatically updates the corresponding PhpClassNode with fresh reflection data.

Important Lifecycle Note: The collection only tracks classes that have been either:

1. Transformed by a transformer.
2. Manually added by a provider.

Because of this, the collection may be empty during the very first run of a provider if the transformers have not yet executed.

Request types are detected by looking for a method parameter that is a Data object (from spatie/laravel-data). The first matching parameter becomes the Request type.

Example PHP signature:

public function store(StorePostData $data): PostData
{
    // ...
}

If no Data object parameter is found, the request type defaults to object. Support for Laravel FormRequest classes is planned for a future release.