Lista de Classes

FastSitePHP\Web\Request

Dica Rápida

Comentários de código estão em Português para ajudá-lo na utilização da classe, entretanto, a maioria das descrições de classes e funções não foram traduzidas.

The Request Class represents an HTTP request and can be used to read content submitted by the browser or client.

Código Fonte

GitHub

Código de Exemplo

Objeto HTTP Request - Lendo Strings de Consulta, Campos de Formulários e Cookies

// O objeto Request pode ser utilizado obtendo informações do cliente
// para uma requisição HTTP. Isso inclui strings de consulta, campos de formulários
// cookies, cabeçalhos e mais. O objeto Request contém funções para
// limpar e de, forma segura, ler informações do cliente.

// Sem utilizar um framework, strings de consulta, variáveis de formulário,
// e outras entradas de usuário, podem ser lidas através de superglobais PHP
// Without using a Framework, Query Strings, Form Variables and other
// [$_GET, $_POST, etc].
// Exemplo, leia o campo da string de consulta [number]:
$numero = $_GET['number'];

// Se a string de consulta [type] não existe, então o código acima lançaria
// uma exceção e, para obter de forma segura o valor, você poderia
// primeiro verificar se foi definida.
$numero = (isset($_GET['number']) ? $_GET['number'] : null);

// Uma linha de código PHP adicional pode ser utilizada para forçar um valor
// numérico:
$numero = (int)$numero;

// A requisição pode ser utilizada então para, seguramente,  ler os valores,
// converter tipos de dados etc. Para usar o objeto Requisição, simplesmente
// crie um:
$req = new \FastSitePHP\Web\Request();

// Você pode então ler strings de consultas por nome sem incluir lógica segura:
$numero = $req->queryString('number');

// Um segundo parâmetro opcional pode ser utilizado para converter para um
// tipo de dados específico. Neste exemplo o valor será convertido para um
// número inteiro se for válido, caso contrário, [null] será retornado.
$numero = $req->queryString('number', 'int?');

// Além de [queryString()] as funções [form()] e [cookie()] podem ser
// utilizadas da mesma maneira.
$value  = $req->form('field');
$cookie = $req->cookie('name');

// O objeto Request, também contém uma função auxiliar para manipular entradas
// de usuário e objetos onde um valor pode ou não existir. Isso pode ser
// utilizado para prevenir erros quando objetos JSON complexos são lidos e
// para limpar dados de qualquer objeto ou array.
//
// Definição de Função:
//     value($data, $key, $format = 'value?', $max_length = null)
//
// Dados de Exemplo:
//     $_POST['input1'] = 'test';
//     $_POST['input2'] = '123.456';
//     $_POST['checkbox1'] = 'on';
//     $json = [
//         'app' => 'FastSitePHP',
//         'strProp' => 'abc',
//         'numProp' => '123',
//         'items' => [ ['name' => 'item1'], ['name' => 'item2'] ],'
//    ];
//
// Funções de Exemplo:
//    'test'        = $req->value($_POST, 'input1');
//    // Truncar a string para dois caracteres:
//    'te'          = $req->value($_POST, 'input1',    'string', 2);
//    123.456       = $req->value($_POST, 'input2',    'float');
//    ''            = $req->value($_POST, 'missing',   'string'); // Faltando
//    1             = $req->value($_POST, 'checkbox1', 'checkbox');
//    0             = $req->value($_POST, 'checkbox2', 'checkbox'); // Faltando
//    true          = $req->value($_POST, 'checkbox1', 'bool');
//    'FastSitePHP' = $req->value($json,  'app');
//    'abc'         = $req->value($json,  'strProp',   'string?');
//    0             = $req->value($json,  'strProp',   'int');  // Int Inválido
//    null          = $req->value($json,  'strProp',   'int?'); // Int Inválido
//    123           = $req->value($json,  'numProp',   'int');
//    'item1'       = $req->value($json,  ['items', 0, 'name']);
//    'item2'       = $req->value($json,  ['items', 1, 'name']);
//    null          = $req->value($json,  ['items', 2, 'name']); // Faltando
//
// Veja a documentação completa para mais. Se você precisa de validação
// completa ao invés de limpeza de dados veja a classe [\FastSitePHP\Data\Validator].

Objeto HTTP Request - Requisite JSON e Conteúdo

// Create the Request Object
$req = new \FastSitePHP\Web\Request();

