9711864001

Committed 28 Jun 2024 11:11AM UTC coverage: 66.312% (-0.1%) from 66.445%

Build # 9711864001

Build Type

push

github

Committed by

web-flow

Commit Message

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

Run Details

2 of 2 new or added lines in 1 file covered. (100.0%)

4 existing lines in 3 files now uncovered.

498 of 751 relevant lines covered (66.31%)

2.61 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

38.0

/php/WP_Mock/API/function-mocks.php

<?php

use PHPUnit\Framework\ExpectationFailedException;
use WP_Mock\Functions\Handler;

if (! function_exists('add_action')) {
    /**
     * Hooks a function on to a specific action.
     *
     * Actions are the hooks that WordPress launches at specific points during execution, or when specific events occur.
     * Plugins can specify that one or more of its PHP functions are executed at these points, using the Action API.
     *
     * @link https://developer.wordpress.org/plugins/hooks/actions/
     *
     * @param string $tag the name of the action to which the $function_to_add is hooked
     * @param string|callable-string|callable $functionToAdd the name of the function you wish to be called
     * @param int $priority optional, used to specify the order in which the functions associated with a particular action are executed (default: 10). Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added to the action
     * @param int $acceptedArgs the number of arguments the function accept (default 1)
     */
    function add_action(string $tag, $functionToAdd, int $priority = 10, int $acceptedArgs = 1)
    {
        \WP_Mock::onActionAdded($tag)->react($functionToAdd, $priority, $acceptedArgs);
    }
}

if (! function_exists('do_action')) {
    /**
     * Execute functions hooked on a specific action hook.
     *
     * @param string $tag     The name of the action to be executed.
     * @param mixed  $arg,... Optional additional arguments which are passed on to the functions hooked to the action.
     *
     * @return null Will return null if $tag does not exist in $wp_filter array
     */
    function do_action($tag, $arg = '')
    {
        $args = func_get_args();
        $args = array_slice($args, 1);

        return \WP_Mock::onAction($tag)->react($args);
    }
}

if (! function_exists('add_filter')) {
    /**
     * Hooks a function on to a specific filter.
     *
     * Filters are the hooks that WordPress uses to alter the value of a variable at specific points during execution.
     * Plugins can specify that one or more of its PHP functions are executed at these points, using the Filter API, to change the value of that variable.
     *
     * @link https://developer.wordpress.org/plugins/hooks/filters/
     *
     * @param string $tag the name of the action to which the $function_to_add is hooked
     * @param string|callable-string|callable $functionToAdd the name of the function you wish to be called
     * @param int $priority optional, used to specify the order in which the functions associated with a particular action are executed (default: 10). Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added to the action
     * @param int $acceptedArgs the number of arguments the function accept (default 1)
     */
    function add_filter(string $tag, $functionToAdd, int $priority = 10, int $acceptedArgs = 1)
    {
        \WP_Mock::onFilterAdded($tag)->react($functionToAdd, $priority, $acceptedArgs);
    }
}

if (! function_exists('apply_filters')) {
    /**
     * Call the functions added to a filter hook.
     *
     * @param string $tag     The name of the filter hook.
     * @param mixed  $value   The value on which the filters hooked to <tt>$tag</tt> are applied on.
     * @param mixed  $var,... Additional variables passed to the functions hooked to <tt>$tag</tt>.
     *
     * @return mixed The filtered value after all hooked functions are applied to it.
     */
    function apply_filters($tag, $value)
    {
        $args    = func_get_args();
        $args    = array_slice($args, 1);
        $args[0] = $value;

        return \WP_Mock::onFilter($tag)->apply($args);
    }
}

