9975227369

Committed 17 Jul 2024 01:31PM UTC coverage: 97.405%. Remained the same

Build # 9975227369

Build Type

push

github

Committed by

jrfnl

Commit Message

AssertObjectNotEquals trait: polyfill the Assert::assertObjectNotEquals() method

PHPUnit 11.2.0 introduced the new `Assert::assertObjectNotEquals()` method.

This commit:
* Adds two traits with the same name.
    One to polyfill the method when not available in PHPUnit.
    The other to allow for `use`-ing the trait in PHPUnit versions in which the method is already natively available.
* Logic to the custom autoloader which will load the correct trait depending on the PHPUnit version used.
* Adds tests.

As the polyfill contains logic to match the PHPUnit native implementation as closely as possible, while still being PHP and PHPUnit cross-version compatible, extensive unit tests have been added to ensure the behaviour of the polyfill matches that of the original function.

Includes:
* Adding information on the new polyfill to the README.
* Adding the new polyfill to the existing `TestCases` classes.
* Updating the class docs for the `InvalidComparisonMethodException` and the `ComparatorValidator` classes.

Refs:
* https://github.com/sebastianbergmann/phpunit/issues/5811
* https://github.com/sebastianbergmann/phpunit/commit/8e3b7c185

Co-authored-by: Sebastian Bergmann <sb@sebastian-bergmann.de>

Run Details

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

2 existing lines in 1 file now uncovered.

638 of 655 relevant lines covered (97.4%)

149.75 hits per line

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

97.06

/src/Helpers/ComparatorValidator.php

<?php

namespace Yoast\PHPUnitPolyfills\Helpers;

use ReflectionNamedType;
use ReflectionObject;
use ReflectionType;
use Yoast\PHPUnitPolyfills\Exceptions\InvalidComparisonMethodException;

/**
 * Helper functions for validating a comparator method complies with the requirements set by PHPUnit.
 *
 * ---------------------------------------------------------------------------------------------
 * This class is only intended for internal use by PHPUnit Polyfills and is not part of the public API.
 * This also means that it has no promise of backward compatibility.
 *
 * End-users should use the {@see \Yoast\PHPUnitPolyfills\Polyfills\AssertObjectEquals} and/or the
 * {@see \Yoast\PHPUnitPolyfills\Polyfills\AssertObjectNotEquals} trait instead.
 * ---------------------------------------------------------------------------------------------
 *
 * @internal
 */
final class ComparatorValidator {
        
