README

A collection of powerful CLI development tools for Laravel that help you maintain code quality, security, and consistency through static analysis.

Requirements

PHP 8.2+
Laravel 11 or 12

Installation

composer require stratos/laravel-toolbox --dev

Optionally publish the configuration file:

php artisan vendor:publish --tag=laravel-toolbox-config

Commands

All commands are prefixed with toolbox: and support JSON output for CI/CD integration.

toolbox:scan-env

Scan for environment variable issues: undefined, undocumented, and unused variables.

php artisan toolbox:scan-env
php artisan toolbox:scan-env --type=undefined
php artisan toolbox:scan-env --fail-on-issues --json

Option	Description
`--path`	Paths to scan (default: app/, config/, routes/, database/)
`--env-file`	Path to .env file
`--example-file`	Path to .env.example file
`--type`	Filter by issue type: `all`, `undefined`, `undocumented`, `unused`
`--json`	Output results as JSON
`--fail-on-issues`	Exit with error code if issues found (for CI/CD)
`--ignore-dynamic`	Ignore dynamic env() calls

Issue Types:

Undefined (critical): Variables used in code but not defined in .env
Undocumented (low): Variables in .env but missing from .env.example
Unused (medium): Variables defined but never referenced in code

toolbox:scan-n1

Scan code for potential N+1 query problems using static analysis.

php artisan toolbox:scan-n1
php artisan toolbox:scan-n1 --severity=high
php artisan toolbox:scan-n1 --json --fail-on-issues

Option	Description
`--path`	Path to scan (default: app)
`--models-path`	Path to Eloquent models (default: app/Models)
`--views-path`	Path to Blade views (default: resources/views)
`--json`	Output results as JSON
`--severity`	Filter by severity: `all`, `high`, `medium`, `low`
`--fail-on-issues`	Exit with error code if issues found

Detection Features:

Discovers Eloquent models and relationships automatically
Detects relationship access inside loops
Scans Blade templates for N+1 patterns
Tracks variable types across code flow
Checks for missing eager loads

toolbox:scan-queries

Scan code for query performance issues and SQL injection risks.

php artisan toolbox:scan-queries
php artisan toolbox:scan-queries --type=raw-query --severity=critical
php artisan toolbox:scan-queries --json --fail-on-issues

Option	Description
`--path`	Path to scan (default: app)
`--json`	Output results as JSON
`--severity`	Filter by severity: `all`, `critical`, `high`, `medium`, `low`
`--type`	Filter by type: `all`, `select-star`, `missing-limit`, `loop-query`, `raw-query`, `inefficient`
`--fail-on-issues`	Exit with error code if issues found

Issue Types:

raw_query (critical): Raw SQL queries that may be vulnerable to injection
loop_query (high): Database queries executed inside loops
select_star (medium): Using SELECT * instead of specific columns
inefficient (medium): Inefficient query patterns
missing_limit (low): Queries without LIMIT clause

toolbox:scan-routes

Scan routes for missing handlers and orphaned resources.

php artisan toolbox:scan-routes
php artisan toolbox:scan-routes --missing-only
php artisan toolbox:scan-routes --orphans-only

Option	Description
`--pages-path`	Path to Inertia pages (default: resources/js/Pages)
`--views-path`	Path to Blade views (default: resources/views)
`--json`	Output results as JSON
`--missing-only`	Only show missing handlers
`--orphans-only`	Only show orphaned items

Detection Features:

Missing controller classes or methods
Orphaned controller methods (not routed)
Orphaned Blade views (not referenced)
Orphaned Inertia components (React/Vue)
Automatic framework detection (Inertia React vs Vue)

toolbox:scan-security

Scan code for common security vulnerabilities.

php artisan toolbox:scan-security
php artisan toolbox:scan-security --severity=critical
php artisan toolbox:scan-security --type=sql-injection

Option	Description
`--path`	Paths to scan (default: app/, config/, resources/views/, .env)
`--type`	Filter by vulnerability type
`--severity`	Filter by severity: `all`, `critical`, `high`, `medium`
`--json`	Output results as JSON
`--fail-on-issues`	Exit with error code if issues found

Security Detectors:

SQL Injection - Detects potential SQL injection vulnerabilities
XSS - Detects cross-site scripting vulnerabilities
Mass Assignment - Detects unguarded model assignments
Command Injection - Detects command injection risks
Hardcoded Secrets - Detects hardcoded API keys and secrets
File Operations - Detects path traversal vulnerabilities
Debug Mode - Detects debug mode enabled in production
Deserialization - Detects unsafe unserialize() calls

