Auxiliares

Introdução

O Laravel inclui várias funções de "auxiliares" PHP globais. Muitas dessas funções são usadas pelo próprio framework; no entanto, você pode usar-los em suas próprias aplicações se considerar conveniente.

Métodos disponíveis

Matrizes e objetos

• Arr::accessible
• Arr::add
• Arr::collapse
• Arr::crossJoin
• Arr::divide
• Arr::dot
• Arr::except
• Arr::exists
• Arr::first
• Arr::flatten
• Arr::forget
• Arr::get
• Arr::has
• Arr::hasAny
• Arr::isAssoc
• Arr::isList
• Arr::join
• Arr::keyBy
• Arr::last
• Arr::map
• Arr::mapSpread
• Arr::mapWithKeys
• Arr::only
• Arr::pluck
• Arr::prepend
• Arr::prependKeysWith
• Arr::pull
• Arr::query
• Arr::random
• Arr::set
• Arr::shuffle
• Arr::sort
• Arr::sortDesc
• Arr::sortRecursive
• Arr::sortRecursiveDesc
• Arr::take
• Arr::toCssClasses
• Arr::toCssStyles
• Arr::undot
• Arr::where
• Arr::whereNotNull
• Arr::wrap
• data_fill
• data_get
• data_set
• data_forget
• head
• last

Números

• Number::abbreviate
• Number::clamp
• Number::currency
• Number::fileSize
• Number::forHumans
• Number::format
• Number::ordinal
• Number::percentage
• Number::spell
• Number::useLocale
• Number::withLocale

Caminhos

• app_path
• base_path
• config_path
• database_path
• lang_path
• mix
• public_path
• resource_path
• storage_path

URLs

• action
• asset
• route
• secure_asset
• secure_url
• to_route
• url

Diversos

• abort
• abort_if
• abort_unless
• app
• auth
• back
• bcrypt
• blank
• broadcast
• cache
• class_uses_recursive
• collect
• config
• context
• cookie
• csrf_field
• csrf_token
• decrypt
• dd
• dispatch
• dispatch_sync
• dump
• encrypt
• env
• event
• fake
• filled
• info
• literal
• logger
• method_field
• now
• old
• once
• optional
• policy
• redirect
• report
• report_if
• report_unless
• request
• rescue
• resolve
• response
• retry
• session
• tap
• throw_if
• throw_unless
• today
• trait_uses_recursive
• transform
• validator
• value
• view
• with

Matrizes e Objetos

Arr::accessible()

O método Arr::accessible determina se o valor passado é acessível ao script:

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

O método Arr::add adiciona um par chave/valor fornecido a uma matriz se a chave não existir na matriz ou estiver definida como 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()

O método Arr::collapse colapsa uma matriz de arrays em uma única matriz:

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

O método Arr::crossJoin realiza uma operação de união cruzada dos array fornecidos e retorna um produto cartesiano com todas as combinações possíveis:

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

O método Arr::divide retorna dois vetores: um contendo as chaves e o outro com os valores do array fornecido.

    use Illuminate\Support\Arr;

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

    // $keys: ['name']

    // $values: ['Desk']

Arr::dot()

O método Arr::dot reduz um array multidimensional a um array de nível único que utiliza a notação de "ponto" para indicar o nível de profundidade:

    use Illuminate\Support\Arr;

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

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

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

Arr::except()

O método Arr::except remove as combinações de chave/valor indicadas a partir de um conjunto:

    use Illuminate\Support\Arr;

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

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

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

Arr::exists()

O método arr :: exists verifica se a chave fornecida existe no array fornecido:

    use Illuminate\Support\Arr;

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

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

    // true

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

    // false

Arr::first()

O método Arr::first retorna o primeiro elemento de um array que passa em um determinado teste de verdade:

    use Illuminate\Support\Arr;

    $array = [100, 200, 300];

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

    // 200

O valor padrão também pode ser passado como o terceiro parâmetro para o método. Este valor será retornado se nenhum dos valores tiver sucesso na análise de veracidade:

    use Illuminate\Support\Arr;

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

Arr::flatten()

O método Arr::flatten "aplana" uma matriz multidimensional numa matriz de nível único:

    use Illuminate\Support\Arr;

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

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

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

Arr::forget()

O método Arr::forget remove uma chave/par de valores dado de um array profundamente aninhado usando notação "ponto":

    use Illuminate\Support\Arr;

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

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

    // ['products' => []]

Arr::get()

O método Arr::get recupera um valor de um array altamente agrupado usando notação "ponto":

    use Illuminate\Support\Arr;

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

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

    // 100

O método Arr::get também aceita um valor padrão que será devolvido se a chave especificada não estiver presente na matriz:

    use Illuminate\Support\Arr;

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

    // 0

Arr::has()

O método Arr::has verifica se um determinado item ou itens existem numa matriz, usando a notação "ponto":

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

O método Arr::hasAny verifica se algum item de um conjunto especificado existe em uma matriz usando a notação de ponto (".")

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

O método Arr::isAssoc retorna true se o array for um array associativo. Um array é considerado "associativo" se não tiver chaves numéricas sequenciais começando por zero:

    use Illuminate\Support\Arr;

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

    // true

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

    // false

