FastSitePHP\Web\Response

The Response Class represents an HTTP response and can be used to build and send the response.

Código Fonte

Código de Exemplo

// Por padrão, quando uma string é retornada em uma rota, o servidor retorna
// uma resposta HTML. Sem criar um Objeto Response, o Objeto Application
// pode ser utilizado para especificar um cabeçalho 'Content-Type' diferente
// que é o que os Navegadores e Clientes HTTP utilizam para determinar como
// lidar com a resposta.
$app->get('/app-text-response', function() use ($app) {
    $app->header('Content-Type', 'text/plain');
    return 'Resposta utilizando o Objeto Application';
});

// Ao utilizar o Objeto Response [contentType()] e [content()] são as
// principais funções para especificar diferentes tipos de conteúdo.
$app->get('/text-response', function() {
    $res = new \FastSitePHP\Web\Response();
    return $res->contentType('text')->content('Resposta em Texto');
});

// Ao utilizar o Objeto Response, propriedades são definidas através de
// funções getter/setter e são encadeáveis para que possam ser utilizadas
// em uma linha como mostrado acima ou separadas em múltiplas linhas como
// é mostrado aqui.
$app->get('/text-response2', function() {
    return (new \FastSitePHP\Web\Response())
        ->contentType('text')
        ->content('Resposta em Texto 2');
});

// Utilizando o Objeto Response
$res = new \FastSitePHP\Web\Response();

// Defina o Cabeçalho 'Content-Type'.
// Todas as seguintes 3 chamadas de função, definem o mesmo valor. A
// diferença é que [contentType()] é uma função auxiliar que permite
// valores abreviados de [html, json, jsonp, text, css, javascript, xml].
$res->contentType('text');
$res->contentType('text/plain');
$res->header('Content-Type', 'text/plain');

// Definir Conteúdo
// Para a maioria dos tipos de conteúdo, utilize uma string ao definir [content()].
$res->content('<h1>FastSitePHP</h1>');

// Para Conteúdo JSON ambos, Objetos e Arrays, são utilizados
$object = [
    'título' => 'Demonstração',
    'número' => '123',
];

$res
    ->contentType('json')
    ->content($object);

// A função auxiliar [json()] define ambos, [contentType()] e [content()]
$res->json($object);

// Para JSON formatado, defina a opções [JSON_PRETTY_PRINT] antes de enviar
// a resposta. POr padrão [JSON_UNESCAPED_UNICODE] é utilizada e o JSON é
// minificado. Qualquer constante utilizada por [json_encode()] pode ser
// definida aqui.
$app->json_options = (JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT);
$res->jsonOptions(JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT);

// Códigos de Status
// [$app] somente suporta [200, 201, 202, 204, 205, 404 e 500] e o Objeto
// Response permite e trata respostas 304 juntamente com qualquer outro
// código de status válido ou personalizado.
$app->statusCode(201);
$res->statusCode(500);

// Uma função auxiliar [pageNotFound()] existe no Objeto Aplicação que pode
// ser utilizada para enviar uma resposta 404 juntamente com a página 404
// padrão ou personalizada.
$app->get('/document/:name', function($name) use ($app) {
    if ($name !== 'test') {
        return $app->pageNotFound();
    }
    return 'Teste';
});

// Especifique um arquivo ou a resposta; o arquivo especificado será
// transmitido para o cliente e enviado de uma maneira eficiente para a
// memória, para que esta função seja chamada em arquivos muito grandes
// impactando minimamente o servidor.
$file_path = __FILE__;
$res->file($file_path);

// Incluir Mime-Type específico com Cabeçalhos para Armazenamento em Cache.
// Outro tópico nesta página cobre armazenamento em cache em mais detalhe.
$res->file($file_path, 'text', 'etag:md5', 'private');

// Exemplo de Uso de Arquivo
$app->get('/view-source-code', function() {
    $file_path = __FILE__;
    $res = new \FastSitePHP\Web\Response();
    return $res->file($file_path, 'download');
});

