Skip to content

Commit cd107cf

Browse files
pedroacpedroac
committed
Refactor core, update docs, add exceptions and scripts
1 parent 2591861 commit cd107cf

35 files changed

Lines changed: 1697 additions & 927 deletions

‎.editorconfig‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# EditorConfig is awesome: https://EditorConfig.org
2+
3+
# top-most EditorConfig file
4+
root = true
5+
6+
# Unix-style newlines with a newline ending every file
7+
[*]
8+
end_of_line = lf
9+
insert_final_newline = true
10+
charset = utf-8
11+
trim_trailing_whitespace = true
12+
13+
# PHP files
14+
[*.php]
15+
indent_style = space
16+
indent_size = 4
17+
18+
# Markdown files
19+
[*.md]
20+
indent_style = space
21+
indent_size = 2
22+
trim_trailing_whitespace = false
23+
24+
# JSON files
25+
[*.json]
26+
indent_style = space
27+
indent_size = 4
28+
29+
# YAML files
30+
[*.{yml,yaml}]
31+
indent_style = space
32+
indent_size = 2
33+
34+
# XML files
35+
[*.xml]
36+
indent_style = space
37+
indent_size = 4
38+
39+
# Composer files
40+
[composer.json]
41+
indent_style = space
42+
indent_size = 4

‎.github/workflows/php.yml‎

Lines changed: 48 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -10,36 +10,76 @@ permissions:
1010
contents: read
1111

1212
jobs:
13-
build:
14-
13+
test:
1514
runs-on: ubuntu-latest
15+
strategy:
16+
matrix:
17+
php-version: ['8.3', '8.4']
1618

1719
steps:
1820
- uses: actions/checkout@v4
1921

22+
- name: Setup PHP
23+
uses: shivammathur/setup-php@v2
24+
with:
25+
php-version: ${{ matrix.php-version }}
26+
extensions: intl, xml
27+
coverage: none
28+
2029
- name: Validate composer.json and composer.lock
2130
run: composer validate --strict --no-check-lock
2231

2332
- name: Cache Composer packages
2433
id: composer-cache
25-
uses: actions/cache@v3
34+
uses: actions/cache@v4
2635
with:
2736
path: vendor
28-
key: ${{ runner.os }}-php-${{ hashFiles('**/composer.json') }}
37+
key: ${{ runner.os }}-php-${{ matrix.php-version }}-${{ hashFiles('**/composer.json') }}
2938
restore-keys: |
39+
${{ runner.os }}-php-${{ matrix.php-version }}-
3040
${{ runner.os }}-php-
3141
3242
- name: Install dependencies
3343
run: composer install --prefer-dist --no-progress
3444

35-
# Add a test script to composer.json, for instance: "test": "vendor/bin/phpunit"
36-
# Docs: https://getcomposer.org/doc/articles/scripts.md
45+
- name: Run PHP CS Fixer check
46+
run: composer run-script cs-check
47+
48+
- name: Run PHPStan
49+
run: composer run-script phpstan
3750

3851
- name: Run test suite
3952
run: composer run-script test
4053

41-
- name: Install Xdebug
42-
run: sudo apt-get install php-xdebug
54+
coverage:
55+
runs-on: ubuntu-latest
56+
needs: test
57+
58+
steps:
59+
- uses: actions/checkout@v4
60+
61+
- name: Setup PHP
62+
uses: shivammathur/setup-php@v2
63+
with:
64+
php-version: '8.3'
65+
extensions: intl, xml, xdebug
66+
coverage: xdebug
67+
68+
- name: Validate composer.json and composer.lock
69+
run: composer validate --strict --no-check-lock
70+
71+
- name: Cache Composer packages
72+
id: composer-cache
73+
uses: actions/cache@v4
74+
with:
75+
path: vendor
76+
key: ${{ runner.os }}-php-8.3-${{ hashFiles('**/composer.json') }}
77+
restore-keys: |
78+
${{ runner.os }}-php-8.3-
79+
${{ runner.os }}-php-
80+
81+
- name: Install dependencies
82+
run: composer install --prefer-dist --no-progress
4383

