Cover Image for PHPStorm+Magento: Configure URN mappings for separate content root

PHPStorm+Magento: Configure URN mappings for separate content root

Sometimes when working on a project that has multiple applications you will wind up with a folder structure that looks like this:

Content Root Folder Example

In this case I have a root that contains my docker-compose.yaml for starting the environment and then the various source roots included.

In PHPStorm you can add multiple Content Root folders in: Settings > Directories.

There is a command within the magento CLI which will generate the mapping that PHPStorm needs to resolve the actual location of the XSD validation schemas. Magento uses the XSDs to validate all of the XML files that are used in the project. If PHPStorm knows how to find the XSDs then it can give you autocomplete and validation hints for the XML which is very useful when developing modules.


When creating a di.xml in a custom module you'll add an attribute xsi:noNamespaceSchemaLocation

<?xml version="1.0"?>
<config xmlns:xsi="" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">

Without the mapping the value will be red signifiying that PHPStorm can't find the actual file.

PHPStorm warning, file not found


The magento CLI tool has a command to automatically generate the mapping that PHPStorm needs in order to resolve the XSDs.

Running dev:urn-catalog:generate misc.xml will generate an XML file which can be copied into /.idea and then PHPStorm will resolve the XSDs.

The only issue with this process is that the default misc.xml file will have entries like the following

<resource url="urn:magento:framework:Module/etc/module.xsd" location="$PROJECT_DIR$/vendor/magento/framework/Module/etc/module.xsd"/>

Notice the $PROJECT_DIR$ variable. This is an internal pointer to

It always points to the directory with .ipr file or .idea sub-directory (with project settings).

That usually works except when your Magento source is in a Content Root that has been added and sits outside the PHPStorm root folder.

In order to fix this I like to create a new Path Variable which maps to my Magento source folder and then replace $PROJECT_DIR$ in the XML with my customer Path Variable.


Create a Path Variable to the resource

Example of creating path variable


<resource url="urn:magento:framework:Module/etc/module.xsd" location="$WSL_SOURCE$/vendor/magento/framework/Module/etc/module.xsd" />

PHPStorm can now resolve the XSD and give autocomplete and validation for the XML files. The path is green and PHPStorm can navigate to the file.

Autocomplete linking XSD to source

PHPStorm will autocomplete and validate for you.

Autocomplete of XML using XSD