// Obtenha o tipo do conteúdo da requisição. Isso é um campo auxiliar que
// retorna um valor simples baseado no cabeçalho 'Content-Type':
//     'json'      = 'application/json'
//     'form'      = 'application/x-www-form-urlencoded'
//     'xml'       = 'text/xml' or 'application/xml'
//     'text'      = 'text/plain'
//     'form-data' = 'multipart/form-data'
// Se diferente, o valor puro do cabeçalho será retornado e se o cabeçalho
// nao estiver definido, então [null] será retornado.
$type = $req->contentType();

// O corpo/conteúdo da requisição pode ser lido à partir de [content()]. Se
// o tipo da requisição for JSON, então o objeto será analisado e um
// objeto/array será retornado. Se [contentType() === 'form'] então um array
// será retornado, caso contrário, o corpo/conteúdo é retornado como uma
// string. No PHP uma string pode também ser utilizada para dados binários
// por que uma string é simplesmente um array de bytes.
$body = $req->content();

// A função [value()] pode ser utilizada para, de forma segura, ler valores
// aninhados de um objeto JSON enviado. Veja outros exemplos e documentos
// para mais sobre o uso da função [value().
$value = $req->value($body,  ['items', 0, 'name']);

Objeto HTTP Request - Campos de Cabeçalho

// Crie o Objeto Request
$req = new \FastSitePHP\Web\Request();

// Lendo Campos Comuns de Cabeçalho pode ser feito através de funções:
$origin = $req->origin();
$userAgent = $req->userAgent();
$referrer = $req->referrer();
$client_ip = $req->clientIp();
$protocol = $req->protocol();
$host = $req->host();
$port = $req->port();

// Ao utilizar funções com cabeçalhos 'Accept' um array de dados é retornado
// e um parâmetro opcional pode ser passado para retornar [true] ou [false]
$accept_encoding = $req->acceptEncoding();
$accept_language = $req->acceptLanguage();

// Exemplo:
//    Valor do Cabeçalho 'Accept-Language' = 'ru-RU,ru;q=0.8,en-US;q=0.6,en;q=0.4'
// Retorna:
//    [
//        ['value' => 'ru-RU', 'quality' => null],
//        ['value' => 'ru',    'quality' => 0.8],
//        ['value' => 'en-US', 'quality' => 0.6],
//        ['value' => 'en',    'quality' => 0.4],
//    ];

$accept_en = $req->acceptLanguage('en'); // true
$accept_de = $req->acceptLanguage('de'); // false

// Qualquer cabeçalho pode ser lido ao utilizar a função [header()]:
$content_type = $req->header('Content-Type');
$user_agent = $req->header('User-Agent');

// Chaves de Cabeçalho ignoram diferenciação de maiúsculas e minúsculas, então
// todas as seguintes retornam o mesmo valor:
$content_type = $req->header('content-type');
$content_type = $req->header('CONTENT-TYPE');
$content_type = $req->header('Content-Type');

// Todos os cabeçalhos pode ser lidos à partir da função [headers()]:
$headers = $req->headers();

Objeto HTTP Request - Campos de Cabeçalho de Proxy

// Cria o Objeto da Request
$req = new \FastSitePHP\Web\Request();

// Cabeçalhos da Request de Proxy são usados por campos chave como IP do
// cliente quando um servidor web está atrás de um servidor "proxy" em
// uma rede local, por exemplo um balanceador de carga. Ler os valores
// corretamente é importante para segurança, entretanto, em geral com qualquer
// linguagem de programação ou framework, ler cabeçalhos de proxy é difícil
// requer configuração extra. O FastSitePHP torna essa tarefa fácil sem a
// necessidade de configuração.

// Por exemplo, simplesmente ler o IP do cliente da requisição pode ser
// feito lendo o valor de REMOTE_ADDR.
$client_ip = $_SERVER['REMOTE_ADDR'];

// Se o balanceador de carga estiver configurado para fornecer o IP do
// Cliente, isso será normalmente um dos seguintes cabeçalhos de requisição:
// [X-Forwarded-For, Client-Ip ou Forwarded]. Entretanto, desde que o usuário
// final possa enviar dados com o cabeçalho de requisição, isso deve ser
// lido corretamente. O cabeçalho padronizado [Forwarded] tem um formato
// como este:
//     'for=192.0.2.43, for="[2001:db8:cafe::17]";proto=http;by=203.0.113.43'
// Enquanto cabeçalhos não padronizados mas amplamente utilizados tal como
// [X-Forwarded-For], utilizam este formato:
//     'client-ip1, client-ip2, proxy1, proxy2'
// O FastSitePHP lida com ambos os formatos.

