mongodb · i80and · Aug 7, 2024 · Jun 22, 2018 · Jun 21, 2018 · Jun 22, 2018
diff --git a/.gitmodules b/.gitmodules
diff --git a/mongo-php-library b/mongo-php-library
diff --git a/source/.static/.mongodb b/source/.static/.mongodb
diff --git a/source/examples/aws-lambda/composer.json b/source/examples/aws-lambda/composer.json
@@ -0,0 +1,19 @@
+{
+    "name": "mongodb/bref-tutorial",
+    "type": "project",
+    "license": "MIT",
+    "repositories": [
+        {
+            "type": "path",
+            "url": "../../..",
+            "options": {
+                "symlink": false
+            }
+        }
+    ],
+    "require": {
+        "bref/bref": "^2.1",
+        "bref/extra-php-extensions": "^1.4",
+        "mongodb/mongodb": "@dev"
+    }
+}
diff --git a/source/examples/aws-lambda/index.php b/source/examples/aws-lambda/index.php
@@ -0,0 +1,31 @@
+<?php
+
+use MongoDB\Client;
+
+require_once __DIR__ . '/vendor/autoload.php';
+
+$uri = getenv('MONGODB_URI');
+
+try {
+    $client = new Client($uri);
+    $planets = $client
+        ->selectCollection('sample_guides', 'planets')
+        ->find([], ['sort' => ['orderFromSun' => 1]]);
+} catch (Throwable $exception) {
+    exit($exception->getMessage());
+}
+
+?>
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <title>MongoDB Planets</title>
+</head>
+<body>
+    <ul>
+        <?php foreach ($planets as $planet) : ?>
+            <li><?= $planet->name ?></li>
+        <?php endforeach ?>
+    </ul>
+</body>
+</html>
diff --git a/source/examples/aws-lambda/serverless.yml b/source/examples/aws-lambda/serverless.yml
@@ -0,0 +1,22 @@
+service: app
+
+provider:
+    name: aws
+    region: us-east-1
+    environment:
+        MONGODB_URI: ${env:MONGODB_URI}
+
+plugins:
+    - ./vendor/bref/bref
+    - ./vendor/bref/extra-php-extensions
+
+functions:
+    api:
+        handler: index.php
+        description: ''
+        runtime: php-83-fpm
+        timeout: 28 # in seconds (API Gateway has a timeout of 29 seconds)
+        events:
+            -   httpApi: '*'
+        layers:
+            - ${bref-extra:mongodb-php-83}
diff --git a/source/examples/codecs/handling-data-types/DateTimeCodec.php b/source/examples/codecs/handling-data-types/DateTimeCodec.php
@@ -0,0 +1,60 @@
+<?php
+
+use MongoDB\BSON\Document;
+use MongoDB\BSON\UTCDateTime;
+use MongoDB\Codec\Codec;
+use MongoDB\Codec\DecodeIfSupported;
+use MongoDB\Codec\EncodeIfSupported;
+use MongoDB\Exception\UnsupportedValueException;
+
+/** @template-implements Codec<Document, DateTimeImmutable> */
+final class DateTimeCodec implements Codec
+{
+    use DecodeIfSupported;
+    use EncodeIfSupported;
+
+    public function canDecode(mixed $value): bool
+    {
+        /* This codec inspects the BSON document to ensure it has the fields it expects, and that those fields are of
+         * the correct type. This is a robust approach to avoid decoding document that are not supported and would cause
+         * exceptions.
+         *
+         * For large documents, this can be inefficient as we're inspecting the entire document four times (once for
+         * each call to has() and get()). For small documents, this is not a problem.
+         */
+        return $value instanceof Document
+            && $value->has('utc') && $value->get('utc') instanceof UTCDateTime
+            && $value->has('tz') && is_string($value->get('tz'));
+    }
+
+    public function canEncode(mixed $value): bool
+    {
+        return $value instanceof DateTimeInterface;
+    }
+
+    public function decode(mixed $value): DateTimeImmutable
+    {
+        if (! $this->canDecode($value)) {
+            throw UnsupportedValueException::invalidDecodableValue($value);
+        }
+
+        $timeZone = new DateTimeZone($value->get('tz'));
+        $dateTime = $value->get('utc')
+            ->toDateTime()
+            ->setTimeZone($timeZone);
+
+        return DateTimeImmutable::createFromMutable($dateTime);
+    }
+
+    public function encode(mixed $value): Document
+    {
+        if (! $this->canEncode($value)) {
+            throw UnsupportedValueException::invalidEncodableValue($value);
+        }
+
+        return Document::fromPHP([
+            'utc' => new UTCDateTime($value),
+            'tz' => $value->getTimezone()->getName(),
+        ]);
+    }
+}
diff --git a/source/examples/codecs/handling-data-types/Person.php b/source/examples/codecs/handling-data-types/Person.php
@@ -0,0 +1,13 @@
+<?php
+
+use MongoDB\BSON\ObjectId;
+
+final class Person
+{
+    public function __construct(
+        public string $name,
+        public readonly DateTimeImmutable $createdAt = new DateTimeImmutable(),
+        public readonly ObjectId $id = new ObjectId(),
+    ) {
+    }
+}
diff --git a/source/examples/codecs/handling-data-types/PersonCodec.php b/source/examples/codecs/handling-data-types/PersonCodec.php
@@ -0,0 +1,55 @@
+<?php
+
+use MongoDB\BSON\Document;
+use MongoDB\Codec\DecodeIfSupported;
+use MongoDB\Codec\DocumentCodec;
+use MongoDB\Codec\EncodeIfSupported;
+use MongoDB\Exception\UnsupportedValueException;
+
+/** @template-implements DocumentCodec<Person> */
+final class PersonCodec implements DocumentCodec
+{
+    use DecodeIfSupported;
+    use EncodeIfSupported;
+
+    public function __construct(
+        private readonly DateTimeCodec $dateTimeCodec = new DateTimeCodec(),
+    ) {
+    }
+
+    public function canDecode(mixed $value): bool
+    {
+        return $value instanceof Document && $value->has('name');
+    }
+
+    public function canEncode(mixed $value): bool
+    {
+        return $value instanceof Person;
+    }
+
+    public function decode(mixed $value): Person
+    {
+        if (! $this->canDecode($value)) {
+            throw UnsupportedValueException::invalidDecodableValue($value);
+        }
+
+        return new Person(
+            $value->get('name'),
+            $this->dateTimeCodec->decode($value->get('createdAt')),
+            $value->get('_id'),
+        );
+    }
+
+    public function encode(mixed $value): Document
+    {
+        if (! $this->canEncode($value)) {
+            throw UnsupportedValueException::invalidEncodableValue($value);
+        }
+
+        return Document::fromPHP([
+            '_id' => $value->id,
+            'name' => $value->name,
+            'createdAt' => $this->dateTimeCodec->encode($value->createdAt),
+        ]);
+    }
+}
diff --git a/source/examples/codecs/handling-documents/Person.php b/source/examples/codecs/handling-documents/Person.php
@@ -0,0 +1,12 @@
+<?php
+
+use MongoDB\BSON\ObjectId;
+
+final class Person
+{
+    public function __construct(
+        public string $name,
+        public readonly ObjectId $id = new ObjectId(),
+    ) {
+    }
+}
diff --git a/source/examples/codecs/handling-documents/PersonCodec.php b/source/examples/codecs/handling-documents/PersonCodec.php
@@ -0,0 +1,49 @@
+<?php
+
+use MongoDB\BSON\Document;
+use MongoDB\Codec\DecodeIfSupported;
+use MongoDB\Codec\DocumentCodec;
+use MongoDB\Codec\EncodeIfSupported;
+use MongoDB\Exception\UnsupportedValueException;
+
+/** @template-implements DocumentCodec<Person> */
+final class PersonCodec implements DocumentCodec
+{
+    // These traits define commonly used functionality to avoid duplication
+    use DecodeIfSupported;
+    use EncodeIfSupported;
+
+    public function canDecode(mixed $value): bool
+    {
+        return $value instanceof Document && $value->has('name');
+    }
+
+    public function canEncode(mixed $value): bool
+    {
+        return $value instanceof Person;
+    }
+
+    public function decode(mixed $value): Person
+    {
+        if (! $this->canDecode($value)) {
+            throw UnsupportedValueException::invalidDecodableValue($value);
+        }
+
+        return new Person(
+            $value->get('name'),
+            $value->get('_id'),
+        );
+    }
+
+    public function encode(mixed $value): Document
+    {
+        if (! $this->canEncode($value)) {
+            throw UnsupportedValueException::invalidEncodableValue($value);
+        }
+
+        return Document::fromPHP([
+            '_id' => $value->id,
+            'name' => $value->name,
+        ]);
+    }
+}
diff --git a/source/examples/codecs/handling-documents/disabling-codec.php b/source/examples/codecs/handling-documents/disabling-codec.php
@@ -0,0 +1,7 @@
+<?php
+
+// Overrides the collection codec, falling back to the default type map
+$collection->aggregate($pipeline, ['codec' => null]);
+
+// Overrides the collection codec, using the specified type map
+$collection->findOne($filter, ['typeMap' => ['root' => 'stdClass']]);
diff --git a/source/examples/codecs/handling-documents/using-codec.php b/source/examples/codecs/handling-documents/using-codec.php
@@ -0,0 +1,13 @@
+<?php
+
+use MongoDB\Client;
+
+$client = new Client();
+$collection = $client->selectCollection('test', 'person', [
+    'codec' => new PersonCodec(),
+]);
+
+$person = new Person('Jane Doe');
+$collection->insertOne($person);
+
+$person = $collection->findOne();
diff --git a/source/examples/codecs/handling-embedded-documents/Address.php b/source/examples/codecs/handling-embedded-documents/Address.php
@@ -0,0 +1,12 @@
+<?php
+
+final readonly class Address
+{
+    public function __construct(
+        public string $street,
+        public string $postCode,
+        public string $city,
+        public string $country,
+    ) {
+    }
+}
diff --git a/source/examples/codecs/handling-embedded-documents/AddressCodec.php b/source/examples/codecs/handling-embedded-documents/AddressCodec.php
@@ -0,0 +1,56 @@
+<?php
+
+use MongoDB\BSON\Document;
+use MongoDB\Codec\DecodeIfSupported;
+use MongoDB\Codec\DocumentCodec;
+use MongoDB\Codec\EncodeIfSupported;
+use MongoDB\Exception\UnsupportedValueException;
+
+/** @template-implements DocumentCodec<Address> */
+final class AddressCodec implements DocumentCodec
+{
+    use DecodeIfSupported;
+    use EncodeIfSupported;
+
+    public function canDecode(mixed $value): bool
+    {
+        return $value instanceof Document
+            && $value->has('street')
+            && $value->has('postCode')
+            && $value->has('city')
+            && $value->has('country');
+    }
+
+    public function canEncode(mixed $value): bool
+    {
+        return $value instanceof Address;
+    }
+
+    public function decode(mixed $value): Address
+    {
+        if (! $this->canDecode($value)) {
+            throw UnsupportedValueException::invalidDecodableValue($value);
+        }
+
+        return new Address(
+            $value->get('street'),
+            $value->get('postCode'),
+            $value->get('city'),
+            $value->get('country'),
+        );
+    }
+
+    public function encode(mixed $value): Document
+    {
+        if (! $this->canEncode($value)) {
+            throw UnsupportedValueException::invalidEncodableValue($value);
+        }
+
+        return Document::fromPHP([
+            'street' => $value->street,
+            'postCode' => $value->postCode,
+            'city' => $value->city,
+            'country' => $value->country,
+        ]);
+    }
+}
diff --git a/source/examples/codecs/handling-embedded-documents/Person.php b/source/examples/codecs/handling-embedded-documents/Person.php
@@ -0,0 +1,14 @@
+<?php
+
+use MongoDB\BSON\ObjectId;
+
+final class Person
+{
+    public ?Address $address = null;
+
+    public function __construct(
+        public string $name,
+        public readonly ObjectId $id = new ObjectId()
+    ) {
+    }
+}