TypeScript export

Keep your frontend and backend in sync – define your types once in PHP and let PHP autodoc generate the matching TypeScript types automatically.

PHP autodoc supports exporting enums, classes, PHPStan type aliases, request/response structures and even custom PHPDoc type expressions as TypeScript types. PHP autodoc-laravel extends this functionality by offering support for Laravel models and other Laravel-specific structures that need custom handling.

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

For Laravel:

php artisan autodoc:ts-sync

For other PHP projects:

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

Optionally, you can add additional parameter to any of the commands above to specify the directory of your TypeScript code. If omitted, PHP autodoc will look for it in your autodoc config file under typescript.working_directory.

Examples

Example 1 - Enum

Consider the following PHP enum:

namespace App\Enums;

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

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

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

The ts-sync 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.

Example 2 - Response structure

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

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

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

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

Example 3 - Request structure with extra parameter in separate 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.

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

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

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

Available annotations

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

1. omit – Remove one or multiple keys from response structure.
   Example: @autodoc App\User {omit: 'created_at'|'updated_at'}
2. only – Export only the specified key(s).
   Example: @autodoc App\User {only: 'id'|'name'}
3. 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'}
4. with – Append additional properties to the exported type (or override existing properties).
   Example: @autodoc App\Planet {with: object{ radius: float }}
5. mode – Custom export mode to use when exporting this type. See more in configuration options section.
   Example: @autodoc App\Planet {mode: 'custom-mode'}
6. 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:

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