pdo-document/README.md

37 lines
2.6 KiB
Markdown
Raw Permalink Normal View History

# PDODocument
2024-06-03 23:07:15 +00:00
This library allows SQLite and PostgreSQL to be treated as document databases. It is a PHP implementation of the .NET [BitBadger.Documents](https://git.bitbadger.solutions/bit-badger/BitBadger.Documents) library.
## Add via Composer
[![Static Badge](https://img.shields.io/badge/v1.0.0--rc1-orange?label=php%208.2)
](https://packagist.org/packages/bit-badger/pdo-document#v1.0.0-rc1)     [![Packagist Version](https://img.shields.io/packagist/v/bit-badger/pdo-document?include_prereleases&label=php%208.4)
](https://packagist.org/packages/bit-badger/pdo-document)
2024-06-09 00:35:38 +00:00
`composer require bit-badger/pdo-document`
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](https://git.bitbadger.solutions/bit-badger/inspired-by-fsharp/src/branch/v1/README.md) for PHP 8.2 or 8.3 and the [v2 README](https://git.bitbadger.solutions/bit-badger/inspired-by-fsharp/src/branch/main/README.md) 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.
## Configuration
### Connection Details
2024-07-22 15:10:33 +00:00
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
2024-07-22 15:10:33 +00:00
Full documentation [is available on the project site](https://bitbadger.solutions/open-source/pdo-document/).