> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Funciones auxiliares

> Recopilación de las funciones auxiliares globales de Laravel y de las clases Arr y Number, con ejemplos prácticos.

## Qué son las funciones auxiliares

Laravel ofrece muchas funciones PHP globales (helpers). El propio framework las usa internamente, pero también puedes utilizarlas libremente en tu aplicación.

Las funciones auxiliares se agrupan en las siguientes categorías:

* **Arrays y objetos**: la clase `Arr::` y funciones como `data_get()`.
* **Números**: la clase `Number::`.
* **Rutas del sistema de ficheros**: funciones para obtener rutas como `app_path()` y `storage_path()`.
* **URLs**: funciones de generación de URL como `route()`, `url()` y `asset()`.
* **Otras**: utilidades muy utilizadas como `config()`, `collect()` o `auth()`.

<Info>
  Las funciones auxiliares pueden llamarse desde cualquier lugar sin necesidad de `use`. Para las clases `Arr` o `Number` sí necesitas importarlas con `use Illuminate\Support\Arr;`, etc.
</Info>

## Helpers de arrays (clase `Arr`)

### `Arr::get()`: obtener valores anidados con notación de punto

Recupera valores anidados de un array multidimensional utilizando notación de punto (`foo.bar.baz`). Si la clave no existe se devuelve el valor por defecto.

```php theme={null}
use Illuminate\Support\Arr;

$config = [
    'database' => [
        'connections' => [
            'mysql' => ['host' => '127.0.0.1', 'port' => 3306],
        ],
    ],
];

$host = Arr::get($config, 'database.connections.mysql.host');
// '127.0.0.1'

// Valor por defecto si la clave no existe
$charset = Arr::get($config, 'database.connections.mysql.charset', 'utf8mb4');
// 'utf8mb4'
```

<Tip>
  La función global `data_get()` ofrece la misma funcionalidad. Además, funciona sobre objetos `Arrayable` como las relaciones de Eloquent, por lo que es más versátil.
</Tip>

### `Arr::set()`: asignar un valor anidado

```php theme={null}
use Illuminate\Support\Arr;

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

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

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

### `Arr::has()`: comprobar la existencia de una clave

```php theme={null}
use Illuminate\Support\Arr;

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

$hasName = Arr::has($array, 'product.name');
// true

// Comprobar la existencia de varias claves
$hasAll = Arr::has($array, ['product.name', 'product.price']);
// true
```

### `Arr::only()` / `Arr::except()`: filtrar o excluir claves

Muy útiles para quedarte solo con las claves necesarias, o excluir claves indeseadas, de los datos de una petición o de un array de configuración.

```php theme={null}
use Illuminate\Support\Arr;

$user = [
    'id' => 1,
    'name' => 'Ana García',
    'email' => 'ana@example.com',
    'password' => 'secret',
    'role' => 'admin',
];

// Solo las claves indicadas
$safe = Arr::only($user, ['id', 'name', 'email']);
// ['id' => 1, 'name' => 'Ana García', 'email' => 'ana@example.com']

// Excluye la clave password
$public = Arr::except($user, ['password']);
// ['id' => 1, 'name' => 'Ana García', 'email' => '...', 'role' => 'admin']
```

### `Arr::pluck()`: extraer una clave concreta de arrays anidados

```php theme={null}
use Illuminate\Support\Arr;

$records = [
    ['user' => ['id' => 1, 'name' => 'Ana García']],
    ['user' => ['id' => 2, 'name' => 'Luis Pérez']],
];

$names = Arr::pluck($records, 'user.name');
// ['Ana García', 'Luis Pérez']

// El tercer argumento indica la clave del array resultante
$nameById = Arr::pluck($records, 'user.name', 'user.id');
// [1 => 'Ana García', 2 => 'Luis Pérez']
```

### `Arr::first()` / `Arr::last()`: primer o último elemento que cumple una condición

```php theme={null}
use Illuminate\Support\Arr;

$prices = [150, 80, 200, 50, 120];

// Primer precio >= 100
$first = Arr::first($prices, fn ($price) => $price >= 100);
// 150

// Valor por defecto si no lo cumple ninguno
$first = Arr::first($prices, fn ($price) => $price >= 500, 0);
// 0

// Último elemento (sin condición)
$last = Arr::last($prices);
// 120
```

### `Arr::flatten()`: aplanar un array multidimensional

```php theme={null}
use Illuminate\Support\Arr;

$tags = [
    'frontend' => ['html', 'css', 'javascript'],
    'backend'  => ['php', 'laravel', 'mysql'],
];

$allTags = Arr::flatten($tags);
// ['html', 'css', 'javascript', 'php', 'laravel', 'mysql']
```

### `Arr::wrap()`: garantizar que el valor sea un array

Si el valor no es un array lo envuelve en uno. Con `null` se obtiene un array vacío. Ideal para aceptar argumentos flexibles en funciones.

```php theme={null}
use Illuminate\Support\Arr;

Arr::wrap('Laravel');
// ['Laravel']

Arr::wrap(['Laravel', 'PHP']);
// ['Laravel', 'PHP']

Arr::wrap(null);
// []
```

### `Arr::sort()`: ordenar por valor

```php theme={null}
use Illuminate\Support\Arr;

$fruits = ['banana', 'apple', 'cherry'];
$sorted = Arr::sort($fruits);
// ['apple', 'banana', 'cherry']

// Ordenar mediante una closure
$products = [
    ['name' => 'Portátil', 'price' => 1200],
    ['name' => 'Ratón', 'price' => 35],
    ['name' => 'Teclado', 'price' => 80],
];

$byPrice = Arr::sort($products, fn ($product) => $product['price']);
// Orden: Ratón, Teclado, Portátil
```

### `Arr::dot()` / `Arr::undot()`: convertir a notación de punto y viceversa

```php theme={null}
use Illuminate\Support\Arr;

$nested = [
    'user' => [
        'profile' => ['name' => 'Ana García', 'age' => 28],
    ],
];

$dotted = Arr::dot($nested);
// ['user.profile.name' => 'Ana García', 'user.profile.age' => 28]

// Restaura la estructura original
$restored = Arr::undot($dotted);
// ['user' => ['profile' => ['name' => 'Ana García', 'age' => 28]]]
```

### `Arr::join()`: unir un array como cadena

```php theme={null}
use Illuminate\Support\Arr;

$items = ['PHP', 'Laravel', 'MySQL'];

Arr::join($items, ', ');
// 'PHP, Laravel, MySQL'

// Cadena distinta antes del último elemento
Arr::join($items, ', ', ' y ');
// 'PHP, Laravel y MySQL'
```

## `data_get()`: acceso a datos anidados

Versión más versátil de `Arr::get()`. Funciona con arrays, objetos, modelos Eloquent y colecciones.

```php theme={null}
$users = [
    ['name' => 'Ana García', 'address' => ['city' => 'Madrid']],
    ['name' => 'Luis Pérez', 'address' => ['city' => 'Barcelona']],
];

// Acceso con notación de punto
$city = data_get($users, '0.address.city');
// 'Madrid'

// Comodín para obtener valores de todos los elementos
$cities = data_get($users, '*.address.city');
// ['Madrid', 'Barcelona']
```

## Helpers de números (clase `Number`)

### `Number::format()`: dar formato legible a un número

```php theme={null}
use Illuminate\Support\Number;

Number::format(1234567.89);
// '1,234,567.89'

Number::format(1234567.89, precision: 0, locale: 'es');
// '1.234.568'
```

### `Number::currency()`: formato monetario

```php theme={null}
use Illuminate\Support\Number;

Number::currency(10000, 'EUR', locale: 'es');
// '10.000,00 €'

Number::currency(29.99, 'USD');
// '$29.99'
```

### `Number::fileSize()`: tamaño de archivo en formato legible

```php theme={null}
use Illuminate\Support\Number;

Number::fileSize(1024);
// '1 KB'

Number::fileSize(1024 * 1024 * 2.5);
// '2.5 MB'
```

### `Number::abbreviate()`: notación abreviada para números grandes

```php theme={null}
use Illuminate\Support\Number;

Number::abbreviate(1000);
// '1K'

Number::abbreviate(1500000);
// '1.5M'
```

### `Number::percentage()`: porcentaje

```php theme={null}
use Illuminate\Support\Number;

