/**
* Sends existing file to a browser as a download using x-sendfile.
*
* X-Sendfile is a feature allowing a web application to redirect the request for a file to the webserver
* that in turn processes the request, this way eliminating the need to perform tasks like reading the file
* and sending it to the user. When dealing with a lot of files (or very big files) this can lead to a great
* increase in performance as the web application is allowed to terminate earlier while the webserver is
* handling the request.
*
* The request is sent to the server through a special non-standard HTTP-header.
* When the web server encounters the presence of such header it will discard all output and send the file
* specified by that header using web server internals including all optimizations like caching-headers.
*
* As this header directive is non-standard different directives exists for different web servers applications:
*
* - Apache: [X-Sendfile](http://tn123.org/mod_xsendfile)
* - Lighttpd v1.4: [X-LIGHTTPD-send-file](http://redmine.lighttpd.net/projects/lighttpd/wiki/X-LIGHTTPD-send-file)
* - Lighttpd v1.5: [X-Sendfile](http://redmine.lighttpd.net/projects/lighttpd/wiki/X-LIGHTTPD-send-file)
* - Nginx: [X-Accel-Redirect](http://wiki.nginx.org/XSendfile)
* - Cherokee: [X-Sendfile and X-Accel-Redirect](http://www.cherokee-project.com/doc/other_goodies.html#x-sendfile)
*
* So for this method to work the X-SENDFILE option/module should be enabled by the web server and
* a proper xHeader should be sent.
*
* **Note**
*
* This option allows to download files that are not under web folders, and even files that are otherwise protected
* (deny from all) like `.htaccess`.
*
* **Side effects**
*
* If this option is disabled by the web server, when this method is called a download configuration dialog
* will open but the downloaded file will have 0 bytes.
*
* **Known issues**
*
* There is a Bug with Internet Explorer 6, 7 and 8 when X-SENDFILE is used over an SSL connection, it will show
* an error message like this: "Internet Explorer was not able to open this Internet site. The requested site
* is either unavailable or cannot be found.". You can work around this problem by removing the `Pragma`-header.
*
* **Example**
*
* ~~~
* Leaps::$app->response->xSendFile('/home/user/Pictures/picture1.jpg');
* ~~~
*
* @param string $filePath file name with full path
* @param string $attachmentName file name shown to the user. If null, it will be determined from `$filePath`.
* @param array $options additional options for sending the file. The following options are supported:
*
* - `mimeType`: the MIME type of the content. If not set, it will be guessed based on `$filePath`
* - `inline`: boolean, whether the browser should open the file within the browser window. Defaults to false,
* meaning a download dialog will pop up.
* - xHeader: string, the name of the x-sendfile header. Defaults to "X-Sendfile".
*
* @return $this the response object itself
*/
public function xSendFile($filePath, $attachmentName = null, $options = [])
{
if ($attachmentName === null) {
$attachmentName = basename($filePath);
}
if (isset($options['mimeType'])) {
$mimeType = $options['mimeType'];
} elseif (($mimeType = FileHelper::getMimeTypeByExtension($filePath)) === null) {
$mimeType = 'application/octet-stream';
}
if (isset($options['xHeader'])) {
$xHeader = $options['xHeader'];
} else {
$xHeader = 'X-Sendfile';
}
$disposition = empty($options['inline']) ? 'attachment' : 'inline';
$this->getHeaders()->setDefault($xHeader, $filePath)->setDefault('Content-Type', $mimeType)->setDefault('Content-Disposition', "{$disposition}; filename=\"{$attachmentName}\"");
$this->format = self::FORMAT_RAW;
return $this;
}
