Typing properties | typescript-transformer | Spatie

 SPATIE

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

spatie.be/open-source

  [Docs](https://spatie.be/docs)  [Typescript-transformer](https://spatie.be/docs/typescript-transformer/v1)  Dtos  Typing properties

 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/v1/introduction)
- [ Postcardware ](https://spatie.be/docs/typescript-transformer/v1/postcardware)
- [ Installation ](https://spatie.be/docs/typescript-transformer/v1/installation)
- [ Under the hood ](https://spatie.be/docs/typescript-transformer/v1/under-the-hood)
- [ Questions & issues ](https://spatie.be/docs/typescript-transformer/v1/questions-and-issues)
- [ Changelog ](https://spatie.be/docs/typescript-transformer/v1/changelog)
- [ About us ](https://spatie.be/docs/typescript-transformer/v1/about-us)

Usage
-----

- [ General overview ](https://spatie.be/docs/typescript-transformer/v1/usage/general-overview)
- [ Getting started ](https://spatie.be/docs/typescript-transformer/v1/usage/getting-started)
- [ Using transformers ](https://spatie.be/docs/typescript-transformer/v1/usage/using-transformers)
- [ Customizing the output using annotations ](https://spatie.be/docs/typescript-transformer/v1/usage/annotations)
- [ Selecting classes using collectors ](https://spatie.be/docs/typescript-transformer/v1/usage/selecting-classes-using-collectors)

Dto's
-----

- [ Transforming DTOs ](https://spatie.be/docs/typescript-transformer/v1/dtos/transforming-dtos)
- [ Typing properties ](https://spatie.be/docs/typescript-transformer/v1/dtos/typing-properties)
- [ Changing types using class property processors ](https://spatie.be/docs/typescript-transformer/v1/dtos/changing-types-with-class-property-processors)

Laravel
-------

- [ Installation and setup ](https://spatie.be/docs/typescript-transformer/v1/laravel/installation-and-setup)
- [ Executing the transform command ](https://spatie.be/docs/typescript-transformer/v1/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                                                                                                                                                                                                                                    `

Typing properties
=================

###  On this page

1. [ Using PHP's built-in typed properties ](#content-using-phps-built-in-typed-properties)
2. [ Using docblocks ](#content-using-docblocks)
3. [ Combining regular types and docblocks ](#content-combining-regular-types-and-docblocks)

Let's take a look at how we can type individual properties of a PHP class.

Using PHP's built-in typed properties
---------------------------------------------------------------------------------------------------------------------------------------------------------------------

Since PHP 7.4 it's possible to use typed properties in a class. This package makes these types an A-class citizen.

```
class Dto
{
    public string $string;

    public int $integer;

    public float $float;

    public bool $bool;

    public array $array;
}
```

It is also possible to use nullable types:

```
class Dto
{
    public ?string $string;
}
```

Or use other types that can be replaced:

```
class Dto
{
    public DateTime $datetime;
}
```

Using docblocks
-----------------------------------------------------------------------------------------------------

You can also use docblocks to type properties. A more detailed overview of this can be found [here](https://docs.phpdoc.org/latest/guides/types.html). While PHP's built-in typed properties are great, docblocks allow for a bit more flexibility:

```
class Dto
{
    /** @var string */
    public $string;

    /** @var int */
    public $integer;

    /** @var float */
    public $float;

    /** @var bool */
    public $bool;

    /** @var array */
    public $array;

    /** @var array|string */
    public $arrayThatMightBeAString;
}
```

It is also possible to use nullable types in docblocks:

```
class Dto
{
    /** @var ?string */
    public $string;
}
```

And add types for your (custom) objects:

```
class Dto
{
    /** @var \DateTime */
    public $dateTime;
}
```

Note: always use the fully qualified class name (FCCN). At this moment the package cannot determine imported classes used in a docblock:

```
use App\DataTransferObjects\UserData;

class Dto
{
    /** @var \App\DataTransferObjects\UserData */
    public $userData; // FCCN: this will work

    /** @var UserData */
    public $secondUserData; // Won't work, class import is not detected
}
```

It's also possible to add compound types:

```
class Dto
{
    /** @var string|int|bool|null */
    public $compound;
}
```

Or these special PHP specific types:

```
class Dto
{
    /** @var mixed */
    public $mixed; // transforms to `any`

    /** @var scalar */
    public $scalar; // transforms to `string|number|boolean`

    /** @var void */
    public $void; // transforms to `never`
}
```

You can even reference the object's own type:

```
class Dto
{
    /** @var self */
    public $self;

    /** @var static */
    public $static;

    /** @var $this */
    public $void;
}
```

These will all transform to a `Dto` TypeScript type.

### Transforming arrays

Arrays in PHP and TypeScript (JavaScript) are completely different concepts. This poses a couple of problems we'll address. A PHP array is a multi-use storage/memory structure. In TypeScript, a PHP array can be represented both as an `Array` and as an `Object` with specified keys.

Depending on how your annotations are written the package will output either an `Array` or `Object`. Let's have a look at some examples that will transform into an `Array` type:

```
class Dto
{
    /** @var \DateTime[] */
    public $array;

    /** @var array */
    public $another_array;

    /** @var array */
    public $you_propably_wont_write_this;
}
```

Typing objects can be done as such:

```
class Dto
{
    /** @var array */
    public $object_with_string_keys;

    /** @var array */
    public $object_with_int_keys;
}
```

Combining regular types and docblocks
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------

It is possible and recommended combine regular type with docblock annotations for more specific typing. Let's have a look:

```
class Dto
{
    /** @var string[] */
    public array $array;
}
```

The package knows `string[]` is a more specific version of the `array` type and will internally remove the redundant `Array` type. The outputted type definition looks like this:

```
array: Array
```