README.md

PHP Classes to TypeScript Bundle

A Symfony bundle that adds a command to extract TypeScript interface from PHP classes. Based on the example from Martin Vseticka this bundle uses the PHP-Parser library and annotations.

TypeScript is a superscript of JavaScript that adds strong typing and other features on top of JS. Automatically generated classes can be useful, for example when using a simple JSON API to communicate to a JavaScript client. This way you can get typing for your API responses in an easy way.

Feel free to build on this or use as inspiration to build something completely different.

Installation

As a Symfony bundle you'll need to start by add the package to your project with composer:

$ composer req paneon/php-to-typescript-bundle

Usage of the Command 'typescript:generate'

The purpose of the generate Command is to create TypeScript definitions for all Classes in your source root which are under your immediate control (i.e. You can change their source). It will only affect classes which have the @TypeScriptInterface-Annotation.

$ php bin/console typescript:generate

The command scans directories recursively for all .php files. It will only generate Type Definitions (interfaces) for files with the appropriate annotation. The default parameters will scan for alle PHP Classes inside "src/" and output them as TypeScript Interfaces into "assets/js/interfaces/" while keeping the relative directory structure.

Examples:

Source File	Output File
src/Model/Person.php	assets/js/interfaces/Model/Person.d.ts
src/Example.php	assets/js/interfaces/Example.d.ts

Example source file:

<?php

/**
 * @TypeScriptInterface
 */
class Example
{
    /**
     * @var string
     */
    public $firstName;

    /**
     * @var string|null
     */
    public $middleName;

    /**
     * @var string
     */
    public $lastName;

    /**
     * @var int|null
     */
    public $age;
    
    /** @var Contact[] */
    public $contacts;
}

Default output file:

interface Example {
    firstName: string;
    middleName: string;
    lastName: string;
    age: number;
    contacts: Contact[];
}

Null-aware Types

Since TypeScript 2.0 Null and optional/undefined types are supported. In the generator bundle, this is an optional feature and null types will be removed by default. To include nullable types use

$ php bin/console typescript:generate --nullable

Output file with null types:

interface Example {
    firstName: string;
    middleName: string|null;
    lastName: string;
    age: number;
    contacts: Contact[];
}

Usage of the Command 'typescript:generate-single'

The purpose of the generate Command is to create TypeScript definitions for Classes from external packages where you can't add the TypeScriptInterface-Annotation but their classes are for example used in your classes. It will only affect a single file and needs a specific target location if you don't want it directly inside assets/js/interfaces.

$ php bin/console typescript:generate-single vendor/some-package/src/SomeDir/DTO/SomeoneElsesClass.php assets/js/external/some-package/

It's recommended to trigger the generation of interfaces after composer update/install.