v3 (#11)

Reviewed-on: #11

README.md

@@ -1,16 +1,21 @@
 # PDODocument
 
-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.
+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
 
-[![v1 Packagist Version](https://img.shields.io/badge/v1.1.0-blue?label=php%208.2)
-](https://packagist.org/packages/bit-badger/pdo-document#v1.1.0-rc1)     [![Packagist Version](https://img.shields.io/packagist/v/bit-badger/pdo-document?include_prereleases&label=php%208.4)
+[![v1 Packagist Version](https://img.shields.io/badge/v1.2.0-blue?label=php%208.2)
+](https://packagist.org/packages/bit-badger/pdo-document#v1.2.0)     [![v2 Packagist Version](https://img.shields.io/badge/v2.2.0-blue?label=php%208.2)
+](https://packagist.org/packages/bit-badger/pdo-document#v2.2.0)     [![Packagist Version](https://img.shields.io/packagist/v/bit-badger/pdo-document?include_prereleases&label=php%208.5)
 ](https://packagist.org/packages/bit-badger/pdo-document)
 
-`composer require bit-badger/pdo-document`
+`composer require bit-badger/pdo-document:^3`
 
-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.
+_(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](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/v2/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.
+
+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
 

composer.json

@@ -18,15 +18,15 @@
     "docs": "https://relationaldocs.bitbadger.solutions/php/"
   },
   "require": {
-    "php": ">=8.4",
+    "php": ">=8.5",
     "bit-badger/inspired-by-fsharp": "^2",
     "netresearch/jsonmapper": "^4",
     "ext-pdo": "*"
   },
   "require-dev": {
-    "square/pjson": "^0.5.0",
+    "square/pjson": "^0.6.0",
     "phpstan/phpstan": "^1.12",
-    "pestphp/pest": "^3.2"
+    "pestphp/pest": "^4"
   },
   "autoload": {
     "psr-4": {

docs/advanced/related.md

@@ -5,7 +5,7 @@
 
 ## Overview
 
-Document stores generally have fewer relationships than traditional relational databases, particularly those that arise when data is structured in [Third Normal Form][tnf]; related collections are stored in the document, and ever-increasing surrogate keys (_a la_ sequences and such) do not play well with distributed data. Unless all data is stored in a single document, though, there will still be a natural relation between documents.
+Document stores generally have fewer relationships than traditional relational databases, particularly those that arise when data is structured in [Third Normal Form][tnf]; related collections are stored in the document, and ever-increasing surrogate keys (_à la_ sequences and such) do not play well with distributed data. Unless all data is stored in a single document, though, there will still be a natural relation between documents.
 
 Thinking back to our earlier examples, we did not store the collection of rooms in each hotel's document; each room is its own document and contains the ID of the hotel as one of its properties.
 

index.md

@@ -7,11 +7,12 @@ PDODocument is a PHP library that implements [relational document](/) concepts o
 
 ## Installing
 
-[![v1 Packagist Version](https://img.shields.io/badge/v1.1.0-blue?label=php%208.2)
-](https://packagist.org/packages/bit-badger/pdo-document#v1.1.0)     [![Packagist Version](https://img.shields.io/packagist/v/bit-badger/pdo-document?include_prereleases&label=php%208.4)
+[![v1 Packagist Version](https://img.shields.io/badge/v1.2.0-blue?label=php%208.2)
+](https://packagist.org/packages/bit-badger/pdo-document#v1.2.0)     [![v2 Packagist Version](https://img.shields.io/badge/v2.2.0-blue?label=php%208.4)
+](https://packagist.org/packages/bit-badger/pdo-document#v2.2.0)     [![Packagist Version](https://img.shields.io/packagist/v/bit-badger/pdo-document?include_prereleases&label=php%208.5)
 ](https://packagist.org/packages/bit-badger/pdo-document)
 
-The library is [listed on Packagist][pkg] as `bit-badger/pdo-document`. v1.x targets PHP 8.2 and 8.3, while v2.x targets PHP 8.4 and up. Run `composer require bit-badger/pdo-document` (or add it to your `composer.json` manually), and it should select the appropriate version based on the target PHP version of your project.
+The library is [listed on Packagist][pkg] as `bit-badger/pdo-document`. v1.x targets PHP 8.2 and 8.3; v2.x targets PHP 8.4; and v3.x targets PHP 8.5 and up. Run `composer require bit-badger/pdo-document` (or add it to your `composer.json` manually), and it should select the appropriate version based on the target PHP version of your project.
 
 ## Using
 

src/Configuration.php

@@ -57,8 +57,9 @@ class Configuration
         if (empty($dsn)) {
             self::$mode = self::$pdoDSN = Option::None();
         } else {
-            self::$mode   = Option::Some(Mode::deriveFromDSN($dsn));
             self::$pdoDSN = Option::Some($dsn);
+            self::$mode   = Mode::deriveFromDSN($dsn)
+                            |> Option::Some(...);
         }
     }
 

src/Field.php

@@ -35,6 +35,7 @@ class Field
      *
      * @param array<string, mixed> $existing The existing parameters
      * @return array<string, mixed> The given parameter array with this field's name and value(s) appended
+     * @throws Exception If the database mode has not been set
      */
     public function appendParameter(array $existing): array
     {
@@ -121,6 +122,33 @@ class Field
             : $fieldPath . ' ' . $this->op->toSQL() . $criteria;
     }
 
+    /**
+     * Set a qualifier for the field, returning the modified field
+     *
+     * @param string $qualifier The table qualifier to use for the field
+     * @return Field The field instance with the qualifier set
+     */
+    public function andQualifier(string $qualifier): Field
+    {
+        $this->qualifier = $qualifier;
+        return $this;
+    }
+
+    /**
+     * Create a new `Field` instance based on the given field, using the qualifier provided
+     *
+     * @param string $qualifier The table qualifier to use for the field
+     * @return callable<Field, Field> A new `Field` instance with the qualifier set
+     */
+    public static function withQualifier(string $qualifier): callable
+    {
+        return function (Field $field) use ($qualifier) {
+            return clone($field, [
+                "qualifier" => $qualifier
+            ]);
+        };
+    }
+
     /**
      * Create parameter names for an IN clause
      *

test_all.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 
 export PDO_DOC_PGSQL_HOST=localhost:8301
-PG_VERSIONS=('13' '14' '15' '16' 'latest')
+PG_VERSIONS=('14' '15' '16' '17' 'latest')
 
 for PG_VERSION in "${PG_VERSIONS[@]}"
 do

tests/Unit/FieldTest.php

@@ -192,6 +192,21 @@ describe('->toWhere()', function () {
     })->group('sqlite');
 });
 
+describe('->andQualifier()', function() {
+    test('adds a qualifier', function () {
+        expect(Field::equal('that', '82')->andQualifier('this'))->qualifier->toBe('this');
+    });
+});
+
+describe('::withQualifier()', function() {
+    test('adds a qualifier to a new instance', function () {
+        $field = Field::equal('that', '14');
+        $field2 = Field::withQualifier('this')($field);
+        expect($field)->qualifier->toBe('')
+            ->and($field2)->qualifier->toBe('this');
+    });
+});
+
 describe('::equal()', function () {
     test('creates Field w/o parameter', function () {
         $field = Field::equal('my_test', 9);