README

Generate TypeScript Schema validation schemas from your Laravel validation rules. This package supports Laravel FormRequest classes, Spatie Data classes, and custom validation classes through an extensible architecture.

It will generate Zod schema out of the box, but can be extended for different schema generators.

Features

• 🚀 Zero Dependencies - Works with vanilla Laravel
• 📦 Smart Package Detection - Automatically detects and uses installed packages
• 🎯 Multiple Validation Sources - FormRequests, Spatie Data classes, custom extractors
• 🔧 Flexible Configuration - Customize output paths, formats, and integration settings
• 🧩 Highly Extensible - Custom extractors and type handlers with priority system

Installation

composer require romegasoftware/laravel-schema-generator

Ensure Zod v4 is installed

npm install zod

Optional Packages

For additional features, install these optional packages:

# For Spatie Data class support
composer require spatie/laravel-data

# For TypeScript transformer integration
composer require spatie/laravel-typescript-transformer

Configuration

To publish the configuration file, run:

php artisan vendor:publish --provider="RomegaSoftware\LaravelSchemaGenerator\LaravelSchemaGeneratorServiceProvider"

This will create a config/laravel-schema-generator.php file where you can customize output paths, formats, and integration settings.

Generating Separate Files

By default, all schemas are generated into a single TypeScript file. You can configure the package to generate separate files for each schema (e.g., UserSchema.ts, PostSchema.ts) by enabling separate_files in the configuration.

// config/laravel-schema-generator.php

'zod' => [
    'output' => [
        'path' => resource_path('js/types/schemas.ts'), // fallback/default path
        'separate_files' => true,
        // Optional: specify a dedicated directory for separate files
        'directory' => resource_path('js/types/schemas'),
    ],
],

When enabled, the generator will:

1. Create individual .ts files for each schema.
2. Automatically resolve and inject imports for dependent schemas (e.g., if UserSchema references AddressSchema).

Quick Start

1. Add the attribute to your Laravel validation classes:

use RomegaSoftware\LaravelSchemaGenerator\Attributes\ValidationSchema;

#[ValidationSchema]
class CreateUserRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'name' => 'required|string|max:255',
            'email' => 'required|email',
            'age' => 'nullable|integer|min:18',
        ];
    }
}

1. Generate the schemas:

php artisan schema:generate

1. Use in TypeScript:

import { CreateUserRequestSchema } from "@/types/schemas";

const result = CreateUserRequestSchema.safeParse(formData);
if (result.success) {
  // Data is valid
  await api.createUser(result.data);
}

Documentation

For complete documentation, configuration options, advanced features, and examples, visit:

📚 Official Documentation Coming Soon

Custom Schema Overrides

When you need to keep bespoke Laravel validation logic but still describe the TypeScript shape, provide a literal override using the fluent helper. Prefix the snippet with . when you want to append behaviour to the inferred Zod builder instead of replacing it entirely:

use RomegaSoftware\LaravelSchemaGenerator\Support\SchemaRule;

'items' => [
    'required',
    'array',
    SchemaRule::make(
        static function ($attribute, $value, $fail, string $message): void {
            if (collect($value)->sum('qty') < 12) {
                $fail($message);
            }
        }
    )
        ->append(static function (string $encodedMessage): string {
            return <<<ZOD
                .superRefine((items, ctx) => {
                    const total = items.reduce((sum, item) => sum + item.qty, 0);
                    if (total < 12) {
                        ctx.addIssue({
                            code: 'custom',
                            message: {$encodedMessage},
                            path: ['items'],
                        });
                    }
                })
                ZOD;
        })
        ->failWith('You must order at least 12 total units.'),
],

Because the override begins with ., the generator keeps the inferred base (z.array(...)) and simply appends your refinement. The callable passed to append() receives the JSON-encoded message as its first argument (and the raw message as a second argument if you declare it). When you want to replace the builder outright, omit the leading dot and provide the complete Zod expression (for example z.array(z.object({ ... }))).

Prefer dedicated rule objects? Implement SchemaAnnotatedRule and reuse the same fluent API with the provided trait:

use Closure;
use Illuminate\Contracts\Validation\ValidationRule;
use RomegaSoftware\LaravelSchemaGenerator\Concerns\InteractsWithSchemaFragment;
use RomegaSoftware\LaravelSchemaGenerator\Contracts\SchemaAnnotatedRule;

final class TotalOrderItemsRule implements SchemaAnnotatedRule, ValidationRule
{
    use InteractsWithSchemaFragment;

    public function __construct()
    {
        $this->withFailureMessage('You must order at least 12 total cases.')
            ->append(function (?string $encodedMessage) {
                return <<<ZOD
                .superRefine((items, ctx) => {
                    const total = items.reduce((sum, item) => sum + item.quantity, 0);
                    if (total < 12) {
                        ctx.addIssue({
                            code: 'custom',
                            message: {$encodedMessage},
                            path: ['items']
                        });
                    }
                })
                ZOD;
            });
    }

    /**
     * Run the validation rule.
     *
     * @param  Closure(string, ?string=): \Illuminate\Translation\PotentiallyTranslatedString  $fail
     */
    public function validate(string $attribute, mixed $value, Closure $fail): void
    {
        if (collect($value)->sum('quantity') < 12) {
            $fail($this->failureMessage() ?? 'You must order at least 12 total units.');
        }
    }
}

Both approaches surface the schema fragment directly alongside the validation logic and are picked up automatically by the generator for FormRequests and Spatie Data classes.

Contributing

Please see CONTRIBUTING for development setup and contribution guidelines.

License

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

Credits

• Romega Software
• All Contributors