PHPackages                             bitbucket/client - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. bitbucket/client

ActiveLibrary[API Development](/categories/api)

bitbucket/client
================

Bitbucket API 2.0 client for PHP

5.1.0(1mo ago)103807.8k↓18.5%2710MITPHPPHP ^8.1CI passing

Since Apr 2Pushed 1mo ago3 watchersCompare

[ Source](https://github.com/BitbucketPHP/Client)[ Packagist](https://packagist.org/packages/bitbucket/client)[ GitHub Sponsors](https://github.com/GrahamCampbell)[ Fund](https://tidelift.com/funding/github/packagist/bitbucket/client)[ RSS](/packages/bitbucket-client/feed)WikiDiscussions 5.1 Synced 1w ago

READMEChangelog (10)Dependencies (25)Versions (77)Used By (10)

Bitbucket PHP API Client
========================

[](#bitbucket-php-api-client)

We present a modern [Bitbucket API 2.0](https://api.bitbucket.org/) client for PHP.

[![Banner](https://user-images.githubusercontent.com/2829600/86968999-f9334a80-c164-11ea-9c20-2a4f9f9c898f.png)](https://user-images.githubusercontent.com/2829600/86968999-f9334a80-c164-11ea-9c20-2a4f9f9c898f.png)

[![Build Status](https://camo.githubusercontent.com/a96ea37a753f7ebbfc421bda484e36006a34ffab260a9e3b505e295b57d75fca/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f4269746275636b65745048502f436c69656e742f74657374732e796d6c3f6c6162656c3d5465737473267374796c653d666c61742d737175617265)](https://github.com/BitbucketPHP/Client/actions?query=workflow%3ATests)[![StyleCI Status](https://camo.githubusercontent.com/e496ae405415fea0d5a3941c5a4792e6b54b714b689c53b719536f83ed7def60/68747470733a2f2f6769746875622e7374796c6563692e696f2f7265706f732f3132373436363536302f736869656c64)](https://github.styleci.io/repos/127466560)[![Software License](https://camo.githubusercontent.com/c090e080484e2a2bc766446291d04437db823929042bf614b26a1643660ddf6f/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e3f7374796c653d666c61742d737175617265)](LICENSE)[![Packagist Downloads](https://camo.githubusercontent.com/f80fdd9e2b6db1e71ef76f985eb2d99f163a530a7691188dac785c2adbd12d4f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6269746275636b65742f636c69656e743f7374796c653d666c61742d737175617265)](https://packagist.org/packages/bitbucket/client)[![Latest Version](https://camo.githubusercontent.com/2126a2cdfe623cf98b143d3f593245ce19eb70f039a963c0bcb4b3dc9c8140df/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f72656c656173652f4269746275636b65745048502f436c69656e743f7374796c653d666c61742d737175617265)](https://github.com/BitbucketPHP/Client/releases)

This is strongly based on [php-github-api](https://github.com/KnpLabs/php-github-api) by [KnpLabs](https://github.com/KnpLabs). With this in mind, we now have **very similar** clients for:

- [GitHub](https://github.com/) - [knplabs/github-api](https://packagist.org/packages/knplabs/github-api) by [KnpLabs](https://github.com/KnpLabs/php-github-api).
- [GitLab](https://gitlab.com/) - [m4tthumphrey/php-gitlab-api](https://packagist.org/packages/m4tthumphrey/php-gitlab-api) by [Matt Humphrey](https://github.com/m4tthumphrey) et al.
- [Bitbucket](https://bitbucket.org/) - [bitbucket/client](https://packagist.org/packages/bitbucket/client) which is this package!

Check out the [change log](CHANGELOG.md), [releases](https://github.com/BitbucketPHP/Client/releases), [security policy](https://github.com/BitbucketPHP/Client/security/policy), [license](LICENSE), [code of conduct](.github/CODE_OF_CONDUCT.md), and [contribution guidelines](.github/CONTRIBUTING.md).

Installation
------------

[](#installation)

This version supports [PHP](https://php.net) 8.1-8.5. To get started, simply require the project using [Composer](https://getcomposer.org). You will also need to install packages that "provide" [`psr/http-client-implementation`](https://packagist.org/providers/psr/http-client-implementation) and [`psr/http-factory-implementation`](https://packagist.org/providers/psr/http-factory-implementation).

### Standard Installation

[](#standard-installation)

```
$ composer require "bitbucket/client:^5.1" "guzzlehttp/guzzle:^7.9.2"
```

### Framework Integration

[](#framework-integration)

#### Laravel:

[](#laravel)

```
$ composer require "graham-campbell/bitbucket:^11.1"
```

We are decoupled from any HTTP messaging client by using [PSR-7](https://www.php-fig.org/psr/psr-7/), [PSR-17](https://www.php-fig.org/psr/psr-17/), [PSR-18](https://www.php-fig.org/psr/psr-18/), and [HTTPlug](https://httplug.io/). You can visit [HTTPlug for library users](https://docs.php-http.org/en/latest/httplug/users.html) to get more information about installing HTTPlug related packages. The framework integration [`graham-campbell/bitbucket`](https://github.com/GrahamCampbell/Laravel-Bitbucket) is by [Graham Campbell](https://github.com/GrahamCampbell).

Usage
-----

[](#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! This client exposes Bitbucket API 2.0 endpoints through fluent resource classes. We'd recommend looking through the [Bitbucket documentation](https://developer.atlassian.com/cloud/bitbucket/rest/intro/), and also the [source code](https://github.com/BitbucketPHP/Client/tree/5.1/src) to get a full picture of what is available to use.

### Authentication

[](#authentication)

There are three ways to authenticate our client:

#### OAuth 2 Token

[](#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 Basic

[](#http-basic)

It is possible to authenticate using HTTP Basic credentials. For [Bitbucket API tokens](https://support.atlassian.com/bitbucket-cloud/docs/api-tokens/), use your Atlassian account email as the username and the API token as the password:

```
$client = new Bitbucket\Client();

$client->authenticate(
    Bitbucket\Client::AUTH_HTTP_PASSWORD,
    'your-email@example.com',
    'your-api-token-here'
);
```

> Bitbucket API tokens are the long-term replacement for [app passwords](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/), which Bitbucket has deprecated. Do not use your Atlassian account password here.

#### JSON Web Token

[](#json-web-token)

Finally, we support logging in using JSON web tokens (JWTs). This method is required by some Bitbucket API endpoints, such as the addons API. Generate your JWT, perhaps using [lcobucci/jwt](https://github.com/lcobucci/jwt), then provide it as below:

```
$client = new Bitbucket\Client();

$client->authenticate(
    Bitbucket\Client::AUTH_JWT,
    'your-jwt-here'
);
```

### Examples

[](#examples)

In the following examples, `$client` will be an authenticated client, as above.

#### Example 1

[](#example-1)

It is possible to show basic information about the currently logged in user:

```
$currentUser = $client->currentUser()->show();
```

#### Example 2

[](#example-2)

It is possible to grab a repository as follows:

```
$repository = $client->repositories()
    ->workspaces('atlassian')
    ->show('stash-example-plugin');
```

#### Example 3

[](#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');
```

Filtering and sorting parameters can be passed through the third argument to `fetchAll()`:

```
$paginator = new Bitbucket\ResultPager($client);

$tagsClient = $client->repositories()
    ->workspaces('my-workspace')
    ->refs('my-repo')
    ->tags();

$tags = $paginator->fetchAll($tagsClient, 'list', [['q' => 'name ~ "v1"', 'sort' => '-name']]);
```

Bitbucket includes those query parameters in the `next` pagination URL, so subsequent pages preserve them automatically.

To list files from a specific branch or commit, use the source API with `ResultPager`. Directory listings include both `commit_file` and `commit_directory` entries, so filter the returned values by `type` if you only need files:

```
$paginator = new Bitbucket\ResultPager($client);

$srcClient = $client->repositories()
    ->workspaces('my-workspace')
    ->src('my-repo');

$entries = $paginator->fetchAll($srcClient, 'show', ['main', '/', ['max_depth' => 10]]);
```

### Migrating Deprecated Bitbucket Endpoints

[](#migrating-deprecated-bitbucket-endpoints)

Bitbucket is removing or deprecating several cross-workspace endpoints. This client keeps the older methods available in v5.1, but marks them as deprecated where Bitbucket has published a supported replacement or removal notice.

Deprecated usageReplacement`$client->currentUser()->listWorkspaces()``$client->currentUser()->workspaces()->list()``$client->currentUser()->listWorkspacePermissions()``$client->currentUser()->workspaces()->permissions($workspace)->show()``$client->currentUser()->listRepositoryPermissions()``$client->currentUser()->workspaces()->permissions($workspace)->repositories()->list()``$client->currentUser()->listTeamPermissions()`Workspace APIs, where applicable`$client->pullRequests()->list($selectedUser)``$client->workspaces($workspace)->pullRequests()->list($selectedUser)``$client->repositories()->list()``$client->repositories()->workspaces($workspace)->list()``$client->users($user)->repositories()->list()``$client->repositories()->workspaces($workspace)->list()``$client->snippets()->list()``$client->snippets()->workspaces($workspace)->list()`The replacement endpoints are usually workspace-scoped. If your application previously relied on cross-workspace results, enumerate the current user's workspaces and aggregate the workspace-scoped results in your application code.

```
$paginator = new Bitbucket\ResultPager($client);

foreach ($paginator->fetchAll($client->currentUser()->workspaces(), 'list') as $workspaceAccess) {
    $workspace = $workspaceAccess['workspace']['slug'];

    $permissions = $paginator->fetchAll(
        $client->currentUser()->workspaces()->permissions($workspace)->repositories(),
        'list'
    );
}
```

The supported current user workspaces endpoint returns `workspace_access` values, not the old workspace object shape. The workspace details are available under the `workspace` key on each result.

Contributing
------------

[](#contributing)

We will gladly receive issue reports and review and accept pull requests, in accordance with our [code of conduct](.github/CODE_OF_CONDUCT.md) and [contribution guidelines](.github/CONTRIBUTING.md)!

```
$ make install
$ make test

```

Security
--------

[](#security)

If you discover a security vulnerability within this package, please send an email to Graham Campbell at . All security vulnerabilities will be promptly addressed. You may view our full security policy [here](https://github.com/BitbucketPHP/Client/security/policy).

License
-------

[](#license)

Bitbucket PHP API Client is licensed under [The MIT License (MIT)](LICENSE).

For Enterprise
--------------

[](#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.](https://tidelift.com/subscription/pkg/packagist-bitbucket-client?utm_source=packagist-bitbucket-client&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)

###  Health Score

70

—

ExcellentBetter than 100% of packages

Maintenance93

Actively maintained with recent releases

Popularity54

Moderate usage in the ecosystem

Community30

Small or concentrated contributor base

Maturity87

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 97.1% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~58 days

Recently: every ~195 days

Total

52

Last Release

34d ago

Major Versions

v1.1.1 → v2.0.02019-06-29

v1.1.2 → v2.1.22020-04-12

2.1.x-dev → v3.0.02020-07-11

v3.3.1 → v4.0.02020-12-22

4.7.x-dev → 5.0.02025-02-23

PHP version history (5 changes)v1.0.0PHP ^7.1.3

v3.3.0PHP ^7.1.3 || ^8.0

v4.0.0PHP ^7.2.5 || ^8.0

v4.2.0PHP ^7.4.15 || ^8.0.2

5.0.0PHP ^8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/d95eb26cb8f3919bb5ca3b6d823daeabbf259663778a970349b245c580713c8e?d=identicon)[graham-campbell](/maintainers/graham-campbell)

---

Top Contributors

[![GrahamCampbell](https://avatars.githubusercontent.com/u/2829600?v=4)](https://github.com/GrahamCampbell "GrahamCampbell (367 commits)")[![StyleCIBot](https://avatars.githubusercontent.com/u/11048387?v=4)](https://github.com/StyleCIBot "StyleCIBot (3 commits)")[![hadjedjvincent](https://avatars.githubusercontent.com/u/3198580?v=4)](https://github.com/hadjedjvincent "hadjedjvincent (2 commits)")[![stayallive](https://avatars.githubusercontent.com/u/1090754?v=4)](https://github.com/stayallive "stayallive (1 commits)")[![tacman](https://avatars.githubusercontent.com/u/619585?v=4)](https://github.com/tacman "tacman (1 commits)")[![dvcom69](https://avatars.githubusercontent.com/u/37877945?v=4)](https://github.com/dvcom69 "dvcom69 (1 commits)")[![zolhorvath](https://avatars.githubusercontent.com/u/9197058?v=4)](https://github.com/zolhorvath "zolhorvath (1 commits)")[![pbarsallo](https://avatars.githubusercontent.com/u/29644270?v=4)](https://github.com/pbarsallo "pbarsallo (1 commits)")[![speakpavlov](https://avatars.githubusercontent.com/u/2760028?v=4)](https://github.com/speakpavlov "speakpavlov (1 commits)")

---

Tags

apiapi-clientbitbucketbitbucket-apihttplugphpbitbucketGraham CampbellGrahamCampbellbitbucket-apiBitbucketAPIBitbucket ClientBitbucket API Client

### Embed Badge

![Health badge](/badges/bitbucket-client/health.svg)

```
[![Health](https://phpackages.com/badges/bitbucket-client/health.svg)](https://phpackages.com/packages/bitbucket-client)
```

###  Alternatives

[telnyx/telnyx-php

Official Telnyx PHP SDK — APIs for Voice, SMS, MMS, WhatsApp, Fax, SIP Trunking, Wireless IoT, Call Control, and more. Build global communications on Telnyx's private carrier-grade network.

35729.6k2](/packages/telnyx-telnyx-php)[m4tthumphrey/php-gitlab-api

GitLab API v4 client for PHP

9515.7M72](/packages/m4tthumphrey-php-gitlab-api)[openai-php/client

OpenAI PHP is a supercharged PHP API client that allows you to interact with the Open AI API

5.8k26.1M293](/packages/openai-php-client)[phpro/http-tools

HTTP tools for developing more consistent HTTP implementations.

28146.3k](/packages/phpro-http-tools)[n1ebieski/ksef-php-client

PHP API client that allows you to interact with the API Krajowego Systemu e-Faktur

8554.6k](/packages/n1ebieski-ksef-php-client)[brd6/notion-sdk-php

Notion SDK for PHP

6121.6k](/packages/brd6-notion-sdk-php)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)