Getting started | typescript-transformer | Spatie

 SPATIE

  TypeScript Transformer
=========================

spatie.be/open-source

  [Docs](https://spatie.be/docs)  [Typescript-transformer](https://spatie.be/docs/typescript-transformer/v2)  Transformers  Getting started

 Version   v3   v2   v1

 Other versions for crawler [v3](https://spatie.be/docs/typescript-transformer/v3) [v2](https://spatie.be/docs/typescript-transformer/v2) [v1](https://spatie.be/docs/typescript-transformer/v1)

- [ Introduction ](https://spatie.be/docs/typescript-transformer/v2/introduction)
- [ Postcardware ](https://spatie.be/docs/typescript-transformer/v2/postcardware)
- [ Installation ](https://spatie.be/docs/typescript-transformer/v2/installation)
- [ Under the hood ](https://spatie.be/docs/typescript-transformer/v2/under-the-hood)
- [ Questions & issues ](https://spatie.be/docs/typescript-transformer/v2/questions-and-issues)
- [ Changelog ](https://spatie.be/docs/typescript-transformer/v2/changelog)
- [ About us ](https://spatie.be/docs/typescript-transformer/v2/about-us)

Usage
-----

- [ General overview ](https://spatie.be/docs/typescript-transformer/v2/usage/general-overview)
- [ Getting started ](https://spatie.be/docs/typescript-transformer/v2/usage/getting-started)
- [ Describing types ](https://spatie.be/docs/typescript-transformer/v2/usage/annotations)
- [ Using transformers ](https://spatie.be/docs/typescript-transformer/v2/usage/using-transformers)
- [ Collectors ](https://spatie.be/docs/typescript-transformer/v2/usage/selecting-classes-using-collectors)
- [ Writers ](https://spatie.be/docs/typescript-transformer/v2/usage/writers)
- [ Formatters ](https://spatie.be/docs/typescript-transformer/v2/usage/formatters)

Writing transformers
--------------------

- [ Getting started ](https://spatie.be/docs/typescript-transformer/v2/transformers/getting-started)
- [ Type reflectors ](https://spatie.be/docs/typescript-transformer/v2/transformers/type-reflectors)
- [ Type processors ](https://spatie.be/docs/typescript-transformer/v2/transformers/type-processors)

Transforming PHP classes
------------------------

- [ Typing properties ](https://spatie.be/docs/typescript-transformer/v2/dtos/typing-properties)
- [ Customization ](https://spatie.be/docs/typescript-transformer/v2/dtos/transforming-dtos)

Laravel
-------

- [ Installation and setup ](https://spatie.be/docs/typescript-transformer/v2/laravel/installation-and-setup)
- [ Executing the transform command ](https://spatie.be/docs/typescript-transformer/v2/laravel/executing-the-transform-command)

      You are viewing the documentation for **an older version** of this package. You can check the version you are using with the following command:

 `                                    composer show spatie/typescript-transformer                                                                                                                                                                                                                                    `

Getting started
===============

A transformer is a class that implements the `Transformer` interface:

```
use Spatie\TypeScriptTransformer\Transformers\Transformer;

class EnumTransformer implements Transformer
{
    public function transform(ReflectionClass $class, string $name): ?TransformedType
    {
    }
}
```

In the `transform` method, you should transform a PHP `ReflectionClass` into a `TransformedType`. This `TransformedType` will include the TypeScript representation of the PHP class and some extra information.

When a transformer cannot transform the given `ReflectionClass` then the method should return `null`, indicating that the transformer is not suitable for the type.

### Creating transformed types

A `TransformedType` always has three properties: the `ReflectionClass` of the type you're transforming, the name of the type and, of course, the transformed TypeScript code:

```
TransformedType::create(
    ReflectionClass $class, // The reflection class
    string $name, // The name of the Type
    string $transformed // The TypeScript representation of the class
);
```

For types that depend on other types a fourth argument can be passed to the `create` method:

```
TransformedType::create(
    ReflectionClass $class,
    string $name,
    string $transformed,
    MissingSymbolsCollection $missingSymbols
);
```

A `MissingSymbolsCollection` will contain references to other types. The package will replace these references with correct TypeScript types.

Consider the following class as an example:

```
/** @typescript **/
class User extends DataTransferObject
{
    public string $name;

    public RoleEnum $role;
}
```

As you can see, it has a `RoleEnum` as a property, which looks like this:

```
/** @typescript **/
class RoleEnum extends Enum
{
    const GUEST = 'guest';
    const ADMIN = 'admin';
}
```

When transforming the `User` class we don't have any context or types for the `RoleEnum`. The transformer can register this missing symbols for a property using the `MissingSymbolsCollection` as such:

```
$type = $missingSymbols->add(RoleEnum::class); // Will return {%RoleEnum::class%}
```

The `add` method will return a token that can be used in your transformed type. It's a link between the two types and will later be replaced by the actual type implementation.

When no type was found (for example: because it wasn't converted to TypeScript), the type will default to TypeScript's `any` type.

In the end, the package will produce the following output:

```
export type RoleEnum = 'guest' | 'admin';

export type User = {
    name: string;
    role: RoleEnum;
}
```

#### Inline types

It is also possible to create an inline type. These types are replaced directly in other types. You can read more about inline types [here](/docs/typescript-transformer/v2/usage/annotations#inlining-types).

Inline types can be created like a regular `TransformedType` but they do not need a name:

```
TransformedType::createInline(
    ReflectionClass $class,
    string $transformed
);
```

When required you can also add a `MissingSymbolsCollection`:

```
TransformedType::createInline(
    ReflectionClass $class,
    string $transformed,
    MissingSymbolsCollection $missingSymbols
);
```

When you create a new transformer, don't forget to add it to the list of transformers in your configuration!