BlueskyManager et HasShortHand

Architecture de BlueskyManager (l’implémentation derrière la facade Bluesky) et description des méthodes raccourci fournies par le trait HasShortHand.

​

Vue d’ensemble

La facade Bluesky est une fine enveloppe autour de BlueskyManager. BlueskyManager gère plusieurs agents, et le trait HasShortHand regroupe les méthodes raccourci les plus fréquemment utilisées.

​

Architecture

Le BlueskyServiceProvider enregistre Factory::class en tant que singleton à portée limitée (une instance par requête) vers BlueskyManager.

// BlueskyServiceProvider::register()
$this->app->scoped(Factory::class, BlueskyManager::class);

Le getFacadeAccessor() de la facade résout ce binding.

// Facades/Bluesky.php
protected static function getFacadeAccessor(): string
{
    return Factory::class;
}

​

Méthodes principales de BlueskyManager

Voici les méthodes principales définies par BlueskyManager lui-même. Les distinguer de celles du trait HasShortHand aide à comprendre la structure interne.

​

Authentification

Méthode	Description
login(string $identifier, string $password, ?string $service = null)	Authentifie via App Password et installe un LegacyAgent
withToken(?AbstractSession $token)	Installe un Agent à partir d’une OAuthSession ou d’une LegacySession
check(): bool	Vérifie si la session est authentifiée (contrôle également l’expiration du token)
refreshSession()	Renouvelle les tokens
logout()	Efface l’Agent

​

Opérations sur l’Agent

Méthode	Description
agent(): ?Agent	Récupère l’Agent courant
withAgent(?Agent $agent)	Installe directement un Agent
assertDid(): string	Renvoie le DID authentifié. Lance une exception si non authentifié

​

Client HTTP

Méthode	Description
client(bool $auth = true): AtpClient	Renvoie un client XRPC authentifié (ou anonyme)
public(): BskyClient	Renvoie un client pour les endpoints publics sans authentification
send(BackedEnum|string $api, string $method, bool $auth, ?array $params, ?callable $callback)	Appelle directement n’importe quelle API AT Protocol

​

Utilitaires

Méthode	Description
identity(): Identity	Récupère le service d’identité (résolution DID, etc.)
pds(): PDS	Récupère le service d’informations PDS
entryway(?string $path): string	Renvoie l’URL du service (par ex. bsky.social)
publicEndpoint(): string	Renvoie l’URL de l’endpoint public

​

Trait HasShortHand

Le trait HasShortHand enveloppe les API bas niveau d’AT Protocol dans des méthodes PHP plus lisibles. Il suffit d’ajouter use HasShortHand; dans BlueskyManager pour exposer ces méthodes directement via Bluesky::.

// BlueskyManager.php
class BlueskyManager implements Factory
{
    use Conditionable;
    use HasShortHand;
    use Macroable;
    // ...
}

HasShortHand est isolé dans un trait pour faciliter les tests et la personnalisation. Ce trait permet de fournir un large éventail de raccourcis d’API tout en gardant le code de BlueskyManager simple.

​

Posts et flux

Méthode	Description
post(Post|string|array $text)	Crée un nouveau post
getPost(string $uri)	Récupère un post via son AT-URI
getPosts(array $uris)	Récupère plusieurs posts en une fois
deletePost(string $uri)	Supprime un post
getTimeline(?string $algorithm, ?int $limit, ?string $cursor)	Récupère la timeline d’accueil
getAuthorFeed(?string $actor, ...)	Récupère le flux d’un compte donné
searchPosts(string $q, ...)	Recherche des posts

​

Engagement

Méthode	Description
like(Like|StrongRef $subject)	Crée un like
deleteLike(string $uri)	Retire un like
repost(Repost|StrongRef $subject)	Crée un repost
deleteRepost(string $uri)	Retire un repost
getActorLikes(?string $actor, ...)	Récupère la liste des likes d’un compte

​

Follow