Arr::isList()

A função Arr::isList retorna true se as chaves do array forem números inteiros consecutivos, começando a partir de zero:

    use Illuminate\Support\Arr;

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

    // true

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

    // false

Arr::join()

O método join une os elementos de uma matriz com uma string. Usando o segundo argumento do método é possível especificar a string para unir o último elemento da matriz:

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

O método Arr::keyBy chaveia a matriz por uma determinada chave. Se vários itens tiverem a mesma chave, apenas o último aparecerá na nova matriz:

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

O método Arr::last retorna o último elemento de uma matriz que deve passar num determinado teste de validação:

    use Illuminate\Support\Arr;

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

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

    // 300

Pode ser passado um valor por padrão como terceiro argumento para o método. Este valor será retornado se nenhum outro puder satisfazer a verificação:

    use Illuminate\Support\Arr;

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

Arr::map()

O método Arr::map itera por todos os valores da matriz e passa cada valor e chave para o callback especificado. O valor da matriz é substituído pelo valor retornado pelo 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::mapSpread()

O método Arr::mapSpread itera sobre o array, passando cada valor de item aninhado para o closure fornecido. O encerramento fica livre para modificar o item e devolvê-lo, formando assim um novo array de itens modificados:

    use Illuminate\Support\Arr;

    $array = [
        [0, 1],
        [2, 3],
        [4, 5],
        [6, 7],
        [8, 9],
    ];

    $mapped = Arr::mapSpread($array, function (int $even, int $odd) {
        return $even + $odd;
    });

    /*
        [1, 5, 9, 13, 17]
    */

Arr::mapWithKeys()

O método Arr::mapWithKeys executa uma iteração através do array e passa cada valor para o callback especificado. O callback deve retornar um array associativo contendo um único par de chave/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()

O método Arr::only retorna apenas as chaves/pares de valores especificados do array fornecido:

    use Illuminate\Support\Arr;

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

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

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

Arr::pluck()

O método Arr::pluck recupera todos os valores para uma determinada chave de um array:

    use Illuminate\Support\Arr;

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

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

    // ['Taylor', 'Abigail']

Você também pode especificar como deseja que o resultado seja chaveado:

    use Illuminate\Support\Arr;

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

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

Arr::prepend()

O método arr::prepend insere um elemento no começo de uma matriz.

    use Illuminate\Support\Arr;

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

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

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

Se necessário, você pode especificar a chave que deve ser usada para o valor:

    use Illuminate\Support\Arr;

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

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

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

Arr::prependKeysWith()

A função Arr::prependKeysWith antepõe todos os nomes de chaves de uma matriz associativa com o prefixo especificado:

    use Illuminate\Support\Arr;

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

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

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

Arr::pull()

O método Arr::pull retorna e remove uma chave/par de valores de um array:

    use Illuminate\Support\Arr;

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

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

    // $name: Desk

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

O valor padrão pode ser passado como o terceiro argumento do método. Este valor é retornado se a chave não existir:

    use Illuminate\Support\Arr;

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

Arr::query()

O método Arr::query converte o array em uma query string:

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

O método Arr::random retorna um valor aleatório de um array:

    use Illuminate\Support\Arr;

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

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

    // 4 - (retrieved randomly)

Você também pode especificar o número de itens a serem retornados como um segundo argumento opcional. Observe que o fornecimento desse argumento retorna um array mesmo se somente um item tiver sido solicitado.

    use Illuminate\Support\Arr;

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

    // [2, 5] - (retrieved randomly)

Arr::set()

O método Arr::set define um valor num array profundamente aninhado, utilizando a notação de "ponto":

    use Illuminate\Support\Arr;

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

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

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

arr::shuffle()

O método Arr::shuffle permite misturar os itens no array de maneira aleatória:

    use Illuminate\Support\Arr;

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

    // [3, 2, 5, 1, 4] - (generated randomly)

Arr::sort()

O método Arr::sort ordena uma matriz por seus valores:

    use Illuminate\Support\Arr;

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

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

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

Você também pode ordenar um array pelos resultados a partir de uma closure:

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

O método Arr::sortDesc ordena um array de maneira decrescente em função dos seus valores:

    use Illuminate\Support\Arr;

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

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

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

Você também pode ordenar um array pelos resultados de um determinado closure:

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

O método Arr::sortRecursive ordena de forma recursiva um array utilizando a função sort para sub-arrays com índice numérico e a função ksort para sub-arrays associativos:

    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'],
        ]
    */

Se você quiser que os resultados sejam ordenados em ordem descendente, poderá usar o método Arr::sortRecursiveDesc.

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

Arr::take()

O método Arr::take retorna um novo array com o número especificado de itens:

    use Illuminate\Support\Arr;

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

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

    // [0, 1, 2]

Você também pode passar um número negativo para pegar o número especificado de itens da parte final do array:

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

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

    // [4, 5]

Arr::toCssClasses()

O método Arr::toCssClasses compila condicionalmente uma string de classe CSS. O método aceita um array com as classes que você deseja adicionar; o nome do campo tem que ser uma classe ou a palavra-chave '*' para incluir todos os elementos; o valor é uma expressão lógica:

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

O comando Arr::toCssStyles compila condicionalmente uma string de estilo de CSS. O método aceita um array de classes onde a chave do array contém a classe ou classes que você deseja adicionar, enquanto o valor é uma expressão booleana. Se o elemento do array tiver uma chave numérica, ela será sempre incluída na lista de classes renderizadas:

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 é o que dá poder à funcionalidade do Laravel, permitindo mesclar classes com uma "mochila" de atributos de um componente Blade, bem como a diretiva @class do Blade.

Arr::undot()

O método Arr::undot expande um array unidimensional que utiliza notação de pontos em um 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()

O método Arr::where filtra um array utilizando o 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()

O método Arr::whereNotNull remove todos os valores null do array fornecido:

    use Illuminate\Support\Arr;

    $array = [0, null];

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

    // [0 => 0]

Arr::wrap()

O método Arr::wrap envolve o valor indicado em uma matriz. Se o valor indicado já for uma matriz, ele será devolvido sem modificações:

    use Illuminate\Support\Arr;

    $string = 'Laravel';

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

    // ['Laravel']

Se o valor for null, será retornado um array vazio:

    use Illuminate\Support\Arr;

    $array = Arr::wrap(null);

    // []

data_fill()

A função data_fill define um valor ausente dentro de um array ou objeto aninhado usando a notação "ponto":

    $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]]]

Essa função também aceita o símbolo "asterisco" como um indicador genérico e preencherá o alvo de acordo com o seguinte:

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

A função data_get recupera um valor de um array ou objeto aninhado utilizando a notação "ponto":

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

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

    // 100

A função data_get também aceita um valor padrão que será retornado caso a chave especificada não seja encontrada:

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

    // 0

O recurso aceita também os símbolos "*" (asteriscos) que podem especificar qualquer chave do array ou objeto.

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

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

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

Os marcadores de posição (placeholders) {first} e {last} podem ser utilizados para obter os elementos primário ou secundário num array:

    $flight = [
        'segments' => [
            ['from' => 'LHR', 'departure' => '9:00', 'to' => 'IST', 'arrival' => '15:00'],
            ['from' => 'IST', 'departure' => '16:00', 'to' => 'PKX', 'arrival' => '20:00'],
        ],
    ];

    data_get($flight, 'segments.{first}.arrival');

    // 15:00

data_set()

A função data_set define um valor dentro de um array ou objeto aninhado usando a notação "ponto":

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

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

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

Esta função também aceita curingas usando asteriscos e definirá valores no alvo de acordo:

    $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 padrão, todos os valores existentes são substituídos. Se pretender definir apenas um valor que ainda não exista, pode passar "false" como o quarto argumento da função:

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

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

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

data_forget()

A função data_forget remove um valor dentro de um array ou objeto aninhado usando a notação "ponto":

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

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

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

Esta função também aceita curingas usando asteriscos e removerá os valores do destino de acordo:

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

A função head retorna o primeiro elemento do array:

    $array = [100, 200, 300];

    $first = head($array);

    // 100

last()

A função last retorna o último elemento do array informado:

    $array = [100, 200, 300];

    $last = last($array);

    // 300

Números

Number::abbreviate()

O método Number::abbreviate devolve o formato legível por seres humanos do valor numérico fornecido com uma abreviação para as 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()

O método Number::clamp garante que um número específico permanece dentro de uma faixa especificada. Se o número for menor do que o mínimo, será retornado o valor mínimo. Se o número for maior do que o máximo, será retornado o 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()

O método Number::currency retorna a representação da moeda do valor fornecido como uma string:

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

O método Number::fileSize retorna a representação do tamanho de um arquivo de um valor em bytes como uma string:

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

O método Number::forHumans retorna o formato legível por humanos do valor numérico fornecido:

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

O método Number::format formata o número fornecido em uma string específica do local:

    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

Número::ordinal()

O método Number::ordinal retorna a representação numérica ordinal de um número:

    use Illuminate\Support\Number;

    $number = Number::ordinal(1);

    // 1st

    $number = Number::ordinal(2);

    // 2nd

    $number = Number::ordinal(21);

    // 21st

Número::percentage()

O método Number::percentage retorna a representação percentual do valor especificado como uma cadeia de caracteres:

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

O método Number::spell converte um número em uma sequência de palavras:

    use Illuminate\Support\Number;

    $number = Number::spell(102);

    // one hundred and two

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

    // quatre-vingt-huit

O argumento after permite-lhe especificar um valor após o qual todos os números devem ser representados por palavras:

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

    // 10

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

    // eleven

O argumento until permite especificar um valor antes do qual todos os números devem ser escritos:

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

    // five

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

    // 10

Number::useLocale()

O método Number::useLocale define o localização de números globalmente padrão, afetando a forma como os números e moedas são formatados durante as chamadas posteriores aos métodos da classe Number:

    use Illuminate\Support\Number;

    /**
     * Inicialize qualquer serviço de aplicativo.
     */
    public function boot(): void
    {
        Number::useLocale('de');
    }

Número::withLocale()

