Skip to content

Commit 5ccce7f

Browse files
CAFernandesCAFernandes
committed
feat: Add ResponseBridge for converting PSR-7 responses to ReactPHP responses
feat: Implement ServeCommand to start the ReactPHP HTTP server with options feat: Create ReactPHPServiceProvider to register services and commands for ReactPHP integration feat: Develop ReactServer to handle HTTP requests and responses using ReactPHP feat: Introduce ReactServerCompat for compatibility with PSR-7 conflicts test: Add RequestBridgeTest to validate request conversion from React to PivotPHP test: Add ResponseBridgeTest to ensure proper response conversion from PivotPHP to React test: Implement ReactServerTest to verify server functionality and request handling test: Create TestCase for setting up common test dependencies and utilities
0 parents  commit 5ccce7f

25 files changed

+4258
-0
lines changed

‎.gitignore‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
/vendor/
2+
/composer.lock
3+
/.phpunit.cache/
4+
/coverage/
5+
/.idea/
6+
/.vscode/
7+
/phpunit.xml
8+
/.env
9+
/.env.local
10+
/.env.*.local
11+
/var/
12+
/logs/
13+
*.log
14+
.DS_Store
15+
Thumbs.db
16+
/build/
17+
/dist/
18+
/node_modules/
19+
/.php-cs-fixer.cache
20+
/.phpstan/
21+
/psalm.xml
22+
/.psalm/
23+
/infection.log
24+
/infection-log.txt

‎CLAUDE.md‎

