Filter

Al igual que su homónima de PHP, filtra el valor de diferentes variables, a partir de la definición de reglas.

 

Ejemplos iniciales

$email = Filter::input(GET, 'email'); 
// -> '...'

$data = Filter::all(POST, [
	'username' => 'text|max:48|required',
	'password' => 'text|required'
]);
// -> ['username' => '...', 'password' => '...'];

En el primer ejemplo, del arreglo global $_GET, se filtra y devuelve la clave email.

En el segundo ejemplo, del arreglo global $_POST, se filtra y devuelven las claves username y password, en este caso, va a devolver un array con dichas claves.

Los métodos

Filter::input

Filtra el valor de una variable global, similar a filter_input.

public static Filter::( int $type, string $var_name, string|array $rules = '' ): mixed

type

Pueden ser las constantes INPUT_GET O INPUT_POST, o sus alias GET y POST.

var_name

El nombre de la variable que se desea recuperar.

rules

Las reglas con las que se filtrará la variable. Puede ser un arreglo o una cadena con todas las reglas separadas por una barra vertical.

 

Filter::var

Filtra el valor de una variable, similar a filter_var.

public static Filter::(mixed $variable, string|array $rules = ''): mixed

variable

La variable a filtrar.

rules

Las reglas con las que se filtrará la variable. Puede ser un arreglo o una cadena con todas las reglas separadas por una barra vertical.

 

filter::all

Filtra un arreglo o una variable global, similar a filter_input_array y filter_var_array, aunque no es exáctamente igual. Los cambios están en el tercer parámetro y en los valores devueltos.

public static Filter::all ( array|int $data, array $definition, bool $iterate = false ): ?array

data

Si el valor es una de las constantes GET o POST, las variables se buscarán en las variables globales. De lo contrario se viltrará el arreglo de variables.

rules

Un arreglo que contiene en las claves el nombre de la variable, y en el valor, las reglas de filtrado.

iterate

Si es false, devuelve un arreglo igual que filter_input_array con el tercer parámetro activo, add_empty = true.

Si es true, devuelve un arreglo multidimensional con filas que contienen los pares key => value que han sido definidos o null en el caso de no hallar una fila para devolver.

 

Las reglas

Las reglas consisten en un filtro y modificadores. Los filtros dan los tipos de datos que deseamos obtener y los modificadores mejoran las espectativas.

La librería pretende que los valores devueltos sean siempre utilizables, sobre todo, para ser guardados en una base de datos. Por eso, si la regla falla, tendremos siempre un valor aceptable.

 

Filtros

int

Devuelve un entero.

id

Es un alias de: int|min:0.

float

Devuelve un número con punto flotante.

text

Devuelve una cadena a la que se le aplica el filtro FILTER_FLAG_STRIP_LOW y las funciones htmlspecialchars y trim.

multiline

Devuelve una cadena a la que se le aplica el filtro FILTER_SANITIZE_SPECIAL_CHARS y las funciones nl2br y trim. El resultado es un valor seguro obtenido de un textarea.

email

Valida un email a través del filtro FILTER_VALIDATE_EMAIL.

url

Valida una url a través del filtro FILTER_VALIDATE_URL. Como valor, acepta una lista blanca de protocolos, por ejemplo: 'url:http,https'.

color

Valida un color. Como valor, acepta una lista de tipos de notaciones, por ejemplo: 'color:hex'.

Actualmente, los tipos de notaciones válidos son:

1. hex hexadecimal de 6 dígitos;
2. hex+ hexadecimal con 3, 4, 6 u 8 dígitos;
3. named colores nombrados de css;
4. named+ a los colores nombrados se le agregan las palabras claves: currencolor y transparent.

slug

Sanitiza una cadena para ser utilizada como "slug" en una url.

bool

Valida una valor boolean utilizando el filtro FILTER_VALIDATE_BOOLEAN.

Puede devolver un boolean o cualquier otro valor pasado en el filtro. Por ejemplo: bool:no/yes devolverá una cadena con cualquiera de estos valores. Otro ejemplo muy útil puede ser bool:0/1.

date, datetime, time, month

Validan fechas y horas reales. En caso de que falle, devolverá el valor null, que es un valor aceptable para los campos date de una base de datos.

file, files, image, images, archive

Cargan uno o varios archivos. Devuelven SIEMPRE un objeto del tipo UploadedFileManager.

Pueden aceptar como valor, las extensiones permitidas. Por ejemplo: 'file:doc,docx'.

callback

Utiliza el filtro FILTER_CALLBACK.

enum

A partir de una cadena, intenta devolver un enum válido. El filtro requiere que se le pase como valor el enum que se desea utilizar, por ejemplo:

// array
$rule = ["enum" => Junco\Users\Enum\UserStatus::class];
// string
$rule = "enum:users.user_status";

Si se utiliza el modificador default sin un valor, buscará el valor por defecto en un método estático de igual nombre del Enum, por ejemplo:

$rule = "enum:users.user_status|default";

enum UserStatus {
    case active;

    static function default(): self
    {
        return self::active;
    }
}

json

Valida una cadena json. Alternativamente, puede decodificar la cadena como un objeto o un array asociativo. Algunos ejemlos:

$rule = 'json:decode'; // json_decode($value)
$rule = 'json:decode_a'; // json_decode($value, true)
$rule = 'json:decode_a,2'; // json_decode($value, true, 2)

none

En caso de no colocar un filtro, se utilizará éste por defecto. Básicamente, no hace nada y equivale a FILTER_DEFAULT.

 

Modificadores

min, max

En los números, modifica los valores por defecto.

En los textos, verifica el tamaño de las cadenas.

En las fechas, si no se le coloca una fecha, tomará la fecha actual.

En los archivos, verifica su tamaño.

default

Modifica los valores por defecto del sistema. Cualquier nuevo valor, será parseado al tipo de filtro.

array

Devolverá un array. En caso de fallo, devolverá un array vacío. Si se le pasa el parámetro :first, tomará la entrada como un array, pero devolverá el primer valor del mismo.

in

Devolverá solo aquellos valores pasados como parámetros o false en caso de fallo.

or_use

Utilizará el valor de otra clave si su valor se evalúa como falso. En todos los casos, se utilizarón los valores de entrada.

$value = Filter::all([
    'title' => '',
    'slug' => 'slug|or_use:title'
]);

En el ejemplo, si no se ingresa un valor de slug, se utilizará el valor de title.

only_if

Devolverá la clave y su valor sólo si la clave pasada como parámetro tiene un valor que se representa como verdadero.

$value = Filter::all([
    'accept' => 'bool',
    'item_id' => 'id|only_if:accept|required'
]);

En el ejemplo, solo si se acepta, deberá solicitarse un item_id.

only_if_not

Igual que only_if, pero devolverá la clave y su valor, solo si la clave pasada como parámetro tiene un valor que se representa como falso.

required

La clave deberá tener un valor true o lanzará una excepción. En caso de ser un array, también comprobará que todos sus valores sean true.

Si el modificador tiene un valor "abort", en lugar de una excepción lanzará un error del sistema.

 

Cuadro de filtros y modificadores