// Converter o nome ou tipo de um arquivo para um mime-type.
//
// Extensões de arquivo que mapeiam para um tipo MIME com a função são:
//     Texto: htm, html, txt, css, csv, md, markdown, jsx
//     Imagem: jpg, jpeg, png, gif, webp, svg, ico
//     Aplicação: js, json, xml, pdf, woff
//     Vídeo: mp4, webm, ogv, flv
//     Áudio: mp3, weba, ogg, m4a, aac
//
// Se um tipo de arquivo não estiver associado com um mime-type, então um
// tipo de arquivo de download 'application/octet-stream' será retornado.
$mime_type = $res->fileTypeToMimeType('video.mp4');
$mime_type = $res->fileTypeToMimeType('mp4');

// Definir Cabeçalhos de Resposta e Cookies

// Utilizando o Objeto Application
$app->header('X-API-Key', 'App_1234');
$app->cookie('X-API-Key', 'App_1234');

// Ou utilizando o Objeto Response
$res->header('X-API-Key', 'Res_1234');
$res->cookie('X-API-Key', 'Res_1234');

// Ao criar um Objeto Response o Objeto Aplicação pode ser passado e todas
// as definições do App de [statusCode(), cors(), noCache(), headers(),
// cookies() e [json_options] serão passadas para o Objeto Response.
$res = new \FastSitePHP\Web\Response($app);

// Requisições HTTP pode ser redirecionadas utilizando o objeto App ou o
// Response.
// Ao utilizar o Objeto Ap e chamar [redirect()], o script PHP finaliza-se
// imediatamente, entretanto, quaisquer eventos definidos por [after()] serão
// chamados. Se seu site utiliza Server-side Unit Testing, você pode querer
// utilizar o objeto resposta que comporta-se como uma rota regular e não
// finaliza a execução do script.

// O usuário faz esta requisição
$app->get('/page1', function() use ($app) {
    $app->redirect('page3');
});

// Ou o usuário faz esta requisição
$app->get('/page2', function() {
    $res = new \FastSitePHP\Web\Response();
    return $res->redirect('page3');
});

// O usuário verá então esta URL resposta
$app->get('/page3', function() {
    return 'page3';
});

// O Código de Status de Resposta Padrão é [302 'Found'] (Temporary Redirect),
// e um segundo parâmetro opcional para ambos App e Response permite códigos
// de status de redirecionamento adicionais:
//   301  Moved Permanently
//   302  Found
//   303  See Other
//   307  Temporary Redirect
//   308  Permanent Redirect
$app->get('/old-page', function() use ($app) {
    $app->redirect('new-page', 301);
});

// Exemplos abaixo mostram como utilizar Cabeçalhos Response para controlar
// como um Navegador ou Cliente HTTP armazena uma Página ou Recurso em cache.

// Evitar que um Navegador ou Cliente Armazene um Arquivo ou Página em Cache.
// Ambos os Objetos, Application e Response, têm uma função [noCache()].
// Chamando essas funções enviará 3 Cabeçalhos Response para o cliente:
//     Cache-Control: no-cache, no-store, must-revalidate
//     Pragma: no-cache
//     Expires: -1
$app->noCache();

$res = new \FastSitePHP\Web\Response();
$res->noCache();

// Se ao utilizar certos Cabeçalhos Response o Objeto Response enviará uma
// resposta 304 "Not Modified" dependendo dos cabeçalhos da requisição.
// Respostas 304 são utilizadas por Navegadores e outros Clientes pare
// reutilizar recursos previamente obtidos de suas cópias armazenadas em
// cache. Isto permite que o usuário veja recursos estáticos mais
// rapidamente e reduz a quantidade de tráfego enviado do servidor.

// Cabeçalho de resposta 'Cache-Control'. Este cabeçalho tem opções
// diferentes para informar clientes de como eles podem armazenar uma
// página em cache. Neste exemplo, somente usuários finais e não servidores
// proxy podem armazenar em cache a reposta e eles devem revalidar isso
// a cada vez.
$res->cacheControl('private, must-revalidate'); // privado, deve revalidar

// Cabeçalho de resposta 'Expires'. Este cabeçalho é utilizado para informar
// o cliente de por quanto tempo o conteúdo é valido, entretanto dependendo
// das opções de 'Cache-Control' este valor pode ser ignorado. Embora,
// definindo esse valor não aciona uma resposta 304 e cabe ao navegador ou
// cliente como lidar com isso.
$res->expires('+1 month'); // mais um mês

