30195550424

Committed 26 Jul 2026 08:56AM UTC coverage: 91.369% (-1.0%) from 92.38%

Build # 30195550424

Build Type

Pull #177

github

Committed by

web-flow

Commit Message

Merge 142e5e39f into 57c7fca16

Pull Request Pull Request #177: Add PHPStan return-type extensions, tighten typing, fix dot-notation edge cases, and update docs/tests

Coverage Stats

31 of 85 new or added lines in 4 files covered. (36.47%)

1 existing line in 1 file now uncovered.

2784 of 3047 relevant lines covered (91.37%)

246.75 hits per line

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

83.33

/src/TypeCheck/TypeCheckPhpDoc.php

<?php

/** @noinspection TransitiveDependenciesUsageInspection */
/** @noinspection ClassReImplementsParentInterfaceInspection */

declare(strict_types=1);

namespace Arrayy\TypeCheck;

/**
 * inspired by https://github.com/spatie/value-object
 *
 * @internal
 */
final class TypeCheckPhpDoc extends AbstractTypeCheck implements TypeCheckInterface
{
    /**
     * @var string
     */
    private $property_name;

    /**
     * @param string $reflectionPropertyName
     */
    public function __construct($reflectionPropertyName)
    {
        $this->property_name = $reflectionPropertyName;
    }

    /**
     * @param \phpDocumentor\Reflection\DocBlock\Tags\Property $phpDocumentorReflectionProperty
     * @param string                                           $property
     *
     * @return self|null
     */
    public static function fromPhpDocumentorProperty(\phpDocumentor\Reflection\DocBlock\Tags\Property $phpDocumentorReflectionProperty, string $property = '')
    {
        if (!$property) {
            /** @var string|null $propertyTmp */
            $propertyTmp = $phpDocumentorReflectionProperty->getVariableName();
            if ($propertyTmp === null) {
                return null;
            }

            $property = $propertyTmp;
        }

        return self::fromDocTypeObject($property, $phpDocumentorReflectionProperty->getType());
    }

    /**
     * Create a type checker from a phpDocumentor type object and an explicit property name.
     *
     * @param string                              $property
     * @param \phpDocumentor\Reflection\Type|null $type
     *
     * @phpstan-param \phpDocumentor\Reflection\Type|null $type
     *
     * @return self
     */
    public static function fromDocTypeObject(string $property, $type)
    {
        $tmpReflection = new self($property);

        if ($type) {
            $docTypes = self::parseDocTypeObject($type);
            if (\is_array($docTypes) === true) {
                foreach ($docTypes as $docType) {
                    $tmpReflection->types[] = $docType;
                }
            } else {
                $tmpReflection->types[] = $docTypes;
            }

            if (\in_array('null', $tmpReflection->types, true)) {
                $tmpReflection->isNullable = true;
            }
        }

        return $tmpReflection;
    }

    public static function fromReflectionProperty(\ReflectionProperty $reflectionProperty): self
    {
        $tmpReflection = new self($reflectionProperty->getName());
        $type = $reflectionProperty->getType();
        $docTypes = self::getTypesFromReflectionPropertyDocBlock($reflectionProperty);

        if ($docTypes !== null) {
            if (\is_array($docTypes) === true) {
                foreach ($docTypes as $docType) {
                    $tmpReflection->types[] = $docType;
                }
            } else {
                $tmpReflection->types[] = $docTypes;
            }
        } elseif ($type === null) {
            $tmpReflection->types[] = 'mixed';
            $tmpReflection->isNullable = true;

            return $tmpReflection;
        } else {
            $docTypes = self::parseReflectionTypeObject($type);
            if (\is_array($docTypes) === true) {
                foreach ($docTypes as $docType) {
                    $tmpReflection->types[] = $docType;
                }
            } else {
                $tmpReflection->types[] = $docTypes;
            }
        }

        if ($type !== null && self::typeAllowsNull($type) && \in_array('null', $tmpReflection->types, true) === false) {
            $tmpReflection->types[] = 'null';
        }

        if (\in_array('null', $tmpReflection->types, true)) {
            $tmpReflection->isNullable = true;
        }

        return $tmpReflection;
    }