O método Number::withLocale executa o closure especificado usando a locação indicada e, em seguida restaura a locação original após o invocador da função ter sido executado.

    use Illuminate\Support\Number;

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

Caminhos

app_path()

A função app_path retorna o caminho total para o diretório app da sua aplicação. Você também pode usar a função app_path para gerar um caminho totalmente qualificado para um ficheiro relativo ao diretório da aplicação:

    $path = app_path();

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

base_path()

A função base_path retorna o caminho total do diretório raiz da sua aplicação. Você pode também utilizar a função base_path para gerar um caminho de um ficheiro dado em relação ao diretório raiz do projeto:

    $path = base_path();

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

config_path()

A função config_path retorna o caminho total do diretório de configurações da sua aplicação. Você também pode usar a função config_path para gerar um caminho para um determinado arquivo dentro do diretório de configurações da aplicação:

    $path = config_path();

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

database_path()

A função database_path retorna o caminho total do diretório de banco de dados da aplicação. Também é possível utilizar a função database_path para gerar um caminho de um determinado arquivo no diretório de banco de dados:

    $path = database_path();

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

lang_path()

A função lang_path retorna o caminho total do diretório lang da aplicação. Também é possível utilizar a função lang_path para gerar um caminho totalmente qualificado de um arquivo específico dentro desse diretório:

    $path = lang_path();

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

NOTA

Por padrão, o esqueleto da aplicação do Laravel não inclui a pasta lang. Se pretender personalizar os ficheiros de linguagem do Laravel, você pode publicá-los através do comando lang:publish do Artisan.

mix()

A função mix retorna o caminho para um arquivo do Mix com versão:

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

public_path()

A função public_path retorna o caminho total do diretório público da aplicação. Você também pode usar a função public_path para gerar um caminho totalmente qualificado de um determinado arquivo dentro deste diretório:

    $path = public_path();

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

resource_path()

A função resource_path retorna o caminho totalmente qualificado do diretório de recursos da aplicação. Você também pode usar a função resource_path para gerar um caminho totalmente qualificado de um arquivo específico dentro do diretório de recursos:

    $path = resource_path();

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

storage_path()

A função storage_path retorna o caminho totalmente qualificado do diretório de armazenamento da aplicação. Você também pode usar a função storage_path para gerar um caminho totalmente qualificado de um determinado arquivo dentro do diretório de armazenamento:

    $path = storage_path();

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

URL

action()

A função action gera um URL para a ação do controlador informado:

    use App\Http\Controllers\HomeController;

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

Se o método aceitar parâmetros de rota, você pode passar esses parâmetros como um segundo argumento do método:

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

asset()

A função asset gera um URL para um arquivo estático usando o esquema atual de requisição (HTTP ou HTTPS):

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

Você pode configurar o host da URL do arquivo estático definindo a variável ASSET_URL em seu arquivo .env. Isso é útil se você hospedar seus arquivos estáticos em um serviço externo, como Amazon S3 ou outro CDN:

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

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

route()

A função route gera um endereço da Web para um roteamento nomeado:

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

Se a rota aceitar parâmetros, você poderá passar-lhes como o segundo argumento da função:

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

Por padrão, a função route gera um URL absoluto. Se você desejar gerar um URL relativo, poderá passar false como o terceiro argumento da função:

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

secure_asset()

A função secure_asset gera uma URL para um arquivo estático utilizando HTTPS:

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

secure_url()

A função secure_url gera uma URL totalmente qualificada de HTTPS para o caminho especificado. Os segmentos adicionais da URL podem ser passados como um segundo argumento na função:

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

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

to_route()

A função to_route gera uma resposta de redirecionamento HTTP para uma determinada rota nomeada:

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

Se necessário, você pode passar o código de resposta do HTTP que deve ser atribuído ao redirecionamento e quaisquer cabeçalhos adicionais da resposta como o terceiro e quarto argumentos para a função to_route:

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

