Beginner's Guide to PhpStorm - Tips & Tricks

For years I was a happy Sublime Text user for my development needs. Everyone kept mentioning that PhpStorm is what you should use for development as it would help you a lot, and save a lot of time. Every year or so, I gave it a try, and soon gave up. It was just too bloated, too slow, and too Java looking. Maybe a lot of things changed, or maybe my approach to it changed, but I'm using PhpStorm for almost a year (at the time of writing) for development, and I just can't think about going back to use something else. This article is a bunch of tips which I think would have helped me in starting to use it earlier, and think it could be useful for others.

Keep in mind that it's based for OSX, there might be slight differences if you're using a different operating system. Some of the configurations are project based, meaning that you will have to make them for each project you work on.

Skip to any of the sections or continue reading:


A great starting point (you can familiarize yourself with the IDE without installing it) are the screencasts Be Awesome in PhpStorm by Laracasts and Lean and Mean Dev with PhpStorm (for Symfony) by Knp University. Both of them will inform you how to configure your IDE, how to navigate in it, and how to use all/most of the tools provided by it to make your development easier. Some of the topics overlap, but I would still suggest to check out both of them. You might skip Knp University screencast if you don't do Symfony development as it's more focused on it.


Check the download page for the latest information about installing. Everyone has their own installation preferences making it pointless providing all of them in an article like this. Personally, I use OSX with brew, so for me installation is running install command in terminal:

brew cask install phpstorm

Changing PhpStorm Settings

You can change the settings of PhpStorm my making changes to, or *.vmoptions files. You should not make changes to the original files. If you want to make changes to them, copy the file to a directory defined by your operating system.

The easier way is to use Help | Edit Custom Properties, or Help | Edit Custom VM Options options from the main menu of launched IDE. This will create an empty file, or open an existing one for you to edit.

You can read more about about this in Tuning PhpStorm help section.

Fix a Warning of Case Sensitive File System in OSX

If you use OSX and your file system is case sensitive you will get warning notification with and URL providing more information about it. I personally don't think that page is providing much information as there are multiple people providing similar solutions, and multiple people saying that they worked/not-worked for them. It provides more confusion that solves anything.

The simplest solution is to choose Help | Edit Custom Properties (or edit your file), and put in it. You will have to do this every time you update/install PhpStorm.

PS: I'm still not sure why that warning notification can't have a button "Yes I use case sensitive file system", which after clicking would just add that line to properties file.

Change CPU usage for indexing

One annoying thing you might run when opening PhpStorm is that it will slow your machine to the crawl because it's indexing all the files. Personally I'm more interested in the machine which is performing rather than the one which finishes the task faster.

Go to Help | Edit Custom VM Options, and put -Djava.util.concurrent.ForkJoinPool.common.parallelism=2 in it.

Disable Staging Created/Deleted Files

Version Control is a good example of IDE trying to do everything, and one of things I would rather do using external tools. You could disable it, but one thing I like it for is visual reminder (different file color, color blocks near line numbers) of what files have changed since last commit.

To disable automatic staging of files go to Preferences | Version Control | Confirmation, choose:

  • Do not add for When files are created option
  • Do not remove for When files are deleted option

Enable Auto-Import of PHP Namespaces

To make IDE automatically import PHP namespaces, add use statements, and complete short class names on the fly when typing go to Preferences | Editor | General | Auto import, make sure that options Enable auto-import in file scope, and Enable auto-import in namespace scope are enabled.

Improve Visual Feedback

To keep the mind on important things the developers often expect the tools to provide visual feedback when something is wrong (or possible issue). The following settings ensure that it will be easier to spot possible issues, improve readability, and keep code clean.

  • Preferences | Editor | General:
    • enable option Ensure line feed at file end on Save
  • Preferences | Editor | General | Appearance:
    • enable option Show line numbers
    • enable option Show whitespaces
  • Preferences | Editor | General | Editor Tabs:
    • enable option Mark modified tabs with asterisk
  • Preferences | Editor | Code Style:
    • set option Right margin (columns) to 80

