|
| 1 | +# Agent Guide: Ymir PHP Runtime |
| 2 | + |
| 3 | +This repository contains the Ymir PHP runtime for AWS Lambda. It provides the necessary infrastructure to run PHP applications (WordPress, Laravel, etc.) on Lambda, including support for FastCGI/PHP-FPM. |
| 4 | + |
| 5 | +## Development Commands |
| 6 | + |
| 7 | +### Build & Setup |
| 8 | +- **Install Dependencies:** `composer install` |
| 9 | + |
| 10 | +### Quality Control (Linting & Static Analysis) |
| 11 | +- **Check Code Style:** `composer php-cs-fixer` (dry-run) |
| 12 | +- **Fix Code Style:** `composer php-cs-fixer:fix` (automatically applies fixes) |
| 13 | +- **Static Analysis:** `composer phpstan` (PHPStan level 9) |
| 14 | +- **Generate Baseline:** `composer phpstan:generate-baseline` (never run this without approval) |
| 15 | +- **Rector (Refactoring):** `composer rector` (dry-run) |
| 16 | +- **Apply Rector Fixes:** `composer rector:fix` |
| 17 | + |
| 18 | +### Testing |
| 19 | +- **Run All Unit Tests:** `composer tests:unit` |
| 20 | +- **Run a Single Test File:** `composer tests:unit -- tests/Unit/Path/To/Test.php` |
| 21 | +- **Run a Specific Test Method:** `composer tests:unit -- --filter testMethodName` |
| 22 | + |
| 23 | +--- |
| 24 | + |
| 25 | +## Code Style & Standards |
| 26 | + |
| 27 | +These are extra rules not covered by PHP-CS-Fixer and Rector. |
| 28 | + |
| 29 | +- Always import classes. Never use the full class name. |
| 30 | + |
| 31 | +--- |
| 32 | + |
| 33 | +## Architecture Overview |
| 34 | + |
| 35 | +### Runtime Loop |
| 36 | +The runtime operates in a loop, fetching the next invocation from the Lambda Runtime API, handling it, and sending the response back. The core logic resides in `src/AbstractRuntime.php`. |
| 37 | + |
| 38 | +### Event Handlers |
| 39 | +Events are processed by handlers implementing `LambdaEventHandlerInterface`. |
| 40 | +- **Location:** `src/Lambda/Handler/` |
| 41 | +- **Http Handlers:** Special handlers for WordPress, Laravel, Bedrock, and generic PHP scripts. They often inherit from `AbstractHttpRequestEventHandler`. |
| 42 | +- **Sqs Handlers:** Handlers for SQS events, inheriting from `AbstractSqsHandler`. |
| 43 | +- **Handler Collection:** `LambdaEventHandlerCollection` manages multiple handlers and finds the first one that can handle a given event. |
| 44 | + |
| 45 | +### FastCGI & PHP-FPM |
| 46 | +For website runtimes, the runtime starts a PHP-FPM process and communicates with it via FastCGI. |
| 47 | +- **FastCGI Client:** Uses `hollodotme/fast-cgi-client`. |
| 48 | +- **PhpFpmProcess:** Manages the lifecycle of the PHP-FPM process (start, stop, health checks). See `src/FastCgi/PhpFpmProcess.php`. |
| 49 | + |
| 50 | +### Runtime Context |
| 51 | +The `RuntimeContext` class centralizes access to environment variables, logger, and other shared services like `LambdaClient` and `SsmClient`. |
| 52 | + |
| 53 | +### Runtime Build |
| 54 | +Docker based runtime build |
| 55 | +- **Location:** `runtime/` |
| 56 | + |
| 57 | +--- |
| 58 | + |
| 59 | +## Testing Strategy |
| 60 | + |
| 61 | +### Unit Tests |
| 62 | +- **Location:** `tests/Unit` |
| 63 | +- **Mocking:** Use traits found in `tests/Mock` to facilitate mocking common dependencies. |
| 64 | + - `LoggerMockTrait` for `Logger` |
| 65 | + - `LambdaRuntimeApiClientMockTrait` for `RuntimeApiClient` |
| 66 | + - `LambdaClientMockTrait` for `LambdaClient` |
| 67 | +- **PHPUnit Version:** PHPUnit 8 is used. Ensure tests are compatible with this version. |
| 68 | + |
| 69 | +### Test Patterns |
| 70 | +- Always test for both successful outcomes and expected exceptions. |
| 71 | +- Use `getFunctionMock` from `FunctionMockTrait` to mock global PHP functions like `getenv`, `curl_init`, etc. |
| 72 | +- Mock objects should be created using the provided traits whenever possible to maintain consistency. |
| 73 | + |
| 74 | +--- |
| 75 | + |
| 76 | +## Implementation Rules for Agents |
| 77 | + |
| 78 | +1. **Verify PSR-4:** Ensure new classes are in the correct namespace under `Ymir\Runtime` (`src/`) or `Ymir\Runtime\Tests` (`tests/`). |
| 79 | +2. **Strict Typing:** Always include `declare(strict_types=1);` and use property, parameter, and return types. |
| 80 | +3. **Run Linting:** Always run `composer php-cs-fixer:fix` and `composer rector:fix` after modifying code. |
| 81 | +4. **Run PHPStan:** Always run `composer phpstan` after changes to ensure type safety. Never fix a PHPStan issue with a comment block. |
| 82 | +5. **Mocking:** When writing tests, check `tests/Mock` first to see if a mock trait already exists for the service you are testing. |
| 83 | +6. **Environment Variables:** Handle Lambda environment variables via `RuntimeContext` or `getenv()` where appropriate. |
| 84 | +7. **No Dependencies:** Avoid adding new dependencies unless absolutely necessary and approved. |
| 85 | +8. **Yoda Style:** Maintain Yoda style in all comparisons. |
| 86 | +9. **Look around:** Scan nearby files (in the same namespace or unit test files) when creating a new file to figure out the conventions |
| 87 | +10. **One level of indentation:** Stick to one level of indentation unless it's impossible to do so. Nested statements should be avoided. |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments