Secciones

Componente Petición


Resumen

Phalcon\Http\Request is a component that encapsulates the actual HTTP request (usually originated by a browser) and sent to our application. The Phalcon\Http\Request object is a simple value object that is passed between the dispatcher and controller classes, wrapping the HTTP request environment. También ofrece fácil acceso a la información como datos de la cabecera, ficheros, métodos, variables, etc.

<?php

use Phalcon\Http\Request;

$request = new Request();

// POST
if (true === $request->isPost()) {
    // AJAX
    if (true === $request->isAjax()) {
        // ....
    }
}

Obteniendo Valores

PHP automatically fills the superglobal arrays $_GET, $_POST and $_REQUEST depending on the type of the request. Estos vectores contienen los valores presentes en los formularios enviados o los parámetros enviados vía URL. The variables in the arrays are never sanitized and can contain illegal characters or even malicious code, which can lead to SQL injection or Cross Site Scripting (XSS) attacks.

Phalcon\Http\Request allows you to access the values stored in the $_GET, $_POST and $_REQUEST arrays and sanitize or filter them with the filter service.

There are 5 methods that allow you to retrieve submitted data from a request:

  • get()
  • getQuery()
  • getPost()
  • getPut()
  • getServer()

All (except getServer()) accept the following parameters:

Nombre Descripción
name the name of the value to get
filters (array/string) the sanitizers to apply to the value
defaultValue returned if the element is not defined (null)
notAllowEmpty if set (default) and the value is empty, the defaultValue will be returned; otherwise null
noRecursive applies the sanitizers recursively in the value (if value is an array)
<?php

use Phalcon\Http\Request;

$request = new Request();

$request->get(
    $name = null,            // string
    $filters = null,         // mixed
    $defaultValue = null,    // mixed
    $notAllowEmpty = false,  // bool
    $noRecursive = false     // bool
): mixed

getServer() acepta sólo una variable name (string), que representa la variable con el nombre del servidor que necesita recuperar.

$_REQUEST

The $_REQUEST superglobal contains an associative array that contains the contents of $_GET, $_POST and $_COOKIE. You can retrieve the data stored in the array by calling the get() method in the Phalcon\Http\Request object as follows:

Ejemplos

Get the userEmail field from the $_REQUEST superglobal:

<?php

use Phalcon\Http\Request;

$request = new Request();

$email = $request->get('userEmail');

Obtiene el campo userEmail del superglobal $_REQUEST. Sanea el valor con el saneador email:

<?php

use Phalcon\Http\Request;

$request = new Request();

$email = $request->get('userEmail', 'email', '[email protected]');

Obtiene el campo userEmail del superglobal $_REQUEST. No lo sanea. Si el parámetro es nulo, devuelve el valor por defecto:

<?php

use Phalcon\Http\Request;

$request = new Request();

$email = $request->get('userEmail', null, '[email protected]');

$_GET

The $_GET superglobal contains an associative array that contains the variables passed to the current script via URL parameters (also known as the query string). Puede recuperar los datos almacenados en el vector llamando al método getQuery() de la siguiente manera:

Ejemplos

Get the userEmail field from the $_GET superglobal:

<?php

use Phalcon\Http\Request;

$request = new Request();

$email = $request->getQuery('userEmail');

Obtiene el campo userEmail del superglobal $_GET. Sanea el valor con el saneador email:

<?php

use Phalcon\Http\Request;

$request = new Request();

$email = $request->getQuery('userEmail', 'email', '[email protected]');

Obtiene el campo userEmail del superglobal $_GET. No lo sanea. Si el parámetro es nulo, devuelve el valor por defecto:

<?php

use Phalcon\Http\Request;

$request = new Request();

$email = $request->getQuery('userEmail', null, '[email protected]');

$_POST

The $_POST superglobal contains an associative array that contains the variables passed to the current script via the HTTP POST method when using application/x-www-form-urlencoded or multipart/form-data as the HTTP Content-Type in the request. Puede recuperar los datos almacenados en el vector llamando al método getPost() de la siguiente manera:

Ejemplos

Get the userEmail field from the $_POST superglobal:

<?php

use Phalcon\Http\Request;

