refactor! Fully rename operation classes & methods to xxxHandler

acoulton · acoulton · commit 7bbfffea8cf3 · 2025-11-30T18:19:08.000Z
Renames all remaining classes, interfaces &amp; methods related to patch
operation handlers to include the `Handler` suffix.

This reinstates consistency between the naming of these concerns, and
will provide the cleanest base for implementing patch operation DTOs
without naming conflicts or confusion.

It will, however, impact any end-users who have implemented &amp; registered
custom patch handlers as they will need to update them for the new
naming as part of the 3.x upgrade.
diff --git a/README.md b/README.md
@@ -185,14 +185,14 @@ Patch application is designed to be atomic. If any operation of a given patch fa
   ```
 
 
-#### `function registerOperation(PatchOperationInterface $PatchOperation): void`
+#### `function registerOperationHandler(PatchOperationHandlerInterface $PatchOperation): void`
 
 - **Description**: Allows to register new patch operation handlers or to override existing ones.
 - **Parameters**:
-  - `PatchOperationInterface $PatchOperation`: The handler class for handling the operation.
+  - `PatchOperationHandlerInterface $PatchOperation`: The handler class for handling the operation.
 - **Example**:
   ```php
-  $FastJsonPatch->registerOperation(new Add);
+  $FastJsonPatch->registerOperationHandler(new Add);
   ```
 
 
diff --git a/src/FastJsonPatch.php b/src/FastJsonPatch.php
@@ -22,7 +22,7 @@
     JsonPointerHandlerInterface
 };
 use blancks\JsonPatch\operations\{
-    PatchOperationInterface,
+    handlers\PatchOperationHandlerInterface,
     PatchValidationTrait,
     handlers\AddHandler,
     handlers\CopyHandler,
@@ -48,9 +48,9 @@ final class FastJsonPatch implements JsonHandlerAwareInterface, JsonPointerHandl
     private mixed $document;
 
     /**
-     * @var array<string, PatchOperationInterface> registered classes for handling patch operations
+     * @var array<string, PatchOperationHandlerInterface> registered classes for handling patch operations
      */
-    private array $operations = [];
+    private array $operationHandlers = [];
 
     /**
      * Creates a FastJsonPatch instance from a json string document
@@ -91,21 +91,21 @@ public function __construct(
 
         $this->setJsonPointerHandler($JsonPointerHandler);
         $this->setJsonHandler($JsonHandler);
-        $this->registerOperation(new AddHandler);
-        $this->registerOperation(new CopyHandler);
-        $this->registerOperation(new MoveHandler);
-        $this->registerOperation(new RemoveHandler);
-        $this->registerOperation(new ReplaceHandler);
-        $this->registerOperation(new TestHandler);
+        $this->registerOperationHandler(new AddHandler);
+        $this->registerOperationHandler(new CopyHandler);
+        $this->registerOperationHandler(new MoveHandler);
+        $this->registerOperationHandler(new RemoveHandler);
+        $this->registerOperationHandler(new ReplaceHandler);
+        $this->registerOperationHandler(new TestHandler);
     }
 
     /**
      * Allows to register a class that will be responsible to handle a specific patch operation.
      * You can replace a handler class for a given operation or register handlers for custom patch operations
-     * @param PatchOperationInterface $PatchOperation
+     * @param PatchOperationHandlerInterface $PatchOperation
      * @return void
      */
-    public function registerOperation(PatchOperationInterface $PatchOperation): void
+    public function registerOperationHandler(PatchOperationHandlerInterface $PatchOperation): void
     {
         if ($PatchOperation instanceof JsonHandlerAwareInterface) {
             $PatchOperation->setJsonHandler($this->JsonHandler);
@@ -115,7 +115,7 @@ public function registerOperation(PatchOperationInterface $PatchOperation): void
             $PatchOperation->setJsonPointerHandler($this->JsonPointerHandler);
         }
 
-        $this->operations[$PatchOperation->getOperation()] = $PatchOperation;
+        $this->operationHandlers[$PatchOperation->getOperation()] = $PatchOperation;
     }
 
     /**
@@ -132,10 +132,10 @@ public function apply(string $patch): void
             $document = &$this->document;
 
             foreach ($this->patchIterator($patch) as $op => $p) {
-                if (!isset($this->operations[$op])) {
+                if (!isset($this->operationHandlers[$op])) {
                     throw new InvalidPatchOperationException(sprintf('Unknown operation "%s"', $op));
                 }
-                $Operation = $this->operations[$op];
+                $Operation = $this->operationHandlers[$op];
                 $Operation->validate($p);
                 $Operation->apply($document, $p);
                 $revertPatch[] = $Operation->getRevertPatch($p);
@@ -144,7 +144,7 @@ public function apply(string $patch): void
             foreach (array_reverse($revertPatch) as $p) {
                 if (!is_null($p)) {
                     $p = (object) $p;
-                    $this->operations[$p->op]->apply($this->document, $p);
+                    $this->operationHandlers[$p->op]->apply($this->document, $p);
                 }
             }
 
@@ -170,10 +170,10 @@ public function isValidPatch(string $patch): bool
     {
         try {
             foreach ($this->patchIterator($patch) as $op => $p) {
-                if (!isset($this->operations[$op])) {
+                if (!isset($this->operationHandlers[$op])) {
                     return false;
                 }
-                $this->operations[$op]->validate($p);
+                $this->operationHandlers[$op]->validate($p);
             }
             return true;
         } catch (FastJsonPatchException) {
diff --git a/src/operations/handlers/AddHandler.php b/src/operations/handlers/AddHandler.php
@@ -3,12 +3,11 @@
 namespace blancks\JsonPatch\operations\handlers;
 
 use blancks\JsonPatch\json\accessors\UndefinedValue;
-use blancks\JsonPatch\operations\PatchOperation;
 
 /**
  * @internal
  */
-final class AddHandler extends PatchOperation
+final class AddHandler extends PatchOperationHandler
 {
     private mixed $previous;
 
diff --git a/src/operations/handlers/CopyHandler.php b/src/operations/handlers/CopyHandler.php
@@ -3,12 +3,11 @@
 namespace blancks\JsonPatch\operations\handlers;
 
 use blancks\JsonPatch\json\accessors\UndefinedValue;
-use blancks\JsonPatch\operations\PatchOperation;
 
 /**
  * @internal
  */
-final class CopyHandler extends PatchOperation
+final class CopyHandler extends PatchOperationHandler
 {
     private mixed $previous;
 
diff --git a/src/operations/handlers/MoveHandler.php b/src/operations/handlers/MoveHandler.php
@@ -2,12 +2,10 @@
 
 namespace blancks\JsonPatch\operations\handlers;
 
-use blancks\JsonPatch\operations\PatchOperation;
-
 /**
  * @internal
  */
-final class MoveHandler extends PatchOperation
+final class MoveHandler extends PatchOperationHandler
 {
     /**
      * @param object{
diff --git a/src/operations/handlers/PatchOperationHandler.php b/src/operations/handlers/PatchOperationHandler.php
@@ -1,14 +1,16 @@
 <?php declare(strict_types=1);
 
-namespace blancks\JsonPatch\operations;
+namespace blancks\JsonPatch\operations\handlers;
 
 use blancks\JsonPatch\json\handlers\JsonHandlerAwareInterface;
 use blancks\JsonPatch\json\handlers\JsonHandlerAwareTrait;
 use blancks\JsonPatch\json\pointer\JsonPointerHandlerAwareInterface;
 use blancks\JsonPatch\json\pointer\JsonPointerHandlerAwareTrait;
+use blancks\JsonPatch\operations\handlers\PatchOperationHandlerInterface;
+use blancks\JsonPatch\operations\PatchValidationTrait;
 
-abstract class PatchOperation implements
-    PatchOperationInterface,
+abstract class PatchOperationHandler implements
+    PatchOperationHandlerInterface,
     JsonHandlerAwareInterface,
     JsonPointerHandlerAwareInterface
 {
diff --git a/src/operations/handlers/PatchOperationHandlerInterface.php b/src/operations/handlers/PatchOperationHandlerInterface.php
@@ -1,6 +1,6 @@
 <?php declare(strict_types=1);
 
-namespace blancks\JsonPatch\operations;
+namespace blancks\JsonPatch\operations\handlers;
 
 use blancks\JsonPatch\exceptions\FastJsonPatchException;
 
@@ -9,7 +9,7 @@
  * handle the patch application for a specific
  * operation type
  */
-interface PatchOperationInterface
+interface PatchOperationHandlerInterface
 {
     /**
      * Must return the operation name that the class will handle
diff --git a/src/operations/handlers/RemoveHandler.php b/src/operations/handlers/RemoveHandler.php
@@ -2,12 +2,10 @@
 
 namespace blancks\JsonPatch\operations\handlers;
 
-use blancks\JsonPatch\operations\PatchOperation;
-
 /**
  * @internal
  */
-final class RemoveHandler extends PatchOperation
+final class RemoveHandler extends PatchOperationHandler
 {
     private mixed $previous;
 
diff --git a/src/operations/handlers/ReplaceHandler.php b/src/operations/handlers/ReplaceHandler.php
@@ -2,12 +2,10 @@
 
 namespace blancks\JsonPatch\operations\handlers;
 
-use blancks\JsonPatch\operations\PatchOperation;
-
 /**
  * @internal
  */
-final class ReplaceHandler extends PatchOperation
+final class ReplaceHandler extends PatchOperationHandler
 {
     private mixed $previous;
 
diff --git a/src/operations/handlers/TestHandler.php b/src/operations/handlers/TestHandler.php
@@ -3,12 +3,11 @@
 namespace blancks\JsonPatch\operations\handlers;
 
 use blancks\JsonPatch\exceptions\FailedTestException;
-use blancks\JsonPatch\operations\PatchOperation;
 
 /**
  * @internal
  */
-final class TestHandler extends PatchOperation
+final class TestHandler extends PatchOperationHandler
 {
     /**
      * @param object{
diff --git a/tests/FastJsonPatchTest.php b/tests/FastJsonPatchTest.php
@@ -21,7 +21,7 @@
     pointer\JsonPointer6901
 };
 use blancks\JsonPatch\operations\{
-    PatchOperation,
+    handlers\PatchOperationHandler,
     handlers\AddHandler,
     handlers\CopyHandler,
     handlers\MoveHandler,
@@ -51,7 +51,7 @@
 #[UsesClass(CrudTrait::class)]
 #[UsesClass(BasicJsonHandler::class)]
 #[UsesClass(JsonPointer6901::class)]
-#[UsesClass(PatchOperation::class)]
+#[UsesClass(PatchOperationHandler::class)]
 #[UsesClass(AddHandler::class)]
 #[UsesClass(CopyHandler::class)]
 #[UsesClass(MoveHandler::class)]
@@ -126,7 +126,7 @@ public function testInvalidJsonPointerRead(): void
     public function testCustomOperationHandler(): void
     {
         $FastJsonPatch = FastJsonPatch::fromJson('{}');
-        $FastJsonPatch->registerOperation(new class() extends PatchOperation {
+        $FastJsonPatch->registerOperationHandler(new class() extends PatchOperationHandler {
             public function getOperation(): string
             {
                 return 'addexclamation';
diff --git a/tests/exceptions/ArrayBoundaryExceptionTest.php b/tests/exceptions/ArrayBoundaryExceptionTest.php
@@ -13,7 +13,7 @@
 use blancks\JsonPatch\json\handlers\BasicJsonHandler;
 use blancks\JsonPatch\json\pointer\JsonPointer6901;
 use blancks\JsonPatch\operations\handlers\AddHandler;
-use blancks\JsonPatch\operations\PatchOperation;
+use blancks\JsonPatch\operations\handlers\PatchOperationHandler;
 use blancks\JsonPatch\FastJsonPatch;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\DataProvider;
@@ -31,7 +31,7 @@
 #[UsesClass(CrudTrait::class)]
 #[UsesClass(BasicJsonHandler::class)]
 #[UsesClass(JsonPointer6901::class)]
-#[UsesClass(PatchOperation::class)]
+#[UsesClass(PatchOperationHandler::class)]
 #[UsesClass(AddHandler::class)]
 final class ArrayBoundaryExceptionTest extends TestCase
 {
diff --git a/tests/exceptions/FailedTestExceptionTest.php b/tests/exceptions/FailedTestExceptionTest.php
@@ -12,8 +12,8 @@
 use blancks\JsonPatch\json\crud\CrudTrait;
 use blancks\JsonPatch\json\handlers\BasicJsonHandler;
 use blancks\JsonPatch\json\pointer\JsonPointer6901;
+use blancks\JsonPatch\operations\handlers\PatchOperationHandler;
 use blancks\JsonPatch\operations\handlers\TestHandler;
-use blancks\JsonPatch\operations\PatchOperation;
 use blancks\JsonPatch\FastJsonPatch;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\DataProvider;
@@ -31,7 +31,7 @@
 #[UsesClass(CrudTrait::class)]
 #[UsesClass(BasicJsonHandler::class)]
 #[UsesClass(JsonPointer6901::class)]
-#[UsesClass(PatchOperation::class)]
+#[UsesClass(PatchOperationHandler::class)]
 #[UsesClass(TestHandler::class)]
 final class FailedTestExceptionTest extends TestCase
 {
diff --git a/tests/exceptions/InvalidPatchExceptionTest.php b/tests/exceptions/InvalidPatchExceptionTest.php
@@ -10,7 +10,7 @@
 use blancks\JsonPatch\json\accessors\ValueAccessorAwareTrait;
 use blancks\JsonPatch\json\handlers\BasicJsonHandler;
 use blancks\JsonPatch\json\pointer\JsonPointer6901;
-use blancks\JsonPatch\operations\PatchOperation;
+use blancks\JsonPatch\operations\handlers\PatchOperationHandler;
 use blancks\JsonPatch\FastJsonPatch;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\UsesClass;
@@ -25,7 +25,7 @@
 #[UsesClass(ValueAccessorAwareTrait::class)]
 #[UsesClass(BasicJsonHandler::class)]
 #[UsesClass(JsonPointer6901::class)]
-#[UsesClass(PatchOperation::class)]
+#[UsesClass(PatchOperationHandler::class)]
 final class InvalidPatchExceptionTest extends TestCase
 {
     /**
diff --git a/tests/exceptions/InvalidPatchFromExceptionTest.php b/tests/exceptions/InvalidPatchFromExceptionTest.php
@@ -15,8 +15,8 @@
 use blancks\JsonPatch\json\pointer\JsonPointer6901;
 use blancks\JsonPatch\operations\handlers\AddHandler;
 use blancks\JsonPatch\operations\handlers\CopyHandler;
+use blancks\JsonPatch\operations\handlers\PatchOperationHandler;
 use blancks\JsonPatch\operations\handlers\RemoveHandler;
-use blancks\JsonPatch\operations\PatchOperation;
 use blancks\JsonPatch\FastJsonPatch;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\UsesClass;
@@ -34,7 +34,7 @@
 #[UsesClass(CrudTrait::class)]
 #[UsesClass(BasicJsonHandler::class)]
 #[UsesClass(JsonPointer6901::class)]
-#[UsesClass(PatchOperation::class)]
+#[UsesClass(PatchOperationHandler::class)]
 #[UsesClass(AddHandler::class)]
 #[UsesClass(CopyHandler::class)]
 #[UsesClass(RemoveHandler::class)]
diff --git a/tests/exceptions/InvalidPatchOperationExceptionTest.php b/tests/exceptions/InvalidPatchOperationExceptionTest.php
@@ -11,7 +11,7 @@
 use blancks\JsonPatch\json\accessors\ValueAccessorAwareTrait;
 use blancks\JsonPatch\json\handlers\BasicJsonHandler;
 use blancks\JsonPatch\json\pointer\JsonPointer6901;
-use blancks\JsonPatch\operations\PatchOperation;
+use blancks\JsonPatch\operations\handlers\PatchOperationHandler;
 use blancks\JsonPatch\FastJsonPatch;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\UsesClass;
@@ -27,7 +27,7 @@
 #[UsesClass(ValueAccessorAwareTrait::class)]
 #[UsesClass(BasicJsonHandler::class)]
 #[UsesClass(JsonPointer6901::class)]
-#[UsesClass(PatchOperation::class)]
+#[UsesClass(PatchOperationHandler::class)]
 final class InvalidPatchOperationExceptionTest extends TestCase
 {
     /**
diff --git a/tests/exceptions/InvalidPatchPathExceptionTest.php b/tests/exceptions/InvalidPatchPathExceptionTest.php
@@ -11,7 +11,7 @@
 use blancks\JsonPatch\json\accessors\ValueAccessorAwareTrait;
 use blancks\JsonPatch\json\handlers\BasicJsonHandler;
 use blancks\JsonPatch\json\pointer\JsonPointer6901;
-use blancks\JsonPatch\operations\PatchOperation;
+use blancks\JsonPatch\operations\handlers\PatchOperationHandler;
 use blancks\JsonPatch\FastJsonPatch;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\UsesClass;
@@ -27,7 +27,7 @@
 #[UsesClass(ValueAccessorAwareTrait::class)]
 #[UsesClass(BasicJsonHandler::class)]
 #[UsesClass(JsonPointer6901::class)]
-#[UsesClass(PatchOperation::class)]
+#[UsesClass(PatchOperationHandler::class)]
 final class InvalidPatchPathExceptionTest extends TestCase
 {
     /**
diff --git a/tests/exceptions/InvalidPatchValueExceptionTest.php b/tests/exceptions/InvalidPatchValueExceptionTest.php
@@ -12,7 +12,7 @@
 use blancks\JsonPatch\json\handlers\BasicJsonHandler;
 use blancks\JsonPatch\json\pointer\JsonPointer6901;
 use blancks\JsonPatch\operations\handlers\AddHandler;
-use blancks\JsonPatch\operations\PatchOperation;
+use blancks\JsonPatch\operations\handlers\PatchOperationHandler;
 use blancks\JsonPatch\FastJsonPatch;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\UsesClass;
@@ -28,7 +28,7 @@
 #[UsesClass(ValueAccessorAwareTrait::class)]
 #[UsesClass(BasicJsonHandler::class)]
 #[UsesClass(JsonPointer6901::class)]
-#[UsesClass(PatchOperation::class)]
+#[UsesClass(PatchOperationHandler::class)]
 #[UsesClass(AddHandler::class)]
 final class InvalidPatchValueExceptionTest extends TestCase
 {
diff --git a/tests/exceptions/MalformedPathExceptionTest.php b/tests/exceptions/MalformedPathExceptionTest.php
diff --git a/tests/exceptions/UnknownPathExceptionTest.php b/tests/exceptions/UnknownPathExceptionTest.php
diff --git a/tests/operations/handlers/AddTest.php b/tests/operations/handlers/AddTest.php
diff --git a/tests/operations/handlers/CopyTest.php b/tests/operations/handlers/CopyTest.php
diff --git a/tests/operations/handlers/MoveTest.php b/tests/operations/handlers/MoveTest.php
diff --git a/tests/operations/handlers/RemoveTest.php b/tests/operations/handlers/RemoveTest.php
diff --git a/tests/operations/handlers/ReplaceTest.php b/tests/operations/handlers/ReplaceTest.php
diff --git a/tests/operations/handlers/TestTest.php b/tests/operations/handlers/TestTest.php
