Funciones auxiliares

• Introducción
• Métodos disponibles
• Otras utilidades
  • Benchmarking
  • Fechas
  • Lotería
  • Pipeline
  • Sleep

#Introducción

Laravel incluye una variedad de funciones globales de ayuda en PHP. Muchas de estas funciones son utilizadas por el propio framework; sin embargo, usted puede usarlas en sus propias aplicaciones si las encuentra convenientes.

#Métodos disponibles

#Arrays y objetos

#Números

#Rutas

#URLs

#Misceláneos

#Arrays y objetos

#Arr::accessible() {.collection-method .first-collection-method}

El método Arr::accessible determina si el valor dado es accesible como un array:

use Illuminate\Support\Arr;
use Illuminate\Support\Collection;

$isAccessible = Arr::accessible(['a' => 1, 'b' => 2]);

// true

$isAccessible = Arr::accessible(new Collection);

// true

$isAccessible = Arr::accessible('abc');

// false

$isAccessible = Arr::accessible(new stdClass);

// false

#Arr::add() {.collection-method}

El método Arr::add añade un par clave / valor a un array si la clave dada no existe ya en el array o está establecida en null:

use Illuminate\Support\Arr;

$array = Arr::add(['name' => 'Desk'], 'price', 100);

// ['name' => 'Desk', 'price' => 100]

$array = Arr::add(['name' => 'Desk', 'price' => null], 'price', 100);

// ['name' => 'Desk', 'price' => 100]

#Arr::collapse() {.collection-method}

El método Arr::collapse aplana un array de arrays en un solo array:

use Illuminate\Support\Arr;

$array = Arr::collapse([[1, 2, 3], [4, 5, 6], [7, 8, 9]]);

// [1, 2, 3, 4, 5, 6, 7, 8, 9]

#Arr::crossJoin() {.collection-method}

El método Arr::crossJoin realiza un producto cartesiano de los arrays dados, devolviendo todas las permutaciones posibles:

use Illuminate\Support\Arr;

$matrix = Arr::crossJoin([1, 2], ['a', 'b']);

/*
    [
        [1, 'a'],
        [1, 'b'],
        [2, 'a'],
        [2, 'b'],
    ]
*/

$matrix = Arr::crossJoin([1, 2], ['a', 'b'], ['I', 'II']);

/*
    [
        [1, 'a', 'I'],
        [1, 'a', 'II'],
        [1, 'b', 'I'],
        [1, 'b', 'II'],
        [2, 'a', 'I'],
        [2, 'a', 'II'],
        [2, 'b', 'I'],
        [2, 'b', 'II'],
    ]
*/

#Arr::divide() {.collection-method}

El método Arr::divide devuelve dos arrays: uno con las claves y otro con los valores del array dado:

use Illuminate\Support\Arr;

[$keys, $values] = Arr::divide(['name' => 'Desk']);

// $keys: ['name']

// $values: ['Desk']

#Arr::dot() {.collection-method}

El método Arr::dot aplana un array multidimensional en un array de un solo nivel que usa notación "dot" para indicar la profundidad:

use Illuminate\Support\Arr;

$array = ['products' => ['desk' => ['price' => 100]]];

$flattened = Arr::dot($array);

// ['products.desk.price' => 100]

#Arr::except() {.collection-method}

El método Arr::except elimina los pares clave / valor dados de un array:

use Illuminate\Support\Arr;

$array = ['name' => 'Desk', 'price' => 100];

$filtered = Arr::except($array, ['price']);

// ['name' => 'Desk']

#Arr::exists() {.collection-method}

El método Arr::exists verifica que la clave dada exista en el array proporcionado:

use Illuminate\Support\Arr;

$array = ['name' => 'John Doe', 'age' => 17];

$exists = Arr::exists($array, 'name');

// true

$exists = Arr::exists($array, 'salary');

// false

#Arr::first() {.collection-method}

El método Arr::first devuelve el primer elemento de un array que pasa una prueba dada:

use Illuminate\Support\Arr;

$array = [100, 200, 300];

$first = Arr::first($array, function (int $value, int $key) {
    return $value >= 150;
});

// 200

También se puede pasar un valor por defecto como tercer parámetro al método. Este valor será devuelto si ningún valor pasa la prueba:

use Illuminate\Support\Arr;

$first = Arr::first($array, $callback, $default);

#Arr::flatten() {.collection-method}

El método Arr::flatten aplana un array multidimensional en un array de un solo nivel:

use Illuminate\Support\Arr;

$array = ['name' => 'Joe', 'languages' => ['PHP', 'Ruby']];

$flattened = Arr::flatten($array);

// ['Joe', 'PHP', 'Ruby']

#Arr::forget() {.collection-method}

El método Arr::forget elimina un par clave / valor dado de un array profundamente anidado usando notación "dot":

use Illuminate\Support\Arr;

$array = ['products' => ['desk' => ['price' => 100]]];

Arr::forget($array, 'products.desk');

// ['products' => []]

#Arr::get() {.collection-method}

El método Arr::get recupera un valor de un array profundamente anidado usando notación "dot":

use Illuminate\Support\Arr;

$array = ['products' => ['desk' => ['price' => 100]]];

$price = Arr::get($array, 'products.desk.price');

// 100

El método Arr::get también acepta un valor por defecto, que será devuelto si la clave especificada no está presente en el array:

use Illuminate\Support\Arr;

$discount = Arr::get($array, 'products.desk.discount', 0);

// 0

#Arr::has() {.collection-method}

El método Arr::has verifica si un ítem o ítems dados existen en un array usando notación "dot":

use Illuminate\Support\Arr;

$array = ['product' => ['name' => 'Desk', 'price' => 100]];

$contains = Arr::has($array, 'product.name');

// true

$contains = Arr::has($array, ['product.price', 'product.discount']);

// false

#Arr::hasAny() {.collection-method}

El método Arr::hasAny verifica si algún ítem de un conjunto dado existe en un array usando notación "dot":

use Illuminate\Support\Arr;

$array = ['product' => ['name' => 'Desk', 'price' => 100]];

$contains = Arr::hasAny($array, 'product.name');

// true

$contains = Arr::hasAny($array, ['product.name', 'product.discount']);

// true

$contains = Arr::hasAny($array, ['category', 'product.discount']);

// false

#Arr::isAssoc() {.collection-method}

El método Arr::isAssoc devuelve true si el array dado es un array asociativo. Un array se considera "asociativo" si no tiene claves numéricas secuenciales comenzando desde cero:

use Illuminate\Support\Arr;

$isAssoc = Arr::isAssoc(['product' => ['name' => 'Desk', 'price' => 100]]);

// true

$isAssoc = Arr::isAssoc([1, 2, 3]);

// false

#Arr::isList() {.collection-method}

El método Arr::isList devuelve true si las claves del array dado son enteros secuenciales comenzando desde cero:

use Illuminate\Support\Arr;

$isList = Arr::isList(['foo', 'bar', 'baz']);

// true

$isList = Arr::isList(['product' => ['name' => 'Desk', 'price' => 100]]);

// false

#Arr::join() {.collection-method}

El método Arr::join une los elementos de un array con una cadena. Usando el segundo argumento de este método, también puede especificar la cadena de unión para el último elemento del array:

