PHP Classes

File: README-ES.md

Recommend this page to a friend!
  Classes of Josantonius   PHP HTTP Request Class   README-ES.md   Download  
File: README-ES.md
Role: Documentation
Content typex: text/markdown
Description: Documentation
Class: PHP HTTP Request Class
Check the HTTP request and extract its parameters
Author: By
Last change: 2.0.0 - Improved version only compatible with PHP > 7.0
2.0.0 - Improved version only compatible with PHP > 7.0
documentation only compatible for versions 1.x
updating collaborators
Date: 6 years ago
Size: 24,542 bytes
 

Contents

Class file image Download

PHP Request library

Latest Stable Version Latest Unstable Version License Codacy Badge Total Downloads Travis PSR2 PSR4 CodeCov

English version

Biblioteca PHP para manejo de peticiones.

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' => '[email protected]'
'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) "[email protected]"
  ["user_address"]=>
  array(3) {
    ["street"]=>
    string(7) "unknown"
    ["locality"]=>
    string(7) "Seville"
    ["country"]=>
    string(5) "Spain"
  }
  ["is_active"]=>
  bool(true)
}
*/

- 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)

- 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)

- 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) "[email protected]"
  ["user_address"]=>
  object(stdClass)#2 (3) {
    ["street"]=>
    string(7) "unknown"
    ["locality"]=>
    string(7) "Seville"
    ["country"]=>
    string(5) "Spain"
  }
  ["is_active"]=>
  bool(true)
}
*/

- 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)

- 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)

- 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":"[email protected]","user_address":{"street":"unknown","locality":"Seville","country":"Spain"},"is_active":true}"
*/

- 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)

- 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)

- 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)

- 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)

- 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)

- 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)

- 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) "[email protected]"


$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("[email protected]");

var_dump($email); // string(13) "[email protected]" (no es un correo electrónico, se devuelve el valor por defecto)

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.