README

Middleware to save or read responses from files. It uses Flysystem as filesystem handler, so you can not only use a local directories, but also any other adapter like ftp, sftp, dropbox, etc... This package includes the following components:

• Reader
• Writer

Requirements

• PHP >= 7.2
• A PSR-7 http library
• A PSR-15 middleware dispatcher

Installation

This package is installable and autoloadable via Composer as middlewares/filesystem.

composer require middlewares/filesystem

Example

Dispatcher::run([
    Middlewares\Reader::createFromDirectory(__DIR__.'/assets')
]);

Reader

To read the response body from a file under the following conditions:

• Only GET methods are allowed, returning a 405 code otherwise.
• If the request path has no extension, assume it's a directory and append /index.html. For example: if the request path is /post/23, the file used is /post/23/index.html.
• It can handle gzipped files. For example, if /post/23/index.html does not exists but /post/23/index.html.gz is available and the request header Accept-Encoding contains gzip, returns it.
• Accept-Ranges is also supported, useful to server big files like videos.

Example using a ftp storage:

use League\Flysystem\Filesystem;
use League\Flysystem\Ftp\FtpAdapter;
use League\Flysystem\Ftp\FtpConnectionOptions;

$adapter = new League\Flysystem\Ftp\FtpAdapter(
    FtpConnectionOptions::fromArray([
        'host' => 'hostname',
        'root' => '/root/path/',
        'username' => 'username',
        'password' => 'password',
        'port' => 21,
        'ssl' => false,
        'timeout' => 90,
        'utf8' => false,
        'passive' => true,
        'transferMode' => FTP_BINARY,
        'systemType' => null, // 'windows' or 'unix'
        'ignorePassiveAddress' => null, // true or false
        'timestampsOnUnixListingsEnabled' => false, // true or false
        'recurseManually' => true // true 
    ])
);

// The FilesystemOperator
$filesystem = new Filesystem($adapter);

Dispatcher::run([
    new Middlewares\Reader($filesystem)
]);

Optionally, you can provide a Psr\Http\Message\ResponseFactoryInterface and Psr\Http\Message\StreamFactoryInterface, that will be used to create the response and stream. If they are not not defined, Middleware\Utils\Factory will be used to detect them automatically.

$responseFactory = new MyOwnResponseFactory();
$streamFactory = new MyOwnStreamFactory();

$reader = new Middlewares\Reader($filesystem, $responseFactory, $streamFactory);

continueOnError

Allows to continue to the next middleware on error (file not found, method not allowed, etc). This allows to create a simple caching system as the following:

$cache = new Filesystem(new LocalFilesystemAdapter(__DIR__.'/path/to/files'));

Dispatcher::run([
    (new Middlewares\Reader($cache))    //read and returns the cached response...
        ->continueOnError(),            //...but continue if the file does not exists

    new Middlewares\Writer($cache),     //save the response in the cache

    new Middlewares\AuraRouter($route), //create a response using, for example, Aura.Router
]);

Writer

Saves the response content into a file if all of the following conditions are met:

• The method is GET
• The status code is 200
• The Cache-Control header does not contain no-cache and no-store

To be compatible with Reader behaviour:

• If the request path has no extension, assume it's a directory and append /index.html. For example: if the request path is /post/23, the file saved is /post/23/index.html.
• If the response is gzipped (has the header Content-Encoding: gzip) the file is saved with the extension .gz. For example /post/23/index.html.gz (instead /post/23/index.html).

$filesystem = new Filesystem(new LocalFilesystemAdapter(__DIR__.'/storage'));

Dispatcher::run([
    new Middlewares\Writer($filesystem)
]);

Optionally, you can provide a Psr\Http\Message\StreamFactoryInterface as the second that will be used to create a new body to the response. If it's not defined, Middleware\Utils\Factory will be used to detect it automatically.

$streamFactory = new MyOwnStreamFactory();

$reader = new Middlewares\Writer($filesystem, $streamFactory);

Helpers

createFromDirectory

Both Reader and Writer have a static method as a shortcut to create instances using a directory in the local filesystem, due this is the most common case:

Dispatcher::run([
    Middlewares\Writer::createFromDirectory(__DIR__.'/assets')
    Middlewares\Reader::createFromDirectory(__DIR__.'/assets')
]);

Please see CHANGELOG for more information about recent changes and CONTRIBUTING for contributing details.

The MIT License (MIT). Please see LICENSE for more information.