#StandWithUkraine

WordPress development in PhpStorm

I had been using PhpStorm for years now and recommend it a lot for WordPress development. Simply put WordPress code base is significantly large and very convoluted. Good IDE is not just beneficial for it — it is indispensable.

PhpStorm had steadily got more and more functionality, related to specific web development projects and standards. After years of hopes, whining to product manager on twitter (hi, Mikhail!), filing issues on bug tracker, and some consulting — version 8 had shipped with dedicated support for WordPress.

This post is by no means exhaustive guide to development in PhpStorm, but it summarizes much of my experience and techniques using it for WordPress projects.

Getting around

The first rule of PhpStorm — take food when going into settings. It is kind of software that can be freely molded by user over time and usually is.

There are two main things which help to manage complexity of configuration and usage both: search and hotkeys.

The widest and easiest search to start with is Search Everywhere — Double Shift hotkey. It is easy to remember and includes most of searchable elements (from PhpStorm’s own settings to code in a project). The one notable omission is WordPress hooks.

A little more specialized searches are:

  • Ctrl+Shift+A — PhpStorm functions and settings
  • Ctrl+Shift+Alt+N — symbol search, which includes all of code–related elements (including WordPress hooks) and lets narrow it down by type of file type/language
  • Ctrl+Shift+N — file search in project

There are several more, but these three see most use.

Another thing to keep in mind is that PhpStorm heavily uses incremental search. In most list–like elements you can usually simply start to type to narrow down, even if there is no explicit search field.

Hotkeys

While covering search already talked about hotkeys mostly, that doesn’t even begin to scratch surface.

There are two shortcuts to quickly pick up good starting set of them:

  1. Print a cheat sheet, available in menu Help > Default Keymap Reference and keep it close. It is very well selected set of basic hotkeys for common tasks.
  2. Install Key Promoter plugin ( Settings > Plugins ). It will automatically notify you about existing hotkey for a lot of things you do with a mouse in interface. It basically annoys you into using keyboard more. :)

Project organization

There are some nuances to putting together project in PhpStorm — both in what of sources to include and how to do it.

Folders

PhpStorm projects are inherently folder–centric. You open a folder with code in it and that folder becomes a project. .idea folder gets created inside of it and holds project’s own settings.

There are two ways to add more to the project:

  • content roots ( Settings > Directories > Add Content Root ) are additional directories with code, they will be “virtually” on same level in project tree, but won’t get separate settings folder inside
  • PHP includes ( Settings > PHP > Include Path > Add ) will show up under External Libraries in project tree; they will be read–only by default and would have lower priority in searches

Over time I cycled through following approaches:

  1. Giant project, including all of local server with multiple sites.
  2. Site projects, including everything in site’s folder.
  3. Focused projects, including one/few folders and external libraries as needed.

You can see that my projects kept getting smaller. There are two reasons for it:

  1. The large projects are simply slower, with more files for PhpStorm to index and navigate.
  2. PhpStorm gets very confused when you have multiple definitions of same classes in projects, not untypical between multiple plugins/themes using same libraries. It’s hard to untangle and easier to prevent.

I still have large project for my development site. For the rest I now tend to do:

  • plugin folder, WordPress core as library
  • theme folder, parent theme as content root, WordPress core as library

Additional things can be either root or library depending on situation, primarily if I want things from them to come up in search right away.

Scopes

Creating a scope ( Settings > Scopes ) allows to select parts of the project (without as much focus on folder structure) and group them together under arbitrary name.

This helps out in multiple ways:

  • assign colors to scopes ( Settings > File Colors ), it helps a lot when code base has distinctly separate parts
  • limit search/replace actions to specific scope
  • configure inspections for scope differently from project defaults

Version control

PhpStorm natively supports several version control systems. You start by adding version–controlled folders in Settings > Version Control. One of the most useful aspects is that you will immediately see markers for changed/added/deleted lines of code inline.

You can do bulk of version control actions without leaving PhpStorm. Personally I mostly do simple commits from it and run to comfort of dedicated tool (and sometimes discomfort of command line) for more complicated things (branching, merging, interactive staging, and so on).

Local history

One pretty special native feature is VCS > Local History. PhpStorm automagically tracks and remembers code edits, even without (or in parallel to) version control in use.

Believe me — one day this one will save you in a major way. :)

Code quality

One of the lines which separate development environments from code editors is amount of proactive insight and corrections to code issues. Even out of the box PhpStorm will inform about dozens of issues or potential issues in code. It works even better with some fine tuning for WordPress specifics.

Coding style

I had maintained configuration for WordPress coding style in PhpStorm for quite a while (my most popular gist ever), but now it’s built in!

Set it up by: Settings > Code Style > PHP > Set From > Predefined Style > WordPress

After that you can easily apply it to any file or code selection by Code > Reformat Code ( Ctrl+Alt+L ).

PHP CodeSniffer

Being able to easily conform to coding style is very helpful already, but you won’t know all of the places you aren’t — unless you are actively looking for it.

PhpStorm supports integration with PHP_CodeSniffer tool that can scan sources and check them for conforming to specific coding standard.

There is a WordPress Coding Standards ruleset for it (maintained by XWP, with some contributions by yours truly).

Install it, following instructions, then set up in PhpStorm:

  • Settings > PHP > Code Sniffer > PHP Code Sniffer path
  • Settings > Inspections > PHP > PHP Code Sniffer validation > Coding standard

After this you will proactively see coding style issues in editor.

Inspections

Speaking of inspections, as you use PhpStorm there would probably be quite a few not very fitting for WordPress development. I had never put together exhaustive list or configuration, but it’s pretty easy to just disable (or reduce severity level) in Settings > Inspections.

When your project includes massive amounts of code which doesn’t conform to sane PHP and/or WordPress practices (like *cough* WordPress core itself *cough*) you can create a scope for it (as above) and disable heavy inspections, like CodeSniffer integration, for it altogether.

PHP Mess Detector

PHP Mess Detector is another PHP utility PhpStorm integrates with. You can install it in similar fashion to CodeSniffer:

  • Settings > PHP > Mess Detector > PHP Mess Detector path
  • Settings > Inspections > PHP > PHP Mess Detector validation > Options

Unlike CodeSniffer it doesn’t have or need custom ruleset for WordPress, but you will probably want to disable several sections. The first Code Size Rules one is most useful and will alert you of excessive complexity of code.

Object Calisthenics

While not directly related to WordPress, I find Object Calisthenics to be interesting recommendation for development. There is CodeSniffer ruleset for it too. I add some of it to WordPress rules and it had been interesting and challenging to try and follow it.

Boilerplate

At the end of the day development is just typing, right? :) Being able to take shortcuts at that saves you from typing unnecessarily and speeds up the process. PhpStorm (of course) has features to help with that.

File templates

Whenever you create a new file (and in some cases part of file) PhpStorm uses template for it from Settings > File and code templates. These can be easily customized, as well as new templates added.

I have shared Wordpress plugin–related templates and parts I use in the gist.

Live templates

Live templates ( Settings > Live Templates ) work mostly inline. PhpStorm has large amount of them out of the box, including implementation of Emmet (ex–Zen Coding) for very fast HTML development.

These are most useful for often used functions. Especially often used bulky functions, which benefit a lot from being able to use variables in templates.

I had shared my WordPress Live Templates in the gist as well.

TL;DR

  1. Use PhpStorm v8+ with WordPress support
  2. Print hotkeys cheat sheet ( Help > Default Keymap Reference )
  3. Set WordPress coding style ( Settings > Code Style > PHP > Set From > Predefined Style > WordPress )
  4. Set up WordPress Coding Standards rules for PHP CodeSniffer
  5. Develop with pleasure

Related Posts

2 Comments

  • Paul Geisler #

    Thanks. I learned some new tricks. There is one think that bothers me a lot, i simple can't find a good way / right settings / workflow to use PhpStorm with XDebug and Wordpress under MAMP. Sometimes i get the right settings and it works, sometimes not. I don't understand the File-Mappings when it comes to define only the theme folder as a project. And i can't figure out if it's possible to display the errors (fatal error) directly in PhpStorm and not on the website.
  • Andrey “Rarst” Savchenko #

    XDebug and WordPress under MAMP
    Not much into xdebug, mostly because it makes my local stack noticeably more sluggish. But didn't have much issues with setup, I use Uniform Server stack.
    And i can’t figure out if it’s possible to display the errors (fatal error) directly in PhpStorm and not on the website.
    I use Remote Call plugin. It allows to click link to file:line in browser and have source code opened in PhpStorm, plenty debug tools (including xdebug) support outputting such links by now.