PHPLIB-1209: Add tutorial to show working with Codecs #1154

alcaeus · 2023-09-07T07:52:42Z

The tutorial uses the same classes and functionality we show in other BSON tutorials, namely the Person class to show serialisation (this is used to show the behaviour of Persistable and Serializable interfaces), and our example of storing a date as UTCDateTime with timezone information.

GromNaN

I think we need an example with a nested document person.city

docs/tutorial/codecs.txt

GromNaN · 2023-09-08T09:28:39Z

docs/tutorial/codecs.txt

+           return MongoDB\BSON\Document::fromPHP([
+               'street' => $value->street,
+               'postCode' => $value->postCode,
+               'city' => $value->city,
+               'country' => $value->country,
+           ]);


Would performance be better without an intermediate array?

Suggested change

return MongoDB\BSON\Document::fromPHP([

'street' => $value->street,

'postCode' => $value->postCode,

'city' => $value->city,

'country' => $value->country,

]);

$doc = new MongoDB\BSON\Document();

$doc->set('street', $value->street);

$doc->set('postCode, $value->postCode);

$doc->set('city', $value->city);

$doc->set('country', $value->country);

return $doc;

The BSON document class is currently read-only, so the only way to create one is through fromPHP or the other factory methods. The reason for this is that we only keep a bson_t* internally, which is essentially a byte stream of the BSON. In-place replacement only works for types with the same size, e.g. overwriting an int with another int. As soon as values grow or shrink in size, the BSON needs to be rewritten (i.e. create a new bson_t*, copy over everything except the property being changed, then write the changed property). Since the main motivation for adding the Document and PackedArray classes was to provide a way to access BSON data without decoding it to PHP objects, we refrained from adding a BSON writing mechanism. That said, there is PHPC-2172 which tracks creating an implementation of a BSON writer.

docs/tutorial/codecs.txt

GromNaN

LGTM.

docs/tutorial/codecs.txt

docs/tutorial.txt

docs/tutorial/codecs.txt

GromNaN · 2023-09-13T18:40:52Z

docs/examples/codecs/handling-data-types/DateTimeCodec.php

+         * 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 4 times (once for each


Thinking...

It's 8 times if you call decodeIfPossible as the decode calls canDecode.

Also, we don't know which document will be tested. It's not because this codec works for small documents that this function will not check huge ones.

That is correct. Inspecting large documents will be slow, but since we've removed libraries users are unlikely to run into such scenarios as they'd be using specific codecs for specific fields.

GromNaN · 2023-09-13T18:44:20Z

docs/examples/codecs/handling-data-types/DateTimeCodec.php

+    public function decode(mixed $value): DateTimeImmutable
+    {
+        if (! $this->canDecode($value)) {
+            throw UnsupportedValueException::invalidDecodableValue($value);


Did you propose to add a method to the trait that wraps this generic 3 lines?

Yes. Will add in a separate PR.

GromNaN · 2023-09-13T18:49:08Z

docs/examples/codecs/handling-data-types/PersonCodec.php

+
+        return new Person(
+            $value->get('name'),
+            $this->dateTimeCodec->decode($value->get('createdAt')),


When you get a nested BSON document, does it duplicates the data in memory or is it a reference to the parent data?

It duplicates the data in memory. Each Document and PackedArray instance is tied to its own bson_t* so we don't have to start refcounting the libmongoc BSON structures.

GromNaN · 2023-09-13T18:52:03Z

docs/examples/codecs/handling-documents/disabling-codec.php

@@ -0,0 +1,7 @@
+<?php
+
+// Returns a document using the default type map


If you set a typemap, does it disable the codec?

Ah, good point. Specifying an operation-level typeMap option also overrides the collection-level codec. I've added a sentence explaining this and updated the example to show both ways.

GromNaN · 2023-09-13T19:24:29Z

docs/tutorial/codecs.txt

+returned, an exception will be thrown.
+
+You can disable codec usage for a specific operation or use a different codec (e.g. to decode the result of an
+aggregation pipeline) by specifying the ``null`` for the ``codec`` option for any operation. This will override the


Suggested change

aggregation pipeline) by specifying the ``null`` for the ``codec`` option for any operation. This will override the

aggregation pipeline) by specifying ``null`` for the ``codec`` option for any operation. This will override the

docs/examples/codecs/handling-data-types/DateTimeCodec.php

docs/examples/codecs/handling-data-types/Person.php

docs/examples/codecs/handling-documents/using-codec.php

docs/tutorial/codecs.txt

jmikola · 2023-09-13T20:18:28Z

docs/tutorial/codecs.txt

+other methods (e.g. type maps), codecs allow for greater customization and handling of different data types. They allow
+separating the logic for BSON encoding and decoding from the domain classes, allowing to decode BSON into plain old PHP
+objects (POPOs).


Enjoy this gem I came across while googling for "POPOs": http://www.javaleaks.org/open-source/php/plain-old-php-object.html

You'll have an army of lawyers suing you for making POPOs.

Haha. Leaving this unresolved so that someone can eventually stumble upon this while cave diving into old pull requests.

docs/tutorial/codecs.txt

jmikola · 2023-09-13T20:26:29Z

docs/tutorial/codecs.txt

+handles a particular data type in any document. This can be achieved by implementing the ``MongoDB\Codec\Codec``
+interface.
+
+The following example defines a codec to store ``DateTimeInterface`` instances as BSON dates including the timezone:


Suggested change

The following example defines a codec to store ``DateTimeInterface`` instances as BSON dates including the timezone:

The following example defines a codec that stores ``DateTimeInterface`` instances as an embedded document containing a BSON date and accompanying timezone string. Those same embedded documents can then be translated back into a ``DateTimeInterface`` during BSON decoding.

This drops the colon but should explain the entire example you're about to present. I think it's worth describing the encode and decode steps in prose here, as the remainder of the section is pretty light on words.

docs/tutorial/custom-types.txt

We still exclude psalm from these examples to avoid littering the code with assertions and annotations

alcaeus requested a review from jmikola September 7, 2023 07:52

alcaeus self-assigned this Sep 7, 2023

GromNaN reviewed Sep 7, 2023

View reviewed changes

GromNaN mentioned this pull request Sep 7, 2023

PHPLIB-1220: Support codec option for GridFS buckets #1149

Merged

GromNaN reviewed Sep 8, 2023

View reviewed changes

alcaeus force-pushed the phplib-1209-codec-tutorial branch from aeec90d to 0037220 Compare September 11, 2023 06:50

GromNaN approved these changes Sep 11, 2023

View reviewed changes

docs/tutorial/codecs.txt Outdated Show resolved Hide resolved

alcaeus force-pushed the phplib-1209-codec-tutorial branch from 87094fe to 36f4c51 Compare September 11, 2023 08:50

GromNaN approved these changes Sep 11, 2023

View reviewed changes

jmikola reviewed Sep 11, 2023

View reviewed changes

alcaeus force-pushed the phplib-1209-codec-tutorial branch from 36f4c51 to d193e7b Compare September 12, 2023 11:13

alcaeus requested review from GromNaN and jmikola September 13, 2023 08:40

alcaeus force-pushed the phplib-1209-codec-tutorial branch from 2c7ffb4 to 7123d47 Compare September 13, 2023 08:41

GromNaN reviewed Sep 13, 2023

View reviewed changes

jmikola reviewed Sep 13, 2023

View reviewed changes

alcaeus added 14 commits September 14, 2023 08:44

PHPLIB-1209: Add tutorial to show working with Codecs

1beec47

Fix code review issues

6956785

Add section on handling embedded documents

f005bc6

Handle code review

ecd83ee

Add example on how to disable codec

50ee3b8

Address code review

028e7d4

Add note linking to codec tutorial in custom-types

d0714dc

Move encryption examples to subfolder

b947b36

Use literalinclude for examples in docs

ae9f4eb

Remove library sections

7228b88

Reformat disabling codec examples

b7aee6e

Refactor UTCDateTimeCodec example

60ae286

Fix phpcs in codec examples

b8a0fbc

Add psalm template annotations for codec examples

c24e39b

We still exclude psalm from these examples to avoid littering the code with assertions and annotations

alcaeus added 3 commits September 14, 2023 08:44

Link to data type section in custom types tutorial

d639a19

Explain type map overriding codecs

04ca6f7

Simplify block comment

e1f63ed

alcaeus force-pushed the phplib-1209-codec-tutorial branch from 7123d47 to e1f63ed Compare September 14, 2023 06:44

Fix code review issues

50a8be2

alcaeus requested a review from jmikola September 14, 2023 07:05

jmikola approved these changes Sep 15, 2023

View reviewed changes

alcaeus merged commit 9fd7457 into mongodb:master Sep 15, 2023

alcaeus deleted the phplib-1209-codec-tutorial branch September 15, 2023 08:57

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

PHPLIB-1209: Add tutorial to show working with Codecs #1154

PHPLIB-1209: Add tutorial to show working with Codecs #1154

alcaeus commented Sep 7, 2023

GromNaN left a comment

GromNaN Sep 8, 2023

alcaeus Sep 8, 2023

GromNaN left a comment

GromNaN Sep 13, 2023

alcaeus Sep 14, 2023

GromNaN Sep 13, 2023

alcaeus Sep 14, 2023

GromNaN Sep 13, 2023

alcaeus Sep 14, 2023

GromNaN Sep 13, 2023

alcaeus Sep 14, 2023

GromNaN Sep 13, 2023

jmikola Sep 13, 2023

GromNaN Sep 13, 2023

alcaeus Sep 14, 2023

jmikola Sep 13, 2023

-           return MongoDB\BSON\Document::fromPHP([
-               'street' => $value->street,
-               'postCode' => $value->postCode,
-               'city' => $value->city,
-               'country' => $value->country,
-           ]);
+           $doc = new MongoDB\BSON\Document();
+           $doc->set('street', $value->street);
+           $doc->set('postCode, $value->postCode);
+           $doc->set('city', $value->city);
+           $doc->set('country', $value->country);
+           return $doc;

		@@ -0,0 +1,7 @@
		<?php

		// Returns a document using the default type map

	aggregation pipeline) by specifying the ``null`` for the ``codec`` option for any operation. This will override the
	aggregation pipeline) by specifying ``null`` for the ``codec`` option for any operation. This will override the

	The following example defines a codec to store ``DateTimeInterface`` instances as BSON dates including the timezone:
	The following example defines a codec that stores ``DateTimeInterface`` instances as an embedded document containing a BSON date and accompanying timezone string. Those same embedded documents can then be translated back into a ``DateTimeInterface`` during BSON decoding.

PHPLIB-1209: Add tutorial to show working with Codecs #1154

PHPLIB-1209: Add tutorial to show working with Codecs #1154

Conversation

alcaeus commented Sep 7, 2023

GromNaN left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

GromNaN left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment