Would performance be better without an intermediate array?

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.

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.

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

Yes. Will add in a separate PR.

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.

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.

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.

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.