Development¶
Package Structure¶
Phpactor is divided into _packages_. Each package occupies a directory in lib/. In addition there are extensions which integrate packages with Phpactor which are in lib/Extension.
Tests and benchmarks are maintained in the package’s directory, e.g. lib/WorseReflection/Tests.
Logging¶
Logging is disabled by default, but can provide some useful information (such as errors encountered when parsing files etc).
Enable it as follows:
{
"logging.enabled": true,
"logging.level": "debug",
"logging.path": "phpactor.log",
}
Var Dump Server¶
Phpactor includes the Symfony Var Dumper, this allows you to inspect values while the server is running or an RPC request is being executed.
Start the server in the Phpactor project root:
$ ./vendor/bin/var-dump
./vendor/bin/var-dump-server
Symfony Var Dumper Server
=========================
[OK] Server listening on tcp://127.0.0.1:9912
// Quit the server with CONTROL-C
You can use the dump function in the code and the variable will be shown in the console output of the server you started: dump($var).
Debugging RPC¶
When executing commands in an editor, it can be tricky to consistently reproduce errors, or to isolate and debug them in Phpactor.
Thankfully there is a feature called RPC replay which allows you to replay the last RPC command received by Phpactor.
Enable it in a Phpactor configuration file, for example
$HOME/.config/phpactor/phpactor.yml
:
rpc.store_replay: true
Now, after you execute an RPC command via. your editor, you can execute Phpactor from the shell and replay your last command:
$ phpactor rpc --replay
{"action":"open_file","parameters":{"path":"\/home\/daniel\/www\/phpactor\/phpactor\/lib\/Extension\/Rpc\/Handler\/AbstractHandler.php","offset":447}}
To see more information, including the initial request add the
--verbose
option:
$ phpactor rpc --replay --verbose
[2018-05-23T22:14:11.486488+02:00] phpactor.DEBUG: REQUEST {"action":"goto_definition","parameters":{"source":"[removed]","offset":1913,"path":"/home/daniel/somepath/SomeClass.php"}}
[2018-05-23T22:14:11.494201+02:00] phpactor.DEBUG: Resolving: Microsoft\PhpParser\Node\Statement\ClassDeclaration [] []
[2018-05-23T22:14:11.494545+02:00] phpactor.DEBUG: Resolving: Microsoft\PhpParser\Node\Parameter [] []
...[truncated]...
[2018-05-23T22:14:11.508019+02:00] phpactor.DEBUG: RESPONSE {"action":"open_file","parameters":{"path":"/home/daniel/www/phpactor/phpactor/lib/Extension/Rpc/Handler/AbstractHandler.php","offset":447}} []
{"action":"open_file","parameters":{"path":"\/home\/daniel\/www\/phpactor\/phpactor\/lib\/Extension\/Rpc\/Handler\/AbstractHandler.php","offset":447}}
The next time you run a command, you will lose your replay, in order to consistently reproduce an action, you can copy the replay file and execute it consistently as many times as required:
$ cp ~/.local/share/phpactor/replay.json .
$ cat replay.json | phpactor rpc --verbose
Documentation¶
Phpactor Documentation¶
Phpactor uses Sphinx (RST) for documentation.
Docs are located in the docs
.
A useful primer on RST can be found here.
$ apt-get install python3-sphinx
$ pip install sphinx-tabs
You can then build the docs with:
make sphinx
Or, to watch for changes (requires inotifywait
):
make sphinxwatch
VIM Help¶
The VIM plugin is documented in the generated doc/phpactor.txt
file using vimdoc.
In order to add documentation just annotate properties / methods with comments, for example:
""
" Extract the selected expression and assign it to a variable before
command! -buffer -range=% PhpactorExtractExpression call phpactor#ExtractExpression('v')
See vimdoc for more information.
Use the following command to both install vimdoc and build the documentation:
make vimdoc
Profiling the Language Server¶
You can selectively profile the language server using Blackfire.
Enable the blackfire via. blackfire.enabled
Call the LSP methods blackfire/start and blackfire/finish, for NVIM see Phpactor Commands