README

This library allows SQLite and PostgreSQL to be treated as document databases. It is a PHP implementation of the .NET BitBadger.Documents library.

Add via Composer

composer require bit-badger/pdo-document:^3

(Version 3 requires PHP 8.5 or greater.)

For the v1 series, the DocumentList type's members hasItems and items are functions; in the v2 series, they are properties. Additionally, the Option and Result types included in the project have a similar difference; see the v1 README for PHP 8.2 or 8.3 and the v2 README for PHP 8.4. Both versions are supported; the v1 / v2 distinction helps composer make the right choice based on the target PHP version of your project.

v1.2, v2.2, and v3 add a Field->andQualifier() function to modify the qualifier for a field and return the same instance. v3 also includes Field::withQualifier() which returns a new instance (and is designed for PHP 8.5's pipe operator); this makes it suitable for mapping an array of fields, adding a qualifier to them.

Configuration

Connection Details

The PDO data source name must be provided via Configuration::useDSN(). Configuration also has $username, $password, and $options variables that will be used to construct the PDO object it will use for data access.

Document Identifiers

Each document must have a unique identifier. By default, the library assumes that this is a property or array key named id, but this can be controlled by setting Configuration::$idField. Once documents exist, this should not be changed.

IDs can be generated automatically on insert. The AutoId enumeration has 4 values:

• AutoId::None is the default; no IDs will be generated
• AutoId::Number will assign max-ID-plus-one to documents with an ID of 0
• AutoId::UUID will generate a v4 UUID for documents with an empty string ID
• AutoId::RandomString will generate a string of letters and numbers for documents with an empty string ID; Configuration::$idStringLength controls the length of the generated string, and defaults to 16 characters

In all generated scenarios, if the ID value is not 0 or blank, that ID will be used instead of a generated one.

Usage

Full documentation is available on the project site.