    /**
     * @param \phpDocumentor\Reflection\Type $type
     *
     * @return string|string[]
     */
    public static function parseDocTypeObject($type)
    {
        if ($type instanceof \phpDocumentor\Reflection\Types\Object_) {
            $tmpObject = (string) $type->getFqsen();
            if ($tmpObject) {
                return $tmpObject;
            }

            return 'object';
        }

        if ($type instanceof \phpDocumentor\Reflection\Types\Compound) {
            $types = [];
            foreach ($type as $subType) {
                $typeTmp = self::parseDocTypeObject($subType);

                /** @noinspection PhpSillyAssignmentInspection - hack for phpstan */
                /** @var string $typeTmp */
                $typeTmp = $typeTmp;

                $types[] = $typeTmp;
            }

            return $types;
        }

        if ($type instanceof \phpDocumentor\Reflection\Types\Nullable) {
            $typeTmp = self::parseDocTypeObject($type->getActualType());
            if (\is_array($typeTmp) === true) {
                $typeTmp[] = 'null';

                return $typeTmp;
            }

            return [$typeTmp, 'null'];
        }

        if (
            \class_exists('\phpDocumentor\Reflection\PseudoTypes\ArrayShape')
            &&
            $type instanceof \phpDocumentor\Reflection\PseudoTypes\ArrayShape
        ) {
            return 'array';
        }

        if ($type instanceof \phpDocumentor\Reflection\Types\Array_) {
            $valueTypeTmp = $type->getValueType()->__toString();
            if ($valueTypeTmp !== 'mixed') {
                return $valueTypeTmp . '[]';
            }

            return 'array';
        }

        if ($type instanceof \phpDocumentor\Reflection\Types\Null_) {
            return 'null';
        }

        if ($type instanceof \phpDocumentor\Reflection\Types\Mixed_) {
            return 'mixed';
        }

        foreach (self::getScalarPseudoTypeClasses() as $scalarTypeClass) {
            if ($type instanceof $scalarTypeClass) {
                return 'string|int|float|bool';
            }
        }

        if ($type instanceof \phpDocumentor\Reflection\Types\Boolean) {
            return 'bool';
        }

        if ($type instanceof \phpDocumentor\Reflection\Types\Callable_) {
            return 'callable';
        }

        if ($type instanceof \phpDocumentor\Reflection\Types\Float_) {
            return 'float';
        }

        if ($type instanceof \phpDocumentor\Reflection\Types\String_) {
            return 'string';
        }

        if ($type instanceof \phpDocumentor\Reflection\Types\Integer) {
            return 'int';
        }

        if ($type instanceof \phpDocumentor\Reflection\Types\Void_) {
            return 'void';
        }

        if ($type instanceof \phpDocumentor\Reflection\Types\Resource_) {
            return 'resource';
        }

        return $type->__toString();
    }

    /**
     * @return list<class-string>
     */
    private static function getScalarPseudoTypeClasses(): array
    {
        $classes = [];

        if (\class_exists(\phpDocumentor\Reflection\PseudoTypes\Scalar::class)) {
            $classes[] = \phpDocumentor\Reflection\PseudoTypes\Scalar::class;
        }

        if (\class_exists(\phpDocumentor\Reflection\Types\Scalar::class)) {
            $classes[] = \phpDocumentor\Reflection\Types\Scalar::class;
        }

        return $classes;
    }

    /**
     * @return string|string[]|null
     */
    private static function getTypesFromReflectionPropertyDocBlock(\ReflectionProperty $reflectionProperty)
    {
        $docComment = $reflectionProperty->getDocComment();
        if ($docComment === false) {
            return null;
        }

        /** @var \phpDocumentor\Reflection\DocBlockFactoryInterface|null $factory cache factory to avoid recreating it per reflected property */
        static $factory = null;
        if ($factory === null) {
            $factory = \phpDocumentor\Reflection\DocBlockFactory::createInstance();
        }
        $docblock = $factory->create($docComment);
        foreach ($docblock->getTagsByName('var') as $tag) {
            if (!$tag instanceof \phpDocumentor\Reflection\DocBlock\Tags\Var_) {
                continue;
            }

            /** @var \phpDocumentor\Reflection\Type|null $type */
            $type = $tag->getType();
            if ($type === null) {
                continue;
            }

            return self::parseDocTypeObject($type);
        }

        return null;
    }

    private static function typeAllowsNull(\ReflectionType $type): bool
    {
        if (
            \class_exists(\ReflectionIntersectionType::class)
            &&
            $type instanceof \ReflectionIntersectionType
        ) {
            return false;
        }

        return $type->allowsNull();
    }

    /**
     * @param \ReflectionType $type
     *
     * @return string|string[]
     */
    public static function parseReflectionTypeObject(\ReflectionType $type)
    {
        if ($type instanceof \ReflectionNamedType) {
            $typeName = $type->getName();

            if ($type->isBuiltin()) {
                return $typeName;
            }

            return '\\' . \ltrim($typeName, '\\');
        }

        if ($type instanceof \ReflectionUnionType) {
            $types = [];
            foreach ($type->getTypes() as $subType) {
                $typeTmp = self::parseReflectionTypeObject($subType);
                if (\is_array($typeTmp)) {
                    foreach ($typeTmp as $typeTmpInner) {
                        $types[] = $typeTmpInner;
                    }
                } else {
                    $types[] = $typeTmp;
                }
            }

            return $types;
        }

        if (
            \class_exists(\ReflectionIntersectionType::class)
            &&
            $type instanceof \ReflectionIntersectionType
        ) {
            $types = [];
            foreach ($type->getTypes() as $subType) {
                $typeTmp = self::parseReflectionTypeObject($subType);
                if (\is_array($typeTmp)) {
                    foreach ($typeTmp as $typeTmpInner) {
                        $types[] = $typeTmpInner;
                    }
                } else {
                    $types[] = $typeTmp;
                }
            }

            return \implode('&', $types);
        }

        return (string) $type;
    }

    /**
     * @param string $expectedTypes
     * @param mixed  $value
     * @param string $type
     *
     * @return \TypeError
     */
    public function throwException($expectedTypes, $value, $type): \Throwable
    {
        throw new \TypeError("Invalid type: expected \"{$this->property_name}\" to be of type {{$expectedTypes}}, instead got value \"" . $this->valueToString($value) . '" (' . \print_r($value, true) . ") with type {{$type}}.");
    }
}

