How settings do work in PhpStorm 2017

02/27/201809/21/2018 SoC

PhpStorm 2017 is eminently configurable. You can adjust more or less any aspect of the IDE. In particular, the user interface (UI) can be very finely tuned to fit your needs.

Configuring the code syle for PHP in PhpStorm 2017.3

Sadly, the way settings work can turn you crazy. The are no less than three ways to tune the settings at any time :

at the welcome screen, the Configuration button, then Settings ;
if a project is opened, the File menu, then Settings ;
if a project is opened, the File menu, then Default Settings.

Moreover, in some cases, a setting may be tuned by telling PhpStorm that its value should be related to a “profile” ou a “scheme”…

The main problem with settings in PhpStorm is that the entry point for tuning settings does not talk to the user. How to tune a setting and apply the new value to a set of projects ? How to tune a setting so that the new value should only apply to projects to come ? The user has to work it by himself to find answers to such basic questions.

Since nobody ever published a good in-depth explanation about how settings do work in PhpStorm 2017, let’s explore the possibilities of PhpStorm 2017.3 to understand how all of this may be achieved.

Ciquez ici pour lire cet article en français.

What is a setting in PhpStorm 2017 ?

Let’s start by clarifying the notion of setting. The are two types of setting :

those that apply to the IDE ;
those that apply to projects.

For example, the settings in Editor / Font do apply to the IDE, and those in Editor / Code Style do apply to projects (you can guess it because of the small icon on the right).

Settings for the IDE and for a project in PhpStorm 2017.3

In PhpStorm 2017.3, settings that apply to projects are grouped in various categories, including Appearance and Behaviour, Editor and Version Control.

Some tests to guess how settings do work

Start PhpStorm 2017.3 for the fist time (you don’t need to reinstalle PhpStorm 2017.3 for that ; just delete the contents of C:\Users\<user>\.PhpStorm2017.3). Choose “Darcula” to avoid tiring your eyes and tell PhpStorm that it should use the default settings.

In the welcome screen, click on Configure and select Settings.

Configuring PhpStorm 2017.3 from the welcome screen

Navigate to Editor / Code Style / PHP. The selected scheme should be Default.

Check Use tab character and set Tab size to 8. Notice that two folders are created in C:\Users\<user>\.PhpStorm2017.3\config:

A codestyles folder containing a Default.xml file. As expected, this file contains both settings values:
```
<option name="TAB_SIZE" value="8" />
<option name="USE_TAB_CHARACTER" value="true" />
```
A options folder containing a bunch of files, among which a code.style.schemes file. This file contains this line:
```
<option name="PREFERRED_PROJECT_CODE_STYLE" value="Default" />
```

Go back in Editor / Code Style / PHP. Select the Project scheme.

Use tab character is not checked and the value of Tab size is 4. Check Use tab character et set Tab size to 16. The code.styles.schemes file in C:\Users\<user>\.PhpStorm2017.3\config\optionsis updated as follows:

<option name="PER_PROJECT_SETTINGS">
	<value version="173">
		<codeStyleSettings language="PHP">
			<indentOptions>
				<option name="TAB_SIZE" value="16" />
				<option name="USE_TAB_CHARACTER" value="true" />
			</indentOptions>
		</codeStyleSettings>
	</value>
</option>
<option name="USE_PER_PROJECT_SETTINGS" value="true" />

Go back in Editor / Code Style / PHP and just select the Default profile. Once again, the code.styles.schemes file is updated to reflect the selected scheme:

<option name="PREFERRED_PROJECT_CODE_STYLE" value="Default" />

Create a new project starting with an empty folder, and add a new PHP file to it.

In the editor, pressing the Tab key does insert a 8 characters wide tabulation character. This means that the Default profile is active, as it could be expected.

The folder of the project does contain a .idea folder. In this folder, there is a codeStyles subfolder. This subfolder contains two files:

codeStyleConfig.xml, which tells that the settings in the Default scheme should apply to Code Style category :
```
<option name="PREFERRED_PROJECT_CODE_STYLE" value="Default" />
```

Project.xml, which contents we have already met since it comes from code.styles.schemes:

<codeStyleSettings language="PHP">
	<indentOptions>
		<option name="TAB_SIZE" value="16" />
		<option name="USE_TAB_CHARACTER" value="true" />
	</indentOptions>
</codeStyleSettings>

The IDE offers two new ways to tune the settings : File / Settings (Ctrl + Alt + S) and File / Default Settings.

Select File / Settings and go to Editor / Code Style / PHP (starting from now, I will not mention this again). The selected scheme being Default, set Tab size to 2. The only file which gets updated is Default.xml. Its contents gives the new values of the settings:

<option name="TAB_SIZE" value="2" />
<option name="USE_TAB_CHARACTER" value="true" />

In the editor, the tabulation character is now 2 characters wide.

Select File / Settings again. This time, select the Project scheme. Use tab character is checked and Tab size is 16. Just apply the tuning. The only file which gets updated is codeStyleConfig.xml. Its contents tells that the Project scheme should now be used:

<option name="USE_PER_PROJECT_SETTINGS" value="true" />

In the editor, the tabulation character is now 16 characters wide.

Once again, select File / Settings. The Project scheme still being selected, set Tab size to 6. The only file which gets updated is Project.xml:

<option name="TAB_SIZE" value="6" />

In the editor, the tabulation character is now 6 characters wide.

Select File / Default Settings. The Default scheme is selected, Use tab character is checked and Tab size is 2. Select the Project scheme. Use tab character is now checked and Tab size is 16.

How do settings work in PhpStorm 2017

What did we learn? If a setting does apply to projects (remember that a setting may apply to the IDE or to projects):

tuning the Default scheme with File / Default Settings is the same as tuning it with File / Settings, or Configuration / Settings in the welcome screen ;
tuning the Project scheme by using File / Default Settings is not the same as tuning it with File / Settings, but it is the same as tuning it with Configuration / Settings in the welcome screen.

When a project is created, it comes with a configuration which is a copy of the default configuration for a project such as tuned in the welcome screen (and maybe later updated with File / Default Settings in the context of whatever project is open). This configuration describes the values of the settings which apply to projects only. There are two types of such settings:

Some settings which values always apply to a given project. Once the project is created, tuning the value of the setting will only affect the project since it is stored in the project .idea\codeStyles folder. As an example, the settings belonging to the categoy Editor / Copyright / Copyright Profiles. You may guess it because of the For current project mention in the top of the configuration page.

From the welcome screen, it is possible to tune this setting after a project has been created, but it will never affect the configuration of this project. This configuration can only be tuned with File / Settings when the project is open.
Some settings which values may be specific to a project or shared among all projects. As an example, the settings belonging to the category Editor / Code Style / PHP. In the configuration page, you may select a scheme (the name of the concept is related to the category of settings; it is a profile for Editor / Inspections) to tell if the project should use the configuration stored at the IDE level (the C:\Users\<user>\.PhpStorm2017.3\config folder) ou the configuration stored at the project level (its .idea\codeStyles folder) for this category of settings only.

So, the various files are:

In the C:\Users\<user>\.PhpStorm2017.3\config\options folder of the IDE:
- In the codestyles folder, Default.xml contains values for the scheme Default:
```
<code_scheme name="Default" version="173">
...
</code_scheme>	
```
- In the options folder, code.style.schemes contains the values for the settings of the Projectscheme…:
```
<option name="PER_PROJECT_SETTINGS">
...
</option>
```
  …and tells if the values to use for those settings for a new project should be those or those of the Default scheme (found in the previous file):
```
<option name="USE_PER_PROJECT_SETTINGS" value="true" />
```
  ou :
```
<option name="PREFERRED_PROJECT_CODE_STYLE" value="Default" />
```
In the .idea\codeStyles folder of a given project:
- codeStyleConfig.xml tells if the values for the settings are those of the Project scheme or those of the Default scheme:
```
<option name="USE_PER_PROJECT_SETTINGS" value="true" />
```
  or:
```
<option name="PREFERRED_PROJECT_CODE_STYLE" value="Default" />
```
- Project.xml contains the values of the settings of the Project scheme, as defined when the project was created by copying the code.style.schemes file, and later possibly tuned at the project level (using File / Settings when the project is open) :
```
<code_scheme name="Project" version="173">
...
</code_scheme>
```

So, how to update the configuration after several projects have been created, and have the modifications affect all those projects ? Well, it is only possible for the settings belonging to categories for which the user may choose a configuration stored at the IDE level :

Editor / Code Style (using a scheme)
Editor / Inspections (using a profile)
Editor / File and Code Templates (using a scheme)

Test it! The project being open, select File / Settings and select the Default scheme (Use tab character checked, Tab size set to 2). Close the project. In the welcome screen, click on Configure and select Settings. The Default scheme being selected, set Tab size to 7. Open the project again. In the editor, the tabulation character is 7 characters wide.

So you cannot refer to a centralized configuration for each and every settings. This may have turn some users angry, as here.

But as it is explained in this message, you can always export a configuration (decentralized at the project level by using File / Export Settings… or centralized at the IDE level by using Export Settings) and import it at the level of the project (by using File / Import Settings…) or the IDE level (by using Import Settings). This works with the settings of the following categories :

Code Style
Code Style (schemes)
Debugger
Default Project
Editor Colors
File Templates (schemes)
Look and Feel

One last word. If you are tuning some settings in a configuration page, two things will happen before you apply the modifications :

a Reset button appears in the top left corner of the page, and you may click on it to restore the values of the settings ;
the categories of settings from which one setting at least has been modified are displayed in blue in the list of categories.

Stash of Code

Bits of help for writing code

Menu

How settings do work in PhpStorm 2017

What is a setting in PhpStorm 2017 ?

Some tests to guess how settings do work

How do settings work in PhpStorm 2017