// Por exemplo, assumamos que o balanceador de carga esteja em '10.0.0.1',
// '10.0.0.2' é utilizado para filtragem adicional de conteúdo e
// [X-Forwarded-For] entrou com o seguinte valor:

//     [REMOTE_ADDR]      =   '10.0.0.1'
//     [X-Forwarded-For]  =   "' OR '1'='1 --, 127.0.0.1, 54.231.1.5, 10.0.0.2"
// Neste exemplo, o seguinte foi enviado:
//     - Client - A SQL Injection String of "' OR '1'='1 --"
//     - Client - A localhost IP [127.0.0.1]
//     - Client - Actual IP [54.231.1.5]
//     - Server - 10.0.0.2

// Ao simplesmente ler o IP do cliente sem parâmetros, o IP do balanceador
// de carga é retornado, que para esta exemplificação é '10.0.0.1'.
$client_ip = $req->clientIp();

// Então ao utilizar a configuração padrão 'from proxy', o correto IP do
// usuário é retornado '54.231.1.5' is returned. Se nenhum servidor de proxy
// for utilizado, então é seguro chamar as configurações padrão de
// 'from proxy'.
$user_ip = $req->clientIp('from proxy');

// Ao utilizar proxies, um segundo parâmetro opcional de [$trusted_proxies]
// está disponível. Este tem sua string definida por padrão como 'trust
// local', entretanto um array de um IP específico ou de faixas de IP
// (format CIDR) pode ser utilizado para uma filtragem mais específica. Além
// disso o primeiro parâmetro [$option], pode também ser modificado para ler
// de Cabeçalhos de Requisição diferentes.
$user_ip = $req->clientIp('from proxy', 'trust local');

// Além do IP de Cliente, valores de proxy também podem ser lidos para
// [Protocol, Host, and Port]:
$portocal = $req->protocol('from proxy'); // 'http' or 'https'
$host = $req->host('from proxy');
$port = $req->port('from proxy');

Objeto Request - Informação do Servidor

// O Objeto Request pode retornar o IP do Servidor e tem uma função auxiliar
// [isLocal()] que retorna true somente se ambos, o cliente requerente e o servidor,
// estiverem no localhost ['127.0.0.1' ou '::1']. Em certas apps você pode
// querer ativar certas funcionalidades para desenvolvimento ou operação
// local e estas funções ajudam nisso.
$req = new \FastSitePHP\Web\Request();
$server_ip = $req->serverIp();
$is_local  = $req->isLocal();

// NOTA - o IP do servidor web é frequentemente diferente do verdadeiro IP
// da rede. Para obter o IP da rede (localização do servidor), utilize o
// Objeto Networking Config como alternativa:
$config = new \FastSitePHP\Net\Config();
$net_ip = $config->networkIp();

Métodos

queryString($name, $format = 'value?')

Return a Request QueryString Value using format options from the [value()] function. Returns Null if the QueryString doesn't exist.

With native PHP Code Query String values can also be read from the [$_GET] Superglobal array. Example:

    $value = (isset($_GET['name']) ? $_GET['name'] : null)

Retorna: mixed

form($name, $format = 'value?')

Return a Request Form Field Value using format options from the [value()] function. Returns Null if the Form Field doesn't exist.

With native PHP Form Field values can also be read from the [$_POST] Superglobal array. Example:

    $value = (isset($_POST['name']) ? $_POST['name'] : null)

Retorna: mixed

Return a Request Cookie Value using format options from the [value()] function. Returns Null if the Cookie doesn't exist.

With native PHP Code Cookie values can also be read from the [$_COOKIE] Superglobal array. Example:

    $value = (isset($_COOKIE['name']) ? $_COOKIE['name'] : null)

Retorna: mixed

verifiedCookie($name)

Use to read secure cookies that were created from [Response->signedCookie()]. Returns null if cookie is not set or if it cannot be verified.

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

Retorna: mixed

jwtCookie($name)

Use to read secure cookies that were created from [Response->jwtCookie()]. Returns null if cookie is not set or if it cannot be verified.

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

Retorna: mixed

decryptedCookie($name)

Use to read secure and secret cookies that were created from [Response->encryptedCookie()]. Returns null if cookie is not set or if it cannot be decrypted.

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

Retorna: mixed

