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

# Fonctions helper

> Fonctions helper globales fournies par Laravel et classes Arr / Number, avec exemples pratiques.

## Que sont les helpers

Laravel fournit de nombreuses fonctions PHP globales (helpers). La plupart sont utilisées en interne par le framework, mais elles sont librement utilisables dans votre application.

Elles se répartissent en grandes catégories :

* **Tableaux et objets** — classe `Arr::` et fonctions comme `data_get()`
* **Nombres** — classe `Number::`
* **Chemins** — `app_path()`, `storage_path()`, etc.
* **URL** — `route()`, `url()`, `asset()`, etc.
* **Autres** — `config()`, `collect()`, `auth()` et autres utilitaires

<Info>
  Les fonctions helper sont accessibles sans `use`. Pour les classes `Arr` ou `Number`, importez avec `use Illuminate\Support\Arr;`.
</Info>

## Helpers de tableau (classe Arr)

### `Arr::get()` — Accès à une valeur imbriquée

Récupère de façon sûre une valeur imbriquée avec la notation `foo.bar.baz`.

```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'

// Valeur par défaut
$charset = Arr::get($config, 'database.connections.mysql.charset', 'utf8mb4');
// 'utf8mb4'
```

<Tip>
  `data_get()` a la même fonction et gère aussi les objets `Arrayable` comme les relations Eloquent.
</Tip>

### `Arr::set()` — Définir une valeur imbriquée

```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()` — Existence d'une clé

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

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

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

// Toutes les clés présentes ?
$hasAll = Arr::has($array, ['product.name', 'product.price']);
// true
```

### `Arr::only()` / `Arr::except()` — Filtrer les clés

Utile pour ne garder ou exclure certains champs.

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

$user = [
    'id' => 1,
    'name' => 'Taro Yamada',
    'email' => 'yamada@example.com',
    'password' => 'secret',
    'role' => 'admin',
];

// Ne garder que certaines clés
$safe = Arr::only($user, ['id', 'name', 'email']);

// Retirer 'password'
$public = Arr::except($user, ['password']);
```

### `Arr::pluck()` — Extraire une clé

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

$records = [
    ['user' => ['id' => 1, 'name' => 'Taro Yamada']],
    ['user' => ['id' => 2, 'name' => 'Hanako Suzuki']],
];

$names = Arr::pluck($records, 'user.name');
// ['Taro Yamada', 'Hanako Suzuki']

// Utiliser une clé personnalisée
$nameById = Arr::pluck($records, 'user.name', 'user.id');
// [1 => 'Taro Yamada', 2 => 'Hanako Suzuki']
```

### `Arr::first()` / `Arr::last()`

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

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

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

// Valeur par défaut
$first = Arr::first($prices, fn ($price) => $price >= 500, 0);
// 0

// Dernier élément
$last = Arr::last($prices);
// 120
```

### `Arr::flatten()` — Aplatir un tableau

```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()` — Envelopper dans un tableau

Enveloppe la valeur dans un tableau si elle n'en est pas déjà un. `null` devient `[]`.

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

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

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

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

### `Arr::sort()` — Trier par valeur

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

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

// Tri via une closure
$products = [
    ['name' => 'PC portable', 'price' => 120000],
    ['name' => 'Souris', 'price' => 3500],
    ['name' => 'Clavier', 'price' => 8000],
];

$byPrice = Arr::sort($products, fn ($product) => $product['price']);
// Ordre : Souris, Clavier, PC portable
```

### `Arr::dot()` / `Arr::undot()` — Conversion en notation point

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

$nested = [
    'user' => [
        'profile' => ['name' => 'Taro Yamada', 'age' => 28],
    ],
];

$dotted = Arr::dot($nested);
// ['user.profile.name' => 'Taro Yamada', 'user.profile.age' => 28]

$restored = Arr::undot($dotted);
```

### `Arr::join()` — Concatener en chaîne

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

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

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

// Séparateur différent avant le dernier
Arr::join($items, ', ', ' et ');
// 'PHP, Laravel et MySQL'
```

## `data_get()` — Accès générique

Version étendue de `Arr::get()`, qui gère tableaux, objets, modèles Eloquent et collections.

```php theme={null}
$users = [
    ['name' => 'Taro Yamada', 'address' => ['city' => 'Tokyo']],
    ['name' => 'Hanako Suzuki', 'address' => ['city' => 'Osaka']],
];

$city = data_get($users, '0.address.city');
// 'Tokyo'

// Joker
$cities = data_get($users, '*.address.city');
// ['Tokyo', 'Osaka']
```

## Helpers de nombres (classe Number)

### `Number::format()`

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

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

Number::format(1234567.89, precision: 0, locale: 'fr');
// '1 234 568'
```

### `Number::currency()`

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

Number::currency(10000, 'EUR', locale: 'fr');
// '10 000,00 €'

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

### `Number::fileSize()`

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

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

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

### `Number::abbreviate()`

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

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

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

### `Number::percentage()`

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

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

## Helpers de chemin

Récupèrent les chemins des répertoires de l'application, correctement peu importe l'environnement.

```php theme={null}
// Chemin absolu de app/
app_path();
// /var/www/html/app

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

// Racine du projet
base_path('composer.json');

// Répertoire config
config_path('database.php');

// Répertoire database
database_path('migrations');

// Répertoire storage
storage_path('app/uploads');

// Répertoire public
public_path('css/app.css');

// Répertoire resources
resource_path('views/welcome.blade.php');
```

