PHP Request library

English version

Biblioteca PHP para manejo de peticiones.

• Requisitos
• Instalación
• Métodos disponibles
• Cómo empezar
• Uso
• Tests
• Tareas pendientes
• Contribuir
• Repositorio
• Licencia
• Copyright

Requisitos

Esta biblioteca es soportada por versiones de PHP 7.0 o superiores.

IMPORTANTE: La versión 2.x no es compatible con la versión 1.x de esta biblioteca.

IMPORTANTE: La version 1.x se considera obsoleta, aún así, si deseas utilizarla para versiones 5.6 de PHP puedes echar un vistazo a su documentación.

Instalación

La mejor forma de instalar esta extensión es a través de Composer.

Para instalar PHP Request library, simplemente escribe:

$ composer require Josantonius/Request

El comando anterior sólo instalará los archivos necesarios, si prefieres descargar todo el código fuente puedes utilizar:

$ composer require Josantonius/Request --prefer-source

También puedes clonar el repositorio completo con Git:

$ git clone https://github.com/Josantonius/PHP-Request.git

O instalarlo manualmente:

Descarga Request.php y Validate.php:

$ wget https://raw.githubusercontent.com/Josantonius/php-request/master/src/Request.php

$ wget https://raw.githubusercontent.com/Josantonius/php-validate/master/src/Validate.php

Métodos disponibles

Métodos disponibles en esta biblioteca:

- Comprobar si es una petición GET:

Request::isGet();

# Return (boolean)

- Comprobar si es una petición POST:

Request::isPost();

# Return (boolean)

- Comprobar si es una petición PUT:

Request::isPut();

# Return (boolean)

- Comprobar si es una petición DELETE:

Request::isDelete();

# Return (boolean)

- Get request params.

Para peticiones PUT y DELETE se comprobará el tipo de contenido para obtener correctamente los datos recibidos en la petición.

Los tipos de contenido compatibles con esta librería son:

• application/atom+xml
• text/html
• text/plain
• application/json
• application/javascript
• multipart/form-data
• application/x-www-form-urlencoded

Request::input($type);

| Atributo | Descripción | Tipo | Requerido | Predeterminado | --- | --- | --- | --- | --- | | $type | Tipo de solicitud. | string | Sí | |

# Return función anónima que devolverá el objeto Request cuando esta sea llamada

- Saneamiento de datos y retornar como array:

asArray($filters, $default);

| Atributo | Descripción | Tipo | Requerido | Predeterminado | --- | --- | --- | --- | --- | | $filters | Array asociativo con tipo de datos para cada clave. Los campos que no estén incluidos en los filtros no se sanearán. | array | No | [] | | $default | Valor por defecto. Se devolverá NULL o el valor por defecto para los valores de los campos que no coincidan con el tipo de dato indicado. | mixed | No | null |

# Return (array) ? devolverá un array vacío en caso de error

- Saneamiento de datos y retornar como objeto:

asObject($filters, $default);

| Atributo | Descripción | Tipo | Requerido | Predeterminado | --- | --- | --- | --- | --- | | $filters | Array asociativo con tipo de datos para cada clave. Los campos que no estén incluidos en los filtros no se sanearán. | array | No | [] | | $default | Valor por defecto. Se devolverá NULL o el valor por defecto para los valores de los campos que no coincidan con el tipo de dato indicado. | mixed | No | null |

# Return (object) ? devolverá un array vacío en caso de error

- Saneamiento de datos y retornar como JSON:

asJson($default);

| Atributo | Descripción | Tipo | Requerido | Predeterminado | --- | --- | --- | --- | --- | | $default | Valor por defecto. Se devolverá NULL o el valor por defecto para los valores de los campos que no coincidan con el tipo de dato indicado. | mixed | No | null |

# Return (mixed|null) ? valor, null o valor de retorno personalizado

- Saneamiento de datos y retornar como cadena de texto:

asString($default);

| Atributo | Descripción | Tipo | Requerido | Predeterminado | --- | --- | --- | --- | --- | | $default | Valor por defecto. Se devolverá NULL o el valor por defecto para los valores de los campos que no coincidan con el tipo de dato indicado. | mixed | No | null |

# Return (mixed|null) ? valor, null o valor de retorno personalizado

- Saneamiento de datos y retornar como entero:

asInteger($default);

