Skip to content

Commit f9ff4e2

Browse files
SmetDenisSmetDenis
authored
docs: Add AI guidance and improve project docs (#8)
- Introduce `CLAUDE.md` to provide detailed guidance for AI assistants, covering project overview, architecture, commands, and standards. - Significantly expand `README.md` with a comprehensive overview, quick start guide, project structure, template system, requirements, code quality, and CI/CD. - Update `create-new-project.php` to remove `CLAUDE.md` after project initialization. - Add `.claude` to `.gitignore`.
1 parent adc6ccc commit f9ff4e2

File tree

4 files changed

+205
-9
lines changed

4 files changed

+205
-9
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ vendor
1717
phpunit.xml
1818
composer.lock
1919
*.cache
20+
.claude
2021

2122
# Cutline
2223
SkeletonPhp*

‎CLAUDE.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
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 Skeleton-Php is a project skeleton template for creating new PHP libraries within the JBZoo ecosystem. This is not a completed library but a template that gets transformed into a new project via the `create-new-project.php` script.
8+
9+
## Architecture
10+
11+
### Skeleton System
12+
- **Template transformation**: The project uses placeholder tokens (`__PACKAGE__`, `__NS__`, etc.) that get replaced during project creation
13+
- **Self-destructing setup script**: `create-new-project.php` transforms the skeleton and then deletes itself
14+
- **Namespace mapping**: Template files like `src/__NS__.php` get renamed to actual class names during setup
15+
16+
### Core Structure
17+
- `src/` - Main library code with skeleton classes
18+
- `tests/` - PHPUnit tests extending JBZoo's testing framework
19+
- Template files use `__NS__` and `__PACKAGE__` placeholders that get replaced during project initialization
20+
21+
## Common Commands
22+
23+
### Development
24+
```bash
25+
make update # Install/update all dependencies
26+
make autoload # Dump optimized autoloader
27+
```
28+
29+
### Testing
30+
```bash
31+
make test # Run PHPUnit tests
32+
make test-all # Run all tests and code style checks
33+
make codestyle # Run all linters at once
34+
```
35+
36+
### Individual QA Tools
37+
```bash
38+
make test-phpstan # Static analysis with PHPStan
39+
make test-psalm # Static analysis with Psalm
40+
make test-phpcsfixer # Check PHP-CS-Fixer rules
41+
make test-phpcsfixer-fix # Auto-fix with PHP-CS-Fixer
42+
make test-phpmd # Mess detector
43+
make test-phan # Phan static analyzer
44+
make test-composer # Validate composer files
45+
```
46+
47+
### Project Creation
48+
```bash
49+
php create-new-project.php YourPackageName # Transform skeleton into new project
50+
make skel-test # Test the skeleton transformation process
51+
```
52+
53+
## JBZoo Standards
54+
55+
### PHP Requirements
56+
- PHP 8.2+ required (`composer.json` specifies `"php": "^8.2"`)
57+
- Strict types declaration required (`declare(strict_types=1)`)
58+
- PSR-4 autoloading with `JBZoo\` namespace prefix
59+
60+
### Testing Framework
61+
Tests extend JBZoo's testing framework classes:
62+
- `AbstractPackageTest` - For package-level tests (validates structure, composer.json, etc.)
63+
- Standard PHPUnit tests for functionality
64+
- Uses custom assertion helpers like `isSame()` instead of `assertEquals()`
65+
66+
### Code Style
67+
Uses JBZoo Codestyle package (`jbzoo/toolbox-dev`) which includes:
68+
- PHP-CS-Fixer with custom JBZoo rules
69+
- PHPStan for static analysis
70+
- Psalm for additional static analysis
71+
- PHPMD for mess detection
72+
- PSR-12 compliance
73+
74+
## File Structure Notes
75+
76+
### Template Files
77+
- `src/__NS__.php` → Gets renamed to actual namespace class during setup
78+
- `tests/__NS__Test.php` → Becomes the main test class
79+
- `tests/__NS__PackageTest.php` → Package validation tests
80+
81+
### Configuration
82+
- `phpunit.xml.dist` - PHPUnit configuration with coverage reporting
83+
- `Makefile` - Includes JBZoo's codestyle Makefiles for consistent tooling
84+
- `.phan.php` - Phan static analyzer configuration
85+
86+
### Build System
87+
The project uses JBZoo's sophisticated Makefile system:
88+
- Main `Makefile` includes `vendor/jbzoo/codestyle/src/init.Makefile`
89+
- Provides unified commands across all JBZoo projects
90+
- Supports both local development and CI environments
91+
92+
## Development Workflow
93+
94+
1. **For new projects**: Use `php create-new-project.php PackageName` to transform skeleton
95+
2. **For skeleton development**: Use `make skel-test` to test the transformation process
96+
3. **Always run**: `make test-all` before committing to ensure all QA checks pass
97+
4. **For fixes**: Use `make test-phpcsfixer-fix` to auto-fix code style issues
98+
99+
## CI Integration
100+
101+
- GitHub Actions workflow in `.github/workflows/main.yml`
102+
- Automated testing across multiple PHP versions
103+
- Coverage reporting integration with Coveralls
104+
- All QA tools run in CI pipeline

‎README.md‎

Lines changed: 98 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,19 +2,109 @@
22

33
[![CI](https://github.com/JBZoo/Skeleton-Php/actions/workflows/main.yml/badge.svg?branch=master)](https://github.com/JBZoo/Skeleton-Php/actions/workflows/main.yml?query=branch%3Amaster) [![Coverage Status](https://coveralls.io/repos/github/JBZoo/Skeleton-PHP/badge.svg?branch=master)](https://coveralls.io/github/JBZoo/Skeleton-PHP?branch=master) [![Psalm Coverage](https://shepherd.dev/github/JBZoo/Skeleton-Php/coverage.svg)](https://shepherd.dev/github/JBZoo/Skeleton-Php) [![Psalm Level](https://shepherd.dev/github/JBZoo/Skeleton-Php/level.svg)](https://shepherd.dev/github/JBZoo/Skeleton-Php) [![CodeFactor](https://www.codefactor.io/repository/github/jbzoo/skeleton-php/badge)](https://www.codefactor.io/repository/github/jbzoo/skeleton-php/issues)
44

5+
## Overview
56

6-
This is not a completed library, but only a blank.
7-
It aims to clean up the minds of programmers and standardize the development of open-source libraries for JBZoo.
7+
This is a project skeleton template for creating new PHP libraries within the JBZoo ecosystem. It's not a completed library but a standardized template that helps maintain consistency across JBZoo projects.
88

9+
The skeleton includes:
10+
- Modern PHP 8.2+ setup with strict typing
11+
- Comprehensive testing framework integration
12+
- Complete CI/CD pipeline configuration
13+
- Integrated code quality tools (PHPStan, Psalm, PHP-CS-Fixer, etc.)
14+
- JBZoo coding standards and conventions
915

10-
### Action items
16+
## Quick Start
1117

12-
* Create a new repository (MIT, without .gitignore).
13-
* Make a checkout of a clean repository for a working machine.
14-
* [Download the latest version of the skeleton](https://github.com/JBZoo/Skeleton/archive/master.zip).
15-
* Run the skeleton script for your package through `php ./create-new-project.php Skeleton-Php`
18+
### Creating a New Project
1619

20+
1. **Create a new repository** (MIT license, without .gitignore)
21+
2. **Clone the skeleton**:
22+
```bash
23+
git clone https://github.com/JBZoo/Skeleton-Php.git your-project-name
24+
cd your-project-name
25+
```
26+
3. **Initialize the project**:
27+
```bash
28+
make update
29+
php create-new-project.php Project-Name
30+
make update
31+
```
1732

18-
### License
33+
The initialization script will:
34+
- Replace all template placeholders with your package name
35+
- Rename template files to match your namespace
36+
- Update composer.json and other configuration files
37+
- Clean up skeleton-specific files
38+
39+
### Development Commands
40+
41+
```bash
42+
# Install/update dependencies
43+
make update
44+
45+
# Develop cycle
46+
make skel-test
47+
48+
# fix, commit, git reset --hard, repeat.
49+
50+
# Run all tests and code quality checks
51+
make test-all
52+
53+
# Run individual tools
54+
make test # PHPUnit tests
55+
make codestyle # All linters
56+
```
57+
58+
## Project Structure
59+
60+
```
61+
├── src/ # Main library code
62+
├── tests/ # PHPUnit tests
63+
├── create-new-project.php # Skeleton transformation script
64+
├── Makefile # Build commands
65+
├── phpunit.xml.dist # PHPUnit configuration
66+
└── composer.json # Dependencies and autoloading
67+
```
68+
69+
## Template System
70+
71+
The skeleton uses placeholder tokens that get replaced during project creation:
72+
73+
- `__PACKAGE__` → Your package name (e.g., "MyAwesomeLib")
74+
- `__NS__` → Your namespace (e.g., "MyAwesomeLib")
75+
- `jbzoo/skeleton-php` → Your composer package name
76+
77+
Template files that get renamed:
78+
- `src/__NS__.php` → `src/YourClassName.php`
79+
- `tests/__NS__Test.php` → `tests/YourClassNameTest.php`
80+
81+
## Requirements
82+
83+
- PHP 8.2 or higher
84+
- Composer 2.0+
85+
- Make (for build commands)
86+
87+
## Code Quality
88+
89+
The skeleton includes comprehensive code quality tools:
90+
91+
- **PHPUnit** - Unit testing framework
92+
- **PHPStan** - Static analysis (level max)
93+
- **Psalm** - Additional static analysis
94+
- **PHP-CS-Fixer** - Code style fixer
95+
- **PHPMD** - Mess detector
96+
- **Phan** - Static analyzer
97+
98+
All tools are pre-configured with JBZoo standards and integrate with CI/CD pipelines.
99+
100+
## CI/CD
101+
102+
The skeleton includes GitHub Actions workflow that:
103+
- Tests against multiple PHP versions
104+
- Runs all quality assurance tools
105+
- Generates coverage reports
106+
- Validates composer configuration
107+
108+
## License
19109

20110
MIT

‎create-new-project.php‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -116,7 +116,8 @@ function getFileList(string $dir, array &$results = []): array
116116
}
117117

118118
// Self-destruction
119-
@\unlink(__FILE__);
119+
\unlink(__DIR__ . '/CLAUDE.md');
120+
\unlink(__FILE__);
120121

121122
// Success
122123
echo $packageName . ' is ready!' . \PHP_EOL;

0 commit comments

Comments
 (0)