gearsite / api
JSON API for Doctrine ORM Based Projects
Maintainers
Requires
- php: ^8.2
- doctrine/orm: ^3.0
- doctrine/persistence: ^3.0 || ^4.0
- psr/log: ^2.0 || ^3.0
- symfony/dependency-injection: ^6.4 || ^7.0 || ^8.0
- symfony/http-foundation: ^6.4 || ^7.0 || ^8.0
- symfony/http-kernel: ^6.4 || ^7.0 || ^8.0
- symfony/security-bundle: ^6.4 || ^7.0 || ^8.0
- symfony/stopwatch: ^6.4 || ^7.0 || ^8.0
Requires (Dev)
- phpunit/phpunit: ^9
- symfony/console: ^6.4 || ^7.0 || ^8.0
- symfony/maker-bundle: ^1.60
Suggests
- symfony/maker-bundle: Enables the make:api-serializer scaffolding command
README
A JSON API library for Symfony and Doctrine ORM. It renders Doctrine entities as JSON API documents. It also applies JSON API request bodies back onto those entities.
Install
composer require gearsite/api
Symfony Flex registers the bundle for you. The recipe writes this line in config/bundles.php:
Gearsite\Api\GearsiteJSONAPIBundle::class => ['all' => true],
NOTE: If you do not use Flex, add that line yourself. Flex configures a package only from its recipe. This package has one.
Quick start
Read docs/quick-start.md to build your first endpoint.
Features
- Serializers — declare the fields and relationships of each entity. Computed fields and role-secured fields are supported.
- Query generation — the library adds the JOINs for computed fields and the sort clause. You supply the pagination and filter strategy.
- Deserialization — apply a JSON API body onto an entity with PATCH semantics.
- Atomic operations — apply a batch of writes in one transaction.
- Security — remove fields and relationships by role, both in the query and in the response.
Supported query parameters:
| Parameter | Example |
|---|---|
| Sparse fieldsets | ?fields[article]=title,body |
| Includes | ?include=comments.author |
| Sort | ?sort=title,-created |
| Pagination | ?page[number]=2&page[size]=25 |
| Filter | ?filter[status]=published |
The library parses page and filter for you. You define what they mean.
Requirements
- PHP 8.2 or later
- Symfony 7.0 or later
- Doctrine ORM 3.0 or later
Documentation
- Quick start — a working endpoint in four steps
- Serializers — fields, relationships, security, and writes
- Atomic operations — batch writes in one transaction
Contributing
Read CONTRIBUTING.md for the setup, the test suites, and the code style.
Security
To report a vulnerability, email security@gearsite.net. Read SECURITY.md for the policy and the scope.
License
MIT. Read LICENSE.