BlueskyManager en HasShortHand

Overzicht

De Bluesky Facade is een dunne wrapper rond BlueskyManager. BlueskyManager beheert meerdere Agents, en de HasShortHand-trait biedt een verzameling shortcuts voor veelgebruikte methodes.

Architectuur

BlueskyServiceProvider registreert Factory::class als BlueskyManager via een scoped singleton (één instantie per request).

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

De getFacadeAccessor() van de Facade lost deze binding op.

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

Kernmethodes van BlueskyManager

Dit zijn de kernmethodes die BlueskyManager zelf definieert. Het helpt bij het begrijpen van de interne structuur om deze te onderscheiden van de methodes uit de HasShortHand-trait.

Authenticatie

Methode	Beschrijving
`login(string $identifier, string $password, ?string $service = null)`	Authenticeert met App Password en stelt een `LegacyAgent` in
`withToken(?AbstractSession $token)`	Stelt een Agent in op basis van een `OAuthSession` of `LegacySession`
`check(): bool`	Controleert of je geauthenticeerd bent (valideert ook de tokenvervaldatum)
`refreshSession()`	Vernieuwt de token
`logout()`	Wist de Agent

Agent-operaties

Methode	Beschrijving
`agent(): ?Agent`	Haalt de huidige Agent op
`withAgent(?Agent $agent)`	Stelt een Agent direct in
`assertDid(): string`	Geeft de geauthenticeerde DID terug. Gooit een exception als je niet geauthenticeerd bent

HTTP-client

Methode	Beschrijving
`client(bool $auth = true): AtpClient`	Geeft een geauthenticeerde (of anonieme) XRPC-client terug
`public(): BskyClient`	Geeft een client terug voor publieke endpoints zonder authenticatie
`send(BackedEnum\|string $api, string $method, bool $auth, ?array $params, ?callable $callback)`	Roept een willekeurige AT Protocol API direct aan

Utilities

Methode	Beschrijving
`identity(): Identity`	Haalt de identity-service op, voor onder andere DID-resolutie
`pds(): PDS`	Haalt de PDS-informatieservice op
`entryway(?string $path): string`	Geeft de service-URL terug (zoals `bsky.social`)
`publicEndpoint(): string`	Geeft de publieke endpoint-URL terug

De HasShortHand-trait

De HasShortHand-trait verpakt de low-level API’s van het AT Protocol in duidelijke, PHP-vriendelijke methodes. Door simpelweg use HasShortHand; toe te voegen aan BlueskyManager kun je deze methodes direct via Bluesky:: aanroepen.

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

De reden dat HasShortHand een aparte trait is, is dat dit het testen en aanpassen makkelijker maakt. Met deze trait blijft de code van BlueskyManager eenvoudig, terwijl er toch een rijke set API-shortcuts beschikbaar is.

Posts en feeds

Methode	Beschrijving
`post(Post\|string\|array $text)`	Maakt een nieuwe post
`getPost(string $uri)`	Haalt een post op via AT-URI
`getPosts(array $uris)`	Haalt meerdere posts in één keer op
`deletePost(string $uri)`	Verwijdert een post
`getTimeline(?string $algorithm, ?int $limit, ?string $cursor)`	Haalt de home-timeline op
`getAuthorFeed(?string $actor, ...)`	Haalt de feed van een specifiek account op
`searchPosts(string $q, ...)`	Zoekt posts

Interacties

Methode	Beschrijving
`like(Like\|StrongRef $subject)`	Maakt een like
`deleteLike(string $uri)`	Verwijdert een like
`repost(Repost\|StrongRef $subject)`	Maakt een repost
`deleteRepost(string $uri)`	Verwijdert een repost
`getActorLikes(?string $actor, ...)`	Haalt de lijst met likes van een account op

Volgen

Methode	Beschrijving
`follow(Follow\|string $did)`	Volgt een account
`deleteFollow(string $uri)`	Ontvolgt een account
`getFollowers(?string $actor, ...)`	Haalt de lijst met volgers op
`getFollows(?string $actor, ...)`	Haalt de lijst met gevolgde accounts op

Profiel en account

Methode	Beschrijving
`getProfile(?string $actor)`	Haalt een profiel op
`upsertProfile(callable $callback)`	Werkt een profiel bij
`resolveHandle(string $handle)`	Lost een handle op naar een DID

Media

Methode	Beschrijving
`uploadBlob(StreamInterface\|string $data, string $type)`	Uploadt een blob, zoals een afbeelding
`uploadVideo(StreamInterface\|string $data, string $type)`	Uploadt een video
`getJobStatus(string $jobId)`	Controleert de jobstatus van een video-upload
`getUploadLimits()`	Haalt de uploadlimieten op

Notificaties

Methode	Beschrijving
`listNotifications(...)`	Haalt de lijst met notificaties op
`countUnreadNotifications(...)`	Haalt het aantal ongelezen notificaties op
`updateSeenNotifications(string $seenAt)`	Markeert notificaties als gelezen

AT Protocol record-operaties

Methode	Beschrijving
`createRecord(string $repo, string $collection, ...)`	Maakt een record
`getRecord(string $repo, string $collection, string $rkey, ...)`	Haalt een record op
`listRecords(string $repo, string $collection, ...)`	Haalt een lijst met records op
`putRecord(string $repo, string $collection, string $rkey, ...)`	Werkt een record bij of maakt het aan
`deleteRecord(string $repo, string $collection, string $rkey, ...)`	Verwijdert een record

Feedgenerators en labelers

