README

Cursor Rules ships a complete set of .mdc files for the Cursor editor. The installer discovers the project root, mirrors the entire rules/ directory (including empty subfolders), and copies or symlinks every file into the target project. The result is a consistent bundle of rules for PHP, Laravel, and testing workflows.

Why This Package

unified 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
fast onboarding inside development repositories

Installation

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

The installer creates .cursor/rules in the project root by default. When the package is required via Composer, the source files are read from vendor/pekral/cursor-rules/rules; in development it falls back to the local rules/ directory.

Available Commands

vendor/bin/cursor-rules help               # print help
vendor/bin/cursor-rules install            # copy/symlink everything to the target
vendor/bin/cursor-rules install --force    # overwrite existing files
vendor/bin/cursor-rules install --symlink  # prefer symlinks (fallback to copy)

Installer Flow

Determine the project root (composer.json search or configured fallback).
Resolve the rules source (local rules/ or vendor/...).
Resolve the destination: .cursor/rules or CURSOR_RULES_TARGET_DIR.
Create the destination root and replicate the whole directory tree, including empty folders.
Copy or symlink every file, optionally overriding existing files via --force.
Surface explicit errors for missing directories, removal failures, copy/symlink issues, etc.

CLI Switches

Option	Description
`--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.

Environment Variables

Variable	Purpose
`CURSOR_RULES_TARGET_DIR`	Absolute path to the destination (for example `/app/.cursor/rules`).
`CURSOR_RULES_PROJECT_ROOT`	Skips auto-discovery of the project root.
`CURSOR_RULES_PROJECT_ROOT_FALLBACK`	Fallback root if `getcwd()` cannot be resolved.
`CURSOR_RULES_DISABLE_SYMLINKS`	Forces copy mode even when `--symlink` is used.
`CURSOR_RULES_FORCE_WINDOWS`	Simulates a Windows environment (symlinks are disabled).
`CURSOR_RULES_FAIL_SYMLINK`	Test flag that forces a symlink failure.
`CURSOR_RULES_FAIL_COPY`	Test flag that forces a copy failure.

Rules Overview

File	Description	Scope
`app-architecture.mdc`	Application architecture (repositories, services, controllers, DTOs)	Always
`laravel-filament.mdc`	Filament v4 rules (resources, enums, tests)	Always
`php-classes.mdc`	Class structure, typed properties, SRP	Always
`php-docs.mdc`	Required docs for iterables, generics, array shapes	Always
`php-fixing-bugs.mdc`	Bug-fix workflow, tests-first refactoring guardrails	Always
`php-laravel.mdc`	Laravel conventions (naming, configs, routes, Blade, jobs, events)	Always
`php-standards.mdc`	Global clean-code rules, no redundant comments	Always
`php-testing.mdc`	Pest conventions, 100% coverage, no private/protected assertions	Always
`sql-rules.mdc`	SQL query optimization, indexes, N+1 prevention	Always
`ui-templates.mdc`	Rules for creating new templates and UI components	Always
`commands/*.md`	Task templates and checklists (e.g., class refactoring, code review)	Manual

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

Development & Testing

Composer Scripts

composer check              # run full quality check
composer fix                # run all automatic fixes
composer analyse            # run PHPStan static analysis
composer test:coverage      # run tests with 100% 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.

License

MIT — free to use, modify, and distribute.

pekral / cursor-rules

Maintainers

Details