Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:128646
Feedback-ID: ifab94697:Fastmail
Precedence: list
MIME-Version: 1.0
Date: Sat, 06 Sep 2025 02:47:35 +0200
To: internals@lists.php.net
Message-ID: <366fba57-cbef-4201-9b72-dbafcec0c521@app.fastmail.com>
In-Reply-To: <7B9311D1-E433-4DBF-A85D-A7DEA94FCC4C@rwec.co.uk>
References: <9c875e83-ddc8-4c5c-a368-747bef46e4a2@app.fastmail.com>
 <F60093E2-9310-4E6D-B1CA-C4B98D60B097@mabe.berlin>
 <25e79d21-7b7f-4d7f-b5cb-1e9cfd0aa657@varteg.nz>
 <b7e870eb-9012-4fff-bd28-6a4a817a9181@app.fastmail.com>
 <ee823501-40c5-455a-99b7-7a6c415ca1f4@app.fastmail.com>
 <7B9311D1-E433-4DBF-A85D-A7DEA94FCC4C@rwec.co.uk>
Subject: Re: [PHP-DEV] enum flag backed enum
Content-Type: multipart/alternative;
 boundary=46fb96a0f1ec4c6ab5af9f981134e8eb
From: rob@bottled.codes ("Rob Landers")

--46fb96a0f1ec4c6ab5af9f981134e8eb
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable



On Fri, Sep 5, 2025, at 22:01, Rowan Tommins [IMSoP] wrote:
> On 4 September 2025 15:50:08 BST, Rob Landers <rob@bottled.codes> wrot=
e:
> >I think this is a fair observation and a fair question; but I think i=
t is important not to have "magic". The power-of-two rule is to make it =
possible to work back how $enum->value =3D=3D=3D 15 (0x1111) even if you=
 are completely new to the language. If you just use some magical cardin=
al order, it is impossible to reserve ranges, handle communications with=
 external systems, etc.
>=20
>=20
> A set does not need elements to have a defined order, only a defined i=
dentity; that is available on any enum, even one with no backing at all.=
 That pure set could be serialised in various ways, based on the availab=
le serialisations of its elements (comma-separated list, integer bitmask=
, binary string bitmask, etc). That's the strongly typed model.
>=20
> The weakly typed model is to keep the values permanently in their seri=
alised form, and manipulate that directly. That is, you have a set of in=
tegers for the flags, and construct a new integer for the set of flags. =
That has the advantage of being simple and efficient, at the cost of saf=
ety and easy tool affordance.
>=20
> What you're suggesting sounds like somewhere between the two: the indi=
vidual flags are of a specific type, rather than raw integers, but the s=
et itself is just an integer composed of their "backing values". The big=
 downside I see is that you can't natively label a parameter or return v=
alue as being a "set of flags from this enum". You could probably make a=
 docblock type annotation work with an external static analyser, but in =
that case, you might as well use that tool to enforce the powers of 2 on=
 your enum or Plain Old Constants.

Interesting... but we don=E2=80=99t really have a way to say that a para=
meter or return value must satisfy *any* constraints except that it be o=
f a certain type. Hmmm, I guess we have "true" and "false" as values tha=
t can be returned/accepted by functions =E2=80=94 but I think they=E2=80=
=99re the only ones.

A form of generics could solve *some* of this... an enum is a set, so wh=
at we really want to say is: "map this set of PHP identifiers to this ot=
her set of values". Which we already have via backed enums. What we lack=
 is some set of operators to allow us to select subsets of the set and r=
epresent them. I was thinking of bitwise operators, because it seems the=
 most natural. In fact, my extension approach was to just inject some op=
erators on the class entry and call it a day.

But with your response and my implementation that needed to deal with st=
ring-backed enums... The bitwise operators with enums would be a bit wei=
rd. Because | is a type union and saying Foo::PrettyPrint | Foo::ThrowOn=
Error also kind of a union, but really, we=E2=80=99re constructing a new=
 subset. So, maybe | isn=E2=80=99t the best operator. Then, when you wou=
ld check, you use & (Foo::PrettyPrint & $val =3D=3D=3D 0)? It is not tha=
t elegant looking... idiomatic in languages like C, sure, but PHP ... no=
t so much.

If I were to step back, I=E2=80=99d probably end up with something like =
this:

// use array-ish syntax to say that it is a subset of Foo
$foo =3D Foo::[PrettyPrint, ThrowOnError];