| Atributo | Descripción | Tipo | Requerido | Predeterminado | --- | --- | --- | --- | --- | | $default | Valor por defecto. Se devolverá NULL o el valor por defecto para los valores de los campos que no coincidan con el tipo de dato indicado. | mixed | No | null |

# Return (mixed|null) ? valor, null o valor de retorno personalizado

- Saneamiento de datos y retornar como decimal:

asFloat($default);

| Atributo | Descripción | Tipo | Requerido | Predeterminado | --- | --- | --- | --- | --- | | $default | Valor por defecto. Se devolverá NULL o el valor por defecto para los valores de los campos que no coincidan con el tipo de dato indicado. | mixed | No | null |

# Return (mixed|null) ? valor, null o valor de retorno personalizado

- Saneamiento de datos y retornar como booleano:

asBoolean($default);

| Atributo | Descripción | Tipo | Requerido | Predeterminado | --- | --- | --- | --- | --- | | $default | Valor por defecto. Se devolverá NULL o el valor por defecto para los valores de los campos que no coincidan con el tipo de dato indicado. | mixed | No | null |

# Return (mixed|null) ? valor, null o valor de retorno personalizado

- Saneamiento de datos y retornar como dirección IP:

asIp($default);

| Atributo | Descripción | Tipo | Requerido | Predeterminado | --- | --- | --- | --- | --- | | $default | Valor por defecto. Se devolverá NULL o el valor por defecto para los valores de los campos que no coincidan con el tipo de dato indicado. | mixed | No | null |

# Return (mixed|null) ? valor, null o valor de retorno personalizado

- Saneamiento de datos y retornar como URL:

asUrl($default);

| Atributo | Descripción | Tipo | Requerido | Predeterminado | --- | --- | --- | --- | --- | | $default | Valor por defecto. Se devolverá NULL o el valor por defecto para los valores de los campos que no coincidan con el tipo de dato indicado. | mixed | No | null |

# Return (mixed|null) ? valor, null o valor de retorno personalizado

- Saneamiento de datos y retornar como email:

asEmail($default);

| Atributo | Descripción | Tipo | Requerido | Predeterminado | --- | --- | --- | --- | --- | | $default | Valor por defecto. Se devolverá NULL o el valor por defecto para los valores de los campos que no coincidan con el tipo de dato indicado. | mixed | No | null |

# Return (mixed|null) ? valor, null o valor de retorno personalizado

Cómo empezar

Para utilizar esta biblioteca con Composer:

require __DIR__ . '/vendor/autoload.php';

use Josantonius\Request\Request;

Si la instalaste manualmente, utiliza:

require_once __DIR__ . '/Request.php';
require_once __DIR__ . '/Validate.php';

use Josantonius\Request\Request;
use Josantonius\Validate\Validate;

Uso

Para los ejemplos se simulará que se reciben los siguientes datos en la solicitud:

Ejemplo de datos recibidos en la solicitud:

'user_name' => 'John'
'user_surname' => 'Doe'
'user_age' => 35
'user_rating' => 8.5
'user_ip' => '89.58.54.188'
'user_website' => 'http://www.site.com/'
'user_email' => 'john@site.com'
'user_address' => [
  'street' => 'unknown'
  'locality' => 'Seville'
  'country' => 'Spain'
]
'is_active' => true

Ejemplo de uso para esta biblioteca:

- Comprobar si es una petición GET:

Request::isGet(); // true or false

- Comprobar si es una petición POST:

Request::isPost(); // true or false

- Comprobar si es una petición PUT:

Request::isPut(); // true or false

- Comprobar si es una petición DELETE:

Request::isDelete(); // true or false

- Acceder a los parámetros de la solicitud:

$_GET = Request::input('GET');

$_POST = Request::input('POST');

$_PUT = Request::input('PUT');

$_DELETE = Request::input('DELETE');

Devuelve una función anónima que devolverá el objeto Request cuando esta sea llamada.

- Array:

- Sanear y devolver los datos como array:

$array = $_GET()->asArray();

$array = $_POST()->asArray();

$array = $_PUT()->asArray();

$array = $_DELETE()->asArray();

var_dump($array);