Méthode	Description
follow(Follow|string $did)	Suivre
deleteFollow(string $uri)	Ne plus suivre
getFollowers(?string $actor, ...)	Récupère la liste des followers
getFollows(?string $actor, ...)	Récupère la liste des comptes suivis

​

Profil et compte

Méthode	Description
getProfile(?string $actor)	Récupère un profil
upsertProfile(callable $callback)	Met à jour un profil
resolveHandle(string $handle)	Résout un handle en DID

​

Médias

Méthode	Description
uploadBlob(StreamInterface|string $data, string $type)	Téléverse un blob (image, etc.)
uploadVideo(StreamInterface|string $data, string $type)	Téléverse une vidéo
getJobStatus(string $jobId)	Vérifie le statut d’un job de téléversement vidéo
getUploadLimits()	Récupère les limites de téléversement

​

Notifications

Méthode	Description
listNotifications(...)	Récupère la liste des notifications
countUnreadNotifications(...)	Récupère le nombre de notifications non lues
updateSeenNotifications(string $seenAt)	Met à jour l’état lu

​

Opérations sur les enregistrements AT Protocol

Méthode	Description
createRecord(string $repo, string $collection, ...)	Crée un enregistrement
getRecord(string $repo, string $collection, string $rkey, ...)	Récupère un enregistrement
listRecords(string $repo, string $collection, ...)	Liste les enregistrements
putRecord(string $repo, string $collection, string $rkey, ...)	Met à jour ou crée un enregistrement
deleteRecord(string $repo, string $collection, string $rkey, ...)	Supprime un enregistrement

​

Feed generator et labeler

Méthode	Description
publishFeedGenerator(BackedEnum|string $name, Generator $generator)	Publie un feed generator
createThreadGate(string $post, ?array $allow)	Crée un thread gate
upsertLabelDefinitions(callable $callback)	Met à jour les définitions de labels
deleteLabelDefinitions()	Supprime les définitions de labels
createLabels(RepoRef|StrongRef|array $subject, array $labels)	Applique des labels
deleteLabels(RepoRef|StrongRef|array $subject, array $labels)	Retire des labels

​

Exemples de raccourcis courants

​

Publier

use Revolution\Bluesky\Facades\Bluesky;

$response = Bluesky::login(
    identifier: config('bluesky.identifier'),
    password: config('bluesky.password'),
)->post('Hello Bluesky');

​

Répondre

Pour une réponse, définissez la StrongRef du post parent via Post::build(). HasShortHand ne dispose pas de méthode reply() dédiée : on passe l’objet Post à post().

use Revolution\Bluesky\Facades\Bluesky;
use Revolution\Bluesky\Record\Post;
use Revolution\Bluesky\Types\StrongRef;

$parent = StrongRef::to(uri: 'at://did:plc:.../app.bsky.feed.post/...', cid: 'bafyrei...');

$reply = Post::create('Texte de la réponse')
    ->reply(root: $parent, parent: $parent);

Bluesky::login(config('bluesky.identifier'), config('bluesky.password'))
    ->post($reply);

​

Like et repost

use Revolution\Bluesky\Facades\Bluesky;
use Revolution\Bluesky\Types\StrongRef;

$ref = StrongRef::to(uri: 'at://did:plc:.../app.bsky.feed.post/...', cid: 'bafyrei...');

// Like
Bluesky::withToken($session)->like($ref);

// Repost
Bluesky::withToken($session)->repost($ref);

​

Mettre à jour son profil

upsertProfile() récupère le profil actuel et enregistre les modifications effectuées dans la closure. Les méthodes de l’objet Profile permettent de définir displayName, description, etc.

use Revolution\Bluesky\Facades\Bluesky;
use Revolution\Bluesky\Record\Profile;

Bluesky::login(config('bluesky.identifier'), config('bluesky.password'))
    ->upsertProfile(function (Profile $profile) {
        $profile->displayName('Nouveau nom d\'affichage')
                ->description('Description du profil');
    });

