85 lines
3.0 KiB
Markdown
85 lines
3.0 KiB
Markdown
# camelia/controllers
|
|
|
|
[](https://packagist.org/packages/camelia/controllers)
|
|
[](https://packagist.org/packages/camelia/controllers)
|
|
[](https://packagist.org/packages/camelia/controllers)
|
|
[](https://git.dr2gsistemas.duckdns.org/dr2gsistemas/camelia-controller/actions)
|
|
|
|
Framework-agnostic REST controller toolkit: routing, request parsing, validation and JSON responses
|
|
over any data source. Vanilla PHP, no framework.
|
|
|
|
- **Package:** `camelia/controllers` — **Namespace:** `Camelia\Controllers`
|
|
- **PHP** `>=8.4`, extension `json`
|
|
|
|
## What it is
|
|
|
|
The HTTP layer of a REST API, and nothing else:
|
|
|
|
- **Routing** with parameters (`/articulos/{id}`), plus 404 and 405 responses with an `Allow` header.
|
|
- **Immutable request and response** objects. Nothing is printed; a `Response` is returned and the
|
|
adapter emits it.
|
|
- **Generic CRUD** over a `ResourceGateway` port that the application implements.
|
|
- **Composable middlewares:** authentication, roles, rate limiting, CORS, logging, content
|
|
negotiation.
|
|
|
|
## What it is not
|
|
|
|
Not a framework. No dependency-injection container, no ORM, no templating. The package declares its
|
|
own ports; if an application uses an ORM, it connects it by composition.
|
|
|
|
## Install
|
|
|
|
```bash
|
|
composer require camelia/controllers
|
|
```
|
|
|
|
## OpenAPI
|
|
|
|
`OpenApi::register()` derives an OpenAPI 3.0 document from the routes already registered on a
|
|
router and serves it under a prefix:
|
|
|
|
```php
|
|
use Camelia\Controllers\{OpenApi, Router};
|
|
|
|
$router = new Router();
|
|
$router->get('/articulos/{id}', /* handler */);
|
|
|
|
OpenApi::register($router, '/docs/', ['title' => 'Facturación', 'version' => '2.0.0']);
|
|
```
|
|
|
|
- `GET /docs/` serves an HTML viewer with the document inline.
|
|
- `GET /docs/openapi.json` serves the raw document.
|
|
|
|
The document describes paths, methods and path parameters. It has no request or response schemas:
|
|
the library holds no payload metadata, and deriving it here would duplicate what the application
|
|
already knows.
|
|
|
|
## Documentation
|
|
|
|
The full developer guide, organised by task, is in
|
|
[`docs/GUIA-PROGRAMADOR.md`](docs/GUIA-PROGRAMADOR.md). The normative contract — public names, JSON
|
|
shapes and status codes — is [`docs/especificaciones-controllers.md`](docs/especificaciones-controllers.md).
|
|
|
|
The documentation index lives in [`docs/README.md`](docs/README.md).
|
|
|
|
## Development
|
|
|
|
```bash
|
|
composer install
|
|
composer check # fmt:check -> lint -> analyze -> phpstan -> test
|
|
```
|
|
|
|
`composer check` must be green before anything is merged, and the steps run in that order.
|
|
|
|
The same gate runs on every commit once the hook is enabled per clone:
|
|
|
|
```bash
|
|
git config core.hooksPath .githooks
|
|
```
|
|
|
|
Use `git commit --no-verify` to bypass it for a single commit.
|
|
|
|
## License
|
|
|
|
MIT. See [LICENSE](LICENSE).
|