use Illuminate\Support\Arr;

$array = ['Tailwind', 'Alpine', 'Laravel', 'Livewire'];

$joined = Arr::join($array, ', ');

// Tailwind, Alpine, Laravel, Livewire

$joined = Arr::join($array, ', ', ' and ');

// Tailwind, Alpine, Laravel and Livewire

#Arr::keyBy() {.collection-method}

El método Arr::keyBy usa la clave dada para indexar el array. Si varios ítems tienen la misma clave, solo el último aparecerá en el nuevo array:

use Illuminate\Support\Arr;

$array = [
    ['product_id' => 'prod-100', 'name' => 'Desk'],
    ['product_id' => 'prod-200', 'name' => 'Chair'],
];

$keyed = Arr::keyBy($array, 'product_id');

/*
    [
        'prod-100' => ['product_id' => 'prod-100', 'name' => 'Desk'],
        'prod-200' => ['product_id' => 'prod-200', 'name' => 'Chair'],
    ]
*/

#Arr::last() {.collection-method}

El método Arr::last devuelve el último elemento de un array que pasa una prueba dada:

use Illuminate\Support\Arr;

$array = [100, 200, 300, 110];

$last = Arr::last($array, function (int $value, int $key) {
    return $value >= 150;
});

// 300

Se puede pasar un valor por defecto como tercer argumento al método. Este valor será devuelto si ningún valor pasa la prueba:

use Illuminate\Support\Arr;

$last = Arr::last($array, $callback, $default);

#Arr::map() {.collection-method}

El método Arr::map itera sobre el array y pasa cada valor y clave al callback dado. El valor del array es reemplazado por el valor devuelto por el callback:

use Illuminate\Support\Arr;

$array = ['first' => 'james', 'last' => 'kirk'];

$mapped = Arr::map($array, function (string $value, string $key) {
    return ucfirst($value);
});

// ['first' => 'James', 'last' => 'Kirk']

#Arr::mapWithKeys() {.collection-method}

El método Arr::mapWithKeys itera sobre el array y pasa cada valor al callback dado. El callback debe devolver un array asociativo con un solo par clave / valor:

use Illuminate\Support\Arr;

$array = [
    [
        'name' => 'John',
        'department' => 'Sales',
        'email' => 'john@example.com',
    ],
    [
        'name' => 'Jane',
        'department' => 'Marketing',
        'email' => 'jane@example.com',
    ]
];

$mapped = Arr::mapWithKeys($array, function (array $item, int $key) {
    return [$item['email'] => $item['name']];
});

/*
    [
        'john@example.com' => 'John',
        'jane@example.com' => 'Jane',
    ]
*/

#Arr::only() {.collection-method}

El método Arr::only devuelve solo los pares clave / valor especificados del array dado:

use Illuminate\Support\Arr;

$array = ['name' => 'Desk', 'price' => 100, 'orders' => 10];

$slice = Arr::only($array, ['name', 'price']);

// ['name' => 'Desk', 'price' => 100]

#Arr::pluck() {.collection-method}

El método Arr::pluck recupera todos los valores para una clave dada de un array:

use Illuminate\Support\Arr;

$array = [
    ['developer' => ['id' => 1, 'name' => 'Taylor']],
    ['developer' => ['id' => 2, 'name' => 'Abigail']],
];

$names = Arr::pluck($array, 'developer.name');

// ['Taylor', 'Abigail']

También puede especificar cómo desea que se indexe la lista resultante:

use Illuminate\Support\Arr;

$names = Arr::pluck($array, 'developer.name', 'developer.id');

// [1 => 'Taylor', 2 => 'Abigail']

#Arr::prepend() {.collection-method}

El método Arr::prepend añade un elemento al inicio de un array:

use Illuminate\Support\Arr;

$array = ['one', 'two', 'three', 'four'];

$array = Arr::prepend($array, 'zero');

// ['zero', 'one', 'two', 'three', 'four']

Si es necesario, puede especificar la clave que debe usarse para el valor:

use Illuminate\Support\Arr;

$array = ['price' => 100];

$array = Arr::prepend($array, 'Desk', 'name');

// ['name' => 'Desk', 'price' => 100]

#Arr::prependKeysWith() {.collection-method}

El método Arr::prependKeysWith antepone a todos los nombres de clave de un array asociativo el prefijo dado:

use Illuminate\Support\Arr;

$array = [
    'name' => 'Desk',
    'price' => 100,
];

$keyed = Arr::prependKeysWith($array, 'product.');

/*
    [
        'product.name' => 'Desk',
        'product.price' => 100,
    ]
*/

#Arr::pull() {.collection-method}

El método Arr::pull devuelve y elimina un par clave / valor de un array:

use Illuminate\Support\Arr;

$array = ['name' => 'Desk', 'price' => 100];

$name = Arr::pull($array, 'name');

// $name: Desk

// $array: ['price' => 100]

Se puede pasar un valor por defecto como tercer argumento al método. Este valor será devuelto si la clave no existe:

use Illuminate\Support\Arr;

$value = Arr::pull($array, $key, $default);

#Arr::query() {.collection-method}

El método Arr::query convierte el array en una cadena de consulta:

use Illuminate\Support\Arr;

$array = [
    'name' => 'Taylor',
    'order' => [
        'column' => 'created_at',
        'direction' => 'desc'
    ]
];

Arr::query($array);

// name=Taylor&order[column]=created_at&order[direction]=desc

#Arr::random() {.collection-method}

El método Arr::random devuelve un valor aleatorio de un array:

use Illuminate\Support\Arr;

$array = [1, 2, 3, 4, 5];

$random = Arr::random($array);

// 4 - (obtenido aleatoriamente)

También puede especificar el número de ítems a devolver como segundo argumento opcional. Tenga en cuenta que proporcionar este argumento devolverá un array incluso si solo se desea un ítem:

use Illuminate\Support\Arr;

$items = Arr::random($array, 2);

// [2, 5] - (obtenido aleatoriamente)

#Arr::set() {.collection-method}

El método Arr::set establece un valor dentro de un array profundamente anidado usando notación "dot":

use Illuminate\Support\Arr;

$array = ['products' => ['desk' => ['price' => 100]]];

Arr::set($array, 'products.desk.price', 200);

// ['products' => ['desk' => ['price' => 200]]]

#Arr::shuffle() {.collection-method}

El método Arr::shuffle mezcla aleatoriamente los ítems en el array:

use Illuminate\Support\Arr;

$array = Arr::shuffle([1, 2, 3, 4, 5]);

// [3, 2, 5, 1, 4] - (generado aleatoriamente)

#Arr::sort() {.collection-method}

El método Arr::sort ordena un array por sus valores:

use Illuminate\Support\Arr;

$array = ['Desk', 'Table', 'Chair'];

$sorted = Arr::sort($array);

// ['Chair', 'Desk', 'Table']

También puede ordenar el array por los resultados de un closure dado:

use Illuminate\Support\Arr;

$array = [
    ['name' => 'Desk'],
    ['name' => 'Table'],
    ['name' => 'Chair'],
];

$sorted = array_values(Arr::sort($array, function (array $value) {
    return $value['name'];
}));