/*
array(9) {
  ["user_name"]=>
  string(4) "John"
  ["user_surname"]=>
  string(3) "Doe"
  ["user_age"]=>
  int(35)
  ["user_rating"]=>
  float(8.5)
  ["user_ip"]=>
  string(12) "89.58.54.188"
  ["user_website"]=>
  string(20) "http://www.site.com/"
  ["user_email"]=>
  string(13) "john@site.com"
  ["user_address"]=>
  array(3) {
    ["street"]=>
    string(7) "unknown"
    ["locality"]=>
    string(7) "Seville"
    ["country"]=>
    string(5) "Spain"
  }
  ["is_active"]=>
  bool(true)
}
*/

• Ejemplo de datos recibidos en la solicitud

- Sanear, filtrar cada valor por el tipo de dato indicado y devolver como array:

$filters = [
    'user_name' => 'string',
    'user_age' => 'string',
    'is_online' => 'boolean'
];

$array = $_GET()->asArray($filters);

$array = $_POST()->asArray($filters);

$array = $_PUT()->asArray($filters);

$array = $_DELETE()->asArray($filters);

var_dump($array['user_name']); // string(4) "John"

var_dump($array['user_age']); // string(2) "35" (aunque se recibe un número entero, se devuelve como una cadena de texto)

var_dump($array['user_age']); // NULL (no existe, se devuelve el valor por defecto)

• Ejemplo de datos recibidos en la solicitud

- Sanear todos los datos recibidos como array, filtrar cada valor según el tipo de datos y especificar un valor para cada tecla cuando sea incorrecto:

$filters = [
    'user_rating' => 'float',
    'is_active' => 'boolean',
    'is_online' => 'boolean'
];

$array = $_GET()->asArray($filters, '');

$array = $_POST()->asArray($filters, '');

$array = $_PUT()->asArray($filters, '');

$array = $_DELETE()->asArray($filters, '');

var_dump($array['user_rating']); // float(8.5)

var_dump($array['is_active']); // bool(true)

var_dump($array['is_online']); // string(0) "" (no existe, se devuelve el valor por defecto)

• Ejemplo de datos recibidos en la solicitud

- Objeto:

- Sanear y devolver los datos como objeto:

$object = $_GET()->asObject();

$object = $_POST()->asObject();

$object = $_PUT()->asObject();

$object = $_DELETE()->asObject();

var_dump($object);

/*
object(stdClass)#1 (9) {
  ["user_name"]=>
  string(4) "John"
  ["user_surname"]=>
  string(3) "Doe"
  ["user_age"]=>
  int(35)
  ["user_rating"]=>
  float(8.5)
  ["user_ip"]=>
  string(12) "89.58.54.188"
  ["user_website"]=>
  string(20) "http://www.site.com/"
  ["user_email"]=>
  string(13) "john@site.com"
  ["user_address"]=>
  object(stdClass)#2 (3) {
    ["street"]=>
    string(7) "unknown"
    ["locality"]=>
    string(7) "Seville"
    ["country"]=>
    string(5) "Spain"
  }
  ["is_active"]=>
  bool(true)
}
*/

• Ejemplo de datos recibidos en la solicitud

- Sanear, filtrar cada valor por el tipo de dato indicado y devolver como objeto:

$filters = [
    'user_name' => 'string',
    'user_age' => 'integer',
    'is_online' => 'boolean'
];

$object = $_GET()->asObject($filters);

$object = $_POST()->asObject($filters);

$object = $_PUT()->asObject($filters);

$object = $_DELETE()->asObject($filters);

var_dump($object->user_name); // string(4) "John"

var_dump($object->user_age); // int(35)

var_dump($object->user_age); // NULL (no existe, se devuelve el valor por defecto)

• Ejemplo de datos recibidos en la solicitud

- Sanear todos los datos recibidos como objeto, filtrar cada valor según el tipo de dato y especificar un valor para cada campo cuando sea incorrecto:

$filters = [
    'user_rating' => 'float',
    'user_surname' => 'boolean',
    'is_online' => 'boolean',
    'is_member' => 'boolean'
];

$object = $_GET()->asObject($filters, false);

$object = $_POST()->asObject($filters, false);

$object = $_PUT()->asObject($filters, false);

$object = $_DELETE()->asObject($filters, false);

var_dump($object->user_rating); // float(8.5)

var_dump($object->user_surname); // string(3) "Doe"

var_dump($object->is_online); // bool(false) (no existe, se devuelve el valor por defecto)

var_dump($object->is_member); // bool(false) (no existe, se devuelve el valor por defecto)

• Ejemplo de datos recibidos en la solicitud

