Ignore throws in function mocks (#245)

# Summary <!-- Required -->

I have noticed that in some circumstances the mocks contained in
`API/function-mocks.php` could trigger false positives in static
analyzers like PhpStan or just the IDE if using WP_Mock within a
project. I think by removing the `@throws` solves this, although PhpStan
will complain about it _in this_ project. I suppose since these are just
internal mocks we can safely ignore.

I did try using `@noinspection` tags but PhpStorm wasn't happy (whether
specific to unhandled exceptions or not).

As for the strict type notations, same reason, externally it will
reflect WP behavior (the alternative was to leave non-strict and rely
only on phpdoc -- like WP does -- but then PhpStan would complain
again... could swap that for a phpstan-ignore again, up to you)

## Closes #248 

## Contributor checklist <!-- Required -->

<!--- Go over all the following points, and put an `x` in all the boxes
that apply. -->
<!--- If you are unsure about any of these, please ask for
clarification. We are here to help! -->

- [x] I agree to follow this project's [**Code of
Conduct**](https://github.com/10up/.github/blob/trunk/CODE_OF_CONDUCT.md).
- [x] I have updated the documentation accordingly 
- [x] I have added tests to cover changes introduced by this pull
request
- [x] All new and existing tests pass

## Testing <!-- Required -->

<!-- If applicable, add specific steps for the reviewer to perform as
part of their testing process prior to approving this pull request. -->

<!-- List any configuration requirements for testing. -->

### Reviewer checklist <!-- Required -->

<!-- The following checklist is for the reviewer: add any steps that may
be relevant while reviewing this pull request -->

- [x] Code changes review
- [ ] Documentation changes review
- [x] Unit tests pass
- [x] Static analysis passes

php/WP_Mock/API/function-mocks.php

@@ -83,186 +83,188 @@ function apply_filters($tag, $value)
 
 if (! function_exists('esc_html')) {
     /**
-     * @return string|mixed
-     * @throws ExpectationFailedException|Exception
+     * @return string
      */
-    function esc_html()
+    function esc_html() : string
     {
+        /** @phpstan-ignore-next-line to prevent flagging the function as throwing exception in codebases requiring WP_Mock */
         return Handler::handlePredefinedReturnFunction(__FUNCTION__, func_get_args());
     }
 }
 
 if (! function_exists('esc_attr')) {
     /**
-     * @return string|mixed
-     * @throws ExpectationFailedException|Exception
+     * @return string
      */
-    function esc_attr()
+    function esc_attr() : string
     {
+        /** @phpstan-ignore-next-line to prevent flagging the function as throwing exception in codebases requiring WP_Mock */
         return Handler::handlePredefinedReturnFunction(__FUNCTION__, func_get_args());
     }
 }
 
 if (! function_exists('esc_url')) {
     /**
-     * @return string|mixed
-     * @throws ExpectationFailedException|Exception
+     * @return string
      */
-    function esc_url()
+    function esc_url() : string
     {
+        /** @phpstan-ignore-next-line to prevent flagging the function as throwing exception in codebases requiring WP_Mock */
         return Handler::handlePredefinedReturnFunction(__FUNCTION__, func_get_args());
     }
 }
 
 if (! function_exists('esc_url_raw')) {
     /**
-     * @return string|mixed
-     * @throws ExpectationFailedException|Exception
+     * @return string
      */
-    function esc_url_raw()
+    function esc_url_raw() : string
     {
+        /** @phpstan-ignore-next-line to prevent flagging the function as throwing exception in codebases requiring WP_Mock */
         return Handler::handlePredefinedReturnFunction(__FUNCTION__, func_get_args());
     }
 }
 
 if (! function_exists('esc_js')) {
     /**
-     * @return string|mixed
-     * @throws ExpectationFailedException|Exception
+     * @return string
      */
-    function esc_js()
+    function esc_js() : string
     {
+        /** @phpstan-ignore-next-line to prevent flagging the function as throwing exception in codebases requiring WP_Mock */
         return Handler::handlePredefinedReturnFunction(__FUNCTION__, func_get_args());
     }
 }
 
 if (! function_exists('esc_textarea')) {
     /**
-     * @return string|mixed
-     * @throws ExpectationFailedException|Exception
+     * @return string
      */
-    function esc_textarea()
+    function esc_textarea() : string
     {
+        /** @phpstan-ignore-next-line to prevent flagging the function as throwing exception in codebases requiring WP_Mock */
         return Handler::handlePredefinedReturnFunction(__FUNCTION__, func_get_args());
     }
 }
 
 if (! function_exists('__')) {
     /**
-     * @return string|mixed
-     * @throws ExpectationFailedException|Exception
+     * @return string
      */
-    function __()
+    function __() : string
     {
+        /** @phpstan-ignore-next-line to prevent flagging the function as throwing exception in codebases requiring WP_Mock */
         return Handler::handlePredefinedReturnFunction(__FUNCTION__, func_get_args());
     }
 }
 
 if (! function_exists('_e')) {
     /**
      * @return void
-     * @throws ExpectationFailedException|Exception
      */
-    function _e(): void
+    function _e() : void
     {
+        /** @phpstan-ignore-next-line to prevent flagging the function as throwing exception in codebases requiring WP_Mock */
         Handler::handlePredefinedEchoFunction(__FUNCTION__, func_get_args());
     }
 }
 
 if (! function_exists('_x')) {
     /**
-     * @return string|mixed
-     * @throws ExpectationFailedException|Exception
+     * @return string
      */
-    function _x()
+    function _x() : string
     {
+        /** @phpstan-ignore-next-line to prevent flagging the function as throwing exception in codebases requiring WP_Mock */
         return Handler::handlePredefinedReturnFunction(__FUNCTION__, func_get_args());
     }
 }
 
 if (! function_exists('esc_html__')) {
     /**
-     * @return string|mixed
-     * @throws ExpectationFailedException|Exception
+     * @return string
      */
-    function esc_html__()
+    function esc_html__() : string
     {
+        /** @phpstan-ignore-next-line to prevent flagging the function as throwing exception in codebases requiring WP_Mock */
         return Handler::handlePredefinedReturnFunction(__FUNCTION__, func_get_args());
     }
 }
 
 if (! function_exists('esc_html_e')) {
     /**
      * @return void
-     * @throws ExpectationFailedException|Exception
      */
-    function esc_html_e(): void
+    function esc_html_e() : void
     {
+        /** @phpstan-ignore-next-line to prevent flagging the function as throwing exception in codebases requiring WP_Mock */
         Handler::handlePredefinedEchoFunction(__FUNCTION__, func_get_args());
     }
 }
 
 if (! function_exists('esc_html_x')) {
     /**
-     * @return string|mixed
-     * @throws ExpectationFailedException|Exception
+     * @return string
      */
-    function esc_html_x()
+    function esc_html_x() : string
     {
+        /** @phpstan-ignore-next-line to prevent flagging the function as throwing exception in codebases requiring WP_Mock */
         return Handler::handlePredefinedReturnFunction(__FUNCTION__, func_get_args());
     }
 }
 
 if (! function_exists('esc_attr__')) {
     /**
-     * @return string|mixed
-     * @throws ExpectationFailedException|Exception
+     * @return string
      */
-    function esc_attr__()
+    function esc_attr__() : string
     {
+        /** @phpstan-ignore-next-line to prevent flagging the function as throwing exception in codebases requiring WP_Mock */
         return Handler::handlePredefinedReturnFunction(__FUNCTION__, func_get_args());
     }
 }
 
 if (! function_exists('esc_attr_e')) {
     /**
      * @return void
-     * @throws ExpectationFailedException|Exception
      */
-    function esc_attr_e(): void
+    function esc_attr_e() : void
     {
+        /** @phpstan-ignore-next-line to prevent flagging the function as throwing exception in codebases requiring WP_Mock */
         Handler::handlePredefinedEchoFunction(__FUNCTION__, func_get_args());
     }
 }
 
 if (! function_exists('esc_attr_x')) {
     /**
-     * @return string|mixed
-     * @throws ExpectationFailedException
+     * @return string
      */
-    function esc_attr_x()
+    function esc_attr_x() : string
     {
+        /** @phpstan-ignore-next-line to prevent flagging the function as throwing exception in codebases requiring WP_Mock */
         return Handler::handlePredefinedReturnFunction(__FUNCTION__, func_get_args());
     }
 }
 
 if (! function_exists('_n')) {
     /**
-     * @return string|mixed singular or plural string based on number
-     * @throws ExpectationFailedException if too few arguments passed
+     * @return string
      */
-    function _n()
+    function _n() : string
     {
         $args = func_get_args();
 
         if (count($args) >= 3) {
             /** @phpstan-ignore-next-line */
             if (isset($args[0]) && 1 >= intval($args[2])) {
-                return $args[0];
+                /** @phpstan-ignore-next-line */
+                return (string) $args[0];
             } else {
-                return $args[1];
+                /** @phpstan-ignore-next-line */
+                return (string) $args[1];
             }
         } else {
+            /** @phpstan-ignore-next-line to prevent flagging the function as throwing exception in codebases requiring WP_Mock */
             throw new ExpectationFailedException(sprintf('Too few arguments to function %s', __FUNCTION__));
         }
     }

php/WP_Mock/Functions/Handler.php

@@ -104,7 +104,7 @@ public static function handlePredefinedReturnFunction(string $functionName, arra
      * @param string $functionName function name
      * @param array<mixed> $args function arguments
      * @return void
-     * @throws Exception|ExpectationFailedException
+     * @throws ExpectationFailedException
      */
     public static function handlePredefinedEchoFunction(string $functionName, array $args = []): void
     {
@@ -115,6 +115,7 @@ public static function handlePredefinedEchoFunction(string $functionName, array
         } catch (Exception $exception) {
             ob_end_clean();
 
+            /** @var ExpectationFailedException $exception */
             throw $exception;
         }
 

tests/Integration/WP_MockTest.php

@@ -130,7 +130,6 @@ public function providerCommonFunctionsDefaultFunctionality(): array
      * @preserveGlobalState disabled
      *
      * @return void
-     * @throws Exception
      */
     public function testDefaultFailsInStrictMode(): void
     {
@@ -175,7 +174,7 @@ public function testMockingOverridesDefaults(): void
      */
     public function testBotchedMocksStillOverridesDefault(): void
     {
-        WP_Mock::userFunction('esc_html');
+        WP_Mock::userFunction('esc_html')->andReturn('');
 
         /** @phpstan-ignore-next-line function "exists" */
         $this->assertEmpty(esc_html('Input'));