framework: Instructions file for GitHub Copilot

Phenix Framework AI Instructions

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 ecosystem. It serves as the core framework for building scalable, async-first API applications. Official documentation can be found at Phenix Documentation.

Core Architecture

Async-First Design

• Framework runs in CLI SAPI with its own HTTP server using SocketHttpServer
• All I/O operations are non-blocking using Amphp primitives
• Use App::make() for dependency resolution throughout the codebase
• Service providers register dependencies in App::setup() method

Application Bootstrap

// Standard app creation pattern
$app = AppBuilder::build($path, $env);
$app->run(); // Starts HTTP server and handles signals

Dependency Container Pattern

• Uses League Container with service providers for registration
• Access via App::make(ClassName::class) static method
• Register services: $app->register(Key::class, $concrete)
• Facades provide static access: Config::get('key'), Route::get('/path')

Key Components

Routing System (src/Routing/)

• Fluent route builder: Route::get('/users', $handler)->middleware($middleware)
• Groups support: Route::group(fn() => Route::get('/admin', $handler))
• Automatic dependency injection in route handlers
• Middleware stacking via stackMiddleware()

Queue System (src/Queue/) - Current Development Focus

• Abstract QueuableTask base class for background jobs
• Multiple drivers: RedisQueue, DatabaseQueue, ParallelQueue
• Tasks use ShouldQueue interface and enqueue() static method
• State management with TaskState for tracking job progress

Database & Query Builder (src/Database/)

• Async database operations using Amphp MySQL/PostgreSQL drivers
• Fluent query builder with method chaining
• Connection factory pattern for multiple database connections
• Migration system with console commands