value($data, $key, $format = 'value?', $max_length = null)

Helper function to handle user input or objects where a value may or may not exist. This function is very flexible and depending upon the parameters checks if an array key, object property, or an array of keys/properties exists and returns the value in the desired format. This function is ideal for handling user input from PHP superglobals ($_GET, $_POST, $_COOKIE, $_SESSION) and data from JSON Objects.

This function can be used to sanitize (clean) data and return it in a needed format (example zero [0] for an integer instead of an invalid string or error message).

Options for the return format are specified in the parameter [$format]. Options that end with a question mark '?' will return either null or the value while options that do not end with a question mark are always converted to the specific data type:

    'value?'
    Optional value, returns the value as-is or null if not set

    'string'
    Always return a string type and an empty string if no data.
    Whitespace is trimmed (spaces, tabs, new lines, etc).

    'string?'
    Return string data type or null if not set or
    the string is empty. Whitespace is trimmed.

    'string with whitespace'
    Always return a string and keep any whitespace

    'int'
    Always return an int data type, if the value was
    not set or a valid integer then it will return zero.

    'int?'
    Return int or null

    'float'
    Always return an float/double data type, if the value
    was not set or a valid float then it will return zero.

    'float?'
    Return float or null

    'bool'
    Return a boolean (true or false).
    returns true if the value is '1', 'true', 'on', or 'yes'
    and false for all other values.

    'bool?'
    Return a boolean (true|false) or null
    Using strict bool validation values so the following rules apply:
    returns true if the value is '1', 'true', 'on', or 'yes'
    returns false if the value is '0', 'false', 'off', or 'no'
    returns null for all other values

    'checkbox'
    Check the value of an HTML Submitted Form Field Checkbox
    and convert it to a database bit value of 1 or 0. HTML
    Posted Forms if checked will have the value set to 'on'
    otherwise the field name will not be included in the POST.
    Specifying $format of 'bool' for a checkbox field will
    allow return true/false if that is desired over 1/0.

    'email?'
    Return a valid email address or null

    'url?'
    Return a valid url address beginning with 'http://' or 'https://' or null

Examples:
    $_POST['input1'] = 'test';
    $_POST['input2'] = '123.456';
    $_POST['checkbox1'] = 'on';
    $json = json_decode('{"app":"FastSitePHP","strProp":"abc","numProp":"123","items":[{"name":"item1"},{"name":"item2"}]}');

    'test'        = $req->value($_POST, 'input1');
    'te'          = $req->value($_POST, 'input1', 'string', 2); // Truncate string to 2 characters
    123.456       = $req->value($_POST, 'input2', 'float');
    ''            = $req->value($_POST, 'missing', 'string'); // Missing Item
    1             = $req->value($_POST, 'checkbox1', 'checkbox');
    0             = $req->value($_POST, 'checkbox2', 'checkbox'); // Missing Item
    true          = $req->value($_POST, 'checkbox1', 'bool');
    'FastSitePHP' = $req->value($json, 'app');
    'abc'         = $req->value($json, 'strProp', 'string?');
    0             = $req->value($json, 'strProp', 'int'); // Invalid Int
    null          = $req->value($json, 'strProp', 'int?'); // Invalid Int
    123           = $req->value($json, 'numProp', 'int');
    'item1'       = $req->value($json, array('items', 0, 'name'));
    'item2'       = $req->value($json, array('items', 1, 'name'));
    null          = $req->value($json, array('items', 2, 'name')); // Missing Item

Retorna: mixed

header($name)

Return the value of a Header Field sent with the HTTP Request. If the key does not exist for then this function will return null. Header values are read directly from the PHP Superglobal $_SERVER Array.

Examples:
    $content_type = $req->header('Content-Type')
    $user_agent = $req->header('User-Agent')

    Header Keys are Case-insensitive so the following all return the same value
    $value = $req->header('content-type')
    $value = $req->header('CONTENT-TYPE')
    $value = $req->header('Content-Type')

Retorna: string | null

headers()

Return an array of all HTTP Request Headers Fields. Header names will be capitalized so the following names ['Content-type', 'Content-Type', and 'CONTENT-TYPE'] would all be returned by this function as 'Content-Type' for the key in the array.

Retorna: array

method()

Return the Request Method as a string ['GET', 'POST', 'PUT', etc].

Retorna: string | null

contentType()