/*
    [
        ['name' => 'Chair'],
        ['name' => 'Desk'],
        ['name' => 'Table'],
    ]
*/

#Arr::sortDesc() {.collection-method}

El método Arr::sortDesc ordena un array en orden descendente por sus valores:

use Illuminate\Support\Arr;

$array = ['Desk', 'Table', 'Chair'];

$sorted = Arr::sortDesc($array);

// ['Table', 'Desk', 'Chair']

También puede ordenar el array por los resultados de un closure dado:

use Illuminate\Support\Arr;

$array = [
    ['name' => 'Desk'],
    ['name' => 'Table'],
    ['name' => 'Chair'],
];

$sorted = array_values(Arr::sortDesc($array, function (array $value) {
    return $value['name'];
}));

/*
    [
        ['name' => 'Table'],
        ['name' => 'Desk'],
        ['name' => 'Chair'],
    ]
*/

#Arr::sortRecursive() {.collection-method}

El método Arr::sortRecursive ordena recursivamente un array usando la función sort para subarrays indexados numéricamente y la función ksort para subarrays asociativos:

use Illuminate\Support\Arr;

$array = [
    ['Roman', 'Taylor', 'Li'],
    ['PHP', 'Ruby', 'JavaScript'],
    ['one' => 1, 'two' => 2, 'three' => 3],
];

$sorted = Arr::sortRecursive($array);

/*
    [
        ['JavaScript', 'PHP', 'Ruby'],
        ['one' => 1, 'three' => 3, 'two' => 2],
        ['Li', 'Roman', 'Taylor'],
    ]
*/

Si desea que los resultados estén ordenados en orden descendente, puede usar el método Arr::sortRecursiveDesc.

$sorted = Arr::sortRecursiveDesc($array);

#Arr::take() {.collection-method}

El método Arr::take devuelve un nuevo array con el número especificado de ítems:

use Illuminate\Support\Arr;

$array = [0, 1, 2, 3, 4, 5];

$chunk = Arr::take($array, 3);

// [0, 1, 2]

También puede pasar un entero negativo para tomar el número especificado de ítems desde el final del array:

$array = [0, 1, 2, 3, 4, 5];

$chunk = Arr::take($array, -2);

// [4, 5]

#Arr::toCssClasses() {.collection-method}

El método Arr::toCssClasses compila condicionalmente una cadena de clases CSS. El método acepta un array de clases donde la clave del array contiene la clase o clases que desea añadir, mientras que el valor es una expresión booleana. Si el elemento del array tiene una clave numérica, siempre se incluirá en la lista de clases renderizada:

use Illuminate\Support\Arr;

$isActive = false;
$hasError = true;

$array = ['p-4', 'font-bold' => $isActive, 'bg-red' => $hasError];

$classes = Arr::toCssClasses($array);

/*
    'p-4 bg-red'
*/

#Arr::toCssStyles() {.collection-method}

La Arr::toCssStyles compila condicionalmente una cadena de estilos CSS. El método acepta un array de clases donde la clave del array contiene la clase o las clases que usted desea añadir, mientras que el valor es una expresión booleana. Si el elemento del array tiene una clave numérica, siempre se incluirá en la lista de clases renderizada:

use Illuminate\Support\Arr;

$hasColor = true;

$array = ['background-color: blue', 'color: blue' => $hasColor];

$classes = Arr::toCssStyles($array);

/*
    'background-color: blue; color: blue;'
*/

Este método impulsa la funcionalidad de Laravel que permite fusionar clases con la bolsa de atributos de un componente Blade así como la directiva @class de Blade.

#Arr::undot() {.collection-method}

El método Arr::undot expande un array unidimensional que usa notación "dot" en un array multidimensional:

use Illuminate\Support\Arr;

$array = [
    'user.name' => 'Kevin Malone',
    'user.occupation' => 'Accountant',
];

$array = Arr::undot($array);

// ['user' => ['name' => 'Kevin Malone', 'occupation' => 'Accountant']]

#Arr::where() {.collection-method}

El método Arr::where filtra un array usando el closure dado:

use Illuminate\Support\Arr;

$array = [100, '200', 300, '400', 500];

$filtered = Arr::where($array, function (string|int $value, int $key) {
    return is_string($value);
});

// [1 => '200', 3 => '400']

#Arr::whereNotNull() {.collection-method}

El método Arr::whereNotNull elimina todos los valores null del array dado:

use Illuminate\Support\Arr;

$array = [0, null];

$filtered = Arr::whereNotNull($array);

// [0 => 0]

#Arr::wrap() {.collection-method}

El método Arr::wrap envuelve el valor dado en un array. Si el valor dado ya es un array, se devolverá sin modificaciones:

use Illuminate\Support\Arr;

$string = 'Laravel';

$array = Arr::wrap($string);

// ['Laravel']

Si el valor dado es null, se devolverá un array vacío:

use Illuminate\Support\Arr;

$array = Arr::wrap(null);

// []

#data_fill() {.collection-method}

La función data_fill establece un valor faltante dentro de un array o objeto anidado usando notación "dot":

$data = ['products' => ['desk' => ['price' => 100]]];

data_fill($data, 'products.desk.price', 200);

// ['products' => ['desk' => ['price' => 100]]]

data_fill($data, 'products.desk.discount', 10);

// ['products' => ['desk' => ['price' => 100, 'discount' => 10]]]

Esta función también acepta asteriscos como comodines y llenará el objetivo en consecuencia:

$data = [
    'products' => [
        ['name' => 'Desk 1', 'price' => 100],
        ['name' => 'Desk 2'],
    ],
];

data_fill($data, 'products.*.price', 200);

/*
    [
        'products' => [
            ['name' => 'Desk 1', 'price' => 100],
            ['name' => 'Desk 2', 'price' => 200],
        ],
    ]
*/

#data_get() {.collection-method}

La función data_get recupera un valor de un array o objeto anidado usando la notación "dot":

$data = ['products' => ['desk' => ['price' => 100]]];

$price = data_get($data, 'products.desk.price');

// 100

La función data_get también acepta un valor por defecto, que será retornado si la clave especificada no se encuentra:

$discount = data_get($data, 'products.desk.discount', 0);

// 0

La función también acepta comodines usando asteriscos, que pueden apuntar a cualquier clave del array u objeto:

$data = [
    'product-one' => ['name' => 'Desk 1', 'price' => 100],
    'product-two' => ['name' => 'Desk 2', 'price' => 150],
];

data_get($data, '*.name');

// ['Desk 1', 'Desk 2'];

#data_set() {.collection-method}

La función data_set asigna un valor dentro de un array u objeto anidado usando la notación "dot":

$data = ['products' => ['desk' => ['price' => 100]]];

data_set($data, 'products.desk.price', 200);

// ['products' => ['desk' => ['price' => 200]]]

Esta función también acepta comodines usando asteriscos y asignará valores en el objetivo según corresponda:

$data = [
    'products' => [
        ['name' => 'Desk 1', 'price' => 100],
        ['name' => 'Desk 2', 'price' => 150],
    ],
];

data_set($data, 'products.*.price', 200);