`url()

A função url gera uma URL totalmente qualificada para o caminho indicado:

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

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

Se não for fornecido nenhum caminho, será retornada uma instância do Illuminate\Routing\UrlGenerator:

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

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

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

Diversos

abort()

A função abort envia uma exceção HTTP, que será renderizada pelo hander de exceções:

    abort(403);

Você também pode fornecer a mensagem da exceção e cabeçalhos de resposta personalizados que devem ser enviados ao navegador:

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

abort_if()

A função abort_if lança uma exceção de HTTP se uma expressão booleana for avaliada como true:

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

Tal como no método abort, é possível fornecer também o texto de resposta da exceção, na terceira posição, e um conjunto de cabeçalhos personalizados da resposta, na quarta posição, para a função.

abort_unless()

A função abort_unless joga uma exceção de HTTP se uma expressão lógica dada avaliar como false:

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

Assim como o método abort, você também pode fornecer o texto da resposta da exceção como o terceiro argumento e um array de cabeçalhos de resposta personalizados como o quarto argumento para a função.

app()

A função app retorna a instância do contêiner de serviços:

    $container = app();

Você pode passar um nome de classe ou de interface para resolvê-la do contêiner:

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

auth()

A função auth retorna uma instância do autenticador (authenticator. Você pode usá-la como uma alternativa à fadade Auth:

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

Se necessário, você pode especificar a instância do guard que deseja acessar:

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

back()

A função back gera uma resposta de redirecionamento HTTP para o local anterior do usuário:

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

    return back();

bcrypt()

A função bcrypt hashes o valor fornecido usando Bcrypt. Você pode usar esta função como uma alternativa à facade Hash:

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

blank()

A função blank determina se o valor fornecido é "em branco", isto é, um espaço ou uma linha vazia:

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

    // true

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

    // false

Para a operação inversa de blank ver o método filled.

broadcast()

A função broadcast (transmite) o evento especificado aos seus ouvinte:

    broadcast(new UserRegistered($user));

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

cache()

A função cache pode ser usada para recuperar valores do cache. Caso a chave especificada não exista no cache, um valor padrão opcional será retornado:

    $value = cache('key');

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

Você pode adicionar itens ao cache, passando uma matriz de pares chave/valor para a função. Além disso, você deve passar o número de segundos ou duração que o valor do cache será considerado válido:

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

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

class_uses_recursive()

A função class_uses_recursive retorna todos os traits usados por uma classe, incluindo os traits usados por todas as suas classes pai:

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

collect()

A função collect cria uma instância de collections a partir do valor fornecido:

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

config()

A função config obtém o valor de uma variável de configuração. Os valores da configuração podem ser acessados utilizando a sintaxe "ponto", que inclui o nome do ficheiro e a opção que pretende acessar. Pode ser especificado um valor padrão, que é retornado se não existir uma opção de configuração:

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

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

Você pode configurar variáveis de configuração durante a execução passando um array de pares chave/valor. No entanto, note que esta função afeta apenas o valor da configuração para a solicitação atual e não atualiza os valores reais da sua configuração:

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

context()

A função context obtém o valor do contexto atual. Pode ser especificado um valor padrão que é retornado se a chave de contexto não existir:

    $value = context('trace_id');

    $value = context('trace_id', $default);

É possível definir valores de contexto passando um array de pares chave/valor:

    use Illuminate\Support\Str;

    context(['trace_id' => Str::uuid()->toString()]);

cookie()

A função cookie cria uma nova instância de cookie:

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

csrf_field()

A função csrf_field gera um campo de entrada oculto HTML contendo o valor do token de CSRF. Por exemplo, usando a sintaxe Blade:

    {{ csrf_field() }}

csrf_token()

A função csrf_token recupera o valor do token de segurança atual:

    $token = csrf_token();

decrypt()

A função decrypt permite decifrar o valor fornecido, podendo esta ser utilizada como alternativa à facade Crypt:

    $password = decrypt($value);

dd()

A função dd mostra as variáveis fornecidas e encerra a execução do script.

    dd($value);

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

Se você não quiser interromper a execução de seu script, use a função dump.

method-dispatch()

A função dispatch envia o trabalho indicado a fila de tarefas do Laravel:

    dispatch(new App\Jobs\SendEmails);

dispatch_sync()

A função dispatch_sync coloca o trabalho fornecido na fila para o envio síncrono para que ele seja processado imediatamente:

    dispatch_sync(new App\Jobs\SendEmails);

dump()

A função dump exibe as variáveis indicadas:

    dump($value);

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

Se você deseja interromper a execução do script após o envio das variáveis, utilize a função dd.

encrypt()

A função encrypt encripta o valor fornecido, que poderá ser utilizada como alternativa ao pacote de funções Crypt:

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

env()

A função env recupera o valor de uma variável de ambiente ou retorna um valor padrão:

    $env = env('APP_ENV');

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

ATENÇÃO

Se você executar o comando config:cache durante o processo de implantação, certifique-se de estar chamando a função env apenas de dentro dos seus arquivos de configuração. Depois que a configuração for armazenada em cache, o arquivo .env não será carregado e todas as chamadas para a função env retornarão null.

event()

A função event envia o evento especificado a seus ouvintes:

    event(new UserRegistered($user));

fake()

A função fake resolve um singleton Faker do container, que pode ser útil ao criar dados falsos em factories de modelos, carregamento de banco de dados, testes e prototipagem de visualizações:

@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 padrão, a função fake utiliza a opção de configuração app.faker_locale em sua configuração no arquivo config/app.php. Normalmente essa opção de configuração é definida através da variável de ambiente APP_FAKER_LOCALE. É possível também especificar o idioma passando-o à função fake. Cada idioma resolve um singleton individual:

    fake('nl_NL')->name()

filled()

A função filled determina se o valor especificado não é "vazio".

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

    // true

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

    // false

Para a função inversa de filled, consulte o método blank.

info()

A função info irá escrever informações no registro da sua aplicação Logging:

    info('Some helpful information!');

Um conjunto de dados contextuais pode também ser passado para a função:

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

literal()

A função literal cria uma nova instância do tipo stdClass com os argumentos nomeados fornecidos como propriedades:

    $obj = literal(
        name: 'Joe',
        languages: ['PHP', 'Ruby'],
    );

    $obj->name; // 'Joe'
    $obj->languages; // ['PHP', 'Ruby']

logger()

A função logger pode ser utilizada para escrever uma mensagem de nível debug no arquivo log:

    logger('Debug message');

É possível enviar uma série de dados contextuais para a função:

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

Se não for passado um valor para a função, será retornada uma instância de logger:

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

method_field()

A função method_field gera um campo de entrada HTML hidden contendo o valor falsificado do verbo HTTP do formulário. Por exemplo, usando a sintaxe do Blade:

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

now()

A função now cria uma nova instância de Illuminate\Support\Carbon para o momento atual:

    $now = now();

old()

A função old recupera um valor de entrada antigo passado à sessão:

    $value = old('value');

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

Uma vez que o valor "padrão" fornecido como segundo argumento da função old é, frequentemente, um atributo de um modelo Eloquent, o Laravel permite-lhe passar o modelo Eloquent em si como segundo argumento para a função old. Neste caso, o primeiro argumento passado à função old será considerado como nome do atributo Eloquent que deve ser utilizado como "valor padrão":

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

    // Is equivalent to...

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

once()

A função once executa o callback definido e armazena o resultado em memória durante a requisição. Quaisquer chamadas subsequentes à função once, com o mesmo callback, devolvem o resultado previamente armazenado:

    function random(): int
    {
        return once(function () {
            return random_int(1, 1000);
        });
    }

    random(); // 123
    random(); // 123 (cached result)
    random(); // 123 (cached result)

Quando a função once é executada dentro de uma instância de objeto, o resultado armazenado em cache será exclusivo para essa instância de objeto:

<?php

class NumberService
{
    public function all(): array
    {
        return once(fn () => [1, 2, 3]);
    }
}

$service = new NumberService;

$service->all();
$service->all(); // (cached result)

$secondService = new NumberService;

$secondService->all();
$secondService->all(); // (resultado em cache)

optional()

A função optional aceita qualquer argumento e permite o acesso à propriedades ou métodos desse objeto. Se o objeto for null, as propriedades e os métodos retornarão null em vez de causar um erro:

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

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

A função optional também aceita um closure como segundo argumento, que será invocado se o valor fornecido como primeiro argumento não for nulo:

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

policy()

O método policy recupera uma instância de política para uma classe específica:

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

``redirect()`