1	<?php
2
3	/** @noinspection TransitiveDependenciesUsageInspection */
4	/** @noinspection ClassReImplementsParentInterfaceInspection */
5
6	declare(strict_types=1);
7
8	namespace Arrayy\TypeCheck;
9
10	/**
11	* inspired by https://github.com/spatie/value-object
12	*
13	* @internal
14	*/
15	final class TypeCheckPhpDoc extends AbstractTypeCheck implements TypeCheckInterface
16	{
17	/**
18	* @var string
19	*/
20	private $property_name;
21
22	/**
23	* @param string $reflectionPropertyName
24	*/
25	public function __construct($reflectionPropertyName)
26	{
27	$this->property_name = $reflectionPropertyName;	187✔
28	}
29
30	/**
31	* @param \phpDocumentor\Reflection\DocBlock\Tags\Property $phpDocumentorReflectionProperty
32	* @param string $property
33	*
34	* @return self\|null
35	*/
36	public static function fromPhpDocumentorProperty(\phpDocumentor\Reflection\DocBlock\Tags\Property $phpDocumentorReflectionProperty, string $property = '')
37	{
38	if (!$property) {	56✔
39	/** @var string\|null $propertyTmp */
40	$propertyTmp = $phpDocumentorReflectionProperty->getVariableName();	14✔
41	if ($propertyTmp === null) {	14✔
42	return null;	×
43	}
44
45	$property = $propertyTmp;	14✔
46	}
47
48	return self::fromDocTypeObject($property, $phpDocumentorReflectionProperty->getType());	56✔
49	}
50
51	/**
52	* Create a type checker from a phpDocumentor type object and an explicit property name.
53	*
54	* @param string $property
55	* @param \phpDocumentor\Reflection\Type\|null $type
56	*
57	* @phpstan-param \phpDocumentor\Reflection\Type\|null $type
58	*
59	* @return self
60	*/
61	public static function fromDocTypeObject(string $property, $type)
62	{
63	$tmpReflection = new self($property);	140✔
64
65	if ($type) {	140✔
66	$docTypes = self::parseDocTypeObject($type);	133✔
67	if (\is_array($docTypes) === true) {	133✔
68	foreach ($docTypes as $docType) {	42✔
69	$tmpReflection->types[] = $docType;	42✔
70	}
71	} else {
72	$tmpReflection->types[] = $docTypes;	126✔
73	}
74
75	if (\in_array('null', $tmpReflection->types, true)) {	133✔
76	$tmpReflection->isNullable = true;	49✔
77	}
78	}
79
80	return $tmpReflection;	140✔
81	}
82
83	public static function fromReflectionProperty(\ReflectionProperty $reflectionProperty): self
84	{
85	$tmpReflection = new self($reflectionProperty->getName());	47✔
86	$type = $reflectionProperty->getType();	47✔
87	$docTypes = self::getTypesFromReflectionPropertyDocBlock($reflectionProperty);	47✔
88
89	if ($docTypes !== null) {	47✔
90	if (\is_array($docTypes) === true) {	33✔
91	foreach ($docTypes as $docType) {	7✔
92	$tmpReflection->types[] = $docType;	7✔
93	}
94	} else {
95	$tmpReflection->types[] = $docTypes;	29✔
96	}
97	} elseif ($type === null) {	28✔
98	$tmpReflection->types[] = 'mixed';	7✔
99	$tmpReflection->isNullable = true;	7✔
100
101	return $tmpReflection;	7✔
102	} else {
103	$docTypes = self::parseReflectionTypeObject($type);	21✔
104	if (\is_array($docTypes) === true) {	21✔
105	foreach ($docTypes as $docType) {	14✔
106	$tmpReflection->types[] = $docType;	14✔
107	}
108	} else {
109	$tmpReflection->types[] = $docTypes;	21✔
110	}
111	}
112
113	if ($type !== null && self::typeAllowsNull($type) && \in_array('null', $tmpReflection->types, true) === false) {	40✔
114	$tmpReflection->types[] = 'null';	21✔
115	}
116
117	if (\in_array('null', $tmpReflection->types, true)) {	40✔
118	$tmpReflection->isNullable = true;	21✔
119	}
120
121	return $tmpReflection;	40✔
122	}
123
124	/**
125	* @param \phpDocumentor\Reflection\Type $type
126	*
127	* @return string\|string[]
128	*/
129	public static function parseDocTypeObject($type)
130	{
131	if ($type instanceof \phpDocumentor\Reflection\Types\Object_) {	166✔
132	$tmpObject = (string) $type->getFqsen();	56✔
133	if ($tmpObject) {	56✔
134	return $tmpObject;	56✔
135	}
136
137	return 'object';	×
138	}
139
140	if ($type instanceof \phpDocumentor\Reflection\Types\Compound) {	152✔
141	$types = [];	42✔
142	foreach ($type as $subType) {	42✔
143	$typeTmp = self::parseDocTypeObject($subType);	42✔
144
145	/** @noinspection PhpSillyAssignmentInspection - hack for phpstan */
146	/** @var string $typeTmp */
147	$typeTmp = $typeTmp;	42✔
148
149	$types[] = $typeTmp;	42✔
150	}
151
152	return $types;	42✔
153	}
154
155	if ($type instanceof \phpDocumentor\Reflection\Types\Nullable) {	152✔
156	$typeTmp = self::parseDocTypeObject($type->getActualType());	7✔
157	if (\is_array($typeTmp) === true) {	7✔
158	$typeTmp[] = 'null';	×
159
160	return $typeTmp;	×
161	}
162
163	return [$typeTmp, 'null'];	7✔
164	}
165
166	if (
167	\class_exists('\phpDocumentor\Reflection\PseudoTypes\ArrayShape')	145✔
168	&&
169	$type instanceof \phpDocumentor\Reflection\PseudoTypes\ArrayShape	145✔
170	) {
171	return 'array';	7✔
172	}
173
174	if ($type instanceof \phpDocumentor\Reflection\Types\Array_) {	138✔
175	$valueTypeTmp = $type->getValueType()->__toString();	49✔
176	if ($valueTypeTmp !== 'mixed') {	49✔
177	return $valueTypeTmp . '[]';	49✔
178	}
179
180	return 'array';	×
181	}
182
183	if ($type instanceof \phpDocumentor\Reflection\Types\Null_) {	124✔
184	return 'null';	42✔
185	}
186
187	if ($type instanceof \phpDocumentor\Reflection\Types\Mixed_) {	124✔
188	return 'mixed';	7✔
189	}
190
191	foreach (self::getScalarPseudoTypeClasses() as $scalarTypeClass) {	124✔
192	if ($type instanceof $scalarTypeClass) {	124✔
193	return 'string\|int\|float\|bool';	21✔
194	}
195	}
196
197	if ($type instanceof \phpDocumentor\Reflection\Types\Boolean) {	117✔
198	return 'bool';	7✔
199	}
200
201	if ($type instanceof \phpDocumentor\Reflection\Types\Callable_) {	117✔
202	return 'callable';	7✔
203	}
204
205	if ($type instanceof \phpDocumentor\Reflection\Types\Float_) {	110✔
206	return 'float';	7✔
207	}
208
209	if ($type instanceof \phpDocumentor\Reflection\Types\String_) {	110✔
210	return 'string';	63✔
211	}
212
213	if ($type instanceof \phpDocumentor\Reflection\Types\Integer) {	82✔
214	return 'int';	70✔
215	}
216
217	if ($type instanceof \phpDocumentor\Reflection\Types\Void_) {	12✔
218	return 'void';	×
219	}
220
221	if ($type instanceof \phpDocumentor\Reflection\Types\Resource_) {	12✔
222	return 'resource';	7✔
223	}
224
225	return $type->__toString();	5✔
226	}
227
228	/**
229	* @return list<class-string>
230	*/
231	private static function getScalarPseudoTypeClasses(): array
232	{
233	$classes = [];	124✔
234
235	if (\class_exists(\phpDocumentor\Reflection\PseudoTypes\Scalar::class)) {	124✔
236	$classes[] = \phpDocumentor\Reflection\PseudoTypes\Scalar::class;	124✔
237	}
238
239	if (\class_exists(\phpDocumentor\Reflection\Types\Scalar::class)) {	124✔
NEW 240	$classes[] = \phpDocumentor\Reflection\Types\Scalar::class;	×
241	}
242
243	return $classes;	124✔
244	}
245
246	/**
247	* @return string\|string[]\|null
248	*/
249	private static function getTypesFromReflectionPropertyDocBlock(\ReflectionProperty $reflectionProperty)
250	{
251	$docComment = $reflectionProperty->getDocComment();	47✔
252	if ($docComment === false) {	47✔
253	return null;	28✔
254	}
255
256	/** @var \phpDocumentor\Reflection\DocBlockFactoryInterface\|null $factory cache factory to avoid recreating it per reflected property */
257	static $factory = null;	33✔
258	if ($factory === null) {	33✔
259	$factory = \phpDocumentor\Reflection\DocBlockFactory::createInstance();	7✔
260	}
261	$docblock = $factory->create($docComment);	33✔
262	foreach ($docblock->getTagsByName('var') as $tag) {	33✔
263	if (!$tag instanceof \phpDocumentor\Reflection\DocBlock\Tags\Var_) {	33✔
264	continue;	×
265	}
266
267	/** @var \phpDocumentor\Reflection\Type\|null $type */
268	$type = $tag->getType();	33✔
269	if ($type === null) {	33✔
270	continue;	×
271	}
272
273	return self::parseDocTypeObject($type);	33✔
274	}
275
276	return null;	×
277	}
278
279	private static function typeAllowsNull(\ReflectionType $type): bool
280	{
281	if (
282	\class_exists(\ReflectionIntersectionType::class)	33✔
283	&&
284	$type instanceof \ReflectionIntersectionType	33✔
285	) {
286	return false;	5✔
287	}
288
289	return $type->allowsNull();	28✔
290	}
291
292	/**
293	* @param \ReflectionType $type
294	*
295	* @return string\|string[]
296	*/
297	public static function parseReflectionTypeObject(\ReflectionType $type)
298	{
299	if ($type instanceof \ReflectionNamedType) {	21✔
300	$typeName = $type->getName();	21✔
301
302	if ($type->isBuiltin()) {	21✔
303	return $typeName;	21✔
304	}
305
306	return '\\' . \ltrim($typeName, '\\');	14✔
307	}
308
309	if ($type instanceof \ReflectionUnionType) {	14✔
310	$types = [];	14✔
311	foreach ($type->getTypes() as $subType) {	14✔
312	$typeTmp = self::parseReflectionTypeObject($subType);	14✔
313	if (\is_array($typeTmp)) {	14✔
314	foreach ($typeTmp as $typeTmpInner) {	×
315	$types[] = $typeTmpInner;	×
316	}
317	} else {
318	$types[] = $typeTmp;	14✔
319	}
320	}
321
322	return $types;	14✔
323	}
324
325	if (
326	\class_exists(\ReflectionIntersectionType::class)	×
327	&&
328	$type instanceof \ReflectionIntersectionType	×
329	) {
330	$types = [];	×
331	foreach ($type->getTypes() as $subType) {	×
332	$typeTmp = self::parseReflectionTypeObject($subType);	×
333	if (\is_array($typeTmp)) {	×
334	foreach ($typeTmp as $typeTmpInner) {	×
335	$types[] = $typeTmpInner;	×
336	}
337	} else {
338	$types[] = $typeTmp;	×
339	}
340	}
341
342	return \implode('&', $types);	×
343	}
344
345	return (string) $type;	×
346	}
347
348	/**
349	* @param string $expectedTypes
350	* @param mixed $value
351	* @param string $type
352	*
353	* @return \TypeError
354	*/
355	public function throwException($expectedTypes, $value, $type): \Throwable
356	{
357	throw new \TypeError("Invalid type: expected \"{$this->property_name}\" to be of type {{$expectedTypes}}, instead got value \"" . $this->valueToString($value) . '" (' . \print_r($value, true) . ") with type {{$type}}.");	196✔
358	}
359	}

voku / Arrayy / 30195550424

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