Read the specified request header 'Content-Type' and return a text string with a simple value 'json|form|text|xml|form-data' to indicate the type of request content, if unknown then the actual value, or if not set then null. This function can be used to show the return format of the input() function. The difference between 'form' and 'form-data' is 'form' is used to indicate a simple html form posted as 'application/x-www-form-urlencoded' while 'form-data' is for forms with possible files posted as 'multipart/form-data'. If the return type is 'form-data' then the input must be read using superglobal variables $_POST and $_FILES because content() and contentText() use 'php://input' which does not read from multipart forms.

Retorna: string | null

content()

Read the request input stream and return the result as as an object, array, text, or null based on the specified content-type. This function is a different from contentText() which always returns the request input as a text string. This would commonly be used to handle posted JSON data or put form values to a web service. The supported return type formats are:
    *) 'json' which returns an associative array if text is parsed or
       null if invalid json
    *) 'form' which returns an associative array of the
       parsed form values
    *) All other input types are returned as text and it's
       up to the app developer to handle them. XML is not handled
       by default because there are multiple XML Libraries built
       into PHP and it would be up to the app developer to determine
       the best one to use plus XML is now becoming a lot less
       common and typically being replaced with JSON services.

Retorna: mixed

contentText()

Read the request input stream and return the result as text. This reads 'php://input' which can only be read once prior to PHP 5.6; this function saves the result and can be read over and over. The return value is always a string regardless of type. This would commonly be used to handle posted JSON data or put form values to a web service. To return request input in the actual format sent from the client use the function input().

Retorna: string

bearerToken()

Return a Bearer Token value from the Authorization Request Header. If the header is not set or the token is invalid then null will be returned.

Bearer Tokens are commonly used with API’s and Web Services. Token values are defined by the app and can include OAuth 2.0, JSON Web Tokens (JWT), or custom formats.

Example Request:
    'Authorization: Bearer abc123'

This function returns:
    'abc123'

The web standard (RFC 6750) is focused around OAuth 2.0 however it defines a flexible format for the token value to support various encoded token types:
    Bearer {OAuth 2.0}
    Bearer {JWT}
    Bearer {Hex}
    Bearer {Base64}
    Bearer {Base64url}

Retorna: string | null

isXhr()

Return true if the request was submitted with the header [X-Requested-With] containing the value [XMLHttpRequest]. This header is sent with jQuery and other popular JavaScript Frameworks when making web service calls.

An example of using this function for on a site would be if a Web Form allows for both Form POST's and Web Service Calls to the same URL. For this example the server code could check if the function was submitted as an xhr request and if so return JSON otherwise return HTML.

Retorna: bool

origin()

Get the value of the 'Origin' Request Header if set or null if not set. This header value is submitted by Web Browsers for Cross-Origin Resource Sharing (CORS) Requests. This function can be used with the cors() function to handle CORS Requests. In JavaScript the origin of a web site can be determined from the property [window.location.origin]. For reference links related to the 'Origin' Header refer to the cors() function.

If a page is being viewed directly from the file system [window.location.origin] will show 'file://' and submit a string value of 'null' to the server. The string value of null is handled and returned as null with this function.

Retorna: null

userAgent()

Get the value of the 'User-Agent' Request Header or null if not submitted. The 'User-Agent' header is a string that often provides info related to what Browser or HTTP client the user is using and what OS they are on. The header value is commonly spoofed meaning requests will say they are a specific browser and OS when they are in fact something else so user agent values generally cannot be relied upon. However if a site is tracking User Agent strings then it can provide a general overview of who is using the site and what devices or browsers they are using. In JavaScript the User Agent can be determined from the property [navigator.userAgent].

Retorna: null

referrer()

Get the value of the 'Referer' Request Header. The Referer Header provides address of a web page or web site that linked to the current request. This value will also be set by search engines (e.g.: Google or Bing) when a user is coming from the search engine. The Referer header is a defined web standard and was originally defined as a misspelled English word so it has been kept as a misspelled word for technical purposes; just like JavaScript this function uses the correctly English Spelling. In JavaScript from a Web Browser this value can be determined from the property [document.referrer].

Retorna: null

clientIp($option = null, $trusted_proxies = 'trust local')

Return the IP Address of the remote client (the end-user) that is requesting the webpage or resource. For security if no options are specified this function will return the server variable REMOTE_ADDR. However depending upon the environment, the server variable REMOTE_ADDR might not the IP Address of the remote client but rather the IP Address of the a Proxy Server such as a Load Balancer. For websites that use a proxy server this function provides a number of options to securely read the IP Address of the client. If you do not use a proxy server then call this function without passing any arguments if you need the client's IP address.

