PHPackages                             calliostro/musicbrainz-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. [HTTP & Networking](/categories/http)
4. /
5. calliostro/musicbrainz-client

ActiveLibrary[HTTP & Networking](/categories/http)

calliostro/musicbrainz-client
=============================

Lightweight MusicBrainz API client for PHP 8.1+ with modern developer comfort — Clean parameter API and minimal dependencies

v1.0.0-beta.1(4mo ago)00MITPHPPHP ^8.1CI passing

Since Feb 14Pushed 4mo agoCompare

[ Source](https://github.com/calliostro/musicbrainz-client)[ Packagist](https://packagist.org/packages/calliostro/musicbrainz-client)[ Docs](https://github.com/calliostro/musicbrainz-client)[ RSS](/packages/calliostro-musicbrainz-client/feed)WikiDiscussions main Synced today

READMEChangelog (1)Dependencies (4)Versions (2)Used By (0)

⚡ MusicBrainz API Client for PHP 8.1+ – Lightweight with Maximum Developer Comfort
==================================================================================

[](#-musicbrainz-api-client-for-php-81--lightweight-with-maximum-developer-comfort)

[![Package Version](https://camo.githubusercontent.com/2d08a749e0e8ac63f50889c56ef6b28bc7321ddfea49e7500d62589362387c65/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f63616c6c696f7374726f2f6d75736963627261696e7a2d636c69656e742e737667)](https://packagist.org/packages/calliostro/musicbrainz-client)[![Total Downloads](https://camo.githubusercontent.com/7e3a36c3f063755c7da777af1b647b0a0da88cb7b73265f41d6159e0dc609b25/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f63616c6c696f7374726f2f6d75736963627261696e7a2d636c69656e742e737667)](https://packagist.org/packages/calliostro/musicbrainz-client)[![License](https://camo.githubusercontent.com/8009561bd2c5ad29ea8a3d7c36b9e2b7349d2d8b8fd2d58ef767052e0e1f167c/68747470733a2f2f706f7365722e707567782e6f72672f63616c6c696f7374726f2f6d75736963627261696e7a2d636c69656e742f6c6963656e7365)](https://packagist.org/packages/calliostro/musicbrainz-client)[![PHP Version](https://camo.githubusercontent.com/acffb6ae1962992d26e4466782832787e79504a6250f80d732c4283458b9f497/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253545382e312d626c75652e737667)](https://php.net)[![Guzzle](https://camo.githubusercontent.com/6a93cb104bf92d53d8f69d987b59934c07ed2b2dba8d5f6801e340ea930f1774/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f67757a7a6c652d253545362e35253743253545372e302d6f72616e67652e737667)](https://docs.guzzlephp.org/)[![CI](https://github.com/calliostro/musicbrainz-client/actions/workflows/ci.yml/badge.svg)](https://github.com/calliostro/musicbrainz-client/actions/workflows/ci.yml)[![Code Coverage](https://camo.githubusercontent.com/c6164ddd88cdc4ddaf71dab1829c787dd925726a98c8d6416878459d812ee829/68747470733a2f2f636f6465636f762e696f2f67682f63616c6c696f7374726f2f6d75736963627261696e7a2d636c69656e742f67726170682f62616467652e737667)](https://codecov.io/gh/calliostro/musicbrainz-client)[![PHPStan Level](https://camo.githubusercontent.com/d117944b58da8146f96b4ef7403807610a20eeb3fbcaaaf95157bbcdad1686eb/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d6c6576656c253230382d627269676874677265656e2e737667)](https://phpstan.org/)[![Code Style](https://camo.githubusercontent.com/5eddc7dd141d0fac72d1558d0950b5f45c014cbbc953b722a79cf21661f73ab6/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f636f64652532307374796c652d50535231322d627269676874677265656e2e737667)](https://github.com/FriendsOfPHP/PHP-CS-Fixer)

> **🚀 MINIMAL YET POWERFUL!** Focused, lightweight MusicBrainz API client — as compact as possible while maintaining modern PHP comfort and clean APIs.

📦 Installation
--------------

[](#-installation)

```
composer require calliostro/musicbrainz-client
```

✨ Features
----------

[](#-features)

- 🎯 **Complete API Coverage** — All MusicBrainz API v2 endpoints supported (50+ operations)
- 📖 **Read & Write Operations** — Both lookup/search and authenticated operations (ratings, tags, collections)
- 🚀 **Lightweight** — Minimal dependencies (only Guzzle)
- 🔒 **Type-safe** — Full PHP 8.1+ type hints and strict types
- 📚 **Well-documented** — PHPDoc with all methods and parameters
- ⚡ **Performance** — Optimized configuration caching
- 🧪 **100% Tested** — Comprehensive unit tests with full code coverage
- 🎨 **PSR-12** — Follows modern PHP coding standards

🚀 Quick Start
-------------

[](#-quick-start)

### Basic Usage (No Authentication Required)

[](#basic-usage-no-authentication-required)

```
use Calliostro\MusicBrainz\MusicBrainzClientFactory;

// Create client
$mb = MusicBrainzClientFactory::create();

// Lookup by MBID
$artist = $mb->lookupArtist('f4abc0b5-3f7a-4eff-8f78-ac078dbce533');

// Search for artists
$results = $mb->searchArtists('Dua Lipa');

// Browse releases by artist
$releases = $mb->browseReleases(artist: 'c8b03190-306c-4120-bb0b-6f2ebfc06ea9', limit: 10);

// Lookup release with includes
$release = $mb->lookupRelease('0c155a34-f9ed-4ade-a676-3ac0d48ead17', inc: 'artists+recordings');
```

### Search with Lucene Query Syntax

[](#search-with-lucene-query-syntax)

```
$mb = MusicBrainzClientFactory::create();

// Advanced search with Lucene syntax
$results = $mb->searchArtists('artist:"Billie Eilish" AND country:US');

// Search releases
$releases = $mb->searchReleases('release:"Happier Than Ever" AND artist:"Billie Eilish"');

// Search recordings
$recordings = $mb->searchRecordings('recording:"Levitating" AND artist:"Dua Lipa"');
```

### With Authentication (For Write Operations)

[](#with-authentication-for-write-operations)

```
use Calliostro\MusicBrainz\MusicBrainzClientFactory;

// Create authenticated client
$mb = MusicBrainzClientFactory::createWithAuth('username', 'password');

// Submit ratings (0-100, 0 = remove rating)
$mb->submitRating(
    client: 'MyApp/1.0',
    entityType: 'artist', // artist, release, recording, release-group, work, label, event, place, series, instrument
    entityId: 'f4abc0b5-3f7a-4eff-8f78-ac078dbce533',
    rating: 80
);

// Submit tags (comma-separated)
$mb->submitTags(
    client: 'MyApp/1.0',
    entityType: 'release',
    entityId: '0c155a34-f9ed-4ade-a676-3ac0d48ead17',
    tags: 'indie,alternative,2020s'
);

// Get user collections
$collections = $mb->getUserCollections();

// Get releases in a collection
$releases = $mb->getCollectionReleases('collection-mbid-123', limit: 50);

// Add releases to collection (semicolon-separated MBIDs)
$mb->addReleasesToCollection(
    mbid: 'collection-mbid-123',
    releaseList: 'release-1;release-2;release-3',
    client: 'MyApp/1.0'
);

// Remove releases from collection
$mb->removeReleasesFromCollection(
    mbid: 'collection-mbid-123',
    releaseList: 'release-1;release-2',
    client: 'MyApp/1.0'
);
```

### Custom User-Agent

[](#custom-user-agent)

MusicBrainz requires proper User-Agent identification. By default, the client includes a User-Agent, but you can customize it:

```
$mb = MusicBrainzClientFactory::createWithUserAgent(
    'MyApp/1.0.0 (https://myapp.com)'
);
```

📖 API Methods
-------------

[](#-api-methods)

### Artist Methods

[](#artist-methods)

```
// Lookup artist by MBID
$artist = $mb->lookupArtist($mbid, inc: 'recordings+releases');

// Browse artists
$artists = $mb->browseArtists(area: $areaMbid, limit: 25);

// Search artists
$results = $mb->searchArtists('Taylor Swift', limit: 10);
```

### Release Methods

[](#release-methods)

```
// Lookup release by MBID
$release = $mb->lookupRelease($mbid, inc: 'artists+labels+recordings');

// Browse releases
$releases = $mb->browseReleases(artist: $artistMbid, type: 'album', status: 'official');

// Search releases
$results = $mb->searchReleases('release:"Future Nostalgia" AND artist:"Dua Lipa"');
```

### Release Group Methods

[](#release-group-methods)

```
// Lookup release group
$releaseGroup = $mb->lookupReleaseGroup($mbid, inc: 'artists+releases');

// Browse release groups
$groups = $mb->browseReleaseGroups(artist: $artistMbid, type: 'album');

// Search release groups
$results = $mb->searchReleaseGroups('releasegroup:"Happier Than Ever"');
```

### Recording Methods

[](#recording-methods)

```
// Lookup recording by MBID
$recording = $mb->lookupRecording($mbid, inc: 'artists+releases');

// Browse recordings
$recordings = $mb->browseRecordings(artist: $artistMbid, limit: 50);

// Search recordings
$results = $mb->searchRecordings('recording:"Blinding Lights" AND artist:"The Weeknd"');
```

### Label Methods

[](#label-methods)

```
// Lookup label
$label = $mb->lookupLabel($mbid, inc: 'releases');

// Browse labels
$labels = $mb->browseLabels(area: $areaMbid);

// Search labels
$results = $mb->searchLabels('label:"Columbia Records"');
```

### Work Methods

[](#work-methods)

```
// Lookup work by MBID
$work = $mb->lookupWork($mbid, inc: 'artist-rels');

// Browse works
$works = $mb->browseWorks(artist: $artistMbid);

// Search works
$results = $mb->searchWorks('work:"Symphony No. 9"');
```

### Other Methods

[](#other-methods)

```
// Lookup area (country, city, etc.)
$area = $mb->lookupArea($mbid);

// Search areas
$areas = $mb->searchAreas('area:"London"');

// Lookup by ISRC
$isrc = $mb->lookupIsrc('USRC17607839');

// Lookup URL
$url = $mb->lookupUrl($mbid);

// Search URLs
$urls = $mb->searchUrls('url:"https://www.example.com"');
```

### Genre Methods

[](#genre-methods)

```
// Lookup genre by MBID
$genre = $mb->lookupGenre($mbid);

// Search genres
$genres = $mb->searchGenres('electronic', limit: 10);
```

### Instrument Methods

[](#instrument-methods)

```
// Lookup instrument by MBID
$instrument = $mb->lookupInstrument($mbid, inc: 'aliases+tags');

// Search instruments
$instruments = $mb->searchInstruments('guitar');
```

### Series Methods

[](#series-methods)

```
// Lookup series by MBID
$series = $mb->lookupSeries($mbid, inc: 'aliases');

// Search series
$seriesList = $mb->searchSeries('Best of', limit: 20);
```

### Event Methods

[](#event-methods)

```
// Lookup event by MBID
$event = $mb->lookupEvent($mbid, inc: 'artist-rels');

// Browse events by artist
$events = $mb->browseEvents(artist: $artistMbid, limit: 50);

// Browse events by area or place
$events = $mb->browseEvents(area: $areaMbid);
$events = $mb->browseEvents(place: $placeMbid);

// Search events
$events = $mb->searchEvents('festival 2024');
```

### Place Methods

[](#place-methods)

```
// Lookup place by MBID
$place = $mb->lookupPlace($mbid, inc: 'aliases+annotation');

// Browse places by area
$places = $mb->browsePlaces(area: $areaMbid, limit: 25);

// Search places
$places = $mb->searchPlaces('Madison Square Garden');
```

📚 Complete API Reference
------------------------

[](#-complete-api-reference)

### Read Operations (No Authentication Required)

[](#read-operations-no-authentication-required)

**Artist**: `lookupArtist`, `browseArtists`, `searchArtists`
**Release**: `lookupRelease`, `browseReleases`, `searchReleases`
**Release Group**: `lookupReleaseGroup`, `browseReleaseGroups`, `searchReleaseGroups`
**Recording**: `lookupRecording`, `browseRecordings`, `searchRecordings`
**Label**: `lookupLabel`, `browseLabels`, `searchLabels`
**Work**: `lookupWork`, `browseWorks`, `searchWorks`
**Area**: `lookupArea`, `searchAreas`
**Genre**: `lookupGenre`, `searchGenres`
**Instrument**: `lookupInstrument`, `searchInstruments`
**Series**: `lookupSeries`, `searchSeries`
**Event**: `lookupEvent`, `browseEvents`, `searchEvents`
**Place**: `lookupPlace`, `browsePlaces`, `searchPlaces`
**ISRC**: `lookupIsrc`
**URL**: `lookupUrl`, `searchUrls`

### Write Operations (Authentication Required)

[](#write-operations-authentication-required)

**Ratings**: `submitRating` - Rate artists, releases, recordings, release-groups, works, labels, events, places, series, or instruments (0-100, 0 removes rating)
**Tags**: `submitTags` - Add tags to artists, releases, recordings, release-groups, works, labels, areas, events, places, series, or instruments
**Collections**: `getUserCollections`, `getCollectionReleases`, `addReleasesToCollection`, `removeReleasesFromCollection`

🎯 Parameter Styles
------------------

[](#-parameter-styles)

The client supports multiple parameter styles for maximum flexibility:

```
// Positional parameters
$artist = $mb->lookupArtist('5b11f4ce-a62d-471e-81fc-a69a8278c7da');

// Named parameters (recommended)
$releases = $mb->browseReleases(
    artist: '5b11f4ce-a62d-471e-81fc-a69a8278c7da',
    type: 'album',
    limit: 10
);

// Mixed positional and named
$results = $mb->searchArtists('Billie Eilish', limit: 25);

// Associative array (for dynamic parameters)
$params = [
    'artist' => '5b11f4ce-a62d-471e-81fc-a69a8278c7da',
    'limit' => 10,
    'inc' => 'recordings'
];
$releases = $mb->browseReleases($params);
```

🔧 Advanced Configuration
------------------------

[](#-advanced-configuration)

### Rate Limiting

[](#rate-limiting)

MusicBrainz has rate limiting (one request per second). Consider implementing rate limiting in your application:

```
use GuzzleHttp\HandlerStack;
use GuzzleHttp\Middleware;

$stack = HandlerStack::create();
$stack->push(Middleware::retry(function ($retries, $request, $response, $exception) {
    if ($response && $response->getStatusCode() === 503) {
        return $retries < 3; // Retry up to 3 times on 503 errors
    }
    return false;
}));

$mb = MusicBrainzClientFactory::create([
    'handler' => $stack,
    'timeout' => 10,
]);
```

### Custom Guzzle Options

[](#custom-guzzle-options)

```
$mb = MusicBrainzClientFactory::create([
    'timeout' => 30,
    'proxy' => 'http://proxy.example.com:8080',
    'verify' => true,
]);
```

📝 Response Format
-----------------

[](#-response-format)

All methods return arrays with the JSON-decoded response from MusicBrainz:

```
$artist = $mb->lookupArtist('f4abc0b5-3f7a-4eff-8f78-ac078dbce533');

// Access response data
echo $artist['name']; // "Billie Eilish"
echo $artist['country']; // "US"
echo $artist['type']; // "Person"

foreach ($artist['life-span'] as $key => $value) {
    echo "$key: $value\n";
}
```

🧪 Testing
---------

[](#-testing)

```
# Run unit tests
composer test

# Run integration tests (requires internet connection)
composer test-integration

# Run all tests
composer test-all

# Generate coverage report
composer test-coverage
```

🔍 Code Quality
--------------

[](#-code-quality)

```
# Check code style
composer cs

# Fix code style
composer cs-fix

# Run static analysis
composer analyse
```

📚 Resources
-----------

[](#-resources)

- [MusicBrainz API Documentation](https://musicbrainz.org/doc/MusicBrainz_API)
- [MusicBrainz Search Syntax](https://musicbrainz.org/doc/Indexed_Search_Syntax)
- [MusicBrainz Rate Limiting](https://musicbrainz.org/doc/MusicBrainz_API/Rate_Limiting)
- [MusicBrainz Database](https://musicbrainz.org/)

📄 License
---------

[](#-license)

MIT License – see the [LICENSE](LICENSE) file for details.

🤝 Contributing
--------------

[](#-contributing)

Contributions are welcome! Please feel free to submit a Pull Request.

🙏 Acknowledgments
-----------------

[](#-acknowledgments)

- [MusicBrainz](https://musicbrainz.org/) for providing the excellent open music encyclopedia and metadata API
- [Guzzle](https://docs.guzzlephp.org/) for the robust HTTP client
- The PHP community for continuous inspiration

---

> ⭐ **Star this repo if you find it useful!**

###  Health Score

28

—

LowBetter than 52% of packages

Maintenance74

Regular maintenance activity

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity29

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% 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

Unknown

Total

1

Last Release

140d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/793482279bf515fd4d7758e76f3b569bc3e2b41787b9d15901d2ed58d03c6b1b?d=identicon)[calliostro](/maintainers/calliostro)

---

Top Contributors

[![calliostro](https://avatars.githubusercontent.com/u/24731284?v=4)](https://github.com/calliostro "calliostro (2 commits)")

---

Tags

api-clientclean-apiguzzlelibrarylightweightmetadataminimal-dependenciesmodern-phpmusicmusic-brainzmusicbrainzmusicbrainz-apiphpphp8web-apiphpGuzzlelibrarymetadatalightweightapi clientphp8musicmusicbrainzweb-apimodern-phpclean-apiminimal-dependenciesmusic-brainzmusicbrainz-api

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

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

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

###  Alternatives

[xeroapi/xero-php-oauth2

Xero official PHP SDK for oAuth2 generated with OpenAPI spec 3

1054.7M18](/packages/xeroapi-xero-php-oauth2)[eslazarev/wildberries-sdk

Wildberries OpenAPI clients (generated).

273.0k](/packages/eslazarev-wildberries-sdk)

PHPackages © 2026

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