This is the EDT monorepo, containing the development of multiple composer packages. In conjunction these packages can be used in PHP applications (if they already use Doctrine as ORM framework) to define a functional web-API contract, adhering to the JSON:API specification.
This library enables you to expose the entity class instances in your PHP application as REST resources using the feature rich JSON:API specification as API contract. How and to whom you expose your entities is highly customizable while minimizing the need of manually written boilerplate code.
Without custom extensions, usage is currently limited to applications building their entities uppon the Doctrine ORM. However, as the different underlying functionalities are split and encapsulated in many individual PHP classes, put together via constructor-based dependency injection, a high degree of customizability and extensibility is ensured.
These classes are structured into multiple composer packages contained in this repository, to ease re-usage for different use cases without the need to include large, unnecessary dependencies. E.g. instead of using it as a whole, you may want to use parts of this library to build your own API implementation more easily. If you do, you can simply skip the Doctrine ORM dependency and implement your own way to access the data source of your entities.
Due to the variety of features provided by the JSON:API specification, implementing it in a maintainable way may provide a challenge. After an initial setup, this library reduces your duty to expressing your intents regarding your web-API contract once, avoiding the risks of inconsistencies due to redundancy.
This is especially helpful in large, volatile, fast-growing web-applications with demanding clients, where most new business features may require new entities or properties to be exposed to them.
On the other hand, for small and relatively settled applications, this library may not be the right choice. This is due to the currently notable time cost for the initial setup, especially in case of applications that don’t already use Symfony and the Doctrine ORM framework. At some point the setup difficulty may be reduced, but for now, batteries are not included.
|
Note
|
The initial setup is quite complex and a considerable entry barrier. But as it only needs to be done once, this section will attempt to give an idea of the more relevant typical day-to-day usage instead. |
When you express your intent regarding your API’s capabilities and schema with this library, it is logically centered around the resources and their properties.
For example, if you wanted to expose your Book entity of your bookstore, you’d write a corresponding PHP configuration, defining which properties of the Book entity are to be available via Book resources.
For the following example we assume that you also want to expose Person entities as Author resources, with each book having potentially multiple authors.
erDiagram
Book {
string id
string title
int price
}
Person {
string id
string fullName
}
Person ||--o{ Book : books
Book ||--o{ Person : authors
The library allows for multiple approaches to define your resources.
The following code shows an example how to use the highest level of abstraction provided by the library: type config classes.
Using these you can create a configuration that will be applied to all resources of a specific type (i.e. using the same value in their type field).
After creating the configuration instance you have access to methods to set some general information and behavior of the type, but you can also configure the schema of the type by accessing the corresponding properties on the type config instance.
$bookConfig = new BookBasedResourceConfig($propertyFactory); (1)
$authorConfig = new PersonBasedResourceConfig($propertyFactory); (2)
$bookConfig->id
->setReadableByPath();
$bookConfig->title (3)
->setReadableByPath()
->setSortable()
->setFilterable();
$bookConfig->price
->setReadableByPath()
->setFilterable()
->addPathUpdateBehavior(); (4)
$bookConfig->authors
->setRelationshipType($authorConfig) (5)
->setFilterable()
->setReadableByPath()
->addPathUpdateBehavior();
$authorConfig->setTypeName('Author'); (6)
$authorConfig->id
->setReadableByPath();
$authorConfig->fullName
->setReadableByPath()
->setFilterable();
$authorConfig->books
->setRelationshipType($bookConfig) (7)
->setReadableByPath();-
You can automatically generate and re-generate a basic configuration template class like
BookBasedResourceConfigfrom your entity class (i.e.Book). This avoids manually writing and maintaining some boilerplate code and helps for its actual configuration, e.g. by providing proper type hinting and IDE autocompletion support. -
Because resources often reference each other via relationship properties, we first create all configuration instances and configure them afterward.
-
Individual properties can be configured using fluent, self-referential methods. I.e. each method call on a property will return that property, so it can be used for further method calls.
-
To keep this example small, the
priceattribute andauthorsrelationship are the only properties that can be updated via the JSON:API. For the same reason we omitted other features here, like default sorting, limiting access to instances and the creation of resources, which are all possible too. -
When configuration template classes are generated, the
authorsrelationship from theBookentity to thePersonentity was automatically deduced, but you may expose yourPersonentity via different resource types, using different configurations each. Thus, you need to define which of them theBookresources references, by setting the specific$authorConfigconfiguration. -
By default, the type name of your exposed resources will be the same as the name of the backing entity. This is correct for the
Bookresources, but for theAuthorresources we need to specify the name, otherwisePersonwould be used as resource type name. -
By not only referencing the authors by the
Bookresource but also the books by theAuthorresource, we created a bidirectional relationship, which is not necessary and (without workarounds) requires a corresponding relationship in thePersonentity, but provides greater flexibility to the client.
When a request is received, the library will automatically validate it against the configuration above and deny it, if access violations are detected. Access is only granted as defined, no other entities or properties will be exposed and the exposed properties can only be used as configured.
|
Note
|
In this basic example we simply exposed all Book and Person entities that are stored in your data source as Book and Author resources and didn’t distinguish access rights based on authorizations.
In practice this may often not be acceptable.
We also assumed that all exposed resource properties have a corresponding property in the entity, which is also not always the case.
Consequently, the configuration classes provide additional methods to control the access and mitigate schema divergences.
Those methods and others, e.g. to configure the creation of resources, were not shown in the example above.
For a more thorough overview of the configuration capabilities as Q&A, please see Configuring Resources.
|
Even though the two resource configurations were mostly done independently, their definition as shown above directly result in some synergies and multiple JSON:API specification features provided to the client, briefly explained in the following sections.
Clients can not only fetch Book resources in one request and Author resources in another, but also state in the fetch request of one or multiple Book resources that referenced Author resources shall be included in the response.
Because of the bidirectional relationship between books and authors this also works the other way around.
From a security perspective this is of no concern, as it does not expose any additional data, but simply allows to request and use it in a more convenient way.
Also, setting the authors relationship as (for example) updatable will allow to change the list of author, but the values set must be resources corresponding to the exact resource type set via setResourceType($authorConfig).
Otherwise, the request would be denied.
Setting the fullName attribute as filterable allows the client to fetch Author resources filtered by that attribute.
But by setting the authors relationship in the Book resource as filterable as well, the client can now filter Book resources by the name of the corresponding authors of each book.
The same is true in regard to sorting Book resources by the data stored in to-one relationships, as long as the corresponding properties are set as filterable.
However, sorting by to-many relationships is currently not supported.
I.e. you could sort Book resources by the name of their authors, if every book only has a single author.
But you can’t do that if a single book has many authors.
While the JSON:API specification provides a format to define the intended sorting, it leaves the format to define filters open.
By default, this library supports the standard Drupal filter format, with its shorthands not yet being supported.
The Drupal filter format allows to define simple but also complex filters, including nested AND/OR groups and a set of many different operators.
The implementation in this library is able to automatically convert such filters into the corresponding DQL query to fetch Doctrine entities.
If wanted, support for custom operators can be added.
Otherwise, no additional implementation is needed beside configuring resource properties as filterable as shown above.
Even though the packages are already used in production, they’re not recommended for general usage yet. While development has settled down in some parts, in others refactorings are still necessary, resulting in deprecations and backward compatibility breaking changes. Because the initial setup still requires extensive work and crucial documentation is missing, the entry barrier can also be deemed too high.
However, contributions are welcome:
The objective is to get the project to a more stable state over the course of the year 2024, ideally releasing a 1.0.0 version with a more reliable API and proper documentation before 2025.
Even after a stable release, adding optional features and support for future JSON:API specification versions is left as an ongoing process. Similarly, easing the usage with applications not based on Symfony and Doctrine is not the scope of a first stable version.
Conception and implementation by Christian Dressler with many thanks to eFrane.
Additional thank goes to DEMOS plan GmbH, which provided the initial use-case and the opportunity to implement relevant parts to solve it.