/*
    [
        'products' => [
            ['name' => 'Desk 1', 'price' => 200],
            ['name' => 'Desk 2', 'price' => 200],
        ],
    ]
*/

Por defecto, cualquier valor existente será sobrescrito. Si desea asignar un valor solo si no existe, puede pasar false como cuarto argumento a la función:

$data = ['products' => ['desk' => ['price' => 100]]];

data_set($data, 'products.desk.price', 200, overwrite: false);

// ['products' => ['desk' => ['price' => 100]]]

#data_forget() {.collection-method}

La función data_forget elimina un valor dentro de un array u objeto anidado usando la notación "dot":

$data = ['products' => ['desk' => ['price' => 100]]];

data_forget($data, 'products.desk.price');

// ['products' => ['desk' => []]]

Esta función también acepta comodines usando asteriscos y eliminará valores en el objetivo según corresponda:

$data = [
    'products' => [
        ['name' => 'Desk 1', 'price' => 100],
        ['name' => 'Desk 2', 'price' => 150],
    ],
];

data_forget($data, 'products.*.price');

/*
    [
        'products' => [
            ['name' => 'Desk 1'],
            ['name' => 'Desk 2'],
        ],
    ]
*/

#head() {.collection-method}

La función head devuelve el primer elemento del array dado:

$array = [100, 200, 300];

$first = head($array);

// 100

#last() {.collection-method}

La función last devuelve el último elemento del array dado:

$array = [100, 200, 300];

$last = last($array);

// 300

#Números

#Number::abbreviate() {.collection-method}

El método Number::abbreviate devuelve el formato legible para humanos del valor numérico proporcionado, con una abreviatura para las unidades:

use Illuminate\Support\Number;

$number = Number::abbreviate(1000);

// 1K

$number = Number::abbreviate(489939);

// 490K

$number = Number::abbreviate(1230000, precision: 2);

// 1.23M

#Number::clamp() {.collection-method}

El método Number::clamp asegura que un número dado se mantenga dentro de un rango especificado. Si el número es menor que el mínimo, se devuelve el valor mínimo. Si el número es mayor que el máximo, se devuelve el valor máximo:

use Illuminate\Support\Number;

$number = Number::clamp(105, min: 10, max: 100);

// 100

$number = Number::clamp(5, min: 10, max: 100);

// 10

$number = Number::clamp(10, min: 10, max: 100);

// 10

$number = Number::clamp(20, min: 10, max: 100);

// 20

#Number::currency() {.collection-method}

El método Number::currency devuelve la representación en moneda del valor dado como una cadena:

use Illuminate\Support\Number;

$currency = Number::currency(1000);

// $1,000

$currency = Number::currency(1000, in: 'EUR');

// €1,000

$currency = Number::currency(1000, in: 'EUR', locale: 'de');

// 1.000 €

#Number::fileSize() {.collection-method}

El método Number::fileSize devuelve la representación del tamaño de archivo del valor dado en bytes como una cadena:

use Illuminate\Support\Number;

$size = Number::fileSize(1024);

// 1 KB

$size = Number::fileSize(1024 * 1024);

// 1 MB

$size = Number::fileSize(1024, precision: 2);

// 1.00 KB

#Number::forHumans() {.collection-method}

El método Number::forHumans devuelve el formato legible para humanos del valor numérico proporcionado:

use Illuminate\Support\Number;

$number = Number::forHumans(1000);

// 1 thousand

$number = Number::forHumans(489939);

// 490 thousand

$number = Number::forHumans(1230000, precision: 2);

// 1.23 million

#Number::format() {.collection-method}

El método Number::format formatea el número dado en una cadena específica del locale:

use Illuminate\Support\Number;

$number = Number::format(100000);

// 100,000

$number = Number::format(100000, precision: 2);

// 100,000.00

$number = Number::format(100000.123, maxPrecision: 2);

// 100,000.12

$number = Number::format(100000, locale: 'de');

// 100.000

#Number::ordinal() {.collection-method}

El método Number::ordinal devuelve la representación ordinal de un número:

use Illuminate\Support\Number;

$number = Number::ordinal(1);

// 1st

$number = Number::ordinal(2);

// 2nd

$number = Number::ordinal(21);

// 21st

#Number::percentage() {.collection-method}

El método Number::percentage devuelve la representación en porcentaje del valor dado como una cadena:

use Illuminate\Support\Number;

$percentage = Number::percentage(10);

// 10%

$percentage = Number::percentage(10, precision: 2);

// 10.00%

$percentage = Number::percentage(10.123, maxPrecision: 2);

// 10.12%

$percentage = Number::percentage(10, precision: 2, locale: 'de');

// 10,00%

#Number::spell() {.collection-method}

El método Number::spell transforma el número dado en una cadena de palabras:

use Illuminate\Support\Number;

$number = Number::spell(102);

// one hundred and two

$number = Number::spell(88, locale: 'fr');

// quatre-vingt-huit

El argumento after permite especificar un valor después del cual todos los números deben ser escritos en palabras:

$number = Number::spell(10, after: 10);

// 10

$number = Number::spell(11, after: 10);

// eleven

El argumento until permite especificar un valor antes del cual todos los números deben ser escritos en palabras:

$number = Number::spell(5, until: 10);

// five

$number = Number::spell(10, until: 10);

// 10

#Number::useLocale() {.collection-method}

El método Number::useLocale establece el locale numérico predeterminado globalmente, lo que afecta cómo se formatean los números y monedas en las invocaciones posteriores a los métodos de la clase Number:

use Illuminate\Support\Number;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Number::useLocale('de');
}

#Number::withLocale() {.collection-method}

El método Number::withLocale ejecuta el closure dado usando el locale especificado y luego restaura el locale original después de que el callback se haya ejecutado:

use Illuminate\Support\Number;

$number = Number::withLocale('de', function () {
    return Number::format(1500);
});

#Rutas de archivos

#app_path() {.collection-method}

La función app_path devuelve la ruta completa al directorio app de su aplicación. También puede usar la función app_path para generar una ruta completa a un archivo relativo al directorio de la aplicación:

$path = app_path();

$path = app_path('Http/Controllers/Controller.php');

#base_path() {.collection-method}

La función base_path devuelve la ruta completa al directorio raíz de su aplicación. También puede usar la función base_path para generar una ruta completa a un archivo dado relativo al directorio raíz del proyecto:

$path = base_path();

$path = base_path('vendor/bin');

#config_path() {.collection-method}

La función config_path devuelve la ruta completa al directorio config de su aplicación. También puede usar la función config_path para generar una ruta completa a un archivo dado dentro del directorio de configuración de la aplicación:

$path = config_path();

$path = config_path('app.php');

#database_path() {.collection-method}

La función database_path devuelve la ruta completa al directorio database de su aplicación. También puede usar la función database_path para generar una ruta completa a un archivo dado dentro del directorio de base de datos:

$path = database_path();

$path = database_path('factories/UserFactory.php');

#lang_path() {.collection-method}

La función lang_path devuelve la ruta completa al directorio lang de su aplicación. También puede usar la función lang_path para generar una ruta completa a un archivo dado dentro del directorio:

$path = lang_path();

$path = lang_path('en/messages.php');

#mix() {.collection-method}

