README

Cursor Rules for PHP and Laravel

Cursor rules for PHP and Laravel — a complete set of .mdc rule files and Agent skills for Cursor, Claude Code, and Codex. One package for PHP and Laravel cursor rules: coding standards, testing, and conventions. The installer discovers the project root (via composer.json lookup from the current directory), mirrors the rules/ directory into the editor's rules path and the skills/ directory into the editor's skills path, and copies or symlinks every file into the target project. Use cursor rules for PHP and Laravel to keep every edit aligned with enforced standards, plus comprehensive Agent skills for issue resolution, bug fixing, code review, security analysis, refactoring, testing, and package review.

Why This Package

cursor rules for PHP and Laravel in one Composer-installable package
unified PHP coding guidelines for PHP 8.4 projects
Pest-based testing with mandatory code analysis and 100% coverage
strong focus on clean code: typed properties, SRP, no redundant comments
23 comprehensive Agent skills for automated workflows (v0.7.1)
fast onboarding inside development repositories

Installation

composer require pekral/cursor-rules --dev
vendor/bin/cursor-rules install --editor=cursor

The --editor flag is required. Use it to choose the target agent:

cursor: .cursor/rules, .cursor/skills
claude: .claude/rules, .claude/skills, and when HOME/USERPROFILE is set also ~/.claude/skills
codex: .codex/rules, .codex/skills, and when HOME/USERPROFILE is set also ~/.codex/skills
all: all of the above (Cursor, Claude, Codex in project + home)

When the package is required via Composer, sources are read from vendor/pekral/cursor-rules/rules and vendor/pekral/cursor-rules/skills.

Important: By default, the installer only copies missing files and keeps existing content untouched. Use the --force flag to overwrite existing files: vendor/bin/cursor-rules install --force. This is particularly useful when you want to update rules to their latest versions or when you've made local changes that should be replaced. The file .cursor/rules/project.mdc and CLAUDE.md are never overwritten once they exist in the target project, so you can safely customize them.

Automatic Installation via Composer Plugin

By default, the Composer plugin does not auto-install rules on composer install or composer update. To enable automatic installation, add the following to your project's composer.json:

{
  "extra": {
    "cursor-rules": {
      "auto-install": true,
      "editor": "claude"
    }
  }
}

Option	Description	Default
`auto-install`	Enable automatic install on `composer install/update`.	`false`
`editor`	Target editor for auto-install (`cursor`, `claude`, `codex`, `all`).	`cursor`

If you prefer manual control, simply call vendor/bin/cursor-rules install in your Composer post-update-cmd scripts with the desired flags.

Installing rules from GitHub (Cursor only)

You can use this repository as a Remote Rule in Cursor without installing the package via Composer:

Open Cursor Settings → Rules.
In the Project Rules section, click Add Rule.
Select Remote Rule (Github).
Enter the repository URL: https://github.com/pekral/cursor-rules.

Cursor will fetch and apply the rules from the repository. Note: this method provides rules only; Agent skills are installed into your project when you use the Composer-based installation above.

Available Commands

vendor/bin/cursor-rules help                                  # print help
vendor/bin/cursor-rules install --editor=cursor               # install for Cursor
vendor/bin/cursor-rules install --editor=claude               # install for Claude
vendor/bin/cursor-rules install --editor=codex                # install for Codex
vendor/bin/cursor-rules install --editor=all                  # install for Cursor, Claude, and Codex
vendor/bin/cursor-rules install --editor=cursor --force       # overwrite existing files
vendor/bin/cursor-rules install --editor=cursor --symlink     # prefer symlinks (fallback to copy)

Installer Flow

Determine the project root by walking up from the current directory until composer.json is found.
Resolve the rules source (local rules/ or vendor/pekral/cursor-rules/rules).
Install rules into the target directory(ies) for the chosen editor (see --editor).
If present, resolve the skills source and install into the corresponding skill directory(ies).
For --editor=claude or --editor=all: copy CLAUDE.md to the project root (never overwrites existing).
Optionally overwrite existing files with --force; use --symlink to prefer symlinks (fallback to copy on Windows).
Surface explicit errors for missing directories, removal failures, and copy/symlink failures.

CLI Switches

Option	Description
`--editor=EDITOR`	Target editor (required): `cursor`, `claude`, `codex`, `all`.
`--force`	Overwrite files that already exist in the target directory.
`--symlink`	Create symlinks when the OS permits; automatically falls back to copy.
(default)	Only copy missing files and keep existing content untouched.

🎯 Skills Overview — v0.7.1

Current release includes 23 skills for issue resolution, code review, refactoring, testing, security, SQL performance, and delivery workflows.

Agent skills are installed into the chosen editor’s skill directory (see --editor). Use --editor=all to install for Cursor, Claude, and Codex at once. They can be invoked when relevant. Each skill follows project conventions, ensures code quality, and maintains 100% test coverage where applicable.

