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
PHP client library for [xrDebug](https://xrdebug.com/). This library provides a set of functions to dump variables, send raw messages, and interact with the inspector.
22
-
23
-
VarDump functionality is provided by the [VarDump](https://chevere.org/packages/var-dump) package and throwable handling by the [ThrowableHandler](https://chevere.org/packages/throwable-handler) package.
21
+
PHP client library for [xrDebug](https://xrdebug.com/). This library provides a set of functions to dump variables, send raw messages, and interact with the inspector from your codebase.
24
22
25
23
## Quick start
26
24
@@ -30,48 +28,102 @@ Install using [Composer](https://packagist.org/packages/xrdebug/php).
30
28
composer require --dev xrdebug/php
31
29
```
32
30
33
-
Make sure to load the Composer `autoload.php` file in your project's entry point file, usually at `index.php`.
31
+
Use `xr()` directly in your code to dump any variable. For example:
34
32
35
33
```php
36
34
require_once __DIR__ . '/vendor/autoload.php';
35
+
36
+
// ...
37
+
xr('Hello, world!');
37
38
```
38
39
39
-
Use `xr()` directly in your code to dump any variable. For example for a WordPress plugin:
40
+
## Configuring
41
+
42
+
This xrDebug PHP client uses the following default configuration.
43
+
44
+
> Skip this section if running from the xrDebug binary and on the same machine.
| isEnabled | bool | Controls sending messages to the server |
59
+
| isHttps | bool | Controls use of https |
60
+
| host | string | The host where xrDebug server is running |
61
+
| port | int | The Port to connect to the `host`|
62
+
| key | string | Private key (ed25519) for signed requests |
49
63
50
-
There's a interactive demo of this library in the `./demo` directory. To use the demo execute `xrdebug` server with default settings.
64
+
> `host` The hostname or IP. When running xrDebug on Docker use `host.docker.internal`.
51
65
52
-
Execute the following command to start the demo, it sends messages to the xrDebug server explaining you the debugger user interface.
66
+
### File-based config
53
67
54
-
```php
55
-
php demo/welcome.php
56
-
```
68
+
Configure the client by placing a `xr.php` file in project's root directory. Need to define only the properties that override the default config.
57
69
58
-
Execute the following command to see how xrDebug [handles errors](#error-handling).
70
+
We recommend adding `xr.php` to your `.gitignore`.
59
71
60
-
```php
61
-
php demo/error-handling.php
62
-
```
72
+
Here some examples of `xr.php`:
73
+
74
+
- Run with Docker at a `27980` port:
75
+
76
+
```php
77
+
<?php
78
+
79
+
return [
80
+
'host' => 'host.docker.internal',
81
+
'port' => 27980,
82
+
];
83
+
```
84
+
85
+
- Run with sign verification:
86
+
87
+
```php
88
+
<?php
89
+
90
+
return [
91
+
'key' => file_get_contents('private.key'),
92
+
];
93
+
```
63
94
64
-
## Debug Helpers
95
+
### Code-based config
96
+
97
+
Use function `xrConfig()` to configure the xrDebug server connection directly in your logic. Need to define only the properties that override the default config.
98
+
99
+
Here some examples of `xrConfig()`:
100
+
101
+
- Run with Docker at a `27980` port:
102
+
103
+
```php
104
+
xrConfig(
105
+
host: 'host.docker.internal',
106
+
port: 27980,
107
+
);
108
+
```
109
+
110
+
- Run with sign verification:
111
+
112
+
```php
113
+
xrConfig(
114
+
key: file_get_contents('private.key'),
115
+
);
116
+
```
117
+
118
+
## Debug helpers
65
119
66
120
This xrDebug PHP client provides the following helper functions in the root namespace. Use these anywhere in your code.
Function `vd` is a drop-in replacement for `var_dump`, it is provided by the [VarDump](https://chevere.org/packages/var-dump) package. It prints information about one or more variables to the output stream.
194
+
Function `vd` is a drop-in replacement for `var_dump`. It prints information about one or more variables to the output stream.
134
195
135
196
```php
136
197
vd($var1, $var2,);
@@ -146,46 +207,21 @@ vdd($var);
146
207
// does exit();
147
208
```
148
209
149
-
## Configuring
150
-
151
-
### Code-based configuration
152
-
153
-
Use `xrConfig()` to configure the xrDebug server connection.
| isEnabled | bool | Controls sending messages to the server |
168
-
| isHttps | bool | Controls use of https |
169
-
| host | string | The host where xrDebug server is running |
170
-
| port | int | The Port to connect to the `host`|
171
-
| key | string | Private key (signed requests) |
210
+
## Exception handling
172
211
173
-
### File-based configuration
212
+
The PHP client provides a throwable handler that can hook or replace existing exception handler logic thanks to the [ThrowableHandler](https://chevere.org/packages/throwable-handler) package.
174
213
175
-
Configure the client by placing a `xr.php` file in project's root directory.
214
+
### Register handler
176
215
177
-
> We recommend adding `xr.php` to your `.gitignore`.
216
+
Use `registerThrowableHandler` to enable xrDebug throwable handling.
178
217
179
218
```php
180
-
<?php
181
219
182
-
return [
183
-
'isEnabled' => true,
184
-
'isHttps' => false,
185
-
'host' => 'localhost',
186
-
'port' => 27420,
187
-
'key' => file_get_contents('private.key'),
188
-
];
220
+
use Chevere\xrDebug\PHP\registerThrowableHandler;
221
+
222
+
// True append xrDebug to your existing handler
223
+
// False use only xrDebug handler
224
+
registerThrowableHandler(true);
189
225
```
190
226
191
227
## Error handling
@@ -203,23 +239,6 @@ register_shutdown_function(
203
239
);
204
240
```
205
241
206
-
## Exception handling
207
-
208
-
The PHP client provides a throwable handler that can hook or replace existing exception handler logic thanks to the [ThrowableHandler](https://chevere.org/packages/throwable-handler) package.
209
-
210
-
### Register handler
211
-
212
-
Use `registerThrowableHandler` to enable xrDebug throwable handling.
213
-
214
-
```php
215
-
216
-
use Chevere\xrDebug\PHP\registerThrowableHandler;
217
-
218
-
// True append xrDebug to your existing handler
219
-
// False use only xrDebug handler
220
-
registerThrowableHandler(true);
221
-
```
222
-
223
242
### Triggered handler
224
243
225
244
Use `throwableHandler` in any existing exception handler logic:
0 commit comments