Expirations

A connection can carry an optional expires_at. Stage it on the builder or pass it to connectTo():

use Carbon\CarbonInterval;
use RoundlyConsulting\Connections\Facades\Connections;

Connections::between($user, $team)->expiresIn(now()->addMonth())->connect();        // an instant
Connections::between($user, $team)->expiresIn(CarbonInterval::days(14))->connect(); // an interval from now
Connections::between($user, $team)->expiresIn(3600)->connect();                     // seconds from now
Connections::between($user, $team)->expiringAt(now()->addYear())->connect();        // an exact instant, or null

$user->connectTo($team, ['view'], now()->addWeek());

Moving the expiry

Connections::between($user, $team)->extend(now()->addYear());   // move the expiry
Connections::between($user, $team)->extend(null);               // clear it — never expires

$connection->expires_at;   // ?CarbonInterface
$connection->isExpired();  // expires_at is in the past
$connection->isActive();   // accepted and not expired

extend() throws ConnectionNotFound when there is no connection, and fires ConnectionUpdated.

Default expiry

Set expiry.default to give new connections an expiry when the caller supplies none — a positive relative string such as 30 days or 2 weeks, or at least 1 second as an integer or a numeric env string; anything else throws InvalidConfigurationException. It applies to new connections only: re-connecting an existing pair keeps its stored expiry. An explicit expiry always wins; null (the default) or a blank value means connections never expire unless you say so:

// config/connections.php
'expiry' => [
    'default' => '30 days',   // or an integer of seconds, e.g. 2592000
],

What expiry does

• isExpired() is true once expires_at is in the past; isActive() is true for an accepted connection that hasn’t expired.
• connect() on an existing pair keeps its expiry unless you stage a new one, and toggle() never renews one — renew with extend(), clear with extend(null).
• While enforce_active_on_check is on, an expired connection grants no permissions and doesn’t count for isConnectedTo() — even before it is pruned.
• Expired rows stay in the table until you prune them with connections:prune, Connections::prune() or model:prune (see Artisan commands).
• connections:notify-expiring dispatches ConnectionExpiring for connections about to lapse.
• The expiredConnections() and expiringConnections() relations list them per model (see Querying connections); Connections::expiring($days) queries every live connection expiring within the window, across all connectors.