TypeScript export - PHP autodoc

PHP autodoc generates TypeScript types for PHP classes, enums, PHPStan aliases, PHPDoc expressions, and API request and response bodies. autodoc-laravel also supports Laravel models and other framework-specific types.

To use this feature, you can add @autodoc annotations to your TypeScript code (see examples below) and run one of the following commands:

For Laravel:

php artisan autodoc:ts

For other PHP projects:

vendor/bin/autodoc ts --config="/path/to/your/autodoc/config.php"

You can pass the TypeScript source directory as an extra argument. If you omit it, autodoc uses typescript.working_directory from your config.

typescript.export_http_requests_and_responses exports selected HTTP request and response types.

Examples

Exporting an enum

Consider the following PHP enum:

namespace App\Enums;

enum SomeEnum: int {
    case A = 1;
    case B = 2;
    case C = 3;
}

In your typescript file add @autodoc tag with enum name.

/**
 * @autodoc App\Enums\SomeEnum
 */

Run autodoc ts command.

/**
 * @autodoc App\Enums\SomeEnum
 */
enum SomeEnum {
    A = 1,
    B = 2,
    C = 3,
}

The autodoc ts command reads all @autodoc tags in your TypeScript code and creates/updates the matching types. If the type definition already exists, it will be updated.

Exporting a response type

Consider the following PHP return statement from the GET /api/user route handler:

return [
    'id' => $user->id,
    'name' => $user->name,
    'email' => $user->email,
];

In your typescript file add @autodoc tag.

/**
 * @autodoc GET /api/user
 */
interface UserResponse {
    // empty or outdated data
}

Run autodoc ts command.

/**
 * @autodoc GET /api/user
 */
interface UserResponse {
    id: number
    name: string
    email: string
}

Exporting a modified request type to another file

Consider a POST /api/test endpoint with known message parameter. You want to export the request body type and add an additional token parameter to your exported type.

In your typescript file add @autodoc tag.

/**
 * @autodoc POST /api/test request {
 *     mode: 'separate_file',
 *     with: array{
 *         token: string,
 *     },
 * }
 */

This example uses a custom separate_file mode which can be defined as follows in your autodoc config file under typescript.modes:
'separate_file' => [
    'save_types_in_single_file' => '@/types.ts',
],
However if you have save_types_in_single_file setting enabled globally, you don't need a custom mode for this functionality.

Run autodoc ts command.

/**
 * @autodoc POST /api/test request {
 *     mode: 'separate_file',
 *     with: array{
 *         token: string,
 *     },
 * }
 */
type TestRequest = import('@/types.ts').TestRequest

In types.ts file you will find the following type:

export type TestRequest = {
    message: string
    token: string
}

Available annotations

@autodoc {class-name} {options?}

Exports a class or enum.
Example: @autodoc Namespace\ClassName

@autodoc {http-method} {route} {http-status?} {options?}

Exports response structure of a route.
If a route has different responses per status code, you can specify which one to export.
Example: @autodoc POST /api/message 201

@autodoc {http-method} {route} request {options?}

Exports request body structure of the route.
Example: @autodoc POST /api/message request

@autodoc {custom-phpdoc-type-expression} {options?}

Exports the matching TypeScript schema of your PHPDoc type expression.
Example: @autodoc object{ name: ?string }

Optionally you may include additional options for each separate @autodoc tag in this structure:

omit – Remove one or multiple keys from response structure.
Example: @autodoc App\User {omit: 'created_at'|'updated_at'}
only – Export only the specified key(s).
Example: @autodoc App\User {only: 'id'|'name'}
from – Specify a class name as the context to export from - useful for exporting PHPStan type aliases that are defined/imported in the specified class.
Example: @autodoc UserAddress {from: 'App\User'}
with – Append additional properties to the exported type (or override existing properties).
Example: @autodoc App\Planet {with: object{ radius: float }}
mode – Custom export mode to use when exporting this type. See more in configuration options section.
Example: @autodoc App\Planet {mode: 'custom-mode'}
as – Specify a custom name for the exported type when exporting it to a separate file. Will not work for inline exports where the type is exported right after the `@autodoc` tag because there it will use the existing type name.
Example: @autodoc GET /api/appointments { mode: 'separate_file', as: 'AppointmentList' }

Configuration options

In your autodoc configuration file, you have a typescript section with these configuration options available:

Option	Description	Default
working_directory	Specify a full path to a directory of your TypeScript code.	null
file_extensions	Specify file extensions to look for in the working directory.	['ts', 'tsx', 'vue']
indent	Specify the indentation to use when exporting TypeScript types.	4 spaces
string_quote	Specify the string quote to use when exporting TypeScript types.	'
add_semicolons	Specify whether to add semicolons when exporting TypeScript types.	false
show_values_for_scalar_types	When enabled, will attempt to read possible values for returned scalar types. It is not guaranteed that all possible values will be detected, so depending on your project you might want to disable this.	true
save_types_in_single_file	Specify a full path to a file where all TypeScript types will be saved. Set to `null` to export types right after their `@autodoc` comments.	null
modes	Custom modes that can be applied to specific TypeScript exports. Accepts an associative array where keys are mode names and values are mode options. Supported options: `save_types_in_single_file`, `show_values_for_scalar_types`, `indent`, `string_quote`, `add_semicolons`.	[]
path_prefixes	Path prefixes from your TypeScript project. Used when generating `import(path).Type` statements when `save_types_in_single_file` is enabled. Specify a function that returns an `iterable<string, string>`.	A function that loads path prefixes from tsconfig.json

You may also customize the output for specific classes/enums using TypeScript export extensions.