Artisan Schematics Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require saher/artisan-schematics --dev
   

   Add the service provider to config/app.php under providers:

   Saher\ArtisanSchematics\ArtisanSchematicsServiceProvider::class,
   

2. Publish Config:

   php artisan vendor:publish --provider="Saher\ArtisanSchematics\ArtisanSchematicsServiceProvider" --tag="config"
   

   This generates config/artisan-schematics.php. Configure default output paths and enabled languages (e.g., typescript, dart).

3. First Use Case: Generate TypeScript definitions for all models:

   php artisan schematics:generate
   

   Outputs to resources/lang/typescript (or your configured path) by default.

Implementation Patterns

Core Workflow

1. Generate Schematics:

   php artisan schematics:generate
   

   • Processes all Eloquent models in app/Models (configurable via model_paths in config).
   • Recursively resolves relationships and includes referenced models/enums.

2. Selective Generation: Generate for specific models:

   php artisan schematics:generate --models="User,Post"
   

   Generate for a single language:

   php artisan schematics:generate --languages="dart"
   

3. Watch Mode (for development):

   php artisan schematics:watch
   

   • Automatically regenerates schematics on file changes (e.g., model updates).

Integration Tips

1. Customize Output Paths: Override paths per language in config/artisan-schematics.php:

   'paths' => [
       'typescript' => 'resources/lang/typescript',
       'dart'       => 'lib/generated',
   ],
   

2. Extend Generators: Create a custom generator (e.g., for Rust):

   • Publish the generator template:

     php artisan vendor:publish --provider="Saher\ArtisanSchematics\ArtisanSchematicsServiceProvider" --tag="generators"
     

   • Add a new class in app/Generators/RustGenerator.php extending Saher\ArtisanSchematics\Generators\Generator.
   • Register it in config/artisan-schematics.php:

     'generators' => [
         \App\Generators\RustGenerator::class,
     ],
     

3. Hook into Model Events: Regenerate schematics after model changes via ModelObserver:

   use Saher\ArtisanSchematics\Facades\Schematics;
   
   class ModelObserver {
       public function saved($model) {
           if ($model instanceof \Illuminate\Database\Eloquent\Model) {
               Schematics::generate();
           }
       }
   }
   

4. CI/CD Pipeline: Add to deployment script to ensure frontend/backend type safety:

   php artisan schematics:generate --languages="typescript,dart" --force
   

Gotchas and Tips

Pitfalls

1. Circular Dependencies:

   • If models reference each other in a loop (e.g., User hasMany Post, Post belongsTo User), the package handles it but may generate verbose output. Use --minimal flag to reduce redundancy:

     php artisan schematics:generate --minimal
     

2. Custom Casts Not Detected:

   • Ensure custom casts are properly typed in the model. For example:

     protected $casts = [
         'metadata' => 'array', // Works
         'status'   => CustomCast::class, // Requires CustomCast to implement `getValueForSerialization`
     ];
     

3. Language-Specific Quirks:

   • TypeScript: Uses interface for models and enum for PHP enums. Nested relationships are flattened into union types.
   • Dart: Uses class for models and class for enums (with @immutable if enabled).
   • Kotlin/Swift: May require additional setup for null safety or optionals.

4. File Overwrites:

   • By default, the package appends to existing files. Use --force to overwrite:

     php artisan schematics:generate --force
     

Debugging

1. Verbose Output: Enable debug mode in config/artisan-schematics.php:

   'debug' => true,
   

   Or use the --verbose flag:

   php artisan schematics:generate --verbose
   

2. Dry Run: Preview changes without writing files:

   php artisan schematics:generate --dry-run
   

3. Check Generated Files:

   • Validate against your backend by importing the generated files into your frontend project and testing API calls.

Extension Points

1. Custom Field Mappings: Override field naming or types per model via a getSchematicsAttributes method:

   class User extends Model {
       public function getSchematicsAttributes(): array {
           return [
               'name' => ['type' => 'string', 'alias' => 'fullName'],
               'email' => ['type' => 'string', 'format' => 'email'],
           ];
       }
   }
   

2. Pre/Post-Generation Hooks: Bind events in EventServiceProvider:

   protected $listen = [
       'Saher\ArtisanSchematics\Events\SchematicsGenerating' => [
           \App\Listeners\LogGenerationStart::class,
       ],
       'Saher\ArtisanSchematics\Events\SchematicsGenerated' => [
           \App\Listeners\NotifySlack::class,
       ],
   ];
   

3. Template Overrides: Customize the output template for a language by extending the generator’s getTemplate method or overriding the Blade template in resources/views/vendor/artisan-schematics.

4. Enum Handling: Exclude PHP enums from generation by adding to config/artisan-schematics.php:

   'exclude_enums' => [
       \App\Enums\InternalStatus::class,
   ],