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

# Trait InteractsWithTime

> Guida al trait di utilità per il calcolo del tempo usato in queue, cache e scheduling, con esempi pratici.

## Cos'è InteractsWithTime

`Illuminate\Support\InteractsWithTime` è un trait che raccoglie i calcoli di tempo, ritardo e durata. All'interno del framework Laravel oltre 40 classi usano `use InteractsWithTime;`: è impiegato in un'ampia gamma di componenti come cache, queue, console e connessioni al database.

<Info>
  Il codice sorgente si trova in `src/Illuminate/Support/InteractsWithTime.php`. È composto solo da metodi `protected` e si presuppone l'uso dall'interno della classe.
</Info>

## Esempi di utilizzo nel framework

| Classe                                    | Scopo                                            |
| ----------------------------------------- | ------------------------------------------------ |
| `Cache\ArrayStore` / `DatabaseStore` ecc. | Calcolo del TTL (tempo di scadenza)              |
| `Cache\RateLimiter`                       | Istante di reset del rate limit                  |
| `Queue\Console\RestartCommand`            | Timestamp di restart dei worker                  |
| `Database\Connection`                     | Misurazione del tempo di esecuzione delle query  |
| `Console\View\Components\Task`            | Visualizzazione del tempo di esecuzione dei task |
| `Redis\Limiters\DurationLimiterBuilder`   | Calcolo della durata per il rate limit su Redis  |

## Descrizione dei metodi

### `secondsUntil()` — ottiene i secondi rimanenti

Restituisce i secondi rimanenti fino al datetime o al ritardo indicato. L'argomento può essere `DateTimeInterface`, `DateInterval` o un intero di secondi.

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

class MyService
{
    use InteractsWithTime;

    public function scheduleAt(\DateTime $target): int
    {
        return $this->secondsUntil($target); // secondi da adesso a $target
    }
}
```

Se passi un datetime nel passato, restituisce `0` (non diventa negativo).

```php theme={null}
$seconds = $this->secondsUntil(now()->addMinutes(5)); // 300
$seconds = $this->secondsUntil(now()->subMinutes(5)); // 0 (passato = 0)
$seconds = $this->secondsUntil(60);                   // 60 (l'intero viene interpretato come secondi)
```

### `availableAt()` — timestamp UNIX di disponibilità

Restituisce il timestamp UNIX ottenuto sommando il ritardo all'istante corrente. È usato per calcolare il delay dei job in coda e le scadenze della cache.

```php theme={null}
$timestamp = $this->availableAt(60);              // timestamp UNIX tra 60 secondi
$timestamp = $this->availableAt(new \DateTime('2026-12-31')); // timestamp UNIX del datetime indicato
$timestamp = $this->availableAt(new \DateInterval('PT5M'));    // tra 5 minuti
```

Chiamato senza argomenti (default `0`) restituisce il timestamp dell'istante corrente.

### `parseDateInterval()` — converte DateInterval in DateTime

Se riceve un'istanza `DateInterval`, la aggiunge all'istante corrente e restituisce un'istanza `Carbon`. `DateTimeInterface` e i valori interi vengono restituiti così come sono.

```php theme={null}
$delay = $this->parseDateInterval(new \DateInterval('P1D')); // Carbon di domani
$delay = $this->parseDateInterval(now()->addHour());         // DateTimeInterface resta invariato
$delay = $this->parseDateInterval(3600);                     // 3600 (intero invariato)
```

`secondsUntil()` e `availableAt()` chiamano internamente questo metodo.

### `currentTime()` — timestamp UNIX dell'istante corrente

Semplice wrapper che restituisce `Carbon::now()->getTimestamp()`. È usato come istante di riferimento in `secondsUntil()`.

```php theme={null}
$now = $this->currentTime(); // int (timestamp UNIX)
```

### `runTimeForHumans()` — durata di esecuzione in formato leggibile

Converte in una stringa leggibile la differenza tra l'istante iniziale e quello finale registrati con `microtime(true)`.

```php theme={null}
$start = microtime(true);

// ... elaborazione ...

echo $this->runTimeForHumans($start); // esempio: "42.15ms" oppure "1s 234ms"
```

Sotto i 1000ms restituisce millisecondi con decimali come `42.15ms`; da 1000ms in su usa la forma abbreviata `forHumans()` di CarbonInterval (`1s 234ms`, ecc.).

Passando l'istante finale come secondo argomento puoi convertire un intervallo già misurato.

```php theme={null}
$elapsed = $this->runTimeForHumans($start, $end);
```

## Utilizzo nello sviluppo di pacchetti

### Uniformare il TTL nei driver di cache

Utile per creare metodi come `put(key, value, ttl)` che accettano `int`, `DateInterval` o `DateTime` come `ttl`.

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

class MyStore
{
    use InteractsWithTime;

    public function put(string $key, mixed $value, mixed $ttl): void
    {
        $seconds = $this->secondsUntil($ttl);

        // salva nello storage effettivo con $seconds (int)
        $this->storage[$key] = [
            'value'      => $value,
            'expires_at' => $this->availableAt($ttl),
        ];
    }
}
```

### Mostrare il tempo di esecuzione di un comando console

Puoi usarlo nell'`handle()` di un comando `Artisan` per mostrare all'utente il tempo di elaborazione.

```php theme={null}
use Illuminate\Console\Command;
use Illuminate\Support\InteractsWithTime;

class ProcessDataCommand extends Command
{
    use InteractsWithTime;

    public function handle(): void
    {
        $start = microtime(true);

        // ... elaborazione ...

        $this->info("Completato: {$this->runTimeForHumans($start)}");
    }
}
```

## InteractsWithTime per i test

`Illuminate\Foundation\Testing\Concerns\InteractsWithTime` è una cosa diversa: fornisce i metodi `travel*()` per manipolare il tempo nei test (viene automaticamente incluso in `TestCase`).

```php theme={null}
// avanza il tempo nei test (Testing\Concerns\InteractsWithTime)
$this->travel(5)->days();
$this->travelTo(now()->addMonth());
$this->travelBack();
```

Attenzione a non confonderlo con `Illuminate\Support\InteractsWithTime` (oggetto di questa pagina): il namespace è diverso.

## Riepilogo

| Metodo                           | Valore di ritorno        | Uso principale                                    |
| -------------------------------- | ------------------------ | ------------------------------------------------- |
| `secondsUntil($delay)`           | `int`                    | Ottenere i secondi rimanenti                      |
| `availableAt($delay)`            | `int`                    | Calcolo del timestamp di inizio validità          |
| `parseDateInterval($delay)`      | `DateTimeInterface\|int` | Conversione DateInterval → Carbon                 |
| `currentTime()`                  | `int`                    | Timestamp UNIX corrente                           |
| `runTimeForHumans($start, $end)` | `string`                 | Visualizzazione leggibile del tempo di esecuzione |

Se vuoi creare metodi che accettino indifferentemente `int`, `DateInterval` o `DateTimeInterface`, basta `use` di questo trait e non dovrai reimplementare la logica di conversione.

## Pagine correlate

* [Sviluppo di pacchetti](/it/advanced/package-development)
* [Trait InteractsWithData](/it/advanced/interacts-with-data)
* [Trait Conditionable](/it/advanced/conditionable)


## Related topics

- [Trait InteractsWithData](/it/advanced/interacts-with-data.md)
- [Broadcasting](/it/broadcasting.md)
- [Attributi PHP](/it/advanced/php-attributes.md)
- [Classe Fluent](/it/advanced/fluent.md)
- [Trait Conditionable](/it/advanced/conditionable.md)