FIG-hosted enumerations

[Larry Garfield]

Greetings, FIGlets. (What does one call a FIG-involved person, anyway? FIGlet? FIGment?)

As you may be aware, PHP 8.1 is going to include support for Enumerations.

https://wiki.php.net/rfc/enumerations

I believe it would be beneficial for some common industrial enumerated types to have a common library, rather than everyone making their own. The first examples that jump out at me are HTTP status codes and methods, which I have implemented here:

https://github.com/Crell/EnumTools

There are likely others, but I haven't come up with them yet. (Obviously this code won't run on any released PHP version yet, but I'm pretty sure the syntax is right...)

I am fine hosting these myself, but it occurs to me that they may be of more value if hosted by a more prominent organization, such as FIG. Of course, it's not really a spec; a PSR for these wouldn't make any sense. It's more akin to the Util libraries that we maintain for various PSRs, but without an associated PSR.

How do folks feel about FIG hosting such an enum collection? We could make it one package or several, depending on how we decide to break it up. If FIG is OK hosting it I am happy to dump the enums I already build into whatever package FIG wants to use for them.

Discuss.

--
Larry Garfield
la...@garfieldtech.com

[Jordi Boggiano]

On 22/05/2021 02:51, Larry Garfield wrote:
> I believe it would be beneficial for some common industrial enumerated types to have a common library, rather than everyone making their own. The first examples that jump out at me are HTTP status codes and methods, which I have implemented here:
>

Definitely would be nice to allow type-hinting standard types in
libraries instead of having every lib shipping lib-specific types.

It would make typing a bit more portable if I can take a function from
one library returning an http status code and plug it into another lib
expecting a status code and type definitions would all uses
Psr\Enum\HttpStatus or something and it would all just work 👍🏻

The one problem is it risks becoming a catch-all mess of everyone's
dreams and wishes, so it's probably only suitable for lists of things
which are already standardized either by the FIG (like.. log levels
could be added as an enum directly in the psr/log package?) or by other
standard bodies (like your http examples).

Best,
Jordi

--

Jordi Boggiano
@seldaek - https://seld.be