Reading the remote client IP Address is a possible source of attacks by malicious clients for insecure web frameworks and code. FastSitePHP is designed for security out of the box so using this function with default parameters is secure however if using a proxy server the actual web server and environment must also be properly configured. For an example of this type of attack see comments in the function [isLocal()].

The server variable REMOTE_ADDR on most server environments will always contain the IP Address of the connecting client. Generally this value is always safe to read. If a proxy server is used and configured to provide the client's IP Address then it will likely be sent in a Request Header such as 'X-Forwarded-For', 'Client-IP', or 'Forwarded'. These request headers typically use the following format:

   X-Forwarded-For: Client1, Client2, Proxy1, Proxy2
   (Example): 127.0.0.1, 54.231.1.14, 10.0.0.1, 10.0.0.2

In this example only the value Client2 would be safe to read as it is the last "untrusted" IP Address to reach a "trusted" proxy server. The IP Address specified in Client1 could be anything (for example 127.0.0.1 to spoof localhost or a SQL Injection Attack) which is why only the value from Client2 would be valid for IP Reporting or Logging. The terms "untrusted" and "trusted" are commonly used when referring to proxy servers and they mean that an "untrusted" client is one that exists on the public internet while a "trusted" client is a known computer (usually on a private network) that you have control over or trust as providing valid IP info.

This function has two parameters [$options] and [$trusted_proxies]:

    $options (string or null):
        *) Defaults to null which returns REMOTE_ADDR and results in remote
           IP Addresses not being checked.
        *) 'from proxy' - If specified this will check the following three server variables
           [ 'HTTP_X_FORWARDED_FOR', 'HTTP_CLIENT_IP', 'HTTP_FORWARDED' ] which maps to
           Request Headers [ 'X-Forwarded-For', 'Client-IP', 'Forwarded' ]. Each of the
           Headers is checked and the matching header is used to lookup the IP Address.
           If multiple headers exist with different IP Addresses then an exception
           is raised with this option because it would not be possible for the application
           to know which header is correct. The three headers checked are the most
           common headers used for specifying the client's IP Address. Headers
           'X-Forwarded-For' and 'Client-IP' are non-standard headers but widely used.
           The header 'Forwarded' is part of Web Standard RFC 7239 however it is relatively
           new (defined in 2014) and not yet widely used.
        *) 'HTTP_X_FORWARDED_FOR' or the key of a Server Variable for the Request Header
           that contains the Client's IP Address from the Proxy Server. For example if
           the client's IP Address is sent in the request header 'X-Forwarded-For' then
           the server variable 'HTTP_X_FORWARDED_FOR' will contain the value of the header.
           Even though FastSitePHP allows for the simple option 'from proxy', entering the
           actual server variable is good practice because it allows the application to
           ignore all other headers. In some cases a valid public client can also be behind
           a proxy server that uses one of the headers which is different than the header
           used by the web server. In this case if the headers are not correctly modified
           by the proxy server then this function will raise an exception because
           it doesn't know which header value to use.

    $trusted_proxies (string or array):
        *) This option only applies if the parameter [$option] is not null.
        *) 'trust local' - The default value. This uses CIDR Notation string
           values returned from the array [$app->privateNetworkAddresses()]
           and also allows for Web Standard RFC 7239 Obfuscated and
           Unknown Identifiers.
        *) Optionally this parameter can be set with a string or an array of
           specific IP Addresses or CIDR Notation IP Ranges to trust.
        *) If using a proxy server then the default value 'trust local' should
           be used for most websites as it is secure and only allows for
           IP Addresses that would appear on a private network to be trusted.

