Download the PHP package paneon/php-to-typescript-bundle without Composer

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 docblock 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 adding the package to your project with Composer:

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.

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:

Example source file:

Default output file:

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

Output file with null types:

Type Aliases instead of Interfaces

Use the --use-type option to generate TypeScript type aliases instead of interface declarations. This will also change the output file extension from .d.ts to .ts:

Output with --use-type:

Export Declarations

Use the --export option to add the export keyword before declarations:

Output with --export:

You can combine options:

Output with --export --use-type:

Import Resolution

When using the --export option, the generator automatically adds import statements for referenced types. This enables proper TypeScript module resolution between generated files.

For example, if you have a User class that references an Address class:

Output with --export (multi-file mode):

The import paths are automatically calculated based on the relative directory structure of the generated files.

Single File Mode

Instead of generating individual files for each class/enum, you can output all TypeScript types into a single file using the --single-file option:

In single file mode:

• All types are concatenated into a single output file
• No import statements are generated (all types are in the same file)
• Directory structure is not preserved

Output with --export --single-file:

Enum Support

PHP 8.1+ enums with the #[TypeScript] attribute are automatically processed alongside classes:

Default enum output:

With --enum-union-type option:

Use --enum-union-type to output enums as string literal union types:

Bundle configuration (php_to_typescript)

Create (or update) config/packages/php_to_typescript.yaml:

Understanding interfaces vs directories

Both options allow you to process external code (e.g., vendor packages), but they work differently:

interfaces - Individual Files

Use when you need to convert specific single files.

Configuration (map syntax):

Configuration (list syntax):

Behavior:

• Processes exactly one file per entry
• Always converts the file (doesn't require #[TypeScript] attribute)
• Useful for external/vendor code you cannot modify
• Only has output option (relative to outputDirectory)

directories - Recursive Directory Scanning

Use when you need to convert all classes in a directory.

Configuration (map syntax):

Configuration (list syntax):

Behavior:

• Recursively scans all .php files in the directory
• Preserves directory structure in output
• Has requireAnnotation option:
  • false (default) - Converts all PHP classes/enums found
  • true - Only converts files with #[TypeScript] attribute
• Useful for processing entire packages or modules

When to use each:

• interfaces: You know the exact file and want to convert it (e.g., a specific DTO class)
• directories: You want to convert all classes in a package/directory (e.g., all DTOs from a vendor package)

Note: Both map and list syntaxes are supported and produce identical results. Use whichever format you find more readable.

Example: Full configuration

Here's a complete example using %kernel.project_dir% and single file mode:

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.

Options for generate-single

• --nullable: Include null types in output
• --use-type: Generate type alias instead of interface
• --export: Add export keyword before declaration
• --enum-union-type: Output enums as union types

The command automatically detects whether the file contains a class or enum and processes it accordingly.

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