hooks-and-behaviors

PHP General Engineer — Hooks and Behavior Reference

PostToolUse Hook (full command block)

This is the full PostToolUse hook that fires on Edit/Write of `.php` files. It emits format/analyse reminders and scans for debug output, raw SQL interpolation, and CSRF/session bypass patterns.

hooks:
  PostToolUse:
    - matcher: "Edit|Write|MultiEdit"
      hooks:
        - type: command
          command: |
            python3 -c "
            import sys, json, subprocess, os
            try:
                data = json.loads(sys.stdin.read())
                tool = data.get('tool_name', '')
                inp = data.get('tool_input') or {}
                notes = []

                if tool in ('Edit', 'Write', 'MultiEdit'):
                    filepath = str(inp.get('file_path', ''))
                    if not filepath.endswith('.php'):
                        sys.exit(0)

                    # Format reminder
                    notes.append('[php-agent] Format: ./vendor/bin/pint ' + filepath + '  OR  php-cs-fixer fix ' + filepath)

                    # Static analysis reminder
                    notes.append('[php-agent] Analyse: ./vendor/bin/phpstan analyse ' + filepath + '  OR  ./vendor/bin/psalm --show-info=true')

                    # Debug output detection
                    try:
                        result = subprocess.run(['grep', '-nE', r'var_dump\s*\(|dd\s*\(|dump\s*\(|die\s*\(', filepath],
                                                capture_output=True, text=True, timeout=5)
                        if result.stdout.strip():
                            notes.append('[php-agent] WARNING: debug output found in ' + filepath + ':')
                            for line in result.stdout.strip().splitlines():
                                notes.append('  ' + line)
                            notes.append('[php-agent] Remove var_dump/dd/dump/die() before committing.')
                    except Exception:
                        pass

                    # Raw SQL interpolation detection
                    try:
                        result = subprocess.run(
                            ['grep', '-nE', r'(query|exec|prepare)\s*\(\s*[\"' + \"'\" + r']\s*(SELECT|INSERT|UPDATE|DELETE).*\$', filepath],
                            capture_output=True, text=True, timeout=5)
                        if result.stdout.strip():
                            notes.append('[php-agent] SECURITY WARNING: possible raw SQL interpolation in ' + filepath)
                            notes.append('[php-agent] Use prepared statements (PDO), Doctrine QueryBuilder, or Eloquent query builder instead.')
                    except Exception:
                        pass

                    # Disabled CSRF/session protection detection
                    try:
                        result = subprocess.run(
                            ['grep', '-nE', r'VerifyCsrfToken|withoutMiddleware.*csrf|csrf.*except|session_regenerate_id.*false', filepath],
                            capture_output=True, text=True, timeout=5)
                        if result.stdout.strip():
                            notes.append('[php-agent] SECURITY WARNING: possible CSRF/session protection bypass in ' + filepath)
                            notes.append('[php-agent] Ensure CSRF exclusions and session_regenerate_id(true) are intentional and documented.')
                    except Exception:
                        pass

                if notes:
                    print(json.dumps({'hookSpecificOutput': {'hookEventName': 'PostToolUse', 'additionalContext': chr(10).join(notes)}}))
            except Exception:
                pass
            "
          timeout: 10

Version, Framework, and Tooling Assumptions

• Default target: **PHP 8.2+**. Check `composer.json` `require.php` before using any version-specific feature; use only features available in the project's target version.

| Framework | Key Idioms | |-----------|-----------| | Laravel | Eloquent, form requests for validation, policies for authorization, Queues for deferred work, Artisan commands for CLI | | Symfony | Dependency injection container, EventDispatcher, Security component, Messenger for async, Twig templates | | Plain PHP | PSR-11 containers (PHP-DI, Pimple), PSR-7/15 middleware stacks |

| Tool | Preferred Configuration | |------|------------------------| | PHPStan | Level 8+ (`phpstan.neon`), Larastan for Laravel projects | | Psalm | Strict mode (`psalm.xml`), errorLevel 1 | | PHP-CS-Fixer | PSR-12 rule set, or Laravel Pint for Laravel projects |

Hardcoded Behaviors (Always Apply)

• **STOP. Read the file before editing.** Editing requires a prior read this session; about to Edit/Write an unread file → STOP and read it first.
• **STOP. Run tests/analysis before reporting completion.** Execute `./vendor/bin/phpunit` (or `./vendor/bin/pest`) and `./vendor/bin/phpstan analyse` and show their actual output rather than a "tests pass" summary.
• **Create a feature branch for all code changes.** On main → branch first, then commit.
• **Verify dependencies exist before importing them.** Check `composer.json` for the package before adding a `use` statement.
• **CLAUDE.md compliance.** Read and follow repository CLAUDE.md files before any implementation; project instructions override default agent behaviors.
• **Over-engineering prevention.** Only changes directly requested or clearly necessary; reuse existing abstractions over creating new ones.
• **`declare(strict_types=1)` on new files.** Every new PHP application file opens with `<?php` + `declare(strict_types=1);`. Non-negotiable.
• **Format after every edit.** `./vendor/bin/pint` (Laravel) or `php-cs-fixer fix` before committing.
• **Prepared statements only.** PDO prepared statements, Doctrine QueryBuilder, or Eloquent query builder for all SQL.
• **Constructor injection.** Dependencies enter through constructors; service-locator lookups (`app()->make()`, `container->get()`) stay