4484
- name: Run coverage
4585
run: composer run-script coverage

‎.php-cs-fixer.dist.php‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
$finder = PhpCsFixer\Finder::create()
6+
->in(__DIR__)
7+
->exclude('vendor')
8+
->exclude('coverage')
9+
->exclude('html-coverage')
10+
->exclude('xml-coverage')
11+
->exclude('tools')
12+
->exclude('doc')
13+
->name('*.php');
14+
15+
$config = new PhpCsFixer\Config();
16+
return $config
17+
->setRiskyAllowed(true)
18+
->setPhpExecutable(PHP_BINARY)
19+
->setRules([
20+
'@PSR12' => true,
21+
'array_syntax' => ['syntax' => 'short'],
22+
'ordered_imports' => ['sort_algorithm' => 'alpha'],
23+
'no_unused_imports' => true,
24+
'not_operator_with_successor_space' => true,
25+
'trailing_comma_in_multiline' => true,
26+
'phpdoc_scalar' => true,
27+
'unary_operator_spaces' => true,
28+
'binary_operator_spaces' => true,
29+
'blank_line_before_statement' => [
30+
'statements' => ['break', 'continue', 'declare', 'return', 'throw', 'try'],
31+
],
32+
'phpdoc_single_line_var_spacing' => true,
33+
'phpdoc_var_without_name' => true,
34+
])
35+
->setFinder($finder)
36+
->setRiskyAllowed(true);

‎CHANGELOG.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [1.0.0] - 2026-01-31
9+
10+
### Added
11+
- Complete PSR-7 HTTP message implementation
12+
- Full URI normalization, validation, and building
13+
- Automatic body parsing based on Content-Type headers
14+
- Secure file upload handling with path traversal protection
15+
- XXE attack prevention for XML/HTML parsing
16+
- Immutable message objects throughout
17+
- Comprehensive test suite (227 tests, 307 assertions)
18+
- Static analysis with PHPStan level 8
19+
- Code style enforcement with PSR-12
20+
21+
### Features
22+
- `ServerRequest::fromGlobals()` - Easy instantiation from PHP superglobals
23+
- `Response::byContentType()` - Automatic content serialization
24+
- Smart URI handling with IDN support
25+
- Specialized exception types for better error handling
26+
- Zero dependencies (only requires `psr/http-message`)
27+
28+
### Security
29+
- XXE protection in XML/HTML parsing
30+
- Path traversal protection in file uploads
31+
- Header injection prevention
32+
- Input validation and sanitization
33+
34+
## [Unreleased]
35+
36+
### Added
37+
- PHPStan static analysis tool for improved code quality
38+
- PHP CS Fixer for consistent code style enforcement
39+
- GitHub Actions workflow improvements with PHP version matrix testing
40+
- CHANGELOG.md for tracking project changes
41+
- CONTRIBUTING.md with detailed contribution guidelines
42+
- .editorconfig for consistent code formatting across editors
43+
44+
### Changed
45+
- Updated GitHub Actions cache action from v3 to v4
46+
- Improved CI/CD workflow with separate test and coverage jobs
47+
- Optimized Xdebug installation to only run when needed for coverage
48+
49+
[Unreleased]: https://github.com/pedroac/lean-http/compare/v0.1.0...HEAD

