README

Downloadable developer software from Diagonal Software Corp. for application development with Laravel, PHP enums, and TypeScript.

Diagonal TS Enum Generator is a downloadable computer software development tool distributed as the diagonal/ts-enum-generator Composer package. It generates TypeScript definitions from PHP enums so backend and frontend applications can share typed enum contracts.

The generated TypeScript can include type definitions, runtime objects, and utility functions for use in application development, deployment, and management workflows.

Package details

Provider: Diagonal Software Corp.
Software name: Diagonal TS Enum Generator
Package: diagonal/ts-enum-generator
Distribution: Downloadable Composer package via Packagist
Use case: Computer system and application development with Laravel, PHP, and TypeScript

Installation

You can install the package via composer:

composer require diagonal/ts-enum-generator

You can publish the config file with:

php artisan vendor:publish --tag="ts-enum-generator-config"

This is the contents of the published config file:

return [
    'default_source_dir' => 'app/Enums',
    'default_destination_dir' => 'resources/ts/enums',
    
    'output' => [
        'use_namespaces' => true,
        'single_file' => true,
        'output_filename' => 'enums.ts',
        'namespace_separator' => '.',
        'include_comments' => true,
        'generate_runtime_objects' => true,
        'generate_per_type_utils' => true,
        'generate_generic_utils' => true,
        'types_only' => false,
    ],
    
    'namespace' => [
        'root_namespace' => null,
        'strip_namespace_prefix' => null,
        'namespace_suffix' => 'Enums',
    ],
];

Usage

Create PHP enums in your Laravel application:

<?php

namespace App\Enums;

enum UserRole: string
{
    case ADMIN = 'admin';
    case USER = 'user';
    case MODERATOR = 'moderator';
}

<?php

namespace App\Enums;

enum Status
{
    case PENDING;
    case APPROVED;
    case REJECTED;
}

Generate TypeScript definitions:

php artisan ts-enums:generate

This will create a TypeScript file with the following content:

declare namespace App.Enums {
  type UserRole = 'admin' | 'user' | 'moderator';

  const UserRole: {
    readonly ADMIN: 'admin';
    readonly USER: 'user';
    readonly MODERATOR: 'moderator';
  };

  const UserRoleUtils: {
    values: UserRole[];
    keys: (keyof typeof UserRole)[];
    entries: [keyof typeof UserRole, UserRole][];
    isValid: (value: any) => value is UserRole;
    fromKey: (key: keyof typeof UserRole) => UserRole;
  };

  type Status = 'PENDING' | 'APPROVED' | 'REJECTED';

  const Status: {
    readonly PENDING: 'PENDING';
    readonly APPROVED: 'APPROVED';
    readonly REJECTED: 'REJECTED';
  };

  const StatusUtils: {
    values: Status[];
    keys: (keyof typeof Status)[];
    entries: [keyof typeof Status, Status][];
    isValid: (value: any) => value is Status;
    fromKey: (key: keyof typeof Status) => Status;
  };
}

Use the generated TypeScript in your frontend:

// Type checking
function setUserRole(role: App.Enums.UserRole) {
    // TypeScript knows role can only be 'admin' | 'user' | 'moderator'
}

// Runtime usage
const adminRole = App.Enums.UserRole.ADMIN; // 'admin'

// Validation
if (App.Enums.UserRoleUtils.isValid(someValue)) {
    // someValue is now typed as UserRole
}

// Get all values
const allRoles = App.Enums.UserRoleUtils.values; // ['admin', 'user', 'moderator']

Command options

The ts-enums:generate command accepts the following options:

php artisan ts-enums:generate --source=app/Models/Enums --destination=resources/js/types

--source: Override the source directory (default: configured in config file)
--destination: Override the destination directory (default: configured in config file)

Configuration options

Output format

Control how the TypeScript is generated:

'output' => [
    'use_namespaces' => false, // Use export syntax instead of declare namespace
    'single_file' => false,    // Generate separate files for each enum
    'types_only' => true,      // Only generate type definitions (no runtime objects)
],

Namespace handling

Customize how PHP namespaces are converted to TypeScript:

'namespace' => [
    'strip_namespace_prefix' => 'App\\',   // Remove App\ from namespaces
    'namespace_suffix' => 'Types',         // Add Types suffix
],

With these settings, App\Enums\UserRole becomes Enums.Types.UserRole.

Runtime utilities

Choose what utility functions to generate:

'output' => [
    'generate_runtime_objects' => true,   // Generate const objects (UserRole.ADMIN)
    'generate_per_type_utils' => true,    // Generate UserRoleUtils.isValid()
    'generate_generic_utils' => true,     // Generate EnumUtils.isValid()
],

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

diagonal / laravel-ts-enum-generator

Maintainers

Package info

Fund package maintenance!

Statistics

Security