Settings Sync in PhpStorm: Aligning Personal Settings Across Devices

1. What Settings Sync is and which problem it solves

Settings Sync is a built-in PhpStorm feature that ties personal IDE settings to the logged-in JetBrains account and automatically replicates them across every device where the same account is used. This covers editor colors, keymaps, installed plugins, and many other personal preferences.

Without Settings Sync, every developer would have to redo all customizations manually after a fresh install or on a second machine, which quickly gets tedious and causes settings to drift apart between devices. Settings Sync replaces that with a one time login and automatic transfer in the background.

The effect is especially clear during onboarding: a new colleague can work productively on day one once Settings Sync has restored the familiar key bindings and preferred color schemes, instead of spending hours rebuilding personal preferences from scratch.

2. What actually gets synchronized

The scope includes UI theme, font size, and color scheme, keymap customizations, enabled and disabled plugins, personal live templates and postfix templates, plus numerous editor fine-tuning options like line wrapping or whitespace display.

Not synchronized are project-specific things such as run configurations with environment variables, the interpreter path of a particular project, or database connections with stored credentials. This separation is deliberate, so personal preferences never accidentally overwrite project-specific configuration.

Notes in scratch files, saved search patterns in the Search Everywhere history, and individually configured tool window layouts also belong to the synchronized scope, provided the relevant category is enabled, which makes switching between devices even more seamless.

3. Enabling Settings Sync and controlling its scope

The feature is enabled under Settings, Settings Sync, where individual categories can be toggled on or off after logging in with the JetBrains account. Anyone who wants keymaps synchronized but color schemes intentionally different per device can configure that granularly here.

Synchronized data is stored encrypted in JetBrains's cloud, though a custom storage location can also be configured through a Settings Repository, for example a private Git repository, when company policy does not allow third party cloud storage for configuration data.

Right after the first activation, a short test run on a second machine is worthwhile, to check that all desired categories actually arrive before relying fully on automatic synchronization and giving up local backups of the personal configuration.

<!-- .idea/codeStyles/Project.xml (project-wide, NOT Settings Sync) -->
<component name="ProjectCodeStyleConfiguration">
  <code_scheme name="Project" version="173">
    <PHPCodeStyleSettings>
      <option name="ALIGN_KEY_VALUE_PAIRS" value="true" />
    </PHPCodeStyleSettings>
  </code_scheme>
</component>

4. The .idea folder: project-wide settings inside the repository

While Settings Sync carries personal preferences, the .idea folder in the project repository handles team standards that must be identical for everyone: code style rules, inspection profiles, run configurations for PHPUnit or Magento CLI commands, and the assigned PHP interpreter.

Not the entire .idea folder should be versioned. Files like workspace.xml or tasks.xml hold purely local UI state and belong in .gitignore, while codeStyles, inspectionProfiles, and runConfigurations are deliberately checked in, so they apply automatically for everyone on checkout.

# Typical git status excerpt for the .idea folder
$ git status .idea/
	modified:   .idea/inspectionProfiles/Project_Default.xml
	modified:   .idea/runConfigurations/PHPUnit__Catalog_.xml

# workspace.xml and tasks.xml are deliberately in .gitignore
$ cat .gitignore | grep idea
.idea/workspace.xml
.idea/tasks.xml
.idea/httpRequests/

5. Decision guide: what belongs where

The simplest rule of thumb: anything an individual developer wants set differently out of personal preference belongs in Settings Sync. Anything that must stay consistent for team collaboration belongs versioned in the project's .idea folder.

A keymap is purely a matter of taste and clearly belongs in Settings Sync. A PHP version for the interpreter or an inspection profile with the team's Magento coding standard rules, however, affects everyone equally and must go into the project repository, not into personal sync.

A helpful follow up question is: would it harm the project if two developers had this setting differently? For a color scheme the answer is clearly no, for a PHPStan configuration file or an inspection profile it is clearly yes.

6. Resolving conflicts between sync and project-wide overrides

Conflicts typically arise when a project-specific setting in the .idea folder overrides a personal preference from Settings Sync, for example a project-wide color scheme for diff views. In such cases PhpStorm usually indicates which level is currently in effect.

When in doubt, project-specific settings in the .idea folder take precedence over globally synchronized values, since they are closer to the concrete project. Anyone who does not want that can remove the affected category from the project configuration and deliberately leave the decision to Settings Sync again.

In practice such conflicts rarely occur on a large scale, since project-specific overrides usually only affect a few deliberately chosen categories. A quick look at the project's .idea files usually clears up any doubt about which setting actually applies.

7. Multiple machines: office, home office, and remote development

For developers switching between an office desktop and a laptop, Settings Sync cuts setup time down to a few minutes: logging in with the JetBrains account is enough, and plugins, keymap, and color scheme are available in identical form shortly after.

Even with JetBrains Remote Development, where the actual code lives on a remote Docker host or server, Settings Sync applies to the thin client interface, while project-specific settings are still loaded from the remote project's own .idea folder.

For freelancers working on several client projects at once, Settings Sync additionally reduces the risk of personal settings accidentally mixing between projects, since the personal configuration stays independent of whichever project repository happens to be open.

8. What must never be distributed through Settings Sync

Run configurations can contain environment variables where tokens or passwords end up carelessly. Such configurations are usually versioned in the project's .idea folder, not distributed via Settings Sync, but a deliberate review before checking in a run configuration is still worthwhile.

As a general rule, secrets belong neither in Settings Sync nor in the versioned .idea folder, but in environment variables fed in through local .env files or the private HTTP client environment file. Placeholder syntax makes run configurations safely shareable without exposing real values.

<!-- .idea/runConfigurations/Magento_CLI.xml, safe to version -->
<component name="ProjectRunConfigurationManager">
  <configuration name="Magento CLI" type="PHPUnitRunConfigurationType">
    <envs>
      <!-- Placeholder instead of a real token, value comes from the local shell -->
      <env name="MAGENTO_ADMIN_TOKEN" value="$MAGENTO_ADMIN_TOKEN" />
    </envs>
  </configuration>
</component>

9. A practical setup for a PHP and Magento team

A proven setup looks like this: every developer enables Settings Sync for personal categories such as keymap, theme, and personal live templates. The project repository, in turn, versions code style, inspection profiles, and run configurations in the .idea folder, complemented by a .gitignore for purely local files like workspace.xml.

It also helps to add a short onboarding note to the project wiki or README explaining to new developers which settings come automatically from the repository and which they need to set up themselves via Settings Sync or manually. That prevents confusion when expectation and the IDE's actual behavior diverge.

It also helps to run a short annual check on whether all team-relevant settings in the .idea folder are still current, since Magento coding standards and team conventions evolve over time and the versioned configuration can otherwise quietly go stale.

10. Summary

11. FAQ: Settings Sync: The Essentials at a Glance