‎CONTRIBUTING.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# Contributing to lean-http
2+
3+
Thank you for your interest in contributing to lean-http! This document provides guidelines and instructions for contributing to the project.
4+
5+
## Getting Started
6+
7+
1. **Fork the repository** on GitHub
8+
2. **Clone your fork** locally:
9+
```bash
10+
git clone https://github.com/your-username/lean-http.git
11+
cd lean-http
12+
```
13+
3. **Install dependencies**:
14+
```bash
15+
composer install
16+
```
17+
4. **Setup git hooks** (optional but recommended):
18+
```bash
19+
chmod +x scripts/setup-git-hooks.sh
20+
./scripts/setup-git-hooks.sh
21+
```
22+
23+
This will enable a pre-commit hook that automatically runs code style checks, static analysis, and tests before allowing commits. This helps catch issues early and keeps the codebase clean.
24+
25+
## Development Workflow
26+
27+
### Making Changes
28+
29+
1. Create a new branch for your changes:
30+
```bash
31+
git checkout -b feature/your-feature-name
32+
```
33+
or
34+
```bash
35+
git checkout -b fix/your-bug-fix
36+
```
37+
38+
2. Make your changes following the coding standards (see below)
39+
40+
3. Run the quality checks before committing:
41+
```bash
42+
# Run tests
43+
composer test
44+
45+
# Check code style
46+
composer cs-check
47+
48+
# Run static analysis
49+
composer phpstan
50+
```
51+
52+
4. Fix any issues found by the tools:
53+
```bash
54+
# Auto-fix code style issues
55+
composer cs-fix
56+
```
57+
58+
5. Commit your changes with a clear, descriptive commit message
59+
60+
6. Push to your fork and create a pull request
61+
62+
## Coding Standards
63+
64+
### Code Style
65+
66+
This project follows **PSR-12** coding standards. We use PHP CS Fixer to enforce code style consistency.
67+
68+
- Run `composer cs-check` to check for style issues
69+
- Run `composer cs-fix` to automatically fix style issues
70+
71+
### Static Analysis
72+
73+
We use PHPStan for static analysis to catch potential bugs and type issues.
74+
75+
- Run `composer phpstan` to check for issues
76+
- PHPStan is configured at level 8 (maximum strictness)
77+
78+
### Testing
79+
80+
- All new features should include tests
81+
- All bug fixes should include tests that demonstrate the fix
82+
- Run `composer test` to execute the test suite
83+
- Ensure all tests pass before submitting a pull request
84+
85+
### Documentation
86+
87+
- Update the README.md if you add new features or change existing behavior
88+
- Add PHPDoc comments for new classes, methods, and properties
89+
- Update CHANGELOG.md with your changes (see below)
90+
91+
## Pull Request Process
92+
93+
1. **Fork and PR:** Fork the repository and create a pull request for any changes
94+
2. **Include tests:** All changes should include relevant tests
95+
3. **Update documentation:** Update README.md and other documentation as needed
96+
4. **Update CHANGELOG:** Add an entry to CHANGELOG.md describing your changes
97+
5. **Ensure quality checks pass:** All tests, code style checks, and static analysis must pass
98+
99+
### Pull Request Checklist
100+
101+
- [ ] Code follows PSR-12 coding standards
102+
- [ ] All tests pass (`composer test`)
103+
- [ ] Code style is correct (`composer cs-check`)
104+
- [ ] Static analysis passes (`composer phpstan`)
105+
- [ ] Documentation is updated (README.md, PHPDoc)
106+
- [ ] CHANGELOG.md is updated
107+
- [ ] Commit messages are clear and descriptive
108+
109+
## Issue Tracking
110+
111+
Use GitHub issues to:
112+
- Report bugs
113+
- Suggest new features
114+
- Ask questions
115+
- Discuss improvements
116+
117+
When reporting bugs, please include:
118+
- PHP version
119+
- Steps to reproduce
120+
- Expected behavior
121+
- Actual behavior
122+
- Any relevant error messages or stack traces
123+
124+
## Using AI Tools
125+
126+
Using AI tools like GitHub Copilot, ChatGPT, or similar tools is **encouraged** to:
127+
- Find issues faster
128+
- Ensure specifications are followed
129+
- Improve code quality
130+
- Generate test cases
131+
132+
However, **always apply critical thinking** and carefully review AI-generated suggestions. AI tools are assistants, not replacements for human judgment.
133+
134+
## Code Review
135+
136+
All pull requests will be reviewed. Reviewers may:
137+
- Request changes
138+
- Ask questions
139+
- Suggest improvements
140+
- Approve the changes
141+
142+
Please be patient and responsive to feedback. The goal is to maintain high code quality and consistency.
143+
144+
## Questions?
145+
146+
If you have questions about contributing, feel free to:
147+
- Open an issue on GitHub
148+
- Check existing issues and discussions
149+
- Review the README.md for project information
150+
151+
Thank you for contributing to lean-http! 🎉

0 commit comments

Comments
 (0)