|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +This is **fox91/dev-tools**, a Composer package that bundles PHP development tools with pre-configured settings. It's designed as a dependency package that other projects install to get a standardized set of quality assurance tools. |
| 8 | + |
| 9 | +**Important**: This package has NO source code (no `src/` directory). It exists solely to bundle tools and provide default configurations via the `configs/` directory. |
| 10 | + |
| 11 | +## PHP Version Support |
| 12 | + |
| 13 | +Compatible with PHP 8.1, 8.2, 8.3, and 8.4. |
| 14 | + |
| 15 | +## Development Commands |
| 16 | + |
| 17 | +### Running Tests |
| 18 | +```bash |
| 19 | +composer test # Run all tests (lint + code style) |
| 20 | +composer lint:test # PHP Parallel Lint only |
| 21 | +composer cs:test # PHP_CodeSniffer tests (all issues) |
| 22 | +composer cs-e:test # PHP_CodeSniffer tests (errors only) |
| 23 | +``` |
| 24 | + |
| 25 | +### Fixing Code |
| 26 | +```bash |
| 27 | +composer fix # Run all automatic fixes (currently just cs:fix) |
| 28 | +composer cs:fix # Auto-fix PHP_CodeSniffer issues with phpcbf |
| 29 | +``` |
| 30 | + |
| 31 | +### Individual Tools (Not in Default Scripts) |
| 32 | +The package includes these tools, but they're not wired up in this repository's composer.json: |
| 33 | +- **Rector**: `composer rector:test` or `composer rector:fix` (if configured) |
| 34 | +- **Psalm**: `composer psalm:test` (if configured) |
| 35 | +- **PHPStan**: `composer phpstan:test` (if configured - optional dependency) |
| 36 | +- **PHPUnit**: `composer unit:test` (if configured) |
| 37 | + |
| 38 | +## Architecture |
| 39 | + |
| 40 | +### Package Structure |
| 41 | +``` |
| 42 | +configs/ # Default configuration files that consuming projects can copy |
| 43 | + .editorconfig # Editor configuration |
| 44 | + .gitignore # Git ignore patterns |
| 45 | + .phpcs.xml.dist # PHP_CodeSniffer ruleset (uses Fox91CodingStandard) |
| 46 | + gitattributes.txt # Git attributes (rename to .gitattributes) |
| 47 | + phpdoc.dist.xml # PHPDocumentor configuration |
| 48 | + phpstan.neon.dist # PHPStan static analysis config (level 6) |
| 49 | + phpunit.xml.dist # PHPUnit testing framework config |
| 50 | + psalm.xml.dist # Psalm static analysis config (errorLevel 1) |
| 51 | + rector.php # Rector automated refactoring config (PHP 8.1+) |
| 52 | +``` |
| 53 | + |
| 54 | +### Bundled Tools |
| 55 | + |
| 56 | +**Core Dependencies** (always installed): |
| 57 | +- `php-parallel-lint/php-parallel-lint` - Checks PHP syntax |
| 58 | +- `squizlabs/php_codesniffer` - Code style checking and fixing (phpcs/phpcbf) |
| 59 | +- `fox91/coding-standard` - Custom coding standard for PHP_CodeSniffer |
| 60 | +- `phpunit/phpunit` - Unit testing framework (v10.5+) |
| 61 | +- `vimeo/psalm` - Static analysis tool |
| 62 | +- `psalm/plugin-phpunit` - PHPUnit plugin for Psalm |
| 63 | +- `rector/rector` - Automated code refactoring and upgrades |
| 64 | + |
| 65 | +**Optional Dependencies** (suggested, not required): |
| 66 | +- `phpstan/phpstan` and various PHPStan extensions |
| 67 | +- `thecodingmachine/safe` - PHP functions that throw exceptions instead of returning false |
| 68 | + |
| 69 | +### Configuration Philosophy |
| 70 | + |
| 71 | +All config files in `configs/` are designed to be **copied** into consuming projects. The standard installation pattern (documented in README) is: |
| 72 | + |
| 73 | +```bash |
| 74 | +composer require --dev fox91/dev-tools |
| 75 | +cp vendor/fox91/dev-tools/configs/.* . |
| 76 | +cp vendor/fox91/dev-tools/configs/rector.php . |
| 77 | +# etc. |
| 78 | +``` |
| 79 | + |
| 80 | +### Rector Configuration Details |
| 81 | + |
| 82 | +The `configs/rector.php` file is pre-configured with: |
| 83 | +- **Target PHP Level**: PHP 8.1 (`LevelSetList::UP_TO_PHP_81`) |
| 84 | +- **Enabled Rule Sets**: CODE_QUALITY, DEAD_CODE, NAMING, PRIVATIZATION, TYPE_DECLARATION, PHPUNIT_CODE_QUALITY |
| 85 | +- **Disabled Rules**: Several naming and code quality rules are explicitly skipped (see lines 34-44) |
| 86 | +- **Search Paths**: Looks for `bin/`, `public/`, `src/`, `tests/` directories |
| 87 | +- **Parallel Processing**: Enabled by default |
| 88 | +- **Cache**: Stored in `build/cache/rector/` |
| 89 | + |
| 90 | +### PHP_CodeSniffer Configuration Details |
| 91 | + |
| 92 | +The `.phpcs.xml.dist` uses: |
| 93 | +- **Coding Standard**: `Fox91CodingStandard` (from fox91/coding-standard package) |
| 94 | +- **PHP Compatibility**: Minimum PHP 8.1 |
| 95 | +- **Parallel Processing**: 80 processes |
| 96 | +- **ParanoiaMode**: Enabled (strict checking) |
| 97 | +- **Default Paths**: `rector.php` and `src/` (bin, public, tests commented out) |
| 98 | + |
| 99 | +### Psalm Configuration Details |
| 100 | + |
| 101 | +The `psalm.xml.dist` uses: |
| 102 | +- **Error Level**: 1 (strictest) |
| 103 | +- **Plugin**: PHPUnit plugin enabled |
| 104 | +- **Cache**: `build/cache/psalm/` |
| 105 | +- **Default Path**: `src/` directory only |
| 106 | + |
| 107 | +### PHPStan Configuration Details |
| 108 | + |
| 109 | +The `phpstan.neon.dist` uses: |
| 110 | +- **Level**: 6 (high strictness, but not maximum) |
| 111 | +- **Cache**: `build/cache/phpstan/` |
| 112 | +- **Default Paths**: `rector.php` and `src/` |
| 113 | + |
| 114 | +## CI/CD |
| 115 | + |
| 116 | +GitHub Actions workflow (`.github/workflows/php-ci.yml`): |
| 117 | +- **Matrix Testing**: PHP 8.1, 8.2, 8.3, 8.4 × (lowest, highest) dependencies |
| 118 | +- **Steps**: |
| 119 | + 1. Composer validation (strict mode) |
| 120 | + 2. PHP Parallel Lint |
| 121 | + 3. PHP_CodeSniffer |
| 122 | + |
| 123 | +**Note**: The workflow only runs lint and code style checks, NOT Psalm, PHPStan, Rector, or PHPUnit. This is because the package itself has no source code to analyze. |
| 124 | + |
| 125 | +## Common Development Patterns |
| 126 | + |
| 127 | +### Adding a New Configuration File |
| 128 | + |
| 129 | +When adding new tool configs to the `configs/` directory: |
| 130 | +1. Add the `.dist` version of the config |
| 131 | +2. Update the README.md copy command examples |
| 132 | +3. Ensure the config uses relative paths that work when copied to project root |
| 133 | +4. Use commented-out sections for optional paths (bin, public, tests, etc.) |
| 134 | + |
| 135 | +### Updating Tool Versions |
| 136 | + |
| 137 | +When bumping tool versions in `composer.json`: |
| 138 | +1. Test against all supported PHP versions (8.1-8.4) |
| 139 | +2. Test with both `--prefer-lowest` and `--prefer-stable` |
| 140 | +3. Update configuration files if the new version introduces breaking config changes |
| 141 | +4. Consider backward compatibility for projects already using the configs |
| 142 | + |
| 143 | +### Testing Configuration Changes |
| 144 | + |
| 145 | +Since this package has no source code: |
| 146 | +1. Make config changes |
| 147 | +2. Run `composer lint:test` to verify syntax |
| 148 | +3. Run `composer cs:test` to verify the config itself passes style checks |
| 149 | +4. Manually test by copying configs to a real project and running tools there |
0 commit comments