Yii PSR-7 Download Response Factory

The package provides a factory to help forming file download PSR-7 response.

Requirements

• PHP 8.1 or higher.

Installation

The package could be installed with Composer:

composer require yiisoft/response-download

General usage

Use the factory to form a response:

use Psr\Http\Message\ResponseInterface;
use Yiisoft\ResponseDownload\DownloadResponseFactory;

final class MyController
{
    public function __construct(
        private readonly DownloadResponseFactory $downloadResponseFactory,
    )
    {    
    }

    public function sendMyContentAsFile(): ResponseInterface
    {
        return $this->downloadResponseFactory->sendContentAsFile('Hello!', 'message.txt');
    }
    
    public function sendMyFile(): ResponseInterface
    {
        return $this->downloadResponseFactory->sendFile('message.txt');
    }
    
    public function xSendMyFile(): ResponseInterface
    {
        return $this->downloadResponseFactory->xSendFile('message.txt');
    }
    
    public function sendMyStreamAsFile(): ResponseInterface
    {
        $stream = new MyStream();
        
        return $this->downloadResponseFactory->sendStreamAsFile($stream, 'message.txt');
    }
}

Note the xSendFile(). It is a special method that delegates the hard work to the web server instead of serving the file using PHP.

X-Sendfile and Nginx

Different web servers use different header names for the x-sendfile feature:

Web server	Header name
Apache	X-Sendfile (default)
Lighttpd v1.4	X-LIGHTTPD-send-file
Lighttpd v1.5	X-Sendfile
Nginx	X-Accel-Redirect
Cherokee	X-Sendfile or X-Accel-Redirect
FrankenPHP	X-Accel-Redirect

When using Nginx, pass 'X-Accel-Redirect' as the $xHeader argument. Nginx also requires an internal location block in its configuration that maps to the directory where your files are stored:

location /protected/ {
    internal;
    alias /var/www/files/;
}

Then call xSendFile() with the internal Nginx location path as the file path:

public function xSendMyFile(): ResponseInterface
{
    return $this->downloadResponseFactory->xSendFile(
        '/protected/myfile.txt',
        xHeader: 'X-Accel-Redirect',
    );
}

The internal directive ensures the location is only accessible internally by Nginx (not directly by clients), while alias maps the internal path to the real file system path.

Optional arguments and defaults:

• If attachment name is not specified in sendFile() or xSendFile(), it will be taken from the name of the file served.
• Each file sending method could also be provided with optional mime type and optional content disposition.
• If mime type is omitted, for sendContentAsFile(), sendFile() and xSendFile() it will be determined based on the file content. For other methods or when unable to determine the mime type, "application/octet-stream" will be used.
• Content disposition is "attachment" by default. It will trigger browser's download dialog. If you want the content of the file to be displayed inline, set it to Yiisoft\Http\ContentDispositionHeader\ContentDispositionHeader::INLINE.

Documentation

• Internals

If you need help or have a question, the Yii Forum is a good place for that. You may also check out other Yii Community Resources.

License

The Yii PSR-7 Download Response Factory is free software. It is released under the terms of the BSD License. Please see LICENSE for more information.

Maintained by Yii Software.

Support the project

Follow updates