Oi Laravel Ts Laravel Package

Getting Started

1. Installation:

   composer require oi-lab/oi-laravel-ts
   php artisan vendor:publish --tag=oi-laravel-ts-config
   

2. First Run:

   php artisan oi:gen-ts
   

   • Outputs to resources/js/types/interfaces.ts by default.
   • Scans app/Models for Eloquent models.

3. Quick Use Case:

   • Add a model like User with relationships (e.g., hasMany(Post)).
   • Run the generator to auto-create IUser with typed relationships:

     export interface IUser {
       id: number;
       posts?: IPost[];
     }
     

Implementation Patterns

Core Workflow

1. Model Definition:

   // app/Models/User.php
   class User extends Model {
       public function posts(): HasMany { return $this->hasMany(Post::class); }
   }
   

2. Generate Interfaces:

   php artisan oi:gen-ts
   

3. Use in TypeScript:

   import { IUser } from '@/types/interfaces';
   
   const user: IUser = await fetchUser();
   

Advanced Patterns

• Watch Mode (auto-regenerate on model changes):

  php artisan oi:gen-ts --watch
  

• Custom Properties (add non-database fields):

  // config/oi-laravel-ts.php
  'custom_props' => [
      'User' => [
          'full_name' => 'string',
          'avatar_url' => 'string',
      ],
  ],
  

• DataObject Support (auto-generate interfaces for cast value objects):

  // app/Models/Page.php
  protected $casts = ['metadata' => MetadataCast::class];
  

  Outputs:

  export interface IMetadata { title: string; }
  export interface IPage { metadata?: IMetadata; }
  

Integration Tips

• Inertia.js: Type page props with generated interfaces:

  interface DashboardProps extends PageProps {
      user: IUser;
  }
  

• API Responses: Use interfaces for request/response validation (e.g., with zod or class-validator).

Gotchas and Tips

Pitfalls

1. Namespace Conflicts:

   • Exclude third-party models with excluded_namespaces to avoid bloated schemas.
   • Example:

     'excluded_namespaces' => ['Spatie\\Permission\\Models'],
     

2. UUID/ULID Keys:

   • Models using HasUuids or $keyType = 'string' generate id: string (not number).
   • Debug with 'save_schema' => true in config to inspect intermediate output.

3. Circular Dependencies:

   • Relationships between models (e.g., User ↔ Post) may cause infinite loops.
   • Use 'discover_related_models' => false to limit scope or manually configure extended_namespaces.

Debugging

• Schema Dump: Enable 'save_schema' => true to inspect raw model data before TypeScript conversion.
• Watch Mode: Useful for iterative development—regenerates on file changes.

Extension Points

1. Custom Type Mappings:

   // config/oi-laravel-ts.php
   'props_with_types' => [
       'App\\Models\\User' => [
           'email_verified_at' => 'Date',
       ],
   ],
   

2. External Imports:

   'custom_props' => [
       'User' => [
           'settings' => '@/types/settings|UserSettings',
       ],
   ],
   

   Outputs:

   import { UserSettings } from '@/types/settings';
   

3. Multi-File Output:

   • Use the --multi-file flag to generate one file per interface + an index.ts barrel.

Pro Tips

• PHPDoc Annotations: Leverage @property or @method in models for finer control over generated types.
• JSON-LD Support: Enable with 'with_json_ld' => true for structured data APIs.
• Performance: For large projects, pre-filter models with Model::when() in a custom discovery class.