README

1,755 engineering checks for building Laravel applications that are secure, correct, auditable, and maintainable.

Born from repeated production audits of a financial platform. Expanded into a universal standard for any Laravel project.

Installation

composer require --dev chuxolab/laravel-fortress

Then run the interactive installer:

php artisan fortress:install

This walks you through setting up:

• AI rules for your editor (Claude Code, Cursor, Windsurf, Copilot — auto-detected)
• Git hooks — 10 safety hooks for catching debug statements, formatting issues, secret leaks, and AI auto-merge
• CI workflow — GitHub Actions PR protection template
• Config — .fortress.yml for per-project rule tuning

You can also install components individually:

php artisan fortress:install --hooks      # Git hooks only
php artisan fortress:install --rules      # AI rules only
php artisan fortress:install --ci         # CI workflow only
php artisan fortress:install --all        # Everything, no prompts

Non-Laravel PHP projects

curl -sL https://raw.githubusercontent.com/oilmonegov/laravel-fortress/main/install.sh | bash

What You Get

1. The Checklist — 1,755 checks across 14 parts

A comprehensive engineering reference. Every check is a - [ ] item you can tick off during code review, sprint planning, onboarding, or audit prep.

Read the full list in one file: checklist.md

2. AI Rules — Your editor enforces the checks automatically

The AI skill system teaches your coding assistant all 1,755 checks. It adapts to your project's PHP version, Laravel version, database, and installed packages at runtime.

3. Git Hooks — Safety rails for AI-assisted development

AI agents write code fast. These hooks catch mistakes at the git level before they reach your repository.

Plus 5 stub hooks (server-side templates) installable with --with-stubs. See hooks/README.md.

4. Compliance Scanner

php artisan fortress:check

Scans your codebase for common violations:

Auto-fix what's fixable:

php artisan fortress:check --fix

5. Deep Code Review

php artisan fortress:review

Runs 52 automated checks across all 14 parts — far deeper than fortress:check. Every finding documents both the problem and the recommended solution, with code snippets.

php artisan fortress:review my-sprint        # Named review
php artisan fortress:review --part=P01       # Specific parts only
php artisan fortress:review --part=P01 --part=P05
php artisan fortress:review --severity=critical  # Only critical findings
php artisan fortress:review --select         # Interactive part selection
php artisan fortress:review --format=console # Print findings to terminal

Reports are saved to docs/fortress-reviews/review-{name}-{date}-{time}-{id}.md with:

• Summary table (findings by severity)
• Findings grouped by part, then severity (critical first)
• Each finding shows: rule ID, file:line, problem description, solution, code snippet

6. PR Merge Protection

A GitHub Actions workflow template that:

• Runs Pint, PHPStan, tests, and composer audit on every PR
• Requires human approval before merge (blocks bot/AI auto-merge)
• Verifies review count meets minimum threshold

Installed to .github/workflows/fortress-pr-protection.yml — configure branch protection rules on GitHub to require these checks.

Configuration

After installation, edit .fortress.yml in your project root:

fortress:
  version: "1.1.0"

  # Enable/disable parts and set enforcement levels
  parts:
    P01_application_security:
      enabled: true
      enforcement: strict        # strict | standard | relaxed

    P05_financial_monetary:
      enabled: true
      enforcement: strict        # Critical for fintech apps

    P10_frontend:
      enabled: false             # Disable for API-only projects

  # Override specific rules
  # rules:
  #   F-P08-042:
  #     enabled: false
  #     reason: "We use a custom ORM"

  minimum_severity: warning      # critical | warning | info

  # Git hooks — all enabled by default, opt-out per hook
  git_hooks:
    enabled: true
    pre_commit:
      run_pint: true
      check_debug: true
      check_secrets: true
      max_file_size_kb: 500
    pre_push:
      run_tests: true
      run_phpstan: true
      block_direct_push: true

  # AI merge protection — strongly recommended
  merge_protection:
    block_ai_auto_merge: true
    protected_branches: [main, master, production]

Full template: rules/.fortress.example.yml

Artisan Commands

Using the Fortress

During Code Review

1. Map the PR's changed files to fortress Parts (controllers → P01/P03/P08, models → P09, money logic → P05)
2. Ask your AI assistant: "Review this PR against fortress Parts P01 and P08. Flag violations with rule IDs."
3. Reference findings as [F-P01-003] in PR comments — traceable and searchable

During Sprint Planning

Scan the relevant Parts before scoping a feature. Identify security, correctness, and testing requirements upfront — not as afterthoughts.

For Onboarding

Give new team members Parts VI–VIII (PHP, Clean Code, Laravel Mastery) as required reading. Faster than explaining conventions one PR at a time.

As an Audit Checklist

Walk through the full checklist systematically when preparing for a security audit, compliance review, or SOC 2 / ISO 27001 assessment.

With Laravel Boost (recommended)

Laravel Boost gives your AI agent direct access to your running app — database schema, routes, config, logs, Artisan commands, and Tinker. This transforms fortress enforcement from static code reading to live application verification.

composer require laravel/boost --dev

With Boost installed, your AI agent can verify fortress rules against your actual database schema, route list, config values, and application state. See rules/README.md for the full tool-to-fortress mapping.

Scope

Laravel 9–12 · PHP 8.1–8.4 · MySQL / PostgreSQL · Vue / React / Blade · Tailwind CSS · Redis · Pest / PHPUnit

The AI skill system is version-agnostic — it detects your project's actual versions and applies only the relevant rules. A PHP 8.1 project won't be told to use PHP 8.4 features.

Not a Style Guide

This does not prescribe tabs vs spaces or where to put braces. It prescribes engineering discipline: how to handle money without rounding errors, how to prevent race conditions on financial records, how to structure authentication so privilege escalation is impossible, how to design migrations that don't cause downtime.

Style is preference. Discipline is survival.

Contributing

Contributions welcome. See CONTRIBUTING.md.

The bar: "Would this have prevented a real bug, security vulnerability, or production incident?" If yes, it belongs. If it's preference, it doesn't.

License

MIT

Built with hard-won lessons from production. Maintained by the community.