By andypost on
Change record status: 
Draft (View all draft change records)
Project: 
Drupal core
Introduced in branch: 
11.4.x
Introduced in version: 
11.4.0
Issue links: 
https://www.drupal.org/node/3548971
Description: 

Summary

Drupal core classes that implement custom serialization now use PHP's modern __serialize()/__unserialize() methods instead of the legacy __sleep()/__wakeup() pair.

Which classes are affected

  • DependencySerializationTrait (used by most services and plugins)
  • EntityBase and ConfigEntityBase
  • EntityDisplayBase
  • ContainerBuilder
  • Connection (database)
  • Query (database)
  • MemoryBackend (cache)
  • StorageComparer and ConfigImporter
  • Extension
  • TranslatableMarkup and PluralTranslatableMarkup
  • ViewExecutable
  • TermStorage

What changed

__sleep() returns property names and relies on PHP to serialize their values. __serialize() returns the full data array directly, giving explicit control over what gets serialized.

// Before
public function __sleep(): array {
  return ['propertyA', 'propertyB'];
}
public function __wakeup(): void {
  // restore from $this->propertyA, etc.
}

// After
public function __serialize(): array {
  return [
    'propertyA' => $this->propertyA,
    'propertyB' => $this->propertyB,
  ];
}
public function __unserialize(array $data): void {
  $this->propertyA = $data['propertyA'];
  $this->propertyB = $data['propertyB'];
}

Impact on contributed and custom code

If you override __sleep() or __wakeup()

Replace them with __serialize() and __unserialize(). PHP calls __serialize() in preference to __sleep() when both exist, so the old methods will no longer be invoked.

If you use DependencySerializationTrait

No changes needed — the trait handles serialization automatically. If you override __sleep()/__wakeup() in a class using the trait, update those overrides to __serialize()/__unserialize().

If you extend EntityBase or ConfigEntityBase

If you override __sleep(), rename to __serialize() and change the return value from property names to a key-value array. Call parent::__serialize() instead of parent::__sleep().

Why

  • __serialize()/__unserialize() is the recommended PHP serialization API since PHP 7.4
  • Avoids side effects — __sleep() often requires storing temporary state in instance properties just to pass data to __wakeup()
  • Clearer data flow — serialized data is an explicit array, not implicit property access
  • Better performance — no separate property-name resolution step
  • Setting readonly class properties in __wakeup() causes errors, which do not occur with __unserialize()
Impacts: 
Module developers