Simple use case for enum

[AlexanderAllen]

I think that enum is a pretty popular feature within the OpenAPI spec, and as such an initial release should support it, at least in the most basic form possible.

At the very least scalar types should be supported in the enum, and if it's not unreasonable on time also nullable enums.

[AlexanderAllen]

Removed from alpha, might be slightly bigger change that I want right now.
Will plan to ship for beta or RC.

[AlexanderAllen]

Some inspiration pasta while I work on this:

• https://swagger.io/docs/specification/data-models/enums/
• OpenAPI-Specification 2019-10-31-Clarify-Nullable.md
• Question: nullable and enum OAI/OpenAPI-Specification#1900

From @handrews comment at issue 1900 (Apr, 2021):

nullable: True in the presence of a type field, means that a JSON null is valid in addition to whatever type (plus constraints from other keywords including enum) the schema allows That's it. That's all OAS says.

So if type: string and nullable: true, then the PHP representation is ?string (a nullable string).

Expanding on that:

nullable: true
type: string
default: null

Would equal ?string foo = null, a nullable string with a default value of null. It's still a slightly different meaning when compared to nullable enums, but I think this captures the general vibes.

But maybe not so quick!

enum and default imply different effects in a OAS context.

And as it concerns to OAS you really need both nullable: true and null in the enum value:

type: string
# Representing a TYPE union of string and null, or nullable type.
nullable: true
# Also placing a constraint on the values allowed in the string, which includes a VALUE of null.
enum:
  - arroz
  - habichuelas
  # Sin carne, pfft?
  - null
# The default value of the type is "arroz"
default: arroz

Which in plain-English OAS would mean a string that allows a null along a list of values, with a default value of arroz?

Q: Cool beans. But do PHP enums allow nulls?

A: No (RFC). Only string and int are allowed in backed enums. A PHP enum case can be named "null", but that's not a literal null value, although it could be interpreted as such.

Illegal:

Technically legal, but against the spirit of the law (objection!) :

I'm fine with interpreting the type as a nullable something, the value however when it comes to enums is still sticky.

Without further internal or external interpretation of the enum (with enum method, or external match, for example), I don't see a way of interpolating the null value in a OAS enum into a PHP enum.

Interpreting that null enum value just feels like a philosophical can of worms, and not one that I'm keen to pop.

[AlexanderAllen]

The folks at myclabs/php-enum had some thoughts about this a long time ago, way before PHP enums were released...

[AlexanderAllen]

I just noted this in test/schema/keyword-enum-simple.yml:

enums cases are super interesting in that they are both a property
of their parent object, but they can also be interpreted as a
object by themselves. However unlike object references, enums lack
their own components/schemas entry.

And that is making for a super interesting/fun problem to entertain in the code (sarcasm: false).

With "regular" object schemas a property generator only needs to concern itself with chugging out property types, confident that referenced "class types (objects)" will eventually find themselves in the pipeline and be generated as well. Assuming referenced objects were declared in component/schemas, and with OAS enforcing references.

Enums and inline objects (without their own component/schema entry) then are kinda homeless and need a side action to define a stand-alone type for them.

A property generator is a good place to detect their existence, since you are checking each schema's properties. But a property generator returns properties, not object-like structures, and that's where this gets interesting.

For example, see this enum get intercepted by a property generator/enumerator/parser:

The generator is flawless in it's ability to generate both the stand-alone enumType instance and all the rest of the PanettoneEnum properties, which include the enum property itself!

However a prospective caller to a property generator expects only properties in returns, what's up with that random enum object hanging in the response?!

[AlexanderAllen]

Final resolution for the meme solo debate up top:

• I am not implementing null value case support for PHP enums in any way, shape, or form. At least not until a genius comes flying down from the Internets and suggest a solid way of doing so.
• Enum properties still have nullable type ?nullableEnumType $enumProp = null support. Meaning printed classes can still assign null to their enum properties. It's just the enum types themselves that don't have a null case.

[handrews]

FWIW, while I don't know PHP well at all, ?nullableEnumType as a way to model a JSON Schema "enum" that includes null sounds correct to me. The need to include null in JSON Schema "enum" lists is just an artifact of JSON Schema treating the "null" type like any other type, just one with a single value (null). This was muddled a bit by OpenAPI <3.1's "nullable" keyword breaking that model, which is otherwise consistent with regular JSON Schema's use of "null" as a value for "type". Languages with an alternate way of handling nulls don't need to translate JSON Schema's "enum" literally, whether null values are modeled with "nullable": true (OAS <3.1) or "type": "null" (OAS 3.1 / standard JSON Schema)