deprecate Form::_execute (cakephp#18725)

Author: LordSimal

src/Form/Form.php

@@ -23,6 +23,8 @@
 use Cake\Utility\Hash;
 use Cake\Validation\ValidatorAwareInterface;
 use Cake\Validation\ValidatorAwareTrait;
+use ReflectionMethod;
+use function Cake\Core\deprecationWarning;
 
 /**
  * Form abstraction used to create forms not tied to ORM backed models,
@@ -33,7 +35,7 @@
  *
  * This class is most useful when subclassed. In a subclass you
  * should define the `_buildSchema`, `validationDefault` and optionally,
- * the `_execute` methods. These allow you to declare your form's
+ * the `process` methods. These allow you to declare your form's
  * fields, validation and primary action respectively.
  *
  * Forms are conventionally placed in the `App\Form` namespace.
@@ -243,7 +245,7 @@ public function setErrors(array $errors)
     /**
      * Execute the form if it is valid.
      *
-     * First validates the form, then calls the `_execute()` hook method.
+     * First validates the form, then calls the `process()` hook method.
      * This hook method can be implemented in subclasses to perform
      * the action of the form. This may be sending email, interacting
      * with a remote API, or anything else you may need.
@@ -256,21 +258,45 @@ public function setErrors(array $errors)
      * @param array $data Form data.
      * @param array<string, mixed> $options List of options.
      * @return bool False on validation failure, otherwise returns the
-     *   result of the `_execute()` method.
+     *   result of the `process()` method.
      */
     public function execute(array $data, array $options = []): bool
     {
-        $this->_data = $data;
+        // check for deprecated _execute() method - https://github.com/cakephp/cakephp/pull/18725
+        $childClass = static::class;
+        $parentClass = self::class;
+        $method = new ReflectionMethod($childClass, '_execute');
+        $hasOverwrittenExecute = $method->getDeclaringClass()->getName() !== $parentClass;
 
+        $this->_data = $data;
         $options += ['validate' => true];
 
         if ($options['validate'] === false) {
-            return $this->_execute($data);
+            if ($hasOverwrittenExecute) {
+                deprecationWarning(
+                    '5.3.0',
+                    'The _execute() method is deprecated. Override the process() method instead.',
+                );
+
+                return $this->_execute($data);
+            }
+
+            return $this->process($data);
         }
 
         $validator = $options['validate'] === true ? static::DEFAULT_VALIDATOR : $options['validate'];
+        $validateResult = $this->validate($data, $validator);
+
+        if ($hasOverwrittenExecute) {
+            deprecationWarning(
+                '5.3.0',
+                'The _execute() method is deprecated. Override the process() method instead.',
+            );
 
-        return $this->validate($data, $validator) && $this->_execute($data);
+            return $validateResult && $this->_execute($data);
+        }
+
+        return $validateResult && $this->process($data);
     }
 
     /**
@@ -280,8 +306,22 @@ public function execute(array $data, array $options = []): bool
      *
      * @param array $data Form data.
      * @return bool
+     * @deprecated 5.3.0 Override process() instead.
      */
     protected function _execute(array $data): bool
+    {
+        return $this->process($data);
+    }
+
+    /**
+     * Hook method to be implemented in subclasses.
+     *
+     * Used by `execute()` to execute the form's action.
+     *
+     * @param array $data Form data.
+     * @return bool
+     */
+    protected function process(array $data): bool
     {
         return true;
     }

tests/TestCase/Form/FormTest.php

@@ -165,20 +165,21 @@ public function testSetErrors(): void
      */
     public function testExecuteInvalid(): void
     {
-        $form = new class extends Form {
-            // phpcs:ignore CakePHP.NamingConventions.ValidFunctionName.PublicWithUnderscore
-            public function _execute(array $data): bool
-            {
-                throw new Exception('Should not be called');
-            }
-        };
-        $form->getValidator()
-            ->add('email', 'format', ['rule' => 'email']);
-        $data = [
-            'email' => 'rong',
-        ];
-
-        $this->assertFalse($form->execute($data));
+        $this->deprecated(function (): void {
+            $form = new class extends Form {
+                protected function _execute(array $data): bool
+                {
+                    throw new Exception('Should not be called');
+                }
+            };
+            $form->getValidator()
+                ->add('email', 'format', ['rule' => 'email']);
+            $data = [
+                'email' => 'rong',
+            ];
+
+            $this->assertFalse($form->execute($data));
+        });
     }
 
     /**
@@ -196,6 +197,38 @@ public function testExecuteValid(): void
         $this->assertTrue($form->execute($data));
     }
 
+    /**
+     * test execute() when data is valid.
+     */
+    public function testExecuteWithProcess(): void
+    {
+        $form = new class extends Form {
+            public function process(array $data): bool
+            {
+                return false;
+            }
+        };
+
+        $this->assertFalse($form->execute([]));
+    }
+
+    /**
+     * test execute()
+     */
+    public function testExecuteWithExecuteAndNoValidate(): void
+    {
+        $this->deprecated(function (): void {
+            $form = new class extends Form {
+                protected function _execute(array $data): bool
+                {
+                    return false;
+                }
+            };
+
+            $this->assertFalse($form->execute([], ['validate' => false]));
+        });
+    }
+
     /**
      * test execute() when data is valid.
      */