Features Releases

How to provide stubs for PhpStorm

We call PhpStorm “an IDE that actually ‘gets’ your code,” meaning that it provides completion, type inference, inspection, documentation pop-ups, and a lot more coding assistance.

For all the Standard PHP Library components as well as for common extensions, this functionality is based on PHP stubs. Stubs are normal, syntactically correct PHP files that contain annotated function, method, and class signatures, constant definitions, and so on. The coding assistance quality relies, apart from anything else, on the quality of these signatures and their PHPDoc @annotations provided in the stubs.

In this post, we’ll take a look at the bundled PHP stubs, learn how to get started with your own stubs, and even create a plugin that will attach an arbitrary stubs set to any PhpStorm project.

Viewing the bundled PHP stubs

To get an overview of what stubs are, take a look at the ones bundled with PhpStorm.

In the Project view, expand the PHP Runtime node under External Libraries and locate the bundled stubs under PHP Runtime:

bundled_stubs

While you can open any of these files in the editor to view their contents, modifying them directly is not possible. PhpStorm displays a warning message at the top of the editor panel to act as a reminder:

stub_open

Obtaining stubs

So, you’ve identified an issue with an existing stub, and want to address it. Or you’ve created your own stub from scratch. Good news: PhpStorm stubs are open source! They are hosted on GitHub, and from there they ultimately find their way into the PhpStorm distribution.

To get started with your own stubs, click the Clone on Github link at the top of the editor panel, which will take you to the stubs repository page.

While you can simply download a copy of the PHP stubs package, it will be more effective to clone this project so that everything is set up properly from the very beginning. To do so, make sure to register your GitHub account credentials in PhpStorm first.

Next, follow these steps:

  1. Fork the stubs repository. You may want to refer to this GitHub article for more details on how to do it.
  2. Copy your forked repository URL to clipboard:
    copy_clone_link
  3. In PhpStorm, start a new project by cloning a GitHub repository. Choose VCS | Checkout from Version Control | Git and provide the repository URL:
    clone_repo
  4. Click Clone.

After PhpStorm fetches everything, the PHP stubs project clone will be at your full disposal: you can now edit stubs or create your own ones.

Using custom stubs

Let’s say you’ve decided to follow PSR-7 and rely on RequestInterface instead of using the $_GET and $_POST superglobals. As a result, you’ve added the corresponding @deprecated annotations for these variables in the _superglobals.php stub.

When you are finished with your edits, you may want to appoint the modified stubs to be used by PhpStorm instead of the bundled ones. To do this, navigate to Settings | Languages & Frameworks | PHP.

On the PHP Runtime tab, you can view the list of the currently loaded stubs and enable only the stubs that you actually need. You can also quickly pick out the stubs that match the currently loaded set of PHP extensions by clicking Sync Extensions with Interpreter.

To switch to a different stubs set, provide the path to the stubs folder under Advanced settings:

default_stubs_path

Now, when you invoke code completion, the variables that you’ve marked as deprecated will be displayed crossed out:

When using custom stubs, do not forget to periodically pull the most recent version from our repository so that you are up-to-date with the latest changes. This GitHub article will provide you with the information for properly updating your fork.

Sharing stubs

You are always welcome to share your stubs with the PhpStorm community!

To do this, push the changes to your remote repository via PhpStorm. Then, create a pull request to the original repository, as described here. We’ll look into your request and merge it into the distribution as soon as possible.

There are a couple of considerations to keep in mind:

  • Technical: stubs need to include the complete PHPDoc, especially the proper @return and @since annotations.
  • Legal: if you’ve created stubs based on some publicly available information source (e.g. you’ve transformed the official publicly available documentation to the appropriate form), make sure to provide the link to this information source together with your stubs.

When in doubt, refer to our contribution guide.

Creating External Libraries

A lot of the popular PHP frameworks’ code is covered with stubs, too, which serve for aiding IDEs with code completion and inspection. These stubs are commonly open-source and can be easily obtained online. You may want to package them into an External Library: the files will be explicitly added to the project’s index to provide coding assistance. Note, however, that they are not meant to be edited in the scope of a project.

To streamline the creation of a custom external library, use the PhpStorm Library Plugin. Follow the provided instructions, and you will be good to go in no time.

As an example, let us create a plugin that will provide us with coding assistance for the Phalcon PHP framework:

  1. Download the Phalcon stubs package and the PhpStorm Library Plugin from GitHub.
  2. Replace the plugin’s library example folder with the src/Phalcon stubs folder.
  3. Review the plugin.xml file under META-INF: at the very least, you need set the proper plugin name and the library root folder.
  4. Package the contents of the Plugin folder by running
    zip -r phpstorm-library-plugin.jar *
  5. In PhpStorm, navigate to Settings | Plugins, and install the plugin from disk as you would do with any other third-party plugin.
  6. Restart the IDE.

That’s it! In the Project view, your library is now available under External Libraries. The contents of your library, in turn, is used to provide coding assistance to any PhpStorm project:

lib_added

And of course, if you feel that the plugin is worth sharing, please feel free to upload it to the plugins directory. Every contribution counts, and helps to make PhpStorm better for everybody.

Your JetBrains PhpStorm Team
The Drive to Develop

image description