Scip Laravel Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev bnomei/scip-laravel
   

   Ensure your project uses Laravel 11-13 and PHP 8.3+.

2. First Run: Execute the CLI command in your project root:

   vendor/bin/scip-laravel generate
   

   This generates index.scip in the project root, merging SCIP data from:

   • Core PHP files (via scip-php)
   • Laravel-specific metadata (via Surveyor and Ranger).

3. Where to Look First:

   • Output: Check index.scip for generated data.
   • Configuration: Review .scip-laravel.php (auto-generated in config/).
   • Dependencies: Verify scip-php, Surveyor, and Ranger are installed (they’re auto-included as dev deps).

First Use Case: Local Code Intelligence

Use index.scip with tools like:

• VS Code: Install the SCIP extension for:
  • Autocomplete for Laravel classes (e.g., Route::, Model::).
  • Navigation to routes, models, or Inertia pages via F12 (Go to Definition).
• PHPStorm: Use the SCIP plugin for similar IDE features.

Implementation Patterns

Workflow: Generating and Updating Indexes

1. Integrate into CI/CD: Add to your composer.json scripts:

   "scripts": {
     "post-update-cmd": [
       "@php vendor/bin/scip-laravel generate"
     ]
   }
   

   Run composer update to auto-generate index.scip.

2. Selective Indexing: Exclude files/dirs via .scip-laravel.php:

   return [
       'exclude' => [
           'storage/*',
           'tests/*',
           'vendor/*',
       ],
   ];
   

3. Custom Metadata: Extend Laravel-specific data via Surveyor hooks (e.g., add custom route tags):

   // In a ServiceProvider
   Surveyor::extend(function ($surveyor) {
       $surveyor->routeTags(['api' => 'routes/api.php']);
   });
   

Integration Tips

• Ranger Integration: Ensure laravel/ranger is installed (auto-included). It provides:

  • Route definitions, model relationships, Inertia pages, etc.
  • Example: Navigate to a route in your IDE by hovering over Route::get('/user', ...).

• SCIP-php Customization: Override scip-php behavior via .scip.php (e.g., ignore abstract classes):

  return [
      'ignore' => [
          'abstract',
          'trait',
      ],
  ];
  

• IDE Sync: For VS Code/PHPStorm, add index.scip to your project’s .gitignore (it’s auto-generated) but keep it in version control for team consistency.

Gotchas and Tips

Pitfalls

1. Performance:

   • Large Projects: Generating index.scip may take minutes for monorepos. Run in CI during off-peak hours.
   • Debugging: Use --verbose flag:

     vendor/bin/scip-laravel generate --verbose
     

2. Dependency Conflicts:

   • Ensure scip-php, Surveyor, and Ranger versions are compatible (check their respective composer.json).
   • If conflicts arise, pin versions in composer.json:

     "require-dev": {
         "bnomei/scip-laravel": "^1.0",
         "laravel/surveyor": "^1.0",
         "laravel/ranger": "^1.0"
     }
     

3. IDE-Specific Issues:

   • VS Code: Restart the IDE after generating index.scip to refresh the SCIP index.
   • PHPStorm: Ensure the SCIP plugin is enabled in Settings > Plugins.

Debugging

1. Invalid Index: Delete index.scip and regenerate. If issues persist, check:

   • Laravel logs (storage/logs/laravel.log).
   • scip-laravel logs (enable with --verbose).

2. Missing Metadata: Verify Ranger is collecting data (e.g., routes/models). Test with:

   vendor/bin/ranger inventory
   

Extension Points

1. Custom SCIP Data: Use Surveyor::extend() to inject custom metadata (e.g., API documentation):

   Surveyor::extend(function ($surveyor) {
       $surveyor->addMetadata('api:description', 'User API', 'routes/api.php');
   });
   

2. Post-Processing: Modify index.scip after generation (e.g., with jq):

   jq '.nodes |= map(select(.kind == "namespace"))' index.scip > filtered.scip
   

3. CI-Cache: Cache index.scip in CI to avoid regenerating on every run:

   # GitHub Actions example
   - name: Cache SCIP index
     uses: actions/cache@v3
     with:
       path: index.scip
       key: ${{ runner.os }}-scip-${{ hashFiles('**/composer.lock') }}
   

Pro Tips

• Team Onboarding: Include index.scip in your repo (even if auto-generated) to ensure all devs have consistent IDE features.
• Monorepos: Use --project-dir to generate indexes for sub-projects:

  vendor/bin/scip-laravel generate --project-dir=packages/api
  

• Local Development: Symlink index.scip to a shared location for multi-repo projects:

  ln -s ../project-a/index.scip ./index.scip