Examples:
    Remote Address and one 'X-Forwarded-For' header on a private network
        REMOTE_ADDR = '10.1.1.1'
        HTTP_X_FORWARDED_FOR = '54.231.1.4, 10.1.1.2'

        '10.1.1.1' = req->clientIp()
        Function called without any parameters so the value from REMOTE_ADDR is returned

        '54.231.1.4' = req->clientIp('from proxy')
        '54.231.1.4' = req->clientIp('from proxy', 'trust local')
        '54.231.1.4' = req->clientIp('from proxy', $app->privateNetworkAddresses())
        Client IP Address is returned when using 'from proxy' as the function
        determines the proxy addresses. 'trust local' is the default option and
        it uses an array of CIDR Notation String Values from the function
        [$app->privateNetworkAddresses()].

        '10.1.1.2' = req->clientIp('from proxy', '10.1.1.1')
        Only the IP Address '10.1.1.1' is trusted so '10.1.1.2' is returned

        '54.231.1.4' = req->clientIp('HTTP_X_FORWARDED_FOR')
        Client IP Address is returned when using the specific server variable as an option

    Three Client IP Addresses specified ("' OR '1'='1' --", 127.0.0.1, 54.231.1.5).
    The left-most address is an attempted SQL Injection String while the 2nd address
    '127.0.0.1' is an attempt to spoof localhost permissions. Only the 3rd Address
    '54.231.1.5' is the IP Address that the client actually connected from.
        REMOTE_ADDR = '10.0.0.1'
        HTTP_X_FORWARDED_FOR = "' OR '1'='1 --, 127.0.0.1, 54.231.1.5"

        '10.0.0.1' = req->clientIp()
        Function called without any parameters so the value from REMOTE_ADDR is returned

        '54.231.1.5' = req->clientIp('from proxy')
        The correct Client IP Address is returned and the two left-most values are ignored

    The Client Connects from their own proxy '54.231.1.7' and specified the final Client IP
    '54.231.1.6' in two Request Headers 'X-Forwarded-For' and 'Client-Ip'. An internal
    Proxy Server is configured to only handle 'X-Forwarded-For'.
        REMOTE_ADDR = '10.0.0.2'
        HTTP_X_FORWARDED_FOR = '54.231.1.6, 54.231.1.7'
        HTTP_CLIENT_IP = '54.231.1.6'

        req->clientIp('from proxy')
        An Exception is thrown because the IP Request Headers are
        incompatible and the client cannot be determined.

        '54.231.1.7' = req->clientIp('HTTP_X_FORWARDED_FOR')
        The correct Client IP is returned because the correct server variable is specified.

    Client IP supports both IPv4 and IPv6. In this example an IPv6 Unique local address
    ('fc00::/7') is specified as the trusted proxy. In CIDR Notation the address 'fc00::/7'
    also covers the IP Range 'fd00::/8' which is why REMOTE_ADDR starts with 'fddb:'.
        REMOTE_ADDR = 'fddb:1273:5643::1234'
        HTTP_X_FORWARDED_FOR = '2001:4860:4801:1318:0:6006:1300:b075'

        '2001:4860:4801:1318:0:6006:1300:b075' = req->clientIp('from proxy')
        The correct public IPv6 Address (in this case a Googlebot) is returned

Retorna: string | null

protocol($option = null, $trusted_proxies = 'trust local')

Return the protocol (a string value of either 'http' or 'https') that was used to make the request. If the web server is behind a proxy server (for example a load balancer) then optional parameters allow for the protocol to be safely read from a proxy request header. If not using a proxy server then functions rootDir() and rootUrl() can be used to easily obtain needed URLs for the hosted site instead of using this function.

For reading proxy headers functions clientIp(), protocol(), host(), and port() all share similar parameters; refer to clientIp() documentation for detailed comments on the options. For protocol() if the [option] parameter is set to 'from proxy' then the value is read from the request header 'X-Forwarded-Proto' (server variable X_FORWARDED_PROTO). To use a different proxy request header use the corresponding server variable name as the [option] parameter. If using a proxy header variable the value from the proxy header should be either 'http' or 'https'.

Retorna: string | null

host($option = null, $trusted_proxies = 'trust local', array $allowed_hosts = null)

Return the host value (domain name) for the request. If the host value contains a port number (for example 'site:8080' then it will be included with the host in return value). If the web server is behind a proxy server (for example a load balancer) then optional parameters allow for the host to be safely read from a proxy request header. If not using a proxy server then functions rootDir() and rootUrl() can be used to easily obtain needed URLs for the hosted site instead of using this function.

For reading proxy headers functions clientIp(), protocol(), host(), and port() all share similar parameters; refer to clientIp() documentation for detailed comments on the options. For host() if the [option] parameter is set to 'from proxy' then the value is read from the request header 'X-Forwarded-Host' (server variable X_FORWARDED_HOST). To use a different proxy request header use the corresponding server variable name as the [option] parameter.