        /**
         * Asserts that a custom object comparison method complies with the requirements set by PHPUnit.
         *
         * The custom comparator method is expected to have the following method
         * signature: `equals(self $other): bool` (or similar with a different method name).
         *
         * Basically, this method checks the following:
         * - A method with name $method must exist on the $actual object.
         * - The method must accept exactly one argument and this argument must be required.
         * - This parameter must have a classname-based declared type.
         * - The $expected object must be compatible with this declared type.
         * - The method must have a declared bool return type.
         *
         * {@internal Type validation for the parameters should be done in the calling function.}
         *
         * @param object $expected Expected value.
         *                         This object should comply with the type requirement set by the parameter type
         *                         of the comparator method on $actual.
         * @param object $actual   The object on which the comparator method should exist.
         * @param string $method   The name of the comparator method expected within the object.
         *
         * @return void
         *
         * @throws InvalidComparisonMethodException When the comparator method does not comply with the requirements.
         */
        public static function isValid( $expected, $actual, $method = 'equals' ) {
                /*
                 * Verify the method exists.
                 */
                $reflObject = new ReflectionObject( $actual );

                if ( $reflObject->hasMethod( $method ) === false ) {
                        throw new InvalidComparisonMethodException(
                                \sprintf(
                                        'Comparison method %s::%s() does not exist.',
                                        \get_class( $actual ),
                                        $method
                                )
                        );
                }

                $reflMethod = $reflObject->getMethod( $method );

                /*
                 * Comparator method return type requirements validation.
                 */
                $returnTypeError = \sprintf(
                        'Comparison method %s::%s() does not declare bool return type.',
                        \get_class( $actual ),
                        $method
                );

                if ( $reflMethod->hasReturnType() === false ) {
                        throw new InvalidComparisonMethodException( $returnTypeError );
                }

                $returnType = $reflMethod->getReturnType();

                if ( \class_exists( 'ReflectionNamedType' ) ) {
                        // PHP >= 7.1: guard against union/intersection return types.
                        if ( ( $returnType instanceof ReflectionNamedType ) === false ) {
                                throw new InvalidComparisonMethodException( $returnTypeError );
                        }
                }
                elseif ( ( $returnType instanceof ReflectionType ) === false ) {
                        /*
                         * PHP 7.0.
                         * Checking for `ReflectionType` will not throw an error on union types,
                         * but then again union types are not supported on PHP 7.0.
                         */
                        throw new InvalidComparisonMethodException( $returnTypeError );
                }

                if ( $returnType->allowsNull() === true ) {
                        throw new InvalidComparisonMethodException( $returnTypeError );
                }

                if ( \method_exists( $returnType, 'getName' ) ) {
                        // PHP >= 7.1.
                        if ( $returnType->getName() !== 'bool' ) {
                                throw new InvalidComparisonMethodException( $returnTypeError );
                        }
                }
                elseif ( (string) $returnType !== 'bool' ) {
                        // PHP 7.0.
                        throw new InvalidComparisonMethodException( $returnTypeError );
                }

                /*
                 * Comparator method parameter requirements validation.
                 */
                if ( $reflMethod->getNumberOfParameters() !== 1
                        || $reflMethod->getNumberOfRequiredParameters() !== 1
                ) {
                        throw new InvalidComparisonMethodException(
                                \sprintf(
                                        'Comparison method %s::%s() does not declare exactly one parameter.',
                                        \get_class( $actual ),
                                        $method
                                )
                        );
                }

                $noDeclaredTypeError = \sprintf(
                        'Parameter of comparison method %s::%s() does not have a declared type.',
                        \get_class( $actual ),
                        $method
                );

                $notAcceptableTypeError = \sprintf(
                        '%s is not an accepted argument type for comparison method %s::%s().',
                        \get_class( $expected ),
                        \get_class( $actual ),
                        $method
                );

                $reflParameter = $reflMethod->getParameters()[0];

                $hasType = $reflParameter->hasType();
                if ( $hasType === false ) {
                        throw new InvalidComparisonMethodException( $noDeclaredTypeError );
                }

                $type = $reflParameter->getType();
                if ( \class_exists( 'ReflectionNamedType' ) ) {
                        // PHP >= 7.1.
                        if ( ( $type instanceof ReflectionNamedType ) === false ) {
                                throw new InvalidComparisonMethodException( $noDeclaredTypeError );
                        }

                        $typeName = $type->getName();
                }
                else {
                        /*
                         * PHP 7.0.
                         * Checking for `ReflectionType` will not throw an error on union types,
                         * but then again union types are not supported on PHP 7.0.
                         */
                        if ( ( $type instanceof ReflectionType ) === false ) {
                                throw new InvalidComparisonMethodException( $noDeclaredTypeError );
                        }

                        $typeName = (string) $type;
                }

                /*
                 * Validate that the $expected object complies with the declared parameter type.
                 */
                if ( $typeName === 'self' ) {
                        $typeName = \get_class( $actual );
                }

                if ( ( $expected instanceof $typeName ) === false ) {
                        throw new InvalidComparisonMethodException( $notAcceptableTypeError );
                }
        }
}

1	<?php
2
3	namespace Yoast\PHPUnitPolyfills\Helpers;
4
5	use ReflectionNamedType;
6	use ReflectionObject;
7	use ReflectionType;
8	use Yoast\PHPUnitPolyfills\Exceptions\InvalidComparisonMethodException;
9
10	/**
11	* Helper functions for validating a comparator method complies with the requirements set by PHPUnit.
12	*
13	* ---------------------------------------------------------------------------------------------
14	* This class is only intended for internal use by PHPUnit Polyfills and is not part of the public API.
15	* This also means that it has no promise of backward compatibility.
16	*
17	* End-users should use the {@see \Yoast\PHPUnitPolyfills\Polyfills\AssertObjectEquals} and/or the
18	* {@see \Yoast\PHPUnitPolyfills\Polyfills\AssertObjectNotEquals} trait instead.
19	* ---------------------------------------------------------------------------------------------
20	*
21	* @internal
22	*/
23	final class ComparatorValidator {
24
25	/**
26	* Asserts that a custom object comparison method complies with the requirements set by PHPUnit.
27	*
28	* The custom comparator method is expected to have the following method
29	* signature: `equals(self $other): bool` (or similar with a different method name).
30	*
31	* Basically, this method checks the following:
32	* - A method with name $method must exist on the $actual object.
33	* - The method must accept exactly one argument and this argument must be required.
34	* - This parameter must have a classname-based declared type.
35	* - The $expected object must be compatible with this declared type.
36	* - The method must have a declared bool return type.
37	*
38	* {@internal Type validation for the parameters should be done in the calling function.}
39	*
40	* @param object $expected Expected value.
41	* This object should comply with the type requirement set by the parameter type
42	* of the comparator method on $actual.
43	* @param object $actual The object on which the comparator method should exist.
44	* @param string $method The name of the comparator method expected within the object.
45	*
46	* @return void
47	*
48	* @throws InvalidComparisonMethodException When the comparator method does not comply with the requirements.
49	*/
50	public static function isValid( $expected, $actual, $method = 'equals' ) {	698✔
51	/*
52	* Verify the method exists.
53	*/
54	$reflObject = new ReflectionObject( $actual );	698✔
55
56	if ( $reflObject->hasMethod( $method ) === false ) {	698✔
57	throw new InvalidComparisonMethodException(	44✔
58	\sprintf(	44✔
59	'Comparison method %s::%s() does not exist.',	44✔
60	\get_class( $actual ),	44✔
61	$method	44✔
62	)	18✔
63	);	18✔
64	}
65
66	$reflMethod = $reflObject->getMethod( $method );	654✔
67
68	/*
69	* Comparator method return type requirements validation.
70	*/
71	$returnTypeError = \sprintf(	654✔
72	'Comparison method %s::%s() does not declare bool return type.',	654✔
73	\get_class( $actual ),	654✔
74	$method	654✔
75	);	272✔
76
77	if ( $reflMethod->hasReturnType() === false ) {	654✔
78	throw new InvalidComparisonMethodException( $returnTypeError );	44✔
79	}
80
81	$returnType = $reflMethod->getReturnType();	610✔
82
83	if ( \class_exists( 'ReflectionNamedType' ) ) {	610✔
84	// PHP >= 7.1: guard against union/intersection return types.
85	if ( ( $returnType instanceof ReflectionNamedType ) === false ) {	562✔
86	throw new InvalidComparisonMethodException( $returnTypeError );	469✔
87	}
88	}
89	elseif ( ( $returnType instanceof ReflectionType ) === false ) {	48✔
90	/*
91	* PHP 7.0.
92	* Checking for `ReflectionType` will not throw an error on union types,
93	* but then again union types are not supported on PHP 7.0.
94	*/
UNCOV 95	throw new InvalidComparisonMethodException( $returnTypeError );	×
96	}
97
98	if ( $returnType->allowsNull() === true ) {	602✔
99	throw new InvalidComparisonMethodException( $returnTypeError );	33✔
100	}
101
102	if ( \method_exists( $returnType, 'getName' ) ) {	569✔
103	// PHP >= 7.1.
104	if ( $returnType->getName() !== 'bool' ) {	521✔
105	throw new InvalidComparisonMethodException( $returnTypeError );	438✔
106	}
107	}
108	elseif ( (string) $returnType !== 'bool' ) {	48✔
109	// PHP 7.0.
110	throw new InvalidComparisonMethodException( $returnTypeError );	4✔
111	}
112
113	/*
114	* Comparator method parameter requirements validation.
115	*/
116	if ( $reflMethod->getNumberOfParameters() !== 1	525✔
117	\|\| $reflMethod->getNumberOfRequiredParameters() !== 1	525✔
118	) {
119	throw new InvalidComparisonMethodException(	77✔
120	\sprintf(	77✔
121	'Comparison method %s::%s() does not declare exactly one parameter.',	77✔
122	\get_class( $actual ),	77✔
123	$method	77✔
124	)	29✔
125	);	29✔
126	}
127
128	$noDeclaredTypeError = \sprintf(	448✔
129	'Parameter of comparison method %s::%s() does not have a declared type.',	448✔
130	\get_class( $actual ),	448✔
131	$method	448✔
132	);	188✔
133
134	$notAcceptableTypeError = \sprintf(	448✔
135	'%s is not an accepted argument type for comparison method %s::%s().',	448✔
136	\get_class( $expected ),	448✔
137	\get_class( $actual ),	448✔
138	$method	448✔
139	);	188✔
140
141	$reflParameter = $reflMethod->getParameters()[0];	448✔
142
143	$hasType = $reflParameter->hasType();	448✔
144	if ( $hasType === false ) {	448✔
145	throw new InvalidComparisonMethodException( $noDeclaredTypeError );	44✔
146	}
147
148	$type = $reflParameter->getType();	404✔
149	if ( \class_exists( 'ReflectionNamedType' ) ) {	404✔
150	// PHP >= 7.1.
151	if ( ( $type instanceof ReflectionNamedType ) === false ) {	368✔
152	throw new InvalidComparisonMethodException( $noDeclaredTypeError );	8✔
153	}
154
155	$typeName = $type->getName();	360✔
156	}
157	else {
158	/*
159	* PHP 7.0.
160	* Checking for `ReflectionType` will not throw an error on union types,
161	* but then again union types are not supported on PHP 7.0.
162	*/
163	if ( ( $type instanceof ReflectionType ) === false ) {	36✔
UNCOV 164	throw new InvalidComparisonMethodException( $noDeclaredTypeError );	×
165	}
166
167	$typeName = (string) $type;	36✔
168	}
169
170	/*
171	* Validate that the $expected object complies with the declared parameter type.
172	*/
173	if ( $typeName === 'self' ) {	396✔
174	$typeName = \get_class( $actual );	220✔
175	}
176
177	if ( ( $expected instanceof $typeName ) === false ) {	396✔
178	throw new InvalidComparisonMethodException( $notAcceptableTypeError );	132✔
179	}
180	}	156✔
181	}

Yoast / PHPUnit-Polyfills / 9975227369

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