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

# Funzioni helper

> Le funzioni helper globali di Laravel e le classi Arr / Number con esempi pratici.

## Cosa sono le funzioni helper

Laravel fornisce numerose funzioni PHP globali (helper). La maggior parte è usata internamente dal framework, ma puoi liberamente utilizzarle anche nella tua applicazione.

Gli helper si dividono nelle seguenti categorie principali:

* **Array e oggetti** — la classe `Arr::` e funzioni come `data_get()`
* **Numeri** — la classe `Number::`
* **Path** — funzioni di path come `app_path()`, `storage_path()`
* **URL** — funzioni di generazione URL come `route()`, `url()`, `asset()`
* **Altro** — utility comuni come `config()`, `collect()`, `auth()`

<Info>
  Le funzioni helper non richiedono `use` e sono richiamabili da ovunque. Per usare le classi `Arr` o `Number` serve l'import (`use Illuminate\Support\Arr;`, ecc.).
</Info>

## Helper per array (classe Arr)

### `Arr::get()` — recupero con notazione dot

Recupera in modo sicuro un valore annidato da un array multidimensionale con la notazione dot (`foo.bar.baz`). Se la chiave non esiste restituisce il default.

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

// Valore default se la chiave non esiste
$charset = Arr::get($config, 'database.connections.mysql.charset', 'utf8mb4');
// 'utf8mb4'
```

<Tip>
  Anche la funzione globale `data_get()` ha la stessa funzionalità. Supporta anche oggetti `Arrayable` come le relazioni Eloquent ed è quindi più generica.
</Tip>

### `Arr::set()` — assegna un valore annidato

```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()` — verifica dell'esistenza di una chiave

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

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

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

// Verifica che siano presenti più chiavi
$hasAll = Arr::has($array, ['product.name', 'product.price']);
// true
```

### `Arr::only()` / `Arr::except()` — filtra o esclude chiavi

Utile per prendere dalla request solo le chiavi che ti servono o per escluderne di indesiderate.

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

$user = [
    'id' => 1,
    'name' => 'Mario Rossi',
    'email' => 'mario@example.com',
    'password' => 'secret',
    'role' => 'admin',
];

// Prendi solo le chiavi necessarie
$safe = Arr::only($user, ['id', 'name', 'email']);
// ['id' => 1, 'name' => 'Mario Rossi', 'email' => 'mario@example.com']

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

### `Arr::pluck()` — estrai una chiave specifica da array annidati

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

$records = [
    ['user' => ['id' => 1, 'name' => 'Mario Rossi']],
    ['user' => ['id' => 2, 'name' => 'Giulia Bianchi']],
];

$names = Arr::pluck($records, 'user.name');
// ['Mario Rossi', 'Giulia Bianchi']

// Terzo argomento come chiave
$nameById = Arr::pluck($records, 'user.name', 'user.id');
// [1 => 'Mario Rossi', 2 => 'Giulia Bianchi']
```

### `Arr::first()` / `Arr::last()` — primo o ultimo che soddisfa la condizione

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

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

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

// Default se nessuno soddisfa
$first = Arr::first($prices, fn ($price) => $price >= 500, 0);
// 0

// Ultimo (senza condizione)
$last = Arr::last($prices);
// 120
```

### `Arr::flatten()` — appiattisce array multidimensionali

```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()` — garantisce un array

Se il valore non è un array lo incapsula in uno. `null` diventa array vuoto. Utile per argomenti flessibili.

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

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

### `Arr::sort()` — ordina per valori

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

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

// Chiave di ordinamento con closure
$products = [
    ['name' => 'Laptop', 'price' => 1200],
    ['name' => 'Mouse', 'price' => 35],
    ['name' => 'Tastiera', 'price' => 80],
];

$byPrice = Arr::sort($products, fn ($product) => $product['price']);
```

### `Arr::dot()` / `Arr::undot()` — conversione con notazione dot

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

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

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

// Torna alla struttura originale
$restored = Arr::undot($dotted);
```

### `Arr::join()` — unisce array in stringa

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

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

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

// Delimitatore diverso prima dell'ultimo elemento
Arr::join($items, ', ', ' e ');
// 'PHP, Laravel e MySQL'
```

## `data_get()` — accesso a dati annidati

Versione generalizzata di `Arr::get()`. Supporta array, oggetti, modelli Eloquent e collection.

```php theme={null}
$users = [
    ['name' => 'Mario', 'address' => ['city' => 'Roma']],
    ['name' => 'Giulia', 'address' => ['city' => 'Milano']],
];

// Notazione dot
$city = data_get($users, '0.address.city');
// 'Roma'

// Wildcard per prendere da tutti
$cities = data_get($users, '*.address.city');
// ['Roma', 'Milano']
```

## Helper numerici (classe Number)

### `Number::format()` — formatta i numeri

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

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

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

### `Number::currency()` — formattazione valuta

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

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

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

### `Number::fileSize()` — dimensione file leggibile

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

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

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

### `Number::abbreviate()` — numeri abbreviati

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

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

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

### `Number::percentage()` — percentuale

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

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

## Helper di path

Restituiscono i percorsi delle directory dell'applicazione. Sono corretti indipendentemente dall'ambiente o dal target di deploy.

```php theme={null}
// Path assoluto della directory app
app_path();
// /var/www/html/app

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

// Path relativo alla root del progetto
base_path('composer.json');

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

// Directory database
database_path('migrations');

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

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

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

## Helper URL

### `route()` — URL per route con nome