La función mix devuelve la ruta a un archivo Mix versionado:

$path = mix('css/app.css');

#public_path() {.collection-method}

La función public_path devuelve la ruta completa al directorio public de su aplicación. También puede usar la función public_path para generar una ruta completa a un archivo dado dentro del directorio público:

$path = public_path();

$path = public_path('css/app.css');

#resource_path() {.collection-method}

La función resource_path devuelve la ruta completa al directorio resources de su aplicación. También puede usar la función resource_path para generar una ruta completa a un archivo dado dentro del directorio de recursos:

$path = resource_path();

$path = resource_path('sass/app.scss');

#storage_path() {.collection-method}

La función storage_path devuelve la ruta completa al directorio storage de su aplicación. También puede usar la función storage_path para generar una ruta completa a un archivo dado dentro del directorio de almacenamiento:

$path = storage_path();

$path = storage_path('app/file.txt');

#URLs

#action() {.collection-method}

La función action genera una URL para la acción del controlador dada:

use App\Http\Controllers\HomeController;

$url = action([HomeController::class, 'index']);

Si el método acepta parámetros de ruta, puede pasarlos como segundo argumento al método:

$url = action([UserController::class, 'profile'], ['id' => 1]);

#asset() {.collection-method}

La función asset genera una URL para un recurso usando el esquema actual de la solicitud (HTTP o HTTPS):

$url = asset('img/photo.jpg');

Puede configurar el host de la URL de los recursos estableciendo la variable ASSET_URL en su archivo .env. Esto puede ser útil si aloja sus recursos en un servicio externo como Amazon S3 u otro CDN:

// ASSET_URL=http://example.com/assets

$url = asset('img/photo.jpg'); // http://example.com/assets/img/photo.jpg

#route() {.collection-method}

La función route genera una URL para una ruta nombrada:

$url = route('route.name');

Si la ruta acepta parámetros, puede pasarlos como segundo argumento a la función:

$url = route('route.name', ['id' => 1]);

Por defecto, la función route genera una URL absoluta. Si desea generar una URL relativa, puede pasar false como tercer argumento a la función:

$url = route('route.name', ['id' => 1], false);

#secure_asset() {.collection-method}

La función secure_asset genera una URL para un recurso usando HTTPS:

$url = secure_asset('img/photo.jpg');

#secure_url() {.collection-method}

La función secure_url genera una URL HTTPS completamente calificada para la ruta dada. Se pueden pasar segmentos adicionales de URL en el segundo argumento de la función:

$url = secure_url('user/profile');

$url = secure_url('user/profile', [1]);

#to_route() {.collection-method}

La función to_route genera una respuesta HTTP de redirección para una ruta nombrada dada:

return to_route('users.show', ['user' => 1]);

Si es necesario, puede pasar el código de estado HTTP que debe asignarse a la redirección y cualquier encabezado adicional de respuesta como tercer y cuarto argumento al método to_route:

return to_route('users.show', ['user' => 1], 302, ['X-Framework' => 'Laravel']);

#url() {.collection-method}

La función url genera una URL completamente calificada para la ruta dada:

$url = url('user/profile');

$url = url('user/profile', [1]);

Si no se proporciona una ruta, se devuelve una instancia de Illuminate\Routing\UrlGenerator:

$current = url()->current();

$full = url()->full();

$previous = url()->previous();

#Misceláneos

#abort() {.collection-method}

La función abort lanza una excepción HTTP que será manejada por el manejador de excepciones:

abort(403);

También puede proporcionar el mensaje de la excepción y encabezados HTTP personalizados que deben enviarse al navegador:

abort(403, 'Unauthorized.', $headers);

#abort_if() {.collection-method}

La función abort_if lanza una excepción HTTP si una expresión booleana dada evalúa a true:

abort_if(! Auth::user()->isAdmin(), 403);

Al igual que el método abort, también puede proporcionar el texto de respuesta de la excepción como tercer argumento y un array de encabezados de respuesta personalizados como cuarto argumento a la función.

#abort_unless() {.collection-method}

La función abort_unless lanza una excepción HTTP si una expresión booleana dada evalúa a false:

abort_unless(Auth::user()->isAdmin(), 403);

Al igual que el método abort, también puede proporcionar el texto de respuesta de la excepción como tercer argumento y un array de encabezados de respuesta personalizados como cuarto argumento a la función.

#app() {.collection-method}

La función app devuelve la instancia del contenedor de servicios:

$container = app();

Puede pasar un nombre de clase o interfaz para resolverlo desde el contenedor:

$api = app('HelpSpot\API');

#auth() {.collection-method}

La función auth devuelve una instancia de autenticador. Puede usarla como alternativa a la fachada Auth:

$user = auth()->user();

Si es necesario, puede especificar qué instancia de guard desea acceder:

$user = auth('admin')->user();

#back() {.collection-method}

La función back genera una respuesta HTTP de redirección a la ubicación previa del usuario:

return back($status = 302, $headers = [], $fallback = '/');

return back();

#bcrypt() {.collection-method}

La función bcrypt hashea el valor dado usando Bcrypt. Puede usar esta función como alternativa a la fachada Hash:

$password = bcrypt('my-secret-password');

#blank() {.collection-method}

La función blank determina si el valor dado está "vacío":

blank('');
blank('   ');
blank(null);
blank(collect());

// true

blank(0);
blank(true);
blank(false);

// false

Para el inverso de blank, consulte el método filled.

#broadcast() {.collection-method}

La función broadcast transmite el evento dado a sus oyentes:

broadcast(new UserRegistered($user));

broadcast(new UserRegistered($user))->toOthers();

#cache() {.collection-method}

La función cache puede usarse para obtener valores del cache. Si la clave dada no existe en el cache, se devolverá un valor por defecto opcional:

$value = cache('key');

$value = cache('key', 'default');

Puede agregar elementos al cache pasando un array de pares clave / valor a la función. También debe pasar el número de segundos o duración durante la cual el valor cacheado debe considerarse válido:

cache(['key' => 'value'], 300);

cache(['key' => 'value'], now()->addSeconds(10));

#class_uses_recursive() {.collection-method}

La función class_uses_recursive devuelve todos los traits usados por una clase, incluyendo los traits usados por todas sus clases padre:

$traits = class_uses_recursive(App\Models\User::class);

#collect() {.collection-method}

La función collect crea una instancia de colección a partir del valor dado:

$collection = collect(['taylor', 'abigail']);

#config() {.collection-method}

La función config obtiene el valor de una variable de configuración. Los valores de configuración pueden accederse usando la sintaxis "dot", que incluye el nombre del archivo y la opción que desea acceder. Se puede especificar un valor por defecto que se devuelve si la opción de configuración no existe:

$value = config('app.timezone');

$value = config('app.timezone', $default);

Puede establecer variables de configuración en tiempo de ejecución pasando un array de pares clave / valor. Sin embargo, tenga en cuenta que esta función solo afecta el valor de configuración para la solicitud actual y no actualiza sus valores de configuración reales:

config(['app.debug' => true]);

#cookie() {.collection-method}

La función cookie crea una nueva instancia de cookie:

$cookie = cookie('name', 'value', $minutes);

