Skip to content

v1.0.0

Latest
Latest

Choose a tag to compare

View all tags
@CodeWithKyrian CodeWithKyrian released this 06 Dec 20:25
1.0.0
a27f415

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: 0.4.0...1.0.0

Assets 2
Loading