The Step-By-Step Guide for Setting up PhpStorm for Magento 2 Development

PhpStorm is still the best IDE for Magento 2. But how we actually use it in 2026 looks nothing like the old advice - these days it's more a review tool than a place we write code, because most of the code is written by Claude.

That changes what the setup is for. It's no longer about typing faster; it's the guardrail stack around AI-written code - coding standards, static analysis, and debugging for when something slips through. This guide is the setup we run building Magento extensions, and where PhpStorm still earns its place.

In a hurry? Jump to how we actually build Magento extensions now.

• Use static code analysis
• Install the Magento 2 coding standard
• Configure Code Sniffer (phpcs) in PhpStorm
• Use PHP Mess Detector (phpmd)
• Add PHPStan for deeper static analysis
• Validate XML against XSD schemas
• Exclude directories to speed up indexing
• Set up Xdebug for Magento 2 debugging
• How we actually build Magento extensions now
• What PhpStorm gives you today
• Essential plugins for Magento 2
• Tips to work faster in PhpStorm
• Alternatives to PhpStorm
• Final thoughts

Use static code analysis

Here's why this matters more than it used to: when a machine writes the first draft, static analysis stops being style police and becomes your first line of defense. It's what catches the plausible-looking code the AI got subtly wrong. Set it up once and every change - yours or the model's - gets checked the same way.

Magento 2 ships a ready-made set of rules and standards for Code Sniffer (phpcs) and PHP Mess Detector (phpmd).

Use these tools to validate code against Magento 2 coding standards without even running it. You get:

• high validation speed
• code validation on the fly.

Learn more in the official Magento coding standards documentation.

Install the Magento 2 coding standard

Before PhpStorm can lint against Magento's rules, install the standard itself. From your Magento root:

composer require --dev magento/magento-coding-standard

Register it with phpcs so the Magento2 standard becomes available:

vendor/bin/phpcs --config-set installed_paths ../../magento/magento-coding-standard/

Now you can run it from the command line against any module:

vendor/bin/phpcs --standard=Magento2 app/code/YourVendor/YourModule

And auto-fix everything that can be fixed automatically:

vendor/bin/phpcbf --standard=Magento2 app/code/YourVendor/YourModule

The ruleset that drives all of this lives in vendor/magento/magento-coding-standard/Magento2/ruleset.xml - that's the file you point PhpStorm at in the next step.

Configure Code Sniffer (phpcs) in PhpStorm

Code Sniffer validates code against standards for formatting, comment placement, and accuracy.

To wire the ruleset into PhpStorm, follow these 6 steps:

1. Go to PhpStorm -> Preferences.
2. In the left menu, open Editor -> Inspections.
3. Find PHP -> Quality tools -> PHP Code Sniffer validation.
4. Turn validation on.
5. Set the Coding standard to Custom and click "...".
6. Choose the directory vendor/magento/magento-coding-standard/Magento2/.

To check it's working, configure everything and you should see phpcs highlighting issues inline:

P.S.: If you haven't configured PhpStorm before, you need to specify the path to the phpcs executable. Do this in PhpStorm -> Preferences -> Languages & Frameworks -> PHP -> Code Sniffer, where you set the path to the file in the Development Environment section.

You can also let PhpStorm format code automatically. It saves a lot of time when you have many files that were formatted incorrectly.

Use PHP Mess Detector (phpmd)

PHPMD also runs static code analysis, but it targets likely errors and overly complex code fragments (classes, methods) that are hard to interpret.

In our experience, if your code passes all tests and validations - particularly the CyclomaticComplexity, NPathComplexity, and CouplingBetweenObjects rules - then it's easy to read and test, and it holds fewer potential errors.

Configuring PHP Mess Detector in PhpStorm is similar to setting up Code Sniffer, except for the ruleset file: dev/tests/static/testsuite/Magento/Test/Php/_files/phpmd/ruleset.xml

If you've done everything correctly, you'll get the result from the screenshot below:

Add PHPStan for deeper static analysis

phpcs and phpmd cover style and complexity, but for type-level bugs Magento also ships a PHPStan integration with its own rule levels. Adobe's static analysis guide covers running it, and PhpStorm surfaces PHPStan results inline just like phpcs. It's worth adding once the basics are in place.

Validate XML against XSD schemas

Unlike Magento 1, every XML file in Magento 2 (layouts, etc/*) must comply with an XSD schema. If an error occurs while you edit an XML file, PhpStorm flags it:

Checking XML files for errors is a good habit.

To use this feature, run the following command in the SSH terminal: bin/magento dev:urn-catalog:generate .idea/misc.xml

Most IDEs don't support Uniform Resource Names (URNs) by default. If you need to reference an XSD schema (which Magento references as URNs) and see it highlighted, you need to use the following command:

bin/magento dev:urn-catalog:generate

Exclude directories to speed up indexing

During development, PhpStorm regularly indexes all project files and their changes. This is important for building relations between classes and for autocompletion.

Still, every project has plenty of files that don't need indexing, and excluding them boosts PhpStorm's everyday performance.

We recommend excluding the following directories:

• /bin/
• /dev/
• /pub/
• /setup/
• /var/cache/
• /var/log/
• /var/page_cache
• /var/view_processed

Follow these steps to exclude the suggested directories:

That's the core configuration done. Below are the newer pieces - debugging, plugins, and how we run this day to day.

Set up Xdebug for Magento 2 debugging

Static analysis catches a lot, but sooner or later you need to step through code. Xdebug plus PhpStorm is the standard debugger for Magento 2.

1. Install the Xdebug PHP extension (pecl install xdebug, or the package from your distro or Docker image) and enable it in php.ini with xdebug.mode=debug and the xdebug.client_host / xdebug.client_port settings (port 9003 for Xdebug 3).
2. In PhpStorm, open Preferences -> PHP -> Debug and confirm the debug port matches (9003 for Xdebug 3, not the old 9000).
3. Add a PHP interpreter under Preferences -> PHP. Most Magento 2 projects run in Docker or on a remote box, so add a Docker or remote interpreter and map the project path to the container path - PhpStorm needs correct path mappings to hit breakpoints.
4. Click "Start Listening for PHP Debug Connections", set a breakpoint, then reload the page (or run a CLI command) with an Xdebug session enabled.

Breakpoints getting ignored? It's almost always a path-mapping mismatch between your local files and the container. Fix the mapping in Preferences -> PHP -> Servers.

One honest caveat: we reach for Xdebug far less than we used to. When we need to know why a piece of code behaves the way it does, it's often faster to have Claude write a small throwaway PHP script that exercises it and run that directly - no breakpoints, no session, no path mapping. Xdebug still earns its place for gnarly runtime state deep inside a request. But it's no longer the first thing we reach for.

How we actually build Magento extensions now

That's the setup. Here's how we actually use it - including the parts that go against the usual advice.

Claude writes the code; we own everything around it. Claude is the core of how we build now, so the code mostly isn't written by hand. What stays firmly with the engineer is the review, the architecture, the decisions, keeping things compatible, and getting the implementation right with enough headroom for what comes next. The AI writes - the engineer is still responsible for whether it should ship.

PhpStorm is a review tool now, not a writing tool. This is the biggest shift, and it's worth being honest about it. Today PhpStorm is where we check what Claude produced, read through pull requests, and go over the diff before a commit - not where the code gets typed.

Antipatterns as instructions for Claude. On top of the standard rules, we keep our own set of antipatterns written as instructions for Claude. After a change, we run a Claude command that checks the new or modified code against them. That format works surprisingly well - it catches the project-specific mistakes a generic linter never would.

Coding standards live in CI, not the IDE. phpcs and phpmd against the Magento2 standard run on our CI servers alongside 5+ other tools and roughly 100 checks. The IDE catch is just a convenience; CI is what actually gates the code before it merges.

Fewer plugins, on purpose. PhpStorm has a long history of performance problems on large projects, so we treat every plugin as a cost. The fewer we run, the smoother the IDE stays. The official Magento plugin is the one we still consider worth its weight; most of the rest we skip. Same logic for indexing: the less PhpStorm has to index, the faster it is, so anything that can be excluded goes into the ignore list - the directories above are only a starting point, we ignore more than that.

What PhpStorm gives you today

PhpStorm changes fast, so here's where it stands in 2026 rather than a frozen feature list.

Three things have always been true, and still are:

• Cross-platform. The IDE runs identically on macOS, Windows, and Linux, so switching machines costs you nothing.
• Real-time inspections. It flags likely errors as you type and checks how variables and functions are used against the platform's standards.
• Code-quality hints. It tells you when code is clumsy or likely to cause problems, not only when it's syntactically wrong.

What has changed since this guide first went out, most relevant first:

• AI is built in and free to start. The JetBrains AI Assistant is generally available: core features like code completion and local-model support are free, with paid AI Pro and AI Ultimate tiers on top. The IDE now also ships coding agents (Junie and Claude Agent) that generate code, explain it, and run multi-step tasks - the same shift this whole guide is built around.
• The New UI is the default. Since PhpStorm 2024.2 the redesigned interface - with a proper dark theme, compact mode, and project tabs - ships on by default; the classic UI is now a plugin.
• Current versions. The 2025.3 release added PHP 8.5 support and bundled Laravel tooling, and 2026.1 is the current line. If you're on an older build, it's worth updating.

Essential plugins for Magento 2

The right plugins turn a generic PHP IDE into a Magento-aware one. Get them from the JetBrains marketplace.

Magento PhpStorm (official). If you install one plugin, install this one. The official magento2-phpstorm-plugin adds smart completion and references for Magento's XML and JavaScript (dependency injection, plugins, Web API), code generation for modules, observers, plugins, controllers, CLI commands, and blocks, GraphQL line markers, and MFTF support. Recent versions also expose Magento-specific MCP tools for AI agents and work with PhpStorm 2026+.

Php Inspections (EA Extended). A static analysis add-on that catches PHP-level issues the built-in inspections miss - risky constructs, performance smells, and code that's technically valid but fragile. A useful second pass on top of phpcs and phpmd.

The Rainbow Brackets add-on improves code readability by adding color to it. It can paint brackets, variables, tags, and other elements, with a customizable default palette.

CSV Editor and .env files support let PhpStorm work with those files. CSV Editor also adds color-coded tables, syntax checks, and customization.

Key Promoter X helps you learn keyboard shortcuts by showing them when you do something with the mouse - for example, that you could've pressed "Alt+1" instead of clicking the "Projects" tab.

The IdeaVim plugin adds the Vim engine and its features: work modes, registers, motion keys, Ex commands, and even Vim plugins.

Tips to work faster in PhpStorm

The IDE does a lot, but a few habits make you noticeably faster:

• Learn the shortcuts. You repeat the same actions - switching tabs, creating files, searching - dozens of times a day. Doing them by keyboard adds up fast, and Key Promoter X (above) helps you learn them.
• Lean on search and navigation. Search Everywhere (double Shift), Go to Declaration, and the quick-documentation pop-up save more time than almost any single feature. Live templates stop you re-typing boilerplate.
• Customize with plugins. Add support for the languages you touch, tweak the UI, and automate repetitive edits. This is where the plugins above earn their place.
• Document as you go. Use the automatic PHPDoc generation. Even working solo, you'll thank yourself later - undocumented code gets confusing no matter how clean it is.

Alternatives to PhpStorm

PhpStorm isn't the only option, but the only alternative we'd seriously suggest is Visual Studio Code. It's free, fast, and lightweight, and with extensions like Intelephense (or the official PHP extension), PHP Debug, and Magento-specific helpers it does real Magento work. You give up PhpStorm's deep, out-of-the-box Magento awareness - you assemble that from extensions instead. For a lot of developers the speed and the free price just win.

Final thoughts

Set this up once and PhpStorm stops being a text editor and starts being a Magento-aware environment. But be honest about where this is going: we review far more code than we write now, and that's not reversing. Get the guardrails right - coding standards in CI, Xdebug that actually stops on a breakpoint, antipatterns the AI can check itself against - and let the machine do the typing. Your job is deciding whether what it wrote should ship.