toolbox:scan-dead-code

Scan for unused classes, methods, functions, traits, interfaces, constants, and properties.

php artisan toolbox:scan-dead-code
php artisan toolbox:scan-dead-code --type=method --severity=high
php artisan toolbox:scan-dead-code --json --fail-on-issues

Option	Description
`--path`	Path to scan (default: app)
`--type`	Filter by type: `all`, `class`, `method`, `function`, `trait`, `interface`, `constant`, `property`
`--severity`	Filter by severity: `all`, `high`, `medium`, `low`
`--json`	Output results as JSON
`--fail-on-issues`	Exit with error code if issues found

Detection Features:

Two-pass AST analysis for accurate detection
Tracks class instantiation, method calls, and property access
Handles type hints, use statements, and inheritance
Smart exclusions for Laravel entry points (Controllers, Commands, etc.)
Excludes magic methods and framework lifecycle methods
Configurable severity per issue type

Issue Types:

unused_class (medium): Classes never instantiated or referenced
unused_method (medium/high): Methods never called (high for private)
unused_function (medium): Standalone functions never called
unused_trait (medium): Traits never used
unused_interface (low): Interfaces never implemented
unused_constant (low): Class constants never accessed
unused_property (low/medium): Properties never accessed (medium for private)

toolbox:scan-dependencies

Scan for dependency issues: high coupling, circular dependencies, and dependency injection problems.

php artisan toolbox:scan-dependencies
php artisan toolbox:scan-dependencies --type=circular --severity=critical
php artisan toolbox:scan-dependencies --max-dependencies=5 --json

Option	Description
`--path`	Path to scan (default: app)
`--type`	Filter by type: `all`, `high-coupling`, `circular`, `concrete`, `unused`, `unstable`
`--severity`	Filter by severity: `all`, `critical`, `high`, `medium`, `low`
`--max-dependencies`	Threshold for high coupling detection (default: 7)
`--json`	Output results as JSON
`--fail-on-issues`	Exit with error code if issues found

Detection Features:

Analyzes constructor dependency injection
Builds dependency graph for cycle detection
Calculates instability metrics for each class
Tracks which dependencies are actually used
Configurable allowed concrete dependencies (framework classes)

Issue Types:

circular_dependency (critical): Circular dependency chain detected (A→B→C→A)
high_coupling (high): Class has too many constructor dependencies (>7 default)
concrete_dependency (medium): Depending on concrete class instead of interface
unused_dependency (medium): Injected dependency is never used in the class
unstable_dependency (low): Stable class depends on unstable class

toolbox:scan-translations

Scan for translation issues: missing keys, unused translations, and inconsistencies.

php artisan toolbox:scan-translations
php artisan toolbox:scan-translations --locale=es
php artisan toolbox:scan-translations --type=inconsistent

Option	Description
`--path`	Paths to scan for translation usages
`--lang`	Path to lang directory (default: lang/)
`--locale`	Check specific locale only
`--type`	Filter by type: `all`, `missing`, `unused`, `inconsistent`
`--json`	Output results as JSON
`--fail-on-issues`	Exit with error code if issues found

Issue Types:

missing (medium): Translation key used but not defined
unused (low): Translation defined but never used
inconsistent (medium): Key present in some locales but missing in others

toolbox:remove-comments

Remove comments from PHP files while preserving DocBlocks.

php artisan toolbox:remove-comments
php artisan toolbox:remove-comments --path=app/Services --dry-run
php artisan toolbox:remove-comments --backup --force

Option	Description
`--path`	Directory or file to process (default: app)
`--dry-run`	Preview changes without modifying files
`--force`	Skip confirmation prompt
`--backup`	Create .bak files before modifying

Features:

Preserves DocBlocks (/** ... */)
Excludes Blade templates automatically
Shows all comments with line numbers before removal
Displays summary with bytes saved

CI/CD Integration

All scan commands support --json and --fail-on-issues flags for pipeline integration:

# GitHub Actions example
- name: Security Scan
  run: php artisan toolbox:scan-security --json --fail-on-issues

- name: N+1 Query Check
  run: php artisan toolbox:scan-n1 --severity=high --fail-on-issues

- name: Environment Check
  run: php artisan toolbox:scan-env --type=undefined --fail-on-issues

