Devtools Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require sikessem/devtools --dev --with-all-dependencies
   

   Or add to composer.json under require-dev:

   "sikessem/devtools": "^1.5"
   

2. Publish Configurations (if needed):

   php artisan vendor:publish --provider="Sikessem\DevTools\DevToolsServiceProvider"
   

   This publishes optional configs for tools like PHPStan, Pest, or Rector.

3. First Use Case: Replace dd() with the enhanced dumping tool:

   use Sikessem\DevTools\dd;
   
   dd($user); // Now integrates with Laravel Debugbar/Ray if installed
   

4. Run IDE Helpers (for autocompletion):

   php artisan devtools:ide-helpers
   

5. Verify Installation: Check if tools like Pest or PHPStan are now available in your project.

Implementation Patterns

Usage Patterns

1. Debugging Workflow:

   • Replace dd() with \Sikessem\DevTools\dd() for enhanced dumping (supports Debugbar/Ray integration).
   • Use php artisan devtools:debugbar to toggle Debugbar visibility.
   • Leverage Ray for complex data inspection (if included in the bundle).

2. Testing Workflow:

   • Write tests in Pest (included in the bundle) instead of PHPUnit:

     test('user can login', function () {
         $response = $this->post('/login', ['email' => 'test@example.com']);
         $response->assertStatus(200);
     });
     

   • Run tests with:

     ./vendor/bin/pest
     

   • Use Testbench for Laravel-specific testing (if needed).

3. Static Analysis:

   • Run PHPStan with default or custom configs:

     ./vendor/bin/phpstan analyse
     

   • Merge existing PHPStan configs with the published bundle config.

4. Refactoring:

   • Use Rector for safe code upgrades:

     ./vendor/bin/rector process src --dry-run
     

   • Configure Rector via published configs or custom rulesets.

5. IDE Integration:

   • Generate PHPDoc blocks for Laravel’s dynamic features:

     php artisan devtools:ide-helpers
     

   • Update .env and config/ files to reflect new helpers.

6. Automation:

   • Use Laravel Sail (if included) for containerized testing/development:

     sail up
     sail artisan migrate
     

   • Automate workflows with Laravel Actions (if supported).

7. Livewire/Blade Testing:

   • Test Livewire components with Pest’s Livewire plugin:

     test('counter increments', function () {
         $this->livewire(Counter::class)
             ->assertSee('0')
             ->call('increment')
             ->assertSee('1');
     });
     

Workflows

1. Daily Debugging:

   • Use \Sikessem\DevTools\dd() instead of dd() for richer output.
   • Toggle Debugbar with php artisan devtools:debugbar.

2. Test-Driven Development (TDD):

   • Write tests in Pest syntax.
   • Run tests with ./vendor/bin/pest --watch for real-time feedback.

3. Code Reviews:

   • Run PHPStan and Rector in CI to catch issues early:

     # .github/workflows/ci.yml
     jobs:
       test:
         runs-on: ubuntu-latest
         steps:
           - run: ./vendor/bin/phpstan analyse --level=5
           - run: ./vendor/bin/rector process --dry-run
     

4. Onboarding New Developers:

   • Install the package once to get all tools (Pest, PHPStan, Debugbar, etc.).
   • Run php artisan devtools:install to set up IDE helpers and configs.

5. Legacy Code Refactoring:

   • Use Rector to upgrade legacy code to modern PHP/Laravel syntax:

     ./vendor/bin/rector process src --set="laravel-100"
     

Integration Tips

1. Selective Tool Adoption:

   • If you don’t need Pest, exclude it by requiring individual tools:

     composer require pestphp/pest --dev
     

   • Override the bundle’s dependencies in composer.json:

     "replace": {
         "pestphp/pest": "2.0"
     }
     

2. Configuration Merging:

   • Merge existing configs with the bundle’s published configs:

     php artisan vendor:publish --tag=phpstan-config
     

   • Edit the merged phpstan.neon to retain custom rules.

3. CI/CD Optimization:

   • Cache dependencies to speed up CI runs:

     steps:
       - uses: actions/cache@v3
         with:
           path: vendor
           key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}
     

   • Run lighter checks in CI (e.g., skip Rector’s --dry-run in production).

4. Laravel Service Providers:

   • Ensure the package’s service provider is registered. If not, manually add it to config/app.php:

     'providers' => [
         // ...
         Sikessem\DevTools\DevToolsServiceProvider::class,
     ],
     

5. Customizing Commands:

   • Extend or override bundled commands by publishing their configs and creating custom commands:

     php artisan vendor:publish --tag=devtools-commands
     

Gotchas and Tips

Pitfalls

1. Dependency Conflicts:

   • The bundle includes 20+ tools, which may conflict with existing dependencies (e.g., Pest vs. PHPUnit, PHPStan vs. Psalm).
   • Fix: Use composer why-not to diagnose conflicts and manually override dependencies in composer.json.

2. PHP Version Requirements:

   • The package requires PHP 8.4+. If your project uses an older version, you’ll need to upgrade or avoid this package.
   • Fix: Check php -v and update if necessary.

3. Configuration Overrides:

   • Some tools (e.g., PHPStan, Rector) may override your existing configs.
   • Fix: Publish the bundle’s configs first, then merge your customizations:

     php artisan vendor:publish --tag=phpstan-config
     

4. Performance Overhead:

   • Tools like PHPStan and Rector can slow down local development and CI.
   • Fix: Run them selectively:

     ./vendor/bin/phpstan analyse --level=3  # Lower strictness for speed
     

5. Debugbar/Ray Duplication:

   • The bundle may include multiple debugging tools (Debugbar, Ray, Ignition), leading to redundancy.
   • Fix: Choose one primary tool and disable others via config.

6. Laravel Version Compatibility:

   • The package may not fully support Laravel 11+ features (e.g., Jetstream, Fortify).
   • Fix: Check the release notes for Laravel compatibility.

7. IDE Helpers Issues:

   • Auto-generated IDE helpers might conflict with existing PHPDoc blocks.
   • Fix: Run php artisan devtools:ide-helpers --force to overwrite or manually merge changes.

Debugging Tips

1. Command Not Found:

   • If a command (e.g., pest, phpstan) isn’t recognized, ensure it’s installed via Composer:

     composer require --dev pestphp/pest
     

2. Debugbar Not Showing:

   • Debugbar may not appear if the middleware isn’t registered. Add it to app/Http/Kernel.php:

     protected $middleware = [
         // ...
         \Sikessem\DevTools\Http\Middleware\Debugbar::class,
     ];
     

3. Pest Tests Failing:

   • If Pest tests fail due to missing Laravel bindings, ensure Testbench is properly set up:

     composer require --dev orchestra/testbench
     

4. PHPStan Errors:

   • If PHPStan fails with "level not found," update your phpstan.neon:

     includes:
         - vendor/sikessem/devtools/config/phpstan.neon
     levels:
         - 1
         - 2
         - 3
         - 5
         - 8
     

5. Rector Dry Run Failing:

   • If Rector’s --dry-run fails, check for syntax errors in your code or ruleset:

     ./vendor/bin/rector process --dry-run --verbose
     

Configuration Quirks

1. **