Laravel Beehiiv Laravel Package

Getting Started

• Install via Composer: composer require jeffersongoncalves/laravel-beehiiv. Laravel's package discovery registers the service provider and the Beehiiv facade automatically.

• Publish the config: php artisan vendor:publish --tag=beehiiv-config. This drops config/beehiiv.php into your application.

• Add the two required credentials to .env:

  • BEEHIIV_API_KEY — issued from your Beehiiv dashboard under Settings › API.
  • BEEHIIV_PUBLICATION_ID — found in the Beehiiv URL (/publications/pub_xxxxxxx/...).

• First use case: subscribing a user to your newsletter. A minimal smoke test in Tinker:

  use JeffersonGoncalves\Beehiiv\Facades\Beehiiv;
  
  Beehiiv::subscriptions()->create(email: '[email protected]');
  

  A successful response returns a subscription object with an id you can persist locally for later lookups.

• Look first at the published config (for the base URI and timeout/retry knobs) and the facade class under src/Facades/Beehiiv.php — it exposes the resource accessors (publications(), subscriptions(), posts(), segments(), webhooks()), which map one-to-one onto the Beehiiv API surface.

Implementation Patterns

• Subscribe on signup. Wire the package into a domain event rather than a controller. A Registered event listener that calls Beehiiv::subscriptions()->create(...) keeps newsletter sign-ups decoupled from auth and makes the behavior easy to disable per project.
• Persist subscription IDs. After creating a subscription, store the returned id on your users table (beehiiv_subscription_id). This gives you a cheap join for later update/unsubscribe flows without hitting the API to search by email.
• Bulk sync command. A php artisan beehiiv:sync-users command that chunks your users table and calls the subscription endpoint per user (respecting rate limits) is the standard onboarding pattern for adding an existing user base to a publication.
• Webhook-driven state changes. Register https://your-app/webhooks/beehiiv by calling Beehiiv::webhooks()->create(...) once in a migration or bootstrap command, then handle inbound events (subscription.created, subscription.deleted, etc.) in a controller. Store inbound payloads verbatim alongside your normalized fields — Beehiiv payloads evolve and a raw column saves you from schema churn.
• Segment targeting for posts. When composing a scheduled launch, use Beehiiv::posts()->create(...) with a segment_id pulled from Beehiiv::segments()->all(). Cache the segment list for a few minutes — it rarely changes and saves a round trip per editorial request.
• Wrap in a service. Even for a small integration, wrap the facade behind your own NewsletterService with methods like subscribe(), unsubscribe(), isSubscribed(). This keeps the package's fluent API out of your controllers and gives you a seam to fake in tests ($this->mock(NewsletterService::class)).
• Queue the calls. Every Beehiiv call is a synchronous HTTP request. Push subscription writes and post creation onto a queue job (ShouldQueue) so a slow Beehiiv response never blocks a checkout or registration request.

Gotchas and Tips

• publication_id is required for most endpoints but lives only in config. If you support multi-brand newsletters in a single app, the single global config is a limit — you'll need to instantiate client objects manually or override config per request.
• Beehiiv returns nested data envelopes. List endpoints return ['data' => [...], 'page' => ..., 'limit' => ...], not a flat array. Don't assume count() of the top-level response reflects result count.
• Pagination is not "offset/limit" — Beehiiv uses cursor-ish page numbers. Loop until the returned page exceeds the last page rather than until an empty array; the API can return a short page mid-run.
• Handle 4xx explicitly. The package throws exceptions on non-2xx responses; catch the package's API exception type (and ConnectionException) separately from your own domain errors, or you'll mask real bugs.
• Debugging: enable Laravel's HTTP client logging around the package (Http::globalRequestMiddleware(...)) or set the config timeout to a low value while verifying credentials — the default timeout can make 401/403 misconfiguration look like a hang.
• Rate limits. Beehiiv throttles aggressively on subscription creation. For bulk imports, sleep 100–200 ms between calls or use a rate-limited queue job; otherwise you'll see intermittent 429s that surface as generic exceptions.
• Webhook signature verification is not automatic — validate the signing header against the raw request body before trusting the payload. Use $request->getContent() (raw), not $request->all(), or verification will fail.
• Config caching. After php artisan config:cache the published beehiiv.php is frozen; env changes require a recache. A frequent "my API key doesn't work" cause in production.
• Extension points: the facade resolves the underlying client from the container, so you can bind a decorated client (logging, retries, circuit breaking) via $this->app->extend(...) in a service provider without forking the package.

Release note caveat: 1.0.0 ships with only a changelog link — no migration notes, breaking-change list, or feature summary. Treat the API surface as the baseline and pin the version in composer.json until subsequent release notes document behavioral changes.