Number::percentage(75.5, precision: 1);
// '75.5%'
```

## Helpers de rutas de sistema

Devuelven rutas absolutas dentro de la aplicación, correctas en cualquier entorno o destino de despliegue.

```php theme={null}
// Ruta absoluta del directorio app
app_path();
// /var/www/html/app

// Ruta a app/Http/Controllers/UserController.php
app_path('Http/Controllers/UserController.php');

// Ruta relativa a la raíz del proyecto
base_path('composer.json');

// Directorio config
config_path('database.php');

// Directorio database
database_path('migrations');

// Directorio storage
storage_path('app/uploads');

// Directorio public
public_path('css/app.css');

// Directorio resources
resource_path('views/welcome.blade.php');
```

## Helpers de URL

### `route()`: generar la URL de una ruta con nombre

```php theme={null}
// Definición de la ruta
// Route::get('/users/{user}', [UserController::class, 'show'])->name('users.show');

// URL absoluta (por defecto)
$url = route('users.show', ['user' => 1]);
// 'https://example.com/users/1'

// URL relativa
$url = route('users.show', ['user' => 1], false);
// '/users/1'
```

### `url()`: generar la URL absoluta de una ruta arbitraria

```php theme={null}
$url = url('user/profile');
// 'https://example.com/user/profile'

// Obtener la instancia del generador de URLs
$current  = url()->current();   // URL actual
$full     = url()->full();      // URL actual con la query string
$previous = url()->previous();  // URL anterior
```

### `asset()`: URL de un asset estático

```php theme={null}
$url = asset('img/logo.png');
// 'https://example.com/img/logo.png'
```

### `to_route()`: redirigir a una ruta con nombre

```php theme={null}
return to_route('users.show', ['user' => 1]);

// También puedes indicar el código HTTP y cabeceras
return to_route('users.show', ['user' => 1], 302, ['X-Custom' => 'value']);
```

## Otras funciones auxiliares muy utilizadas

### `config()`: obtener y asignar valores de configuración

```php theme={null}
// Obtener un valor con notación de punto
$timezone = config('app.timezone');
// 'Europe/Madrid'

// Con valor por defecto
$debug = config('app.debug', false);

// Cambiar un valor en tiempo de ejecución (solo dentro del proceso actual)
config(['app.locale' => 'es']);
```

### `collect()`: crear una colección

```php theme={null}
$collection = collect([1, 2, 3, 4, 5]);

$sum = collect([1, 2, 3])->sum(); // 6
```

<Tip>
  `collect()` es la puerta de entrada a las colecciones. Consulta [colecciones](/es/collections) para más información.
</Tip>

### `auth()`: obtener el usuario autenticado

```php theme={null}
// Usuario actual
$user = auth()->user();

// Comprobar si hay sesión iniciada
if (auth()->check()) {
    // Procesar como autenticado
}

// Usar un guard concreto
$admin = auth('admin')->user();
```

### `blank()` / `filled()`: comprobar si un valor está vacío

`blank()` considera vacíos `null`, cadenas vacías, cadenas solo con espacios y colecciones/arrays vacíos. `filled()` es la operación inversa.

```php theme={null}
blank('');         // true
blank('   ');      // true
blank(null);       // true
blank(collect()); // true

blank(0);      // false (0 no es «vacío»)
blank(false);  // false

filled('hello'); // true
filled(0);       // true
```

### `abort()` / `abort_if()` / `abort_unless()`: excepciones HTTP

```php theme={null}
// Lanzar directamente un error HTTP
abort(404);
abort(403, 'No tienes permiso para acceder a esta página.');

// Error si la condición es true
abort_if(! auth()->user()->isAdmin(), 403);

// Error si la condición es false
abort_unless(auth()->check(), 401);
```

### `dd()` / `dump()`: depuración

```php theme={null}
// Volcar una variable y terminar el script
dd($user);
dd($user, $orders, $config);

// Volcar sin terminar el script
dump($query);
```

### `dispatch()`: encolar un job

```php theme={null}
dispatch(new App\Jobs\SendWelcomeEmail($user));