- JSON:

- Sanear y devolver los datos como JSON:

$json = $_GET()->asJson();

$json = $_POST()->asJson();

$json = $_PUT()->asJson();

$json = $_DELETE()->asJson();

var_dump($json);

/*
string(260) "{"user_name":"John","user_surname":"Doe","user_age":35,"user_rating":8.5,"user_ip":"89.58.54.188","user_website":"http:\/\/www.site.com\/","user_email":"john@site.com","user_address":{"street":"unknown","locality":"Seville","country":"Spain"},"is_active":true}"
*/

• Ejemplo de datos recibidos en la solicitud

- Obtener el valor de un campo específico, sanear los datos y devolverlos como JSON:

$json = $_GET('user_address')->asJson();

var_dump($json); // string(59) "{"street":"unknown","locality":"Seville","country":"Spain"}"

$json = $_POST('user_name')->asJson();

var_dump($json); // string(6) ""John""

$json = $_PUT('is_online')->asJson();

var_dump($json); // NULL (no existe, se devuelve el valor por defecto)

$json = $_DELETE('user_address')->asJson([]);

var_dump($json); // string(2) "[]" (no existe, se devuelve el valor por defecto)

• Ejemplo de datos recibidos en la solicitud

- String:

- Obtener el valor de un campo específico, sanear los datos y devolverlos como string:

$string = $_GET('user_age')->asString();

var_dump($string); // string(2) "35" (aunque se recibe un número entero, se devuelve como una cadena de texto)

$string = $_POST('user_name')->asString();

var_dump($string); // string(4) "John"

$string = $_PUT('user_address')->asString();

var_dump($string); // NULL (es un array, se devuelve el valor por defecto)

$string = $_DELETE('user_address')->asString('unknown');

var_dump($string); // string(7) "unknown" (es un array, se devuelve el valor por defecto)

• Ejemplo de datos recibidos en la solicitud

- Integer:

- Obtener el valor de un campo específico, sanear los datos y devolverlos como número entero:

$integer = $_GET('user_age')->asInteger();

var_dump($integer); // int(35)

$integer = $_PUT('user_rating')->asInteger();

var_dump($integer); // NULL (es un número decimal, se devuelve el valor por defecto)

$integer = $_DELETE('user_rating')->asInteger(5);

var_dump($integer); // int(5) (es un número decimal, se devuelve el valor por defecto)

• Ejemplo de datos recibidos en la solicitud

- Float:

- Obtener el valor de un campo específico, sanear los datos y devolverlos como número decimal:

$float = $_GET('user_age')->asFloat();

var_dump($float); // float(35) (aunque se recibe un número entero, se devuelve como un número decimal)

$float = $_POST('user_rating')->asFloat();

var_dump($float); // float(8.5)

$float = $_PUT('user_name')->asFloat();

var_dump($float); // NULL (es una cadena de texto, se devuelve el valor por defecto)

$float = $_DELETE('user_name')->asFloat(5.5);

var_dump($float); // float(5.5) (es una cadena de texto, se devuelve el valor por defecto)

• Ejemplo de datos recibidos en la solicitud

- Boolean:

- Obtener el valor de un campo específico, sanear los datos y devolverlos como booleanos:

$_GET['is_active'] = true;

$boolean = $_GET('is_active')->asBoolean();

var_dump($boolean); // bool(true)

$_GET['is_active'] = 'true';

$boolean = $_GET('is_active')->asBoolean();

var_dump($boolean); // bool(true)

$_POST['is_active'] = '1';

$boolean = $_POST('is_active')->asBoolean();

var_dump($boolean); // bool(true)

$_POST['is_active'] = 1;

$boolean = $_POST('is_active')->asBoolean();

var_dump($boolean); // bool(true)

$_GET['is_active'] = false;

$boolean = $_GET('is_active')->asBoolean();

var_dump($boolean); // bool(false)

$_GET['is_active'] = 'false';

$boolean = $_GET('is_active')->asBoolean();

var_dump($boolean); // bool(false)

$_POST['is_active'] = '0';

$boolean = $_POST('is_active')->asBoolean();

var_dump($boolean); // bool(false)

$_POST['is_active'] = 0;

$boolean = $_POST('is_active')->asBoolean();

var_dump($boolean); // bool(false)

$boolean = $_PUT('user_name')->asBoolean();