#csrf_field() {.collection-method}

La función csrf_field genera un campo de entrada HTML hidden que contiene el valor del token CSRF. Por ejemplo, usando la sintaxis Blade:

{{ csrf_field() }}

#csrf_token() {.collection-method}

La función csrf_token recupera el valor del token CSRF actual:

$token = csrf_token();

#decrypt() {.collection-method}

La función decrypt desencripta el valor dado. Puede usar esta función como alternativa a la fachada Crypt:

$password = decrypt($value);

#dd() {.collection-method}

La función dd muestra las variables dadas y termina la ejecución del script:

dd($value);

dd($value1, $value2, $value3, ...);

Si no desea detener la ejecución de su script, use la función dump en su lugar.

#dispatch() {.collection-method}

La función dispatch envía el job dado a la cola de jobs de Laravel:

dispatch(new App\Jobs\SendEmails);

#dispatch_sync() {.collection-method}

La función dispatch_sync envía el job dado a la cola sync para que se procese inmediatamente:

dispatch_sync(new App\Jobs\SendEmails);

#dump() {.collection-method}

La función dump muestra las variables dadas:

dump($value);

dump($value1, $value2, $value3, ...);

Si desea detener la ejecución del script después de mostrar las variables, use la función dd en su lugar.

#encrypt() {.collection-method}

La función encrypt encripta el valor dado. Puede usar esta función como alternativa a la fachada Crypt:

$secret = encrypt('my-secret-value');

#env() {.collection-method}

La función env recupera el valor de una variable de entorno o devuelve un valor por defecto:

$env = env('APP_ENV');

$env = env('APP_ENV', 'production');

#event() {.collection-method}

La función event despacha el evento dado a sus oyentes:

event(new UserRegistered($user));

#fake() {.collection-method}

La función fake resuelve un singleton de Faker desde el contenedor, lo cual puede ser útil al crear datos falsos en factories de modelos, seeding de base de datos, pruebas y prototipos de vistas:

@for($i = 0; $i < 10; $i++)
    <dl>
        <dt>Name</dt>
        <dd>{{ fake()->name() }}</dd>

        <dt>Email</dt>
        <dd>{{ fake()->unique()->safeEmail() }}</dd>
    </dl>
@endfor

Por defecto, la función fake utilizará la opción de configuración app.faker_locale en su archivo config/app.php; sin embargo, también puede especificar el locale pasándolo a la función fake. Cada locale resolverá un singleton individual:

fake('nl_NL')->name()

#filled() {.collection-method}

La función filled determina si el valor dado no está "vacío":

filled(0);
filled(true);
filled(false);

// true

filled('');
filled('   ');
filled(null);
filled(collect());

// false

Para el inverso de filled, consulte el método blank.

#info() {.collection-method}

La función info escribirá información en el log de su aplicación:

info('Some helpful information!');

También puede pasar un array de datos contextuales a la función:

info('User login attempt failed.', ['id' => $user->id]);

#logger() {.collection-method}

La función logger puede usarse para escribir un mensaje de nivel debug en el log:

logger('Debug message');

También puede pasar un array de datos contextuales a la función:

logger('User has logged in.', ['id' => $user->id]);

Se devolverá una instancia de logger si no se pasa ningún valor a la función:

logger()->error('You are not allowed here.');

#method_field() {.collection-method}

La función method_field genera un campo de entrada HTML hidden que contiene el valor falsificado del verbo HTTP del formulario. Por ejemplo, usando la sintaxis Blade:

<form method="POST">
    {{ method_field('DELETE') }}
</form>

#now() {.collection-method}

La función now crea una nueva instancia de Illuminate\Support\Carbon para la hora actual:

$now = now();

#old() {.collection-method}

La función old recupera un valor de entrada antigua almacenado en la sesión:

$value = old('value');

$value = old('value', 'default');

Dado que el "valor por defecto" proporcionado como segundo argumento a la función old suele ser un atributo de un modelo Eloquent, Laravel permite pasar simplemente el modelo Eloquent completo como segundo argumento a la función old. Al hacerlo, Laravel asumirá que el primer argumento proporcionado a la función old es el nombre del atributo Eloquent que debe considerarse el "valor por defecto":

{{ old('name', $user->name) }}

// Es equivalente a...

{{ old('name', $user) }}

#optional() {.collection-method}

La función optional acepta cualquier argumento y le permite acceder a propiedades o llamar métodos en ese objeto. Si el objeto dado es null, las propiedades y métodos devolverán null en lugar de causar un error:

return optional($user->address)->street;

{!! old('name', optional($user)->name) !!}

La función optional también acepta un closure como segundo argumento. El closure se ejecutará si el valor proporcionado como primer argumento no es null:

return optional(User::find($id), function (User $user) {
    return $user->name;
});

#policy() {.collection-method}

El método policy obtiene una instancia de policy para una clase dada:

$policy = policy(App\Models\User::class);

#redirect() {.collection-method}

La función redirect devuelve una respuesta HTTP de redirección, o devuelve la instancia del redireccionador si se llama sin argumentos:

return redirect($to = null, $status = 302, $headers = [], $https = null);

return redirect('/home');

return redirect()->route('route.name');

#report() {.collection-method}

La función report reportará una excepción usando su manejador de excepciones:

report($e);

La función report también acepta una cadena como argumento. Cuando se le pasa una cadena, la función creará una excepción con esa cadena como mensaje:

report('Something went wrong.');

#report_if() {.collection-method}

La función report_if reportará una excepción usando su manejador de excepciones si la condición dada es true:

report_if($shouldReport, $e);

report_if($shouldReport, 'Something went wrong.');

#report_unless() {.collection-method}

La función report_unless reportará una excepción usando su manejador de excepciones si la condición dada es false:

report_unless($reportingDisabled, $e);

report_unless($reportingDisabled, 'Something went wrong.');

#request() {.collection-method}

La función request devuelve la instancia actual de request o obtiene el valor de un campo de entrada de la solicitud actual:

$request = request();

$value = request('key', $default);

#rescue() {.collection-method}

La función rescue ejecuta el closure dado y captura cualquier excepción que ocurra durante su ejecución. Todas las excepciones capturadas serán enviadas a su manejador de excepciones; sin embargo, la solicitud continuará procesándose:

return rescue(function () {
    return $this->method();
});

También puede pasar un segundo argumento a la función rescue. Este argumento será el valor "por defecto" que se devolverá si ocurre una excepción durante la ejecución del closure:

return rescue(function () {
    return $this->method();
}, false);

return rescue(function () {
    return $this->method();
}, function () {
    return $this->failure();
});

Se puede proporcionar un argumento report a la función rescue para determinar si la excepción debe ser reportada mediante la función report:

return rescue(function () {
    return $this->method();
}, report: function (Throwable $throwable) {
    return $throwable instanceof InvalidArgumentException;
});

#resolve() {.collection-method}

La función resolve resuelve un nombre de clase o interfaz dado a una instancia usando el contenedor de servicios:

$api = resolve('HelpSpot\API');

#response() {.collection-method}

La función response crea una instancia de respuesta u obtiene una instancia de la fábrica de respuestas:

return response('Hello World', 200, $headers);

