End User Guide

Contents

• Getting Started
• Commands
• Crane's Features
• Crane's Limitations
• Crane Settings
• PHP Library Stubs

Getting Started

Installing Crane

To install Crane, you have several options. You can either install it via the built-in extension installer, or via the .vsix download file from the releases page.

Via the Built-in Extension Installer

1. Open VS Code
2. Press F1 to open the command palette
3. Type ext install and select Install Extension from the list that appears
4. Type crane and select Crane from the list
5. Restart VS Code when prompted

Via the .vsix Download File

1. Go to the releases page
2. Download the crane-[version].vsix file from the relevant release
3. Open VS Code
4. Select File -> Open and choose the downloaded .vsix file
5. Restart VS Code when prompted

Using Crane

Crane will initialise automatically when you open a PHP file and begin processing each PHP file in the workspace folder to build an Abstract Syntax Tree (AST) for generating suggestions and code analysis.

Simply start typing in a PHP file to have variables, functions, classes and more suggested. While VS Code has it's "24/7 code-completion", Crane specific code-completion is triggered when you type one of the following characters: $ . > :

If you have the cache setting enabled, then Crane will cache the generated AST to a local file for fast access when you close and re-open the project again. If you modify any of the files in the workspace outside of VS Code, you will need to regenerate this cache when you open the project again. To do this, press F1 and type crane rebuild cache. This will then re-index the workspace and rebuild the cache file.

Commands

Crane has some commands that you can run manually to perform certain actions:

Report PHP Intellisense Bug
This command allows you to navigate directly to the GitHub issues page to report a bug with Crane.

Reindex PHP files in the workspace Ctrl + Shift + R or Cmd + Shift + R on Mac
This command allows you to reindex all PHP files in the workspace. This is useful to rebuild the cache if something isn't working correctly.

Delete all PHP file caches
This command deletes all of the existing workspace caches. Over time these cache files can build up and consume disk space, so running this command infrequently is probably a good idea.

Download PHP library stubs
This command allows you to download and install the PHP library stubs for the built-in classes and selected PHP extensions.

These commands can be run by pressing F1 and typing crane to see a list of suggestions.

Crane's Features

Crane currently has a limited feature-set and can only provide semi-basic code-completion for variables, classes, functions and class level properties and methods accessed via $this->, self::, or via an instantiated variable (eg. $foo = new Bar(); $foo->).

Crane's Limitations

Crane cannot currently provide suggestions for nested instantiated properties (eg. $this->prop->).

It also does not currently parse phpDoc comments; these will just be ignored.

Crane Settings

Crane has a number of settings that can be configured in your global user settings, or in the workspace specific settings.

crane.showStatusBarBugReportLink
This setting allows you to show or hide the link in the status bar footer prompting you to file a bug report if you find an issue with Crane.

crane.saveCache
This setting allows you to enable or disable the cache functionality that stores the generated AST to a local file for fast access when reloading a project.

crane.debugMode
This setting allows you to enable debug mode which generates log information about files being parsed and errors that might be generated. In future this may be expanded to show additional code analysis or suggestion debug information.

crane.phpstubsZipFile
This setting allows you to define where the PHP library stubs will be downloaded from.

PHP Library Stubs

These files, available on the crane-php-stubs repository, contain "stub" classes/functions for built-in or selected 3rd party PHP extensions so that rich suggestions can be generated for them.

You can add your own stubs by creating a new folder next to the existing directory and putting your stubs inside.
TODO: Expand this

If you examine an existing stub (eg. PDO.php) then you will see the format required - all Crane needs is the class/function outline plus as much documentation as possible. No actual code inside each function is needed.