Skip to content

Commit 0e75720

Browse files
felixfbeckerfelixfbecker
committed
Improve README
1 parent 7a283f4 commit 0e75720

File tree

1 file changed

+141
-91
lines changed

1 file changed

+141
-91
lines changed

‎README.md‎

Lines changed: 141 additions & 91 deletions
Original file line numberDiff line numberDiff line change
@@ -1,91 +1,141 @@
1-
PHP Debug adapter for Visual Studio Code
2-
========================================
3-
4-
[![Latest Release](https://img.shields.io/github/release/felixfbecker/vscode-php-debug.svg)](https://github.com/felixfbecker/vscode-php-debug/releases/latest)
5-
[![Build Status](https://travis-ci.org/felixfbecker/vscode-php-debug.svg?branch=master)](https://travis-ci.org/felixfbecker/vscode-php-debug)
6-
[![Build Status Windows](https://ci.appveyor.com/api/projects/status/hda6n2umfdt6eyms/branch/master?svg=true)](https://ci.appveyor.com/project/felixfbecker/vscode-php-debug/branch/master)
7-
[![Dependency Status](https://gemnasium.com/felixfbecker/vscode-php-debug.svg)](https://gemnasium.com/felixfbecker/vscode-php-debug)
8-
[![Gitter](https://badges.gitter.im/felixfbecker/vscode-php-debug.svg)](https://gitter.im/felixfbecker/vscode-php-debug?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
9-
10-
![Demo GIF](images/demo.gif)
11-
12-
How to install
13-
--------------
14-
15-
### Install extension:
16-
Press `F1`, type `ext install php-debug`.
17-
18-
### Install XDebug:
19-
[Download and install the XDebug extension](http://xdebug.org/download.php).
20-
Then, in addition to `zend_extension=path/to/xdebug`, add these lines to your php.ini to enable remote debugging:
21-
22-
```ini
23-
[XDebug]
24-
xdebug.remote_enable = 1
25-
xdebug.remote_autostart = 1
26-
```
27-
For web projects, if you haven't already, point your webserver's webroot to your project and don't forget to restart your webserver after you made these changes.
28-
Now, everytime you do a request to a PHP file, XDebug will automatically try to connect to port 9000 for debugging.
29-
30-
### Start debugging:
31-
In your project, go to the debugger and hit the little gear icon. Choose PHP. A new launch configuration will be created for you.
32-
Now, if you select the _Listen for XDebug_ configuration and hit `F5`, VS Code will listen on port 9000 for incoming XDebug requests.
33-
When you make a request to `localhost` with your webbrowser or run a script from the command line, XDebug will connect to VS Code and you can debug your PHP.
34-
35-
For CLI scripts, you can set the same options the Node debugger supports: `program`, `runtimeExecutable`, `runtimeArgs`, `args`, `cwd`, `env` and `externalConsole` (see IntelliSense for descriptions).
36-
The default configuration includes one that runs the currently opened script as an example.
37-
38-
What is supported?
39-
------------------
40-
- Line breakpoints
41-
- Conditional breakpoints
42-
- Function breakpoints
43-
- Step over, step in, step out
44-
- Break on entry
45-
- Breaking on uncaught exceptions and errors / warnings / notices
46-
- Multiple, parallel requests (Still buggy, see [Microsoft/vscode#1703](https://github.com/Microsoft/vscode/issues/1703))
47-
- Stack traces, scope variables, superglobals, user defined constants
48-
- Arrays & objects (including classname, private and static properties)
49-
- Debug console
50-
- Watches
51-
- Run as CLI
52-
- Run without debugging
53-
54-
Remote Host Debugging
55-
---------------------
56-
If you want to debug a running application on a remote host, you have to set the `localSourceRoot` and `serverSourceRoot` settings in your launch.json.
57-
Example:
58-
```json
59-
"serverSourceRoot": "/var/www/myproject",
60-
"localSourceRoot": "${workspaceRoot}/src"
61-
```
62-
Both paths are normalized, so you can use slashes or backslashes no matter of the OS you're running.
63-
64-
Troubleshooting
65-
---------------
66-
When you are facing problems, please don't send me private emails, instead ask on
67-
[Gitter](https://gitter.im/felixfbecker/vscode-php-debug) or if you think there is a bug in the adapter, [open an issue](https://github.com/felixfbecker/vscode-php-debug/issues).
68-
If it fails with your ultra-awesome MVC app, please first try it on a dead-simple test.php (like the one in the [testproject](https://github.com/felixfbecker/vscode-php-debug/tree/master/testproject)). Please provide some info by setting `xdebug.remote_log = /path/to/logfile` in your php.ini (you will need to restart your webserver), `"log": true` in your launch.json and posting the two logs.
69-
70-
FAQ
71-
---
72-
73-
#### Where are the variables of the parent scope?
74-
In opposite to Javascript, PHP does not have closures.
75-
A scope contains only variables that have been declared, parameters and imported globals with `global` or `use`.
76-
If you want to see the variables of the scope of the callee, click on it in the stacktrace.
77-
78-
Contributing
79-
------------
80-
To hack on this adapter, clone the repository and open it in VS Code.
81-
You can debug it (run it in "server mode") by selecting the "Debug adapter" launch configuration and hitting `F5`.
82-
Then, open a terminal inside the project, and open the included testproject with VS Code while specifying the current directory as `extensionDevelopmentPath`:
83-
84-
```sh
85-
code testproject --extensionDevelopmentPath=.
86-
```
87-
88-
VS Code will open an "Extension Development Host" with the debug adapter running. Open `.vscode/launch.json` and
89-
uncomment the `debugServer` configuration line. Hit `F5` to start a debugging session.
90-
Now, you can debug the testproject like specified above and set breakpoints inside your first VS Code instance to step through the adapter code.
91-
1+
PHP Debug Adapter for Visual Studio Code
2+
========================================
3+
4+
[![Latest Release](https://img.shields.io/github/release/felixfbecker/vscode-php-debug.svg)](https://github.com/felixfbecker/vscode-php-debug/releases/latest)
5+
[![Build Status](https://travis-ci.org/felixfbecker/vscode-php-debug.svg?branch=master)](https://travis-ci.org/felixfbecker/vscode-php-debug)
6+
[![Build Status Windows](https://ci.appveyor.com/api/projects/status/hda6n2umfdt6eyms/branch/master?svg=true)](https://ci.appveyor.com/project/felixfbecker/vscode-php-debug/branch/master)
7+
[![Dependency Status](https://gemnasium.com/felixfbecker/vscode-php-debug.svg)](https://gemnasium.com/felixfbecker/vscode-php-debug)
8+
[![Gitter](https://badges.gitter.im/felixfbecker/vscode-php-debug.svg)](https://gitter.im/felixfbecker/vscode-php-debug?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
9+
10+
![Demo GIF](images/demo.gif)
11+
12+
Installation
13+
------------
14+
15+
Install the extension: Press `F1`, type `ext install php-debug`.
16+
17+
This extension is a debug adapter between VS Code and [XDebug](https://xdebug.org/) by Derick Rethan.
18+
XDebug is a PHP extension (a `.so` file on Linux and a `.dll` on Windows) that needs to be installed on your server.
19+
There are installation instructions available [here].
20+
21+
1. [Install XDebug](https://xdebug.org/docs/install)
22+
***I highly recommend you make a simple `test.php` file, put a `phpinfo();` statement in there,
23+
then copy the output and paste it into the [XDebug installation wizard](https://xdebug.org/wizard.php).
24+
It will analyze it and give you tailored installation instructions for your environment.***
25+
In short:
26+
- On Windows: [Download](https://xdebug.org/download.php) the appropiate precompiled DLL for your PHP version,
27+
architecture (64/32 Bit), thread safety (TS/NTS) and Visual Studio compiler version and place it in your PHP extension folder.
28+
- On Linux: Either download the source code as a tarball or [clone it with git](https://xdebug.org/docs/install#source),
29+
then [compile it](https://xdebug.org/docs/install#compile).
30+
- Reference the extension in your php.ini by adding `zend_extension=path/to/xdebug`.
31+
The path of your php.ini is shown in your `phpinfo()` output under "Loaded Configuration File".
32+
- Enable remote debugging in your php.ini:
33+
```ini
34+
[XDebug]
35+
xdebug.remote_enable = 1
36+
xdebug.remote_autostart = 1
37+
```
38+
There are other ways to tell XDebug to connect to a remote debugger than `remote_autostart`, like cookies,
39+
query parameters or browser extensions. I recommend `remote_autostart` because it "just works".
40+
There are also a variety of other options, like the port (by default 9000),
41+
please see the [XDebug documentation on remote debugging](https://xdebug.org/docs/remote#starting) for more information.
42+
- If you are doing web development, don't forget to restart your webserver to reload the settings
43+
- Verify your installation by checking your `phpinfo()` output for an XDebug section.
44+
45+
### VS Code Configuration
46+
In your project, go to the debugger and hit the little gear icon and choose _PHP_.
47+
A new launch configuration will be created for you with two configurations:
48+
- **Listen for XDebug**
49+
This setting will simply start listening on the specified port (by default 9000) for XDebug.
50+
If you configured XDebug like recommended above, everytime you make a request with a browser to your webserver
51+
or launch a CLI script XDebug will connect and you can stop on breakpoints, exceptions etc.
52+
- **Launch currently open script**
53+
This setting is an example of CLI debugging. It will launch the currently opened script as a CLI,
54+
show all stdout/stderr output in the debug console and end the debug session once the script exits.
55+
56+
#### Supported launch.json settings:
57+
- `request`: Always `"launch"`
58+
- `port`: The port on which to listen for XDebug (default: `9000`)
59+
- `stopOnEntry`: Wether to break at the beginning of the script (default: `false`)
60+
- `localSourceRoot`: The path to the folder that is being served by your webserver and maps to `serverSourceRoot`
61+
(for example `"${workspaceRoot}/public"`)
62+
- `serverSourceRoot`: The path on the remote host where your webroot is located (for example `"/var/www"`)
63+
- `log`: Wether to log all communication between VS Code and the adapter to the debug console.
64+
See _Troubleshooting_ further down.
65+
66+
Options specific to CLI debugging:
67+
- `program`: Path to the script that should be launched
68+
- `args`: Arguments passed to the script
69+
- `cwd`: The current working directory to use when launching the script
70+
- `runtimeExecutable`: Path to the PHP binary used for launching the script. By default the one on the PATH.
71+
- `runtimeArgs`: Additional arguments to pass to the PHP binary
72+
- `externalConsole`: Launches the script in an external console window instead of the debug console (default: `false`)
73+
- `env`: Environment variables to pass to the script
74+
75+
Features
76+
--------
77+
- Line breakpoints
78+
- Conditional breakpoints
79+
- Function breakpoints
80+
- Step over, step in, step out
81+
- Break on entry
82+
- Breaking on uncaught exceptions and errors / warnings / notices
83+
- Multiple, parallel requests (Still buggy, see [Microsoft/vscode#1703](https://github.com/Microsoft/vscode/issues/1703))
84+
- Stack traces, scope variables, superglobals, user defined constants
85+
- Arrays & objects (including classname, private and static properties)
86+
- Debug console
87+
- Watches
88+
- Run as CLI
89+
- Run without debugging
90+
91+
Remote Host Debugging
92+
---------------------
93+
To debug a running application on a remote host, you need to tell XDebug to connect to a different IP than `localhost`.
94+
This can either be done by setting `xdebug.remote_host` to your IP or by setting `xdebug.remote_connect_back`
95+
to make XDebug always connect back to the machine who did the web request.
96+
The former is the only setting that supports multiple users debugging the same server and "just works" for web projects.
97+
Again, please see the [XDebug documentation](https://xdebug.org/docs/remote#communcation) on the subject for more information.
98+
have to set the `localSourceRoot` and `serverSourceRoot` settings in your launch.json.
99+
Example:
100+
```json
101+
"serverSourceRoot": "/var/www/myproject",
102+
"localSourceRoot": "${workspaceRoot}/public"
103+
```
104+
Please also note that setting any of the CLI debugging options will not work with remote host debugging,
105+
because the script is always launched locally.
106+
If you want to debug a CLI script on a remote host, you need to launch it manually from the command line.
107+
108+
Troubleshooting
109+
---------------
110+
- Ask a question on [Gitter](https://gitter.im/felixfbecker/vscode-php-debug)
111+
- If you think you found a bug, [open an issue](https://github.com/felixfbecker/vscode-php-debug/issues)
112+
- Make sure you have the latest version of this extension and XDebug installed
113+
- Try out a simple PHP file to recreate the issue, for example from the [testproject](https://github.com/felixfbecker/vscode-php-debug/tree/master/testproject)
114+
- In your php.ini, set `xdebug.remote_log = /path/to/logfile` (make sure your webserver has write permissions to the file)
115+
- Set `"log": true` in your launch.json
116+
117+
Contributing
118+
------------
119+
To hack on this adapter, clone the repository and open it in VS Code.
120+
You need NodeJS and typings installed (`npm install -g typings`).
121+
Install dependencies by running `npm install` and `typings install`.
122+
123+
You can debug the extension (run it in "server mode") by selecting the "Debug adapter" launch configuration and hitting `F5`.
124+
Then, open a terminal inside the project, and open the included testproject with VS Code
125+
while specifying the current directory as `extensionDevelopmentPath`:
126+
127+
```sh
128+
code testproject --extensionDevelopmentPath=.
129+
```
130+
131+
VS Code will open an "Extension Development Host" with the debug adapter running. Open `.vscode/launch.json` and
132+
uncomment the `debugServer` configuration line. Hit `F5` to start a debugging session.
133+
Now you can debug the testproject like specified above and set breakpoints inside your first VS Code instance to step through the adapter code.
134+
135+
The extension is written in TypeScript and compiled using a Gulpfile that first transpiles to ES6
136+
and then uses Babel to specifically target VS Code's Node version.
137+
You can run the compile task through `npm run compile`, `gulp compile` or from VS Code with `Ctrl`+`Shift`+`B`.
138+
`npm run watch` / `gulp watch` enables incremental compilation.
139+
140+
Tests are written with Mocha and can be run with `npm test`.
141+
The tests are run in CI on Linux and Windows against PHP 5.4, 5.6, 7.0 and XDebug 2.3, 2.4.

0 commit comments

Comments
 (0)