Dev Tools Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require clickable/dev-tools
   

   Add the service provider to config/app.php under providers:

   Clickable\DevTools\DevToolsServiceProvider::class,
   

2. Publish Config (Optional)

   php artisan vendor:publish --provider="Clickable\DevTools\DevToolsServiceProvider" --tag="config"
   

   This generates config/dev-tools.php with default settings.

3. First Use Case: Debugging Routes Run the dev-tools:routes command to list all registered routes with their middleware, controllers, and actions:

   php artisan dev-tools:routes
   

   Output includes:

   • Route URI
   • Method (GET, POST, etc.)
   • Controller/Closure
   • Middleware stack
   • Action method (if applicable)

4. First Use Case: Database Inspection Use the dev-tools:tables command to inspect database tables, columns, and indexes:

   php artisan dev-tools:tables
   

   Filter by table name:

   php artisan dev-tools:tables --table=users
   

Implementation Patterns

Common Workflows

1. Route Debugging

• List All Routes with Metadata

  php artisan dev-tools:routes --json
  

  Outputs structured JSON for programmatic use (e.g., API documentation generation).

• Filter Routes by Name or URI

  php artisan dev-tools:routes --name="admin.dashboard"
  

  or

  php artisan dev-tools:routes --uri="api/v1/users"
  

• Integrate with Route Caching Use the --cache flag to generate a cached routes file for performance:

  php artisan dev-tools:routes --cache
  

  Cache is stored at storage/framework/cache/dev-tools/routes.php.

2. Database Schema Analysis

• Compare Schemas Across Environments Use the --diff flag to compare local and production schemas (requires DB_DATABASE config):

  php artisan dev-tools:tables --diff
  

• Generate Migration Snippets Extract schema as a migration file:

  php artisan dev-tools:tables --table=posts --migration > database/migrations/2023_11_01_create_posts_table.php
  

3. Configuration Inspection

• Dump All Config Values

  php artisan dev-tools:config
  

  Outputs a tree of all Laravel config values (useful for debugging environment-specific settings).

• Search Config by Key

  php artisan dev-tools:config --key="app.timezone"
  

4. Event/Listener Debugging

• List All Events and Listeners

  php artisan dev-tools:events
  

  Includes:

  • Event class
  • Listener classes/methods
  • Priority

• Trace Event Dispatching Enable event tracing in config/dev-tools.php:

  'events' => [
      'trace' => true,
  ],
  

  Then run:

  php artisan dev-tools:events --trace
  

  Logs event dispatching to storage/logs/dev-tools-events.log.

5. Service Container Inspection

• Browse Bound Services

  php artisan dev-tools:services
  

  Outputs:

  • Service ID
  • Concrete class
  • Shared status
  • Tags

• Resolve a Specific Service

  php artisan dev-tools:services --id="App\Services\UserService"
  

6. Middleware Analysis

• List All Middleware

  php artisan dev-tools:middleware
  

  Includes:

  • Middleware class
  • Registered routes (if applicable)
  • Priority

• Test Middleware Isolation Use the --test flag to simulate middleware execution without affecting the request:

  php artisan dev-tools:middleware --test --middleware="auth"
  

Integration Tips

1. Automate in CI/CD

Add to phpunit.xml for pre-test debugging:

<env name="DEV_TOOLS_AUTOMATE" value="true"/>

Then run:

php artisan dev-tools:routes --json > routes.json

2. Extend with Custom Commands

Create a custom command to combine multiple dev-tools features:

use Clickable\DevTools\Commands\RoutesCommand;
use Clickable\DevTools\Commands\TablesCommand;

class DebugCommand extends Command {
    protected $signature = 'debug:full {--routes?} {--tables?}';
    protected $description = 'Run multiple dev-tools checks';

    public function handle() {
        if ($this->option('routes')) {
            (new RoutesCommand())->handle();
        }
        if ($this->option('tables')) {
            (new TablesCommand())->handle();
        }
    }
}

3. Use in IDE Plugins

Export dev-tools output as JSON and integrate with IDE plugins (e.g., PHPStorm) for:

• Route navigation
• Database schema exploration
• Config value lookup

4. Customize Output Format

Override the default output by extending the base command:

use Clickable\DevTools\Commands\BaseCommand;

class CustomRoutesCommand extends BaseCommand {
    protected function getOutputFormat() {
        return 'custom'; // Triggers custom output in config
    }
}

Gotchas and Tips

Pitfalls

1. Performance Overhead

   • Commands like dev-tools:routes or dev-tools:services can be slow on large applications.
   • Mitigation: Use the --cache flag or run during development only.

2. Database Connection Issues

   • dev-tools:tables requires a valid database connection.
   • Fix: Ensure .env has correct DB_* settings or use --env=production to test against production.

3. Middleware Testing Quirks

   • The --test flag for middleware may not work with global middleware (e.g., App\Http\Middleware\TrustProxies).
   • Workaround: Exclude global middleware in config/dev-tools.php:

     'middleware' => [
         'exclude_globals' => true,
     ],
     

4. Event Tracing Overhead

   • Enabling trace: true for events can significantly slow down requests.
   • Tip: Use only in development and disable in production.

5. Config Key Conflicts

   • Some config keys (e.g., app.debug) may conflict with dev-tools internal keys.
   • Solution: Prefix custom dev-tools config keys:

     'dev_tools' => [
         'custom_key' => 'value',
     ],
     

Debugging Tips

1. Enable Verbose Output Add -v or -vv to commands for debug-level logging:

   php artisan dev-tools:routes -vv
   

2. Check Logs Dev-tools logs to storage/logs/dev-tools.log. Enable with:

   'logging' => [
       'enabled' => true,
   ],
   

3. Validate JSON Output Use --json to ensure API-compatible output:

   php artisan dev-tools:config --json | jq
   

4. Reset Cache Clear dev-tools cache if output seems stale:

   php artisan cache:clear
   php artisan dev-tools:routes --cache
   

Extension Points

1. Custom Commands Extend Clickable\DevTools\Commands\BaseCommand to add new functionality:

   namespace App\Console\Commands;
   
   use Clickable\DevTools\Commands\BaseCommand;
   
   class MyCustomCommand extends BaseCommand {
       protected $signature = 'dev-tools:my-command';
       protected $description = 'My custom dev-tools command';
   
       public function handle() {
           $this->info('Extended dev-tools!');
       }
   }
   

2. Modify Output Formatters Override the formatter in config/dev-tools.php:

   'formatters' => [
       'routes' => App\Formatters\CustomRoutesFormatter::class,
   ],
   

3. Add New Inspection Targets Implement the Clickable\DevTools\Contracts\Inspectable interface:

   use Clickable\DevTools\Contracts\Inspectable;
   
   class MyInspectable implements Inspectable {
       public function inspect() {
           return ['key' => 'value'];
       }
   }
   

   Register in DevToolsServiceProvider:

   $this->app->bind('dev-tools.inspectable.my_target', MyInspectable::class);
   

4. Hook into Dev-Tools Events Listen for dev-tools events (e.g., dev-tools.inspecting):

   use Clickable\DevTools\Events\Inspecting;
   
   Event::listen