Antenna Bundle Laravel Package

Getting Started

• Install the package with Composer and publish any config it ships (php artisan vendor:publish --provider="..."). If you already have the package installed, 1.1.0 is an additive minor release—update with composer require vendor/package:^1.1.
• Look first at the package service provider and config file, then at UsernamePasswordAuthenticator. That class is the main entry point for username/password authentication and, as of 1.1.0, accepts a time_to_live option.
• First use case: authenticate a user and issue a token/session with a controlled lifetime.

use Vendor\Package\Auth\UsernamePasswordAuthenticator;

$authenticator = app(UsernamePasswordAuthenticator::class);

$token = $authenticator->attempt([
    'username' => $request->username,
    'password' => $request->password,
], [
    'time_to_live' => now()->addHours(2), // new in 1.1.0
]);

If the package supports config-driven defaults, set a sensible fallback in config/<package>.php:

'time_to_live' => env('AUTH_TOKEN_TTL', 60 * 60 * 24),

Implementation Patterns

• Controller login endpoint: validate credentials with a FormRequest, then call the authenticator. Return the token plus expiry metadata so clients know when to refresh.
• Per-request TTL: use the new time_to_live option for “remember me” flows—short TTL for normal logins, longer TTL when the user opts in. Pass the option at call time instead of hard-coding it.
• Config-driven TTL: for most apps, set one default in config and override per call only when needed. This keeps token lifetimes consistent across web, API, and mobile clients.
• Guard integration: if the package provides a guard, register it in config/auth.php and use Auth::guard('api')->attempt(...). If not, call the authenticator directly from your login endpoint.
• Testing: bind a fake UsernamePasswordAuthenticator in the container, or use actingAs when a guard is available. Add a test that asserts the time_to_live option is passed through, since expiry bugs are easy to miss.
• API response shape: include expires_in or expires_at in your login response using the same TTL you passed to the authenticator. Clients can then refresh proactively instead of reacting to 401s.

Gotchas and Tips

• TTL units: confirm whether time_to_live expects seconds, a DateTimeInterface, or a DateInterval. The release note does not specify; check the class signature or package tests. Mixing units is the fastest way to issue tokens that expire immediately or never.
• Default behavior: if you omit time_to_live, the package likely falls back to a configured default. Audit that default before and after upgrading—1.1.0 adds the option but may not change existing defaults.
• Config caching: after adding time_to_live to config, run php artisan config:clear locally and config:cache in production. Stale config is a common reason the new option appears ignored.
• Clock skew: compare expiry on the client using the server-provided expires_at, not the client clock. If you test with Carbon::setTestNow(), make sure the authenticator uses the same clock.
• Token storage: if tokens are persisted, verify that your storage layer honors the TTL. Some repositories store an expires_at column; others rely on cache TTL. Check both.
• Debugging: log the resolved TTL before calling attempt, and check the package tests for the expected time_to_live type. If tokens still expire at the old time, confirm you are not reusing a cached authenticator instance in Octane or a queue worker.
• Extension points: if TTL is resolved through a method or config, subclass the authenticator or bind a custom implementation in a service provider for per-tenant or per-client lifetime rules.
• Upgrade safety: 1.1.0 is additive, but pin to ^1.1 and run your auth tests after upgrading—especially if you call the authenticator with positional arguments or custom subclasses.