|
| 1 | +# Phenix Framework AI Instructions |
| 2 | + |
| 3 | +Phenix is an async-first PHP web framework built on Amphp v3 for high-performance applications. This guide helps AI agents understand the framework's unique patterns and architecture. **Phenix** is an asynchronous PHP web framework built on the [AmPHP](https://amphp.org/) ecosystem. It serves as the core framework for building scalable, async-first API applications. Official documentation can be found at [Phenix Documentation](https://phenix.omarbarbosa.com/). |
| 4 | + |
| 5 | +## Core Architecture |
| 6 | + |
| 7 | +### Async-First Design |
| 8 | +- Framework runs in CLI SAPI with its own HTTP server using `SocketHttpServer` |
| 9 | +- All I/O operations are non-blocking using Amphp primitives |
| 10 | +- Use `App::make()` for dependency resolution throughout the codebase |
| 11 | +- Service providers register dependencies in `App::setup()` method |
| 12 | + |
| 13 | +### Application Bootstrap |
| 14 | +```php |
| 15 | +// Standard app creation pattern |
| 16 | +$app = AppBuilder::build($path, $env); |
| 17 | +$app->run(); // Starts HTTP server and handles signals |
| 18 | +``` |
| 19 | + |
| 20 | +### Dependency Container Pattern |
| 21 | +- Uses League Container with service providers for registration |
| 22 | +- Access via `App::make(ClassName::class)` static method |
| 23 | +- Register services: `$app->register(Key::class, $concrete)` |
| 24 | +- Facades provide static access: `Config::get('key')`, `Route::get('/path')` |
| 25 | + |
| 26 | +## Key Components |
| 27 | + |
| 28 | +### Routing System (`src/Routing/`) |
| 29 | +- Fluent route builder: `Route::get('/users', $handler)->middleware($middleware)` |
| 30 | +- Groups support: `Route::group(fn() => Route::get('/admin', $handler))` |
| 31 | +- Automatic dependency injection in route handlers |
| 32 | +- Middleware stacking via `stackMiddleware()` |
| 33 | + |
| 34 | +### Queue System (`src/Queue/`) - Current Development Focus |
| 35 | +- Abstract `QueuableTask` base class for background jobs |
| 36 | +- Multiple drivers: `RedisQueue`, `DatabaseQueue`, `ParallelQueue` |
| 37 | +- Tasks use `ShouldQueue` interface and `enqueue()` static method |
| 38 | +- State management with `TaskState` for tracking job progress |
| 39 | + |
| 40 | +### Database & Query Builder (`src/Database/`) |
| 41 | +- Async database operations using Amphp MySQL/PostgreSQL drivers |
| 42 | +- Fluent query builder with method chaining |
| 43 | +- Connection factory pattern for multiple database connections |
| 44 | +- Migration system with console commands |
| 45 | + |
| 46 | +### Console Commands (`src/Console/`) |
| 47 | +- Symfony Console-based with `Phenix` application class |
| 48 | +- Maker commands extend `Maker` base class |
| 49 | +- Commands registered via service providers in `pushCommands()` |
| 50 | +- Stubs located in `src/stubs/` directory |
| 51 | + |
| 52 | +## Development Patterns |
| 53 | + |
| 54 | +### Service Provider Pattern |
| 55 | +```php |
| 56 | +class ExampleServiceProvider extends ServiceProvider |
| 57 | +{ |
| 58 | + public function register(): void { |
| 59 | + // Register bindings in container |
| 60 | + } |
| 61 | + |
| 62 | + public function provides(string $id): bool { |
| 63 | + // Declare what this provider provides |
| 64 | + } |
| 65 | +} |
| 66 | +``` |
| 67 | + |
| 68 | +### Testing with PestPHP |
| 69 | +- Unit tests: `tests/Unit/` with simple `it('description', fn() => expect()->toBe())` |
| 70 | +- Feature tests: `tests/Feature/` for HTTP integration |
| 71 | +- Use `Tests\TestCase` base class for both unit and feature tests |
| 72 | +- Run tests: `vendor/bin/pest` |
| 73 | + |
| 74 | +### Command Creation |
| 75 | +- Extend `Maker` class for generators |
| 76 | +- Define `stub()`, `outputDirectory()`, `commonName()` methods |
| 77 | +- Use `InputArgument` and `InputOption` for CLI parameters |
| 78 | +- Stubs use Mustache-style templating |
| 79 | + |
| 80 | +### Facades Pattern |
| 81 | +- Extend `Runtime\Facade` and implement `getKeyName()` |
| 82 | +- Provide `@method` docblocks for IDE support |
| 83 | +- Static calls proxy to container-resolved instances |
| 84 | + |
| 85 | +## File Organization |
| 86 | + |
| 87 | +- **Core**: `src/App.php` (main application), `src/AppBuilder.php` (factory) |
| 88 | +- **HTTP**: `src/Http/` (requests, responses, middleware) |
| 89 | +- **Database**: `src/Database/` (query builder, migrations, models) |
| 90 | +- **Queue**: `src/Queue/` (async job processing system) |
| 91 | +- **Console**: `src/Console/Commands/` (CLI commands) |
| 92 | +- **Config**: Framework uses dotenv with `src/Runtime/Environment` |
| 93 | +- **Tests**: PestPHP in `tests/` with `Unit/` and `Feature/` directories |
| 94 | + |
| 95 | +## Key Conventions |
| 96 | + |
| 97 | +- All classes use strict types: `declare(strict_types=1);` |
| 98 | +- PSR-12 code style with type hints for all methods |
| 99 | +- Async operations return Amphp `Future` objects when applicable |
| 100 | +- Service providers define dependencies in `provides()` method |
| 101 | +- Queue tasks extend `QueuableTask` and implement `handle()` method |
| 102 | +- Database models extend base model with async query methods |
| 103 | +- Middleware implements Amphp HTTP middleware interface |
| 104 | + |
| 105 | +## Integration Points |
| 106 | + |
| 107 | +- **AmphpPHP**: Core async runtime and HTTP server |
| 108 | +- **League Container**: Dependency injection container |
| 109 | +- **Symfony Console**: CLI command framework |
| 110 | +- **PestPHP**: Testing framework |
| 111 | +- **Monolog**: Logging with async handlers |
| 112 | +- **Redis/MySQL/PostgreSQL**: Async database drivers |
0 commit comments