php-auto-fixer

name

php-auto-fixer

description

CRITICAL: Read BEFORE writing or modifying any PHP file. A PostToolUse hook automatically runs nette/coding-standard (ECS) on every PHP file after each Edit or Write. The fixer removes unused `use` statements - so never add `use` statements in a separate edit before the code that references them. Always include `use` imports in the same edit as the referencing code, or add the code first then `use` statements. This skill should be used whenever creating new PHP files, editing existing PHP code, adding methods, refactoring, or fixing bugs in PHP - even for small one-line changes.

PHP Auto-Fixer

A PostToolUse hook runs ecs fix on every PHP file after each Edit or Write operation. The file is automatically reformatted and cleaned up - no manual formatting needed.

Editing Order for use Statements

The fixer removes any use statement not referenced in the file. This creates a timing trap between consecutive edits:

1. Edit adds use App\Model\Foo;
2. Hook runs → Foo is not used anywhere → removes the use statement
3. Next Edit adds code using Foo → fails because the use is gone

The Rule

Always add use statements in the same Edit as the code that references them. Alternatively, add the code first, then add the use statement in a follow-up edit.

Never add use statements alone in a separate Edit - they will be removed before the next edit adds the referencing code.

Safe Patterns

Single edit with both use and code (preferred):

use App\Model\UserRepository;

public function getUsers(UserRepository $repo): array
{
    return $repo->findAll();
}

Code first, use second (also safe):

1. First Edit: add the method body referencing UserRepository
2. Second Edit: add use App\Model\UserRepository; - now it's referenced, fixer keeps it

use first, code second (broken):

1. First Edit: add use App\Model\UserRepository; - fixer removes this immediately
2. Second Edit: add method body - UserRepository undefined

Multiple Classes in One Edit

When adding code that references several new classes, include all their use statements in the same edit. Do not split use statements and code across separate edits.

What the Fixer Does

• Removes unused use statements
• Sorts use statements alphabetically
• Fixes indentation, spacing, and line breaks
• Enforces PSR-12 with Nette modifications (e.g., no space before parentheses in arrow functions)

Do not manually fix formatting - the fixer handles it automatically after every edit.

What Not to Do

• Do not remove use statements manually - the fixer handles unused imports
• Do not sort use statements manually - the fixer sorts them
• Do not fix whitespace or indentation manually - the fixer fixes it

When the Fixer Reports Errors

The hook exits with an error when ECS cannot auto-fix all issues. Common causes:

• PHP syntax error in the file - fix the syntax first, fixer will run again on the next edit
• Conflicting rules - rare, usually resolved by re-running (edit the file again)

Excluding Paths

To stop the fixer from touching certain paths (e.g. fixtures folders), add a .nette-claude.json file to the project root. It is shared by all Nette Claude Code hooks; each top-level key is a hook name:

{
	"fix-php-style": {
		"exclude": ["fixtures*"]
	}
}

Patterns are gitignore-like, relative to the config file: a pattern without a slash (fixtures, fixtures*) matches a segment at any depth; a pattern with a slash (tests/**/temp) is a glob anchored to the config directory. The file is looked up upwards from the edited file.

Installation

If the fixer is not installed, run /php-fixer:install-php-fixer.