For proxy server values an optional array of allowed hosts can be defined for validation using the [allowed_host] parameter. If the array is defined and the proxy host does not match then an exception is thrown. This can help prevent attacks when using a proxy server that specifies a different domain from the actual web server. Values in the array are matched to the host based on an exact match (case-insensitive) or can also be matched using one of two wildcard card characters: [*] which matches to one or more of any character and [#] which matches to a numeric value of digits.

[$allowed_hosts] Examples:
    'domain.tld'   - matches [domain.tld] and [DOMAIN.TLD] but not [www.domain.tld]
    '*.domain.tld' - matches [sub.domain.tld] and [sub. sub2.domain.tld] but not [domain.tld]
    'Domain.tld:#' - matches [domain.tld:8080]

Retorna: string | null

port($option = null, $trusted_proxies = 'trust local')

Return the port number for the request. In most cases the end user would connect to a server using port 80 for HTTP and port 443 for secure HTTPS requests. Other port numbers may be used in development or on server environments. If the web server is behind a proxy server (for example a load balancer) then optional parameters allow for the port number to be safely read from a proxy request header. If not using a proxy server then functions rootDir() and rootUrl() can be used to easily obtain needed URLs for the hosted site instead of using this function.

For reading proxy headers functions clientIp(), protocol(), host(), and port() all share similar parameters; refer to clientIp() documentation for detailed comments on the options. For port() if the [option] parameter is set to 'from proxy' then the value is read from the request header 'X-Forwarded-Port' (server variable X_FORWARDED_PORT). To use a different proxy request header use the corresponding server variable name as the [option] parameter.

Retorna: string | null

serverIp()

Return the IP Address that the Web Server is running from. When running on localhost or using PHP's Built-in Development Web Server this function will likely return '127.0.0.1' (IPv4) or '::1' (IPv6) and if running a PHP Script from the command line without a web server then this function will likely return null. For default Apache installations this function will get the IP Address from the server variable SERVER_ADDR and for default IIS installations this function will get the IP Address from the server variable LOCAL_ADDR. To get the Network IP Address of the Computer see the function [FastSitePHP\Net\Config->networkIp()].

Retorna: string | null

isLocal()

Return true if the request is running from localhost '127.0.0.1' (IPv4) or '::1' (IPv6) and if the web server software is also running on localhost. This function can be used to show or hide specific site features for developers or administrators. This function would likely always be safe to call as it does not use IP Addresses from a proxy server however it is possible that a misconfigured sever or server code that overwrites server variables could provide incorrect info. If using this function make sure to test the site in various environments to see that it behaves as expected. The reference link provides an example of how a misconfigured server can cause errors with server software thinking its running in localhost when it's not. In regards to the reference link this function would not have failed as it's checking both Client and Server IP Addresses.

Retorna: bool

accept($mime_type = null)

Parse the 'Accept' Request Header into an array or if an optional parameter is specified then check if the 'Accept' Header contains the specified MIME Type and return true or false. See also comments for the function [acceptLanguage()] because all [accept*()] functions have similar behavior.

Retorna: array | bool

acceptCharset($character_encoding = null)

Parse the 'Accept-Charset' Request Header into an array or if an optional parameter is specified then check if the 'Accept-Charset' Header contains the specified Character Encoding and return true or false. See also comments for the function [acceptLanguage()] because all [accept*()] functions have similar behavior.

NOTE - this header is no longer commonly used and for web browsers and it is safe for servers to assume that UTF-8 is the accepted character encoding method.

Retorna: array | bool

acceptEncoding($content_encoding = null)

Parse the 'Accept-Encoding' Request Header into an array or if an optional parameter is specified then check if the 'Accept-Encoding' Header contains the specified Content Encoding and return true or false. See also comments for the function [acceptLanguage()] because all [accept*()] functions have similar behavior.

Retorna: array | bool

acceptLanguage($language = null)

For HTTP there are several standard 'Accept*' Request Headers that can be used for content negotiation by a web server to determine how to respond.

Parse the 'Accept-Language' Request Header into an array or if an optional parameter is specified then check if the 'Accept-Language' Header contains the specified Language and return true or false.

Example:
    'Accept-Language' Header Value = 'ru-RU,ru;q=0.8,en-US;q=0.6,en;q=0.4'

    acceptLanguage():
    returns array(
        array('value' => 'ru-RU', 'quality' => null),
        array('value' => 'ru',    'quality' => 0.8),
        array('value' => 'en-US', 'quality' => 0.6),
        array('value' => 'en',    'quality' => 0.4),
    );

    acceptLanguage('en'): true
    acceptLanguage('de'): false

Retorna: array | bool