A função redirect retorna uma resposta de redirecionamento HTTP, ou a instância da função redirector quando não for utilizada com parâmetros:

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

    return redirect('/home');

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

report()

A função report informará uma exceção utilizando o seu manipulador de exceções:

    report($e);

A função report também aceita um argumento do tipo string. Se for passada uma string à função, a função irá criar uma exceção com a string como mensagem:

    report('Something went wrong.');

report_if()

A função report_if relatará uma exceção usando o seu gerenciador de exceções, se a condição for verdadeira:

    report_if($shouldReport, $e);

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

report_unless()

A função report_unless relatará a exceção usando o seu manipulador de exceções caso a condição for falsa:

    report_unless($reportingDisabled, $e);

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

request()

A função request retorna a instância atual da requisição ou obtém o valor de um campo de entrada da requisição ativa:

    $request = request();

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

rescue()

A função rescue executa um closure especificado e captura quaisquer exceções que sejam geradas durante a sua execução. Todas as exceções capturadas são enviadas para o mecanismo de tratamento de exceções; no entanto, o pedido continua a ser processado:

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

Você também pode passar um segundo argumento à função rescue. Este argumento será o valor "padrão" que deverá ser retornado se uma exceção ocorrer ao executar a closure:

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

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

Um argumento report pode ser passado para a função rescue, que determina se a exceção deve ser relatada pela função report:

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

resolve()

A função resolve resolve um nome de classe ou interface para uma instância usando o conjunto de serviços:

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

response()

A função response cria uma instância de resposta ou obtém uma instância do factory de respostas:

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

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

retry()

A função retry tenta executar o callback fornecido até atingir o limite máximo de tentativas especificadas. Se o callback não lançar uma exceção, seu valor será retornado. Se o callback lançar uma exceção, ele será automaticamente reexecutado. Se o número máximo de tentativas for excedido, a exceção será jogada:

    return retry(5, function () {
        // Tente 5 vezes enquanto descansa 100ms entre as tentativas...
    }, 100);

Se você preferir calcular manualmente o número de milésimos de segundo para esperar entre as tentativas, você poderá passar um closure como terceiro argumento à função retry:

    use Exception;

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

Para maior conveniência, você pode fornecer um array como o primeiro argumento da função retry. Este array será usado para determinar a quantidade de milésimos de segundo que devem passar entre tentativas subseqüentes.

    return retry([100, 200], function () {
        // Durma por 100 ms na primeira tentativa, 200 ms na segunda tentativa...
    });

Para tentar novamente apenas sob condições específicas, você pode passar um encerramento como o quarto argumento para a função retry:

    use Exception;

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

session()

A função session pode ser usada para obter ou definir valores de (sessão:

    $value = session('key');

Você pode definir valores passando um array de pares chave/valor para a função:

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

Se nenhum valor for passado para a função, o valor armazenado da sessão será retornado:

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

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

tap()

A função tap aceita dois argumentos: um valor aleatório $value e um bloqueio (closure). O valor de $value será passado ao closure e, em seguida, retornado pela função tap. O valor de retorno do closure é irrelevante:

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

        $user->save();
    });

