You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: composer.json
+3-3Lines changed: 3 additions & 3 deletions
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
{
2
2
"name": "typephp/typephp",
3
-
"description": "Zero-cost runtime type checker for PHP. Enforces PHPDoc annotations including generics, typed arrays, array shapes, and advanced types at runtime in development and testing.",
3
+
"description": "Zero-cost runtime type checker for PHP. Enforces PHPDoc annotations including generics, typed arrays, array shapes, and advanced types at runtime in development and production.",
If you run TypePHP in live production applications—especially for validating external HTTP API payloads, webhooks, or dynamic database records—catching `TypePHP\Exception\TypeError` gives you a clean way to intercept data validation failures gracefully without letting exceptions crash your application.
4
+
5
+
TypePHP provides a custom exception class, `TypePHP\Exception\TypeError`, designed for both polymorphic compatibility with PHP's native type system and surgical error handling at application boundaries.
6
+
7
+
---
8
+
9
+
## The Exception Class Hierarchy
10
+
11
+
All contract violations in TypePHP instantiate `TypePHP\Exception\TypeError`, which extends PHP's native `\TypeError`:
12
+
13
+
```
14
+
\Throwable
15
+
└── \Error
16
+
└── \TypeError
17
+
└── TypePHP\Exception\TypeError
18
+
```
19
+
20
+
---
21
+
22
+
## Dual Catching Modes
23
+
24
+
Because `TypePHP\Exception\TypeError` extends native `\TypeError`, you can choose how broadly or narrowly to catch type failures:
Catches both native PHP engine type errors (such as passing a string into a native `int` type hint) and TypePHP contract failures:
29
+
30
+
```php
31
+
try {
32
+
processUser(-50);
33
+
} catch (\TypeError $e) {
34
+
// Catches both native PHP TypeErrors and TypePHP contract failures!
35
+
}
36
+
```
37
+
38
+
### 2. Specific Contract Catching (`catch (\TypePHP\Exception\TypeError $e)`)
39
+
40
+
Specifically catches TypePHP contract violations while allowing native PHP engine errors to bubble up separately:
41
+
42
+
```php
43
+
use TypePHP\Exception\TypeError as TypePHPTypeError;
44
+
45
+
try {
46
+
processUser(-50);
47
+
} catch (TypePHPTypeError $e) {
48
+
// Catches ONLY TypePHP contract violations!
49
+
} catch (\TypeError $e) {
50
+
// Catches native PHP engine type errors!
51
+
}
52
+
```
53
+
54
+
---
55
+
56
+
## Call-Site Trace Attribution
57
+
58
+
When a function parameter or callback argument fails type validation, TypePHP automatically rewrites the exception's file and line attributes.
59
+
60
+
Instead of blaming internal library files, `ErrorFactory` filters out internal frames and attributes `$e->file` and `$e->line` directly to **the exact line of code in the caller file where the invalid argument was passed**, matching native PHP engine behavior.
61
+
62
+
---
63
+
64
+
## HTTP API Payload Validation (Framework-Agnostic 422 Responses)
65
+
66
+
`TypePHP\Exception\TypeError` is especially useful when validating external HTTP request payloads at application boundaries.
67
+
68
+
When dynamic request data fails contract validation, you can catch `TypePHPTypeError` and return a clean HTTP `422 Unprocessable Entity` response:
69
+
70
+
```php
71
+
namespace App\Http;
72
+
73
+
use App\Services\UserService;
74
+
use TypePHP\Exception\TypeError as TypePHPTypeError;
75
+
76
+
class UserApiController
77
+
{
78
+
public function __construct(private UserService $userService) {}
79
+
80
+
public function handleRequest(array $requestData): array
0 commit comments