# PDODocument

This library allows SQLite and PostgreSQL to be treated as document databases. It is a PHP implementation of the .NET [BitBadger.Documents](https://relationaldocs.bitbadger.solutions/dotnet/) library.

## Add via Composer

[![Packagist Version](https://img.shields.io/badge/v1.2.0-blue?label=packagist)](https://packagist.org/packages/bit-badger/pdo-document#v1.2.0)

`composer require bit-badger/pdo-document:^1`

This version requires PHP 8.2 or greater.

v1.2 adds a `Field->andQualifier()` function to modify the qualifier for a field and return the same instance.

## Configuration

### Connection Details

The [PDO data source name](https://www.php.net/manual/en/pdo.construct.php#refsect1-pdo.construct-parameters) 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 <abbr title="Universally Unique Identifier">UUID</abbr> 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](https://relationaldocs.bitbadger.solutions/php/).