|
| 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 | +JBZoo Data is a PHP library that provides an extended version of ArrayObject for working with data arrays and various formats (JSON, YAML, INI, PHP arrays). It offers a fluent API for data manipulation with built-in filtering, nested access, and format conversion capabilities. |
| 8 | + |
| 9 | +## Core Architecture |
| 10 | + |
| 11 | +### Abstract Base Class Pattern |
| 12 | +- `AbstractData` - Base class extending PHP's ArrayObject with common functionality |
| 13 | +- `AliasesTrait` - Provides multiple access methods (array, object, method-based) |
| 14 | +- Concrete implementations: `Data`, `JSON`, `Yml`, `Ini`, `PhpArray` |
| 15 | + |
| 16 | +### Function-Based Factory Pattern |
| 17 | +The `src/functions.php` file provides factory functions for creating instances: |
| 18 | +- `data()` - Creates Data objects |
| 19 | +- `json()` - Creates JSON objects |
| 20 | +- `yml()` - Creates Yml objects |
| 21 | +- `ini()` - Creates Ini objects |
| 22 | +- `phpArray()` - Creates PhpArray objects |
| 23 | + |
| 24 | +### Data Access Patterns |
| 25 | +Multiple ways to access data with graceful undefined handling: |
| 26 | +- Array access: `$data['key']` |
| 27 | +- Object access: `$data->key` |
| 28 | +- Method access: `$data->get('key', $default)` |
| 29 | +- Nested access: `$data->find('deep.nested.key', $default)` |
| 30 | + |
| 31 | +### Format Support |
| 32 | +Each class handles specific data formats: |
| 33 | +- `JSON` - JSON strings and files |
| 34 | +- `Yml` - YAML format (requires symfony/yaml) |
| 35 | +- `Ini` - INI configuration files |
| 36 | +- `PhpArray` - PHP files returning arrays |
| 37 | +- `Data` - Generic/serialized data |
| 38 | + |
| 39 | +## Common Commands |
| 40 | + |
| 41 | +### Development Setup |
| 42 | +```bash |
| 43 | +make update # Install/update all dependencies via Composer |
| 44 | +make autoload # Dump optimized autoloader |
| 45 | +``` |
| 46 | + |
| 47 | +### Testing |
| 48 | +```bash |
| 49 | +make test # Run PHPUnit tests |
| 50 | +make test-all # Run all tests and code style checks at once |
| 51 | +make codestyle # Run all linters and style checks |
| 52 | +``` |
| 53 | + |
| 54 | +### Individual Quality Assurance Tools |
| 55 | +```bash |
| 56 | +make test-phpstan # Static analysis with PHPStan |
| 57 | +make test-psalm # Static analysis with Psalm |
| 58 | +make test-phpcs # PHP CodeSniffer (PSR-12 + compatibility) |
| 59 | +make test-phpcsfixer # PHP-CS-Fixer style check |
| 60 | +make test-phpcsfixer-fix # Auto-fix code style issues |
| 61 | +make test-phpmd # PHP Mess Detector |
| 62 | +make test-phan # Phan static analyzer |
| 63 | +make test-performance # Run benchmark tests |
| 64 | +``` |
| 65 | + |
| 66 | +### Reports and Analysis |
| 67 | +```bash |
| 68 | +make report-all # Generate all analysis reports |
| 69 | +make report-phpmetrics # PHP Metrics report |
| 70 | +make report-pdepend # PHP Depend analysis |
| 71 | +make report-phploc # Lines of code statistics |
| 72 | +``` |
| 73 | + |
| 74 | +## Development Standards |
| 75 | + |
| 76 | +### PHP Requirements |
| 77 | +- PHP 8.2+ required |
| 78 | +- Strict types enabled (`declare(strict_types=1)`) |
| 79 | +- PSR-12 coding standard |
| 80 | +- Full type hints required |
| 81 | + |
| 82 | +### Code Patterns |
| 83 | +When extending the library: |
| 84 | +1. New format classes should extend `AbstractData` |
| 85 | +2. Implement `decode()` and `encode()` abstract methods |
| 86 | +3. Add factory function to `functions.php` |
| 87 | +4. Follow existing naming conventions (`Yml` not `Yaml`, `PhpArray` not `PHPArray`) |
| 88 | + |
| 89 | +### Testing Structure |
| 90 | +- Tests in `tests/` directory follow naming pattern `Data{Format}Test.php` |
| 91 | +- Benchmark tests in `tests/phpbench/` for performance monitoring |
| 92 | +- Test fixtures in `tests/resource/` |
| 93 | +- Use `tests/Fixtures.php` for common test data |
| 94 | + |
| 95 | +### Performance Considerations |
| 96 | +The library includes comprehensive benchmarks comparing: |
| 97 | +- Native PHP arrays vs ArrayObject performance |
| 98 | +- Different access methods (array, object, method calls) |
| 99 | +- Data retrieval patterns for defined vs undefined values |
| 100 | + |
| 101 | +## Key Dependencies |
| 102 | + |
| 103 | +### Required |
| 104 | +- `php: ^8.2` |
| 105 | +- `ext-json: *` |
| 106 | + |
| 107 | +### Development/Optional |
| 108 | +- `jbzoo/toolbox-dev: ^7.2` - Development tooling |
| 109 | +- `jbzoo/utils: ^7.2.2` - Utility functions for filtering |
| 110 | +- `symfony/yaml: >=7.3.3` - YAML parsing support |
| 111 | + |
| 112 | +## Test Data and Fixtures |
| 113 | + |
| 114 | +The library uses shared test fixtures across format tests: |
| 115 | +- `tests/Fixtures.php` - Common test data arrays |
| 116 | +- `tests/resource/` - Sample data files in various formats |
| 117 | +- Consistent test data ensures format conversion accuracy |
| 118 | + |
| 119 | +## Filter Integration |
| 120 | + |
| 121 | +When JBZoo/Utils is available, the library supports data filtering: |
| 122 | +- `$data->get('key', $default, 'int')` - Type conversion |
| 123 | +- `$data->find('key', $default, 'email')` - Email validation |
| 124 | +- Chain filters: `'strip,trim'` |
| 125 | +- Custom callbacks supported |
| 126 | + |
| 127 | +## Build System Integration |
| 128 | + |
| 129 | +The project uses JBZoo's standardized Makefile system via: |
| 130 | +```makefile |
| 131 | +ifneq (, $(wildcard ./vendor/jbzoo/codestyle/src/init.Makefile)) |
| 132 | + include ./vendor/jbzoo/codestyle/src/init.Makefile |
| 133 | +endif |
| 134 | +``` |
0 commit comments