$request = new Request();

$email = $request->getPost('userEmail');

Obtiene el campo userEmail del superglobal $_POST. Sanea el valor con el saneador email:

<?php

use Phalcon\Http\Request;

$request = new Request();

$email = $request->getPost('userEmail', 'email', '[email protected]');

Obtiene el campo userEmail del superglobal $_POST. No lo sanea. Si el parámetro es nulo, devuelve el valor por defecto:

<?php

use Phalcon\Http\Request;

$request = new Request();

$email = $request->getPost('userEmail', null, '[email protected]');

Put

El objeto petición analiza el flujo PUT que se ha recibido internamente. Puede recuperar los datos almacenados en el vector llamando al método getPut() de la siguiente manera:

Ejemplos

Get the userEmail field from the PUT stream:

<?php

use Phalcon\Http\Request;

$request = new Request();

$email = $request->getPut('userEmail');

Obtiene el campo userEmail del flujo PUT. Sanea el valor con el saneador email:

<?php

use Phalcon\Http\Request;

$request = new Request();

$email = $request->getPut('userEmail', 'email', '[email protected]');

Obtiene el campo userEmail del flujo PUT. No lo sanea. Si el parámetro es nulo, devuelve el valor por defecto:

<?php

use Phalcon\Http\Request;

$request = new Request();

$email = $request->getPut('userEmail', null, '[email protected]');

$_SERVER

The $_SERVER superglobal contains an array containing information such as headers, paths, and script locations. Puede recuperar los datos almacenados en el vector llamando al método getServer() de la siguiente manera:

Ejemplos

Get the SERVER_NAME value from the $_SERVER superglobal:

<?php

use Phalcon\Http\Request;

$request = new Request();

$name = $request->getServer('SERVER_NAME');

Saneadores Preestablecidos

Es relativamente común que ciertos campos usen el mismo nombre a lo largo de su aplicación. Un campo publicado desde un formulario en su aplicación puede tener el mismo nombre y función que otro formulario en un área distinta. Ejemplos de este comportamiento podrían ser los campos id, nombre etc.

To make the sanitization process easier, when retrieving such fields, Phalcon\Http\Request offers a method to define those sanitizing filters based on HTTP methods when setting up the object.

<?php

use Phalcon\Di\Di;
use Phalcon\Filter;
use Phalcon\Http\Request;

$container = new Di();

$container->set(
    'request',
    function () {
        $request = new Request();
        $request
            ->setParameterFilters(
                'id', 
                Filter::FILTER_ABSINT, 
                [
                    'post'
                ]
            )
            ->setParameterFilters(
                'name', 
                [
                    'trim', 
                    'string'
                ], 
                [
                    'post'
                ]
            )
        ;

        return $request;
    }
);

Lo anterior saneará automáticamente cualquier parámetro publicado desde un formulario que tenga un nombre id o name con sus respectivos filtros. Sanitization takes place when calling the following methods (one per HTTP method)

  • getFilteredPost()
  • getFilteredPut()
  • getFilteredQuery()

Estos métodos aceptan los mismos parámetros que getPost(), getPut() y getQuery() pero sin el parámetro $filter.

Controladores

If you use the Phalcon\Di\FactoryDefault container, the Phalcon\Http\Request is already registered for you. El lugar más común para acceder el entorno de la petición es en una acción de un controlador. To access the Phalcon\Http\Request object from a controller you will need to use the $this->request public property of the controller:

<?php

use Phalcon\Http\Request;
use Phalcon\Mvc\Controller;

/**
 * Class PostsController
 * 
 * @property Request $request
 */
class PostsController extends Controller
{
    public function saveAction()
    {
        // Check if request has made with POST
        if (true === $this->request->isPost()) {
            // Access POST data
            $customerName = $this
                ->request
                ->getPost('name');
            $customerBorn = $this
                ->request
                ->getPost('born', 'string', '1984');
        }
    }
}

Operaciones de Comprobación

The Phalcon\Http\Request component contains a number of methods that help you check the current operation. Por ejemplo, si quiere comprobar si se ha realizado una solicitud en particular usando AJAX, puede hacerlo usando el método isAjax(). Todos los métodos llevan el prefijo is.

