Laravel Best Practices Laravel Package

Getting Started

First Steps

1. Installation Add the package via Composer:

   composer require jpswade/laravel-best-practices
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="Jpswade\LaravelBestPractices\BestPracticesServiceProvider"
   

2. Prerequisites Ensure Laravel Boost is installed (this package extends its laravel-best-practices skill). Run:

   composer require beberlei/laravel-boost
   

3. First Use Case Run the best-practices checks during development:

   php artisan boost:check
   

   Or integrate into your CI pipeline (e.g., GitHub Actions) to enforce standards pre-merge.

Implementation Patterns

Core Workflows

1. Enforcing Standards

   • Automated Checks: Use boost:check to validate:
     • Namespace consistency (e.g., App\ prefix).
     • File structure (e.g., app/Http/Controllers/ for controllers).
     • Naming conventions (e.g., PascalCase for classes, snake_case for migrations).
   • Custom Rules: Extend via BestPracticesServiceProvider:

     // app/Providers/BestPracticesServiceProvider.php
     public function register()
     {
         $this->app->make(\Jpswade\LaravelBestPractices\Rules\CustomRule::class);
     }
     

2. Integration with Boost

   • Compose Skills: Merge with Boost’s default laravel-best-practices:

     // config/boost.php
     'skills' => [
         \Beberlei\Boost\Skills\LaravelBestPractices::class,
         \Jpswade\LaravelBestPractices\Skills\ExtendedBestPractices::class,
     ],
     

   • Selective Enforcement: Disable specific rules in config/laravel-best-practices.php:

     'rules' => [
         'namespaces' => true,
         'controller_location' => false, // Disable if using custom structure
     ],
     

3. CI/CD Pipeline

   • Fail builds on violations:

     # .github/workflows/laravel.yml
     - name: Run Best Practices
       run: php artisan boost:check --fail-on-violations
     

Daily Developer Habits

• Pre-Commit Hooks: Use php artisan boost:check in a hook to catch issues early.
• IDE Integration: Configure your IDE (e.g., PHPStorm) to highlight violations via PHP Inspections.
• Onboarding: Document team-specific rules in README.md or a wiki.

Gotchas and Tips

Common Pitfalls

1. Rule Conflicts

   • Issue: Overlapping rules between Boost and this package may cause false positives.
   • Fix: Explicitly disable redundant rules in config/laravel-best-practices.php.

2. Performance Overhead

   • Issue: Running checks on large codebases can be slow.
   • Fix: Cache results or run selectively:

     php artisan boost:check --path=app/Http/Controllers
     

3. False Positives

   • Issue: Custom project structures may trigger unnecessary warnings.
   • Fix: Extend rules to whitelist paths:

     // app/Rules/CustomNamespaceRule.php
     public function passes($file)
     {
         return str_starts_with($file, 'app/') && !str_contains($file, 'Exceptions/');
     }
     

Debugging Tips

• Verbose Output: Use --verbose to see detailed rule explanations:

  php artisan boost:check --verbose
  

• Dry Runs: Test changes without failing:

  php artisan boost:check --dry-run
  

• Rule Isolation: Temporarily disable all rules except one to debug:

  // config/laravel-best-practices.php
  'rules' => ['controller_location' => true, ...],
  

Extension Points

1. Custom Rules

   • Implement Jpswade\LaravelBestPractices\Contracts\Rule:

     namespace App\Rules;
     
     use Jpswade\LaravelBestPractices\Contracts\Rule;
     
     class CustomRule implements Rule
     {
         public function passes($file) { /* ... */ }
         public function message() { return 'Custom rule message'; }
     }
     

   • Register in BestPracticesServiceProvider.

2. Modifying Existing Rules

   • Override default rules by publishing and modifying:

     php artisan vendor:publish --tag="laravel-best-practices-config"
     

   • Edit config/laravel-best-practices.php to adjust severity or thresholds.

3. Excluding Files/Directories

   • Use .boostignore (similar to .gitignore) to skip files:

     # .boostignore
     app/Exceptions/
     resources/views/cache/
     

Pro Tips

• Progressive Enforcement: Start with --fix to auto-correct simple issues:

  php artisan boost:check --fix
  

• Team Alignment: Use the package to standardize code reviews—reduce bikeshedding over style.
• Document Exceptions: Maintain a RULE_EXCEPTIONS.md file to justify disabled rules for future devs.