Serve static files

[johanjanssens]

This PR implements a static file router and downloader. The file router offers support for both pattern and callback based routing.

Static file routing is available globally, file downloads can be setup outside of the context of Pages for any url on your Joomla site.

Adding routes

Routes are defined in the configuration through the new files config option. For example:

<?php
return array(
    'files' => [
        'documents/[:name]' => '/images/files/documents/[:name].pdf'
    ]
);

If the route target is not a fully qualified file path it is considered a relative path starting from the Joomla root directory.

Global configuration

You do not need to setup a /joomlatools-pages folder to be able to define file routes. If you just want to use this feature add a configuration-pages.php to your Joomla root, and defines your file routes there, they will just work.

Force downloading

By default browsers will preview files they recognise, for example, images, pdf files and specific video formats. If you want to force the browser to download the file instead you can either add force-download to the url or to the route.

Using URL

>> http://example.com/documents/foo?force-download

Using route

>> 'documents/[:name]' => '/images/files/documents/[:name].pdf?force-download'

Different transports

The downloader offers support for two additional transports: stream and sendfile. The transport can be defined using the transport query parameter in the route target.

>> 'documents/[:name]' => '/images/files/documents/[:name].pdf?transport=[name]'

Stream

>> 'documents/[:name]' => '/images/files/documents/[:name].pdf?transport=stream'

Streaming is a data transfer mechanism in version HTTP 1.1 in which a web server serves content in a series of chunks.

Pages uses Byte Serving to stream files. This mechanism is the process of sending only a portion of the data from a server to a client. Range-serving uses the Range HTTP request header and the Accept-Ranges and Content-Range HTTP response headers.

Clients which request range-serving might do so in cases in which a large file has been only partially delivered and a limited portion of the file is needed in a particular range. Range Serving is therefore a method of bandwidth optimisation.

Tip: Use streaming to send larger files faster, for example to download large pdf files and allow to view the first page before the file has completely downloaded, or to stream video or audio files.

Sendfile

>> 'documents/[:name]' => '/images/files/documents/[:name].pdf?transport=sendfile'

Sendfile allows for internal redirection to a location determined by a header returned from a backend. This allows to handle authentication, logging or whatever else you please in your backend and then have the server serve the contents from redirected location to the client, thus freeing up the backend to handle other requests.

Following servers are supported:

• Apache: https://tn123.org/mod_xsendfile/
• Nginx: http://wiki.nginx.org/XSendfile
• Lighttpd: http://redmine.lighttpd.net/projects/1/wiki/X-LIGHTTPD-send-file

Configure caching

You can configure the cache lifetime through the cache query parameter in the route target. It will set the max-age value for the Cache-Control header when the response is send.

The max-age parameter indicates that the file is to be considered stale after its age is greater than the specified number of seconds.

By setting a cache liftetime you instruct CDN's and browser cache the redirect for a specific time. This helps to increase the performance of your site and is recommended practice.

The cache parameters offers support for English textual relative datetime formats as supported by strtotime, for example:

• 1day
• 2hours
• 15min

See also: https://github.com/joomlatools/joomlatools-framework/pull/373

For example, set the cache lifetime to 1day

>> 'documents/[:name]' => '/images/files/documents/[:name].pdf?cache=1day'