meilisearch/meilisearch-php

⚠️ 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

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

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

Deprecated

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

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

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

🚀 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

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

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! 🎉