PHPackages                             otatechie/laravel-spotlight - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. otatechie/laravel-spotlight

ActiveLibrary

otatechie/laravel-spotlight
===========================

A lighthouse-style diagnostics tool that scans Laravel applications for performance, security, and architecture issues.

v1.1.0(3mo ago)950[2 PRs](https://github.com/otatechie/laravel-spotlight/pulls)MITPHPPHP ^8.1CI passing

Since Jan 22Pushed 1mo agoCompare

[ Source](https://github.com/otatechie/laravel-spotlight)[ Packagist](https://packagist.org/packages/otatechie/laravel-spotlight)[ Docs](https://github.com/otatechie/laravel-spotlight)[ GitHub Sponsors](https://github.com/otatechie)[ RSS](/packages/otatechie-laravel-spotlight/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (3)Dependencies (12)Versions (7)Used By (0)

Laravel Spotlight
=================

[](#laravel-spotlight)

A lighthouse-style diagnostics tool that scans Laravel applications for performance, security, and architecture issues. Built with a modular rule system that makes it easy to extend and customize.

[![Latest Version on Packagist](https://camo.githubusercontent.com/e8e6e740fb06ea72dbec6c1ff52ac2df1a7d9a56c6a2cf0c2e35db244db47e46/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6f74617465636869652f6c61726176656c2d73706f746c696768742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/otatechie/laravel-spotlight)[![GitHub Tests](https://camo.githubusercontent.com/cb8c5727da221033e4b3a20115574ae04b460e2cdc7454c31f42997f7be50179/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6f74617465636869652f6c61726176656c2d73706f746c696768742f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/otatechie/laravel-spotlight/actions/workflows/run-tests.yml)[![Code Style](https://camo.githubusercontent.com/6b1775a57891e71b11bab6d12b6318fed47dfbc8a4777009f8758f22b0204c9b/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6f74617465636869652f6c61726176656c2d73706f746c696768742f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/otatechie/laravel-spotlight/actions/workflows/fix-php-code-style-issues.yml)[![Total Downloads](https://camo.githubusercontent.com/75fc538eb75045c5dc080cc1584b35ce861691165b97378c0db7cd0a10aae8f4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6f74617465636869652f6c61726176656c2d73706f746c696768742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/otatechie/laravel-spotlight)

What is Spotlight?
------------------

[](#what-is-spotlight)

**Spotlight is NOT:**

- ❌ **Code formatter** - Spotlight doesn't format or fix your code style
- ❌ **Linter** - Spotlight doesn't enforce coding standards or syntax rules
- ❌ **Debugger** - Spotlight doesn't debug runtime errors or exceptions

**Spotlight IS:**

- ✅ **Diagnostic Scanner** - Identifies potential issues before they become problems
- ✅ **Best Practices Advisor** - Points out improvements based on Laravel best practices
- ✅ **Performance Analyzer** - Finds performance bottlenecks and optimization opportunities
- ✅ **Security Auditor** - Flags security vulnerabilities and misconfigurations
- ✅ **Architecture Mentor** - Gives gentle tips on code organization
- ✅ **Guidance Tool** - Just suggestions, you're in control

Laravel Spotlight helps you identify and fix issues in your Laravel application before they become problems. It scans your application for:

- **Performance Issues**: Missing caches, inefficient queue drivers, N+1 queries
- **Security Vulnerabilities**: Debug mode in production, insecure configurations
- **Architecture Problems**: Fat controllers, route closures, code organization

Philosophy
----------

[](#philosophy)

**Spotlight provides guidance, not enforcement. No shaming, no judgment.**

Laravel Spotlight is a **friendly mentor**, not an angry linter. We help you improve your code with gentle suggestions, not shame or rigid rules.

- **No Shaming** - We use "could improve" and "consider" instead of "MUST fix" or "WRONG"
- **User Control** - Every rule can be disabled if it doesn't fit your project
- **Objective vs Advisory** - Security/performance issues are flagged firmly; architecture suggestions are gentle
- **Fast & Lightweight** - Executes in < 1 second using lightweight checks

See [Why Spotlight?](docs/WHY_SPOTLIGHT.md) to see how it compares to other tools.

Features
--------

[](#features)

- 🔍 **20 Built-in Rules** - Covers performance, security, and architecture
- 🧩 **Modular Rule System** - Easy to extend with custom rules (auto-detection eliminates boilerplate)
- ⚙️ **Full User Control** - Enable/disable any rule that doesn't fit your project
- 🎯 **Severity Scoring** - 4-level severity system with health score calculation
- ⚡ **Lightning Fast** - Executes in < 1 second
- 🛡️ **Error Handling** - One rule failure won't crash the entire scan
- 📊 **Multiple Output Formats** - Table and JSON output formats
- 🛠️ **Developer Tools** - Rule generator, rule listing, CI/CD exit codes
- 📖 **Documentation URLs** - Rules can link to detailed documentation
- 🎨 **PHP 8.1+ Enums** - Type-safe severity and rule type enums

Installation
------------

[](#installation)

You can install the package via composer:

```
composer require otatechie/laravel-beacon
```

You can publish the config file with:

```
php artisan vendor:publish --tag="spotlight-config"
```

The config file lets you:

- Enabling/disabling specific rules
- Registering custom rules
- Setting severity threshold
- Configuring error handling
- Enabling debug mode

See the [configuration documentation](docs/EXAMPLES.md#configuration-examples) for details.

Usage
-----

[](#usage)

### Basic Scanning

[](#basic-scanning)

Run a full scan of your application:

```
php artisan spotlight:scan
```

### Scan Specific Categories

[](#scan-specific-categories)

Scan only performance issues:

```
php artisan spotlight:scan --category=performance
```

Scan multiple categories:

```
php artisan spotlight:scan --category=performance --category=security
```

### Get JSON Output

[](#get-json-output)

```
php artisan spotlight:scan --format=json
```

### Filter by Severity

[](#filter-by-severity)

Only show critical issues:

```
php artisan spotlight:scan --severity=critical
```

### Exit Codes for CI/CD

[](#exit-codes-for-cicd)

Spotlight uses exit codes for CI/CD integration:

**Exit Code Mapping:**

- `0` - No issues found (clean scan)
- `1` - Only low severity issues found
- `2` - Medium or high severity issues found
- `3` - Critical issues found

**Usage Examples:**

```
# Default: Auto-detect exit code based on severity
php artisan spotlight:scan

# Fail only on critical issues
php artisan spotlight:scan --fail-on=critical

# Fail on high or critical issues
php artisan spotlight:scan --fail-on=high

# Fail on any issues (including low)
php artisan spotlight:scan --fail-on=low
```

**GitHub Actions Example:**

```
- name: Run Spotlight Scan
  run: php artisan spotlight:scan || exit 1
```

### List Available Rules

[](#list-available-rules)

See all available rules:

```
php artisan spotlight:rules
```

Get details about a specific rule:

```
php artisan spotlight:rules --rule=performance.config-cache
```

### Create Custom Rules

[](#create-custom-rules)

Generate a new rule class:

```
php artisan spotlight:make-rule MyCustomRule --category=performance --type=objective
```

This creates a rule class with proper structure and auto-registers it.

### Programmatic Usage

[](#programmatic-usage)

```
use Otatechie\Spotlight\Spotlight;

$spotlight = app(Spotlight::class);
$results = $spotlight->scan(['performance', 'security']);

// Access results
$summary = $results['summary'];
$categories = $results['categories'];
```

Rule Types & Severity
-------------------------

[](#rule-types--severity)

Spotlight uses a two-dimensional classification system:

### Rule Types

[](#rule-types)

- **Objective Rules** (`type: 'objective'`) - Firm recommendations based on hard facts

    - Examples: Debug enabled, config not cached, insecure cookies
    - Spotlight can be firm with these
- **Advisory Rules** (`type: 'advisory'`) - Gentle suggestions based on best practices

    - Examples: Fat controllers, route closures, folder structure
    - Spotlight should be gentle with these

### Severity Levels

[](#severity-levels)

Spotlight uses 4 severity levels with numeric weights for scoring:

LevelWeightPurpose`critical`100Production-breaking / security risk`high`70Serious performance or stability issue`medium`40Performance issues or config problems`low`10Minor improvement / suggestion**Health Score:** Spotlight calculates a health score (0-100%) based on severity weights, giving you a quick overview of your application's status.

**Category-Based Defaults:** If a rule doesn't specify severity, it inherits from its category:

- Security rules default to `high`
- Performance rules default to `medium`
- Architecture rules default to `low`

All rules can be disabled in `config/spotlight.php` if they don't apply to your project.

Built-in Rules
--------------

[](#built-in-rules)

### Performance Rules

[](#performance-rules)

- **Config Cache**: Checks if config cache is enabled in production
- **Route Cache**: Checks if route cache is enabled in production
- **Queue Sync Driver**: Warns about sync queue driver in production
- **View Cache**: Checks if view cache is enabled
- **Event Cache**: Checks if event cache is enabled
- **N+1 Queries**: Detects potential N+1 query problems
- **Missing Chunking**: Identifies large dataset operations without chunking

### Security Rules

[](#security-rules)

- **App Debug Enabled**: Critical check for debug mode in production
- **Insecure Session Driver**: Warns about insecure session drivers
- **HTTPS Enforcement**: Checks if HTTPS is properly enforced
- **Cookie Secure Flag**: Verifies secure cookie configuration

### Architecture Rules

[](#architecture-rules)

- **Route Closure Usage**: Detects route closures preventing caching
- **Large Controller Detection**: Identifies controllers exceeding configurable line threshold
- **Missing API Resources**: Detects API routes without API resources
- **Missing Form Requests**: Detects controllers using inline validation instead of Form Requests
- **Direct ENV Usage**: Finds direct `env()` calls that should use `config()`
- **Queries in Blade**: Detects database queries in Blade templates
- **Mass Assignment Protection**: Checks for missing `$fillable` or `$guarded`
- **Logic in Routes**: Identifies complex logic in route files
- **JS/CSS in Blade**: Finds inline JavaScript and CSS in templates

Creating Custom Rules
---------------------

[](#creating-custom-rules)

Want to add your own rules? It's easy. Check out the [Creating Rules Guide](docs/CREATING_RULES.md) for the full walkthrough.

### Quick Example

[](#quick-example)

Here's how simple it is:

```