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.):

Create your own package that requires this contracts library.
Implement the interfaces in your classes:
- Create a concrete VectorStoreInterface implementation.
- Create concrete VectorCollectionRepositoryInterface implementations.
- Optionally create a VectorStoreFactoryInterface for configuration.
Ensure your implementation satisfies all contract requirements and semantics (distance metrics, filters, exceptions).
Use the provided DTOs and collections for data exchange.
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

adachsoft / vector-store-contracts

Maintainers

Package info

Statistics

Security