Nombre Descripción
isAjax() Checks whether request has been made using AJAX
isConnect() Checks whether HTTP method is CONNECT
isDelete() Checks whether HTTP method is DELETE
isGet() Checks whether HTTP method is GET
isHead() Checks whether HTTP method is HEAD
isMethod() Comprueba si el método HTTP coincide con alguno de los métodos pasados
isOptions() Checks whether HTTP method is OPTIONS
isPatch() Checks whether HTTP method is PATCH
isPost() Checks whether HTTP method is POST
isPurge() Checks whether HTTP method is PURGE (Squid and Varnish support)
isPut() Checks whether HTTP method is PUT
isSecure() Comprueba si la petición se ha hecho usando alguna capa segura
isSoap() Comprueba si la petición se ha hecho usando SOAP
isTrace() Checks whether HTTP method is TRACE
isValidHttpMethod() Comprueba si un método es un método HTTP válido

Comprobar Existencia

Hay un número de métodos disponibles que le permiten comprobar la existencia de elementos de la solicitud. Estos métodos llevan el prefijo has. Dependiendo del método utilizado, puede comprobar si existe un elemento en el $_REQUEST, $_GET, $_POST, $_SERVER, $_FILES, caché PUT y los encabezados de solicitud.

Nombre Descripción
has() Checks whether the $_REQUEST superglobal has a certain element
hasFiles() Checks whether the request has any uploaded files
hasHeader() Checks whether the headers have a certain element
hasPost() Checks whether $_POST superglobal has a certain element
hasPut() Checks whether the PUT data has a certain element
hasQuery() Checks whether $_GET superglobal has a certain element
hasServer() Checks whether $_SERVER superglobal has a certain element
numFiles() Returns the number of files present in the request

Información de la Petición

The Phalcon\Http\Request object offers methods that provide additional information regarding the request.

Autenticación

Nombre Descripción
getBasicAuth() Gets auth info accepted by the browser/client
getDigestAuth() Gets auth info accepted by the browser/client

Cliente

Nombre Descripción
getClientAddress() Gets most possible client IPv4 Address
getClientCharsets() Gets a charsets array and their quality accepted by the browser/client
getUserAgent() Obtiene el agente de usuario HTTP utilizado para hacer la solicitud
getHTTPReferer() Gets web page that refers active request

Contenido

Nombre Descripción
getAcceptableContent() Gets an array with mime/types and their quality accepted by the browser/client
getBestAccept() Gets best mime/type accepted by the browser/client
getContentType() Obtiene el tipo de contenido en el que se hizo la solicitud
getJsonRawBody() Obtiene el cuerpo de la petición HTTP sin procesar decodificado en JSON
getRawBody() Obtiene el cuerpo de solicitud HTTP sin procesar

i18n

Nombre Descripción
getBestCharset() Gets best charset accepted by the browser/client
getBestLanguage() Gets best language accepted by the browser/client
getLanguages() Gets languages array and their quality accepted by the browser/client

Servidor

Nombre Descripción
getPort() Obtiene información sobre el puerto en el que se ha hecho la petición
getServerAddress() Obtiene la IP de la dirección del servidor activo
getServerName() Obtiene el nombre del servidor activo
getScheme() Obtiene el esquema HTTP (http/https)
getURI() Gets HTTP URI which request has been made. Si se pasa true como parámetro, la parte de consulta no se devolverá
<?php

use Phalcon\Http\Request;

$request = new Request();

if ($request->isAjax()) {
    echo 'The request was made with Ajax';
}

// Check the request layer
if ($request->isSecure()) {
    echo 'The request was made using a secure layer';
}

Algunos métodos:

$ipAddress = $request->getServerAddress();

Obtiene la dirección IP del servidor. ie. 192.168.0.100

$ipAddress = $request->getClientAddress();

Get the client’s IP address ie. 201.245.53.51

$userAgent = $request->getUserAgent();

Obtiene el Agente del Usuario (HTTP_USER_AGENT)

$contentType = $request->getAcceptableContent();

Obtiene el mejor contenido aceptable por el navegador. ej text/xml

$charset = $request->getBestCharset();

Obtiene el mejor conjunto de caracteres aceptado por el navegador. ie. utf-8

$language = $request->getBestLanguage();

Obtiene el mejor idioma aceptado configurado en el navegador. ie. en-us

Método

getMethod() devuelve método HTTP que ha hecho la petición. Si la cabecera X-HTTP-Method-Override está establecida, y si el método es POST, entonces se usa para determinar el método HTTP “real” deseado. El parámetro _method de la petición también se puede usar para determinar el método HTTP, se tiene que llamar a setHttpMethodParameterOverride(true). El método siempre devuelve una cadena en mayúsculas.

<?php

use Phalcon\Http\Request;

$request = new Request();

// POST
$_SERVER['REQUEST_METHOD'] = 'POST';
echo $request->getMethod();

/**
 * header('X-HTTP-Method-Override: GET');
 */ 
$_SERVER['REQUEST_METHOD'] = 'POST';
$request->setHttpMethodParameterOverride(true);
echo $request->getMethod();

// GET
$_SERVER['REQUEST_METHOD'] = 'POST';
$_REQUEST['_method']       = 'GET';
$request->setHttpMethodParameterOverride(true);
echo $request->getMethod();

Inyección de Dependencias

The Phalcon\Http\Request object implements the Phalcon\Di\InjectionAwareInterface interface. Como resultado, el contenedor DI está disponible y puede ser recuperado usando el método getDI(). Un contenedor también puede ser establecido usando el método setDI().

Trabajando con Cabeceras

Las cabeceras de solicitud contienen información útil, permitiéndole tomar los pasos necesarios para enviar la respuesta adecuada de vuelta al usuario. The Phalcon\Http\Request exposes the getHeader() and getHeaders() methods.

<?php

use Phalcon\Http\Request;

$request = new Request;

$_SERVER["HTTP_HOST"] = "example.com";
$request->getHttpHost(); // example.com

$_SERVER["HTTP_HOST"] = "example.com:8080";
$request->getHttpHost(); // example.com:8080

$request->setStrictHostCheck(true);
$_SERVER["HTTP_HOST"] = "ex=am~ple.com";
$request->getHttpHost(); // UnexpectedValueException

$_SERVER["HTTP_HOST"] = "ExAmPlE.com";
$request->getHttpHost(); // example.com

El método getHttpHost() devolverá el nombre del servidor usado por la petición. The method will try to find host name in following order:

  • $_SERVER["HTTP_HOST"]
  • $_SERVER["SERVER_NAME"]
  • $_SERVER["SERVER_ADDR"]

Opcionalmente getHttpHost() valida y realizar una comprobación estricta del nombre del servidor. Para conseguirlo, puede usar el método setStrictHostCheck().

Ficheros Subidos

Otra tarea común es la subida de ficheros. Phalcon\Http\Request offers an object-oriented way work with files. For the whole upload process to work, you will need to make the necessary changes to your php.ini (see php-uploads).

<?php

use Phalcon\Http\Request;
use Phalcon\Mvc\Controller;

/**
 * Class PostsController
 * 
 * @property Request $request
 */
class PostsController extends Controller
{
    public function uploadAction()
    {
        // if ($this->request->numFiles() > 0) {
        if ($this->request->hasFiles()) {
            $files = $this->request->getUploadedFiles();

            foreach ($files as $file) {
                echo $file->getName(), ' ', $file->getSize(), '\n';

                $file->moveTo(
                    'files/' . $file->getName()
                );
            }
        }
    }
}

Each object returned by Phalcon\Http\Request::getUploadedFiles() is an instance of the Phalcon\Http\Request\File which implements the Phalcon\Http\Request\FileInterface class. Usar el vector superglobal $_FILES ofrece el mismo comportamiento. Phalcon\Http\Request\File encapsulates only the information related to each file uploaded with the request.

getUploadedFiles() acepta dos parámetros.

Nombre Descripción
$onlySuccessful Contains only successful uploads
$namedKeys Returns the array with named keys obtained by the upload process

The method returns an array of Phalcon\Http\Request\File objects. Cada objeto ofrece las siguientes propiedades y métodos, que le permiten trabajar con los ficheros subidos:

