Cursor Rules for PHP: Types, Dependencies, and Tests

Cursor rules for PHP tell the AI assistant which PHP version the project requires, how Composer is used, what the typing expectations are, and how tests are run. PHP projects vary enormously — from modern PHP 8.3 applications with strict types to legacy codebases that still run on PHP 7 — and an assistant without clear rules will make choices suited to a different project.

The conventions your project has established — why certain patterns are used, which Composer packages are approved, what the PHP version constraint means for available language features — belong in fenbs as Decisions, where they stay findable alongside the tasks that prompted them.

What PHP rules should cover

• PHP version: the minimum and recommended version, and which language features that version enables.
• Composer commands: how to install, update, and add packages, and which commands run code quality tools.
• Typing: whether strict types are declared in every file, how null safety is handled, and whether union types are used.
• Autoloading: the namespace root and how classes are organized relative to it.
• Test runner: PHPUnit or Pest, the config file location, and the exact commands for running unit and integration tests.
• Code style: PSR-12 or a custom standard, and which tool enforces it (PHP CS Fixer, PHP_CodeSniffer).

A starting template

# PHP project rules

## Runtime
- PHP version: 8.2 or higher.
- Do not use deprecated functions or APIs removed in PHP 8.2.

## Composer
- Install: composer install
- Update a single package: composer update vendor/package (ask first)
- Add a dependency: ask before running composer require
- Autoload dump: composer dump-autoload

## Code quality
- Check style: ./vendor/bin/phpcs --standard=PSR12 src/
- Fix style: ./vendor/bin/phpcbf src/
- Static analysis: ./vendor/bin/phpstan analyse src/ --level=8

## Typing
- Declare strict_types=1 at the top of every file.
- Use typed properties (no untyped class properties).
- Prefer union types over mixed.
- Handle nullable types with the ? prefix or with a null check.

## Namespace and autoloading
- Root namespace: App\
- Root directory: src/
- Match the class name to the file name exactly.

## Tests
- Run: ./vendor/bin/phpunit
- Config: phpunit.xml
- Do not modify test fixtures in tests/fixtures/ without asking.

PHP version rules and language features

PHP 8.x introduced substantial changes to the language, and the right rules depend on which minor version you target. PHP 8.1 added enums and fibers. PHP 8.2 added readonly classes. PHP 8.3 added typed class constants. An assistant without a version rule will use whichever features it knows about, producing code that may not compile on your target runtime.

If your project runs on hosting that lags behind the current PHP release — common with shared hosting or older servers — state the actual runtime version explicitly. A constraint like "must run on PHP 8.0" affects every language feature the assistant should use.

Static analysis and type rules

PHPStan and Psalm (another popular static analysis tool) have configurable strictness levels. If your project runs PHPStan at level 8 or 9, add that to the rules: "new code must pass PHPStan at level 8." This gives the assistant a concrete bar to meet rather than a general instruction to write well-typed code.

The Cursor rules for AI projects guide covers how to integrate quality checks like these into a broader project workflow. The same patterns apply to PHP projects using Composer-based tooling.

Project conventions and fenbs

Why does the project use PSR-12 instead of a different standard? Why was PHPStan chosen over Psalm? Why is a particular database library used instead of an ORM? These choices were made for reasons the rules file does not explain.

Recording them in fenbs as Decisions makes the rationale findable by any assistant connected to the project. When a convention changes — upgrading to a new PHP version, adopting a different test framework — a new Decision captures the change and the reason alongside the tasks that drove it.

How to set up PHP rules with fenbs

1. Create a free account and add your PHP project to fenbs. Record the key conventions as Decisions: PHP version, static analysis level, testing framework, code style standard.
2. Add the template above to your project's .cursor/rules/ directory and update the commands, PHP version, and namespace root to match your actual project.
3. Connect Cursor to fenbs over MCP from Integrations. Ask the assistant to read the project context at session start before writing any new classes or tests.
4. When the project upgrades PHP or changes a code quality tool, update the Decision in fenbs and the rules file in the same change.

Error handling and exception conventions

PHP 8 provides a robust exception hierarchy, but projects differ in how they use it. Some catch all exceptions at a single top-level handler and let them bubble up unchecked everywhere else. Some use a domain exception hierarchy with specific exception classes for each error case. An assistant without exception rules will choose whatever pattern the documentation examples show, which may not match how your project handles errors.

Write the exception rules specifically. If your project catches exceptions at the controller level and transforms them into HTTP responses, say so. If domain exceptions live in a specific namespace, name it. If certain PHP built-in exceptions should be wrapped before they cross a module boundary, note that pattern. An assistant that follows these rules will write error paths that fit the existing architecture rather than introducing a second approach.

What to watch for

Legacy PHP codebases often have mixed typing: older files without type declarations alongside newer files with strict types. An assistant given access to the whole codebase will see the inconsistency and may follow the older pattern. Add a rule: "new files must declare strict_types=1 regardless of what existing files do." This keeps new code on the modern standard without forcing a rewrite.

Composer scripts in composer.json are a convenient way to standardize commands. If your project uses composer test or composer check scripts, list those in the rules instead of the underlying commands. An assistant that uses the Composer script will benefit from any future changes to that script automatically.