Refactoring for Serialization in Drupal 10: Solving the LogicException: The database connection is not serializable. This probably means you are serializing an object that has an indirect reference to the database connection.

By hari, 30 September, 2024

If you’ve encountered the following error in your Drupal 10 project:

LogicException: The database connection is not serializable. This probably means you are serializing an object that has an indirect reference to the database connection. Adjust your code so that is not necessary. Alternatively, look at DependencySerializationTrait as a temporary solution.

You're not alone. This error can be tricky, especially if your code involves services that have direct or indirect references to the database connection. In this blog, we’ll dive into why this error occurs, and how to refactor your code to prevent it from happening.

Understanding the Problem

The error arises because the database connection is an active resource that manages real-time communication with the database. Objects like these cannot be serialized (i.e., converted to a storable or transferable format) because they represent live resources. When you try to serialize objects that hold references to the database connection or other non-serializable services, you’ll see the LogicException.

In Drupal 10, this problem often occurs when you try to serialize service objects such as EntityTypeManagerInterface or DatabaseConnection as part of a larger object, such as when storing data in a session, queue, or cache.

Example Scenario

Let’s consider a typical use case where you’re working with an order in a custom service:

<?php

public function __construct(CurrencyFormatterInterface $currency_formatter, EntityTypeManagerInterface $entity_type_manager, $order_id = NULL, $debug = FALSE) {
  $this->currencyFormatter = $currency_formatter;
  $this->entityTypeManager = $entity_type_manager;
  $this->values = [];

  if (!empty($order_id)) {
    $this->order = $this->entityTypeManager->getStorage('commerce_order')->load($order_id);
  }
  $this->debug = $debug;
}

In this example, the EntityTypeManagerInterface and CurrencyFormatterInterface services are injected into the class to work with the order. However, if you try to serialize this object, you will encounter the LogicException because the services (currencyFormatter and entityTypeManager) have direct or indirect references to the database connection.

Refactoring the Code for Serialization

To avoid this issue, you need to refactor your code to serialize only the necessary data while ensuring that the non-serializable services are re-injected after deserialization. Here’s how we can do this.

Step 1: Serialize Only Plain Data

Modify your class so that only serializable data, such as the order_id and debug properties, are included in the serialized output. The service objects will be excluded from serialization.

<?php

class OrderService {
  private $currencyFormatter;
  private $entityTypeManager;
  private $orderId;
  private $values;
  private $debug;

  public function __construct(CurrencyFormatterInterface $currency_formatter, EntityTypeManagerInterface $entity_type_manager, $order_id = NULL, $debug = FALSE) {
    $this->currencyFormatter = $currency_formatter;
    $this->entityTypeManager = $entity_type_manager;
    $this->orderId = $order_id;
    $this->debug = $debug;
    $this->values = [];

    if (!empty($order_id)) {
      $this->order = $this->entityTypeManager->getStorage('commerce_order')->load($order_id);
    }
  }

  /**
   * Serialize only necessary data.
   */
  public function __serialize(): array {
    return [
      'order_id' => $this->orderId,
      'values' => $this->values,
      'debug' => $this->debug,
    ];
  }

  /**
   * Unserialize and restore data.
   */
  public function __unserialize(array $data): void {
    $this->orderId = $data['order_id'] ?? NULL;
    $this->values = $data['values'] ?? [];
    $this->debug = $data['debug'] ?? FALSE;
  }
}

Step 2: Re-inject Services after Deserialization

After deserialization, services like EntityTypeManagerInterface and CurrencyFormatterInterface must be manually re-injected into the object. Add a method to handle this:

<?php

public function injectServices(CurrencyFormatterInterface $currency_formatter, EntityTypeManagerInterface $entity_type_manager): void {
  $this->currencyFormatter = $currency_formatter;
  $this->entityTypeManager = $entity_type_manager;

  // Reload the order entity after services are re-injected
  if (!empty($this->orderId)) {
    $this->order = $this->entityTypeManager->getStorage('commerce_order')->load($this->orderId);
  }
}

Step 3: Usage Example

Now, when you serialize the object, only the order_id, values, and debug properties are stored:

<?php

$serializedData = serialize($orderService);

When you unserialize it, you can re-inject the necessary services like this:

<?php

$orderService = unserialize($serializedData);
$orderService->injectServices($currency_formatter, $entity_type_manager);

This approach ensures that the non-serializable services are injected after deserialization, avoiding the LogicException error.

Temporary Workaround: DependencySerializationTrait

As the error message suggests, there is a temporary solution you can apply by using the DependencySerializationTrait. This trait helps manage the serialization of objects with dependencies, though it’s a less flexible approach compared to manual injection.

If you are working within a Symfony-based system (such as Drupal), you can use the DependencySerializationTrait like this:

<?php

use Symfony\Component\DependencyInjection\DependencySerializationTrait;

class OrderService {
  use DependencySerializationTrait;

  private $currencyFormatter;
  private $entityTypeManager;
  private $orderId;
  private $debug;

  public function __construct(CurrencyFormatterInterface $currency_formatter, EntityTypeManagerInterface $entity_type_manager, $order_id = NULL, $debug = FALSE) {
    $this->currencyFormatter = $currency_formatter;
    $this->entityTypeManager = $entity_type_manager;
    $this->orderId = $order_id;
    $this->debug = $debug;
  }
}

The DependencySerializationTrait allows you to exclude service dependencies from serialization and inject them back when needed. However, this is more of a temporary patch, and refactoring the code with manual service injection is a more robust solution.

Conclusion

The LogicException related to serializing database connections or service objects in Drupal 10 can be easily resolved by refactoring your code to serialize only plain data. This allows you to avoid serializing complex service objects while maintaining flexibility and performance.

By following the steps outlined above, you can refactor your code to safely serialize and unserialize your objects without encountering the LogicException. The key takeaway is to keep service dependencies out of the serialized state and re-inject them after deserialization for a more maintainable and scalable solution.

Stay tuned for more Drupal tips, and feel free to share your experiences in handling complex object serialization in the comments below!