var_dump($boolean); // NULL (es una cadena de texto, se devuelve el valor por defecto)

$boolean = $_DELETE('is_online')->asBoolean(false);

var_dump($boolean); // bool(false) (no existe, se devuelve el valor por defecto)

- IP:

- Obtener el valor de un campo específico, sanear los datos y devolverlos como dirección IP:

$ip = $_GET('user_ip')->asIp();

var_dump($ip); // string(12) "89.58.54.188"

$ip = $_POST('user_rating')->asIp();

var_dump($ip); // NULL (no es una IP, se devuelve el valor por defecto)

$ip = $_DELETE('user_name')->asIp("87.32.48.164");

var_dump($ip); // string(12) "87.32.48.164" (no es una IP, se devuelve el valor por defecto)

• Ejemplo de datos recibidos en la solicitud

- URL:

- Obtener el valor de un campo específico, sanear los datos y devolverlos como URL:

$url = $_GET('user_website')->asUrl();

var_dump($url); // string(20) "http://www.site.com/"

$url = $_POST('user_rating')->asUrl();

var_dump($url); // NULL (no es una URL, se devuelve el valor por defecto)

$url = $_DELETE('user_name')->asUrl("http://www.site.com/");

var_dump($url); // string(20) "http://www.site.com/" (no es una URL, se devuelve el valor por defecto)

• Ejemplo de datos recibidos en la solicitud

- email:

- Obtener el valor de un campo específico, sanear los datos y devolverlos como email:

$email = $_GET('user_website')->asEmail();

var_dump($email); // string(13) "john@site.com"

$email = $_POST('user_rating')->asEmail();

var_dump($email); // NULL (no es un correo electrónico, se devuelve el valor por defecto)

$email = $_DELETE('user_name')->asEmail("john@site.com");

var_dump($email); // string(13) "john@site.com" (no es un correo electrónico, se devuelve el valor por defecto)

• Ejemplo de datos recibidos en la solicitud

Tests

Para ejecutar las pruebas necesitarás Composer y seguir los siguientes pasos:

$ git clone https://github.com/Josantonius/php-request.git

$ cd php-request

$ composer install

Ejecutar pruebas unitarias con PHPUnit:

$ gnome-terminal -e 'php -S localhost:8000 -t tests/'

$ composer phpunit

Ejecutar pruebas de estándares de código PSR2 con PHPCS:

$ composer phpcs

Ejecutar pruebas con PHP Mess Detector para detectar inconsistencias en el estilo de codificación:

$ composer phpmd

Ejecutar todas las pruebas anteriores:

$ composer tests

? Tareas pendientes

• [ ] Añadir nueva funcionalidad.
• [ ] Mejorar pruebas.
• [ ] Mejorar documentación.
• [ ] Refactorizar código para las reglas de estilo de código deshabilitadas. Ver phpmd.xml y .php_cs.dist.
• [ ] Detener la exclusión de archivos de prueba en .php_cs.dist.
• [ ] Cambiar el método `getParsedInput` a público, crear tests y documentarlo.
• [ ] Cambiar el método `getContentType` a público, crear tests y documentarlo.
• [ ] Cambiar el método `parseRaw` a público, crear tests y documentarlo.

Contribuir

Si deseas colaborar, puedes echar un vistazo a la lista de issues o tareas pendientes.

Pull requests

• Fork and clone.
• Ejecuta el comando `composer install` para instalar dependencias. Esto también instalará las dependencias de desarrollo.
• Ejecuta el comando `composer fix` para estandarizar el código.
• Ejecuta las pruebas.
• Crea una nueva rama (branch), commit, push y envíame un pull request.

¡Gracias a quienes ya habéis contribuido a este proyecto!

<img alt="peter279k" src="https://avatars2.githubusercontent.com/u/9021747?v=4&s=117" height="117" width="117">|<img alt="Mahdrentys" src="https://avatars2.githubusercontent.com/u/40216477?v=4&s=117" height="117" width="117">| :---:|:---:| peter279k| Mahdrentys|

Repositorio

La estructura de archivos de este repositorio se creó con PHP-Skeleton.

Licencia

Este proyecto está licenciado bajo licencia MIT. Consulta el archivo LICENSE para más información.

Copyright

2017 - 2018 Josantonius, josantonius.com

Si te ha resultado útil, házmelo saber :wink:

Puedes contactarme en Twitter o a través de mi correo electrónico.