Lines changed: 210 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,210 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Repository Overview
6+
7+
This is the PivotPHP ReactPHP extension - a high-performance continuous runtime extension for PivotPHP using ReactPHP's event-driven, non-blocking I/O model. This extension bridges PivotPHP's PSR-7 implementation with ReactPHP's server to provide persistent application state and eliminate bootstrap overhead.
8+
9+
## Essential Commands
10+
11+
### Development
12+
```bash
13+
# Quality checks
14+
composer quality:check # Run all quality checks (CS, PHPStan, tests)
15+
composer phpstan # Static analysis (Level 9 strict)
16+
composer cs:check # PSR-12 code style check
17+
composer cs:fix # Auto-fix code style issues
18+
19+
# Testing
20+
composer test # Run all tests
21+
composer test:coverage # Run tests with HTML coverage report
22+
23+
# Server operations
24+
composer server:start # Start ReactPHP server (examples/server.php)
25+
```
26+
27+
### Server Management
28+
```bash
29+
# Start development server
30+
php examples/server.php
31+
32+
# Start async features example
33+
php examples/async-example.php
34+
35+
# Console command (if integrated with PivotPHP console)
36+
php artisan serve:reactphp --host=0.0.0.0 --port=8080
37+
```
38+
39+
### PSR-7 Version Management
40+
```bash
41+
# Check current PSR-7 version in PivotPHP Core
42+
php vendor/pivotphp/core/scripts/switch-psr7-version.php --check
43+
44+
# Switch to PSR-7 v1.x for ReactPHP compatibility (if needed)
45+
php vendor/pivotphp/core/scripts/switch-psr7-version.php 1
46+
composer update psr/http-message
47+
48+
# Note: Upcoming PivotPHP Core version will have native PSR-7 support
49+
```
50+
51+
## Code Architecture
52+
53+
### Core Components
54+
1. **ReactServer** (`src/Server/ReactServer.php`): Main server class that bridges ReactPHP's HttpServer with PivotPHP Application
55+
2. **Request/Response Bridges** (`src/Bridge/`): Convert between ReactPHP and PivotPHP PSR-7 implementations
56+
3. **Service Provider** (`src/Providers/ReactPHPServiceProvider.php`): Registers all ReactPHP services with PivotPHP's container
57+
4. **Console Command** (`src/Commands/ServeCommand.php`): Provides CLI interface for server management
58+
59+
### Request Flow Architecture
60+
```
61+
ReactPHP Request → RequestBridge → PivotPHP Request → Application → PivotPHP Response → ResponseBridge → ReactPHP Response
62+
```
63+
64+
### PSR-7 Compatibility Layer
65+
The extension includes a PSR-7 compatibility adapter (`src/Adapter/Psr7CompatibilityAdapter.php`) that handles version differences between ReactPHP's PSR-7 v1.x requirements and PivotPHP's PSR-7 implementation. Note: Future PivotPHP Core versions will provide native PSR-7 support, reducing the need for this compatibility layer.
66+
67+
### Bridge Pattern Implementation
68+
- **RequestBridge**: Temporarily manipulates global state ($_SERVER, $_GET, $_POST) to create PivotPHP Request objects, then restores original state
69+
- **ResponseBridge**: Converts PivotPHP Response objects to ReactPHP Response objects, handling streaming and content types
70+
71+
### Service Provider Pattern
72+
ReactPHP services are registered via `ReactPHPServiceProvider` which:
73+
- Registers ReactPHP event loop as singleton
74+
- Binds request/response bridges
75+
- Configures ReactServer with application instance
76+
- Registers console commands if available
77+
78+
## Key Implementation Details
79+
80+
### Global State Management
81+
The RequestBridge uses a critical pattern for PivotPHP compatibility:
82+
```php
83+
// Save original state
84+
$originalServer = $_SERVER ?? [];
85+
$originalGet = $_GET ?? [];
86+
$originalPost = $_POST ?? [];
87+
88+
try {
89+
// Modify globals for PivotPHP Request construction
90+
$_SERVER = $this->prepareServerVariables($reactRequest);
91+
$_GET = $reactRequest->getQueryParams();
92+
$_POST = $this->preparePostData($reactRequest);
93+
94+
// Create PivotPHP Request (reads from globals)
95+
$pivotRequest = new Request($method, $path, $path);
96+
97+
return $pivotRequest;
98+
} finally {
99+
// Always restore original state
100+
$_SERVER = $originalServer;
101+
$_GET = $originalGet;
102+
$_POST = $originalPost;
103+
}
104+
```
105+
106+
### Header Name Conversion
107+
PivotPHP converts HTTP headers to camelCase format:
108+
- `Content-Type` → `contentType`
109+
- `Authorization` → `authorization`
110+
- `X-API-Key` → `xApiKey`
111+
- `Accept-Language` → `acceptLanguage`
112+
113+
### Event Loop Management
114+
The server uses ReactPHP's event loop with proper signal handling for graceful shutdown (SIGTERM, SIGINT).
115+
116+
### Memory Management
117+
Continuous runtime means:
118+
- Application and services persist across requests
119+
- Database connections can be kept alive
120+
- Cached data survives between requests
121+
- Memory usage must be monitored
122+
123+
## Testing Approach
124+
125+
### Test Structure
126+
- Tests extend custom `TestCase` which sets up ReactPHP event loop and PSR-7 factories
127+
- Each test creates fresh application instance to avoid state pollution
128+
- Request/Response bridges are tested with various HTTP scenarios
129+
130+
### Testing PSR-7 Factories
131+
The codebase uses specific PivotPHP PSR-7 factories:
132+
```php
133+
use PivotPHP\Core\Http\Psr7\Factory\RequestFactory;
134+
use PivotPHP\Core\Http\Psr7\Factory\ResponseFactory;
135+
use PivotPHP\Core\Http\Psr7\Factory\ServerRequestFactory;
136+
use PivotPHP\Core\Http\Psr7\Factory\StreamFactory;
137+
use PivotPHP\Core\Http\Psr7\Factory\UriFactory;
138+
```
139+
140+
### Test Coverage
141+
- Request bridge conversion (headers, body, query params)
142+
- Response bridge conversion (status codes, headers, streaming)
143+
- Server lifecycle (start, stop, request handling)
144+
- Error handling and recovery
145+
146+
## Configuration
147+
148+
### Default Configuration
149+
```php
150+
return [
151+
'server' => [
152+
'debug' => env('APP_DEBUG', false),
153+
'streaming' => env('REACTPHP_STREAMING', false),
154+
'max_concurrent_requests' => env('REACTPHP_MAX_CONCURRENT_REQUESTS', 100),
155+
'request_body_size_limit' => env('REACTPHP_REQUEST_BODY_SIZE_LIMIT', 67108864), // 64MB
156+
'request_body_buffer_size' => env('REACTPHP_REQUEST_BODY_BUFFER_SIZE', 8192), // 8KB
157+
],
158+
];
159+
```
160+
161+
### Environment Variables
162+
- `REACTPHP_HOST`: Server host (default: 0.0.0.0)
163+
- `REACTPHP_PORT`: Server port (default: 8080)
164+
- `REACTPHP_STREAMING`: Enable streaming requests
165+
- `REACTPHP_MAX_CONCURRENT_REQUESTS`: Concurrent request limit
166+
- `APP_DEBUG`: Enable debug mode for error details
167+
168+
## Performance Considerations
169+
170+
### Continuous Runtime Benefits
171+
- No bootstrap overhead per request
172+
- Persistent database connections
173+
- Shared application state and caches
174+
- Faster response times under load
175+
176+
### Production Deployment
177+
- Use process managers (Supervisor) for reliability
178+
- Load balance across multiple ports
179+
- Monitor memory usage over time
180+
- Configure appropriate request limits
181+
182+
## Development Workflow
183+
184+
1. **Quality Checks**: Always run `composer quality:check` before committing
185+
2. **PHPStan Level 9**: Code must pass strict static analysis
186+
3. **PSR-12 Standard**: Code style must be compliant
187+
4. **Test Coverage**: All new features require tests
188+
5. **Documentation**: Update IMPLEMENTATION_GUIDE.md for significant changes
189+
190+
## Common Issues and Solutions
191+
192+
### PSR-7 Version Conflicts
193+
**Problem**: ReactPHP requires PSR-7 v1.x but PivotPHP uses v2.x
194+
**Solution**: Use PivotPHP's built-in version switching script (temporary solution until native PSR-7 support is available)
195+
196+
### Request Object Immutability
197+
**Problem**: PivotPHP Request objects are immutable
198+
**Solution**: Use global state manipulation pattern in RequestBridge
199+
200+
### Memory Leaks in Long-Running Processes
201+
**Problem**: Continuous runtime can accumulate memory
202+
**Solution**: Monitor usage, use weak references, periodic cleanup
203+
204+
## Future Enhancements
205+
206+
- WebSocket support for real-time communication
207+
- HTTP/2 and HTTP/3 support
208+
- Built-in clustering for multi-core utilization
209+
- Server-sent events (SSE) implementation
210+
- Enhanced middleware pipeline integration

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2024 PivotPHP
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

0 commit comments

Comments
 (0)