{"id":19689151,"url":"https://github.com/xrdebug/php","last_synced_at":"2025-05-15T20:05:27.189Z","repository":{"id":40443402,"uuid":"442894283","full_name":"xrdebug/php","owner":"xrdebug","description":"Official PHP client library for xrDebug","archived":false,"fork":false,"pushed_at":"2025-01-09T11:07:58.000Z","size":5194,"stargazers_count":226,"open_issues_count":4,"forks_count":5,"subscribers_count":4,"default_branch":"3.0","last_synced_at":"2025-05-08T10:16:44.734Z","etag":null,"topics":["debug","debugger","debugging-tool","dump","php"],"latest_commit_sha":null,"homepage":"https://xrdebug.com","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xrdebug.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-12-29T21:27:00.000Z","updated_at":"2025-04-30T13:40:05.000Z","dependencies_parsed_at":"2023-10-03T01:04:07.748Z","dependency_job_id":"8c6766bc-11f6-4c1f-aa9c-304a9180872e","html_url":"https://github.com/xrdebug/php","commit_stats":{"total_commits":296,"total_committers":1,"mean_commits":296.0,"dds":0.0,"last_synced_commit":"0ef77144e845c384c5866f689a57eb2e12033f70"},"previous_names":["xrdebug/php","chevere/xr"],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xrdebug%2Fphp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xrdebug%2Fphp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xrdebug%2Fphp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xrdebug%2Fphp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xrdebug","download_url":"https://codeload.github.com/xrdebug/php/tar.gz/refs/heads/3.0","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254414499,"owners_count":22067272,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["debug","debugger","debugging-tool","dump","php"],"created_at":"2024-11-11T18:42:54.810Z","updated_at":"2025-05-15T20:05:21.714Z","avatar_url":"https://github.com/xrdebug.png","language":"PHP","funding_links":[],"categories":["PHP"],"sub_categories":[],"readme":"# xrDebug PHP client\n\n\u003ca href=\"https://xrdebug.com\"\u003e\u003cimg alt=\"xrDebug\" src=\"xr.svg\" width=\"40%\"\u003e\u003c/a\u003e\n\n[![Build](https://img.shields.io/github/actions/workflow/status/xrdebug/php/test.yml?branch=3.0\u0026style=flat-square)](https://github.com/xrdebug/php/actions)\n![Code size](https://img.shields.io/github/languages/code-size/xrdebug/php?style=flat-square)\n[![Apache-2.0](https://img.shields.io/github/license/xrdebug/php?style=flat-square)](LICENSE)\n[![PHPStan](https://img.shields.io/badge/PHPStan-level%209-blueviolet?style=flat-square)](https://phpstan.org/)\n[![Mutation testing badge](https://img.shields.io/endpoint?style=flat-square\u0026url=https%3A%2F%2Fbadge-api.stryker-mutator.io%2Fgithub.com%2Fxrdebug%2Fphp%2F3.0)](https://dashboard.stryker-mutator.io/reports/github.com/xrdebug/php/3.0)\n\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=xrdebug_php\u0026metric=alert_status)](https://sonarcloud.io/dashboard?id=xrdebug_php)\n[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=xrdebug_php\u0026metric=sqale_rating)](https://sonarcloud.io/dashboard?id=xrdebug_php)\n[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=xrdebug_php\u0026metric=reliability_rating)](https://sonarcloud.io/dashboard?id=xrdebug_php)\n[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=xrdebug_php\u0026metric=security_rating)](https://sonarcloud.io/dashboard?id=xrdebug_php)\n[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=xrdebug_php\u0026metric=coverage)](https://sonarcloud.io/dashboard?id=xrdebug_php)\n[![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=xrdebug_php\u0026metric=sqale_index)](https://sonarcloud.io/dashboard?id=xrdebug_php)\n[![CodeFactor](https://www.codefactor.io/repository/github/xrdebug/php/badge)](https://www.codefactor.io/repository/github/xrdebug/php)\n\n## Summary\n\nPHP 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.\n\n## Quick start\n\nInstall using [Composer](https://packagist.org/packages/xrdebug/php).\n\n```sh\ncomposer require --dev xrdebug/php\n```\n\nUse `xr()` directly in your code to dump any variable. For example:\n\n```php\nrequire_once __DIR__ . '/vendor/autoload.php';\n\n// ...\nxr('Hello, world!');\n```\n\n## Configuring\n\nThis xrDebug PHP client uses the following default configuration.\n\n\u003e Skip this section if running from the xrDebug binary and on the same machine.\n\n```php\n[\n    'isEnabled' =\u003e true,\n    'isHttps' =\u003e false,\n    'host' =\u003e 'localhost',\n    'port' =\u003e 27420,\n    'key' =\u003e '',\n]\n```\n\n| Property  | Type   | Effect                                    |\n| --------- | ------ | ----------------------------------------- |\n| isEnabled | bool   | Controls sending messages to the server   |\n| isHttps   | bool   | Controls use of https                     |\n| host      | string | The host where xrDebug server is running  |\n| port      | int    | The Port to connect to the `host`         |\n| key       | string | Private key (ed25519) for signed requests |\n\n\u003e `host` The hostname or IP. When running xrDebug on Docker use `host.docker.internal`.\n\n### File-based config\n\nConfigure the client by placing a `xr.php` file in project's root directory. Need to define only the properties that override the default config.\n\nWe recommend adding `xr.php` to your `.gitignore`.\n\nHere some examples of `xr.php`:\n\n- Run with Docker at a `27980` port:\n\n  ```php\n  \u003c?php\n\n  return [\n      'host' =\u003e 'host.docker.internal',\n      'port' =\u003e 27980,\n  ];\n  ```\n\n- Run with sign verification:\n\n  ```php\n  \u003c?php\n\n  return [\n      'key' =\u003e file_get_contents('private.key'),\n  ];\n  ```\n\n### Code-based config\n\nUse function `xrConfig()` to configure the xrDebug server connection directly in your logic. Need to define only the properties that override the default config.\n\nHere some examples of `xrConfig()`:\n\n- Run with Docker at a `27980` port:\n\n  ```php\n   xrConfig(\n      host: 'host.docker.internal',\n      port: 27980,\n  );\n  ```\n\n- Run with sign verification:\n\n  ```php\n   xrConfig(\n      key: file_get_contents('private.key'),\n  );\n  ```\n\n## Debug helpers\n\nThis xrDebug PHP client provides the following helper functions in the root namespace. Use these anywhere in your code.\n\n| Function    | Purpose                      |\n| ----------- | ---------------------------- |\n| [xr](#xr)   | Dump one or more variables   |\n| [xrr](#xrr) | Dump raw message             |\n| [xri](#xri) | Dump inspector (pauses, etc) |\n\n### xr\n\nUse function `xr($var1, $var2,...)` to dump one or more variable(s).\n\n```php\nxr($var, 'Hola, mundo!');\n```\n\nPass a topic using `t:`.\n\n```php\nxr($var, t: 'Epic win');\n```\n\nPass an emote using `e:`.\n\n```php\nxr($var, e: '😎');\n```\n\nPass bitwise flags to trigger special behavior.\n\n- `f: XR_BACKTRACE` to include debug backtrace.\n\n```php\nxr($var, f: XR_BACKTRACE);\n```\n\n### xrr\n\nUse function `xrr()` to send a raw message.\n\n```php\nxrr('\u003ch1\u003eHola, mundo!\u003c/h1\u003e');\nxrr('\u003cspan\u003eTest\u003c/span\u003e', t: 'Epic win');\nxrr('\u003cb\u003etest\u003c/b\u003e', e: '😎');\nxrr('some string\u003cbr\u003e', f: XR_BACKTRACE);\n```\n\n### xri\n\nUse function `xri()` to interact with the inspector.\n\nUse `pause` to pause code execution.\n\n```php\nxri()-\u003epause();\n```\n\nUse `memory` to send memory usage information.\n\n```php\nxri()-\u003ememory();\n```\n\n### Debug helpers (VarDump)\n\nThis xrDebug PHP client also provides the following helper functions provided by the [VarDump](https://chevere.org/packages/var-dump) package.\n\n| Function    | Purpose                           |\n| ----------- | --------------------------------- |\n| [vd](#vd)   | VarDump to output stream          |\n| [vdd](#vdd) | VarDump to output stream  and die |\n\n### vd\n\nFunction `vd` is a drop-in replacement for `var_dump`. It prints information about one or more variables to the output stream.\n\n```php\nvd($var1, $var2,);\n// more code\n```\n\n### vdd\n\nFunction `vdd` does same as vd, but with die(0) which halts further execution.\n\n```php\nvdd($var);\n// does exit();\n```\n\n## Exception handling\n\nThe 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.\n\n### Register handler\n\nUse `registerThrowableHandler` to enable xrDebug throwable handling.\n\n```php\n\nuse Chevere\\xrDebug\\PHP\\registerThrowableHandler;\n\n// True append xrDebug to your existing handler\n// False use only xrDebug handler\nregisterThrowableHandler(true);\n```\n\n## Error handling\n\nTo handle errors with xrDebug you will require to configure your project to handle errors as exceptions and register a shutdown function:\n\n```php\nuse Chevere\\ThrowableHandler\\ThrowableHandler;\n\nset_error_handler(\n    ThrowableHandler::ERROR_AS_EXCEPTION\n);\nregister_shutdown_function(\n    ThrowableHandler::SHUTDOWN_ERROR_AS_EXCEPTION\n);\n```\n\n### Triggered handler\n\nUse `throwableHandler` in any existing exception handler logic:\n\n```php\nuse Chevere\\xrDebug\\PHP\\throwableHandler;\n\nset_exception_handler(\n    function(Throwable $throwable) {\n        // ...\n        try {\n            throwableHandler($throwable);\n        } catch(Throwable) {\n            // Don't panic\n        }\n    }\n);\n```\n\n## Custom inspectors\n\nExtra inspectors can be defined to provide more context aware debug information. To create a custom inspector use `XrInspectorTrait` to implement the `XrInspectorInterface` and use `sendCommand` method.\n\nFor code below, `myDump` defines a method that will stream data from your application logic and `myPause` sends a pause with debug backtrace by default.\n\n```php\n\u003c?php\n\nuse Chevere\\xrDebug\\PHP\\Traits\\XrInspectorTrait;\nuse Chevere\\xrDebug\\PHP\\Interfaces\\XrInspectorInterface;\n\nclass MyInspector implements XrInspectorInterface\n{\n    use XrInspectorTrait;\n\n    public function myDump(\n        string $t = '',\n        string $e = '',\n        int $f = 0,\n    ): void {\n        $data = 'my queries from somewhere...';\n        $this-\u003esendCommand(\n            command: 'message',\n            body: $data,\n            topic: $t,\n            emote: $e,\n            flags: $f,\n        );\n    }\n\n    public function myPause(\n        int $f = XR_DEBUG_BACKTRACE,\n    ): void {\n        $this-\u003esendCommand(\n            command: 'pause',\n            flags: $f,\n        );\n    }\n}\n```\n\nThe method `sendCommand` enables to interact with the existing xrDebug instance.\n\n```php\nprivate function sendCommand(\n    string $command,\n    string $body = '',\n    string $topic = '',\n    string $emote = '',\n    int $flags = 0\n);\n```\n\n### Null inspector\n\nA null inspector is required to void any inspection call **if xrDebug is disabled**. The null inspector should implement the same methods as the real inspector, but without carrying any action.\n\n💡 Use `XrInspectorNullTrait` to implement the `XrInspectorInterface` when providing null inspector.\n\n```php\n\u003c?php\n\nuse Chevere\\xrDebug\\PHP\\Traits\\XrInspectorNullTrait;\nuse Chevere\\xrDebug\\PHP\\Interfaces\\XrInspectorInterface;\n\nclass MyInspectorNull implements XrInspectorInterface\n{\n    use XrInspectorNullTrait;\n\n    public function myDump(\n        string $t = '',\n        string $e = '',\n        int $f = 0,\n    ): void {\n    }\n\n    public function myPause(\n        int $f = XR_DEBUG_BACKTRACE,\n    ): void {\n    }\n}\n```\n\n### Helper function for custom inspector\n\n```php\nuse Chevere\\xrDebug\\PHP\\XrInspectorInstance;\nuse Chevere\\xrDebug\\PHP\\Interfaces\\XrInspectorInterface;\nuse LogicException;\nuse MyInspector;\nuse MyInspectorNull;\n\nfunction my_inspector(): MyInspector\n{\n    try {\n        return XrInspectorInstance::get();\n    } catch (LogicException) {\n        $inspector = getXr()-\u003eenable()\n            ? MyInspector::class\n            : MyInspectorNull::class;\n        $client = getXr()-\u003eclient();\n        $inspector = new $inspector($client);\n        $instance = new XrInspectorInstance($inspector);\n\n        return $instance::get();\n    }\n}\n```\n\nTo use your custom helper:\n\n```php\nmy_inspector()-\u003emyDump();\nmy_inspector()-\u003emyPause();\n```\n\n## Documentation\n\nDocumentation available at [docs.xrdebug.com](https://docs.xrdebug.com/).\n\n## License\n\nCopyright [Rodolfo Berrios A.](https://rodolfoberrios.com/)\n\nxrDebug is licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for the full license text.\n\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxrdebug%2Fphp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxrdebug%2Fphp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxrdebug%2Fphp/lists"}