Debugging with PhpStorm

This article describes how to use PhpStorm to efficiently develop and debug TYPO3 extensions.

Overview:

What is PhpStorm?

Quoting what JetBrains says about it:

PhpStorm is a lightweight and smart PHP Editor focused on developer productivity that deeply understands your code, provides smart code completion, quick navigation and on-the-fly error checking. It is always ready to help you shape your code, run unit-tests or provide visual debugging.

It supports PHP, HTML, JavaScript — everything you need to develop your web-application.

Its  feature set is amazingly rich and I quickly decided to switch to this IDE instead of keep using Zend Studio after one of the TYPO3 Core Team members,  Dmitry Dulepov, informed us he discovered a new editor. Thanks for sharing this!

How my files are organized

My projects are stored under my home directory: 

/Users/xavier/Projects
    |-- TYPO3-Core
    |       |-- TYPO3_4-3
    |       |-- TYPO3_4-4
    |       `-- TYPO3_trunk
    `-- Extensions
            |-- Customer1
            |       `-- extension1
            |-- Customer2
            |       `-- extension1
            `-- Personal
                    |-- dbal
                    |-- …
                    |-- mantis_connect
                    |-- mvc_extjs
                    |-- …
                    `-- …

Then, I have different TYPO3 local websites. For instance: 

/Users/xavier/Sites
    |-- site_1
    |-- site_2
    |-- mysql.typo3dev.loc
    `-- oracle.typo3dev.loc

Each of these websites is a standard TYPO3 website with symbolic links. Thus I can link the typo3_src to the actual TYPO3 version I want to use. E.g., for  mysql.typo3dev.loc: 

/Users/xavier/Sites/mysql.typo3dev.loc
    |-- clear.gif
    |-- fileadmin
    |-- index.php -> typo3_src/index.php
    |-- t3lib -> typo3_src/t3lib
    |-- typo3 -> typo3_src/typo3
    |-- typo3_src -> /Users/xavier/Projects/TYPO3-Core/TYPO3_trunk
    |-- typo3conf
    |-- typo3temp
    `-- uploads

The same applies for extensions under development, they are symlinked to the actual Projects directory. E.g., with DBAL: 

/Users/xavier/Sites/mysql.typo3dev.loc
    |-- …
    |-- typo3conf
            |-- …
            |-- ext
                 `-- dbal -> /Users/xavier/Projects/Extensions/Personal/dbal.TRUNK

1 customer = 1 project

Open PhpStorm and choose to create a new project from existing files (let’s say for my Personal extensions thus choosing /Users/xavier/Projects/Extensions/Personal as source directory in the wizard):

My project will look like that:

What I miss however to efficiently develop is a reference to the TYPO3 sources, in order to have auto-completion of method names and, later, debug my extensions. This is easily done by adding another source directory to my project. To do this, choose File > Settings and add a reference to the TYPO3 source files (according to the version you use):

Debugging your extension

This is the funny part. You should open project settings again (File > Settings) and create a deployment server on your local host with the hostname you configured locally (e.g., localhost/):

Last but not least, you have to configure the deployment mapping, in order for PhpStorm to be able to know which source file is currently used when debugging your website. As I use symbolic links for TYPO3 sources, I add two mappings, one for t3lib/, the other for typo3/ and I set the mapping of my whole Extensions/Personal/ directory to typo3conf/ext/:

Now set the breakpoints you need in your extension (or even in TYPO3 itself) and start debugging your code.

The trick is to choose /typo3/backend.php as startup script if you want to debug Backend modules and /index.php for Frontend plugins: