diff --git a/README.md b/README.md index 91dfea0..7a2fb53 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ This path is designed for developers who want both a fast start and a clearer un The current Quantum 3.x baseline requires: -- PHP 8.0 or newer +- PHP 8.1 or newer - Composer - PHP extensions: `pdo`, `curl`, `json`, `simplexml`, `fileinfo`, `openssl`, `bcmath` diff --git a/v3.0/cli/code-generation.md b/v3.0/cli/code-generation.md index c9f18f3..dc0d791 100644 --- a/v3.0/cli/code-generation.md +++ b/v3.0/cli/code-generation.md @@ -150,18 +150,50 @@ This is another example where `qt` generates project state, not just source file ## OpenAPI resource generation -Quantum also includes: +Say you generated an API module from the `DefaultApi` or `DemoApi` template and want a page where you can read and try the API. Run: ```bash php qt install:openapi Api ``` -From the upstream `OpenApiCommand`, this command can: +Then open `/api/docs` for the Swagger UI page. The specification itself is served at `/api/spec`. Both routes sit under the module's route prefix, so a module with another prefix serves them there. + +The command: + +- publishes the Swagger UI resources into the public assets directory, and creates that folder when it is missing +- adds an `openapi` route group with the `docs` and `spec` routes to the module's routes when it has none +- creates the module's `resources/openapi/` directory, and `resources/` when the module has none +- generates `spec.json` from the controllers in the module's `Controllers/OpenApi` folder + +The API templates ship that folder with the documentation already written as PHP attributes. `OpenApiController` describes the API and its security scheme, and each operation is an attribute on an abstract controller method: + +```php +use OpenApi\Attributes as OA; + +abstract class OpenApiMainController extends OpenApiController +{ + #[OA\Get( + path: '/Api', + tags: ['Api'], + summary: 'Get status of Api', + responses: [ + new OA\Response( + response: 200, + description: 'Successful response', + content: new OA\JsonContent( + type: 'object', + properties: [ + new OA\Property(property: 'status', type: 'string', example: 'success'), + ] + ) + ), + ] + )] + abstract public function index(); +} +``` -- publish OpenAPI UI resources into the public assets directory -- update the target module routes for OpenAPI endpoints when needed -- create the module `resources/openapi/` directory -- generate an OpenAPI `spec.json` file from controller annotations +Documentation written as `@OA\...` docblock annotations is only read when `doctrine/annotations` is installed, and the framework no longer requires it. Without it `install:openapi` fails with `Required @OA\PathItem() not found`. Convert the annotations to attributes, or require `doctrine/annotations` in your application. So `qt` is also able to generate API documentation resources, not only application scaffolding. diff --git a/v3.0/installation.md b/v3.0/installation.md index a30f23f..d86bebe 100644 --- a/v3.0/installation.md +++ b/v3.0/installation.md @@ -6,7 +6,7 @@ This guide walks you through installing and running a new Quantum PHP project. Make sure your environment includes: -* **PHP 8.0+**; +* **PHP 8.1+**; * **PHP extensions**: * PDO * curl @@ -19,7 +19,7 @@ Make sure your environment includes: Optional framework features may require additional extensions or packages such as `redis`, `memcached`, `zip`, `dom`, or `twig/twig`. -Practical note: run `php -v` to check your PHP version before you start. Quantum needs PHP 8.0 or newer. +Practical note: run `php -v` to check your PHP version before you start. Quantum needs PHP 8.1 or newer. ### Installation Steps diff --git a/v3.0/packages/console/built-in-commands.md b/v3.0/packages/console/built-in-commands.md index 35bdaea..806e3af 100644 --- a/v3.0/packages/console/built-in-commands.md +++ b/v3.0/packages/console/built-in-commands.md @@ -113,7 +113,7 @@ Publishes DebugBar assets into `public/assets/DebugBar/Resources`. Publishes Swagger UI assets if needed, injects an `openapi` route group into the module route file when missing, and writes `resources/openapi/spec.json` for the target module. -Use it only after the module exists and has OpenAPI-annotated controllers in `Controllers/OpenApi`. +Use it only after the module exists and has controllers with OpenAPI attributes in `Controllers/OpenApi`. See [OpenAPI resource generation](../../cli/code-generation.md#openapi-resource-generation) for what it produces and how the documentation is written. ### `install:toolkit ` diff --git a/v3.0/packages/tracer/contracts.md b/v3.0/packages/tracer/contracts.md index 8dca390..2e9cda4 100644 --- a/v3.0/packages/tracer/contracts.md +++ b/v3.0/packages/tracer/contracts.md @@ -15,6 +15,8 @@ $handler->setup($logger); `handleError()` converts enabled PHP errors into `ErrorException`. +A deprecation (`E_DEPRECATED` or `E_USER_DEPRECATED`) is the exception. It only warns about a future PHP version, often from a library you do not control, so it should not stop the request. `handleError()` logs it with `warning()` as ` in :` and returns `true`, and the script goes on. When no logger is set, the deprecation is ignored. + Suppressed or masked severities are ignored (`false` return), so `@` suppression still works. ## Severity mapping contract diff --git a/v3.0/packages/tracer/overview.md b/v3.0/packages/tracer/overview.md index 6104d7e..f9a139a 100644 --- a/v3.0/packages/tracer/overview.md +++ b/v3.0/packages/tracer/overview.md @@ -25,7 +25,8 @@ $handler->setup($logger); After setup: - enabled PHP errors become `ErrorException` instances -- uncaught throwables are routed by runtime (`cli` or web) +- deprecations are [logged as warnings](contracts.md#error-conversion-contract) instead, and the script goes on +- uncaught throwables are routed by app type (console or web) - web requests return HTTP 500 for uncaught exceptions - production web requests log the exception before rendering the response