// have a function accept any Foo but returns only specific subsets of F=
oo.
function doFoo(Foo $anyFoo): Foo::[PrettyPrint, ThrowOnError]|Foo::[Pret=
tyPrint]|null

// check if a value of Foo intersects with another set of Foo
return enum_intersects($anyFoo, Foo::[PrettyPrint]);

In this case, backing values don=E2=80=99t matter at all. Serialization =
would still be an issue, but then again, it is already.

>=20
> Indeed, enforcing "this integer must be a power of 2" is not really an=
ything to do with enums, it would be useful on *any* type declaration.
>=20
>=20
> Personally, I find the concept of enum cases having a single backing v=
alue unnecessarily limiting, and would much prefer Java-style case prope=
rties.
>=20
> enum FooFlag: object {
>     case None(0, '');
>     case ThrowOnError(0b1, 'T');
>     // etc.
>     case PrettyPrint(0b1000, 'P');
>     // etc.
>=20
>     public function __construct(public int $flagForBinaryApi, public s=
tring $flagForTextApi){}
> }
>=20
> FooFlag::ThrowOnError->flagForBinaryApi; // 0b1
> FooFlag:: PrettyPrint->flagForTextApi; // 'P'
>=20
>=20
> Ideally we would declare that $flagForBinaryApi must be a power of 2, =
and that $flagForTextApi must be a single character, using some general-=
purpose feature of the type system.=20
>=20
> The only thing that might be enum-specific is a way to say whether the=
 values of a property must be unique (something we don't currently have =
with single-value backed enums).
>=20
>=20
> Then the ideal would be an EnumSet customised to work with any propert=
ies or methods it wanted:
>=20
> $foo =3D FooFlag::ThrowOnError | FooFlag::PrettyPrint;
> $foo->serialiseForBinaryApi(); // 0b1001
> $foo->serialiseForTextApi(); // 'TP'
>=20
>=20
> Rowan Tommins
> [IMSoP]
>=20

=E2=80=94 Rob
--46fb96a0f1ec4c6ab5af9f981134e8eb
Content-Type: text/html; charset=utf-8
Content-Transfer-Encoding: quoted-printable

<!DOCTYPE html><html><head><title></title></head><body><div><br></div><d=
iv><br></div><div>On Fri, Sep 5, 2025, at 22:01, Rowan Tommins [IMSoP] w=
rote:</div><blockquote type=3D"cite" id=3D"qt" style=3D""><div>On 4 Sept=
ember 2025 15:50:08 BST, Rob Landers &lt;<a href=3D"mailto:rob@bottled.c=
odes">rob@bottled.codes</a>&gt; wrote:</div><div>&gt;I think this is a f=
air observation and a fair question; but I think it is important not to =
have "magic". The power-of-two rule is to make it possible to work back =
how $enum-&gt;value =3D=3D=3D 15 (0x1111) even if you are completely new=
 to the language. If you just use some magical cardinal order, it is imp=
ossible to reserve ranges, handle communications with external systems, =
etc.</div><div><br></div><div><br></div><div>A set does not need element=
s to have a defined order, only a defined identity; that is available on=
 any enum, even one with no backing at all. That pure set could be seria=
lised in various ways, based on the available serialisations of its elem=
ents (comma-separated list, integer bitmask, binary string bitmask, etc)=
. That's the strongly typed model.</div><div><br></div><div>The weakly t=
yped model is to keep the values permanently in their serialised form, a=
nd manipulate that directly. That is, you have a set of integers for the=
 flags, and construct a new integer for the set of flags. That has the a=
dvantage of being simple and efficient, at the cost of safety and easy t=
ool affordance.</div><div><br></div><div>What you're suggesting sounds l=
ike somewhere between the two: the individual flags are of a specific ty=
pe, rather than raw integers, but the set itself is just an integer comp=
osed of their "backing values". The big downside I see is that you can't=
 natively label a parameter or return value as being a "set of flags fro=
