Packagist · #593 most downloaded on Packagist

meilisearch/meilisearch-php

v1.17.021M downloads/momeilisearch/meilisearch-php ↗New releases in your daily digest, changelog included.

PHP wrapper for the Meilisearch API

Last release today
07 Oct 2026
Release timing varies
gaps range from 8 days to 3 months
Rarely documented
notes for 4 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
7 years old
80 releases · first in 2020

Release timeline

80 releases since 2020

2020202120222023202420252026

20202026

One column per quarter.

Releases

v2.0.0-beta.87 Oct 2026pre-release

If you're migrating from v1.x , read the complete migration guide .

Migration guide

If you're migrating from v1.x, read the complete migration guide.

Per-index APIs now use `Index` instead of `Indexes`

The per-index object from $client->index() / $client->getIndex() is now Meilisearch\Endpoints\Index. Metadata is lazy-loaded; fetchInfo() and fetchPrimaryKey() were removed.

Update type hints, imports, and code that fetched index metadata or assumed getIndex() made an HTTP call.

Rename Indexes to Index

// Before (v1.x)
use Meilisearch\Endpoints\Indexes;

function handle(Indexes $index): void { /* ... */ }

// After (v2.x)
use Meilisearch\Endpoints\Index;

function handle(Index $index): void { /* ... */ }

getIndex() is now lazy

// Before (v1.x) - threw ApiException immediately if the index didn't exist
$index = $client->getIndex('missing');

// After (v2.x) - the call to a getter triggers the fetch (and any exception)
$index = $client->getIndex('missing');
$index->getPrimaryKey(); // ApiException thrown here

Call getters instead of fetchInfo() / fetchPrimaryKey()

// Before (v1.x)
$index = $client->index('books');
$index->fetchInfo();
$primaryKey = $index->fetchPrimaryKey();

// After (v2.x)
$index = $client->index('books');
$primaryKey = $index->getPrimaryKey(); // loads on demand

getUid(), getCreatedAt(), getUpdatedAt() are no longer nullable

// Before (v1.x)
$date = $index->getCreatedAt();
if ($date !== null) {
    echo $date->format(DATE_ATOM);
}

// After (v2.x)
echo $index->getCreatedAt()->format(DATE_ATOM);

`multiSearch()` now takes `MultiSearchQuery`

setIndexUid() and setFederationOptions() were moved off SearchQuery and onto the new MultiSearchQuery class. SearchQuery is now only for single-index search.

Update multi-search and federation query construction.

Use MultiSearchQuery for multiSearch()

// Before (v1.x)
use Meilisearch\Contracts\SearchQuery;

$client->multiSearch([
    (new SearchQuery())->setIndexUid('books')->setQuery('prince'),
    (new SearchQuery())->setIndexUid('songs')->setQuery('be'),
]);

// After (v2.x)
use Meilisearch\Contracts\MultiSearchQuery;

$client->multiSearch([
    (new MultiSearchQuery())->setIndexUid('books')->setQuery('prince'),
    (new MultiSearchQuery())->setIndexUid('songs')->setQuery('be'),
]);

Use MultiSearchQuery for federation options

// Before (v1.x)
$query = (new SearchQuery())
    ->setIndexUid('books')
    ->setFederationOptions((new FederationOptions())->setWeight(0.5));

// After (v2.x)
$query = (new MultiSearchQuery())
    ->setIndexUid('books')
    ->setFederationOptions((new FederationOptions())->setWeight(0.5));

Index stats now return a typed `IndexStats` object

Index stats APIs no longer return array-based responses. They now return a typed IndexStats object.

Update code that reads index stats fields to use getter methods.

$stats = $index->stats();

// Before (v1.x)
$count = $stats['numberOfDocuments'];
$indexing = $stats['isIndexing'];
$fields = $stats['fieldDistribution'];

// After (v2.x)
$count = $stats->getNumberOfDocuments();
$indexing = $stats->isIndexing();
$fields = $stats->getFieldDistribution();

`getSettings()` returns plain arrays for nested settings

synonyms, typoTolerance, faceting, and embedders are now plain arrays instead of iterable setting objects, so iterator_to_array() is no longer needed.

Update code that converts nested settings to arrays.

$settings = $index->getSettings();

// Before (v1.x)
$typoTolerance = iterator_to_array($settings['typoTolerance']);
$synonyms = iterator_to_array($settings['synonyms']);

// After (v2.x)
$typoTolerance = $settings['typoTolerance'];
$synonyms = $settings['synonyms'];

Batch APIs now return typed `Batch` objects

Batch APIs no longer return array-based responses. They now return typed Batch objects.

Update code that reads batch fields or lists batches.

// Before (v1.x)
$batch = $client->getBatch($uid);
$uid = $batch['uid'];
$startedAt = $batch['startedAt']; // string
$total = $batch['stats']['totalNbTasks'];

// After (v2.x)
$batch = $client->getBatch($uid);
$uid = $batch->getUid();
$startedAt = $batch->getStartedAt(); // \DateTimeImmutable
$total = $batch->getStats()->getTotalNbTasks();

This also applies to $client->getBatches(). getResults() now returns an array of Batch objects.

// Before (v1.x)
$batches = $client->getBatches();
$uid = $batches->getResults()[0]['uid'];

// After (v2.x)
$batches = $client->getBatches();
$uid = $batches->getResults()[0]->getUid();

progress is a BatchProgress object while the batch is running, and null when it has finished.

// Before (v1.x)
$percent = $batch['progress']['percentage'] ?? null;

// After (v2.x)
$percent = $batch->getProgress()?->getPercentage();

🧪 Experimental