Surround Selection on Typing Wrapping Character

If you want selected text to be surrounded with associated symbol when pressing any one of "[ { ' "" rather than replaced with that symbol go to Preferences | Editor | General | Smart Keys and enable Surround selection on typing quote or brace option.

Line Comments at Beginning of the Code

Comment with Line Comment (⌘/ keyboard shorcut) can be very useful. The only problem I find with it is that it adds line comment at the first column no matter at that indentation level your code is. This is a personal preference, but I prefer when line comments are right beside the code. Go to Preferences | Editor | Code Style | PHP | Other, un-check Line comment at first column, check Add a space at comment start.

Back-up IDE Settings

Local backup

You can back-up your IDE settings by including the settings directory to the application what does your back-ups. The settings are stored in /Users/<username>/Library/Preferences/<product-name> directory. This directory will change depending on the user and version, for example my current settings are kept in /Users/ifdattic/Library/Preferences/PhpStorm2016.2 directory. Just remember to update your back-up strategy after installing new IDE version.

Git based backup

Warning: I removed this after a day, as I assume this just messed up all of my keymaps (resetting them to default), and maybe even some other configurations. For the time being I don't trust it enough to use myself, proceed on your own.

Another method which I just found while writing this article is using git repository, you can read more about this in this help page.

Just create a GitHub Repository (private repository works if you don't want to share your settings with others), and add it through File | Settings Repository.... For the first time you will want to Overwrite Remote to push your settings.

From documentation it appears that settings are synced when you perform a VCS action of Push..., or Update Project. If like me you don't use VCS actions in IDE, you can perform Sync Settings action to sync your settings. The issue might be that you will forget to run that action.

Set Up a New (Symfony) Project

There are some configurations that you do when you start a new project to get better IDE support for it. This is based on Symfony project, but you can do similar configurations for any project.

First exclude vendor and var directories. To mark a directory right click on it, from menu choose Mark Directory as, and then choose the type of mark. This will make sure they don't get in the way then you're looking for some file. Now, because you might still want to search for 3rd-party library files add the vendor directory as a library root by going to Preferences | Languages & Frameworks | PHP and adding the vendor directory as Include path.

You will also want to mark src directory as Sources Root.

Go to Preferences | Languages & Frameworks | PHP | Symfony and enable the plugin by checking Enable Plugin for this Project option. From the same window change app/ to var/ in Path to urlGenerator.php and Translation Root Path options if you're using a new Symfony directory structure.

Go to Preferences | Languages & Frameworks | PHP to choose the PHP language level and Interpreter for current project.


Below is a list of plugins I found useful for improving my workflow.

  • BashSupport add support for bash language (syntax highlighting, inspections, etc.)
  • Dash add shortcut to access Dash from IDE
  • gfm add markdown support
  • Lines Sorter add support to sort selected lines (or whole file)
  • PHP Advanced AutoComplete it extends the support of auto-completion
  • PHP Annotations add PHP annotations support
  • Php Inspections (EA Extended) it extends the inspections (Static Code Analysis)
  • Pipe Table Formatter format pipe (|) delimited tables. This is very useful when working with Behat, but later found that Reformat Code (⌘⌥L) can do that too (so not needed anymore for simple cases)
  • Scratch allows to have temporary editor tabs. In IDE all the files must be on the file system, which can be a hassle if you just need something to jot your notes on, or for similar throw away actions
  • Symfony add support for Symfony (dependency injection container, doctrine, twig, etc.)

Add Ruby Syntax Highlighting

I normally don't work with Ruby, but sometimes it's required to make changes to some Ruby file (like Vagrant configuration), and having syntax highlighting helps a lot. You can find the full answer on how to do it on this Stack Overflow answer.

In short you need to:

  • Git clone Ruby.tmbundle
  • Add that directory to TextMate Bundles in Settings
  • If *.rb files are not recognized you might need to modify Ruby.tmbundle\Syntaxes\Ruby.plist file

How to Configure Development Environment

For most projects you will want to make changes to your development environment configuration. This will give you proper errors depending on PHP version, and interpreter for debugging.

Screenshot of development environment configuration in PhpStorm

To change PHP version used go to Preferences | Languages & Frameworks | PHP, select your PHP version from PHP language level drop down.

Then click the button with 3 dots near the CLI Interpreter. In opened window click the + icon, and choose From Vagrant, ... option. It will open Configure Remote PHP Interpreter window where you need to choose Vagrant option, the IDE should pick the configuration automatically. Press OK, and then Yes to connect to remote host. Enter the name for the interpreter, and press OK when done.

How to Configure Xdebug

Read this in the "How to use Xdebug in PhpStorm article".

How to Make a 4 Editors Grid Layout

Most of the time 2 editors split horizontally/vertically is enough for good development workflow. If you have a screen estate, and need to modify multiple files a grid layout of 4 editors is helpful.


It's easy to split the current editor into 4 editors, but your initial split will define in what order the cursor moves when moving between panes using shortcut.

If you start with a horizontal split, and when split both of them vertically the cursor will move in order of 1 -> 2 -> 3 -> 4 when pressing the next split shortcut.

If you start with a vertical split, and when split both of them horizontally the cursor will move in order of 1 -> 3 -> 2 -> 4 when pressing the next split shortcut.

How to Create Command Line Launcher

Sometimes you might want to use PhpStorm from the command line (e.g., to compare some files, open a file/directory in it). This can be achieved by using a CLI script which PhpStorm can create for you automatically.

Go to Tools | Create Command-line Launcher... which should open a prompt where you can enter the name, and location for a script. For example you can put something /usr/local/bin/phpstorm. In that case if your CLI script would be phpstorm, and you could open a current directory by running phpstorm . in command line. Personally I like to name my script as storm.

You might need to do this if you have multiple PhpStorm versions, or you have recently upgraded.

Keyboard Shortcuts

In my opinion Sublime Text made very good choices for keyboard shortcuts, and I think it was a big issue when trying to move PhpStorm. Great thing is that you have a lot of freedom when configuring your IDE. Press the ⌘, to open preferences (Main menu | File | Preferences...) window, and when choose Keymap. You can search for an action you want to do, or lookup by pressing the shortcut.

Below is a list (in no particular order) of shortcuts I found comfortable, and use most often. Please keep in mind that for personal preferences some combinations are not available, or reserved by global shortcut (e.g., plus number is for moving windows around on my machine). You might think that there are a lot of shortcuts missing from this list, the way I see it is that the more shortcuts you have to remember, the less you will remember. I try to remember those that provide most value, or are used most often, and for the rest just use it some other way (like through the Find Action ⇧⌘P). Some actions for which I have not found a good shortcut are marked with __NONE__.

⌘, => Preferences...; open up the preferences window

⇧⌘P => Find Action...; open up a prompt to execute action or option

⌘P => File...; open up a prompt to find a file

⌘R => File Structure; open up a prompt to display file structure (methods, variables, etc.)

⌘L => Go To Line;

⌘B => Declaration; go to the declaration of the element

⌘↓ => Jump To Source;

⌥⌘B => Implementation(s); open up a prompt with the implementations of class/interface, good for navigation when trying to figure out code

⌘↑ => Jump to Navigation Bar; open up a small horizontal bar to navigate the project, very useful for creating/deleting files

⌘N => New... | Generate...; create a new file from navigation bar, or generate code from editor tab

⌥↑ => Extend Selection; selects more of the code / text (stopping at scopes)

⌥↓ => Shrink Selection; selects less of the code / text (stopping at scopes)

⌘⌥L => Reformat Code; reformats the code using your defined code style (selection or whole file), also reformats BDD feature file tables

⌃T => Refactor This...; opens up a prompt with choices for reformating the code (move, copy, extract, etc.), options change depending on the context

⌘C => Copy; works on selection, or current line if nothing selected

⌘V => Paste; works on selection, or current line if nothing selected

⌘X => Cut; works on selection, or current line if nothing selected

⌘⌫ => Delete; works on selection, or current line if nothing selected

⌥⏎ => Show Intention Actions; opens up a prompt for field initialization, class importing, etc. (very powerful for writing less code once you get used to it)

⌘D => Add Selection for Next Occurrence; add next occurrence to selection

⌃V => Split Vertically; split the editor (with current file in the new and old splits), can go indefinitely

⌃H => Split Horizontally; split the editor (with current file in the new and old splits), can go indefinitely

⌘⌃→ => Goto Next Splitter; move between splits

⌘⌃← => Goto Previous Splitter; move between splits

__NONE__ => Change Splitter Orientation;

__NONE__ => Unsplit All;

⌘⇧] => Select Next Tab;

