bitbucket / client
Bitbucket API 2.0 client for PHP
Fund package maintenance!
GrahamCampbell
Tidelift
Installs: 517 871
Dependents: 11
Suggesters: 0
Security: 0
Stars: 98
Watchers: 5
Forks: 26
Open Issues: 5
Requires
- php: ^7.4.15 || ^8.0.2
- ext-json: *
- php-http/cache-plugin: ^1.8.1 || ^2.0
- php-http/client-common: ^2.7.1
- php-http/discovery: ^1.19.2
- php-http/httplug: ^2.4
- php-http/multipart-stream-builder: ^1.3
- psr/cache: ^1.0 || ^2.0 || ^3.0
- psr/http-client-implementation: ^1.0
- psr/http-factory-implementation: ^1.0
- psr/http-message: ^1.1 || ^2.0
- symfony/polyfill-php80: ^1.26
Requires (Dev)
- bamarni/composer-bin-plugin: ^1.8.2
- guzzlehttp/guzzle: ^7.8
- http-interop/http-factory-guzzle: ^1.2
- php-http/mock-client: ^1.6
- 4.7.x-dev
- v4.7.0
- 4.6.x-dev
- v4.6.1
- v4.6.0
- 4.5.x-dev
- v4.5.0
- 4.4.x-dev
- v4.4.0
- 4.3.x-dev
- v4.3.0
- 4.2.x-dev
- v4.2.0
- 4.1.x-dev
- v4.1.0
- 4.0.x-dev
- v4.0.2
- v4.0.1
- v4.0.0
- 3.3.x-dev
- v3.3.1
- v3.3.0
- 3.2.x-dev
- v3.2.3
- v3.2.2
- v3.2.1
- v3.2.0
- 3.1.x-dev
- v3.1.0
- 3.0.x-dev
- v3.0.1
- v3.0.0
- 2.1.x-dev
- v2.1.5
- v2.1.4
- v2.1.3
- v2.1.2
- v2.1.1
- v2.1.0
- v2.0.2
- v2.0.1
- v2.0.0
- 1.1.x-dev
- v1.1.2
- v1.1.1
- v1.1.0
- v1.0.1
- v1.0.0
This package is auto-updated.
Last update: 2024-12-17 23:08:24 UTC
README
We present a modern Bitbucket API 2.0 client for PHP.
This is strongly based on php-github-api by KnpLabs. With this in mind, we now have very similar clients for:
- GitHub - knplabs/github-api by KnpLabs.
- GitLab - m4tthumphrey/php-gitlab-api by Matt Humphrey et al.
- Bitbucket - bitbucket/client which is this package!
Check out the change log, releases, security policy, license, code of conduct, and contribution guidelines.
Installation
This version supports PHP 7.4-8.3. To get started, simply require the project using Composer. You will also need to install packages that "provide" psr/http-client-implementation
and psr/http-factory-implementation
.
Standard Installation
$ composer require "bitbucket/client:^4.7" \ "guzzlehttp/guzzle:^7.8" "http-interop/http-factory-guzzle:^1.2"
Framework Integration
Laravel:
$ composer require "graham-campbell/bitbucket:^10.4"
We are decoupled from any HTTP messaging client by using PSR-7, PSR-17, PSR-18, and HTTPlug. You can visit HTTPlug for library users to get more information about installing HTTPlug related packages. The framework integration graham-campbell/bitbucket
is by Graham Campbell.
Usage
The main point of entry is the Bitbucket\Client
class. Simply create a new instance of that, authenticate, and you're good to go! As of time of writing (Tuesday 29th June 2020), every endpoint (excluding issue export and import, and various deprecated endpoints) available on the Bitbucket API 2.0 is also available through this PHP client. We'd recommend looking through the Bitbucket documentation, and also the source code to get a full picture of what is available to use.
Authentication
There are three ways to authenticate our client:
OAuth 2 Token
The most common way to authenticate is using an OAuth 2 token. You will need to generate this by some means outside of the library, and then provide it as below:
$client = new Bitbucket\Client(); $client->authenticate( Bitbucket\Client::AUTH_OAUTH_TOKEN, 'your-token-here' );
HTTP Password
It is possible to login using a username and password combination. This method is not recommended for production use, however you may find it useful never the less:
$client = new Bitbucket\Client(); $client->authenticate( Bitbucket\Client::AUTH_HTTP_PASSWORD, 'your-username-here', 'your-password-here' );
If you have two-factor authentication enabled on your account, then you must use an application password.
JSON Web Token
Finally, we support logging in using JSON web tokens (JWTs). This method is exclusively required by some of Bitbucket's API endpoints, such as the addons API. Generate your JWT, perahps using lcobucci/jwt, then provide it as below:
$client = new Bitbucket\Client(); $client->authenticate( Bitbucket\Client::AUTH_JWT, 'your-jwt-here' );
Examples
In the following examples, $client
will be an authenticated client, as above.
Example 1
It is possible to show basic information about the currently logged in user:
$currentUser = $client->currentUser()->show();
Example 2
It is possible to grab a repository as follows:
$repository = $client->repositories() ->workspaces('atlassian') ->show('stash-example-plugin');
Example 3
We support automatic pagination without you having to lift a finger. The following example gets all branches of a repository:
$paginator = new Bitbucket\ResultPager($client); $branchesClient = $client->repositories() ->workspaces('atlassianlabs') ->refs('stash-log-parser']) ->branches(); $branches = $paginator->fetchAll($branchesClient, 'list');
Contributing
We will gladly receive issue reports and review and accept pull requests, in accordance with our code of conduct and contribution guidelines!
$ make install
$ make test
Security
If you discover a security vulnerability within this package, please send an email to Graham Campbell at hello@gjcampbell.co.uk. All security vulnerabilities will be promptly addressed. You may view our full security policy here.
License
Bitbucket PHP API Client is licensed under The MIT License (MIT).
For Enterprise
Available as part of the Tidelift Subscription
The maintainers of bitbucket/client
and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. Learn more.