return response()->json(['foo' => 'bar'], 200, $headers);

#retry() {.collection-method}

La función retry intenta ejecutar el callback dado hasta que se alcance el umbral máximo de intentos. Si el callback no lanza una excepción, se devolverá su valor de retorno. Si el callback lanza una excepción, se reintentará automáticamente. Si se excede el número máximo de intentos, se lanzará la excepción:

return retry(5, function () {
    // Intentar 5 veces descansando 100ms entre intentos...
}, 100);

Si desea calcular manualmente el número de milisegundos para dormir entre intentos, puede pasar un closure como tercer argumento a la función retry:

use Exception;

return retry(5, function () {
    // ...
}, function (int $attempt, Exception $exception) {
    return $attempt * 100;
});

Para mayor comodidad, puede proporcionar un array como primer argumento a la función retry. Este array se usará para determinar cuántos milisegundos dormir entre intentos sucesivos:

return retry([100, 200], function () {
    // Dormir 100ms en el primer reintento, 200ms en el segundo...
});

Para reintentar solo bajo condiciones específicas, puede pasar un closure como cuarto argumento a la función retry:

use Exception;

return retry(5, function () {
    // ...
}, 100, function (Exception $exception) {
    return $exception instanceof RetryException;
});

#session() {.collection-method}

La función session puede usarse para obtener o establecer valores de sesión:

$value = session('key');

Puede establecer valores pasando un array de pares clave / valor a la función:

session(['chairs' => 7, 'instruments' => 3]);

Se devolverá la tienda de sesión si no se pasa ningún valor a la función:

$value = session()->get('key');

session()->put('key', $value);

#tap() {.collection-method}

La función tap acepta dos argumentos: un $value arbitrario y un closure. El $value será pasado al closure y luego será devuelto por la función tap. El valor de retorno del closure es irrelevante:

$user = tap(User::first(), function (User $user) {
    $user->name = 'taylor';

    $user->save();
});

Si no se pasa un closure a la función tap, puede llamar a cualquier método sobre el $value dado. El valor de retorno del método que llame siempre será $value, sin importar lo que el método realmente devuelva en su definición. Por ejemplo, el método update de Eloquent típicamente devuelve un entero. Sin embargo, podemos forzar que el método devuelva el modelo mismo encadenando la llamada al método update a través de la función tap:

$user = tap($user)->update([
    'name' => $name,
    'email' => $email,
]);

Para añadir un método tap a una clase, puede agregar el trait Illuminate\Support\Traits\Tappable a la clase. El método tap de este trait acepta un Closure como único argumento. La instancia del objeto será pasada al Closure y luego devuelta por el método tap:

return $user->tap(function (User $user) {
    // ...
});

#throw_if() {.collection-method}

La función throw_if lanza la excepción dada si una expresión booleana dada evalúa a true:

throw_if(! Auth::user()->isAdmin(), AuthorizationException::class);

throw_if(
    ! Auth::user()->isAdmin(),
    AuthorizationException::class,
    'No tiene permiso para acceder a esta página.'
);

#throw_unless() {.collection-method}

La función throw_unless lanza la excepción dada si una expresión booleana dada evalúa a false:

throw_unless(Auth::user()->isAdmin(), AuthorizationException::class);

throw_unless(
    Auth::user()->isAdmin(),
    AuthorizationException::class,
    'No tiene permiso para acceder a esta página.'
);

#today() {.collection-method}

La función today crea una nueva instancia de Illuminate\Support\Carbon para la fecha actual:

$today = today();

#trait_uses_recursive() {.collection-method}

La función trait_uses_recursive devuelve todos los traits usados por un trait:

$traits = trait_uses_recursive(\Illuminate\Notifications\Notifiable::class);

#transform() {.collection-method}

La función transform ejecuta un closure sobre un valor dado si el valor no es blank y luego devuelve el valor retornado por el closure:

$callback = function (int $value) {
    return $value * 2;
};

$result = transform(5, $callback);

// 10

Se puede pasar un valor por defecto o un closure como tercer argumento a la función. Este valor será devuelto si el valor dado está en blanco:

$result = transform(null, $callback, 'The value is blank');

// El valor está en blanco

#validator() {.collection-method}

La función validator crea una nueva instancia de validator con los argumentos dados. Puede usarla como alternativa a la fachada Validator:

$validator = validator($data, $rules, $messages);

#value() {.collection-method}

La función value devuelve el valor que se le pasa. Sin embargo, si se pasa un closure, este se ejecutará y se devolverá su valor retornado:

$result = value(true);

// true

$result = value(function () {
    return false;
});

// false

Se pueden pasar argumentos adicionales a la función value. Si el primer argumento es un closure, los parámetros adicionales serán pasados al closure como argumentos, de lo contrario serán ignorados:

$result = value(function (string $name) {
    return $name;
}, 'Taylor');

// 'Taylor'

#view() {.collection-method}

La función view obtiene una instancia de view:

return view('auth.login');

#with() {.collection-method}

La función with devuelve el valor que se le pasa. Si se pasa un closure como segundo argumento, este se ejecutará y se devolverá su valor retornado:

$callback = function (mixed $value) {
    return is_numeric($value) ? $value * 2 : 0;
};

$result = with(5, $callback);

// 10

$result = with(null, $callback);

// 0

$result = with(5, null);

// 5

#Otras utilidades

#Benchmarking

A veces puede que desee probar rápidamente el rendimiento de ciertas partes de su aplicación. En esas ocasiones, puede utilizar la clase de soporte Benchmark para medir la cantidad de milisegundos que tardan en completarse los callbacks dados:

<?php

use App\Models\User;
use Illuminate\Support\Benchmark;

Benchmark::dd(fn () => User::find(1)); // 0.1 ms

Benchmark::dd([
    'Scenario 1' => fn () => User::count(), // 0.5 ms
    'Scenario 2' => fn () => User::all()->count(), // 20.0 ms
]);

Por defecto, los callbacks dados se ejecutarán una vez (una iteración), y su duración se mostrará en el navegador / consola.

Para invocar un callback más de una vez, puede especificar el número de iteraciones que debe ejecutarse el callback como segundo argumento del método. Al ejecutar un callback más de una vez, la clase Benchmark devolverá el promedio de milisegundos que tomó ejecutar el callback en todas las iteraciones:

Benchmark::dd(fn () => User::count(), iterations: 10); // 0.5 ms

A veces, puede querer medir el rendimiento de la ejecución de un callback mientras obtiene el valor devuelto por el callback. El método value devolverá una tupla que contiene el valor devuelto por el callback y la cantidad de milisegundos que tomó ejecutar el callback:

[$count, $duration] = Benchmark::value(fn () => User::count());

#Fechas

Laravel incluye Carbon, una potente biblioteca para manipulación de fechas y horas. Para crear una nueva instancia de Carbon, puede invocar la función now. Esta función está disponible globalmente dentro de su aplicación Laravel:

$now = now();

O bien, puede crear una nueva instancia de Carbon usando la clase Illuminate\Support\Carbon:

use Illuminate\Support\Carbon;

$now = Carbon::now();

Para una discusión detallada sobre Carbon y sus características, consulte la documentación oficial de Carbon.

