README

A PHP library providing comprehensive contracts and testing utilities for vector store implementations.

Overview

This package defines interfaces, DTOs, collections, and exceptions for vector stores, along with abstract PHPUnit contract tests that can be extended by concrete implementations. It provides a provider-agnostic foundation for integrating vector databases in PHP applications.

Installation

Install via Composer:

composer require adachsoft/vector-store-contracts

After installation you can immediately use the in-memory adapter provided by this package under the AdachSoft\\VectorStoreInMemory namespace. It is intended primarily for testing, examples and as a reference implementation of the contracts, not as a production-ready backend.

Contracts Overview

Core Interfaces

• VectorStoreInterface - Main entrypoint for managing vector collections (namespaces)
• VectorCollectionRepositoryInterface - CRUD and search operations on a single collection
• VectorStoreFactoryInterface - Factory for creating configured vector store instances

Data Transfer Objects

• VectorRecordDto - Record with vector embedding and metadata
• SearchQueryDto - Vector search query with filters and constraints
• SearchResultDto - Single search result with similarity score
• UpsertResultDto - Result of insert/update operations

Collections

• FloatVectorCollection - Immutable collection of float vectors
• MetadataCollection - Immutable map of scalar metadata
• FilterCollection - Immutable map of search filters
• SearchResultDtoCollection - Immutable collection of search results

Supporting Types

• DistanceMetricEnum - Supported distance metrics (COSINE, EUCLIDEAN, DOT_PRODUCT)
• VectorStoreException - Base exception for the library
• CollectionNotFoundException - Thrown when collection doesn't exist
• UpsertFailedException - Thrown when insert/update fails
• DimensionMismatchException - Thrown when vector dimensions don't match

Implementing a Provider

To integrate a concrete vector database (e.g., Qdrant, Milvus, PostgreSQL with pgvector, etc.):

1. Create your own package that requires this contracts library.
2. Implement the interfaces in your classes:
   • Create a concrete VectorStoreInterface implementation.
   • Create concrete VectorCollectionRepositoryInterface implementations.
   • Optionally create a VectorStoreFactoryInterface for configuration.
3. Ensure your implementation satisfies all contract requirements and semantics (distance metrics, filters, exceptions).
4. Use the provided DTOs and collections for data exchange.
5. Use the in-memory implementation (AdachSoft\\VectorStoreInMemory) and .docs/implementation-guide.md as a reference for structure, behaviour and tests integration.

In-memory reference implementation

This package ships with a simple, fully in-memory implementation of the contracts under the AdachSoft\\VectorStoreInMemory namespace. It stores collections and records in PHP arrays and implements all behaviours required by the contract tests (distance metrics, filters, exceptions).

You can use it as:

• a quick way to experiment with the contracts without configuring an external vector store,
• a reference for how to implement VectorStoreInterface, VectorCollectionRepositoryInterface and VectorStoreFactoryInterface,
• a baseline to run and understand the contract tests.

Key classes:

• InMemoryVectorStore – manages collections and exposes repositories,
• InMemoryVectorCollectionRepository – performs CRUD and vector search in memory,
• InMemoryVectorStoreFactory – creates in-memory stores and can serve as a template for real factories.

See .docs/implementation-guide.md for a detailed walkthrough of these classes and their responsibilities.

Contract Tests

This package ships with abstract PHPUnit test cases for validating implementations:

• AbstractVectorStoreContractTestCase - Tests VectorStoreInterface behavior
• AbstractVectorCollectionRepositoryContractTestCase - Tests repository behavior

To use these tests in your implementation:

// In your test file
class MyVectorStoreTest extends AbstractVectorStoreContractTestCase
{
    protected function createStore(): VectorStoreInterface
    {
        return new MyVectorStoreImplementation();
    }
}

class MyVectorCollectionRepositoryTest extends AbstractVectorCollectionRepositoryContractTestCase
{
    protected function createRepository(): VectorCollectionRepositoryInterface
    {
        // Create and return your repository instance
        return new MyVectorCollectionRepository();
    }
}

Development

This project uses quality tools configured via Composer scripts:

# Check code style
composer cs:check

# Fix code style
composer cs:fix

# Run static analysis
composer stan

# Run Rector refactoring
composer rector

The repository includes ready-to-use configurations for:

• PHP-CS-Fixer - Code style enforcement
• PHPStan - Static analysis
• Rector - Automated refactoring

Requirements

• PHP >= 8.0
• Composer

License

MIT