Boost Spatie Guidelines Laravel Package

Getting Started

Minimal Setup

1. Install the package in your Laravel project:

   composer require spatie/boost-spatie-guidelines --dev
   

2. Run Boost installation:

   php artisan boost:install
   

   • Select "Spatie Guidelines" from the list of available guidelines.
   • The package will auto-configure and place guidelines in .ai/guidelines/boost-spatie-guidelines/.

3. Verify integration:

   • Open Laravel Boost and confirm the guidelines are active.
   • Test by prompting Boost to generate a simple controller or model—it should now follow Spatie’s conventions.

First Use Case: Controller Generation

Ask Boost to generate a controller for a User resource:

"Create a Laravel controller for managing users with RESTful routes, following Spatie’s guidelines. Include happy path logic and proper type hints."

Expected output:

• Proper snake_case route naming (users).
• Controller method names in camelCase (storeUser, updateUser).
• Type-declared methods and properties.
• Early returns for error handling.

Implementation Patterns

Workflow Integration

1. AI-Assisted Development Loop:

   • Use Boost’s chat interface to draft code snippets (e.g., models, migrations, policies).
   • Reference Spatie’s guidelines explicitly:

     "Write a Laravel policy for Post with Spatie’s happy path pattern and nullable type hints."

   • Iterate with Boost’s suggestions, then refine manually.

2. Consistent Codebase Enforcement:

   • Models: Boost will auto-generate:

     class User extends Model
     {
         use HasApiTokens, Notifiable;
     
         protected $fillable = [
             'name', 'email', 'password',
         ];
     
         protected $hidden = ['password'];
         protected $casts = [
             'email_verified_at' => 'datetime',
         ];
     }
     

   • Controllers: Follows snake_case routes + camelCase methods:

     Route::post('/users', [UserController::class, 'storeUser']);
     

3. Validation and Blade:

   • Prompt Boost for validation rules:

     "Generate FormRequest for user registration with Spatie’s validation rules." Output:

     public function rules(): array
     {
         return [
             'name' => ['required', 'string', 'max:255'],
             'email' => ['required', 'string', 'email', 'max:255', 'unique:users'],
             'password' => ['required', 'confirmed', 'min:8'],
         ];
     }
     

   • Blade templates will use snake_case for variables and kebab-case for classes:

     <x-input type="text" name="user_name" :value="old('user_name', $user->name)" />
     

4. Testing Patterns:

   • Ask Boost to scaffold tests with Spatie’s conventions:

     "Write a feature test for UserController@storeUser with happy path and error cases." Output:

     public function test_store_user_creates_user()
     {
         $userData = UserFactory::new()->raw();
     
         $response = $this->post('/users', $userData);
     
         $response->assertCreated();
         $this->assertDatabaseHas('users', $userData);
     }
     

Pro Tips for Daily Use

• Customize Guidelines: Override defaults in .ai/guidelines/boost-spatie-guidelines/config.php (e.g., adjust max_line_length or disallowed_functions).
• Pair with php-cs-fixer: Run php-cs-fixer fix to align existing code with Spatie’s standards after Boost generates snippets.
• Leverage Boost’s Snippets: Save frequently used patterns (e.g., "Spatie Policy Template") in Boost’s snippet manager for reuse.

Gotchas and Tips

Common Pitfalls

1. Over-Reliance on AI:

   • Issue: Boost may generate overly verbose or redundant code (e.g., nested if-else for happy path).
   • Fix: Manually refactor post-generation. Use Boost for structure, not final output.
   • Prompt Hack:

     "Write a minimal UserController for store with Spatie’s happy path—avoid unnecessary comments."

2. Type Hint Conflicts:

   • Issue: Boost may suggest ?string for nullable fields where string|null is preferred (PHP 8.1+).
   • Fix: Configure in config/boost.php:

     'preferred_nullable_syntax' => 'string|null', // Override default
     

3. Blade Template Quirks:

   • Issue: Boost might use @if instead of @unless for negative conditions.
   • Fix: Explicitly request:

     "Use @unless for negative conditions in Blade, following Spatie’s guidelines."

4. Route Caching:

   • Issue: Generated routes may not account for Route::model() or API resource grouping.
   • Fix: Prompt Boost to include:

     "Group routes under /api/v1 and use Route::apiResource for Post."

Debugging and Extensions

1. Guideline Overrides:

   • Disable specific rules in .ai/guidelines/boost-spatie-guidelines/rules.php:

     return [
         'disallowed_functions' => [
             'strtolower', // Temporarily allow for case-insensitive checks
         ],
     ];
     

2. Boost Logs:

   • Enable verbose logging in config/boost.php to debug why Boost ignores your prompts:

     'debug' => env('BOOST_DEBUG', false),
     

3. Extending Guidelines:

   • Add custom rules by extending SpatieGuidelines in .ai/guidelines/boost-spatie-guidelines/SpatieGuidelines.php:

     public function getCustomRules(): array
     {
         return [
             'types' => [
                 'App\\Models\\User' => 'UserModel',
             ],
         ];
     }
     

4. Performance:

   • Issue: Large files (e.g., AppServiceProvider) may slow down Boost’s analysis.
   • Fix: Split logic into smaller classes or use @boost-ignore comments:

     // @boost-ignore
     public function boot()
     {
         // Complex legacy code
     }
     

Pro-Level Tips

• Pair with spatie/laravel-ignition: Use Ignition’s error pages to validate Boost-generated code against Spatie’s conventions.
• Git Hooks: Add a pre-commit hook to run php artisan boost:validate (if supported) to catch guideline violations early.
• Documentation: Cross-reference Spatie’s Laravel Styleguide for edge cases Boost doesn’t cover (e.g., custom facades).