- name: Dead Code Check
  run: php artisan toolbox:scan-dead-code --severity=high --fail-on-issues

- name: Dependency Check
  run: php artisan toolbox:scan-dependencies --type=circular --fail-on-issues

Configuration

The configuration file allows you to customize scan paths, ignored patterns, and severity levels for each scanner.

Key configuration sections:

return [
    // Global settings
    'table_prefix' => 'toolbox_',
    'cache' => [
        'enabled' => true,
        'ttl' => 3600,
    ],

    // N+1 Scanner
    'n1-scanner' => [
        'paths' => ['app'],
        'models_path' => 'app/Models',
        'views_path' => 'resources/views',
    ],

    // Route Scanner
    'route-scanner' => [
        'ignore_routes' => ['debugbar.*', 'sanctum.*'],
    ],

    // Query Scanner
    'query-scanner' => [
        'paths' => ['app'],
        'ignore_patterns' => ['*Test.php', '*/migrations/*'],
    ],

    // Environment Scanner
    'env-scanner' => [
        'paths' => ['app', 'config', 'routes', 'database'],
        'system_keys' => ['APP_*', 'DB_*', 'LOG_*'],
    ],

    // Translation Scanner
    'translation-scanner' => [
        'paths' => ['app', 'resources/views'],
        'lang_path' => 'lang',
    ],

    // Dead Code Scanner
    'dead-code-scanner' => [
        'paths' => ['app'],
        'exclude_classes' => ['*Controller', '*Command', '*ServiceProvider'],
        'exclude_methods' => ['__*', 'boot', 'register', 'handle'],
    ],
];

Roadmap

Future commands and features planned for Laravel Toolbox:

Code Quality

toolbox:scan-complexity - Analyze cyclomatic complexity and suggest refactoring
toolbox:scan-dead-code - Detect unused classes, methods, and variables (implemented)
toolbox:scan-dependencies - Analyze class dependencies and coupling (implemented)
toolbox:scan-duplicates - Find duplicate or similar code blocks

Database & Models

toolbox:scan-migrations - Detect migration issues (missing indexes, large columns)
toolbox:scan-models - Validate model configurations (fillable, casts, relationships)
toolbox:generate-indexes - Suggest database indexes based on query analysis
toolbox:scan-seeders - Validate seeder data integrity

API & Routes

toolbox:scan-api - Validate API responses against documentation
toolbox:generate-openapi - Generate OpenAPI spec from routes and controllers
toolbox:scan-rate-limits - Check rate limiting configuration

Testing

toolbox:scan-coverage - Identify untested code paths
toolbox:generate-tests - Generate test stubs for controllers/services
toolbox:scan-test-quality - Analyze test quality and assertions

Performance

toolbox:scan-cache - Detect caching opportunities
toolbox:scan-lazy-load - Find assets that should be lazy-loaded
toolbox:profile-boot - Analyze application boot performance

Code Generation

toolbox:make-service - Generate service class with interface
toolbox:make-action - Generate single-action class
toolbox:make-dto - Generate data transfer object
toolbox:make-enum - Generate PHP enum with methods

Maintenance

toolbox:cleanup-logs - Clean old log files with retention policy
toolbox:cleanup-cache - Clear stale cache entries
toolbox:cleanup-storage - Find orphaned files in storage

Documentation

toolbox:generate-docs - Generate API documentation from DocBlocks
toolbox:scan-docblocks - Validate DocBlock completeness

DevOps

toolbox:check-config - Validate configuration for production
toolbox:check-permissions - Verify file/directory permissions
toolbox:check-health - Comprehensive application health check

Contributing

Contributions are welcome! Please ensure:

Code follows PSR-12 and uses strict types
All new commands extend BaseCommand
Tests are written using Pest
Run composer format before submitting

License

MIT License. See LICENSE for details.

stratos / laravel-toolbox

Maintainers

Details

README

Requirements

Installation

Commands

toolbox:scan-env

toolbox:scan-n1

toolbox:scan-queries

toolbox:scan-routes

toolbox:scan-security

toolbox:scan-dead-code

toolbox:scan-dependencies

toolbox:scan-translations

toolbox:remove-comments

CI/CD Integration

Configuration

Roadmap

Code Quality

Database & Models

API & Routes

Testing

Performance

Code Generation

Maintenance

Documentation

DevOps

Contributing

License