Download the PHP package codewithkyrian/chromadb-php without Composer

ChromaDB PHP

A customized, framework-agnostic PHP library for interacting with Chroma vector database seamlessly.

Note: This package is framework-agnostic. If you use Laravel, check out chromadb-laravel for a tailored experience.

Introduction

Chroma is an open-source vector database designed to be fast, scalable, and reliable. ChromaDB PHP allows you to interact with Chroma servers seamlessly. It provides a fluent, type-safe API for managing collections, documents, and embeddings, making it easy to build LLM-powered applications in PHP.

Requirements

• PHP 8.1 or higher
• ChromaDB 1.0 or higher

Installation

Configuration & Setup

Running ChromaDB

You need a running ChromaDB instance.

Docker (Recommended):

Chroma CLI:

Connectivity

Connect to your Chroma server. The default connection is http://localhost:8000.

Embedding Functions

ChromaDB uses embedding functions to convert text into vectors. You can define which function a collection uses upon creation.

Embedding functions are linked to a collection and used when you call add, update, upsert or query. If you add documents without embeddings, it is used to generate them automatically. If you query using text, it is used to convert your query text into a vector for search.

The library provides lightweight wrappers around popular embedding providers for ease of use:

• OpenAIEmbeddingFunction
• JinaEmbeddingFunction
• HuggingFaceEmbeddingServerFunction
• OllamaEmbeddingFunction
• MistralAIEmbeddingFunction

Example:

Custom Functions

You can create your own embedding function by implementing Codewithkyrian\ChromaDB\Embeddings\EmbeddingFunction.

Collections

Collections are where you store and categorize your embeddings and documents. All operations are performed on a specific collection.

Adding Data

You can add items to a collection using the structured Record class or raw arrays. Both methods represent the same data:

• IDs (Required): Unique string identifier.
• Embeddings: Vector representation (float array).
• Documents: Raw text content.
• Metadatas: Key-value pairs for filtering.

Using Arrays

You can pass a parallel arrays of IDs, embeddings, metadatas, etc. This is useful for bulk operations.

Using Records (Fluent API)

The Record class provides a fluent interface for building items. It mirrors the array structure but in an object-oriented way.

If you provide documents but omit embeddings, Chroma uses the collection's Embedding Function to generate them. This is useful if you have an external embedding function or if you want to manually control the embedding process. When providing just embeddings and not documents, it's assumed you're storing the documents elsewhere and associating the provided embeddings with those documents using the ids or any other metadata.

If the supplied embeddings are not the same dimension as the embeddings already indexed in the collection, an exception will be raised.

Retrieval (get and peek)

Retrieve specific items by ID or filtered metadata without generating embeddings.

Get

Fetch specific items.

Peek

Preview the first n items in the collection.

Specifying Return Data (include)

Both get and query allow you to specify what data to return using the include parameter.

Note: Includes::Distances is only available when Querying, not when using get().

Querying (Vector Search)

Querying is about finding items semantically similar to your input. Chroma performs a vector search to find the nearest neighbors. ChromaDB-PHP also provides a powerful, fluent query builder for filtering by metadata and document content.

Query by Text

Provide text strings. Chroma embeds them using the collection's Embedding Function and finds the nearest neighbors.

Query by Embeddings

Provide raw vectors. Useful if you compute embeddings externally.

Specifying Return Data (include)

By default, queries return IDs, Embeddings, Metadatas, and Distances. You can customize this using the Includes enum to optimize performance.

Metadata Filtering (where)

You can filter search results based on metadata of the items. The library provides a fluent Builder for safety, but also supports raw arrays.

Supported Comparisons

Usage

Full Text Search (whereDocument)

Used to filter based on the text content of the document itself. This supports substring matching and Regex. You can also use the fluent builder or array syntax.

Supported Comparisons

Usage

Updating Data

Use update to modify existing items (fails if ID missing) or upsert to update-or-create. Just like adding, you can either pass an array of records, or a parallel array of IDs, documents, and metadatas.

Deleting Data

Delete by IDs or by filter.

Examples

• basic-usage - Simple example demonstrating basic operations: connecting, adding documents, and querying
• document-chunking-cloud - Document chunking, embedding, and storage in Chroma Cloud with semantic search

Testing

Run the test suite using Pest.

License

MIT License. See LICENSE for more information.