shieldci/laravel

ShieldCI Laravel Package

Automated code analysis for Laravel applications - 73 open-source analyzers covering security, performance, reliability, code quality, and best practices.

Built on top of shieldci/analyzers-core - a shared, framework-agnostic foundation for static analysis tools.

Requirements

• PHP 8.1 or higher
• Laravel 9.x, 10.x, 11.x, 12.x, 13.x

Architecture

This package uses shieldci/analyzers-core for its core analyzer functionality, providing:

• Type-safe enums (Status, Category, Severity)
• Immutable value objects (Location, Issue, AnalyzerMetadata)
• Abstract base classes (AbstractAnalyzer, AbstractFileAnalyzer)
• AST parsing with nikic/php-parser
• Result formatters (JSON, Console)
• Comprehensive utilities (CodeHelper, FileParser)

Installation

composer require shieldci/laravel

Configuration

Publish the configuration file:

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

Add your ShieldCI credentials to .env (your API token is displayed when you create a project in the ShieldCI dashboard):

SHIELDCI_TOKEN=your-api-token
SHIELDCI_PROJECT_ID=your-project-id

Usage

Run the analysis:

php artisan shield:analyze

Options

Run a specific analyzer:

php artisan shield:analyze --analyzer=sql-injection

Run analyzers by category:

php artisan shield:analyze --category=security

Output as JSON:

php artisan shield:analyze --format=json

Save report to file:

php artisan shield:analyze --output=report.json

Send results to ShieldCI platform:

php artisan shield:analyze --report

Attach Git metadata to the report with --git-branch, --git-commit, --git-pr-number, --git-repository and --git-base-branch.

Schedule analysis with trigger tracking:

// Laravel 11+, either in routes/console.php
use Illuminate\Support\Facades\Schedule;

Schedule::command('shield:analyze --triggered-by=scheduled --report')->daily();

// Laravel 11+, or in bootstrap/app.php
->withSchedule(function (Schedule $schedule) {
    $schedule->command('shield:analyze --triggered-by=scheduled --report')->daily();
})

// Laravel 9-10 (app/Console/Kernel.php)
$schedule->command('shield:analyze --triggered-by=scheduled --report')->daily();

Advanced Features

Baseline Support (Gradual Adoption)

Generate a baseline to suppress existing issues and only catch new ones:

# Generate baseline from current state (all analyzers, respects config)
php artisan shield:baseline

# Generate baseline for CI mode (only CI-compatible analyzers)
php artisan shield:baseline --ci

# Merge with existing baseline
php artisan shield:baseline --merge

# Analyze against baseline (only NEW issues reported)
php artisan shield:analyze --baseline

CI Mode (Optimized for CI/CD)

Skip slow or network-dependent analyzers in CI/CD:

# Run in CI mode (only CI-compatible analyzers)
php artisan shield:analyze --ci

Whitelist/blacklist specific analyzers in config/shieldci.php:

'ci_mode_analyzers' => ['sql-injection', 'xss-vulnerabilities', 'csrf-protection'],
'ci_mode_exclude_analyzers' => ['vulnerable-dependencies', 'frontend-vulnerable-dependencies'],

Don't Report (Exit Code Control)

Run informational analyzers without failing CI:

// config/shieldci.php
'dont_report' => [
    'missing-docblock',    // Informational only
    'commented-code',      // Won't fail CI
],

Compact Output

Limit displayed issues per check:

# Show only 3 issues per check
SHIELDCI_MAX_ISSUES=3 php artisan shield:analyze

Environment-Aware Analyzers

Some analyzers are only relevant in specific environments. Custom environment names are mapped to the standard ones through environment_mapping.

Standard environments (no configuration needed):

• local - Local development
• development - Development server
• staging - Staging/pre-production
• production - Production
• testing - Automated testing

Custom environments (configure mapping):

// config/shieldci.php
'environment_mapping' => [
    'production-us' => 'production',
    'production-eu' => 'production',
    'staging-preview' => 'staging',
    'prod-1' => 'production',
],

How it works:

• Analyzers declare which environments they're relevant for (e.g., ['production', 'staging'])
• Custom environment names you list in environment_mapping are mapped to their standard type; an unmapped name is used as-is
• Analyzers run only in their relevant environments

Example: AutoloaderOptimizationAnalyzer only runs in production/staging environments.

Available Analyzers

ShieldCI includes 73 comprehensive analyzers across five categories:

→ Full Analyzer Reference: all 155 analyzers (73 free + 82 Pro) with examples and fix guidance

ShieldCI Pro

ShieldCI Pro adds 82 advanced analyzers on top of the free package, 155 in total:

Highlights:

• Security: command injection, SSRF, XXE, object injection, GDPR compliance, hard-coded credentials, cryptographic weaknesses; framework-specific checks for Sanctum, Horizon, Telescope, Nova, Livewire, Inertia, and FilamentPHP
• Performance: Redis rate limiting, CDN/HTTP2/compression header analysis, lazy collection opportunities, FilamentPHP table optimization
• Reliability: health check and alerting config, job queue config, Horizon status and provisioning, Redis eviction policy, Laravel Vapor config

→ Upgrade to Pro

Configuration Options

See config/shieldci.php for all available configuration options.

Fail Conditions

Configure when the analysis should fail:

'fail_on' => 'high',     // default; never, critical, high, medium, low
'fail_threshold' => 80,  // Minimum score to pass (0-100)

Paths

Configure which paths to analyze:

'paths' => [
    'analyze' => ['app', 'config', 'database', 'routes', 'resources/views'],
],

'excluded_paths' => [
    'vendor/*',
    'node_modules/*',
    'storage/*',
    'bootstrap/cache/*',
    'tests/*',
],

Disabling Analyzers

Turn off specific analyzers by ID:

'disabled_analyzers' => [
    'missing-docblock',
],

Ignoring Errors

Remove specific issues from the report by analyzer ID, path and message. Unlike dont_report, matching issues do not appear in console or JSON output.

'ignore_errors' => [
    'xss-vulnerabilities' => [
        ['path' => 'app/Http/Controllers/Legacy.php', 'message' => 'Unescaped blade output'],
        ['path_pattern' => 'app/Legacy/*.php'],
    ],
    'debug-mode' => [
        ['message_pattern' => 'Ray debugging*'],
    ],
],

Each rule takes a path (exact) or path_pattern (glob), and/or a message (exact) or message_pattern (wildcards). Given both a path and a message, both must match.

Testing

composer test
composer test-coverage  # 98%+ code coverage
composer analyse        # PHPStan Level 9

Documentation

• Full Documentation - Installation, configuration, and analyzer guides
• Getting Started - Quick start guide
• Analyzer Reference - All 155 analyzers (73 free + 82 Pro) with examples and fix guidance
• Analyzers Core - Core package documentation

License

MIT License. See LICENSE file for details.