## Helpers d'URL

### `route()` — URL d'une route nommée

```php theme={null}
// Route : Route::get('/users/{user}', ...)->name('users.show');

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

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

### `url()` — URL absolue d'un chemin

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

// Récupération d'un UrlGenerator
$current  = url()->current();
$full     = url()->full();
$previous = url()->previous();
```

### `asset()` — URL d'un asset statique

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

### `to_route()` — Redirection vers une route nommée

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

// Avec code et en-têtes
return to_route('users.show', ['user' => 1], 302, ['X-Custom' => 'value']);
```

## Autres helpers courants

### `config()`

```php theme={null}
// Lecture avec notation point
$timezone = config('app.timezone');
// 'Europe/Paris'

// Avec défaut
$debug = config('app.debug', false);

// Modification en runtime (portée de la requête)
config(['app.locale' => 'fr']);
```

### `collect()`

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

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

<Tip>
  `collect()` est le point d'entrée essentiel des collections. Voir [Collections](/fr/collections).
</Tip>

### `auth()`

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

if (auth()->check()) {
    // Connecté
}

// Autre garde
$admin = auth('admin')->user();
```

### `blank()` / `filled()`

`blank()` renvoie `true` pour `null`, chaîne vide ou d'espaces, collection/tableau vide. `filled()` c'est l'inverse.

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

blank(0);      // false
blank(false);  // false

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

### `abort()` / `abort_if()` / `abort_unless()`

```php theme={null}
abort(404);
abort(403, 'Vous n\'avez pas accès à cette page.');

abort_if(! auth()->user()->isAdmin(), 403);

abort_unless(auth()->check(), 401);
```

### `dd()` / `dump()`

```php theme={null}
dd($user);
dd($user, $orders, $config);

dump($query);
```

### `dispatch()`

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

// Synchrone
dispatch_sync(new App\Jobs\GenerateReport($data));
```

### `encrypt()` / `decrypt()`

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

### `env()`

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

<Warning>
  N'appelez pas `env()` dans les contrôleurs ou services. Utilisez-le dans les fichiers de `config/` et accédez via `config()`. Avec `php artisan config:cache`, `env()` peut ne pas renvoyer la valeur attendue.
</Warning>

## Arr vs collect()

`Arr::` opère sur des tableaux PHP standard ; `collect()` retourne un objet Collection.

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

// Opération sur un tableau → Arr
$filtered = Arr::where($items, fn ($v) => $v > 0);
// Résultat : tableau

// Chaînage → collect()
$result = collect($items)
    ->filter(fn ($v) => $v > 0)
    ->map(fn ($v) => $v * 2)
    ->values()
    ->all();
// Résultat : tableau (via all())
```

<Info>
  Les résultats Eloquent sont déjà des collections. `collect()` n'est pas nécessaire dans ce cas. Pour des opérations simples, `Arr::` est plus léger.
</Info>

## Récapitulatif

<AccordionGroup>
  <Accordion title="Helpers fréquents">
    | Helper                                | Rôle                             |
    | ------------------------------------- | -------------------------------- |
    | `Arr::get($array, 'a.b.c', $default)` | Accès imbriqué sécurisé          |
    | `Arr::only($array, $keys)`            | Ne garder que les clés indiquées |
    | `Arr::except($array, $keys)`          | Retirer les clés                 |
    | `Arr::pluck($array, 'key')`           | Extraire les valeurs d'une clé   |
    | `Arr::flatten($array)`                | Aplatir un tableau               |
    | `Arr::wrap($value)`                   | Garantir un tableau              |
    | `data_get($target, 'a.*.b')`          | Accès générique avec joker       |
    | `Number::format($n)`                  | Formater un nombre               |
    | `Number::currency($n, 'EUR')`         | Formater une devise              |
    | `Number::fileSize($bytes)`            | Taille de fichier lisible        |
    | `route('name', $params)`              | URL d'une route nommée           |
    | `url('path')`                         | URL absolue                      |
    | `asset('path')`                       | URL d'asset                      |
    | `config('key', $default)`             | Configuration                    |
    | `collect($array)`                     | Créer une Collection             |
    | `auth()->user()`                      | Utilisateur connecté             |
    | `blank($value)`                       | Test de « vide »                 |
    | `filled($value)`                      | Non vide                         |
    | `abort(403)`                          | Exception HTTP                   |
    | `dispatch($job)`                      | Mettre en file                   |
    | `env('KEY', $default)`                | Variable d'environnement         |
  </Accordion>

  <Accordion title="Arr vs collect()">
    **Utiliser `Arr::` :**

    * Opérations simples sur tableaux (accès imbriqué, filtrage de clés)
    * Pas besoin de l'overhead d'un objet Collection
    * Conserver le résultat en tableau

    **Utiliser `collect()` :**

    * Chaîner plusieurs opérations
    * Enrichir un résultat Eloquent (déjà collection)
    * Utiliser des méthodes propres aux collections (`map`, `filter`, `groupBy`)
  </Accordion>
</AccordionGroup>


## Related topics

- [Classe Fluent](/fr/advanced/fluent.md)
- [Construire une SPA avec Inertia.js](/fr/blog/inertia-introduction.md)
- [Localisation](/fr/localization.md)
- [Façades](/fr/facades.md)
- [Laravel Prompts](/fr/prompts.md)