m this enum". You could probably make a docblock type annotation work wi=
th an external static analyser, but in that case, you might as well use =
that tool to enforce the powers of 2 on your enum or Plain Old Constants=
.</div></blockquote><div><br></div><div>Interesting... but we don=E2=80=99=
t really have a way to say that a parameter or return value must satisfy=
&nbsp;<b>any</b>&nbsp;constraints except that it be of a certain type. H=
mmm, I guess we have "true" and "false" as values that can be returned/a=
ccepted by functions =E2=80=94 but I think they=E2=80=99re the only ones=
.</div><div><br></div><div>A form of generics could solve&nbsp;<i>some</=
i> of this... an enum is a set, so what we really want to say is: "map t=
his set of PHP identifiers to this other set of values". Which we alread=
y have via backed enums. What we lack is some set of operators to allow =
us to select subsets of the set and represent them. I was thinking of bi=
twise operators, because it seems the most natural. In fact, my extensio=
n approach was to just inject some operators on the class entry and call=
 it a day.</div><div><br></div><div>But with your response and my implem=
entation that needed to deal with string-backed enums... The bitwise ope=
rators with enums would be a bit weird. Because | is a type union and sa=
ying Foo::PrettyPrint | Foo::ThrowOnError also kind of a union, but real=
ly, we=E2=80=99re constructing a new subset. So, maybe | isn=E2=80=99t t=
he best operator. Then, when you would check, you use &amp; (Foo::Pretty=
Print &amp; $val =3D=3D=3D 0)? It is not that elegant looking... idiomat=
ic in languages like C, sure, but PHP ... not so much.</div><div><br></d=
iv><div>If I were to step back, I=E2=80=99d probably end up with somethi=
ng like this:</div><div><br></div><div>// use array-ish syntax to say th=
at it is a subset of Foo</div><div>$foo =3D Foo::[PrettyPrint, ThrowOnEr=
ror];</div><div><br></div><div>// have a function accept any Foo but ret=
urns only specific subsets of Foo.</div><div>function doFoo(Foo $anyFoo)=
: Foo::[PrettyPrint, ThrowOnError]|Foo::[PrettyPrint]|null</div><div><br=
></div><div>// check if a value of Foo intersects with another set of Fo=
o</div><div>return enum_intersects($anyFoo, Foo::[PrettyPrint]);</div><d=
iv><br></div><div>In this case, backing values don=E2=80=99t matter at a=
ll. Serialization would still be an issue, but then again, it is already=
.</div><div><br></div><blockquote type=3D"cite" id=3D"qt" style=3D""><di=
v><br></div><div>Indeed, enforcing "this integer must be a power of 2" i=
s not really anything to do with enums, it would be useful on *any* type=
 declaration.</div><div><br></div><div><br></div><div>Personally, I find=
 the concept of enum cases having a single backing value unnecessarily l=
imiting, and would much prefer Java-style case properties.</div><div><br=
></div><div>enum FooFlag: object {</div><div>&nbsp;&nbsp;&nbsp; case Non=
e(0, '');</div><div>&nbsp;&nbsp;&nbsp; case ThrowOnError(0b1, 'T');</div=
><div>&nbsp;&nbsp;&nbsp; // etc.</div><div>&nbsp;&nbsp;&nbsp; case Prett=
yPrint(0b1000, 'P');</div><div>&nbsp;&nbsp;&nbsp; // etc.</div><div><br>=
</div><div>&nbsp;&nbsp;&nbsp; public function __construct(public int $fl=
agForBinaryApi, public string $flagForTextApi){}</div><div>}</div><div><=
br></div><div>FooFlag::ThrowOnError-&gt;flagForBinaryApi; // 0b1</div><d=
iv>FooFlag:: PrettyPrint-&gt;flagForTextApi; // 'P'</div><div><br></div>=
<div><br></div><div>Ideally we would declare that $flagForBinaryApi must=
 be a power of 2, and that $flagForTextApi must be a single character, u=
sing some general-purpose feature of the type system.&nbsp;</div><div><b=
r></div><div>The only thing that might be enum-specific is a way to say =
whether the values of a property must be unique (something we don't curr=
ently have with single-value backed enums).</div><div><br></div><div><br=
></div><div>Then the ideal would be an EnumSet customised to work with a=
ny properties or methods it wanted:</div><div><br></div><div>$foo =3D Fo=
oFlag::ThrowOnError | FooFlag::PrettyPrint;</div><div>$foo-&gt;serialise=
ForBinaryApi(); // 0b1001</div><div>$foo-&gt;serialiseForTextApi(); // '=
TP'</div><div><br></div><div><br></div><div>Rowan Tommins</div><div>[IMS=
oP]</div><div><br></div></blockquote><div><br></div><div id=3D"sig121229=
152">=E2=80=94 Rob</div></body></html>
--46fb96a0f1ec4c6ab5af9f981134e8eb--