Scopes are one of the less obvious features of PhpStorm. They add level of virtual organization in a project.
Scopes require a bit of initial setup to benefit from, but once in place they enhance general experience and make many other functions even more flexible.
PhpStorm Scopes in action.
Definition
Scopes are file–based. You can create multiple Scopes in a project. Each of them is defines logic of files included and excluded in it.
Define
Scopes are defined in Settings > Appearance & Behavior > Scopes.
Each scope has a Pattern with respective field in the creation dialog. Basic patterns can be created interactively, by using interface to include and exclude folders in project’s file tree.
More elaborate patterns can be edited directly, by using masks and some logical operators. See defining scopes in documentation for details.
The practical example of custom scope would be file:*sitemap*.php&&!file:tests//* pattern. This scope includes all PHP files that have “sitemap” in their name, except those in “tests” folder.
Color
One of the first things to do with a new Scope is usually to assign color to it. This is done in Settings > Appearance & Behavior > File Colors.
Colors show up in file tree and editor tabs (either can be disabled). This makes it easy to distinguish different Scopes.
PhpStorm doesn’t have native conventions for colors, other than yellow for libraries.
I tend to set colors either semantically (current task — green, deprecated code — red) or by association (WordPress — blue, QueryPosts — orange, and so on). It should just make sense to you.
Usage
Scopes seamlessly tie into many other PhpStorm features. Typically operations you perform on whole project can be done on a standalone Scope instead.
Navigate
As covered above Scopes are displayed in their color in the Project tool window. You can also use dropdown on top of it to restrict the view to only files of specific Scope.
Search
In all incremental searches (starting with Search Everywhere, double Shift) the matches will be colorized with scope as well.
More extensive search dialogs (such as Edit > Find > Find in Path…) tend to have explicit option to restrict search to a specific Scope.
Inspect
There are two ways to enhance Inspections with help of Scopes.
You can fine–tune Severity (complaining level :) of any Inspection by the Scope. Click In All Scopes dropdown in any Inspection and you can change or disable altogether the reported severity for different Scopes. This helps when certain Scopes are irrelevant or unfixable for some reason.
Another way is to run Inspection on demand via Code > Inspect Code… or Run Inspection by Name… and select a target Scope. This is very convenient when only part of code base needs to be cleaned up for specific purpose.
Scopes overall
Scopes become more useful as the size of a project grows. They add a level organization that is more flexible than directory structure (often practically fixed), allow to visualize it, and enable many of PhpStorm features to make use of it.
I consider it indispensable for larger legacy code bases, that have layers upon layers of code of different purpose.
jchlu #
Andrey “Rarst” Savchenko #