- How do I install graham-campbell/bitbucket in a Laravel app?
- Install it with Composer using composer require graham-campbell/bitbucket, then publish the package config with php artisan vendor:publish and select the bitbucket config tag. Add your Bitbucket OAuth consumer credentials or app password to your .env file, then resolve the client through the Bitbucket facade or by type-hinting the manager. Laravel's package auto-discovery registers the service provider and facade alias, so no manual wiring is needed in most setups.
- Which Laravel and PHP versions does this package support?
- The package targets modern Laravel releases and recent PHP versions, with v11.1.0 adding Laravel 13 and PHP 8.5 compatibility. Because release notes typically state what was added rather than what was dropped, check the composer.json constraints and the package's CI matrix before committing to a version. Confirm that Laravel 13 and PHP 8.5 are actually exercised in CI rather than only allowed by widened constraints, since an untested constraint can resolve into an unverified combination.
- How do I configure Bitbucket connections and credentials?
- Connections live in the published config/bitbucket.php file and are driven by environment variables, so you can define one or more named connections with their own consumer key, secret, and token settings. Resolve a specific connection through the manager rather than hardcoding credentials in application code. If you run php artisan config:cache in production, remember that the cached configuration is a plaintext secret at rest, so protect file permissions and confirm no token logging occurs in debug mode.
- Should I use the Bitbucket facade or dependency injection?
- Both work: the facade is convenient for quick calls, while dependency injection gives you testability and explicit dependencies. Type-hint the package's manager or client in a constructor or method signature and Laravel's container will resolve it, optionally selecting a named connection. For anything beyond a script, prefer injecting the client so your class stays decoupled from the facade's static surface.
- What Bitbucket resources can I access through this package?
- The package wraps the Bitbucket PHP client, so you get the SDK's resource endpoints for repositories, pull requests, users, teams, and webhooks, plus related areas like commit statuses and pipelines. It does not add its own domain model or abstractions on top of those resources, so the calls you make mirror the upstream client's API. Anything the underlying SDK exposes is available to you; anything it lacks is not added by the wrapper.
- Does this package work with Bitbucket Server or Data Center?
- No, it is aimed at Bitbucket Cloud's API v2, matching the upstream bitbucket/client SDK it depends on. Bitbucket Server and Data Center use different REST endpoints and authentication models, so they are out of scope here. If you need self-hosted Bitbucket, plan on a separate client rather than trying to point this package at a Server instance.
- What breaks when upgrading to version 11 with bitbucket/client 5.x?
- The material risk is the transitive SDK major bump from bitbucket/client 4.x to 5.x, which can change client construction, exception hierarchy, pagination iterators, and resource namespaces. Any code that catches SDK exceptions, type-hints SDK classes, or walks paginated results directly is exposed, and the dangerous failures are silent response-shape changes rather than fatals your CI catches. Review the upstream upgrade guide, run your integration tests against a real workspace, and treat the upgrade as a code change with a dependency-review gate rather than a lockfile refresh.
- Should I wrap this package behind my own interface?
- Yes, and it is the highest-leverage decision you can make with this package. A thin internal gateway with methods like get repository, list pull requests, post commit status, and read pipeline keeps SDK types out of your application code, so the next SDK major becomes a one-file change and a vendor swap stays realistic. The package is a thin adapter with no persistence or queue opinions, so it is easy to hide behind your own contract.
- How do I test code that uses the Bitbucket facade?
- Swap the container binding for a fake or stub in your test suite, or use the facade's shouldReceive helpers for the calls your code makes. Because the package delegates almost everything to the SDK and exposes SDK objects, assertions can end up coupled to SDK response shapes, which makes a small hand-written gateway interface easier to fake. Keep contract tests against a sandbox Bitbucket workspace for the handful of calls that matter most.
- Is this package actively maintained, and what are the alternatives?
- Graham Campbell maintains it and has historically tracked upstream promptly, including adding Laravel 13 and PHP 8.5 support soon after release. Adoption is thin, with few dependents, so you get limited downstream validation of any specific version combination and should budget for being an early adopter. Alternatives are using bitbucket/client directly and wiring your own service provider, calling the Bitbucket Cloud REST API through Guzzle, or using a different Bitbucket SDK if one fits your requirements better.