Weave Code
Laravel Bluesky Laravel Package
revolution/laravel-bluesky
A Laravel package for integrating Bluesky and the AT Protocol into your app. Connect accounts, publish posts, and interact with the Bluesky API through a clean, framework-friendly wrapper with simple configuration and service provider support.
At a glance
Frequently asked questions about Laravel Bluesky
- How do I install and configure revolution/laravel-bluesky in a Laravel application?
- Install it with Composer using composer require revolution/laravel-bluesky. The package registers its own service provider and ships a publishable configuration block where you supply your Bluesky credentials and connection settings. After publishing the config you can resolve the client from the container or through the provided facade, so no manual wiring is required. On supported Laravel versions package auto-discovery handles the provider registration for you.
- Does this package support Bluesky OAuth login, or only handle and app password authentication?
- Both paths appear to be covered. The 1.1.0 release adds a BlueskyProvider that acts as a Socialite-style OAuth driver, including the transition:email scope, which points at the AT Protocol authorization-code plus DPoP flow rather than only handle and app password credentials. The older app-password route still underpins the simple write path, so you can keep it during a migration. Verify coexistence against your target version before dropping app passwords from your provisioning.
- Which Laravel and PHP versions does revolution/laravel-bluesky support?
- The package follows standard Laravel package conventions and constrains illuminate/* dependencies, but check composer.json in the repository for the exact Laravel major and PHP range before committing. Because it is a small, single-maintainer package, support for the newest Laravel release can lag the framework. Pin the version in composer.json and run your test suite after each Laravel upgrade to catch constraint conflicts early.
- How do I publish a post to Bluesky from a Laravel controller or queued job?
- Resolve the Bluesky client from the container or facade and call the post-creation methods the package exposes; the service provider binds it as a singleton, so it behaves the same in a controller, job, or console command. The idiomatic pattern is Controller to Job to Facade, keeping the HTTP call off the request cycle. Queue the job so Bluesky latency and rate-limit backoff do not block your users. Store the returned post identifiers if you need to correlate or delete posts later.
- How does BlueskyProvider work with Laravel Socialite for Bluesky sign-in?
- BlueskyProvider is a Socialite-style driver, so the intended usage is the familiar Socialite redirect and callback flow rather than hand-rolled OAuth. It handles the AT Protocol specifics, including DPoP proof construction and JWT exp claims, which you would otherwise have to implement and get right yourself. That makes per-user or per-tenant publishing plausible instead of provisioning a handle and app password for every account. Confirm the driver is registered in your Socialite configuration and test the full redirect round trip in staging before relying on it.
- Where is the DPoP private key stored and how do I rotate it?
- DPoP introduces a new class of secret that is separate from app passwords, and the package does not manage its storage or rotation for you, so that is your application's responsibility. Decide whether the key is scoped per user, per session, or per tenant, and persist it in the same encrypted store you use for other credentials. Rotation has to be coordinated with Bluesky, so plan a re-authorization path and treat a missing or mismatched key as an auth failure rather than a transient error. Because key and proof defects surface as intermittent authentication failures, log the proof generation path in staging.
- Do I need a long-running worker to use FirehoseSyncMessage?
- Yes. FirehoseSyncMessage and its sync handler consume the AT Protocol firehose, which is an inbound streaming workload rather than a request-scoped API call. That means a supervised long-lived process, durable cursor persistence so you can resume after a restart, and a backfill strategy for gaps. Treat it as a separate workstream from the publishing integration, closer to a queue consumer or websocket worker than a facade call. A reconnect defect shows up as silent data gaps weeks later, so add cursor lag monitoring.
- How does the package handle Bluesky rate limits and API errors?
- Rate-limit handling is largely left to the caller, so build retry and backoff into the job or command that calls the API rather than assuming the client does it. Since the client is bound as a singleton, avoid holding it across long-running loops without accounting for token refresh and error state. Catch and classify failures so a 429 is retried with delay while auth errors fail fast instead of looping. Log request and response context for Bluesky calls the same way you would for any third-party integration.
- How can I test the Bluesky integration without calling the real API?
- Because the client is container-bound and exposed through a facade, you can swap or fake the binding in your test suite and assert that posting jobs dispatch and call the expected methods. The package has no third-party dependencies beyond Laravel, so there is very little transitive surface to mock. Keep a thin adapter around the client if you want to test your own application logic independently of the package's API. Add a small number of staging tests against a real Bluesky test account to validate auth and DPoP behavior that fakes cannot cover.
- Is revolution/laravel-bluesky production ready, and what are the alternatives?
- It is a small, zero-dependency, single-maintainer package with a modest star count, so there is no strong downstream signal that the OAuth, DPoP, and firehose code is widely exercised in production. Weigh that against the fact that the codebase is small enough to read, audit, and fork if the maintainer falls behind. The write path of authenticate and post is the lowest-risk part; the firehose consumer and notification subscriptions are newer and should be scoped separately. If you need a more supported option, compare against calling the AT Protocol HTTP endpoints directly or a community SDK, and budget for protocol drift either way since AT Protocol OAuth and Jetstream move quickly.
Weaver
How can I help you explore Laravel packages today?