// Cabeçalho de Resposta 'ETag' (ETag é uma abreviação para Entity Tag). Uma
// ETag representa um valor para o conteúdo (geralmente utilizando uma Hash).
// Navegadores e Clientes enviarão um Cabeçalho de Requisição 'If-None-Match'
// com a versão que eles tem armazenada e se corresponder, então o Objeto
// Response enviará uma resposta 304 sem o conteúdo já que o navegador pode
// utilizar a cópia local.
$res->etag('hash:md5');

// A função [etag()] também aceita a própria hash ou uma função de fechamento.
$res->etag('0132456789abcdef');
$res->etag(function($content) {
    return sha256($content);
});

// O segundo parâmetro opcional aceita as ETag do tipo 'strong' ou 'weak'.
// O padrão é 'weak' e este é o recomendado para evitar erros complexos de
// de armazenamento em cache. Se você precisa utilizar ETags 'strong',
// provavelmente você deveria fazer testes extra.
$res->etag('hash:sha256', 'weak');

// Cabeçalho de Resposta 'Last-Modified'. Se estiver definido e o cliente
// envia de volta um cabeçalho de requisição 'If-Modified-Since' que
// corresponde, então uma resposta 304 é enviada. Ao definir o valor
// utilize um Timestamp Unix ou uma String que pode ser analisada pela
// função PHP [strtotime()].
$res->lastModified('2019-01-01 13:01:30');

// Cabeçalho de Resposta 'Vary'. O cabeçalho de resposta 'Vary' pode ser
// utilizado para especificar regras para armazenamento HTTP em cache e
// também prover dicas de conteúdo para Google e outros Mecanismos de
// Busca.
$res->vary('User-Agent, Referer');

// Ao enviar um arquivo coo a resposta, você pode especificar parâmetros
// opcionais [$cache_type e $cache_control]. Cache Type tem 3 opções válidas
// mostradas abaixo e Cache Control defini a função [cacheControl()].
$file_path = __FILE__;
$content_type = 'text'; // texto
$res->file($file_path, $content_type, 'etag:md5');
$res->file($file_path, $content_type, 'etag:sha1',     'private'); // privado
$res->file($file_path, $content_type, 'last-modified', 'public');// público

// Ao enviar etags com [file()] e utilizando uma das duas 'etag:md5' ou
// 'etag:sha1' a hash é calculada a cada vez. Se você utiliza ETags e tem
// arquivo grandes ou frequentemente acessados, isso seria uma boa ideia
// para salvar a hash quando o arquivo for criado pela primeira vez
// definí-la através da função [etag()].
$saved_hash = '0132456789abcdef';
$res->file($file_path)->etag($saved_hash);

// CORS é comumente utilizado em APIs web para compartilhar dados de um site
// ou domínio com outro domínio (recursos entre origens). Para incluir o
// cabeçalho 'Access-Control-Allow-Origin' em sua resposta, utilize a função
// [cors()]. Primeiro, certifique-se de definir os cabeçalhos CORS à partir
// do Objeto do App.
$app->cors('*');

// Se você estiver utilizando o Objeto Response você pode passar o Objeto App para a
// resposta em sua criação ou para sua função [cors()].
$res = new \FastSitePHP\Web\Response($app);
$res->cors($app);

// Ao passar uma string o 'Access-Control-Allow-Origin' é validado e definido,
// entretanto se você precisar passar CORS adicionais, utilize um array com
// cabeçalhos nomeados.
$app->cors([
    'Access-Control-Allow-Origin' => 'https://www.example.com',
    'Access-Control-Allow-Headers' => 'Authorization, Content-Type',
    'Access-Control-Allow-Credentials' => 'true',
    'Access-Control-Max-Age' => 86400,
]);

// Se estiver chamando um POST, PUT, DELETE ou outro Método de Requisição
// você provavelmente precisa tratar requisições OPTIONS. Ao utilizar CORS e
// uma requisição OPTIONS é processada, FastSItePHP definirá automaticamente
// o cabeçalho 'Access-Control-Allow-Methods' baseando-se em como rotas são
// definidas.
// Para ter certeza que requisições OPTIONS sejam tratadas, primeiro crie
// uma função que defina o valor CORS.
$cors = function () use ($app) {
    $app->cors('*');
};

