From 942b163057a59fee67613858980e12f597d4206d Mon Sep 17 00:00:00 2001
From: Graham Campbell <hello@gjcampbell.co.uk>
Date: Tue, 9 Jun 2026 23:26:41 +0100
Subject: [PATCH 1/2] Reject native PHP serialization of ServiceClient

---
 CHANGELOG.md                 |  1 +
 UPGRADING.md                 |  5 +++++
 src/NonSerializableTrait.php | 21 +++++++++++++++++++++
 src/ServiceClient.php        |  2 ++
 4 files changed, 29 insertions(+)
 create mode 100644 src/NonSerializableTrait.php

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1427bed..f2e17f1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,7 @@
 * Drop support for PHP 7.2 and 7.3
 * Require `guzzlehttp/guzzle` ^8.0, `guzzlehttp/promises` ^3.0, and `guzzlehttp/psr7` ^3.0
 * Add generic PHPDoc return types to asynchronous service client APIs
+* Reject native PHP serialization of `ServiceClient`
 * Require custom implementations and subclasses of public command APIs to match native method signatures
 * Require service client response transformers to return `ResultInterface` values
 * Require custom middleware, transformers, and `executeAll()` callbacks to accept exact argument types instead of relying on scalar coercion
diff --git a/UPGRADING.md b/UPGRADING.md
index 25fdb10..c3e1600 100644
--- a/UPGRADING.md
+++ b/UPGRADING.md
@@ -28,6 +28,11 @@ If your application still supports PHP 7.2 or 7.3, or still uses the Guzzle 7
 dependency stack, continue using Guzzle Command 1.x until your minimum PHP and
 dependency versions are raised.
 
+#### Native PHP Serialization Of Service Clients
+
+`ServiceClient` no longer supports native PHP `serialize()` or `unserialize()`.
+Persist command names and parameter arrays instead of runtime client objects.
+
 #### Strict Types and Extension Points
 
 Guzzle Command source and test files now declare strict types. This mostly
diff --git a/src/NonSerializableTrait.php b/src/NonSerializableTrait.php
new file mode 100644
index 0000000..03007c3
--- /dev/null
+++ b/src/NonSerializableTrait.php
@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace GuzzleHttp\Command;
+
+/**
+ * @internal
+ */
+trait NonSerializableTrait
+{
+    public function __serialize(): array
+    {
+        throw new \LogicException(static::class.' should never be serialized');
+    }
+
+    public function __unserialize(array $data): void
+    {
+        throw new \LogicException(static::class.' should never be unserialized');
+    }
+}
diff --git a/src/ServiceClient.php b/src/ServiceClient.php
index 2cc60e4..8e9c7a3 100644
--- a/src/ServiceClient.php
+++ b/src/ServiceClient.php
@@ -18,6 +18,8 @@
  */
 class ServiceClient implements ServiceClientInterface
 {
+    use NonSerializableTrait;
+
     private HttpClient $httpClient;
 
     /** @var HandlerStack<callable(CommandInterface): PromiseInterface<ResultInterface, mixed>> */

From c5f215c53b364310e9997d12040845ebd20bc0e9 Mon Sep 17 00:00:00 2001
From: Graham Campbell <hello@gjcampbell.co.uk>
Date: Tue, 9 Jun 2026 23:34:45 +0100
Subject: [PATCH 2/2] Move serialization upgrade note

---
 UPGRADING.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/UPGRADING.md b/UPGRADING.md
index c3e1600..d18e65f 100644
--- a/UPGRADING.md
+++ b/UPGRADING.md
@@ -28,11 +28,6 @@ If your application still supports PHP 7.2 or 7.3, or still uses the Guzzle 7
 dependency stack, continue using Guzzle Command 1.x until your minimum PHP and
 dependency versions are raised.
 
-#### Native PHP Serialization Of Service Clients
-
-`ServiceClient` no longer supports native PHP `serialize()` or `unserialize()`.
-Persist command names and parameter arrays instead of runtime client objects.
-
 #### Strict Types and Extension Points
 
 Guzzle Command source and test files now declare strict types. This mostly
@@ -93,6 +88,11 @@ the command key. `executeAllAsync()` callback annotations include the same first
 two arguments plus the aggregate promise as a third argument. Lower-arity
 userland callbacks continue to work at runtime when PHP accepts them.
 
+#### Native PHP Serialization of Service Clients
+
+`ServiceClient` no longer supports native PHP `serialize()` or `unserialize()`.
+Persist command names and parameter arrays instead of runtime client objects.
+
 1.0 from 0.8
 ------------