Panoramica
Laravel Bluesky supporta due metodi di autenticazione. Dopo l’autenticazione, le chiamate API sono comuni a entrambi i metodi.
| Elemento | App Password | OAuth |
|---|
| Classi interne | LegacyAgent / LegacySession | OAuthAgent / OAuthSession |
| Entry point | Bluesky::login() | Bluesky::withToken(OAuthSession) |
| Chiave privata | Non necessaria | Serve BLUESKY_OAUTH_PRIVATE_KEY |
| Azione di autorizzazione dell’utente | Non necessaria | Necessaria (approvazione nel browser) |
| Esecuzione in background | ✅ Ideale | ✅ Possibile (salvando refresh_token) |
| Chiavi di sessione | accessJwt / refreshJwt | access_token / refresh_token |
| Deprecato | No | — |
| Usi principali | Post automatici, notifiche, batch processing | Operazioni per conto dell’utente, integrazione Socialite |
Il nome LegacyAgent significa “metodo di autenticazione precedente a OAuth”, ma App Password in sé non è deprecato. Per notifiche e post automatici, quando non c’è interazione utente, App Password è più semplice e adatto.
Architettura
BlueskyManager è l’implementazione dietro alla Facade Bluesky. Configuri l’agente con login() o withToken() e da quel momento le chiamate API usano gli stessi metodi indipendentemente dal metodo di autenticazione.
App Password (LegacyAgent)
Flusso di autenticazione
Bluesky::login()
Basta impostare l’App Password in .env e chiamare login().
BLUESKY_IDENTIFIER=your-handle.bsky.social
BLUESKY_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx
use Revolution\Bluesky\Facades\Bluesky;
$response = Bluesky::login(
identifier: config('bluesky.identifier'),
password: config('bluesky.password'),
)->post('Hello Bluesky');
Riutilizzo di LegacySession
Chiamare login() ogni volta genera una richiesta API a ogni chiamata. Mettere in cache la sessione e riutilizzarla è più efficiente.
use Revolution\Bluesky\Facades\Bluesky;
use Revolution\Bluesky\Session\LegacySession;
// Primo login e salvataggio della sessione
Bluesky::login(
identifier: config('bluesky.identifier'),
password: config('bluesky.password'),
);
cache()->put('bluesky_session', Bluesky::agent()->session()->toArray(), now()->addDay());
// Nelle esecuzioni successive, ripristina dalla cache
$session = LegacySession::create(cache('bluesky_session', []));
Bluesky::withToken($session);
// Se l'access token è scaduto, aggiornalo
if (! Bluesky::check()) {
Bluesky::refreshSession();
}
$response = Bluesky::post('Hello from cached session');
Chiavi principali di LegacySession
| Chiave | Contenuto | Metodo |
|---|
accessJwt | Access token | token() |
refreshJwt | Refresh token | refresh() |
did | DID Bluesky | did() |
handle | Handle | handle() |
email | Indirizzo email | email() |
active | Se l’account è attivo | active() |
Casi d’uso adatti
- Post automatici in background job e job in coda
- Notifiche tramite un canale Laravel Notification
- Batch processing e schedulazione
- Quando si pubblica con l’account dell’applicazione stessa
OAuth (OAuthAgent)
Flusso di autenticazione
Bluesky::withToken()
Passa a withToken() la OAuthSession ottenuta tramite Socialite.
use Revolution\Bluesky\Facades\Bluesky;
use Revolution\Bluesky\Session\OAuthSession;
// Ripristino dalla sessione Laravel (richiesta web)
$session = OAuthSession::create(session('bluesky_session'));
$timeline = Bluesky::withToken($session)->getTimeline();
OAuthSession a partire dai valori salvati in DB.
use Revolution\Bluesky\Facades\Bluesky;
use Revolution\Bluesky\Session\OAuthSession;
$session = OAuthSession::create([
'did' => $user->did,
'refresh_token' => $user->refresh_token,
// Per gli account non su bsky.social, specifica anche iss
// 'iss' => $user->iss,
]);
$response = Bluesky::withToken($session)
->refreshSession()
->post('Hello from OAuth');
Chiavi principali di OAuthSession
| Chiave | Contenuto | Metodo |
|---|
access_token | Access token | token() |
refresh_token | Refresh token (utilizzabile una sola volta) | refresh() |
did / sub | DID Bluesky | did() |
iss | URL del server di autorizzazione | issuer() |
profile.handle | Handle | handle() |
profile.displayName | Nome visualizzato | displayName() |
Il refresh_token OAuth può essere usato una sola volta. Usa l’evento OAuthSessionUpdated e assicurati di aggiornare il DB dopo ogni refresh del token. Per i dettagli consulta Socialite. Casi d’uso adatti
- Login utente con Socialite
- Chiamate API per conto dell’utente
- Quando è necessario operare con account diversi a seconda dell’utente
Le chiamate API dopo l’autenticazione sono comuni
Con entrambi i metodi di autenticazione, dopo withToken() si usano gli stessi metodi API.
use Revolution\Bluesky\Facades\Bluesky;
use Revolution\Bluesky\Session\LegacySession;
use Revolution\Bluesky\Session\OAuthSession;
// App Password
Bluesky::login(config('bluesky.identifier'), config('bluesky.password'));
// oppure OAuth
$session = OAuthSession::create(session('bluesky_session'));
Bluesky::withToken($session);
// ↓ Da qui in poi le chiamate API sono completamente comuni ↓
Bluesky::post('Hello Bluesky');
Bluesky::getTimeline();
Bluesky::getProfile();
Bluesky::searchPosts(q: '#laravel');
BlueskyManager internamente sceglie tra LegacyAgent o OAuthAgent, ma il codice chiamante non ne risente.
Quale scegliere
| Situazione | Consigliato |
|---|
| Post automatici, notifiche, batch | App Password |
| Funzione di login utente | OAuth |
| Solo background job | App Password |
| Serve operare per conto dell’utente | OAuth |
| Priorità alla semplicità operativa | App Password |
| Priorità a sicurezza e controllo dei permessi | OAuth |
Se sei indeciso, il criterio più semplice è dividere in base all’obiettivo. Se “è l’app che agisce da sola” → App Password; se “è l’utente che opera” → OAuth. È anche possibile combinare i due: ad esempio usare App Password per le notifiche e OAuth per il login utente è una configurazione molto comune.
Link di riferimento
