Laravel Stubs Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require rawilk/laravel-stubs --dev
   

   Add this to your composer.json to auto-publish stubs on updates (ensure compatibility with Laravel 13.x):

   "scripts": {
       "post-update-cmd": [
           "@php artisan custom-stub:publish --force"
       ]
   }
   

2. Publish Stubs:

   php artisan custom-stub:publish
   

   This replaces Laravel’s default stubs with the opinionated versions, now fully compatible with Laravel 13.x and PHP 8.5.

3. First Use Case: Generate a migration to see the changes:

   php artisan make:migration create_posts_table --laravel=13
   

   Notice the absence of down() method, declare(strict_types=1), and timestamps by default, now aligned with Laravel 13.x conventions.

Implementation Patterns

Daily Workflows

1. Consistent Code Generation:

   • Use php artisan make: commands (e.g., make:controller, make:model) to generate files with the package’s opinionated structure.
   • Example: Controllers now include Laravel 13.x imports (e.g., use Illuminate\Foundation\Application;).

2. Type Safety:

   • Stubs include declare(strict_types=1) and return type hints where applicable (e.g., in controllers, commands).
   • Example: A generated controller method (PHP 8.5 compatible):

     public function index(): Response
     {
         return response()->json([]);
     }
     

3. Simplified Migrations:

   • Migrations omit the down() method, aligning with modern Laravel practices (use php artisan migrate:fresh for resets).
   • Example (Laravel 13.x syntax):

     public function up(): void
     {
         Schema::create('posts', function (Blueprint $table) {
             $table->id();
             $table->timestamps();
         });
     }
     

4. Modern Syntax:

   • Uses Laravel 13.x syntax (e.g., use Illuminate\Foundation\Application; in stubs, updated Mailable stubs).
   • Example: Mailables now include PHP 8.5 features:

     public function build(): Mailable
     {
         return $this->markdown('emails.posts.created')->subject('New Post');
     }
     

5. Package Development:

   • Integrate with Orchestral Canvas for package stubs (now supports Laravel 13.x):

     composer require --dev rawilk/laravel-stubs orchestra/canvas
     composer exec canvas preset package
     

     Configure canvas.yaml for Laravel 13.x:

     preset: Rawilk\Stubs\Canvas\Package
     namespace: YourPackageNamespace
     laravel_version: 13.*
     

     Generate files via:

     composer exec canvas make:migration CreatePostsTable --create --laravel=13
     

6. Custom Stubs:

   • Override specific stubs by publishing and modifying files in resources/stubs/.
   • Ensure custom stubs use PHP 8.5 syntax (e.g., array_unpack, str_contains).

Gotchas and Tips

Pitfalls

1. Missing down() in Migrations:

   • Stubs omit down() methods. If your team relies on rollback logic, manually add it or use php artisan migrate:fresh for testing.

2. Strict Types (PHP 8.5):

   • declare(strict_types=1) is added globally. Ensure all generated code (e.g., factories, policies) supports PHP 8.5.
   • Example: Use array_unpack or str_contains in custom stubs.

3. Removed Docblocks:

   • Stubs strip docblocks. Add PHPDoc comments manually if needed for IDE hints or documentation.

4. Namespace Placeholders:

   • Factory stubs may have placeholder issues (fixed in v1.2.1). Verify generated factories:

     namespace Database\Factories;
     use Illuminate\Database\Eloquent\Factories\Factory;
     

5. Canvas Integration:

   • Requires orchestra/canvas for package stubs. Misconfigured canvas.yaml may break generation.
   • Specify laravel_version in canvas.yaml to avoid compatibility issues.

6. Laravel 13.x Breaking Changes:

   • Some stubs (e.g., Mailable) may reference deprecated classes. Update custom stubs to use Laravel 13.x equivalents (e.g., Illuminate\Mail\Mailable instead of older imports).

Debugging Tips

• Verify Stubs: Check if stubs are published correctly by inspecting resources/stubs/ after running custom-stub:publish.
• Override Stubs: Copy stubs from vendor/rawilk/laravel-stubs/stubs/ to resources/stubs/ to customize them for Laravel 13.x.
• Type Errors: If strict types cause issues, temporarily disable them in the stub or adjust your codebase to PHP 8.5.
• Migration Timestamps: Stubs use $table->timestamps() by default. Remove if not needed (e.g., for audit tables).

Extension Points

1. Add New Stubs: Extend the package by adding custom stubs to resources/stubs/ and update composer.json scripts to republish them.
   • Example: Add a resources/stubs/model.stub for custom model generation.
2. Conditional Logic: Use Laravel’s stub customization to inject project-specific logic (e.g., default namespace, guards).
   • Example: Override namespace in stubs for multi-tenant applications.
3. CI/CD Hooks: Automate stub updates in CI by running php artisan custom-stub:publish in deployment scripts.
   • Ensure your CI environment uses PHP 8.5 and Laravel 13.x.

Performance

• No Runtime Overhead: Stubs are static files; no performance impact after generation.
• Cache Artisan Commands: Use composer dump-autoload after publishing stubs to optimize autoloading.
• Laravel 13.x Optimizations: Leverage Laravel’s new optimizations (e.g., bootstrap/app.php changes) in custom stubs.