Guidelines Skills Laravel Package

Getting Started

Minimal Setup

1. Install via Composer (Laravel Boost):

   composer require spatie/guidelines-skills --dev
   php artisan boost:install
   

   • Select "Spatie guidelines" from the list during installation.

2. Install via skills.sh (CLI-only):

   npx skills add spatie/guidelines-skills
   

3. First Use Case:

   • Open a Laravel/PHP file in VS Code/PhpStorm. The IDE will highlight violations (e.g., PSR-12 naming, security risks) with real-time suggestions.
   • Commit a Git message; skills.sh will validate commit conventions (e.g., "fix: resolve X" format).

Where to Look First

• Configuration: .boost/skills.json (for Laravel Boost) or skills.sh config.
• Documentation: Spatie Guidelines for human-readable rules.
• CLI Feedback: Run php artisan boost:check or skills check to scan the codebase for violations.

Implementation Patterns

Workflows

1. IDE Integration (Laravel Boost):

   • Onboarding: New developers install via composer require and select guidelines during boost:install.
   • Daily Use: IDE underlines violations (e.g., mysql_query()) with quick-fix suggestions.
   • Team Sync: Shared .boost/skills.json ensures consistency across all dev environments.

2. CLI Enforcement (skills.sh):

   • Pre-Commit Hook: Add to .git/hooks/pre-commit:

     #!/bin/bash
     npx skills check --fix
     

   • CI Pipeline: Add to Laravel/PHP jobs:

     - run: npx skills check
     

3. Modular Adoption:

   • Start with spatie-security and spatie-version-control for immediate impact.
   • Gradually add spatie-laravel-php or spatie-javascript as needed.

Integration Tips

• Laravel Projects:
  • Combine with phpstan/phpstan for static analysis. Example phpstan.neon:

    includes:
      - vendor/spatie/guidelines-skills/rules/laravel.neon
    

• JavaScript:
  • Pair with Prettier for auto-formatting. Add to .prettierrc:

    {
      "overrides": [spatie/guidelines-skills/config/javascript.json]
    }
    

• Git Hooks:
  • Use skills.sh to enforce branch naming (e.g., feature/, fix/ prefixes):

    npx skills add spatie/version-control
    

Example: Enforcing Security Rules

1. IDE Feedback:
   • A dev writes DB::select("SELECT * FROM users WHERE id = $id"). The IDE flags it as a SQL injection risk and suggests:

     DB::table('users')->where('id', $id)->get();
     

2. CI Block:
   • Add to .github/workflows/laravel.yml:

     - name: Security Check
       run: npx skills check --skill spatie-security
     

Gotchas and Tips

Pitfalls

1. Rule Overrides:

   • Gotcha: Disabling spatie-security rules may expose vulnerabilities. Example:

     // ❌ Avoid disabling security rules entirely
     {
       "skills": {
         "spatie-security": { "enabled": false }
       }
     }
     

   • Fix: Use selective overrides for edge cases:

     // ✅ Allow specific exceptions
     {
       "skills": {
         "spatie-security": {
           "rules": {
             "no-mysql-query": { "ignore": ["legacy/old-code.php"] }
           }
         }
       }
     }
     

2. Performance:

   • Gotcha: Real-time IDE analysis may slow down large codebases.
   • Fix: Exclude directories in .boost/skills.json:

     {
       "exclude": ["storage/*", "tests/*"]
     }
     

3. Tooling Conflicts:

   • Gotcha: Conflicts with existing linters (e.g., PHP_CodeSniffer).
   • Fix: Run skills.sh in CI to catch violations early:

     npx skills check --skill spatie-laravel-php --format json > violations.json
     

Debugging

• IDE Not Showing Issues?:
  • Restart the IDE or run:

    php artisan boost:clear-cache
    

• CLI Errors:
  • Check skills.sh logs with --verbose:

    npx skills check --verbose
    

• Custom Rules Not Working:
  • Ensure the skill is enabled in .boost/skills.json or skills.sh config.

Tips

1. Team Adoption:

   • Start with a pilot group (e.g., backend team) to gather feedback before full rollout.
   • Use skills.sh to generate a report of violations:

     npx skills check --format markdown > CODE_REVIEW.md
     

2. Custom Rules:

   • Extend Spatie’s rules by creating a custom skill. Example:

     npx create-skill my-custom-skill
     

     Then reference it in .boost/skills.json:

     {
       "skills": ["spatie/guidelines-skills", "my-custom-skill"]
     }
     

3. CI/CD Integration:

   • Fail the pipeline on violations:

     - name: Enforce Guidelines
       run: npx skills check --fail-on-violations
     

4. Legacy Code:

   • Use --fix to auto-correct non-critical violations:

     npx skills check --skill spatie-laravel-php --fix
     

5. Documentation:

   • Link the Spatie Guidelines in your team’s onboarding docs to explain the "why" behind rules.

Extension Points

• Custom Skills:
  • Create a skill using skills.sh’s CLI tooling:

    npx create-skill my-team-guidelines
    

• Boost Plugins:
  • Extend Laravel Boost with custom plugins to integrate Spatie’s rules into your workflow.
• Git Templates:
  • Use spatie-version-control to enforce commit templates:

    npx skills add spatie/version-control --commit-template