Download the PHP package xp-forge/frontend without Composer

Web frontends

Frontends based on xp-forge/web, using annotation-based routing.

Example

Frontend uses handler classes with methods annotated with HTTP verbs to handle routing. These methods return a context, which is passed along with the template name to the template engine.

Note: For PHP 7, the Param annotation must be on a line by itself, see here!

For the above class, the template engine will receive home as template name and the returned map as context. This library contains only the skeleton for templating - the xp-forge/handlebars-templates library implements it. For the rest of the examples, we'll be using it.

The handlebars template hello.handlebars (calculated from the lowercase version of the above handler class' name) is quite straight-forward:

Finally, wiring it together is done in the application class, as follows:

To run it, use xp -supervise web Site, which will serve the site at http://localhost:8080/.

Organizing your code

In real-life situations, you will not want to put all of your code into the Hello class. In order to separate code out into various classes, place all handler classes inside a dedicated package:

Then use the delegation API provided by the HandlersIn class:

Handling routes and methods

The Handler annotation can include a path which is used as a prefix for all method routes in a handler class. Placeholders can be used to select method parameters from the request URI.

The above method routes will only accept GET requests. POST request methods can be annotated with Post, PUT with Put, and so on.

Route methods can return web.frontend.View instances to have more control over the response:

To overwrite the method used for POST requests, pass the special _method field:

This will route the request as if it had been issued as PUT /example HTTP/1.1.

Serving assets

Assets are delivered by the AssetsFrom handler as seen above. It takes care of content types, handling conditional and range requests for partial content, as well as compression.

Sources

The constructor accepts single paths as well as an array of paths which will be searched for the requested asset. The first path to provide the asset is selected, the file being served from there.

Caching

Assets can be delivered with a Cache-Control header by passing it to the with function. In this example, assets are cached for 28 days, but clients are asked to revalidate using conditional requests before using their cached copy.

Compression

Assets can also be delivered in compressed forms to save bandwidth. The typical bundled JavaScript library can be megabytes in raw size! By using e.g. Brotli, this can be drastically reduced to a couple of hundred kilobytes.

• The request URI is mapped to the asset file name
• If the clients sends an Accept-Encoding header, it is parsed and the client preference negotiated
• The server tries [file].br (for Brotli), [file].bz2 (for BZip2), [file].gz (for GZip) and [file].dfl (for Deflate), and only sends the uncompressed version if none exists nor is acceptable.

Note: Assets are not compressed on the fly as this would cause unnecessary server load.

Asset fingerprinting

Generated assets can be fingerprinted by embedding a version identifier in the filename, e.g. [file].[version].[ext]. Every time their contents change, the version (or fingerprint) changes, and with it the filename. These assets can then be regarded "immutable", and served with an "infinite" maximum age. Bundlers (like Webpack or the one built-in to this library) will create an asset manifest along with these assets.

Because mapping the filenames happens in the template engine, the manifest must also be passed there:

The handlebars code then uses the asset helper to lookup the filename including the fingerprint:

This way, we don't have to commit changes to our handlebars file every time the assets are changed, which may happen often!

The built-in bundler

Bundling assets makes sense from a security standpoint, but also to reduce HTTP requests. This library comes with a bundle subcommand, which can generate JavaScript and CSS bundles from dependencies tracked in package.json.

To create the bundles to the src/main/webapp/static directory and the assets manifest, run the following:

This will create vendor.[fingerprint].js and vendor.[fingerprint].css files as well as compressed versions (if the zlib and brotli PHP extensions are available) and the assets manifest, which maps the file names without fingerprints to those with.

The bundler can also resolve local files, URLs as well as Google fonts:

Error handling

By default, errors and exceptions will yield in a minimalistic error page with the corresponding error code (defaulting to 500 Internal Server Error) shown. Exceptions can be handled by a closure, a status code or by default, and decide to return a view of their own. This view is loaded from the errors/ subfolder and passed a context of ['cause' => $exception].

Using our handlebars engine from above, the template errors/404.handlebars could look like this:

Security

This library sets the following security header defaults:

• X-Content-Type-Options: nosniff - prevents browsers from MIME sniffing
• X-Frame-Options: DENY - prevents site from being embedded in an <iframe>.
• Referrer-Policy: no-referrer-when-downgrade - doesn't send HTTP referrer over unencrypted connections.

To configure framing, referrer and content security policies, use the security() fluent interface:

Read more about hardening response headers at https://scotthelme.co.uk/hardening-your-http-response-headers/ or watch this talk: https://www.youtube.com/watch?v=mr230uotw-Y

Performance

When using the production servers, the application's code is only compiled and its setup only runs once. This gives us lightning-fast response times: