RPC Protocol¶
This document should largely be correct but is a work-in-progress
Phpactor communicates with the editor over its own RPC protocol which effectively allows the editor to instruct Phpactor to do things, and in turn Phpactor can also instruct the editor to do things.
rpc¶
Requests can be sent via. stdin to the Phpactor rpc command
$ echo '{"action": "echo", "parameters": { "message": "Hello" }}' | ./bin/phpactor rpc
Above we use the somewhat pointless echo action, which simply
returns a response asking the editor to echo a message. The result is
sent over stdout:
{"action":"echo","parameters":{"message":"Hello"}}
Responses contain an action which will be executed in the editor.
Some responses will include callbacks to Phpactor. This allows Phpactor to ask for more information as required.
Work-in-progress¶
This Protocol is a work-in-progress.
TODO:
Parameters should not refer to file paths in class contexts: Although classes map 1-1 to files now, this may not always be the case and Phpactor can figure out a file-path from a class-name and vice-versa (so
classinstead ofclass_path).
Editor Actions¶
return¶
Return a value. This action should return the value immediately to the caller without further dispatches.
Name:
returnParameters:
Value: Value to return.
return_choice¶
The editor should render a dialog asking the user to select a choice:
1) Do this
2) Do that
It should then return the chosen value.
Name:
return_choiceParameters:
choices: Key to value list of choices, the key is the label for the choice, the value is the value to return.
echo¶
The editor should echo (or otherwise visibly display) a message.
Name:
echoParameters:
message: Message to display.
error¶
The editor should show an error.
Name:
errorParameters:
message: Error message to display.
collection¶
Collection of actions to be executed sequentially until there are no
more or until a return is encountered.
Name:
collectionParameters:
actions: Array of actions to dispatch.
open_file¶
Open a file in the editor.
Name:
open_fileParameters:
path: Path to file which should be opened.offset: Goto this offset after opening the file.
close_file¶
Close a file.
Name:
close_fileParameters:
path: Path to file which should be closed.
file_references¶
List of files and references. The editor should populate a navigable list of the files and the references (in VIM this is a quick-fix list).
Name:
file_referencesParameters:
references: Array containing file paths nested with references:
Example of references parameter:
{
"file_references": [
{
"file": "/path/to/File.php",
"references": [
{
"line_no": 1234,
"col": 12
},
{
"line_no": 1234,
"col": 12
}
]
}
]
}
input_callback¶
This action will provide a callback to Phpactor and inputs which the end-user will need to complete to populate the parameters of the callback.
Name:
input_callbackParameters:
callback:action: Callback command name for Phpactor.parameters: Array of parameters to pass.
inputs: Array of inputs
Example:
{
"callback": {
"action": "hello",
"parameters": {
"greeting": "Hello",
"first_name": "value1"
}
}
"inputs": [
{
"name": "first_name",
"type": "text",
"parameters": {
"default": "<enter your first name>",
}
}
]
}
See the VIM plugin for the supported inputs.
information¶
Show information in a persistent and unobtrusive way (in VIM as a preview window).
Name:
informationParameters:
information: Information to show (text)
replace_file_source¶
Replace the source code in the current file.
Name:
replace_file_sourceParameters:
source: Source code.
Phpactor Commands¶
In the following references all parameters are assumed to be required unless otherwise stated. optional parameters are optional, eventually required means the parameter is optional, but if not given Phpactor will ask for it (via. a callback).
Note that after implementing a dispatcher for standard editor actions above it is not necessary to know the result of these commands, they will be handled by your editor.
complete¶
The complete RPC command returns a list of completions:
$ echo '{"actions": [ {"action": "complete", "parameters": { "source": "<?php $foo = new Exception(); $foo->", "offset": 37} }] }' | ./bin/phpactor rpc
Example response:
{
"actions": [
{
"action": "return",
"parameters": {
"value": [
{
"info": "pri __clone(): void",
"name": "__clone",
"type": "f"
},
{
"info": "pub getMessage(): string",
"name": "getMessage",
"type": "f"
},
{
"info": "pub getCode()",
"name": "getCode",
"type": "f"
},
]
}
}
]
}
class_search¶
Searches for a class with a given class name. No need for the fully qualified class name.
Name:
class_searchParameters:
short_name: Name of the class that you want to find
$ echo '{"actions": [ {"action": "class_search", "parameters": { "short_name": "InputInterface" } }] }' | ./bin/phpactor rpc
goto_definition¶
Open file and goto offset of symbol at the given offset in the given source code:
Name:
goto_definitionParameters:
source: Source code as a stringoffset: Offset of symbol (int)
$ echo '{"actions": [ {"action": "goto_definition", "parameters": { "source": "<?php $foo = new Exception(); $foo->getMessage()", "offset": 37} }] }' | ./bin/phpactor rpc
Will return an action to open the file containing the definition and goto the offset.
copy_class¶
Copy a class to a new location and update its name accordingly:
Name:
copy_classParameters:
source_path: File containing class to copy..dest_path: (eventually required) Destination path
$ echo '{"actions": [ {"action": "copy_class", "parameters": { "source_path": "/path/to/class.php" } } ] }| ./bin/phpactor rpc
Will return an action to open the new file.
move_class¶
Move a class and update all references to it in the project.
Name:
move_classParameters:
source_path: File containing class to move.dest_path: (eventually required) File to move class to.
Will eventually return an action to open the new file, and a command to forget about the old one.
offset_info¶
Return debug information about the symbol and the state of the frame at the given offset.
Name:
offset_infoParameters:
source: Source code as a stringoffset: Offset of symbol (int)
Returns an (information) action to show a pretty-printed JSON string containing the debug information.
transform¶
Perform a transformation on the class in the given file.
Name:
transformParameters:
source: Sourcepath: Path for file containing class to transform (required only in order to reload the file in the editor later).transform: (eventually required) Name of transformation to make.
If no transformation Phpactor will offer a choice of available transformations, then make the transformation and ask the editor to reload the file.
class_new¶
Generate a new class.
Name:
class_newParameters:
current_path: Path to current file (used as default for new path)new_path: (eventually required) Path to new class.variant: (eventually required) Variant to create.overwrite: (conditionally eventually required) If file already exists then this should be true in order that it is overwritten.
Will return an action to open the new file.
class_inflect¶
Generate a new class based on the current (given) class.
Name:
class_newParameters:
current_path: Path to current file (used as default for new path)new_path: (eventually required) Path to new class.variant: (eventually required) Variant to create.overwrite: (conditionally eventually required) If file already exists then this should be true in order that it is overwritten.
Will return an action to open the new file.
references¶
Find references to the symbol under the cursor.
Name:
referencesParameters:
source: Source code as a stringoffset: Offset of symbol (int)
Will return a file-list action, containing a list of all the files in which references can be found (and the position of all the references).
extract_constant¶
Extract a constant from the value at the given offset and replace all identical values with a reference to the constant.
Name:
extract_constantParameters:
source: Source code as a stringoffset: Offset of symbol (int)constant_name: Name for constant.constant_suggestion_name: (optional) Use this as a suggestion when interactive.
Will return an action to replace the file with the updated code.
generate_method¶
Generate (or update) a method from the method call at the given offset in the given source.
Name:
generate_methodParameters:
source: Source code as a stringpath: Path to sourceoffset: Offset of symbol (int)
Will return an action to replace the file with the updated code.
generate_accessor¶
Generate (or update) an accessor for the property under the cursor.
Name:
generate_accessorParameters:
source: Source code as a stringoffset: Offset of symbol (int)
Will return an action to replace the file with the updated code.
