Serialization of enums (including within sessions)

[DeveloperRob]

Description

In the Enums RFC then it was stated that Enums will have their own code when serialised. It then mentions:

On deserialization, if an enum and case cannot be found to match a serialized value a warning will be issued and false returned. (That is standard existing behavior for unserialize().)

While the above does hold for enums, this isn't the case for non-enum classes - instead then __PHP_Incomplete_Class is returned and importantly, behind the scenes the original class serialisation is maintained. This is actually the existing behaviour if the serialisation string is entirely invalid.

The pre-existing behaviour with sessions in particular, means you can have a 1st party class and a scalar (for instance), and a seperate file can load that session, change the scalar and (successfully) save the session without affecting the stored 1st party class.

In the implementation of enums however, it is implemented as per the RFC - on either an enum being stored in a session or serialised via serialize call; and then later deserialized, a warning is thrown and false is returned instead of an array. Even worse, if this is a session then the error 'Failed to decode session object. Session has been destroyed' is raised and the entire session file is destroyed (even if it no changes are made (and lazy_write is enabled) or read_and_close is used - so you wouldn't expect the script to modify the session.

There are some test links that show the behaviour (https://3v4l.org/mLGPa, https://3v4l.org/u130I), with the session-based one showing the behaviour reproduced here:

class X{}
session_start();
$_SESSION["x"] = new X();
$_SESSION["y"] = "5";
echo session_encode();
// Echoes:  x|O:1:"X":0:{}y|s:1:"5";

session_start();
session_decode('x|O:1:"X":0:{}y|s:1:"5";');
$_SESSION["y"] = 6;
echo session_encode();
die();
print_r($_SESSION);
/* Echos:
Array
(
    [x] => __PHP_Incomplete_Class Object
        (
            [__PHP_Incomplete_Class_Name] => X
        )

    [y] => 5
)
*/

enum Y{
    case Y;
}
session_start();
$_SESSION["x"] = Y::Y;
$_SESSION["y"] = "5";
echo session_encode();
// Echoes: x|E:3:"Y:Y";y|s:1:"5";

session_start();
session_decode('x|E:3:"Y:Y";y|s:1:"5";');
print_r($_SESSION);
/* Echoes: 
Warning: session_decode(): Class 'Y' not found in /in/1IEIF on line 36

Warning: session_decode(): Failed to decode session object. Session has been destroyed in /in/1IEIF on line 36
Array
(
)
*/

PHP Version

PHP 8.3.22 (cli) (built: Jun  6 2025 08:44:51) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.3.22, Copyright (c) Zend Technologies
    with Zend OPcache v8.3.22, Copyright (c), by Zend Technologies

Operating System

No response

[DeveloperRob]

Just as a follow up to this, the allowed_classes option on unserialize also has no effect:

<?php
class X{}
enum Y{
    case Y;
}
$x = serialize(["a" => Y::Y, "b" => new X()]);

print_r(\unserialize($x, ["allowed_classes" => false]));
/* Echoes:
Array
(
    [a] => Y Enum
        (
            [name] => Y
        )

    [b] => __PHP_Incomplete_Class Object
        (
            [__PHP_Incomplete_Class_Name] => X
        )

)
*/

[iluuu1994]

Hi @DeveloperRob. Given this works as intended and specified, I'm reclassifying from bug to feature. One possible issue with the __PHP_Incomplete_Class mechanism for enums is that it may lead to faulty comparisons. Consider:

User.php

enum Permissions {
    case User;
    case Admin;
}

class User {
    public Permissions $permissions;
}

login.php

require 'User.php';

session_start();
$user = new User();
$user->permissions = Permissions::User;
$_SESSION['user'] = $user;

admin.php

session_start(); // Start session before including User.php

require 'User.php';

$user = $_SESSION['user'];
$isAdmin = $user->permissions !== Permissions::User; // true?

This behavior seems worse than failing to decode the session. The decode will fail fast with an obvious message, rather than just breaking comparisons.

While the above does hold for enums, this isn't the case for non-enum classes - instead then __PHP_Incomplete_Class is returned and importantly, behind the scenes the original class serialisation is maintained. This is actually the existing behaviour if the serialisation string is entirely invalid.

I understand. I'm not sure how to provide a similar behavior without introducing the potential issue above. Maybe we may have a __PHP_Incomplete_Enum class that allows to be deserialized and serialized, but that throws for every comparison. We also can't know about the correct backing value, for obvious reasons.

/cc @Crell

[Crell]

This is the first possible use I've seen for __PHP_Incomplete_Class, so that's something. Though I'm not clear if it is supposed to round-trip successfully?

But still, I don't really understand the use case for "I want to deserialize a session and don't have the class/enum available to me." That's not a workflow I have ever seen.

I'd be open to @iluuu1994's suggestion of a new marker class, though I'm still not convinced it's a case worth supporting. The only compelling argument here is that the Enum RFC said it was consistent with what serialize() already did, but actually was wrong.

[iluuu1994]

I think what it referred to is that invalid serialization data would lead to a false return value. But it's been too long to remember exactly what we've discussed.

[DeveloperRob]

Evening all,

For reference, our production use case is we have some off-the-shelf systems and custom built systems running on the same domain. The custom built systems store some configuration in classes (in the session), and then some scalar values are shared for things like impression ids for a user. This worked without issue until we added some Enums in the configuration store.

@iluuu1994 - that makes sense on both the issue with using the preexisting class and the suggested new class. Without much internals knowledge then that sounds not too different due to the E used in the serialisation for Enums.

@Crell : to be clear, the classes are ignored by the off the shelf system. Hopefully the above explains it a bit better on the production usage.

I think what it referred to is that invalid serialization data would lead to a false return value. But it's been too long to remember exactly what we've discussed.

I haven't checked externals, but the RFC seems to have confused what happens with an invalid serialised string with an invalid (unknown) class definition.

Given this works as intended and specified, I'm reclassifying from bug to feature

No issues with this in the whole, the main parts that led me to file it as a bug was the RFC seeming to have a slightly incorrect assumption on existing behavior and that if it can't load the enum definition, the session is destroyed with no way of recovering it. The production breaking behaviour (when we introduced enums in a class) wasn't expected/obvious due to this as the serialisation aspect of sessions is usually transparent (and I can't think of another example that an unmodified session file won't be loaded; we initially thought it was a DevOps issue as the session file was empty for instance). However my less common use case won't have helped!