Laravel Dub Laravel Package

Product Decisions This Supports

• Build vs. buy for link infrastructure. This package is a thin client over Dub.co's hosted API. It lets you ship branded short links, bulk link creation, and click analytics without building redirect services, click tracking, or analytics aggregation in-house. The PM decision it informs: do we build a link-shortening/analytics subsystem or rent one? For most teams the answer is rent — link infra is undifferentiated, and this package makes the rental cheap to adopt on Laravel.
• Feature enablement on the roadmap. Directly unblocks shareable/branded links in-product (invites, referrals, campaign URLs), marketing attribution via UTM-tagged links, and lightweight analytics surfaces (clicks by country/device) inside an admin panel or customer dashboard.
• Scope discipline. Analytics exposed here are aggregate breakdowns (country, device), not a full analytics warehouse. That's a signal to scope roadmap items as "link performance summaries," not "replace our BI stack." bulkCreateLinks supports campaign/batch workflows; listLinks/getLink/updateLink/deleteLink cover CRUD lifecycle management for an admin link-management screen.
• Integration sequencing. Because it's config-driven (DUB_API_KEY, DUB_API_URL, DUB_TIMEOUT), it slots into a Laravel service with near-zero setup — suitable for a spike/MVP. It does not cover webhooks/events, custom domains, tags, or QR codes in this release, so roadmap items depending on those must be deferred or built against the raw API.
• Reliability budgeting. Rate-limit awareness (typed DubRateLimitException honoring Retry-After) means the PM can plan for graceful degradation and queueing rather than assuming unlimited throughput — relevant for high-volume bulk operations and campaign launches.

When to Consider This Package

Adopt when:

• You are on Laravel (or plain PHP) and want a minimal, dependency-light client to the Dub.co hosted API.
• Your need is standard link CRUD plus aggregate click analytics — short links, branded URLs, campaign tracking, referral links.
• You want fast time-to-value: config-only setup, static calls, no service container wiring to reason about.
• You can tolerate provider coupling to Dub.co and its API/rate limits.
• Your volume fits within Dub's rate limits or you can queue/retry around DubRateLimitException.

Look elsewhere (or plan to wrap/extend) when:

• You need testability and DI. A static client is awkward to mock; expect to lean on Laravel's HTTP fakes or write a thin adapter interface around it so your domain code isn't coupled to static calls.
• You need webhooks, event subscriptions, custom domains, tags, or QR generation — not exposed in 1.0.0; you'd call the API directly or wait for a later release.
• You need self-hosting. Dub is open source, but this client targets the hosted API (DUB_API_URL is configurable, so self-hosted may work, but it's untested/unsupported here).
• You require rich error handling beyond 429 — this release only names rate-limit exceptions; general 4xx/5xx handling is unspecified, so verify before relying on it for critical flows.
• You need pagination semantics, DTOs, or typed responses — not mentioned; listLinks behavior at scale should be validated.
• You're not on Laravel/PHP, or you'd rather use Dub's official SDKs.

How to Pitch It (Stakeholders)

To executives: We can add branded short links, campaign tracking, and basic click analytics to our product without building or maintaining that infrastructure ourselves. This package is a small, config-only integration to a proven link platform (Dub.co) — days of work, not a quarter, and no new servers to run. It keeps us on the "buy" side of build-vs-buy for undifferentiated plumbing and lets the team focus on product. Main trade-off: we take on a vendor dependency and are bounded by their rate limits and feature set (no webhooks/QR/custom-domain management in this release).

To engineering: Thin static PHP client over Dub's REST API covering link CRUD, bulk create, and aggregate analytics, with typed rate-limit exceptions that respect Retry-After. Zero-config via environment variables. Caveats to plan around: static calls hurt mockability — wrap it behind an interface/facade we control and use Laravel's HTTP fake in tests; error handling beyond 429 is thin, so add a resilient wrapper with retry/queueing for bulk and launch-critical paths; confirm pagination and self-hosted-URL behavior before depending on them. Treat it as an adapter to isolate, not a deep architectural commitment.