|This tutorial describes the features and best practices relevant to using PhpStorm as an IDE for WordPress development (including plugins, themes and core). Starting with version 8 (Early Access version available at this time), PhpStorm bundles the WordPress Plugin providing many WordPress-specific features.|
- Enabling WordPress Integration in an Existing PhpStorm Project, or Creating a New WordPress Plugin
- Enabling WordPress Integration in an Existing PhpStorm Project
- Creating a New WordPress Plugin
- Development Environment Configuration
- WordPress Hooks Support
- Completion for WordPress Action and Filter functions parameters (hooks completion)
- Navigation from Action and Filter functions (hook registration) to hook invocation
- Callbacks from Hook Registration
- Navigate to Symbol... for Hooks
- Find Usages for Hook Registration Functions
- Search on WordPress.org Right from the Editor
- WordPress Command Line Tool WP-CLI Integration
- PHP Code Sniffer with WordPress Coding Standards Integration in PhpStorm
- Debugging and Profiling WordPress with PhpStorm
When the project you're working on is recognized as a WordPress Plugin, you will be offered to enable support for WordPress automatically with a popup and event in the Event Log.
You need to provide WordPress Installation Path (root folder of your WordPress Installation, directory should contain wp-admin and wp-includes subdirectories).
WordPress integration settings can be changed in Settings | WordPress.
A new WordPress plugin can be created from the Welcome screen or by selecting File | New Project.
Project type should be set to WordPress Plugin. After clicking OK you need to provide WordPress Installation Path (root folder of your WordPress Installation, directory should contain wp-admin and wp-includes subdirectories).
Initial plugin file in the project will be created automatically (plugin-name.php with proper meta information skeleton).
Whether you enable WordPress integration in an existing PhpStorm project or create a new WordPress plugin, the IDE checks if the development environment is configured properly for WordPress development. If the configuration does not meet the requirements, pop-ups with a fix suggestion will appear, as well as events in the Event Log. To fix these issues, just click the Fix link.
Include Path Configuration (wp-content folder and/or plugin you are working on are OUTSIDE of WordPress installation)
In order to take advantage of PhpStorm's deep understanding of the code, code completion and other intelligent features, WordPress installation should be included as an external library in the IDE. As soon as WordPress installation path is provided in WordPress integration configuration, the IDE will offer to include WordPress installation path as included path in your project.
You can always change Include path in Settings | PHP | Include path.
|In this use case, WordPress installation has to be added as an external library to have all the WordPress core files indexed, but other plugins/themes are NOT included by default (when wp-content folder is located somewhere else), and in order to add them you can just do that in Settings | PHP | Include path (or in Settings | Directories | Add content root if you would like to change them in your project, or need them to be under VCS).|
Content Root Configuration (wp-content folder and plugin you are working on are INSIDE WordPress installation)
If you are developing WordPress plugin located inside WordPress installation folder, the IDE suggests adding the entire WordPress installation as content root and remove the initial content root.
Content root can always be configured in Settings | Directories.
|In this use case it's recommended to mark the entire WordPress installation configured as a Content Root, and all other plugins/themes are included in your project in this case. In order to exclude any of them, you can just mark them as excluded folders in Settings | Directories. Root directory is still considered to be a plugin root though (not the root of the entire WordPress installation, so .idea folder would be located inside plugin directory).|
When WordPress integration is enabled, you will automatically be offered to set WordPress Code Style based on the coding standards.
Code Style can always be re-configured in Settings | Code Style | PHP. WordPress-specific code style can be applied with Set from... | Predefined Style | WordPress.
|Learn more about hooks in official WordPress documentation and WordPress hooks directory by Adam Brown.|
Any hooks declared in WordPress core and included plugins are indexed by the IDE, and hook names become available in code completion with Ctrl+Space for standard action and filter functions parameters (add_action and add_filter).
From WordPress hook registration (with add_action and add_filter functions) you can navigate to hook invocations with a navigate icon on the editor gutter:
You will be navigated to the very line where the relevant hook is invoked with do_action (in our case) or other invocation method.
Going to declaration of function/method specified as the second parameter of actions/filters hook registration functions (add_action and add_filter) can be performed with Ctrl+Click (CMD-Click on Mac OS X) or Ctrl+B (CMD-B on Mac OS X).
You will be navigated to the very line where the relevant function/method is declared.
With Navigate | Symbol... (Ctrl+Alt+Shift+N on Windows/Linux, CMD-ALT-O on Mac OS X) you can search for hook invocations and easily navigate to them.
Similar results can be achieved with Search Everywhere (Double-Shift). Make sure to enable Include non-project items option if needed.
Invoking Find Usages action (Alt-F7) for hook registration functions will provide a list of possible options (so that you select what you are looking for in terms of hook/function name).
WordPress Documentation at http://wordpress.org/ can be easily reached from the IDE by using text search. Just select the text you are interested in, invoke the context menu in the editor, and then select Search on WordPress.org.
The default browser will be opened in order to reach WordPress documentation with the request you sent from the IDE.
WP-CLI is a set of command-line tools for managing WordPress installations. You can update plugins, set up multisite installs and much more, without using a web browser.
We recommend installing WordPress Command Line Tool WP-CLI, either by following the official website instructions (via downloadable PHAR package) or with Composer right in PhpStorm (package wp-cli/wp-cli). Refer to this tutorial for more information about using Composer in PhpStorm.
To configure WP-CLI as a command line tool in the development environment, open Settings | Command Line Tool Support and add a new command line tool with the plus icon:
Specify tool type as WP-CLI, choose visibility (project or global), click OK to proceed, and then provide the path. Command definitions will be loaded automatically by the IDE.
Now you can bring up the command line tool by selecting Tools | Run Command... or pressing Ctrl+Shift+X (Cmd-Shift-X on Mac OS X).
Command completion is provided for WP-CLI commands. All output is shown in the PhpStorm Command Line Tool Console.
Read more about command line tools in PhpStorm.
PHP Code Sniffer is a tool designed to detect violations of a defined coding standard. It is an essential development tool that helps ensure your code remains clean and consistent. It can also help prevent some common semantic errors made by developers.
WordPress Coding Standards rules for PHP Code Sniffer are maintained in this GitHub repository by the community.
PHP Code Sniffer is supported in PhpStorm, which means you can get its notifications inside the IDE editor. WordPress-specific coding standards are easy to add in PHP Code Sniffer, so that WordPress Coding Standard violations will be shown in the IDE editor along with standard PHP Code Sniffer notifications.
2. Download WordPress Coding Standards rules for PHPCode Sniffer following installation guide described in the GitHub repository. You can download the entire package as an archive or check it out from git repository.
3. Unpack the downloaded archive (if needed) and navigate to the directory containing files (the one with Sniffs folder and ruleset.xml file inside). You need to move all the directory contents to /usr/share/php/PHP/CodeSniffer/Standards/WordPress (path depends on your configuration). There should be ruleset.xml in this directory and some other subdirectories.
4. Configure PHP Code Sniffer by providing the path in Settings | PHP | Code Sniffer. Click the Validate button to check if the Code Sniffer tool can be reached.
5. Turn on PHP Code Sniffer inspections in Settings | Inspections | PHP | PHP Code Sniffer validation. Select WordPress coding standard in the list (use the refresh button if needed). Click OK.
6. Now your code is inspected by PHP Code Sniffer with WordPress Coding Standards, in addition to PhpStorm's inspections. You will see notifications marked phpcs in the editor.
7. If you run batch inspections with Code | Inspect Code PHP Code Sniffer, the results of PHP Code Sniffer inspections will be listed in the section PHP | PHP Code Sniffer validation.
WordPress-based projects can be debugged and profiled without any WordPress-specific configuration. Please proceed with standard PhpStorm debugging or profiling workflow.