Nombre Descripción
getError(): string Returns any error that happened with this file
getExtension(): string Returns the extension of the file
getKey(): string Returns the internal key of the file
getName(): string Devuelve el nombre real del fichero subido
getRealType(): string Return the real mime type of the upload file using finfo
getSize(): int Devuelve el tamaño de fichero del fichero subido
getTempName(): string Devuelve el nombre temporal del fichero subido
getType(): string Returns the mime type reported by the browser. El tipo mime no es completamente seguro, use getRealType() en su lugar
isUploadedFile(): bool Checks whether the file has been uploaded via POST.
moveTo(string $destination): bool Mueve el fichero temporal a una ubicación dentro de la aplicación

Inyección de Dependencias

The Phalcon\Http\Request object implements the Phalcon\Di\InjectionAwareInterface interface. Como resultado, el contenedor DI está disponible y puede ser recuperado usando el método getDI(). Un contenedor también puede ser establecido usando el método setDI().

Eventos

The Phalcon\Http\Request object implements the Phalcon\Events\EventsAware interfaces. Como resultado getEventsManager() y setEventsManager() están disponibles para usar.

Evento Descripción Puede parar la operación
afterAuthorizationResolve Se dispara cuando la autorización se ha resuelto No
beforeAuthorizationResolve Se dispara antes de que la autorización haya sido resuelta Si

Cuando se usa la autorización HTTP, la cabecera Authorization tiene el siguiente formato:

Authorization: <type> <credentials>

donde <type> es un tipo de autenticación. Un tipo común es Basic. Additional authentication types are described in IANA registry of Authentication schemes and Authentication for AWS servers (AWS4-HMAC-SHA256). In most use cases the authentication type is:

  • AWS4-HMAC-SHA256
  • Básico
  • Bearer
  • Digest
  • HOBA
  • Mutual
  • Negotiate
  • OAuth
  • SCRAM-SHA-1
  • SCRAM-SHA-256
  • vapid

Puede usar los eventos request:beforeAuthorizationResolve y request:afterAuthorizationResolve para realizar operaciones adicionales antes o después de que la autorización se resuelva.

request:beforeAuthorizationResolve recibe el vector SERVER con la clave server como segundo parámetro del evento.

request:afterAuthorizationResolve recibe el vector SERVER con la clave server así como también las cabeceras con la clave headers.

Se requiere una resolución personalizada de autorizaciones.

Ejemplo sin usar la resolución personalizada de autorizaciones:

<?php

use Phalcon\Http\Request;

$_SERVER['HTTP_AUTHORIZATION'] = 'Enigma Secret';

$request = new Request();
print_r($request->getHeaders());

Resultado:

Array
(
    [Authorization] => Enigma Secret
)

Type: Enigma
Credentials: Secret

Ejemplo usando la resolución personalizada de autorización:

<?php

use Phalcon\Di\Di;
use Phalcon\Events\Event;
use Phalcon\Http\Request;
use Phalcon\Events\Manager;

class NegotiateAuthorizationListener
{
    public function afterAuthorizationResolve(Event $event, Request $request, array $data)
    {
        if (empty($data['server']['CUSTOM_KERBEROS_AUTH'])) {
            return false;
        }

        list($type,) = explode(
            ' ', 
            $data['server']['CUSTOM_KERBEROS_AUTH'], 
            2
        );

        if (!$type || stripos($type, 'negotiate') !== 0) {
            return false;
        }

        return [
           'Authorization'=> $data['server']['CUSTOM_KERBEROS_AUTH'],
        ];
    }
}

$_SERVER['CUSTOM_KERBEROS_AUTH'] = 'Negotiate '
                                 . 'a87421000492aa874209af8bc028';

$di = new Di();

$di->set(
    'eventsManager',
    function () {
        $manager = new Manager();

        $manager->attach(
            'request',
            new NegotiateAuthorizationListener()
        );

        return $manager;
    }
);

$request = new Request();

$request->setDI($di);

print_r(
    $request->getHeaders()
);

Resultado:

Array
(
    [Authorization] => Negotiate a87421000492aa874209af8bc028
)

Type: Negotiate
Credentials: a87421000492aa874209af8bc028