Se não for passado um closure para a função tap, você pode chamar qualquer método do valor especificado. O valor de retorno do método chamado será sempre o $value, independentemente do que o método realmente retorne em sua definição. Por exemplo, o método Eloquent update geralmente retorna um número inteiro. No entanto, podemos forçar o método a retornar o modelo em si chamando a função tap para o método de atualização:

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

Para adicionar um método tap a uma classe, você pode adicionar a trait Illuminate\Support\Traits\Tappable à classe. O método tap desta trait aceita como único argumento um Closure. A própria instância do objeto será passada para o Closure e, em seguida, devolvido pelo método tap:

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

throw_if()

A função throw_if lança a exceção fornecida se uma expressão booleana dada for verdadeira:

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

    throw_if(
        ! Auth::user()->isAdmin(),
        AuthorizationException::class,
        'You are not allowed to access this page.'
    );

throw_unless()

A função throw_unless lança a exceção dada se uma expressão lógica for falsa:

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

    throw_unless(
        Auth::user()->isAdmin(),
        AuthorizationException::class,
        'You are not allowed to access this page.'
    );

today()

A função today() cria uma nova instância de Illuminate\Support\Carbon para a data atual:

    $today = today();

trait_uses_recursive()

A função trait_uses_recursive retorna todos as traits usadas por uma trait:

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

transform()

A função transform executa um closure em um determinado valor se o valor não for blank e então retorna o valor de retorno do closure:

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

    $result = transform(5, $callback);

    // 10

Um valor padrão ou uma chave de closure podem ser passados como o terceiro argumento para a função. Esse valor será retornado se o valor for em branco:

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

    // O valor está em branco

validator()

A função validator cria uma nova instância do conjunto de regras de validação com os argumentos passados. Pode ser usada como alternativa à interface Validator:

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

value()

A função value retorna o valor que foi passado à mesma. No entanto, se for passada uma sub-rotina para essa função, a sub-rotina será executada e seu valor de retorno será retornado:

    $result = value(true);

    // true

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

    // false

Pode ser passado mais de um argumento para a função value. Se o primeiro argumento for uma chave, os parâmetros adicionais são passados como argumentos para a chave, caso contrário, eles serão ignorados:

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

view()

A função view recupera uma instância da classe View:

    return view('auth.login');

with()

A função with retorna o valor que lhe é passado. Se um closure for passado como segundo argumento à função, esse closure será executado e o seu valor será devolvido:

    $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

Outros Serviços

Benchmarking

Às vezes pode ser necessário testar rapidamente o desempenho de certas partes da sua aplicação. Nestas ocasiões, você poderá utilizar a classe de suporte Benchmark para medir o número de milésimos de segundo necessários ao final da execução dos callbacks:

    <?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
    ]);

Os callbacks fornecidos serão executados uma única vez por padrão (uma iteração) e sua duração será exibida no navegador/console.

Para invocar um callback mais de uma vez, você pode especificar o número de repetições que o callback deve ser invocado como segundo argumento do método. Ao executar um callback mais do que uma vez, a classe Benchmark irá retornar a média das milésimas de segundos necessárias para executar o callback em todas as repetições:

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

Às vezes, você pode querer comparar o desempenho de uma função callback enquanto ainda obtém o valor retornado por ela. O método value retorna um par contendo o valor retornado pela função callback e a quantidade de milésimos de segundo necessários para executá-la:

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

Datas

O Laravel inclui Carbon, uma poderosa biblioteca de manipulação de datas e horários. Para criar uma nova instância do Carbon, você pode utilizar a função now. Essa função está disponível em toda parte na sua aplicação Laravel:

$now = now();

Ou você pode criar uma nova instância de Carbon, usando a classe Illuminate\Support\Carbon:

use Illuminate\Support\Carbon;

$now = Carbon::now();

Para uma discussão completa sobre o Carbon e suas características, consulte a documentação oficial do Carbon.

Lottery

A classe Lottery do Laravel pode ser usada para executar callbacks com base em um conjunto de chances definidas. Isso pode ser muito útil quando você deseja executar apenas código para um percentual das suas solicitações recebidas:

    use Illuminate\Support\Lottery;

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

Você pode combinar a classe Lottery do Laravel com outros recursos do Laravel. Por exemplo, você talvez deseje informar apenas uma pequena porcentagem de consultas lentas ao seu manipulador de exceções. E como a classe lottery é invocável, nós podemos passar uma instância da classe para qualquer método que aceite invocáveis:

    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.')),
    );

Teste de Lottery

O Laravel disponibiliza alguns métodos simples para que você possa testar facilmente as chamadas de lottery no seu aplicativo:

    // A Lottery sempre ganhará...
    Lottery::alwaysWin();

    // A Lottery sempre perderá...
    Lottery::alwaysLose();

    // A Lottery vai ganhar, depois perder e, finalmente, retornar ao comportamento normal...
    Lottery::fix([true, false]);

    // A Lottery voltará ao comportamento normal...
    Lottery::determineResultsNormally();

Pipeline

