Mercure.rocks is a brand new protocol allowing to push data updates to web browsers and other HTTP clients in a convenient, fast, reliable and battery-efficient way. It is especially useful to publish real-time updates of resources served through web APIs, to reactive web and mobile apps.
Both Symfony and API Platform now have an official support for this protocol!
From the ground, Mercure has been designed to work with technologies not able to maintain persistent connections. It’s especially relevant in serverless environments, but is also convenient when using PHP or FastCGI scripts.
Mercure is basically a higher-level replacement for WebSocket. Unlike WebSocket, it is compatible with HTTP/2 and HTTP/3.
It has been designed with hypermedia APIs in mind, is auto-discoverable through the Web Linking RFC and is also compatible with GraphQL.
It natively supports authorization, reconnection in case of network issue (with refetching of missed events), subscribing to several topics, topics patterns (using templated URIs)…
Because it is built on top of Server-sent Events and plain old HTTP requests, it is already compatible with all modern browsers, and requires 0 client-side dependencies.
The protocol is open (available as an Internet Draft), and a reference open source implementation of the server written in Go is available.—
I’m pleased to announce the immediate availability of API Platform 2.4 beta! This new version is a huge one, that comes with a large set of new features.
For newcomers, API Platform is a full-stack framework to develop in a breath high quality API-driven projects. Among other (lower level) libraries, API Platform provides:
To create your initial project, you just have to describe the public structures of the data to expose through the API. API Platform will take care of exposing the web API and bootstrapping the clients to consume it: get started with API Platform.
Version 2.4 introduces a lot of very interesting new features. Here is the curated list:
Read and write support for MongoDB, the reference document database, including a lot of useful filters
Read support for Elasticsearch, the open source search and analytics engine, including filters for advanced search
Automatic “push” of updated resources from the server to the clients using the brand new Mercure protocol
Integration with the Symfony Messenger component to easily implement the CQRS pattern and to handle messages asynchronously (using brokers such as RabbitMQ, Apache Kafka, Amazon SQS or Google PubSub)
Automatic availability of list filters in the React-based admin when a corresponding one is available API-side
Full compatibility with the version 3 of the OpenAPI specification format (formerly known as Swagger), and integration of the beautiful ReDoc documentation generator
With 114 commits and 234 files changed over almost 3 years. This is one of the biggest contributions to the project.
The MongoDB integration relies on Doctrine MongoDB ODM 2.0 (currently in beta). To enable this feature, just install and configure DoctrineMongoDBBundle. API Platform will autodetect it. Then, create a class mapped with MongoDB, and mark it as an API resource:
The support for MongoDB leverages the flexibility of API Platform: it has been implemented as a data provider and a data persister. Relations, pagination as well as boolean, date, numeric, order, range and search filters are also supported!
A big thanks to all contributors of this amazing feature, and to Andreas Braun, the maintainer of Doctrine MongoDB ODM, for the in-depth reviews!
Elasticsearch support
Elasticsearch is another very popular open-source data store. It allows to perform full-text searches and advanced analyzes on very large datasets. Orange has sponsored the development of an Elasticsearch data provider for API Platform, as well as some interesting search filters. The implementation has been realized by Baptiste Meyer (API Platform Core Team). Thanks to Orange, this feature is now available for everybody in API Platform 2.4.
To enable and configure the Elasticsearch support, refer to the official documentation. Then, a simple resource class corresponding to an Elasticsearch index is enough to benefit from the full power of API Platform:
Then, you can use an URL such as /tweets?message=foo to search using Elasticsearch.
Keep in mind that it’s your responsibility to populate your Elastic index. To do so, you can use Logstash, a custom data persister or any other mechanism that fits for your project (such as an ETL).
Baptiste also took this opportunity to improve the code handling the pagination. It is now a generic class used by all native data providers (Doctrine ORM, MongoDB and Elasticsearch), that you can reuse in your own.
Mercure is a brand new protocol built on top of HTTP/2 and Server-sent Events (SSE). It’s a modern and high-level alternative to WebSocket (WebSocket is not compatible with HTTP/2). Mercure is especially useful to publish updates of resources served through web APIs in real time. It is natively supported by modern browsers (no required library nor SDK) and is very useful to update reactive web and mobile apps.
In version 2.4, I added Mercure support to the server component of API Platform and to the React and React Native app generators. The Docker Compose setup provided with API Platform has also been updated to provide a Mercure hub.
Configuring the framework to automatically dispatch updates to the currently connected clients is straightforward:
CQRS and async message handling with Symfony Messenger
Messenger is a new Symfony component created by Samuel Roze (Symfony and API Platform Core Team). It allows to dispatch messages using message queues (RabbitMQ, Kafka, Amazon SQS, Google PubSub…) and to handle them asynchronously. It provides a message bus that is very useful to implement the CQRS design pattern.
In API Platform 2.4, I added a convenient way to leverage the capabilities of Messenger. This new feature is particularly useful to create service-oriented (RPC-like) endpoints:
Thanks to the new messenger attribute, this object will automatically be dispatched to the bus. It can then be handled (synchronously or asynchronously) by a message handler:
HTTP/2 allows a server to pre-emptively send (or “push”) responses (along with corresponding “promised” requests) to a client in association with a previous client-initiated request. This can be useful when the server knows the client will need to have those responses available in order to fully process the response to the original request.
API Platform 2.4 makes it very easy to push relations using HTTP/2:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
namespaceApp\Entity;
useApiPlatform\Core\Annotation\ApiProperty;
useApiPlatform\Core\Annotation\ApiResource;
/**
* @ApiResource
*/
classBook
{
/**
* @ApiProperty(push=true)
*
* @var Author
*/
public$author;
}
Thanks to the push attribute, if the client asks for /books/1 the web server will directly send both the requested book resource and the related author (e.g. /authors/12) to the client.
The UI is built client-side dynamically by parsing the API spec. Awesome isn’t it?
Jean-François also added some convenient helpers to help customizing the admin, and Laury Sorriaux fixed a long standing limitation: it’s now possible to use the admin even with API not served at the root of the domain (such as /api).
Also, in addition to Swagger UI, we added support for ReDoc, a beautiful, human-readable, API docs generator written in React:
ReDoc in API Platform 2.4
OpenAPI v3 support has been contributed by Anthony Grassiot (API Platform Core Team). ReDoc integration has been contributed by Grégoire Hébert. A big thanks to them!
Handling Data Transfer Objects was known to be difficult with API Platform. Back in October, the API Platform and the Sylius teams worked together to improve the API of the popular e-commerce solution… using API Platform (stay tuned!). During this workshop Antoine Bluchet and I worked on a new way to handle DTOs with API Platform:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
namespaceApp\Entity;
useApiPlatform\Core\Annotation\ApiResource;
useApp\Dto\BookInput;
useApp\Dto\BookOutput;
/**
* @ApiResource(
* input=BookInput::class,
* output=BookOutput::class
* )
*/
finalclassBook
{
// ...
}
The new input and output attributes allow to use specific classes respectively for the writeable and the readable representation of the resource.
As demonstrated in the example using Symfony Messenger, it’s also possible to set these new attributes to false to hint that the operation will take no inputs or no outputs.
These new attributes are automatically taken into account by all API Platform subsystems, including GraphQL, Hydra and OpenAPI.
With this config, API Platform will automatically generate the following Cache-Control HTTP header: Cache-Control: max-age=60, public, s-maxage=120. Thanks Daniel!
Thanks to the new capabilities of the web platform (web components, Progressive Web Apps…) and the rise of modern JS libraries (Vue, React, Angular) almost all modern Symfony applications must leverage the frontend ecosystem. Symfony 4 embed many gems that make it easy to integrate modern JavaScript within the framework, including the first component entirely written in JS: Webpack Encore.
In Symfony 4.2, another component that is super convenient for apps containing JS code has been released: Panther, a PHP library compatible with BrowserKit, that drives real web browsers to create end-to-end (E2E) tests with ease.
During this talk, I’ll show you how to cleanly integrate modern JavaScript code with Symfony and Twig and how to test such applications using Panther.
The examples will use VueJS, because it’s probably the easiest JS framework to get started with as a PHP developer, but all the tips and tricks will be applicable with other libraries such as React or Angular.
Finally, we’ll add some real time capabilities to our app using Mercure.rocks
HTTP/2 can improve the loading time of webpages up to 2 times. Did you know that it’s very easy to optimize your Symfony applications to leverage the advanced features of this new protocol?
This talk also contains the announcement of 3 new PHP packages:
I’ll speak at several conferences until the end of 2018.
The topics will be varied: Panther, modern JavaScript, HTTP/2 and a brand new project to be announced (teasing: it’s written in Go, and it will be very helpful for serverless architectures!).
Today, an introduction blog post to Panther was published on the Symfony blog! Panther is a new browser testing and web scraping library I contributed to the Symfony project,
In the blog post, I showcase how to use Symfony, API Platform and VueJS together to create a small but modern app, and how to test it on Panther:
Today, the API Platform framework has reached 3k stars on GitHub, and it makes us very proud! To celebrate, I’ve just tagged the 2.3 version, that comes with a lot of amazing new features. Let’s discover them!
We’re committed to continuously improving the performance of API Platform. In version 2.1, we’ve added an amazing invalidation-based cache mechanism. When enabled, HTTP responses are generated only one time then stored and served by a reverse caching proxy. When a resource is modified, all responses including or referencing it are automatically removed from the cache.
In version 2.3, Ben Davies has done an excellent job at profiling and patching the core component. Moreover, we’ve worked closely with the Symfony team to dramatically improve the performance of the Symfony Serializer component (one of the most important pieces of software used by API Platform).
With all these optimizations put together, in the scenario of a cache miss, API Platform-based apps are now more than 40% faster in version 2.3 compared to version 2.2 (Blackfire comparison):
A big thanks to Ben and to Nicolas Grekas from Blackfire.io for making it happen!
Support for API evolution (aka deprecating fields and resources)
A growing best practice is to use the evolution strategy for web APIs. Creating new versions of the API, of or its endpoints requires modifying all clients to upgrade, even the ones not impacted by the changes. On the other hand, this strategy (also known as versionless APIs) consists of deprecating the fields, resources types or operations that will be removed at some point. Most modern API formats including GraphQL, OpenAPI and Hydra are able to support this strategy.
In API Platform 2.3, we’ve introduced a new attribute to mark deprecated resource classes, operations and properties. All documentation formats generated by API Platform and having support for this feature will then automatically take it into account.
Here is how to deprecate an entire resource:
PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
<?php
namespaceApp\Entity;
useApiPlatform\Core\Annotation\ApiResource;
/**
* @ApiResource(deprecationReason="Create a Book instead")
*/
classParchment
{
// ...
}
As you can see, to deprecate a resource, we just have to explain what the client should do to upgrade in a dedicated attribute. You can also use this new deprecationReason attribute on any operation.
The deprecation will automatically be taken into account by clients supporting the previously mentioned format. Here is how it renders for OpenAPI in the built-in Swagger UI shipped with the framework:
And now in the built-in version of GraphiQL (for GraphQL APIs):
It’s also possible to deprecate a single field:
PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<?php
namespaceApp\Entity;
useApiPlatform\Core\Annotation\ApiProperty;
useApiPlatform\Core\Annotation\ApiResource;
/**
* @ApiResource
*/
classReview
{
// ...
/**
* @ApiProperty(deprecationReason="Use the rating property instead")
*/
public$letter;
}
All our client-side tools have been updated to ignore deprecated fields, operations and resources by default. The api-doc-parser library (which supports Hydra, and OpenAPI in the latest version) also support this new feature.
Dedicated Profiler Panel and Web Debug Toolbar Integration
Symfony comes with a nice set of development tools, including the Profiler, and it is compatible with API Platform! To install it, execute composer req profiler. Thanks to the contributions of Julien Deniau and Anthony Grassiot, the Web Debug Toolbar now displays an icon featuring our nice spider Webby that is linked to a new profiler panel dedicated to API Platform:
Shorter Attributes Syntax
Defining attributes using annotations can become verbose pretty quickly. As alternatives to annotations, for complex configurations API Platform also supports the XML and YAML formats. However, in version 2.3, Baptiste Meyer added a nicer and shorter syntax to define attributes on the @ApiResource and @ApiProperty annotations:
Of course the “old” syntax is still valid, but the new shortcuts allow a better discoverability and enable autocompletion in IDEs (if you are a PHPStorm user, install the PHP Annotations plugin to benefit from this new feature).
Revamped Admin
In version 2.3, a lot of love has been given to the API Platform Admin Component. This JavaScript library, maintained by Morgan Auchedé, dynamically constructs a UI for any API supporting Hydra or OpenAPI.
It uses React, and was built on top of the Admin On Rest library. But as you may know, Admin On Rest has been deprecated and Marmelab, the company behind the tool, has released a replacement called React Admin. React Admin comes with an updated fancy interface and it also fixes some design issues.
So we’ve patched API Platform Admin to use the new kid on the block, and we’ve taken this opportunity to also fix a well known annoying issue on our side: the Admin component wasn’t able to deal with embedded relations. This isn’t the case anymore. What’s even better, the Admin is now smart enough to reuse the data already downloaded as embedded relation instead of triggering a new HTTP request. It allows to dramatically improve the performance of the admin!
We’ve also added support for new features introduced by React Admin, including bulk delete.
Other Features
Of course, this new version also includes a lot of new features that are less visible but also very useful. Here is the curated list of some interesting changes:
Make resource class’s constructor parameters writable
Add support for interface as a resource
Throw an exception if a required filter isn’t set
Allow to specify the message when access is denied using the access_control_message attribute
Add a new option to include null results when using the date filter
Allow data persisters to return a new instance instead of mutating the existing one
Add a new attribute to configure specific formats per resources or operations
Add an --output option to the api:swagger:export command
Drop support for PHP 7.0
Upgrade Swagger UI and GraphiQL
GraphQL: Add a totalCount field in GraphQL paginated collections
As usual, thank you very much to all the developers who’ve contributed these new features, bug fixes, and the related documentation entries. You’re the most important part of the project: the community.
It covers the main features of the API Platform framework: we will install the framework, design an API data model as a set of tiny plain old PHP classes and learn how to get:
A fully featured dev environment with Symfony Flex and React containers, HTTP/2 and HTTPS support and a cache proxy
Pagination, data validation, access control, relation embedding, filters and error handling
Support for modern REST API formats: JSON-LD/Hydra, OpenAPI/Swagger, JSONAPI, HAL, JSON…
GraphQL support
An API responding in a just few milliseconds thanks to the builtin invalidation based cache mechanism
A dynamically created Material Design admin interface (a la Sonata / EasyAdmin – but 100% client-side) built with React
The Symfony Serializer Component exists since the very beginning of Symfony 2. Years after years, it gained a lot of new features useful to transform various data formats to PHP structures and the opposite. It is also a foundation block of API Platform and a first-class citizen in FOSRest.
Let’s dive into this component. We will cover the basic concepts behind the serialization process: normalization, denormalization, encoding and decoding.
Then we will discover all the little known features of the component: JSON, XML and CSV support, file handling with “data:” URIs, serialization groups, attributes names conversion, trees support, updating existing objects, dealing with circular references.
Finally we will learn how to create custom normalizers and encoders; and how to modify the behavior of the builtin ones using composition.
GraphQL is an increasingly popular alternative to REST architectures for building web APIs.
The query language promoted by Facebook has undeniable advantages: retrieve exactly what the client need, limitation of the number of queries, strong typing, powerful and extremely well thought out syntax…
However, it also suffers from often underestimated problems including HTTP cache, logs, security or authentication, features that are the basis of the today’s web stack. GraphQL is also a non-standard format that requires a specific parser.
In addition, modern REST-based hypermedia formats such as JSON-LD or JSON API have features very similar to those of GraphQL (and more advanced ones) while remaining compatible with the fundamentals of the web.
The API Platform framework, based on Symfony, makes it easy to create REST APIs (JSON-LD, JSON API, HAL …) just like GraphQL.
After listing the advantages and disadvantages of different formats, we will study through different cases of frequent use when it is better to use GraphQL, REST or both in addition.