Breaking: Update dynamic search rules for Meilisearch v1.54 (#952) @Strift

⚠️ Breaking changes

Separate Index endpoint and add type-safe search query DTOs (#914) @norkunas
Add types to Indexes stats, settings, and search (#931) @Strift
Typehint Batch results (#928) @Strift

🚀 Enhancements

Separate Index endpoint and add type-safe search query DTOs (#914) @norkunas
Add types to Indexes stats, settings, and search (#931) @Strift
Add indexSize and usedIndexSize to IndexStats (#946) @murilolivorato

⚙️ Maintenance/misc

Replace timing-bound wait() tests with HTTP-stubbed polling (#947) @Strift
Add a scheduled workflow to bump pinned Meilisearch versions (#951) @Strift

Thanks to @Strift, @murilolivorato and @norkunas! 🎉

See full changelog: v2.0.0-beta.7...v2.0.0-beta.8

v2.0.0-beta.722 Jul 2026pre-release

Typehint HandlesSystem::health return type ( #927 ) @Strift

⚠️ Breaking changes

Typehint HandlesSystem::health return type (#927) @Strift

🧪 Experimental

Breaking: Make Dynamic Search Rules API compatible with Meilisearch v1.50 (#933) @Strift

🚀 Enhancements

Add method to get task documents (#895) @mvanhorn
Add PHPDoc return type for HandlesDocuments::getDocument. (#926) @Strift
Improve HTTP client types (#930) @Strift
Make Dynamic Search Rules API compatible with Meilisearch v1.50 (#933) @Strift

⚙️ Maintenance/misc

Fix PHPStan issues (#925) @Strift
Bump actions/configure-pages from 5 to 6 (#901) @dependabot[bot]
Bump actions/deploy-pages from 4 to 5 (#902) @dependabot[bot]
Bump release-drafter/release-drafter from 6 to 7 (#900) @dependabot[bot]
Bump actions/download-artifact from 7 to 8 (#882) @dependabot[bot]
Bump actions/upload-artifact from 6 to 7 (#884) @dependabot[bot]

Thanks to @Strift, @dependabot[bot], @mvanhorn, Matt Van Horn and dependabot[bot]! 🎉

See full changelog: v2.0.0-beta.6...v2.0.0-beta.7

Open source →

v2.0.0-beta.628 Apr 2026pre-release

If you're migrating from v1.x , read the complete migration guide .

Migration guide

If you're migrating from v1.x, read the complete migration guide.

API keys API now uses typed query and result objects

API key methods no longer accept array-based write payloads or return plain list shapes. They now use CreateKeyQuery and UpdateKeyQuery for requests, KeysResults for lists, and KeyAction for actions.

// Before (v1.x)
$key = $client->createKey([
    'description' => 'tenant token key',
    'actions'     => ['*'],
    'indexes'     => ['tenant*'],
    'expiresAt'   => '2055-10-02T00:00:00Z',
]);

// After (v2.x)
$key = $client->createKey(new CreateKeyQuery(
    actions:    [KeyAction::Any],
    indexes:    ['tenant*'],
    description: 'tenant token key',
    expiresAt:   new DateTimeImmutable('2055-10-02T00:00:00Z'),
));

The client updateKey method accepts an UpdateKeyQuery, which works similarly. It allows clearing the key name or description by passing null.

Additionally, KeysResults::count() was removed; use count($keysResults) instead.

Type improvements

SimilarDocumentsQuery, FacetSearchResult, and SearchResult are now final

🧪 Experimental features

Update network API compatibility to Meilisearch v1.37 (#888) @Strift
Add dynamic search rules API API (#910) @Strift

⚠️ Breaking changes

Refactor Keys API to use typed query and result objects (#903) @norkunas

These other changes only pertain to PHPStan type hints improvements:

Add type hints to DocumentsResults (#908) @norkunas
Add type hints to, and make query and results classes final (#909) @norkunas
Add types to Data's ArrayAccess methods (#912) @norkunas

🚀 Enhancements

Add support for showPerformanceDetails option (#871) @QDenka
Add index compaction API (#874) @norkunas
Add support for distinct in federated search requests (#892) @mvanhorn
Add dynamic search rules (#910) @Strift

🐛 Bug Fixes

Use array_key_exists instead of isset in Task::offsetExists (#870) @norkunas
Fix uninitialized properties in TasksQueryTrait (#875) @norkunas

⚙️ Maintenance/misc

Fix non-working link (#876) @norkunas
chore: update tests for v1.36.0 (#879) @Strift
Replace localhost:7700 with MEILISEARCH_URL (#880) @Strift
Remove unused code samples (#885) @curquiza
Update release drafter workflow to handle beta releases (#907) @Strift

Thanks to @QDenka, @Strift, @curquiza, @mvanhorn and @norkunas! 🎉

See full changelog: v2.0.0-beta.5...v2.0.0-beta.6

Open source →

v2.0.0-beta.54 Feb 2026pre-release

Note This replaces the incorrect v2.0.0-beta.4 release tagged from the wrong branch.

Note

This replaces the incorrect v2.0.0-beta.4 release tagged from the wrong branch.

Migration guide

If you're migrating from v1.x, read the full migration guide instead.

🟠 Task methods now return types (Impact: moderate)

$client->getTasks() and $index->getTasks() now return a TaskResults object.

// Before (v1.x)
$tasks = $client->getTasks();
$results = $tasks['results']; // Accessing as array

// After (v2.x)
$tasks = $client->getTasks(); // Returns TaskResults
$results = $tasks->getResults(); // Returns an array of Task objects

Additionally

The internal task manager all() method now returns an array of Task objects.
The TaskResults class is now final

⚠️ Breaking changes

Wrap data with Task before passing to TasksResults (#864) @norkunas

🚀 Enhancements

Add raw data to Task and implement ArrayAccess (backward compatibility) (#863) @norkunas
Use environment flag to allow all network IPs in tests (#867) @Strift

⚙️ Maintenance/misc

Bump actions/cache from 4 to 5 (#856) @dependabot[bot]
Bump actions/download-artifact from 6 to 7 (#858) @dependabot[bot]
Bump actions/upload-artifact from 5 to 6 (#860) @dependabot[bot]
Add AI usage disclosure guidelines to CONTRIBUTING.md (#862) @curquiza

Thanks to @Strift, @norkunas and dependabot[bot]! 🎉

See full changelog: v2.0.0-beta.3...v2.0.0-beta.5

Open source →

v2.0.0-beta.46 Jan 2026pre-release

Warning This release was incorrectly tagged from the wrong branch . Please use v2.0.0-beta.5 instead.

Deprecated

Warning

This release was incorrectly tagged from the wrong branch.
Please use v2.0.0-beta.5 instead.

Open source →

v2.0.0-beta.323 Dec 2025pre-releaseDeprecated

Fix PHP-CS-Fixer deprecation ( #830 ) @norkunas

Migration guide

🟢 Improved exception types DX (Impact: minor)

The custom $message property has been removed from custom exceptions. Use the getMessage() method instead:

try {
    // ...
} catch (\Meilisearch\Exceptions\ApiException $e) {
   // Before (v1.x)
    echo $e->message;
    // After (v2.x)
    echo $e->getMessage();
}

Also:

Exception classes are now final
Exception public properties are now read-only and strictly typed.
The rethrowWithHint static method now returns a \RuntimeException instead of a generic \Exception.

⚠️ Breaking changes

Add types to exceptions (#850) @norkunas

🚀 Enhancements

Update experimental Network API for Meilisearch v1.30 compatibility (#853) @Strift

⚙️ Maintenance/misc

Fix PHP-CS-Fixer deprecation (#830) @norkunas

Thanks to @Strift and @norkunas! 🎉

See full changelog: v2.0.0-beta.2...v2.0.0-beta.3

Open source →

v2.0.0-beta.211 Dec 2025pre-release

Database stats now return a typed Stats object

Migration guide

Database stats now return a typed `Stats` object

$stats = $client->stats();

// Before (v1.x) - accessing stats as array
$databaseSize = $response['databaseSize'];
$usedDatabaseSize = $response['usedDatabaseSize'];
// etc...

// After (v2.x) - use getter methods
$databaseSize = $stats->getDatabaseSize();
$usedDatabaseSize = $stats->getUsedDatabaseSize();

Version is now a typed `Version` object

$version = $client->version();

// Before (v1.x) - access as array
$commitSha = $version['commitSha'];
$commitDate = $version['commitDate']; // String
$pkgVersion = $version['pkgVersion'];

// After (v2.x) - use getter methods
$commitSha = $version->getCommitSha();
$commitDate = $version->getCommitDate(); // \DateTimeImmutable
$pkgVersion = $version->getPkgVersion();

Removed legacy `MeiliSearch` namespace

We removed MeiliSearch (capital S) namespace.

// Before (v1.x) - MeiliSearch with capital S
use MeiliSearch\Client;

// After (v2.x) - Meilisearch without capital S
use Meilisearch\Client;

Removed `Indexes::parseDate()` public method

This only affects you if you were using this utility method directly.

// Before (v1.x) - If you used this method in your code
$dateTime = \Meilisearch\Endpoints\Indexes::parseDate('2021-01-01T01:23:45.123456Z');

// After (v2.x) - Use native PHP instead
$dateTime = new \DateTimeImmutable('2021-01-01T01:23:45.123456Z');

⚠️ Breaking changes

Remove custom date parsing (#826) @norkunas
Add typed Stats object (#823) @norkunas
Remove remaining custom datetime parsing (#827) @norkunas
Add typed Version object (#821) @norkunas
Remove legacy namespace (#822) @norkunas

🐛 Bug Fixes

Fix: expose facetStats in SearchResult::toArray (#828) @walkwizus

⚙️ Maintenance/misc

Add PHP 8.5 to CI (#829) @norkunas
allow symfony/http-client 8.0 (#820) @tacman
Fix test namespaces (#824) @norkunas
Add PHP 8.5 to CI (#829) @norkunas
chore: handle unknown commit date in version (#836) @Strift
Use Meilisearch Enterprise Edition (#835) @Strift

Thanks to @Strift, @bpolaszek, @dependabot[bot], @norkunas, @tacman, and @walkwizus! 🎉

See full changelog: v2.0.0-beta.1...v2.0.0-beta.2

Open source →

v2.0.0-beta.118 Nov 2025pre-releaseBreaking

While we recommend against production usage due to breaking changes, the code is stable. Please consider whether you can afford the potential upcoming…

While we recommend against production usage due to breaking changes, the code is stable. Please consider whether you can afford the potential upcoming breaking changes before upgrading.

Migration guide

Refactor tasks as objects, and task status and type as enums

This introduces two changes:

Asynchronous operations now return Tasks as an object instead of an array
Tasks can be awaited with the new wait(int $timeoutInMs = 5000, int $intervalInMs = 50): Task method

Awaiting tasks:

// Before
$promise = $this->client->createIndex('new-index', ['primaryKey' => 'objectID']);
$this->index->waitForTask($promise['taskUid']);

// After
$this->client->createIndex('new-index', ['primaryKey' => 'objectID'])->wait();

Asserting task status:

// Before
$task = $this->client->getTask($taskUid);
if ($task['status'] === 'succeeded') {
    // do something
}

// After
if ($task->getStatus() === TaskStatus::Succeeded) {
    // do something
}

Asserting task types:

// Before
$task = $this->client->getTask($taskUid);
if ($task['type'] === 'indexCreation') {
    // do something
}

// After
$task = $this->client->getTask($taskUid);
if ($task->getType() === TaskType::IndexCreation) {
    // do something
}

Remove custom exception for JSON parsing

Before: catching SDK-specific JSON exceptions

<?php

try {
    $client->index('books')->addDocuments([["title" => "\xB1\x31"]]);
} catch (JsonEncodingException | JsonDecodingException $e) {
    // handle JSON errors
}

After: catching native PHP JsonException

<?php

try {
    $client->index('books')->addDocuments([["title" => "\xB1\x31"]]);
} catch (\JsonException $e) {
    // handle JSON errors
}

⚠️ Breaking changes

feat: remove custom json exceptions (#791) @Strift
Bump to PHP 8.1, improve type safety for Tasks (#735) @norkunas

🚀 Enhancements

Support sort for documents endpoint (#779) @bpolaszek

🐛 Bug Fixes

Cast federation payload explicitly to an object (#757) @norkunas

⚙️ Maintenance/misc

Update repository config for v2 (#787) @Strift
fix: reference the correct php-version in matrix (#792) @Strift
chore: update ci for v2 (#793) @Strift
chore: update release drafter (#804) @Strift
Update dependabot and release template configuration (#806)
Migrate CI from bors to merge queue (#801) @Strift
Bump actions/upload-artifact from 4 to 5 (#813) @dependabot[bot]
Bump actions/download-artifact from 4 to 6 (#812) @dependabot[bot]

Thanks to @Strift, @bpolaszek, and @norkunas! 🎉

See full changelog: v1.16.0...v2.0.0-beta.1

Open source →

v1.17.04 Aug 2026

Add Dynamic Search Rules ( #942 ) @Junaid-PK

🚀 Enhancements

Add Dynamic Search Rules (#942) @Junaid-PK

⚙️ Maintenance/misc

Add merge_group trigger to workflows for merge queue (#814) @Strift
Bump actions/download-artifact from 4 to 6 (#811) @dependabot[bot]
Bump actions/upload-artifact from 4 to 5 (#810) @dependabot[bot]
Bump actions/download-artifact from 6 to 7 (#861) @dependabot[bot]
Bump actions/upload-artifact from 5 to 6 (#859) @dependabot[bot]

Thanks to @Junaid-PK, @Strift, @dependabot[bot] and dependabot[bot]! 🎉

See full changelog: v1.16.1...v1.17.0

Open source →

v1.16.118 Sept 2025

This PR adds support for sorting to the documents endpoint .

What's Changed

This PR adds support for sorting to the documents endpoint.

🚀 Enhancements

chore: backport document sorting to v1.x (#802) @Strift

🐛 Bug Fixes

chore: backport federated search fix (#789) @Strift

Thanks to @Strift, and dependabot[bot]! 🎉

See full changelog: v1.16.0...v1.16.1

Open source →

v1.16.010 Sept 2025

This release makes the SDK compatible with features release in Meilisearch 1.16 .

This release makes the SDK compatible with features release in Meilisearch 1.16.

🚀 Enhancements

Run tests only with a single http client (#758) @norkunas
Add conversational search (#774) @Strift
Add multi-modal search (#783) @Strift

🐛 Bug Fixes

fix: wrong type for retrieveVectors (#777) @bpolaszek

⚙️ Maintenance/misc

Run tests only with a single http client (#758) @norkunas
Fix index swaps tests after v1.18 (#780) @Strift
Make network tests compatible with v1.19 (#781) @Strift
tests: increase PHP memory limit to 512M in Dockerfile (#778) @bpolaszek
Make network tests compatible with v1.19 (#781) @Strift

Thanks again to @Strift, @bpolaszek, @brunoocasali, and @norkunas! 🎉

Open source →

v1.15.010 Jun 2025