Chromadb Php Laravel Package

This release represents a complete overhaul of the ChromaDB PHP client to support Chroma v1.0 and the Chroma v2 API. The package has been refactored with modern PHP standards, improved type safety, and enhanced developer experience.

New Features

• New ChromaDB::cloud() helper method for easy Chroma Cloud connections
• Automatic header configuration for cloud authentication
• Support for forking collections (Chroma Cloud only)
• Create copies of existing collections with new names
• New Record and ScoredRecord classes for structured data handling
• Fluent API for building records: Record::make('id')->withDocument('text')->withMetadata(['key' => 'value'])
• All collection methods (add, update, upsert) now accept arrays of Record objects
• Response methods (get, query) can convert results to records via asRecords()
• Type-safe Where query builder for filtering
• Metadata filtering: Where::field('category')->eq('news')
• Document content filtering: Where::document()->contains('text')
• Logical operators: Where::all(), Where::any()
• Full support for all Chroma filter operators (eq, ne, gt, gte, lt, lte, in, nin, contains, regex)
• New Includes enum for specifying response fields
• Better type hints throughout the codebase
• Improved validation with descriptive error messages
• Automatic batch generation of missing embeddings
• Support for partial embeddings arrays where some items have embeddings and others are null
• New ChromaDB::local() helper method for local/self-hosted instances
• Simplified connection configuration

Improvements

• Migrated to PSR-18/PSR-17 standards with HTTP Discovery
• Automatic detection of installed HTTP clients (GuzzleHttp, Symfony HTTP Client, etc.)
• Removed hard dependency on GuzzleHttp
• Consistent exception types based on Chroma's standardized error responses
• Cleaner exception class names (removed "Chroma" prefix)
• Better error messages with context
• Removed CollectionResource wrapper - Collection is now the direct resource
• Collections from listCollections() can be used immediately
• Cleaner API surface with fewer abstraction layers
• Comprehensive test coverage with negative test scenarios
• Chroma CLI integration for local server management
• Better test organization and fixtures
• Completely rewritten README with modern examples
• New real-world example: document chunking with Chroma Cloud
• Enhanced inline documentation

Breaking Changes

• ChromaDB::client() is deprecated - use ChromaDB::local()->connect() or ChromaDB::factory()->connect() instead
• ChromaDB::reset() static method removed - use $client->reset() instance method instead
• Factory::withAuthToken() is deprecated - use Factory::withHeader('X-Chroma-Token', $token) instead
• Factory::withHttpClient() method removed - HTTP client is now auto-discovered via PSR-18
• CollectionResource class removed - Collection is now the direct resource model
• listCollections() now returns Collection[] instead of CollectionResource[]
• All exception classes renamed (removed "Chroma" prefix):
  • ChromaNotFoundException → NotFoundException
  • ChromaConnectionException → ConnectionException
  • ChromaValueException → ValueException
  • ChromaUniqueConstraintException → UniqueConstraintException
  • ChromaDimensionalityException → DimensionalityException
  • ChromaInvalidCollectionException → InvalidCollectionException
  • ChromaTypeException → TypeException
  • ChromaInvalidArgumentException → InvalidArgumentException
• Exception namespace changed from Generated\Exceptions to Exceptions
• Exception creation changed from ChromaException::throwSpecific() to ChromaException::create()
• ChromaApiClient class removed - replaced with Api class
• Image parameters removed from all item-related requests (was never fully supported)
• guzzlehttp/guzzle moved from require to require-dev - package now requires PSR-18/PSR-17 compatible HTTP clients (auto-discovered)

Migration Checklist

• Update composer.json to require ^1.0
• Replace ChromaDB::client() with ChromaDB::local()->connect()
• Replace withAuthToken() with withHeader('X-Chroma-Token', $token)
• Update all exception imports (remove "Chroma" prefix, update namespace)
• Replace ChromaDB::reset() with $client->reset()
• Ensure a PSR-18 HTTP client is installed (or will be auto-discovered)
• Test collection operations (should work the same)
• Review and update any custom exception handling code

🙏 Acknowledgments

Thank you to all contributors and users who provided feedback during the development of this major release.

Full Changelog: https://github.com/CodeWithKyrian/chromadb-php/compare/0.4.0...1.0.0

What's Changed

• PHP 8.4 by @chr-hertel in https://github.com/CodeWithKyrian/chromadb-php/pull/11
• Create MistralAIEmbeddingFunction.php by @OliverIost in https://github.com/CodeWithKyrian/chromadb-php/pull/9

New Contributors

• @chr-hertel made their first contribution in https://github.com/CodeWithKyrian/chromadb-php/pull/11
• @OliverIost made their first contribution in https://github.com/CodeWithKyrian/chromadb-php/pull/9

Full Changelog: https://github.com/CodeWithKyrian/chromadb-php/compare/0.3.0...0.4.0

What's Changed

• Support Chroma v0.5.0
• New environment variables by @BlackyDrum in https://github.com/CodeWithKyrian/chromadb-php/pull/7
• Add support for Ollama Embedding Function by @CodeWithKyrian in https://github.com/CodeWithKyrian/chromadb-php/pull/8

Full Changelog: https://github.com/CodeWithKyrian/chromadb-php/compare/v0.2.1...0.3.0

What's Changed

• Fix bug introduced in 0.2.0 while handling exceptions by @CodeWithKyrian in https://github.com/CodeWithKyrian/chromadb-php/pull/5
• Throw better exceptions when connecting to non-existent chroma server by @CodeWithKyrian in https://github.com/CodeWithKyrian/chromadb-php/commit/b27ad8b7c07d2e0cf4fa09909eda3fb9d932d965

Full Changelog: https://github.com/CodeWithKyrian/chromadb-php/compare/v0.2.0...v0.2.1

What's Changed

• New - Add static api authentication with bearer token by @BlackyDrum in https://github.com/CodeWithKyrian/chromadb-php/pull/3
• BugFix - Validate and cast ids array for collections as strings by @CodeWithKyrian in https://github.com/CodeWithKyrian/chromadb-php/commit/8d8691fae179439c1feb0f05b3f15c08d5eb3bb8

New Contributors

• @BlackyDrum made their first contribution in https://github.com/CodeWithKyrian/chromadb-php/pull/3

Full Changelog: https://github.com/CodeWithKyrian/chromadb-php/compare/v0.1.0...v0.2.0

🚀 Initial Release

Release Highlights:

• Initial Integration with ChromaDB: Introduction of seamless integration with ChromaDB, enabling PHP developers to interact with high-dimensional vector databases effortlessly.
• Core Functionality: Provides essential features to create, manage, and query collections, allowing users to handle documents and execute queries effectively.
• Flexible Embedding Support: Offers support for multiple embedding functions, allowing diverse methods for computing and managing document embeddings.
• Error Handling and Performance: Initial implementation of error handling mechanisms and foundational optimizations for better performance.
• Comprehensive Documentation: Detailed documentation to guide users through setup, usage, and implementation of the ChromaDB PHP client.

These highlights showcase the foundational features and capabilities introduced in the inaugural release, laying the groundwork for a robust and efficient ChromaDB PHP client.

Get Started:

Refer to our documentation or README for guidance on getting started with this release.