// Atribua a Função Filtro para as rotas que utilizam CORS:
$app->post('/api-data', function() {
    return [ 'exemplo' => 'POST' ];
})
->filter($cors);

$app->put('/api-data', function() {
    return [ 'exemplo' => 'PUT' ];
})
->filter($cors);

// Se você não quer permitir que o FastSitePHP manipule requisições OPTIONS,
// você pode desativar isso utilizando esta opção:
$app->allow_options_requests = false;

Métodos

__construct(Application $app = null)

Class Constructor

The FastSitePHP Application can be passed as an optional parameter and when used the Status Code and any Response Headers defined from the Application Object will be assigned to the Response Object.

header($name, $value = null)

Define an HTTP Header to be sent with the Response. Additionally previously defined Header fields can be read and cleared using this function. To set a Header field specify both $name and $value parameters. To read the value of a Header field specify only the $name parameter; if the value has been defined it will be returned otherwise if it has not been defined then null will be returned. To clear a Header field pass an empty string '' for the $value parameter. If setting or clearing a Header field then the Response Object will be returned so it can be called as a chainable method.

The Class [\FastSitePHP\Application] also has this function defined. The difference is that Application version is used for basic responses and headers are not validated.

Examples:
    Set the Response Header 'Content-Type' to 'text/plain'
    $res->header('Content-Type', 'text/plain')

    Get the Response Header 'Content-Type' that has been set.
    If no value has been set then null will be returned.
    $value = $res->header('Content-Type')

    Clear the Response Header 'Content-Type' that has been set
    $res->header('Content-Type', '')

Retorna: $this | mixed | null

headers()

Return an array of Headers fields defined from the header() function that will be or have been sent with the HTTP Response.

Retorna: array

statusCode($new_value = null)

Get or set the response status code by number (for example 200 for 'OK' or 404 for 'Not Found'). By default the PHP will set a status of 200 so setting a status code is usually only needed for other status codes other than 200. This gets sent when the response is sent to the client. If this function is called without a status code passed as a parameter then it will return the current status code otherwise when setting a status code it will return the Response object so it can be used in chainable methods.

Retorna: null | int | $this

• https://en.wikipedia.org/wiki/List_of_HTTP_status_codes

contentType($type = null, $option = null)

Get or set the response content type header. This function is designed for developer ease of use so rather than having to define the full header such as 'Content-Type: application/json' the type 'json' can simply be used. The header is sent in the response from the function send(). This function supports the most common text content types used in web sites and web applications. For a full list of content media types see the defined standards from Internet Assigned Numbers Authority (IANA) in the reference link below.

If this function is called without a type passed as a a parameter then it will return the current content type otherwise it will return the Response object so it can be used in chainable methods.

Parameters: [$type] If specified will be one of 'html|json|jsonp|text|css|javascript|xml|graphql',
    any type from function [Response->fileTypeToMimeType()],
    or the actual content type for example 'text/html'. [$option] If $type is in 'html|css|javascript|text' then $option can be a string
    to specify the charset (e.g.: 'UTF-8') otherwise if 'jsonp' is the content type
    then $option can be a string or an array of query string parameters.
    By default if $option is null and the type is 'html' then 'UTF-8' is used
    as the charset and if the type is 'jsonp' and then the query string
    parameters 'callback' and 'jsonp' are used as the default.

Retorna: $this | mixed | null

• http://www.iana.org/assignments/media-types/media-types.xhtml

jsonpQueryString($value = null)

Gets or sets the value of the Query String Parameters that would be used for a JSONP Request (JSON with Padding). This function would not commonly be used and instead simply calling contentType('jsonp') would be enough for most apps. The only time this function would likely be used is if the contentType() was manually set with a specific JavaScript character set then this function could be used to set the Query String Parameters.

Retorna: $this | array | null | string

content($content = null)

Get or set content that will be sent to the client. When a Route returns a Response Object the function [send()] will be called which sends the actual Response. To get the content of the response object call this function without any parameters and to specify content specify the [$content] parameter. If the response type [define from contentType()] is JSON or JSONP then the [$content] can be an array or object otherwise it should be a string. When setting a content value the Response Object Instance is returned.