Note: Skill files use relative paths (e.g. @rules/…, @skills/…) without any editor-specific prefix, so they work with any supported editor (--editor=cursor, --editor=claude, --editor=codex, --editor=all).

Issue Resolution & Delivery

Skill	Description
`analyze-problem`	Structured problem analysis for debugging, root cause identification, and breaking down complex issues.
`resolve-issue`	Unified issue resolution for GitHub, JIRA, and Bugsnag. Detects the tracker from the provided link, runs `analyze-problem` before implementation, validates with tests, and creates a PR.
`merge-github-pr`	Safely merge GitHub pull requests that are ready for deployment.
`create-issue`	Create a tracker issue from provided task text while preserving original meaning and structure.
`create-issues-from-text`	Batch-create issues from provided text with automatic structure detection.
`pr-summary`	Summarize current PR changes for development and product teams in a clear markdown report.

Code Review, Security & Architecture

Skill	Description
`code-review`	Senior PHP code review focused on architecture, risk, and behavior (read-only).
`code-review-github`	Review GitHub pull requests with severity-based findings and review comments.
`code-review-jira`	Review JIRA-linked changes with GitHub PR comments and structured findings.
`process-code-review`	Process existing review feedback, resolve comments, and prepare next review cycle.
`security-review`	OWASP-focused security review (injection, auth, SSRF, exposure, misconfigurations).
`class-refactoring`	Refactor PHP classes using SOLID and Laravel best practices with testability focus.
`refactor-entry-point-to-action`	Refactor controller/job/command/listener entry-point logic into Action classes.
`smartest-project-addition`	Propose one high-impact, low-risk project improvement.
`understand-propose-implement-verify`	Enforce a strict 4-step loop: understand, propose, implement, verify.

Testing & Quality Automation

Skill	Description
`create-test`	Add tests following project rules with deterministic behavior and high coverage.
`create-missing-tests-in-pr`	Validate review recommendations and add missing tests for current PR changes.
`rewrite-tests-pest`	Rewrite tests to PEST style while preserving behavior and conventions.
`test-like-human`	Validate PR behavior from user perspective using scenario-driven testing.
`test-driven-development`	Enforce strict red-green-refactor flow for bugfixes and features.

Platform & Data

Skill	Description
`composer-update`	Analyze composer updates, conflicts, and changelog impact.
`mysql-problem-solver`	Diagnose and optimize MySQL queries, indexes, and execution plans.
`laravel-telescope`	Analyze Laravel Telescope request data from URL, match entries in DB, and propose concrete optimizations.

Rules Overview

Rules included in this package:

File	Description	Scope
`php/core-standards.mdc`	Project context, AI behavior, and unified PHP/Laravel coding standards	Always
`git/general.mdc`	Unified git workflow, commits, and pull request rules	Always
`code-review/general.mdc`	Code review conventions and output rules	Always
`code-testing/general.mdc`	Testing conventions and quality standards	Always
`jira/general.mdc`	JIRA CLI usage and formatting rules	JIRA
`laravel/architecture.mdc`	Laravel architecture and conventions	Laravel
`laravel/laravel.mdc`	Laravel-specific rules and patterns	Laravel
`laravel/filament.mdc`	Filament v4 specific rules	Filament
`laravel/livewire.mdc`	Livewire component rules and conventions	Livewire
`sql/optimalize.mdc`	SQL query optimization, index design, schema standards	Always
`security/backend.md`	Backend security rules and OWASP Top 10 checks	Always
`security/frontend.md`	Frontend security rules (XSS, CSRF, CSP)	Frontend
`security/mobile.md`	Mobile-specific security rules and WebView checks	Mobile

All .mdc and .md files are ready for automatic injection by Cursor so every PHP and Laravel edit stays aligned with the enforced standards.

Development & Testing

Composer Scripts

composer check              # run full quality check (normalize, phpcs, pint, rector, phpstan, audit, tests)
composer fix                # run all automatic fixes (normalize, rector, pint, phpcs)
composer build              # fix then check
composer analyse            # run PHPStan static analysis
composer test:coverage       # run tests with 100% coverage
composer coverage           # alias for test:coverage
composer security-audit     # run security audit of dependencies

Individual Commands

composer phpcs-check        # PHP CodeSniffer check
composer phpcs-fix          # PHP CodeSniffer fix
composer pint-check         # Laravel Pint check
composer pint-fix           # Laravel Pint fix
composer rector-check       # Rector check (dry-run)
composer rector-fix         # Rector fix

Testing

./vendor/bin/pest           # run all tests
composer test:coverage      # run tests with coverage (min. 100%)

Remove coverage.xml before committing if it was produced locally.

Author

Petr Král — PHP Developer & Laravel programmer, open source contributor (pekral.cz).

License

MIT — free to use, modify, and distribute.

pekral / cursor-rules

Maintainers

Package info

Statistics

Security