#Lotería

La clase de lotería de Laravel puede usarse para ejecutar callbacks basados en un conjunto de probabilidades dadas. Esto puede ser especialmente útil cuando solo desea ejecutar código para un porcentaje de sus solicitudes entrantes:

use Illuminate\Support\Lottery;

Lottery::odds(1, 20)
    ->winner(fn () => $user->won())
    ->loser(fn () => $user->lost())
    ->choose();

Puede combinar la clase de lotería de Laravel con otras características de Laravel. Por ejemplo, puede que solo desee reportar un pequeño porcentaje de consultas lentas a su manejador de excepciones. Y, dado que la clase de lotería es invocable, podemos pasar una instancia de la clase a cualquier método que acepte callables:

use Carbon\CarbonInterval;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Lottery;

DB::whenQueryingForLongerThan(
    CarbonInterval::seconds(2),
    Lottery::odds(1, 100)->winner(fn () => report('Querying > 2 seconds.')),
);

#Pruebas de loterías

Laravel proporciona algunos métodos simples para permitirle probar fácilmente las invocaciones de lotería de su aplicación:

// La lotería siempre ganará...
Lottery::alwaysWin();

// La lotería siempre perderá...
Lottery::alwaysLose();

// La lotería ganará y luego perderá, y finalmente volverá al comportamiento normal...
Lottery::fix([true, false]);

// La lotería volverá al comportamiento normal...
Lottery::determineResultsNormally();

#Pipeline

La fachada Pipeline de Laravel proporciona una forma conveniente de "encaminar" una entrada dada a través de una serie de clases invocables, closures o callables, dando a cada clase la oportunidad de inspeccionar o modificar la entrada e invocar el siguiente callable en el pipeline:

use Closure;
use App\Models\User;
use Illuminate\Support\Facades\Pipeline;

$user = Pipeline::send($user)
            ->through([
                function (User $user, Closure $next) {
                    // ...

                    return $next($user);
                },
                function (User $user, Closure $next) {
                    // ...

                    return $next($user);
                },
            ])
            ->then(fn (User $user) => $user);

Como puede ver, a cada clase invocable o closure en el pipeline se le proporciona la entrada y un closure $next. Invocar el closure $next invocará el siguiente callable en el pipeline. Como habrá notado, esto es muy similar a middleware.

Cuando el último callable en el pipeline invoca el closure $next, se invocará el callable proporcionado al método then. Normalmente, este callable simplemente devolverá la entrada dada.

Por supuesto, como se discutió anteriormente, no está limitado a proporcionar closures a su pipeline. También puede proporcionar clases invocables. Si se proporciona un nombre de clase, la clase será instanciada a través del contenedor de servicios de Laravel, permitiendo que se inyecten dependencias en la clase invocable:

$user = Pipeline::send($user)
            ->through([
                GenerateProfilePhoto::class,
                ActivateSubscription::class,
                SendWelcomeEmail::class,
            ])
            ->then(fn (User $user) => $user);

#Sleep

La clase Sleep de Laravel es un envoltorio ligero alrededor de las funciones nativas sleep y usleep de PHP, ofreciendo mayor capacidad de prueba y una API amigable para desarrolladores para trabajar con el tiempo:

use Illuminate\Support\Sleep;

$waiting = true;

while ($waiting) {
    Sleep::for(1)->second();

    $waiting = /* ... */;
}

La clase Sleep ofrece una variedad de métodos que le permiten trabajar con diferentes unidades de tiempo:

// Pausar la ejecución por 90 segundos...
Sleep::for(1.5)->minutes();

// Pausar la ejecución por 2 segundos...
Sleep::for(2)->seconds();

// Pausar la ejecución por 500 milisegundos...
Sleep::for(500)->milliseconds();

// Pausar la ejecución por 5,000 microsegundos...
Sleep::for(5000)->microseconds();

// Pausar la ejecución hasta un tiempo dado...
Sleep::until(now()->addMinute());

// Alias de la función nativa "sleep" de PHP...
Sleep::sleep(2);

// Alias de la función nativa "usleep" de PHP...
Sleep::usleep(5000);

Para combinar fácilmente unidades de tiempo, puede usar el método and:

Sleep::for(1)->second()->and(10)->milliseconds();

#Pruebas de Sleep

Al probar código que utiliza la clase Sleep o las funciones nativas de sleep de PHP, su prueba pausará la ejecución. Como puede imaginar, esto hace que su suite de pruebas sea significativamente más lenta. Por ejemplo, imagine que está probando el siguiente código:

$waiting = /* ... */;

$seconds = 1;

while ($waiting) {
    Sleep::for($seconds++)->seconds();

    $waiting = /* ... */;
}

Normalmente, probar este código tomaría al menos un segundo. Por suerte, la clase Sleep nos permite "simular" el sleep para que nuestra suite de pruebas se mantenga rápida:

public function test_it_waits_until_ready()
{
    Sleep::fake();

    // ...
}

Al simular la clase Sleep, se omite la pausa real de ejecución, lo que conduce a una prueba sustancialmente más rápida.

Una vez que la clase Sleep ha sido simulada, es posible hacer aserciones sobre los "sleeps" esperados que deberían haber ocurrido. Para ilustrar esto, imaginemos que estamos probando código que pausa la ejecución tres veces, con cada pausa aumentando en un segundo. Usando el método assertSequence, podemos afirmar que nuestro código "durmió" la cantidad correcta de tiempo mientras mantenemos la prueba rápida:

public function test_it_checks_if_ready_four_times()
{
    Sleep::fake();

    // ...

    Sleep::assertSequence([
        Sleep::for(1)->second(),
        Sleep::for(2)->seconds(),
        Sleep::for(3)->seconds(),
    ]);
}

Por supuesto, la clase Sleep ofrece una variedad de otras aserciones que puede usar al probar:

use Carbon\CarbonInterval as Duration;
use Illuminate\Support\Sleep;

// Asegurar que sleep fue llamado 3 veces...
Sleep::assertSleptTimes(3);

// Asegurar contra la duración del sleep...
Sleep::assertSlept(function (Duration $duration): bool {
    return /* ... */;
}, times: 1);

// Asegurar que la clase Sleep nunca fue invocada...
Sleep::assertNeverSlept();

// Asegurar que, incluso si Sleep fue llamado, no ocurrió pausa en la ejecución...
Sleep::assertInsomniac();

A veces puede ser útil realizar una acción cada vez que ocurre un sleep simulado en el código de su aplicación. Para lograr esto, puede proporcionar un callback al método whenFakingSleep. En el siguiente ejemplo, usamos los helpers de manipulación de tiempo de Laravel para avanzar instantáneamente el tiempo por la duración de cada sleep:

use Carbon\CarbonInterval as Duration;

$this->freezeTime();

Sleep::fake();

Sleep::whenFakingSleep(function (Duration $duration) {
    // Avanzar el tiempo al simular sleep...
    $this->travel($duration->totalMilliseconds)->milliseconds();
});

Laravel usa la clase Sleep internamente cada vez que pausa la ejecución. Por ejemplo, el helper retry usa la clase Sleep al dormir, permitiendo una mejor capacidad de prueba cuando se usa ese helper.