PHPC-2083: BSON handling for enum classes

[jmikola]

https://jira.mongodb.org/browse/PHPC-2083
https://jira.mongodb.org/browse/PHPC-2159

Proposed Behavior

Prohibit encoding of pure enums.

Encode BackedEnum instances as their backing value.

Ignore enums indicated in a “__pclass” field during BSON encoding (see PHPC-2159). While enums were previously never instantiatable from decoding BSON, a previous driver version might have been used to encode a Persistable enum to BSON. That is not a use case we want to support, but it would be inconsistent to raise an exception in this case.

Prohibit enums from implementing Persistable and Unserializable using the “interface_gets_implemented” object handler. We will remove previously introduced code in 1.15-dev that instantiated enums from case strings, and will not add behavior to instantiate BackedEnums from case values. Additionally, the bsonUnserialize() method was never relevant for enums, since they have no state.

Allow pure and backed enums to implement Serializable. Since enums are objects, they are permitted to implement Serializeable and that implementation will take precedence over standard BSON encoding rules (as it does with BSON type classes). Two thoughts on this:

• The previous behavior (i.e. encoding as a BSON document with a “name” and optional “value” fields) can be achieved by implementing Serializable and returning “(array) $this” from bsonSerialize().
• I certainly don’t want to encourage Serializable implementations for enums, but I also don't see a reason we need to prohibit it. It could technically provide a back door for users to round-trip non-backed enums. For example, the bsonUnserialize() method of an Unserializable class containing an enum could convert the pure/backed enum’s bsonSerialize() document representation back into an enum.

Note that I removed the following:

Allow a BackedEnum class to be specified in a type map field path without requiring it to implement Unserializable. Modify the int32, int64, and string visitor functions to consult the type map and conditionally instantiate a BackedEnum using the same logic as from() (i.e. error if the value is not an enum case). We can utilize the zend_enum_get_case_by_value() API in PHP 8.2+ for this (and backport it for PHP 8.1).

[alcaeus]

LGTM. We might circle back to add decoding to an enum case, but for now this is significantly more robust than the previous iteration 👍