O recurso Pipeline do Laravel fornece uma maneira conveniente de "concatenar" um determinado tipo de entrada através de uma série de classes invocáveis e closures dando a cada classe a oportunidade de inspecionar ou modificar a entrada e fazer uma chamada para o próximo objeto chamável do 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 você pode verificar, cada classe ou closure invocável na pipeline recebe o input e um closure $next. A invocação de um closure $next inicia a próxima chamada possível na pipeline. Como você deve ter reparado, isto é muito semelhante ao middleware.

Quando o último invocável na lista chamar o closure de $next, o invocável fornecido ao método then será executado. Normalmente, esse chamável retorna simplesmente a entrada especificada.

Claro, como discutido anteriormente, você não está limitado a apenas fornecer closures para sua pipeline. Também é possível fornecer classes com métodos de invocação. Se um nome da classe for fornecido, ela será instanciada por meio do conjunto de serviços do Laravel, permitindo que dependências sejam injetadas na classe invocável:

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

Sleep

A classe Sleep do Laravel é uma camada leve que engloba as funções nativas "sleep" e "usleep" do PHP, oferecendo maior capacidade de teste, ao mesmo oferecendo uma API amigável para o desenvolvedor quando se trabalha com o tempo:

    use Illuminate\Support\Sleep;

    $waiting = true;

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

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

A classe Sleep contém vários métodos que permitem trabalhar com as diferentes unidades de tempo:

    // Pausar a execução por 90 segundos...
    Sleep::for(1.5)->minutes();

    // Pausar a execução por 2 segundos...
    Sleep::for(2)->seconds();

    // Pausar a execução por 500 milissegundos...
    Sleep::for(500)->milliseconds();

    // Pausar a execução por 5.000 microssegundos...
    Sleep::for(5000)->microseconds();

    // Pausar a execução até um determinado momento...
    Sleep::until(now()->addMinute());

    // Alias ​​da função "sleep" nativa do PHP...
    Sleep::sleep(2);

    // Alias ​​da função "usleep" nativa do PHP...
    Sleep::usleep(5000);

Para combinar facilmente as unidades de tempo, você pode utilizar o método and:

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

Testando o sleep

Ao testar código que usa a classe Sleep ou funções de pausa nativas do PHP, seu teste fará com que sua execução seja interrompida. Como esperado, isso faz com que seu conjunto de testes seja significativamente mais lento. Por exemplo, imagine que você está testando o código abaixo:

    $waiting = /* ... */;

    $seconds = 1;

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

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

Normalmente, o teste deste código levaria no mínimo um segundo. Por sorte, a classe Sleep permite que possamos "iludir" o sleep para que o nosso conjunto de testes permaneça rápido:

Pest

it('waits until ready', function () {
    Sleep::fake();

    // ...
});

PHPUnit

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

    // ...
}

Ao simular a classe "Sleep", para a execução do programa mas, é ignorado o período de espera real, que leva a um teste significativamente mais rápido.

Uma vez que a classe 'Sleep' foi falsificada, é possível fazer afirmações esperadas contra o "sleep" que deveriam ter ocorrido. Para ilustrar isto, vamos imaginar que estamos testando códigos que pausam a execução três vezes, aumentando cada pausa por um segundo. Usando o método assertSequence, podemos afirmar que nosso código "pausou" pelo tempo correto enquanto mantemos nosso teste rápido:

Pest

it('checks if ready three times', function () {
    Sleep::fake();

    // ...

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

PHPUnit

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(),
    ]);
}

Claro que a classe Sleep oferece uma variedade de outras asserções que você pode usar ao fazer testes:

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

    // Afirme que o sleep foi chamado 3 vezes...
    Sleep::assertSleptTimes(3);

    // Afirme contra a duração do sleep...
    Sleep::assertSlept(function (Duration $duration): bool {
        return /* ... */;
    }, times: 1);

    // Afirme que a classe Sleep nunca foi invocada...
    Sleep::assertNeverSlept();

    // Afirme que, mesmo que Sleep tenha sido chamado, nenhuma execução pausada ocorreu...
    Sleep::assertInsomniac();

Às vezes pode ser útil executar uma ação sempre que um sleep falso ocorrer no código da aplicação. Para conseguir isto, forneça uma função de retorno para o método whenFakingSleep. No exemplo seguinte, utilizamos as ajudas de manipulação do tempo em Laravel para avançar instantaneamente o tempo pelo período de cada sleep:

use Carbon\CarbonInterval as Duration;

$this->freezeTime();

Sleep::fake();

Sleep::whenFakingSleep(function (Duration $duration) {
    // Tempo de progresso ao fingir o sleep...
    $this->travel($duration->totalMilliseconds)->milliseconds();
});

Como o avanço do tempo é um requisito comum, o método fake aceita um argumento syncWithCarbon para manter o Carbon sincronizado quando estiver dormindo durante um teste:

Sleep::fake(syncWithCarbon: true);

$start = now();

Sleep::for(1)->second();

$start->diffForHumans(); // 1 segundo atrás

O Laravel usa a classe Sleep internamente sempre que faz uma pausa na execução. Por exemplo, a função de ajuda retry usa a classe Sleep quando está dormindo, o que melhora a capacidade de testar a utilização da ajuda.