Examples:

    $app->get('/html', function() {
        $res = new \FastSitePHP\Web\Response();
        return $res->content('<h1>FastSitePHP</h1>');
    });

    $app->get('/json', function() {
        $res = new \FastSitePHP\Web\Response();
        return $res
            ->contentType('json')
            ->content(array('Name' => 'FastSitePHP'));
    });

Retorna: $this | mixed

json($content)

Prepare the Response Object for a JSON Response with Content. This is a helper function to provide a shorter syntax for the following:

    $res->contentType('json')->content($object);

This is a setter function only and returns the Response Object. For practical usage a basic JSON response can be returned from the Application Object by simply returning an array to the route. In most cases this would be used along with other Response fields, for example:

    $res->header('API-Key', '123')->etag('hash:md5')->json($data);

Retorna: $this

jsonOptions($new_value = null)

Get or set options for [json_encode()] when a JSON Response is returned. Defaults to [JSON_UNESCAPED_UNICODE] when using PHP 5.4 or later.

Example:
    $res->jsonOptions(JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT);

Retorna: int | $this

etag($value = null, $type = 'weak')

Get or set a value for the 'ETag' Response Header which is used to specify rules for HTTP Caching. ETag is short for Entity Tag and is typically a hash value (e.g.: md5 value of the content). When the function sendResponse() in this class gets called the ETag value is compared to the Request Header 'If-None-Match' and based on matching rules either a 200 'Ok' or 304 'Not Modified' response is returned for most webpages. There are two types of ETags validators: 'strong' and 'weak'.  A strong ETag is used to indicate that the contents of two requested resources including header fields at a URL (e.g.: webpages) are byte-for-byte identical. A weak ETag indicates that two requested resources are semantically equivalent. Strong ETags are not suitable for gzipped content because with compression turned on the response is not byte-for-byte identical. Depending upon the web server version if using strong ETags with gzipped content Nginx will remove them from the Response or convert them to weak ETags and Apache using mod_deflate will add a suffix which makes it unusable to most server side frameworks. Because of this weak ETags are used as the default option. If your site is using ETags then the Unit Testing Pages and the Samples Cache Test Section can be used to make sure that caching for your site is working as expected.

Retorna: $this | mixed | null

• https://en.wikipedia.org/wiki/HTTP_ETag

lastModified($last_modified_time = null)

Get or set a value for the 'Last-Modified' Response Header which is used to specify rules for HTTP Caching. Additionally when sendResponse() gets called the 'Last-Modified' value is compared to the Request Header 'If-Modified-Since' and based on matching rules either a 200 'Ok' or 304 'Not Modified' response is returned. If setting the value then the parameter value $ last_modified_time needs to be defined as an int to represent a Unix Timestamp or a valid string format for the php function strtotime().

Retorna: $this | mixed | null

cacheControl($value = null)

Get or set a value for the 'Cache-Control' Response Header which is used to specify rules for HTTP Caching. When setting the header value this function validates that it is in a correct format for defined HTTP 1.1 directive options and values. Per HTTP 1.1 Specs user defined fields are allowed however they are not commonly used so this function validates only for standards fields. This function is handled this way so that if there is a typo it can be caught. If the a custom 'Cache-Control' field name is needed then it can be added with the header() function instead.

Retorna: $this | mixed | null

• http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9

expires($expires_time = null)

Get or set a value for the 'Expires' Response Header which is used to specify rules for HTTP Caching. If setting the value then the parameter value $expires_time needs to be defined as an int to represent a Unix Timestamp, string values of '0' or '-1' for to prevent caching, or a valid string format for the php function strtotime(). When setting the header value through this function the largest date allowed is one year from today. To set the header value to a date greater than one year from today use the header() function instead.

Retorna: $this | mixed | null

• http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.21

vary($value = null)

Get or set a value for the 'Vary' Response Header which is used to specify rules for HTTP Caching and also to provide content hints to Google and other Search Engines. When setting the header value this function validates that the options specified are valid options; this includes all server driven content negotiation headers and several commonly used request headers. It's possible that other options could be used and would be valid however this function validates for common options so that if there is a typo it can be caught and to catch logic errors with the parameters. The valid parameters that can be used with this function are ['Accept', 'Accept-Charset', 'Accept-Encoding', 'Accept-Language', 'User-Agent', 'Origin', 'Cookie', and 'Referer']. If the a custom 'Vary' option is needed then it can be added with the header() function instead. Additionally testing should be performed when using this function because depending upon how the actual web server is configured this function could overwrite the web server value or the web server could overwrite the value set from this function.

