Download the PHP package helgesverre/chromadb without Composer

ChromaDB PHP API Client

A framework-agnostic PHP client for the ChromaDB v2 API. Works with any PHP 8.2+ project, with optional Laravel integration for enhanced developer experience.

Use Anywhere: This package works in vanilla PHP, Symfony, WordPress, or any PHP framework.
Laravel features (config, facades, service provider) are completely optional.

Looking for an alternative? Check out CodeWithKyrian/chromadb-php for another ChromaDB PHP client.

Documentation

Version Compatibility

This package supports ChromaDB v2 API. The v1 API has been deprecated by ChromaDB.

• ChromaDB Server: 1.0.0 - 1.5.x
• PHP: 8.2+
• Laravel: 11.x, 12.x, 13.x (optional)

Version-Specific Features

Installation

Install the package via Composer:

Quick Start

Basic Usage (Any PHP Project)

Using with Laravel (Optional)

If you're using Laravel, you can leverage the Facade and config-based setup:

See the Laravel Integration section below for full setup details, including dependency injection.

Usage

Collections

Items

Database Management

ChromaDB v2 supports multiple databases within a tenant for logical data separation:

Tenant Management

Manage tenants for multi-tenancy isolation:

Server API

Monitor and manage the ChromaDB server:

Multi-Tenancy

ChromaDB v2 provides native multi-tenancy support:

Attached Functions (ChromaDB 1.3.0+)

Attach server-side functions to collections for automatic processing:

Note: Attached functions require ChromaDB 1.3.0 or higher. These methods will return error responses on older versions.

Laravel Integration (Optional)

If you're using Laravel, this package provides additional features for enhanced developer experience through the service provider, config file, and Facade.

Publishing Configuration

Publish the config file with:

This creates config/chromadb.php with the following structure:

Environment Variables

Add these variables to your .env file:

Using the Facade

The package automatically registers a Facade for convenient static access:

Dependency Injection

The service provider automatically binds the client to the container:

Using Config-Based Embeddings (Laravel Only)

Note: The Embeddings::fromConfig() method requires Laravel and reads from your config file.

Embedding Providers

This package includes built-in support for automatic embedding generation using various providers. All embedding classes work in any PHP project - Laravel is not required.

Supported Providers

• OpenAI - text-embedding-3-small, text-embedding-3-large, text-embedding-ada-002
• Voyage AI - voyage-3.5 (default), voyage-3-large, voyage-code-3, voyage-finance-2, voyage-law-2
• Mistral AI - mistral-embed
• Jina AI - jina-embeddings-v3, jina-embeddings-v2-base-en, jina-embeddings-v2-small-en, jina-clip-v2
• Ollama - Local embeddings with any Ollama model

Direct Usage (Any PHP Project)

Create embedding providers directly without any framework dependencies:

With Laravel Config (Laravel Only)

If using Laravel, you can configure embeddings in your config file and load them with fromConfig():

Automatic Embedding Generation

Using withEmbeddings()

Configure a client instance with an embedding function for automatic embedding generation:

Available Embedding Providers

All providers implement the EmbeddingFunction interface and work in any PHP 8.2+ project (Laravel not required). Each provider can be instantiated directly or using the Embeddings factory class.

1. OpenAI Embeddings

2. Voyage AI Embeddings

3. Mistral AI Embeddings

4. Jina AI Embeddings

5. Ollama Embeddings (Local)

Using Helper Functions

For a more functional programming style, the package provides convenient helper functions:

Creating Custom Embedding Functions

You can create your own embedding provider by implementing the EmbeddingFunction interface. This works in any PHP project:

Interface Definition

Example: Semantic Search with ChromaDB and OpenAI Embeddings

This example demonstrates how to perform a semantic search in ChromaDB using embeddings generated from OpenAI. This works in any PHP project.

Full code available in SemanticSearchTest.php.

Note: This example uses the OpenAI PHP client. You can use any method to generate embeddings - this package's embedding providers, direct API calls, or any other embedding service.

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.

Generate Embeddings

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

Create ChromaDB Collection

Create a collection in ChromaDB to store your blog post embeddings.

Insert into ChromaDB

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

Creating a Search Vector with OpenAI

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

Searching using the Embedding in ChromaDB

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

Running ChromaDB in Docker

To quickly get started with ChromaDB (works with any PHP setup), you can run it in Docker:

The auth token is set to test-token-chroma-local-dev by default.

You can change this in the docker-compose.yml file by changing the CHROMA_SERVER_AUTH_CREDENTIALS environment variable

To stop ChromaDB, run docker compose down, to wipe all the data, run docker compose down -v.

NOTE

The docker-compose.yml file in this repo is provided only as an example and should not be used in production.

Go to the ChromaDB deployment documentation for more information on deploying Chroma in production.

Testing

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security-related issues, please email the maintainer instead of using the issue tracker.

Credits

• Helge Sverre
• All Contributors

License

The MIT License (MIT). Please see License File for more information.