​

Définir des self labels

Vous pouvez utiliser SelfLabels pour appliquer un self label à l’ensemble du compte.

use Revolution\Bluesky\Facades\Bluesky;
use Revolution\Bluesky\Record\Profile;
use Revolution\Bluesky\Types\SelfLabels;

Bluesky::login(config('bluesky.identifier'), config('bluesky.password'))
    ->upsertProfile(function (Profile $profile) {
        $profile->labels(SelfLabels::make(['!no-unauthenticated']));
    });

​

Appeler directement une API arbitraire

Pour toute méthode absente de HasShortHand, utilisez send() ou client().

use Revolution\Bluesky\Facades\Bluesky;

// send() pour appeler une méthode XRPC arbitraire
$response = Bluesky::withToken($session)
    ->send(
        api: 'app.bsky.actor.getProfiles',
        method: 'get',
        params: ['actors' => ['did:plc:...', 'did:plc:...']],
    );

// client() pour un contrôle plus fin
$response = Bluesky::withToken($session)
    ->client()
    ->bsky()
    ->getProfiles(actors: ['did:plc:...']);

​

Différences entre l’utilisation via la facade et l’utilisation directe

Bluesky::post() et app(Factory::class)->post() opèrent sur la même instance de BlueskyManager.

use Revolution\Bluesky\Facades\Bluesky;
use Revolution\Bluesky\Contracts\Factory;

// Via la facade (usage courant)
Bluesky::login(config('bluesky.identifier'), config('bluesky.password'))
    ->post('Hello');

// Récupération directe depuis le conteneur
$manager = app(Factory::class);
$manager->login(config('bluesky.identifier'), config('bluesky.password'))
        ->post('Hello');

// DI par type-hint
class MyService
{
    public function __construct(private Factory $bluesky) {}

    public function doPost(): void
    {
        $this->bluesky->login(
            config('bluesky.identifier'),
            config('bluesky.password'),
        )->post('Hello from DI');
    }
}

Grâce à l’enregistrement scoped, l’état de session obtenu après login() est conservé pendant toute la requête.

​

Conditionable et Macroable

BlueskyManager utilise également les traits Conditionable et Macroable.

​

Conditionable : when() / unless()

use Revolution\Bluesky\Facades\Bluesky;

Bluesky::login(config('bluesky.identifier'), config('bluesky.password'))
    ->when(config('app.env') === 'production', function ($bluesky) {
        $bluesky->post('Publication depuis l\'environnement de production');
    });

​

Macroable : ajouter des méthodes personnalisées

macro() permet à l’application d’ajouter des méthodes à BlueskyManager. On les définit typiquement dans la méthode boot() d’AppServiceProvider.

use Revolution\Bluesky\Facades\Bluesky;

Bluesky::macro('postWithHashtag', function (string $text, string $tag) {
    /** @var \Revolution\Bluesky\BlueskyManager $this */
    return $this->post("{$text} #{$tag}");
});

// Exemple d'utilisation
Bluesky::login(config('bluesky.identifier'), config('bluesky.password'))
    ->postWithHashtag('Hello', 'laravel');

​

Injecter un Agent personnalisé

withAgent() permet d’installer directement une implémentation d’Agent de votre choix.

use Revolution\Bluesky\Facades\Bluesky;
use Revolution\Bluesky\Contracts\Agent;

// Pour implémenter un Agent personnalisé, implémentez l'interface Agent
class MyCustomAgent implements Agent
{
    // ...
}

Bluesky::withAgent(new MyCustomAgent());

Comme l’authentification normale (login() / withToken()) installe automatiquement l’agent, l’usage direct de withAgent() intervient surtout lors des tests.

​

Liens utiles

• Comparaison des méthodes d’authentification — Détails App Password vs OAuth
• Client de base — Exemples d’appels d’API après authentification
• Tests — Méthodes de test avec Fake
• Source : src/BlueskyManager.php
• Source : src/HasShortHand.php