Methode	Beschrijving
`publishFeedGenerator(BackedEnum\|string $name, Generator $generator)`	Publiceert een feedgenerator
`createThreadGate(string $post, ?array $allow)`	Maakt een threadgate
`upsertLabelDefinitions(callable $callback)`	Werkt labeldefinities bij
`deleteLabelDefinitions()`	Verwijdert labeldefinities
`createLabels(RepoRef\|StrongRef\|array $subject, array $labels)`	Kent labels toe
`deleteLabels(RepoRef\|StrongRef\|array $subject, array $labels)`	Verwijdert labels

Voorbeelden van veelgebruikte shortcuts

Posten

use Revolution\Bluesky\Facades\Bluesky;

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

Reageren

Voor een reply stel je met Post::build() de StrongRef van de bovenliggende post in. HasShortHand heeft geen aparte reply()-methode; je geeft een Post-object door aan 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('Tekst van de reply')
    ->reply(root: $parent, parent: $parent);

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

Liken en reposten

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

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

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

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

Profiel bijwerken

upsertProfile() haalt het huidige profiel op en slaat de wijzigingen op die je in de closure maakt. Met de methodes van het Profile-object kun je onder andere displayName en description instellen.

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

Bluesky::login(config('bluesky.identifier'), config('bluesky.password'))
    ->upsertProfile(function (Profile $profile) {
        $profile->displayName('Nieuwe weergavenaam')
                ->description('Profielbeschrijving');
    });

Zelflabels instellen

Met SelfLabels kun je zelflabels instellen voor het hele account.

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']));
    });

Een willekeurige API direct aanroepen

Voor methodes die niet in HasShortHand zitten, gebruik je send() of client().

use Revolution\Bluesky\Facades\Bluesky;

// Een willekeurige XRPC-methode aanroepen met send()
$response = Bluesky::withToken($session)
    ->send(
        api: 'app.bsky.actor.getProfiles',
        method: 'get',
        params: ['actors' => ['did:plc:...', 'did:plc:...']],
    );

// Fijnmaziger werken met client()
$response = Bluesky::withToken($session)
    ->client()
    ->bsky()
    ->getProfiles(actors: ['did:plc:...']);

Verschil tussen de Facade en direct gebruik

Bluesky::post() en app(Factory::class)->post() werken op dezelfde BlueskyManager-instantie.

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

// Via de Facade (gebruikelijke aanpak)
Bluesky::login(config('bluesky.identifier'), config('bluesky.password'))
    ->post('Hello');

// Direct uit de container halen
$manager = app(Factory::class);
$manager->login(config('bluesky.identifier'), config('bluesky.password'))
        ->post('Hello');

// DI via 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');
    }
}

Door de scoped-registratie blijft de sessiestatus na login() behouden binnen één request.

Conditionable en Macroable

BlueskyManager gebruikt ook de traits Conditionable en 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('Post vanuit de productieomgeving');
    });

Macroable: eigen methodes toevoegen

Met macro() kun je vanuit je applicatie methodes toevoegen aan BlueskyManager. Meestal definieer je deze in de boot() van je AppServiceProvider.

use Revolution\Bluesky\Facades\Bluesky;

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

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

Een custom Agent inpluggen

Met withAgent() kun je een willekeurige Agent-implementatie direct instellen.

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

// Implementeer de Agent-interface als je een custom Agent maakt
class MyCustomAgent implements Agent
{
    // ...
}

Bluesky::withAgent(new MyCustomAgent());

Bij de normale authenticatie (login() / withToken()) wordt de agent automatisch ingesteld, dus withAgent() gebruik je in de praktijk vooral bij testen.

Referenties

Vergelijking van authenticatiemethodes — details over App Password en OAuth
Basic client — API-voorbeelden na authenticatie
Testen — testen met Fakes
Source: src/BlueskyManager.php
Source: src/HasShortHand.php

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter kits

Feeds en RSS

Middleware

Overzicht

Architectuur

Kernmethodes van BlueskyManager

Authenticatie

Agent-operaties

HTTP-client

Utilities

De HasShortHand-trait

Posts en feeds

Interacties

Volgen

Profiel en account

Media

Notificaties

AT Protocol record-operaties

Feedgenerators en labelers

Voorbeelden van veelgebruikte shortcuts

Posten

Reageren

Liken en reposten

Profiel bijwerken

Zelflabels instellen

Een willekeurige API direct aanroepen

Verschil tussen de Facade en direct gebruik

Conditionable en Macroable

Conditionable: when() / unless()

Macroable: eigen methodes toevoegen

Een custom Agent inpluggen

Referenties

​Overzicht

​Architectuur

​Kernmethodes van BlueskyManager

​Authenticatie

​Agent-operaties

​HTTP-client

​Utilities

​De HasShortHand-trait

​Posts en feeds

​Interacties

​Volgen

​Profiel en account

​Media

​Notificaties

​AT Protocol record-operaties

​Feedgenerators en labelers

​Voorbeelden van veelgebruikte shortcuts

​Posten

​Reageren

​Liken en reposten

​Profiel bijwerken

​Zelflabels instellen

​Een willekeurige API direct aanroepen

​Verschil tussen de Facade en direct gebruik

​Conditionable en Macroable

​Conditionable: when() / unless()

​Macroable: eigen methodes toevoegen

​Een custom Agent inpluggen

​Referenties

Overzicht

Architectuur

Kernmethodes van BlueskyManager

Authenticatie

Agent-operaties

HTTP-client

Utilities

De HasShortHand-trait

Posts en feeds

Interacties

Volgen

Profiel en account

Media

Notificaties

AT Protocol record-operaties

Feedgenerators en labelers

Voorbeelden van veelgebruikte shortcuts

Posten

Reageren

Liken en reposten

Profiel bijwerken

Zelflabels instellen

Een willekeurige API direct aanroepen

Verschil tussen de Facade en direct gebruik

Conditionable en Macroable

Conditionable: when() / unless()

Macroable: eigen methodes toevoegen

Een custom Agent inpluggen

Referenties