```php theme={null}
// Definizione della route
// Route::get('/users/{user}', [UserController::class, 'show'])->name('users.show');

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

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

### `url()` — URL assoluto da un path qualsiasi

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

// Istanza URL generator
$current  = url()->current();   // URL corrente
$full     = url()->full();      // URL corrente con query string
$previous = url()->previous();  // URL precedente
```

### `asset()` — URL degli asset statici

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

### `to_route()` — redirect a una route con nome

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

// Puoi indicare anche stato HTTP e header
return to_route('users.show', ['user' => 1], 302, ['X-Custom' => 'value']);
```

## Altri helper comuni

### `config()` — leggi/imposta valori di configurazione

```php theme={null}
// Leggi con notazione dot
$timezone = config('app.timezone');

// Con default
$debug = config('app.debug', false);

// Cambia a runtime (limitato all'esecuzione)
config(['app.locale' => 'it']);
```

### `collect()` — crea una Collection

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

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

<Tip>
  `collect()` è l'helper fondamentale per le Collection. Per approfondire vedi [Collections](/it/collections).
</Tip>

### `auth()` — recupera l'utente autenticato

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

// Verifica il login
if (auth()->check()) {
    // Loggato
}

// Guard specifica
$admin = auth('admin')->user();
```

### `blank()` / `filled()` — verifica di vuoto

`blank()` considera `true` `null`, stringhe vuote, solo spazi, collection e array vuoti. `filled()` è l'opposto.

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

blank(0);      // false (0 non è "vuoto")
blank(false);  // false

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

### `abort()` / `abort_if()` / `abort_unless()` — eccezioni HTTP

```php theme={null}
// Solleva direttamente un errore HTTP
abort(404);
abort(403, 'Non hai i permessi per accedere.');

// Errore quando la condizione è true
abort_if(! auth()->user()->isAdmin(), 403);

// Errore quando la condizione è false
abort_unless(auth()->check(), 401);
```

### `dd()` / `dump()` — debug

```php theme={null}
// Stampa e termina lo script
dd($user);
dd($user, $orders, $config);

// Stampa senza terminare
dump($query);
```

### `dispatch()` — job in coda

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

// Esecuzione sincrona immediata
dispatch_sync(new App\Jobs\GenerateReport($data));
```

### `encrypt()` / `decrypt()` — cifratura

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

### `env()` — leggi variabili d'ambiente

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

<Warning>
  Best practice: non chiamare `env()` direttamente da controller o service. Chiamalo solo in `config/` e accedi tramite `config()`. Con la config cache attiva (`php artisan config:cache`), `env()` potrebbe non restituire il valore atteso.
</Warning>

## Arr vs collect()

`Arr::` opera su array PHP, `collect()` restituisce oggetti Collection.

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

// Se resti sugli array → Arr
$filtered = Arr::where($items, fn ($v) => $v > 0);
// Risultato: array

// Se vuoi concatenare più operazioni → collect()
$result = collect($items)
    ->filter(fn ($v) => $v > 0)
    ->map(fn ($v) => $v * 2)
    ->values()
    ->all();
// Risultato: array (tramite all())
```

<Info>
  I risultati Eloquent sono già Collection; non serve avvolgerli con `collect()`. Se ti basta una manipolazione semplice, `Arr::` è più immediato.
</Info>

## Riepilogo

<AccordionGroup>
  <Accordion title="Helper più usati">
    | Helper                                | Uso                              |
    | ------------------------------------- | -------------------------------- |
    | `Arr::get($array, 'a.b.c', $default)` | Lettura sicura da array annidati |
    | `Arr::only($array, $keys)`            | Solo alcune chiavi               |
    | `Arr::except($array, $keys)`          | Escludi alcune chiavi            |
    | `Arr::pluck($array, 'key')`           | Elenco valori di una chiave      |
    | `Arr::flatten($array)`                | Appiattisci array                |
    | `Arr::wrap($value)`                   | Garantisci array                 |
    | `data_get($target, 'a.*.b')`          | Lettura con wildcard             |
    | `Number::format($n)`                  | Formatta numero                  |
    | `Number::currency($n, 'EUR')`         | Formatta valuta                  |
    | `Number::fileSize($bytes)`            | Dimensione file                  |
    | `route('name', $params)`              | URL route con nome               |
    | `url('path')`                         | URL assoluto                     |
    | `asset('path')`                       | URL asset statico                |
    | `config('key', $default)`             | Leggi config                     |
    | `collect($array)`                     | Crea Collection                  |
    | `auth()->user()`                      | Utente corrente                  |
    | `blank($value)`                       | Verifica vuoto                   |
    | `filled($value)`                      | Verifica non vuoto               |
    | `abort(403)`                          | Solleva eccezione HTTP           |
    | `dispatch($job)`                      | Job in coda                      |
    | `env('KEY', $default)`                | Variabile d'ambiente             |
  </Accordion>

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

    * Operazioni semplici (accesso annidato, filtri di chiavi)
    * Quando non ti serve l'overhead di una Collection
    * Vuoi restare su array

    **Usa `collect()`**:

    * Concatenare più operazioni
    * Manipolare risultati Eloquent (già Collection)
    * Metodi propri delle Collection (`map`, `filter`, `groupBy`, ecc.)
  </Accordion>
</AccordionGroup>


## Related topics

- [Facade](/it/facades.md)
- [Contracts (contratti)](/it/contracts.md)
- [Collezioni](/it/collections.md)
- [Localizzazione](/it/localization.md)
- [Manipolazione delle stringhe (classe Str)](/it/strings.md)