// Ejecución inmediata (síncrona)
dispatch_sync(new App\Jobs\GenerateReport($data));
```

### `encrypt()` / `decrypt()`: cifrado

```php theme={null}
$encrypted = encrypt('sensitive-value');
$decrypted = decrypt($encrypted);
```

### `env()`: obtener variables de entorno

```php theme={null}
$debug = env('APP_DEBUG', false);
$dbHost = env('DB_HOST', '127.0.0.1');
```

<Warning>
  La buena práctica es llamar a `env()` únicamente dentro de los archivos de `config/` y acceder a los valores mediante `config()` desde los controladores y clases de servicio. Con la caché de configuración activada (`php artisan config:cache`), `env()` puede no devolver el valor esperado.
</Warning>

## Cuándo usar `Arr` y cuándo `collect()`

La clase `Arr::` está pensada para operaciones sobre arrays PHP nativos, mientras que `collect()` devuelve un objeto colección.

```php theme={null}
use Illuminate\Support\Arr;

// Si quieres trabajar con arrays sin envoltorio → clase Arr
$filtered = Arr::where($items, fn ($v) => $v > 0);
// El resultado es un array

// Si quieres encadenar varias operaciones → collect()
$result = collect($items)
    ->filter(fn ($v) => $v > 0)
    ->map(fn ($v) => $v * 2)
    ->values()
    ->all();
// El resultado es un array (recuperado con all())
```

<Info>
  Los resultados de Eloquent ya son colecciones, así que no necesitas envolverlos con `collect()`. Para operaciones sencillas sobre arrays, `Arr::` da como resultado un código más simple.
</Info>

## Resumen

<AccordionGroup>
  <Accordion title="Lista de helpers habituales">
    | Helper                                | Uso                                 |
    | ------------------------------------- | ----------------------------------- |
    | `Arr::get($array, 'a.b.c', $default)` | Acceso seguro a arrays anidados     |
    | `Arr::only($array, $keys)`            | Conservar solo las claves indicadas |
    | `Arr::except($array, $keys)`          | Excluir las claves indicadas        |
    | `Arr::pluck($array, 'key')`           | Extraer los valores de una clave    |
    | `Arr::flatten($array)`                | Aplanar un array multidimensional   |
    | `Arr::wrap($value)`                   | Asegurar que el valor es un array   |
    | `data_get($target, 'a.*.b')`          | Acceso con comodines                |
    | `Number::format($n)`                  | Formato numérico legible            |
    | `Number::currency($n, 'EUR')`         | Formato monetario                   |
    | `Number::fileSize($bytes)`            | Tamaño de archivo legible           |
    | `route('name', $params)`              | URL de una ruta con nombre          |
    | `url('path')`                         | Generar URL absoluta                |
    | `asset('path')`                       | URL de un asset estático            |
    | `config('key', $default)`             | Obtener configuración               |
    | `collect($array)`                     | Crear una colección                 |
    | `auth()->user()`                      | Obtener el usuario actual           |
    | `blank($value)`                       | Comprobar si está vacío             |
    | `filled($value)`                      | Comprobar si no está vacío          |
    | `abort(403)`                          | Lanzar una excepción HTTP           |
    | `dispatch($job)`                      | Encolar un job                      |
    | `env('KEY', $default)`                | Obtener una variable de entorno     |
  </Accordion>

  <Accordion title="Clase Arr frente a collect()">
    **Cuándo usar la clase `Arr::`**:

    * Operaciones sencillas sobre arrays (acceder a claves anidadas, filtrar claves...).
    * Cuando no quieres la sobrecarga de una colección.
    * Si prefieres seguir trabajando con arrays.

    **Cuándo usar `collect()`**:

    * Cuando encadenas varias operaciones.
    * Al procesar resultados de Eloquent (ya son colecciones).
    * Cuando necesitas métodos propios de las colecciones como `map`, `filter` o `groupBy`.
  </Accordion>
</AccordionGroup>


## Related topics

- [Laravel LSP — Extensión de funciones de IDE con Language Server Protocol](/es/blog/laravel-lsp-introduction.md)
- [Colecciones](/es/collections.md)
- [Laravel Chisel — Biblioteca de scripts de post-instalación para starter kits](/es/blog/chisel-introduction.md)
- [Gestión de la compatibilidad de versiones de paquetes](/es/advanced/package-versioning.md)
- [Core — operaciones core de AT Protocol](/es/packages/laravel-bluesky/core.md)