[Matthew Weier O'Phinney]

You're aware we have constants defined already in the fig/http-message-util library, right? Couldn't we just add an enum later, once 8.1 is ready?

(I'd argue that, in general, the *-util packages are a good place for these.)

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/9fa79e25-5755-4f3f-9be9-3acc2ee67c6a%40www.fastmail.com.

--

Matthew Weier O'Phinney
mweiero...@gmail.com
https://mwop.net/

he/him

[Larry Garfield]

On Mon, May 24, 2021, at 10:57 AM, Matthew Weier O'Phinney wrote:
> You're aware we have constants defined already in the
> fig/http-message-util library, right? Couldn't we just add an enum
> later, once 8.1 is ready?
>
> (I'd argue that, in general, the *-util packages are a good place for these.)

I am unsurprised to learn it. :-)

For HTTP-related enums, that may be a good place to put it. However, making them their own package may be helpful for those not already using PSR-7. (Or, maybe we do want to put it in that package to encourage people to use PSR-7? Interesting question.) The current PSRs (naturally) don't use any enums themselves, either.

There's likely other enums that it makes sense to have a single definition of, but don't fit neatly into a single existing PSR/util package.

--
Larry Garfield
la...@garfieldtech.com

[Michael C]

I echo Jordi's thoughts and think doing enums once for easy, common and uncontroversial enum sets makes sense but would steer away from anything that could be hard to define a finite set for. We would also need to consider a policy for changes to the set I think (is adding new element considered a BC break, do we want to support doing so but only in major versions [semver] etc.).

Personally I'd lean towards having a separate package just for enums, but perhaps bundling all the FIG enums into that one package. I don't think bringing along PSR-7 is really necessary and can imagine plenty of people and ecosystems that don't use PSR-7 using this enum set.

One thing I would note - this is probably relatively time-sensitive, in that we probably want to get something out before there are already 14 competing standards for us to add a 15th.

Many thanks,

Michael

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/b78ce3af-6a01-43fe-93af-83900665358b%40www.fastmail.com.

[Alexandru Pătrănescu]

On Mon, May 24, 2021 at 10:25 PM Michael C <m...@michaelcullum.com> wrote:

I echo Jordi's thoughts and think doing enums once for easy, common and uncontroversial enum sets makes sense but would steer away from anything that could be hard to define a finite set for. We would also need to consider a policy for changes to the set I think (is adding new element considered a BC break, do we want to support doing so but only in major versions [semver] etc.).

When I'm thinking about enums, I also think it's important to always be aware of having it as a finite set. Otherwise, the BC breaks of adding or removing a case will pop up often.

 

Personally I'd lean towards having a separate package just for enums, but perhaps bundling all the FIG enums into that one package. I don't think bringing along PSR-7 is really necessary and can imagine plenty of people and ecosystems that don't use PSR-7 using this enum set.

One thing I would note - this is probably relatively time-sensitive, in that we probably want to get something out before there are already 14 competing standards for us to add a 15th.

Many thanks,

Michael

On Mon, 24 May 2021, 18:06 Larry Garfield, <la...@garfieldtech.com> wrote:

On Mon, May 24, 2021, at 10:57 AM, Matthew Weier O'Phinney wrote:
> You're aware we have constants defined already in the
> fig/http-message-util library, right? Couldn't we just add an enum
> later, once 8.1 is ready?
>
> (I'd argue that, in general, the *-util packages are a good place for these.)

I am unsurprised to learn it. :-)

For HTTP-related enums, that may be a good place to put it.  However, making them their own package may be helpful for those not already using PSR-7.  (Or, maybe we do want to put it in that package to encourage people to use PSR-7?  Interesting question.)  The current PSRs (naturally) don't use any enums themselves, either.

I think "naturally" here might have other meanings as well.

A http request method enum will not be complete for usage in all places because in fact a http method is just a string as I should be able to send BLABLABLA in my http client if I want to. Or receive it on my server. And because of that, they cannot be easily used as types in PSR-7, PSR-18. I think using string constants is fine here.

Same thing for http response code; eventually Cloudflare will return a 524 timeout response code that is not included. Well, for this actually it can be defined as an integer between 100 and 599 but that's not practical.

So only StatusCategory enum looks good from my point of view.

 

There's likely other enums that it makes sense to have a single definition of, but don't fit neatly into a single existing PSR/util package.

--
  Larry Garfield
  la...@garfieldtech.com

Regards,

Alex 

[Paul Dragoonis]

On Sat, May 22, 2021 at 1:51 AM Larry Garfield <la...@garfieldtech.com> wrote:

Greetings, FIGlets.  (What does one call a FIG-involved person, anyway?  FIGlet?  FIGment?)

We're definitely FIGlet's ;-) Spiderfig, spiderdig, codes whatever a spiderfig codes.

 

As you may be aware, PHP 8.1 is going to include support for Enumerations. 

https://wiki.php.net/rfc/enumerations

I believe it would be beneficial for some common industrial enumerated types to have a common library, rather than everyone making their own.  The first examples that jump out at me are HTTP status codes and methods, which I have implemented here:

https://github.com/Crell/EnumTools

There are likely others, but I haven't come up with them yet.  (Obviously this code won't run on any released PHP version yet, but I'm pretty sure the syntax is right...)

I am fine hosting these myself, but it occurs to me that they may be of more value if hosted by a more prominent organization, such as FIG.  Of course, it's not really a spec; a PSR for these wouldn't make any sense.  It's more akin to the Util libraries that we maintain for various PSRs, but without an associated PSR.

How do folks feel about FIG hosting such an enum collection?  We could make it one package or several, depending on how we decide to break it up.  If FIG is OK hosting it I am happy to dump the enums I already build into whatever package FIG wants to use for them.

I think we need to gracefully add Enum's into our existing packages (HTTP, Cache ..etc) and then also see how PHP8.x enum's are being used in the wild.

Over time we'll be able to spot the patterns and then begin reacting accordingly.

I think we'd be jumping the gun if we tried to go this now. Let's see how the dust settles in the PHP community, and then we make our move.

I think a generic enum package is fine, but to be honest having it contextualized inside a particular package (a bounded context) is a stronger move.

 

Discuss.

--
  Larry Garfield
  la...@garfieldtech.com

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/9fa79e25-5755-4f3f-9be9-3acc2ee67c6a%40www.fastmail.com.

[Navarr Barnier]

Agreed with Paul.

I think it would also behoove the group to be careful about what is enumerated.  HTTP Status codes were the first one to come up, as Larry has made a pretty neat library for those - however, I think in general HTTP status codes are already pretty portable as numbers.  Turning them into Enumerations would make them less portable and, in my opinion, would go against the goal of FIG.

If enumerations were to be suggested for FIG, I would suggest things that are more likely to be represented different ways by different libraries.  Items such as Months or Days of the week or basic colors.

[Matthew Weier O'Phinney]

On Mon, May 24, 2021 at 12:06 PM Larry Garfield <la...@garfieldtech.com> wrote:

On Mon, May 24, 2021, at 10:57 AM, Matthew Weier O'Phinney wrote:
> You're aware we have constants defined already in the
> fig/http-message-util library, right? Couldn't we just add an enum
> later, once 8.1 is ready?
>
> (I'd argue that, in general, the *-util packages are a good place for these.)

I am unsurprised to learn it. :-)

For HTTP-related enums, that may be a good place to put it.  However, making them their own package may be helpful for those not already using PSR-7.  (Or, maybe we do want to put it in that package to encourage people to use PSR-7?  Interesting question.)

Currently, http-message-util only has a requirement on PHP, not on psr/http-message. It's defining interfaces with constants for status codes and request methods only.

That's not to say it would NEVER depend on psr/http-message, but the idea behind it has been primarily to provide a vendor-neutral package for common HTTP-related concerns, which is why I suggested it here.

I see good arguments for having them separate as well. It's hard for me to gauge which direction would have greatest impact.

 

The current PSRs (naturally) don't use any enums themselves, either.

There's likely other enums that it makes sense to have a single definition of, but don't fit neatly into a single existing PSR/util package.

--
  Larry Garfield
  la...@garfieldtech.com

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/b78ce3af-6a01-43fe-93af-83900665358b%40www.fastmail.com.

[Matthew Weier O'Phinney]

On Mon, May 24, 2021 at 3:41 PM Alexandru Pătrănescu <drea...@gmail.com> wrote:

On Mon, May 24, 2021 at 10:25 PM Michael C <m...@michaelcullum.com> wrote:

On Mon, 24 May 2021, 18:06 Larry Garfield, <la...@garfieldtech.com> wrote:

On Mon, May 24, 2021, at 10:57 AM, Matthew Weier O'Phinney wrote:

<snip>

 

A http request method enum will not be complete for usage in all places because in fact a http method is just a string as I should be able to send BLABLABLA in my http client if I want to. Or receive it on my server. And because of that, they cannot be easily used as types in PSR-7, PSR-18. I think using string constants is fine here.

Same thing for http response code; eventually Cloudflare will return a 524 timeout response code that is not included. Well, for this actually it can be defined as an integer between 100 and 599 but that's not practical.

So only StatusCategory enum looks good from my point of view.

When it comes to HTTP status codes and request methods, the IETF has left them deliberately open-ended. That said:

- The specification allows for flexibility to add more within certain parameters, and

- They have a process for petitioning to make new additions canonical.

What the current http-message-util does is codify the ones that are already canonical. The primary reason to use them is not so much to consume and validate an HTTP message, but to _create_ one. For example, with HTTP clients, having the ability to select an enum for a given request method helps prevent potential typos. If you are choosing to use a non-canonical request method, you will need to deliberately steer clear from using the enum, which in turn should trigger a bit of extra review on either your part or your team's part. Similarly, for status codes, these are generally of interest when creating the response. The way we've defined the constants is to use their semantic name as the constant name, which in turn makes it easier to indicate _intent_ as you create the response.

Yes, these _can_ also be used for validations, or if you want to see if a request method or status code matches a known canonical value, but, as noted, you should always be able to fall back to either range checks or a regexp.

As such, I'd argue that having enums is a _starting point_ for message validation, and an important one, and a _requirement_ for users creating messages, with the understanding that they _can_ break out of the defined values as needed, again, as long as they provide values that fit in the standard ranges or ABNF.

 

 

There's likely other enums that it makes sense to have a single definition of, but don't fit neatly into a single existing PSR/util package.

--
  Larry Garfield
  la...@garfieldtech.com

Regards,

Alex 

--

You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CAAwdEzBQvW3SaJH8fvzjN5rsSuEB280e2iab_JEcJ-cbVoesJQ%40mail.gmail.com.

[Larry Garfield]

However, if you type a parameter or return value with an enum, then by definition you cannot pass an arbitrary int instead. You would be constrained to only allow values in that specific enum definition already.

I suppose you could allow Status|int, but then you have to always check which one it is and take different actions. I don't know if that's really an improvement.

I realize I may be arguing against myself now, but that's why I started the discussion. :-)

What about other common enums besides HTTP codes? Like, cardinal directions? There's only 4 of those, worldwide, and i don't expect any new ones to be added soon.

--Larry Garfield

[Alessandro Chitolina]

Hi everyone,

Apart from cardinal directions, some common enums could be

- Log levels (PSR-3 will need another update)

- Units of measurement: distance, area, time, temperature, ..

--

Alessandro Chitolina

[Woody Gilk]

Country codes for phone numbers as well, though this is subject to change and may not fit nicely into a static PSR. 

Sent from my iPhone

On Jun 26, 2021, at 9:19 AM, Alessandro Chitolina <alek...@gmail.com> wrote:



--

You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/b3c9d37d-f301-42fb-83b8-ca76d472e472n%40googlegroups.com.

[Michele Locati]

> - Units of measurement: distance, area, time, temperature, ..

That'd be a tough one. Here's the unit list defined by Unicode CLDR:

https://github.com/unicode-org/cldr/blob/release-39/common/main/en.xml#L5965-L6998

--

Michele

[Vincent de Lau]

Thinking about this the last couple of days, there were two topics that feel worth sharing:

1. Instead of specifying a specific enumeration in a PSR, a PSR could also describe a policy for how to maintain a specific enum package. For instance, the mentioned country codes for phone numbers PSR could specify that the implementation will be updated when the ITU E.164 registry changes. New enum entries will be added, old entries could be deprecated an removed after 2 years. The PSR could contain an initial implementation, especially if there are additional methods on the enum.

2. Given the mission of the FIG, should we try to limit ourselves to enums that have interop benefits? For instance, log levels and HTTP status codes seem like good candidates, but I can't readily see units of measurement (except potentially for time) being of direct use.

--

Vincent

[Larry Garfield]

Any Enum collection would have to operate via a "living working group" process, which we'd have to define first. (The same holds for any new coding standards document; the current PSR process is simply not feasible for that.)

I'd say overall, good targets for FIG enum collections would be:

* Fixed lists defined already by some other standards body that we're porting to PHP. (Eg, RFCs, W3C specs, etc.)
* Very common but logically closed lists. For instance, SortOrder::Asc vs SortOrder::Desc. Basically every DBAL is going to have that in it somewhere, and it's not like there's a 3rd option, so that tiny Enum likely makes sense.

The point that HTTP codes and methods are *technically* an open list, not a closed list, is valid, and makes those less practical. OTOH, with Union types one could allow for int|HttpCode as a type, and then fold down to int internally. However, I don't know if that actually provides significant benefit over just a collection of constants. (Which I suppose we could also produce if there was interest.)

--Larry Garfield

[Woody Gilk]

> On Jun 29, 2021, at 8:49 AM, Larry Garfield <la...@garfieldtech.com> wrote:

>
> On Tue, Jun 29, 2021, at 6:34 AM, Vincent de Lau wrote:
>> Thinking about this the last couple of days, there were two topics that
>> feel worth sharing:
>>
>> 1. Instead of specifying a specific enumeration in a PSR, a PSR could
>> also describe a policy for how to maintain a specific enum package. For
>> instance, the mentioned country codes for phone numbers PSR could
>> specify that the implementation will be updated when the ITU E.164
>> registry changes. New enum entries will be added, old entries could be
>> deprecated an removed after 2 years. The PSR could contain an initial
>> implementation, especially if there are additional methods on the enum.
>>
>> 2. Given the mission of the FIG, should we try to limit ourselves to
>> enums that have interop benefits? For instance, log levels and HTTP
>> status codes seem like good candidates, but I can't readily see units
>> of measurement (except potentially for time) being of direct use.
>
> Any Enum collection would have to operate via a "living working group" process, which we'd have to define first. (The same holds for any new coding standards document; the current PSR process is simply not feasible for that.)

It seems to me that figuring out a process for “living working group” is something that has come up before and is almost mandatory for doing Enums.

Maybe that should be the priority right now?

Woody

>
> I'd say overall, good targets for FIG enum collections would be:
>
> * Fixed lists defined already by some other standards body that we're porting to PHP. (Eg, RFCs, W3C specs, etc.)
> * Very common but logically closed lists. For instance, SortOrder::Asc vs SortOrder::Desc. Basically every DBAL is going to have that in it somewhere, and it's not like there's a 3rd option, so that tiny Enum likely makes sense.
>
> The point that HTTP codes and methods are *technically* an open list, not a closed list, is valid, and makes those less practical. OTOH, with Union types one could allow for int|HttpCode as a type, and then fold down to int internally. However, I don't know if that actually provides significant benefit over just a collection of constants. (Which I suppose we could also produce if there was interest.)
>
> --Larry Garfield
>

> --
> You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.

> To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/680199c0-1258-4f15-9eda-9bcf341d7cef%40www.fastmail.com.