if (! function_exists('esc_html')) {
    /**
     * @return string
     */
    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
     */
    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
     */
    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
     */
    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
     */
    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
     */
    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
     */
    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
     */
    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
     */
    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
     */
    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
     */
    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
     */
    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
     */
    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
     */
    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
     */
    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
     */
    function _n() : string
    {
        $args = func_get_args();

        if (count($args) >= 3) {
            /** @phpstan-ignore-next-line */
            if (isset($args[0]) && 1 >= intval($args[2])) {
                /** @phpstan-ignore-next-line */
                return (string) $args[0];
            } else {
                /** @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__));
        }
    }
}

1	<?php
2
3	use PHPUnit\Framework\ExpectationFailedException;
4	use WP_Mock\Functions\Handler;
5
6	if (! function_exists('add_action')) {	×
7	/**
8	* Hooks a function on to a specific action.
9	*
10	* Actions are the hooks that WordPress launches at specific points during execution, or when specific events occur.
11	* Plugins can specify that one or more of its PHP functions are executed at these points, using the Action API.
12	*
13	* @link https://developer.wordpress.org/plugins/hooks/actions/
14	*
15	* @param string $tag the name of the action to which the $function_to_add is hooked
16	* @param string\|callable-string\|callable $functionToAdd the name of the function you wish to be called
17	* @param int $priority optional, used to specify the order in which the functions associated with a particular action are executed (default: 10). Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added to the action
18	* @param int $acceptedArgs the number of arguments the function accept (default 1)
19	*/
20	function add_action(string $tag, $functionToAdd, int $priority = 10, int $acceptedArgs = 1)
21	{
22	\WP_Mock::onActionAdded($tag)->react($functionToAdd, $priority, $acceptedArgs);	×
23	}
24	}
25
26	if (! function_exists('do_action')) {	×
27	/**
28	* Execute functions hooked on a specific action hook.
29	*
30	* @param string $tag The name of the action to be executed.
31	* @param mixed $arg,... Optional additional arguments which are passed on to the functions hooked to the action.
32	*
33	* @return null Will return null if $tag does not exist in $wp_filter array
34	*/
35	function do_action($tag, $arg = '')
36	{
37	$args = func_get_args();	×
38	$args = array_slice($args, 1);	×
39
40	return \WP_Mock::onAction($tag)->react($args);	×
41	}
42	}
43
44	if (! function_exists('add_filter')) {	×
45	/**
46	* Hooks a function on to a specific filter.
47	*
48	* Filters are the hooks that WordPress uses to alter the value of a variable at specific points during execution.
49	* Plugins can specify that one or more of its PHP functions are executed at these points, using the Filter API, to change the value of that variable.
50	*
51	* @link https://developer.wordpress.org/plugins/hooks/filters/
52	*
53	* @param string $tag the name of the action to which the $function_to_add is hooked
54	* @param string\|callable-string\|callable $functionToAdd the name of the function you wish to be called
55	* @param int $priority optional, used to specify the order in which the functions associated with a particular action are executed (default: 10). Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added to the action
56	* @param int $acceptedArgs the number of arguments the function accept (default 1)
57	*/
58	function add_filter(string $tag, $functionToAdd, int $priority = 10, int $acceptedArgs = 1)
59	{
60	\WP_Mock::onFilterAdded($tag)->react($functionToAdd, $priority, $acceptedArgs);	×
61	}
62	}
63
64	if (! function_exists('apply_filters')) {	×
65	/**
66	* Call the functions added to a filter hook.
67	*
68	* @param string $tag The name of the filter hook.
69	* @param mixed $value The value on which the filters hooked to <tt>$tag</tt> are applied on.
70	* @param mixed $var,... Additional variables passed to the functions hooked to <tt>$tag</tt>.
71	*
72	* @return mixed The filtered value after all hooked functions are applied to it.
73	*/
74	function apply_filters($tag, $value)
75	{
76	$args = func_get_args();	×
77	$args = array_slice($args, 1);	×
78	$args[0] = $value;	×
79
80	return \WP_Mock::onFilter($tag)->apply($args);	×
81	}
82	}
83
84	if (! function_exists('esc_html')) {	×
85	/**
86	* @return string
87	*/
88	function esc_html() : string
89	{
90	/** @phpstan-ignore-next-line to prevent flagging the function as throwing exception in codebases requiring WP_Mock */
91	return Handler::handlePredefinedReturnFunction(__FUNCTION__, func_get_args());	1✔
92	}
93	}
94
95	if (! function_exists('esc_attr')) {	×
96	/**
97	* @return string
98	*/
99	function esc_attr() : string
100	{
101	/** @phpstan-ignore-next-line to prevent flagging the function as throwing exception in codebases requiring WP_Mock */
102	return Handler::handlePredefinedReturnFunction(__FUNCTION__, func_get_args());	1✔
103	}
104	}
105
106	if (! function_exists('esc_url')) {	×
107	/**
108	* @return string
109	*/
110	function esc_url() : string
111	{
112	/** @phpstan-ignore-next-line to prevent flagging the function as throwing exception in codebases requiring WP_Mock */
113	return Handler::handlePredefinedReturnFunction(__FUNCTION__, func_get_args());	1✔
114	}
115	}
116
117	if (! function_exists('esc_url_raw')) {	×
118	/**
119	* @return string
120	*/
121	function esc_url_raw() : string
122	{
123	/** @phpstan-ignore-next-line to prevent flagging the function as throwing exception in codebases requiring WP_Mock */
124	return Handler::handlePredefinedReturnFunction(__FUNCTION__, func_get_args());	1✔
125	}
126	}
127
128	if (! function_exists('esc_js')) {	×
129	/**
130	* @return string
131	*/
132	function esc_js() : string
133	{
134	/** @phpstan-ignore-next-line to prevent flagging the function as throwing exception in codebases requiring WP_Mock */
135	return Handler::handlePredefinedReturnFunction(__FUNCTION__, func_get_args());	1✔
136	}
137	}
138
139	if (! function_exists('esc_textarea')) {	×
140	/**
141	* @return string
142	*/
143	function esc_textarea() : string
144	{
145	/** @phpstan-ignore-next-line to prevent flagging the function as throwing exception in codebases requiring WP_Mock */
146	return Handler::handlePredefinedReturnFunction(__FUNCTION__, func_get_args());	1✔
147	}
148	}
149
150	if (! function_exists('__')) {	×
151	/**
152	* @return string
153	*/
154	function __() : string
155	{
156	/** @phpstan-ignore-next-line to prevent flagging the function as throwing exception in codebases requiring WP_Mock */
157	return Handler::handlePredefinedReturnFunction(__FUNCTION__, func_get_args());	1✔
158	}
159	}
160
161	if (! function_exists('_e')) {	×
162	/**
163	* @return void
164	*/
165	function _e() : void
166	{
167	/** @phpstan-ignore-next-line to prevent flagging the function as throwing exception in codebases requiring WP_Mock */
168	Handler::handlePredefinedEchoFunction(__FUNCTION__, func_get_args());	1✔
169	}
170	}
171
172	if (! function_exists('_x')) {	×
173	/**
174	* @return string
175	*/
176	function _x() : string
177	{
178	/** @phpstan-ignore-next-line to prevent flagging the function as throwing exception in codebases requiring WP_Mock */
179	return Handler::handlePredefinedReturnFunction(__FUNCTION__, func_get_args());	1✔
180	}
181	}
182
183	if (! function_exists('esc_html__')) {	×
184	/**
185	* @return string
186	*/
187	function esc_html__() : string
188	{
189	/** @phpstan-ignore-next-line to prevent flagging the function as throwing exception in codebases requiring WP_Mock */
190	return Handler::handlePredefinedReturnFunction(__FUNCTION__, func_get_args());	1✔
191	}
192	}
193
194	if (! function_exists('esc_html_e')) {	×
195	/**
196	* @return void
197	*/
198	function esc_html_e() : void
199	{
200	/** @phpstan-ignore-next-line to prevent flagging the function as throwing exception in codebases requiring WP_Mock */
201	Handler::handlePredefinedEchoFunction(__FUNCTION__, func_get_args());	1✔
202	}
203	}
204
205	if (! function_exists('esc_html_x')) {	×
206	/**
207	* @return string
208	*/
209	function esc_html_x() : string
210	{
211	/** @phpstan-ignore-next-line to prevent flagging the function as throwing exception in codebases requiring WP_Mock */
UNCOV 212	return Handler::handlePredefinedReturnFunction(__FUNCTION__, func_get_args());	×
213	}
214	}
215
216	if (! function_exists('esc_attr__')) {	×
217	/**
218	* @return string
219	*/
220	function esc_attr__() : string
221	{
222	/** @phpstan-ignore-next-line to prevent flagging the function as throwing exception in codebases requiring WP_Mock */
223	return Handler::handlePredefinedReturnFunction(__FUNCTION__, func_get_args());	1✔
224	}
225	}
226
227	if (! function_exists('esc_attr_e')) {	×
228	/**
229	* @return void
230	*/
231	function esc_attr_e() : void
232	{
233	/** @phpstan-ignore-next-line to prevent flagging the function as throwing exception in codebases requiring WP_Mock */
234	Handler::handlePredefinedEchoFunction(__FUNCTION__, func_get_args());	1✔
235	}
236	}
237
238	if (! function_exists('esc_attr_x')) {	×
239	/**
240	* @return string
241	*/
242	function esc_attr_x() : string
243	{
244	/** @phpstan-ignore-next-line to prevent flagging the function as throwing exception in codebases requiring WP_Mock */
245	return Handler::handlePredefinedReturnFunction(__FUNCTION__, func_get_args());	1✔
246	}
247	}
248
249	if (! function_exists('_n')) {	×
250	/**
251	* @return string
252	*/
253	function _n() : string
254	{
255	$args = func_get_args();	1✔
256
257	if (count($args) >= 3) {	1✔
258	/** @phpstan-ignore-next-line */
259	if (isset($args[0]) && 1 >= intval($args[2])) {	1✔
260	/** @phpstan-ignore-next-line */
261	return (string) $args[0];	1✔
262	} else {
263	/** @phpstan-ignore-next-line */
264	return (string) $args[1];	1✔
265	}
266	} else {
267	/** @phpstan-ignore-next-line to prevent flagging the function as throwing exception in codebases requiring WP_Mock */
UNCOV 268	throw new ExpectationFailedException(sprintf('Too few arguments to function %s', __FUNCTION__));	×
269	}
270	}
271	}

10up / wp_mock / 9711864001

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous