Guidelines Skills Laravel Package

Getting Started

First Steps

1. Installation:

   • For Laravel Boost: Run composer require spatie/guidelines-skills --dev followed by php artisan boost:install and select the Spatie guidelines.
   • For skills.sh: Execute npx skills add spatie/guidelines-skills in your project root.

2. Initial Use Case:

   • Laravel Boost: Run php artisan boost:check to scan your codebase for violations against Spatie’s guidelines. Focus on the spatie-laravel-php skill first, as it covers core Laravel/PHP conventions.
   • skills.sh: Integrate with your CI/CD pipeline (e.g., GitHub Actions) to run npx skills check and enforce guidelines pre-commit or pre-merge.

3. Quick Wins:

   • Use php artisan boost:fix (if available) or manually address top violations (e.g., PSR-12 compliance, naming conventions).
   • Bookmark spatie.be/guidelines for reference during code reviews.

Implementation Patterns

Workflows

1. Onboarding New Developers:

   • Add npx skills check to your README.md as a pre-development step.
   • Use php artisan boost:check --skill=spatie-version-control to enforce Git workflows (e.g., branch naming, commit messages).

2. Code Reviews:

   • Run php artisan boost:check --skill=spatie-security to catch security misconfigurations (e.g., hardcoded secrets, SQL injection risks).
   • Integrate with Pull Request templates to highlight guideline violations early.

3. CI/CD Pipeline:

   • GitHub Actions Example:

     - name: Check Spatie Guidelines
       run: npx skills check
     

   • Fail builds on critical violations (e.g., spatie-security issues).

4. Team Alignment:

   • Schedule a 15-minute team sync to review php artisan boost:check --report output and prioritize fixes.
   • Use spatie-javascript to standardize frontend codebases (e.g., Prettier alignment).

Integration Tips

• Laravel Boost:
  • Combine with spatie/laravel-developer-tools for a unified developer experience.
  • Exclude test files from checks via .boostignore:

    tests/
    storage/
    

• skills.sh:
  • Pair with eslint or php-cs-fixer for layered enforcement (e.g., auto-fix formatting).
  • Use npx skills check --skill=spatie-laravel-php --fix (if supported) for quick fixes.

Gotchas and Tips

Pitfalls

1. False Positives:
   • spatie-security may flag legacy code (e.g., mysql_connect()). Use .boostignore or suppress rules via:

     // config/boost.php
     'skills' => [
         'spatie-security' => [
             'ignore' => [
                 'files' => ['legacy/Database.php'],
                 'rules' => ['no-mysql-connect'],
             ],
         ],
     ],
     

2. Performance Overhead:
   • Skip guidelines-skills in production by adding to composer.json:

     "extra": {
         "laravel": {
             "dont-discover": ["spatie/guidelines-skills"]
         }
     }
     

3. Skill Conflicts:
   • spatie-javascript and spatie-laravel-php may have overlapping rules (e.g., naming conventions). Resolve conflicts by aligning with Spatie’s full guidelines.

Debugging

• Verbose Output:
  • Use php artisan boost:check --verbose to diagnose rule triggers.
  • For skills.sh, add --debug to inspect skill execution:

    npx skills check --debug
    

• Rule Exclusions:
  • Temporarily disable a skill during refactoring:

    npx skills check --skip=spatie-security
    

Extension Points

1. Custom Rules:
   • Extend spatie-laravel-php by creating a custom skill (see Laravel Boost docs).
   • Example: Add a rule to enforce use App\Models; over use App\ in all files.
2. Git Hooks:
   • Integrate with husky to run npx skills check pre-commit:

     npx husky add .husky/pre-commit "npx skills check --skill=spatie-version-control"
     

3. IDE Support:
   • Configure PHPStorm to use Spatie’s PSR-12 inspection profile (download from spatie.be/guidelines).
   • For JavaScript, add a .eslintrc that mirrors spatie-javascript rules.

Pro Tips

• Prioritize Skills:
  • Start with spatie-security and spatie-laravel-php for immediate impact.
  • Use spatie-version-control to standardize commit messages (e.g., Conventional Commits).
• Document Exceptions:
  • Maintain a GUIDELINES_EXCEPTIONS.md file to justify ignored rules (e.g., legacy code, third-party constraints).
• Automate Updates:
  • Add a weekly cron job to update guidelines:

    composer update spatie/guidelines-skills && php artisan boost:update