Retorna: $this | mixed | null

• http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.44
• https://developers.google.com/search/mobile-sites/mobile-seo/dynamic-serving
• http://httpd.apache.org/docs/2.2/content-negotiation.html
• https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation
• https://www.fastly.com/blog/best-practices-for-using-the-vary-header
• https://www.youtube.com/watch?v=va6qtaiZRHg
• https://support.microsoft.com/en-us/kb/2877816

noCache()

Set Response Headers that tell the browser or client to not cache the response.

This function defines the following response headers:
    Cache-Control: no-cache, no-store, must-revalidate
    Pragma: no-cache
    Expires: -1

For most clients and all modern browsers 'Cache-Control' will take precedence over 'Expires' when both tags exist. The 'Expires' header per HTTP Specs must be defined as an HTTP-Date value, and when an invalid value such as '0' is used then the client should treat the content as already expired, however in reality certain older versions of Internet Explorer may end up caching the response if '0' is used so '-1' is used for the 'Expires' header. At the time of writing both Google and Microsoft use 'Expires: -1' for their homepages. The header 'Pragma' is for old HTTP 1.0 clients that do not support either 'Cache-Control' or 'Expires'.

This function exists in both [FastSitePHP\Application] and [FastSitePHP\Web\Response] classes; calling the function from the Application object specifies the headers only when a route returns a basic response and calling the function from the Response object specifies the headers only when the route returns a Response object.

Retorna: $this | mixed

• http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.21
• http://blogs.msdn.com/b/ieinternals/archive/2012/01/31/avoid-using-meta-to-specify-expires-or-pragma-in-html-markup.aspx

cors(Application $app = null)

Get or set a values for Cross-Origin Resource Sharing (CORS) Response Headers. For security reasons browsers will restrict content that is from a different domain when using JavaScript (for example: calling a Web Service from XMLHttpRequest). CORS is a web standard that allows for restricted resources to work on domains other than the domain where the resource is hosted.

CORS Headers are sent with both the OPTIONS request method and the calling method. Because OPTIONS requests are required for certain response types CORS Headers are initially defined from the Application Object and then passed the Response Object.

For more on this topic refer to documentation from the cors() function in the Application Object.

Example:
    $app->cors(array(
        'Access-Control-Allow-Origin' => '*',
        'Access-Control-Allow-Headers' => 'Origin, X-Requested-With, Content-Type, Authorization',
    ));
    $res = new \FastSitePHP\Web\Response();
    $res->cors($app);

Retorna: $this | array | null

cookie($name, $value = '', $expire = 0, $path = '', $domain = '', $secure = false, $httponly = false)

Define a cookie to be sent with the response along with the response headers. Internally this calls the PHP function setcookie() from the private function sendResponse(). To delete a cookie use the function [clearCookie()]. To read cookies use the [cookie()] function of the [FastSitePHP\Web\Request] Object or use the PHP superglobal array $_COOKIE.

Retorna: $this

• http://php.net/manual/en/function.setcookie.php
• http://php.net/manual/en/features.cookies.php
• http://php.net/manual/en/reserved.variables.cookies.php

clearCookie($name, $path = '', $domain = '', $secure = false, $httponly = false)

Send an empty value for a named cookie and expired time to tell the browser or client to clear the cookie.

Retorna: $this

signedCookie($name, $value = '', $expire_time = '+1 hour', $expire = 0, $path = '', $domain = '', $secure = false, $httponly = false)

Create a secure cookie that can be read by clients client but not tampered with. Cookies sent using this method need to be read with [Request->verifiedCookie()] to verify that they are not tampered with or expired. The default expiration time is 1 hour and it applies to the signed data and not the cookie itself.

Using this function requires the Application Config Value 'SIGNING_KEY'.

See also [encryptedCookie()] and [jwtCookie()].

Retorna: $this

jwtCookie($name, $value = '', $expire_time = '+1 hour', $expire = 0, $path = '', $domain = '', $secure = false, $httponly = false)

