PHPackages                             helgesverre/milvus - 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. [Database & ORM](/categories/database)
4. /
5. helgesverre/milvus

ActiveLibrary[Database & ORM](/categories/database)

helgesverre/milvus
==================

PHP Client for the Milvus Rest API

v0.3.1(2w ago)337.3k↑11.4%9[4 issues](https://github.com/HelgeSverre/milvus/issues)[1 PRs](https://github.com/HelgeSverre/milvus/pulls)MITPHPPHP ^8.3

Since Dec 27Pushed 1y ago1 watchersCompare

[ Source](https://github.com/HelgeSverre/milvus)[ Packagist](https://packagist.org/packages/helgesverre/milvus)[ Docs](https://github.com/helgesverre/milvus)[ RSS](/packages/helgesverre-milvus/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (7)Dependencies (23)Versions (8)Used By (0)

[![](./art/header.png)](./art/header.png)

Milvus.io PHP API Client
========================

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

[![Latest Version on Packagist](https://camo.githubusercontent.com/ba1938203b89958ee4b8d7242bd7a650ef896c6505b901ab296840c00a06cf6b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f68656c67657376657272652f6d696c7675732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/helgesverre/milvus)[![Total Downloads](https://camo.githubusercontent.com/26597e01166b3957d6d2df455eaacccf4b65e43e1840296adbd2a6faece51ca5/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f68656c67657376657272652f6d696c7675732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/helgesverre/milvus)[![CI](https://github.com/HelgeSverre/milvus/actions/workflows/main.yml/badge.svg)](https://github.com/HelgeSverre/milvus/actions/workflows/main.yml)[![Code Coverage](https://camo.githubusercontent.com/370030cb2357530e464308a78be05912333b1eecf09ec24ed228e3bb7f7d43de/68747470733a2f2f636f6465636f762e696f2f67682f48656c67655376657272652f6d696c7675732f6272616e63682f6d61696e2f67726170682f62616467652e737667)](https://codecov.io/gh/HelgeSverre/milvus)

[Milvus](https://github.com/milvus-io/milvus) is an open-source vector database that is highly flexible, reliable, and blazing fast. It supports adding, deleting, updating, and near real-time search of vectors on a trillion-byte scale.

This package is a PHP client for the stable Milvus REST v2 endpoints shared by Milvus 2.5 through 3.0. It is tested against Milvus 2.5.21, 2.6.21, and 3.0.0, and built on [Saloon](https://docs.saloon.dev/).

See the [Milvus REST API documentation](https://milvus.io/api-reference/restful/v3.0.x/About.md) and the official [database](https://github.com/milvus-io/web-content/blob/master/scripts/apifox-docs/meta/openapi/06-database-operations-v2.json), [collection](https://github.com/milvus-io/web-content/blob/master/scripts/apifox-docs/meta/openapi/05-collection-operations-v2.json), and [vector](https://github.com/milvus-io/web-content/blob/master/scripts/apifox-docs/meta/openapi/04-vector-operations-v2.json)OpenAPI definitions.

See the [changelog](CHANGELOG.md) for the complete release history and upgrade notes.

Compatibility
-------------

[](#compatibility)

The supported runtime matrix is PHP 8.3–8.5 and Laravel 12–13. Laravel 10 and 11 remain covered by compatibility tests for existing applications, but both framework versions are end-of-life and should not be used for new installations. Their CI jobs use Composer's command-scoped `--no-blocking` option because current Composer versions block their affected upstream framework releases.

Laravel VersionTested PHPStatus13.x8.5Supported12.x8.4Supported11.x8.3Legacy compatibility10.x8.3Legacy compatibilityVersions
--------

[](#versions)

Milvus VersionPHP Client Versionv3.0.xv0.2.0+v2.6.xv0.2.0+v2.5.xv0.2.0+v2.3.xv0.0.x-v0.1.xPHP 8.3–8.5 is supported. Laravel is optional; the client can also be used as a standalone Saloon connector.

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

[](#installation)

You can install the package via composer:

```
composer require helgesverre/milvus
```

You can publish the config file with:

```
php artisan vendor:publish --tag="milvus-config"
```

This is the contents of the published `config/milvus.php` file:

```
return [
    'token' => env('MILVUS_TOKEN'),
    'username' => env('MILVUS_USERNAME'),
    'password' => env('MILVUS_PASSWORD'),
    'host' => env('MILVUS_HOST', 'localhost'),
    'port' => env('MILVUS_PORT', '19530'),
];
```

`MILVUS_TOKEN` takes precedence. When it is absent, the Laravel service provider builds the token from a complete `MILVUS_USERNAME` and `MILVUS_PASSWORD` pair. Milvus expects that credential token in raw `username:password` format.

Usage
-----

[](#usage)

### With Laravel

[](#with-laravel)

For Laravel users, you can use the `Milvus` facade to interact with the Milvus API:

```
use HelgeSverre\Milvus\Facades\Milvus;

// NOTE: dbName is optional and defaults to 'default', this is only relevant if you have multiple databases.
// List all collections in the 'default' database
Milvus::collections()->list(
    dbName: 'default'
);

// Create a new collection named 'documents' in the 'default' database with a specified dimension
Milvus::collections()->create(
    collectionName: 'documents',
    dimension: 128,
    dbName: 'default',
    autoID: false,
);

// Describe the structure and properties of the 'documents' collection in the 'default' database
Milvus::collections()->describe(
    collectionName: 'documents',
    dbName: 'default',
);

// Drop or delete the 'documents' collection from the 'default' database
Milvus::collections()->drop(
    collectionName: 'documents',
    dbName: 'default',
);

// Insert a new vector into the 'documents' collection with additional fields like title and link
// Note "vector" is a reserved field name and must be used for the vector data
Milvus::vector()->insert(
    collectionName: 'documents',
    data: [
        [
            'id' => 123129471497,
            'vector' => [0.1, 0.2, 0.3 /* etc... */],
            'title' => 'Document name here',
            'link' => 'https://example.com/document-name-here',
        ],
    ]
);

// Search for similar vectors in the 'documents' collection using a provided vector
Milvus::vector()->search(
    collectionName: 'documents',
    data: [[0.1, 0.2, 0.3 /* etc... */]],
    annsField: 'vector',
);

// Delete a vector from the 'documents' collection using its ID
Milvus::vector()->delete(
    collectionName: 'documents',
    filter: 'id == 123129471497',
);

// Query the 'documents' collection for specific documents using a filter condition and select specific output fields
Milvus::vector()->query(
    collectionName: 'documents',
    filter: 'id in [443300716234671427, 443300716234671426]',
    outputFields: ['id', 'title', 'link'],
);

// Retrieve a specific vector from the 'documents' collection using its ID
Milvus::vector()->get(
    id: '123129471497',
    collectionName: 'documents'
);

// Update or insert a vector in the 'documents' collection. If the ID exists, it's updated; if not, a new entry is created
Milvus::vector()->upsert(
    collectionName: 'documents',
    data: [
        [
            'id' => 123129471497,
            'vector' => [0.1, 0.2, 0.3 /* etc... */],
            'title' => 'Document name here',
            'link' => 'https://example.com/document-name-here',
        ],
    ]
);
```

### Managing databases

[](#managing-databases)

Database operations use the Milvus REST v2 database endpoints. The REST API is stateless, so pass `dbName` to each collection or vector operation that should run outside the `default` database.

```
Milvus::databases()->create(
    dbName: 'analytics',
    properties: ['database.replica.number' => 1],
)->dto()->throwIfFailed();

$databases = Milvus::databases()->list()->dto()->throwIfFailed();
$analytics = Milvus::databases()->describe('analytics')->dto()->throwIfFailed();

Milvus::collections()->list(dbName: 'analytics');

Milvus::databases()->drop('analytics')->dto()->throwIfFailed();
```

The default database cannot be dropped, and a database must have no collections before it can be dropped. Database list and describe responses expose `databases` and `database`; database IDs remain strings if they exceed PHP's integer range.

### Filtering vector searches

[](#filtering-vector-searches)

Use `filter` to restrict similarity search by scalar fields. `data` is an array of query vectors and `annsField` is the collection's vector field. Scalar fields must be part of the collection schema or accepted by its dynamic field.

```
$results = Milvus::vector()->search(
    collectionName: 'documents',
    data: [[0.1, 0.2, 0.3 /* etc... */]],
    annsField: 'vector',
    filter: 'project_id == 10',
    limit: 10,
    outputFields: ['title', 'project_id'],
)->dto()->throwIfFailed();
```

The same Milvus expression syntax works for `query()` and `delete()`, including expressions such as `id in [1, 2, 3]` and `status == "published"`.

### Custom schemas and AutoID

[](#custom-schemas-and-autoid)

For explicit field control, pass a custom schema. Field options follow the Milvus REST schema unchanged:

```
Milvus::collections()->create(
    collectionName: 'documents',
    schema: [
        'autoID' => false,
        'enableDynamicField' => false,
        'fields' => [
            ['fieldName' => 'id', 'dataType' => 'Int64', 'isPrimary' => true],
            [
                'fieldName' => 'vector',
                'dataType' => 'FloatVector',
                'elementTypeParams' => ['dim' => '1536'],
            ],
            ['fieldName' => 'project_id', 'dataType' => 'Int64'],
        ],
    ],
);
```

With quick setup, set `autoID: true` and omit the primary key from inserted rows. The mutation DTO returns generated IDs through `$response->dto()->result->insertIds`.

### Milvus 3 features

[](#milvus-3-features)

Milvus 3 can search using existing entity IDs instead of providing a vector directly:

```
Milvus::vector()->search(
    collectionName: 'documents',
    data: null,
    annsField: 'vector',
    ids: [123129471497],
    outputFields: ['title', 'link'],
);
```

Partial upserts let you update scalar fields without resending the vector:

```
Milvus::vector()->upsert(
    collectionName: 'documents',
    data: [
        ['id' => 123129471497, 'title' => 'Updated document name'],
    ],
    partialUpdate: true,
);
```

### Without Laravel

[](#without-laravel)

Without Laravel, create a `Milvus` instance with a token, host, and port. For username/password authentication, pass the raw `username:password` value as the token.

```
use HelgeSverre\Milvus\Milvus;

$milvus = new Milvus(
    token: 'root:Milvus',
    host: 'localhost',
    port: '19530'
);
```

The connector exposes the same methods shown above; replace `Milvus::` with `$milvus->`.

### Typed responses

[](#typed-responses)

Every request still returns a Saloon response, so existing `json()` and `collect()` calls continue to work. Call `dto()` when you want a validated response object:

```
$search = Milvus::vector()->search(
    collectionName: 'documents',
    data: [[0.1, 0.2, 0.3]],
    annsField: 'vector',
    limit: 3,
    outputFields: ['title'],
)->dto()->throwIfFailed();

foreach ($search->entities as $entity) {
    echo $entity->id.' '.$entity->field('title').PHP_EOL;
}
```

Milvus can report API failures with HTTP status 200, so use `throwIfFailed()` when handling a DTO. It throws a `MilvusApiException` containing the Milvus error code. Malformed success payloads throw `InvalidResponseException`instead of silently returning partial data.

The response types are `EmptyResponse` for create/drop, `DatabaseListResponse`, `DatabaseDescriptionResponse`, `CollectionListResponse`, `CollectionDescriptionResponse`, `MutationResponse` for insert/upsert/delete, `EntityResponse` for get/query, and `SearchResponse`. Dynamic entity fields and unknown future response fields remain available through `raw`.

### Using with Zilliz Cloud

[](#using-with-zilliz-cloud)

Milvus v0.2 and newer automatically uses the `/v2/vectordb/...` endpoints; do not include an API version or operation path in the host. For Zilliz Cloud, pass the HTTPS cluster endpoint, port 443, and your API key as the token:

```
use HelgeSverre\Milvus\Milvus;

$milvus = new Milvus(
    token: 'your-api-key',
    host: 'https://in03-example.serverless.gcp-us-west1.cloud.zilliz.com',
    port: '443'
);
```

Existing applications that still send requests to `/v1/vector/...` should upgrade with `composer require helgesverre/milvus:^0.2`.

Example: Semantic Search with Milvus and OpenAI Embeddings
----------------------------------------------------------

[](#example-semantic-search-with-milvus-and-openai-embeddings)

This example demonstrates how to perform a semantic search in Milvus using embeddings generated from OpenAI.

### Prepare Your Data

[](#prepare-your-data)

First, create an array of data you wish to index. In this example, we'll use blog posts with titles, summaries, and tags.

```
$blogPosts = [
    [
        'title' => 'Exploring Laravel',
        'summary' => 'A deep dive into Laravel frameworks...',
        'tags' => ['PHP', 'Laravel', 'Web Development']
    ],
       [
        'title' => 'Exploring Laravel',
        'summary' => 'A deep dive into Laravel frameworks, exploring its features and benefits for modern web development.',
        'tags' => ['PHP', 'Laravel', 'Web Development']
    ],
    [
        'title' => 'Introduction to React',
        'summary' => 'Understanding the basics of React and how it revolutionizes frontend development.',
        'tags' => ['JavaScript', 'React', 'Frontend']
    ],
    [
        'title' => 'Getting Started with Vue.js',
        'summary' => 'A beginner’s guide to building interactive web interfaces with Vue.js.',
        'tags' => ['JavaScript', 'Vue.js', 'Frontend']
    ],
];
```

### Generate Embeddings

[](#generate-embeddings)

Use OpenAI's embeddings API to convert the summaries of your blog posts into vector embeddings.

```
$summaries = array_column($blogPosts, 'summary');
$embeddingsResponse = OpenAI::client('sk-your-openai-api-key')
    ->embeddings()
    ->create([
        'model' => 'text-embedding-ada-002',
        'input' => $summaries,
    ]);

foreach ($embeddingsResponse->embeddings as $embedding) {
    $blogPosts[$embedding->index]['vector'] = $embedding->embedding;
}
```

### Create Milvus collection

[](#create-milvus-collection)

Create a collection in Milvus to store your blog post embeddings, note that the dimension of the embeddings must match the dimension of the embeddings generated by OpenAI (`1536` if you are using the `text-embedding-ada-002` model).

```
$milvus = new Milvus(
    token: 'your-token',
    host: 'localhost',
    port: '19530'
);

$milvus->collections()->create(
    collectionName: 'blog_posts',
    dimension: 1536,
);
```

### Insert into Milvus

[](#insert-into-milvus)

Insert these embeddings, along with other blog post data, into your Milvus collection.

```
$insertResponse = $milvus->vector()->insert('blog_posts', $blogPosts);
```

### Creating a Search Vector with OpenAI

[](#creating-a-search-vector-with-openai)

Generate a search vector for your query, akin to how you processed the blog posts.

```
$searchVectorResponse = OpenAI::client('sk-your-openai-api-key')
    ->embeddings()
    ->create([
        'model' => 'text-embedding-ada-002',
        'input' => 'laravel framework',
    ]);

$searchEmbedding = $searchVectorResponse->embeddings[0]->embedding;
```

### Searching using the Embedding in Milvus

[](#searching-using-the-embedding-in-milvus)

Use the Milvus client to perform a search with the generated embedding.

```
$searchResponse = $milvus->vector()->search(
    collectionName: 'blog_posts',
    data: [$searchEmbedding],
    annsField: 'vector',
    limit: 3,
    outputFields: ['title', 'summary', 'tags']
)->dto()->throwIfFailed();

// Output the search results
foreach ($searchResponse->entities as $result) {
    echo "Title: " . $result->field('title') . "\n";
    echo "Summary: " . $result->field('summary') . "\n";
    echo "Tags: " . implode(', ', $result->field('tags', [])) . "\n\n";
}
```

Running Milvus in Docker
------------------------

[](#running-milvus-in-docker)

To quickly get started with Milvus, you can run it in Docker, by using the following command

```
# Download the docker-compose.yml file
wget https://github.com/milvus-io/milvus/releases/download/v3.0.0/milvus-standalone-docker-compose.yml -O docker-compose.yml

# Start Milvus
docker compose up --wait --wait-timeout 180
```

A healthcheck endpoint will now be available on `http://localhost:9091/healthz`, and the Milvus API will be available on `http://localhost:19530`.

To stop Milvus, run `docker compose down`. Data is stored in the local `volumes/` directory.

For more details [Installing Milvus Standalone with Docker Compose](https://milvus.io/docs/install_standalone-docker.md)

For production workloads, consider checking out [Zilliz.com](https://zilliz.com/), which are the developers behind Milvus and provides a hosted version of Milvus in the Cloud ☁️.

Testing
-------

[](#testing)

The fast suite verifies request serialization, response decoding and edge cases, authentication, Laravel service-provider resolution, and architecture rules without contacting Milvus:

```
just unit
```

The full test command starts Docker and runs both the unit suite and live full-client smoke, database, collection, custom-schema, AutoID, filtered-search, error-envelope, and response-DTO scenarios:

```
just test
```

To run only the integration suite against a specific supported Milvus version:

```
cp .env.example .env
just integration 2.5.21
```

Run the remaining release checks with:

```
composer analyse src
composer format:test
composer validate --strict
composer audit
```

CI repeats the integration test against Milvus 2.5.21, 2.6.21, and 3.0.0, and runs the package suite across PHP 8.3–8.5 and Laravel 10–13.

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

Disclaimer
----------

[](#disclaimer)

"Milvus®" and the Milvus logo are registered trademarks of the [Linux Foundation](https://www.linuxfoundation.org/about) (LF Projects, LLC). This package is not affiliated with, endorsed by, or sponsored by the Linux Foundation. It's developed independently and uses the "Milvus" name under fair use, solely for identification. All trademarks and registered trademarks, including "Milvus®", are the property of their respective owners. "Milvus®" is a [registered trademark](https://branddb.wipo.int/en/quicksearch/brand/EM500000018660437) of the Linux Foundation.

###  Health Score

44

—

FairBetter than 90% of packages

Maintenance60

Regular maintenance activity

Popularity35

Limited adoption so far

Community15

Small or concentrated contributor base

Maturity53

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 90.5% 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 ~158 days

Recently: every ~237 days

Total

7

Last Release

15d ago

PHP version history (2 changes)v0.0.1PHP ^8.2

v0.2.0PHP ^8.3

### Community

Maintainers

![](https://www.gravatar.com/avatar/68f3958f40262d577ddc0596e4ba78b42c0409ebc7de948bab47edee392d5f68?d=identicon)[HelgeSverre](/maintainers/HelgeSverre)

---

Top Contributors

[![HelgeSverre](https://avatars.githubusercontent.com/u/1089652?v=4)](https://github.com/HelgeSverre "HelgeSverre (57 commits)")[![yourpropertyexpert](https://avatars.githubusercontent.com/u/16901176?v=4)](https://github.com/yourpropertyexpert "yourpropertyexpert (3 commits)")[![scotteuser](https://avatars.githubusercontent.com/u/7620946?v=4)](https://github.com/scotteuser "scotteuser (2 commits)")[![Barbery](https://avatars.githubusercontent.com/u/2239529?v=4)](https://github.com/Barbery "Barbery (1 commits)")

---

Tags

clientlaravelmilvusphpsdkvector-databasephplaravelsdkdatabasevectormilvusvectorstore

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/helgesverre-milvus/health.svg)

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

###  Alternatives

[helgesverre/chromadb

PHP Client for the Chromadb Rest API

321.8k](/packages/helgesverre-chromadb)[relaticle/custom-fields

User Defined Custom Fields for Laravel Filament

16461.2k](/packages/relaticle-custom-fields)[codebar-ag/laravel-docuware

DocuWare integration with Laravel

1125.1k](/packages/codebar-ag-laravel-docuware)[ntanduy/cloudflare-d1-database

Cloudflare D1 database driver for Laravel — full Eloquent & Query Builder support.

278.2k](/packages/ntanduy-cloudflare-d1-database)[tarfin-labs/event-machine

Event-driven state machines for Laravel with event sourcing, type-safe context, and full audit trail.

219.6k](/packages/tarfin-labs-event-machine)

PHPackages © 2026

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