Production-ready agents, skills, commands, rules, and hooks for PHP development with Claude Code.
Inspired by everything-claude-code, adapted and extended for the PHP ecosystem.
# Add marketplace
/plugin marketplace add ekut/claude-code-php-toolkit
# Install plugin
/plugin install claude-code-php-toolkit@claude-code-php-toolkitThis installs agents, skills, commands, and hooks automatically.
The plugin can be installed at different scopes depending on your setup:
| Scope | Flag | Where the setting is stored | Best for |
|---|---|---|---|
user |
default | ~/.claude/settings.json |
PHP-only developers. The plugin is available in all your projects. |
project |
--scope project |
.claude/settings.json (committed to git) |
Teams using Claude Code. Every team member gets the plugin automatically. |
local |
--scope local |
.claude/settings.local.json (gitignored) |
Solo Claude Code user in a team. Plugin is active in this project but doesn't affect teammates. |
How to choose:
- You work only on PHP projects → install with default
userscope - You work on PHP, Go, Rust, etc. → install with
projectorlocalscope in your PHP projects only - Your whole team uses Claude Code → install with
projectscope so it's shared via git - You're the only Claude Code user on the team → install with
localscope
Hooks are safe at any scope: they only trigger on *.php files and check for tools (vendor/bin/...) before running.
Claude Code plugins cannot distribute rules automatically. Install them manually:
# Clone the repo
git clone https://github.com/ekut/claude-code-php-toolkit.git
cd claude-code-php-toolkit
# Run the installer (installs to ~/.claude/rules/ — global scope)
./install.shThis copies rules to ~/.claude/rules/common/ and ~/.claude/rules/php/. Rules installed this way apply to all projects. If you want rules only in a specific project, copy them to your project's .claude/rules/ instead:
# Project-scoped rules (alternative)
cp -r claude-code-php-toolkit/rules/ /path/to/your/project/.claude/rules//php-review # Review PHP code for PSR compliance, security, performance
/php-tdd # TDD workflow with PHPUnit or Pest
/php-analyze # Run PHPStan + PHP-CS-Fixer + Psalm
Copy the example CLAUDE.md template into your PHP project:
cp claude-code-php-toolkit/examples/CLAUDE.md /path/to/your/php-project/CLAUDE.mdCustomize it for your project's specific needs.
| Agent | Description |
|---|---|
| php-reviewer | PHP code review — PSR compliance, type safety, security, performance |
| php-tdd-guide | TDD specialist — Red-Green-Refactor with PHPUnit and Pest |
| php-security-reviewer | Security audit — OWASP Top 10, SQL injection, XSS, CSRF |
| php-build-resolver | Composer & PHP build error resolution |
| php-architect | System architecture — neutral assessment, 3 architectural schools, two-phase recommendation |
| php-planner | Feature planning — phased implementation, risks, deployment |
| php-database-reviewer | Database review — schemas, migrations, queries, ORM (MySQL & PostgreSQL) |
| php-doc-updater | Documentation — PHPDoc, codemaps, API stubs |
| php-refactor-cleaner | Dead code cleanup — unused imports, packages, refactoring |
| php-e2e-runner | E2E & integration testing — Symfony, Laravel, framework-agnostic |
| Skill | Description |
|---|---|
| php-patterns | Modern PHP 8.1+ idioms — enums, readonly, match, fibers |
| php-coding-standards | PSR-1, PSR-4, PSR-12, PER-CS 2.0, PHP-CS-Fixer, Pint |
| php-testing | PHPUnit 10+, Pest 2+, mocking, coverage, data providers |
| php-static-analysis | PHPStan, Psalm, PHP-CS-Fixer, Rector |
| php-verification | 6-phase verification pipeline — Composer, style, analysis, tests, security, diff |
| php-architecture-ddd | DDD — Rich Domain, Hexagonal, CQRS, Bounded Contexts |
| php-architecture-service-layer | Service-Oriented — Service Layer, Transaction Scripts, DTOs |
| php-architecture-action-based | Action-Based — Single-action controllers, ADR, Command/Query |
| doctrine-orm-patterns | Doctrine ORM 3.x — entities, relationships, DQL, migrations, performance |
| doctrine-odm-patterns | Doctrine MongoDB ODM — documents, references, query builder, aggregation |
| php-deployment | Docker, php-fpm, Swoole, FrankenPHP, Deployer, CI/CD, zero-downtime |
| symfony-patterns | Symfony 6+/7+ architecture — service container, autowiring, controllers, events, Messenger |
| laravel-patterns | Laravel 10+/11+ architecture — routing, Eloquent, middleware, events, queues, validation |
| php-api-design | REST API design — resource naming, status codes, pagination, versioning, rate limiting |
| php-security-scanning | Security scanning pipeline — Composer audit, Psalm taint, PHPStan security, secrets, debug detection |
| php-security-patterns | Security implementation — authentication, authorization, CORS, security headers, PII protection |
| php-error-handling | Error handling — exception hierarchies, RFC 9457 Problem Details, structured logging, retry patterns |
| content-hash-cache | SHA-256 content-hash caching — deterministic cache keys, file-based storage, PSR-16 integration |
| eval-harness | Evaluation framework — PHP graders, metrics (pass@k), 4-phase EDD workflow |
| strategic-compact | Strategic /compact — phase transitions, survival map, context preservation |
| iterative-retrieval | Progressive context retrieval — 4-phase DISPATCH-EVALUATE-REFINE-LOOP, PHP search patterns |
| search-first | Research-before-coding workflow — search Packagist, Spatie, League before writing custom code |
| continuous-learning | Auto-extract PHP patterns from sessions — instinct model, confidence scoring, hooks |
| skill-stocktake | Skill quality audit — Quick Scan and Full Stocktake modes, verdicts, consolidation |
| Command | Description |
|---|---|
/audit-packages |
Audit package references against verified-packages.json allowlist |
/php-analyze |
Run PHPStan + PHP-CS-Fixer + Psalm |
/php-build-fix |
Incrementally fix Composer conflicts, autoloading, and build errors |
/php-checkpoint |
Create, verify, and list workflow checkpoints |
/php-evolve |
Cluster related instincts into skills, commands, or agents |
/php-instinct-export |
Export learned instincts to YAML for sharing |
/php-instinct-import |
Import instincts from files or URLs with conflict detection |
/php-instinct-status |
Show instincts grouped by domain with confidence scores |
/php-learn |
Extract reusable patterns from session with self-evaluation |
/php-orchestrate |
Sequential agent workflow: plan, build, test, review, security |
/php-plan |
Create phased implementation plan before coding (read-only) |
/php-refactor-clean |
Detect and remove dead code with test verification |
/php-review |
Comprehensive PHP code review |
/php-tdd |
TDD workflow with PHPUnit or Pest |
/php-test-coverage |
Analyze coverage gaps, generate missing tests for 80%+ |
/php-update-codemaps |
Generate token-lean architecture documentation |
/php-update-docs |
Sync PHPDoc, env docs, Composer scripts with codebase |
/php-verify |
Full verification pipeline — Composer, syntax, style, analysis, tests, security |
| Rule | Scope |
|---|---|
| git-workflow | Conventional commits, branching, PR workflow |
| development-workflow | Plan > TDD > Review > Commit |
| supply-chain-safety | Package verification, hallucination prevention, allowlist |
| coding-style | PSR-12/PER-CS, strict types, final by default |
| testing | PHPUnit/Pest requirements, 80% coverage |
| security | PDO, htmlspecialchars, password_hash, CSRF |
| performance | OPcache, generators, N+1 prevention |
| Hook | Trigger |
|---|---|
| PHP-CS-Fixer on edit | Auto-formats PHP files after Edit/Write |
| PHPStan on edit | Type-checks PHP files after Edit/Write |
| Markdown table formatter | Aligns table columns in .md files after Edit/Write |
Hooks are auto-loaded from hooks/hooks.json by Claude Code (v2.1+). They are not declared in plugin.json to avoid the duplicate hooks error.
Session behavior presets — injected via --system-prompt to switch Claude's working mode for the entire session.
| Context | Mode |
|---|---|
| php-dev | Active development — type-safe, test-first, Composer workflow |
| php-review | Code review — security, types, PSR compliance, severity-grouped output |
| php-refactor | Refactoring — structural changes with test-guarded discipline |
| php-debug | Debugging — reproduce, diagnose, fix cycle |
| php-legacy | Legacy modernization — incremental migration to PHP 8.1+ |
Usage:
claude --system-prompt "$(cat contexts/php-dev.md)"Or create shell aliases:
alias claude-php='claude --system-prompt "$(cat contexts/php-dev.md)"'
alias claude-review='claude --system-prompt "$(cat contexts/php-review.md)"'Contexts are NOT part of the plugin system — they are standalone markdown files used via CLI flag.
- Claude Code v1.0.33+ (plugin system), v2.1+ recommended (auto-loading hooks)
- PHP 8.1 or higher
- Composer
composer require --dev phpunit/phpunit
composer require --dev phpstan/phpstan
composer require --dev friendsofphp/php-cs-fixer
# or for Laravel projects:
composer require --dev laravel/pintThe toolkit is framework-agnostic at its core. The directory structure supports future expansion:
rules/
├── common/ # Generic rules (git, workflow, supply-chain safety)
├── php/ # Core PHP rules (current)
├── symfony/ # Symfony rules (future)
└── laravel/ # Laravel rules (future)
skills/
├── php-patterns/ # Core PHP idioms
├── php-coding-standards/ # PSR, PER-CS, formatting
├── php-testing/ # PHPUnit, Pest
├── php-static-analysis/ # PHPStan, Psalm, Rector
├── php-verification/ # 6-phase verification pipeline
├── php-architecture-ddd/ # DDD, Hexagonal, CQRS
├── php-architecture-service-layer/ # Service Layer, Transaction Scripts
├── php-architecture-action-based/ # Action-Based, ADR
├── doctrine-orm-patterns/ # Doctrine ORM entities, DQL, migrations
├── doctrine-odm-patterns/ # Doctrine MongoDB ODM documents, queries
├── php-deployment/ # Docker, runtimes, CI/CD, Deployer
├── symfony-patterns/ # Symfony 6+/7+ patterns
├── laravel-patterns/ # Laravel 10+/11+ patterns
├── php-api-design/ # REST API design patterns
├── php-security-scanning/ # Security scanning pipeline
├── php-security-patterns/ # Security implementation patterns
├── php-error-handling/ # Error handling & structured logging
├── content-hash-cache/ # Content-hash caching pattern
├── eval-harness/ # Evaluation framework for AI sessions
├── strategic-compact/ # Strategic /compact guide
├── iterative-retrieval/ # Progressive context retrieval
├── search-first/ # Research-before-coding workflow
├── continuous-learning/ # Auto-extract patterns from sessions
└── skill-stocktake/ # Skill quality audit framework
contexts/
├── php-dev.md # Development mode
├── php-review.md # Code review mode
├── php-refactor.md # Refactoring mode
├── php-debug.md # Debugging mode
└── php-legacy.md # Legacy modernization mode
- Symfony support (routing, services, Doctrine, Twig)
- Laravel support (Eloquent, Blade, Artisan, queues)
- Doctrine ORM patterns
- API Platform support
- PHP package development skill (library authors)
- Docker/Compose integration hooks
- CI/CD pipeline templates (GitHub Actions, GitLab CI)