Create a secure cookie with a JSON Web Token (JWT). Cookies sent using this method need to be read with [Request->jwtCookie()] to verify that they are not tampered with or expired. The default expiration time is 1 hour and it applies to the JWT and not the cookie itself.

Using this function requires the Application Config Value 'JWT_KEY'.

See also [encryptedCookie()] and [signedCookie()].

Retorna: $this

encryptedCookie($name, $value = '', $expire = 0, $path = '', $domain = '', $secure = false, $httponly = false)

Create a secure and secret cookie that cannot be read by clients. Cookies sent using this method need to be read with [Request->decryptedCookie()].

Using this function requires the Application Config Value 'ENCRYPTION_KEY'.

See also [signedCookie()] and [jwtCookie()].

Retorna: $this

cookies()

Return the Array of Cookies that will be sent with the response.

Retorna: array

fileTypeToMimeType($file_name)

Return a Response Mime-type for a File extension for commonly used file formats in modern web apps and supported by popular browsers. For example 'file.txt' will return 'text/plain' and 'file.mp4' will return 'video/mp4'. The file path does not need to be a real file when calling this function. If a file type is not associated with a mime-type then 'application/octet-stream' will be returned indicating that the type of file is a file download; this includes common file types such as Office Documents and Windows BMP Images. For a large list of known Mime-types refer to the reference links below.

File extensions that map to a Mime type with the function are:
    Text: htm, html, txt, css, csv, md, markdown, jsx
    Image: jpg, jpeg, png, gif, webp, svg, ico
    Application: js, json, xml, pdf, woff, graphql
    Video: mp4, webm, ogv, flv
    Audio: mp3, weba, ogg, m4a, aac

Retorna: string

• http://www.iana.org/assignments/media-types/media-types.xhtml
• http://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types
• https://msdn.microsoft.com/en-us/library/ms775147
• https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types

file($file_path = null, $content_type = null, $cache_type = null, $cache_control = null)

Specify a file for the response; the file specified will be streamed to the client and sent in a memory efficient manner so this function can be called on very large files with minimal performance impact for the server. The contents of the file are not modified when calling this function so it cannot be used to render templates. This function is ideal for sending file download responses and media files such as images or video.

This function provides several optional parameters to specify the response content type and caching headers:

$content_type The content type to set for contentType() such as 'text', 'html' or 'download' to specify 'application/octet-stream' and related headers for a file download. If not set then the mime type is determined from the file extension using the function fileTypeToMimeType().

$cache_type Value to set for either ETag or Last-Modified headers which allow for Cached Responses of 304 'Not Modified'. Valid options are: 'etag:md5', 'etag:sha1', and 'last-modified'. All values are calculated from the file directly. When calculating Etag based on a hash be aware that the value will be calculated each time this function is called so in the case of large files that are 100's of megabytes or more in size it can delay the initial streamed response by as much as a few seconds. If very large files are used with this function and ETag is needed then an alternative solution such as saving a hash of the file and setting it through the etag() function can be used to improve performance.

$cache_control Value for the 'Cache-Control' header which gets set from the function cacheControl().

Retorna: $this

redirect($url, $status_code = 302)

Specify a redirect URL for the response. By calling this function the response will redirect the user to another page or site by sending a status code of 3## for the response with the Location Header set to the new URL.

The redirect() function also exists in the main Application Object but can be used here instead if your site is designed to return a Response object for all routes.

Status Code can optionally be specified as the 2nd parameter. The default Status Code used is [302 'Found'] (Temporary Redirect). If Status Code [301 'Moved Permanently'] is used Web Browsers will typically cache the result so careful testing and consideration should be done if using a Status Code of 301. Other supported Status Codes are: [303 'See Other'], [307 'Temporary Redirect'], and [308 'Permanent Redirect'].

Example:

    // User makes this request
    $app->get('/page1', function() {
        $res = new \FastSitePHP\Web\Response();
        return $res->redirect('page2');
    });

    // User will then see this URL and Response
    $app->get('/page2', function() {
        return 'page2';
    });

Retorna: $this

• http://en.wikipedia.org/wiki/URL_redirection

reset()

Reset the Response object to its default state as if it were just created.

Retorna: $this

send()

Send the Response to the Client. This function gets called automatically if a route returns a response object and would normally not be manually called. This function handles sending Response Headers, Cookies, and Content.