⌘⇧[ => Select Previous Tab;

__NONE__ => Move To Opposite Group;

__NONE__ => Open In Opposite Group; when you want to have different parts of the file open

⌘T => Reopen Closed Tab;

⌘⇧F => Find in Path...; open up a prompt to search in whole project

⌘⇧R => Replace in Path...; open up a prompt to search and replace text in whole project

⌘+ => Expand; unfold code at cursor

⌘⇧+ => Expand All; unfold all code in file

⌘- => Collapse; fold code at cursor

⌘⇧- => Collapse All; fold all code in file

⌘⇧↑ => Move Statement Up; move whole part of statement (method, line, loop, etc.) up paying attention to code

⌘⇧↓ => Move Statement Down; move whole part of statement (method, line, loop, etc.) down paying attention to code

⌥⇧D => Listen For Debugger Connections; start/stop debug session, rarely use it as for me personally it's easier to use Menu Bar Search Alfred workflow (by using m start, or m stop)

v⌥R => Resume Program; to continue the execution after stopping at breakpoint during the debugging session

⌘⇧D => Search in Dash;

⌘K => Other | Project; open the project sidebar

⌘⇧W => Editors Tabs | Close All;

F12 => Jump to Last Tool Window; workflow example: search for something in whole project, select the result you want in results window, then press to show that file, or ⌘↓ to put a cursor at that location, press this shortcut to select different result

⌘⌥R => Resume Program; useful when debugging to continue code execution (it was conflicting with Alfred application RightClick workflow, the fix was to change workflow to only work for Finder application)

⌃⌥↑ => Scroll Up; change editor view without changing location of cursor

⌃⌥↓ => Scroll Down; change editor view without changing location of cursor

Useful, but seldom used

⌘⇧U => Toggle Case; switch between lowercase/uppercase, useful with Mac keyboard where Caps Lock key is dumb

⌘⇧8 => Column Selection Mode; toggle between normal selection, and rectangular selection

⌘⇧Z => Redo; I was more used to ⌘Y for redo

⌘⇧V => Paste from History...; open a prompt to choose content to paste

⌥F7 => Find Usages; search where selected element is used through whole project

⌘J => Insert Live Template...; open a prompt to insert live template

⌥C + ⌥A => New Scratch; start a new temporary file

⌥C + ⌥S => Open Scratch List; open a prompt with a list of temporary files

⌥⇧L => Sort Lines;

⌘⌥O => Symbol...; open up a prompt to find any symbol (methods, variables, etc.)

⇧⇧ => Search Everywhere; open up a prompt to search anything (class, option, method, etc.)

⌘E => Recent files; open up a prompt with recent files

⌘⌃P => Manage Projects...; open up a prompt with recent projects

__NONE__ => Compare with Clipboard;

⌥F12 => Terminal;

⌥F1 => Select In...; useful when you want to select current file in sidebar (rather than navigating to it manually)

Posted in: PHP, Technical, Tips, Tools