Bitbucket Laravel Package

Product Decisions This Supports

• Build vs. buy for Bitbucket integrations. This package is a thin Laravel adapter over Bitbucket's official bitbucket/client SDK — service provider, facade, publishable config, container binding, auto-discovery. It removes the plumbing (auth wiring, HTTP client configuration, dependency injection, config caching) that typically consumes 20–40% of a first integration and nearly all of its ongoing maintenance. That is a buy, not a build, and the price is a Composer line.
• Roadmap sequencing for developer-workflow features. Anything that reads or writes Bitbucket — PR status on an internal dashboard, pipeline status in an admin panel, branch-per-ticket automation, repo provisioning for new tenants, code-review SLA reporting, deploy triggers — flips from "API integration project" to "configuration plus mapping logic." That is the difference between a next-quarter item and a next-sprint item, and it is the single most useful fact for prioritisation.
• Platform upgrade planning. v11.1.0 explicitly targets PHP 8.5 and Laravel 13 and tracks upstream SDK releases rather than lagging them. That makes it a defensible line item in the dependency register when planning our own runtime upgrade — provided we confirm the additions are additive and no supported versions were dropped.
• Vendor-lock and reversibility posture. Because it wraps the official SDK rather than hand-rolling HTTP calls, the exit path is to the raw SDK, not to a rewrite. Blast radius of a Bitbucket API change is small; cost of reversal is low. That is a risk profile that can be approved without a committee.
• Adoption-signal caveat that belongs in the decision record. Zero dependents and a single-maintainer community package is a real signal — not a disqualifier, but it means the decision is "we accept a small bus factor in exchange for saved plumbing," and it should be written down as such rather than buried.
• Where it should not decide anything: it is an integration library, not a capability. It should not shape pricing, packaging, or user-facing differentiation. The strategic question is which VCS we standardise on; this package is downstream of that answer and cheap to reverse if the answer changes.

When to Consider This Package

Consider it when:

• You are on Laravel and need to talk to Bitbucket Cloud (repositories, pull requests, pipelines, webhooks, workspaces) from application code.
• You want the integration to look like the rest of the codebase — config file, facade, container bindings, queued jobs — so it is maintainable by the team, not by the one engineer who wrote it.
• You want forward-compatibility headroom: the v11.1.0 line targets PHP 8.5 and Laravel 13, so adopting now avoids a re-platform in the next upgrade window.
• Your use case is a consumer of Bitbucket data — dashboards, reporting, automation triggers — where the value you add is the mapping layer, not the transport.
• You are willing to wrap it behind your own thin interface so the next SDK major bump is a one-file change.

Look elsewhere when:

• You need Bitbucket Server / Data Center rather than Cloud — the auth model and SDK coverage differ; verify against bitbucket/client 5.1 before committing.
• The integration is trivial and one-directional (a single webhook receiver). A hand-rolled controller plus signed-payload verification may be less total surface area than a dependency.
• You are pinned to bitbucket/client 4.x elsewhere in the monorepo. v11.1.0 raises the floor to 5.1 on a minor wrapper release — run composer why-not bitbucket/client ^5.1 before assuming the lockfile will move, and stage the bump in a branch.
• You need a supported, SLA-backed vendor. This is community OSS with a single-maintainer bus factor; keep a fork-ready patch path and budget a roughly annual SDK-migration spike.
• Bitbucket is not your system of record. If the organisation is standardising on GitHub or GitLab, adopting this deepens a strategic inconsistency for the sake of a sprint of saved work.

Adoption checklist before committing: confirm the support matrix (does v11.1.0 drop any Laravel or PHP versions, or only add?); review the bitbucket/client 4.x → 5.x changelog for breaking changes in client construction, exception hierarchy, pagination iterators, and resource namespaces; check the licence against our distribution model; and look at release cadence over the last 12 months, not just this release.

How to Pitch It (Stakeholders)

To executives (one paragraph): This is a small, actively maintained open-source library that connects our Laravel application to Bitbucket using Bitbucket's own official SDK. It converts what would otherwise be a bespoke integration project into configuration plus our business logic — meaningfully less engineering time up front and, more importantly, far less ongoing maintenance as Bitbucket's API evolves. The current release explicitly supports the next PHP and Laravel versions, so it will not become an upgrade blocker. Licence cost is zero; the investment is a one-to-two-day evaluation spike and a review of one transitive dependency bump. The main caveat to note is that it is community-maintained with a small maintainer base, which we mitigate by keeping our own wrapper thin and staying fork-ready.

To engineering leadership: Approve a time-boxed spike (1–2 days) to wire the package into a branch, confirm the new bitbucket/client 5.1 floor resolves cleanly against our lockfile, and exercise the two or three endpoints the roadmap actually needs — including the OAuth refresh path, pagination, and error handling. Success criteria: clean install on our target PHP/Laravel versions, no constraint conflicts, and a working read path against a non-production workspace. The only thing to scrutinise in these release notes is the SDK major-version floor raise; the PHP 8.5 and Laravel 13 additions are purely additive. Follow it with a canary: ship one low-risk read-only consumer to production before migrating any write path, and instrument auth-error rate and 429s rather than relying on exception volume alone.

Framing to avoid: do not sell this as a strategic platform choice. It is a tactical dependency that removes undifferentiated plumbing, and it sits downstream of the VCS standardisation decision — which is the one that deserves the committee.