Composer dependency manager

IntelliJ IDEA integrates with the Composer dependency manager, which allows you to declare packages from Packagist or a custom repository as your project's dependencies and manage them from the IDE. IntelliJ IDEA provides:

A dedicated user interface for running the common Composer commands: init, install, update, and a number of additional Composer commands. The command output is displayed in the Composer Log console.
If you wish to use the full range of Composer commands in an IntelliJ IDEA project, you can configure and run Composer as an external command-line tool.
Comprehensive coding assistance for working with composer.json.
Synchronization of the project's roots structure and PHP language level with configuration in composer.json.
IntelliJ IDEA is aware of PSR-0/PSR-4 source roots and their namespace prefixes. It sets the Source root based on the autoload section, and the Tests root based on the autoload-dev section. IntelliJ IDEA also detects the PHP language level based on the php setting in the require section.
To learn more about PSR and autoloading, refer to the Composer official website. For examples and details on synchronizing settings, refer to the PhpStorm blog post.

Install the PHP plugin

This functionality relies on the PHP plugin, which you need to install and enable.

Press Control+Alt+S to open the IDE settings and select Plugins.
Open the Marketplace tab, find the PHP plugin, and click Install (restart the IDE if prompted).

Download and install Composer

For details on installing Composer, refer to the Composer official documentation.

If you work in a local environment, Composer commands in IntelliJ IDEA are run via the configured local PHP interpreter. You can download and install Composer manually as a system-wide standalone tool, or have IntelliJ IDEA download it automatically when you create a new Composer project, initialize Composer, or invoke other Composer commands in an existing project.

Additionally, IntelliJ IDEA enables you run Composer commands via any configured remote PHP interpreter.

Set up Composer commands execution

Open the Composer dialog by either of the following:
- In the Settings dialog (Control+Alt+S), go to Languages & Frameworks | PHP | Composer.
- If you have a single composer.json file in your project, select Tools | Composer | Install from the main menu to open the Composer Settings dialog.
Choose how the Composer commands will be executed:
- To run commands via a globally installed composer executable, choose 'composer' executable and specify its location in the field.
- To run commands via the local composer.phar archive, choose composer.phar. Then, either specify the location of the existing composer.phar file in the field or select the Download composer.phar from getcomposer.org checkbox to download a new instance of the file. The composer.phar file will be saved under the project root folder specified in the Location field.
  Then, choose one of the configured local PHP interpreters from the PHP interpreter list. Refer to Configuring Local PHP Interpreters for details.
- To run commands via a remote interpreter, choose Remote interpreter.
  - From the CLI Interpreter list, select a remote interpreter to use, or click and configure a new one as described in Configuring Remote PHP Interpreters.
    In most cases, IntelliJ IDEA detects path mappings automatically. If necessary, you can click in the Path mappings field and specify them manually in the Edit Project Path Mappings that opens.
  - In the Composer executable field, provide the name of the Composer executable. You can click , and locate the executable in the Select Path On The Server dialog that opens.
  If you rely on Docker, you can use the composer Official Docker image, which is preconfigured as a remote interpreter in IntelliJ IDEA out of the box. This image is not intended for production use. If necessary, you can create and manage your own Docker images in IntelliJ IDEA as described in Docker images.

Set up a project with Composer

In IntelliJ IDEA, you can work with existing Composer projects, create new projects based on the Composer package of your choice, or initialize Composer in an existing project. IntelliJ IDEA resolves dependencies and uses the information from composer.json to automatically apply certain configuration options.

Open a Composer-managed project in IntelliJ IDEA

When you open an existing Composer-managed project, IntelliJ IDEA uses the information contained in the composer.json file to automatically apply the project's content roots and PHP language level.

Click Open on the Welcome screen or choose File | Open from the main menu, then choose the folder where your Composer project is stored.
IntelliJ IDEA opens the project and shows a notification:
Click to open the Composer dialog and configure the project settings if required:
- Path to composer.json: IntelliJ IDEA detects the composer.json file in the project root automatically. Click to specify the path to another composer.json file in the project.
- Add packages as libraries: clear the checkbox to disable adding packages under the vendor/*/* directory as write-protected External Libraries and PHP include paths.
- Synchronize IDE Settings with composer.json: clear the checkbox to turn off automatic synchronization of the project's PHP language level and Source and Test roots with the settings in composer.json.
- Check for available package updates: clear the checkbox to disable running the update --dry-run command.
  To retrieve the available package updates and provide better coding assistance in composer.json, IntelliJ IDEA runs the update --dry-run command in the background every time you open a project or modify composer.json.
- : clear the checkbox to hide the quick actions panel on top of the composer.json file in the editor.
- : clear the checkbox to turn off notifications about missing vendor directory in a project.
- : select the checkbox to install or update the dependencies specified in composer.json even if your IntelliJ IDEA project has an invalid PHP interpreter version or is missing a PHP extension or library.
Click OK to apply the specified project settings and close the dialog.
Install project dependencies from composer.json by one of the following:
- Click on the balloon notification that pops up when IntelliJ IDEA opens a project and detects that the vendor directory is missing from it.
- Open composer.json in the editor and click the Install shortcut link on top of the editor panel.
- Select Tools | Composer | Install from the main menu or Composer | Install from the context menu of the composer.json file in the Project tools window.
If your IntelliJ IDEA project has an invalid PHP interpreter version or is missing a PHP extension or library, IntelliJ IDEA will prompt you to run Composer install with the --ignore-platform-reqs option.
The third-party libraries declared as dependencies in composer.json are installed in the vendor directory inside your project.

Create a project from Composer package

When you create a new Composer project, IntelliJ IDEA creates a project based on the Composer package of your choice, resolves the dependencies and installs them under the project's vendor directory.

Choose File | New | Project or click Create New Project on the Welcome screen.
The New Project dialog opens:
In the dialog, specify the project's parameters:
1. Select the project type and location:
  - In the left-hand pane, click PHP from the list, then choose Composer Package Project in the right-hand pane, and then click Next.
  - On the second page of the wizard, specify the project name, and the folder where it will be created.
2. Choose how the Composer commands will be executed:
  - To run commands via a globally installed composer executable, choose 'composer' executable and specify its location in the field.
  - To run commands via the local composer.phar archive, choose composer.phar. Then, either specify the location of the existing composer.phar file in the field or select the Download composer.phar from getcomposer.org checkbox to download a new instance of the file. The composer.phar file will be saved under the project root folder specified in the Location field.
    Then, choose one of the configured local PHP interpreters from the PHP interpreter list. Refer to Configuring Local PHP Interpreters for details.
  Optionally, in the Command line parameters field, type the additional command line parameters.
3. In the Package area, type the name of the desired package in the Package field. To use code completion, press Control+Space. Then choose the relevant version from the Version to install list.
Click Finish. The create-project Composer command will be invoked with the selected package. As a result, the Composer project will be created, whose configuration and structure depends on the selected package. After that, the created IntelliJ IDEA project opens.

Initialize Composer in an existing project

When you initialize Composer in a project, composer.json is created. This file lists the project dependencies and other metadata and is automatically set as the project default.

From the main menu, select Tools | Composer | Init Composer.
The Composer Settings dialog opens:
Choose how the Composer commands will be executed:
- To run commands via a globally installed composer executable, choose 'composer' executable and specify its location in the field.
- To run commands via the local composer.phar archive, choose composer.phar. Then, either specify the location of the existing composer.phar file in the field or select the Download composer.phar from getcomposer.org checkbox to download a new instance of the file. The composer.phar file will be saved under the project root folder specified in the Location field.
  Then, choose one of the configured local PHP interpreters from the PHP interpreter list. Refer to Configuring Local PHP Interpreters for details.
- To run commands via a remote interpreter, choose Remote interpreter.
  - From the CLI Interpreter list, select a remote interpreter to use, or click and configure a new one as described in Configuring Remote PHP Interpreters.
    In most cases, IntelliJ IDEA detects path mappings automatically. If necessary, you can click in the Path mappings field and specify them manually in the Edit Project Path Mappings that opens.
  - In the Composer executable field, provide the name of the Composer executable. You can click , and locate the executable in the Select Path On The Server dialog that opens.
  If you rely on Docker, you can use the composer Official Docker image, which is preconfigured as a remote interpreter in IntelliJ IDEA out of the box. This image is not intended for production use. If necessary, you can create and manage your own Docker images in IntelliJ IDEA as described in Docker images.
Click OK to close the Composer Settings dialog. IntelliJ IDEA creates a composer.json stub file and opens it in the editor:
Complete the code or accept the generated values. For details on working with the composer.json file, refer to Composer.json: Project Setup.

Manage multiple composer.json files

You can have several composer.json files in one IntelliJ IDEA project, and invoke Composer actions and commands for each of them.

If a project contains subdirectories with dedicated composer.json files, IntelliJ IDEA handles Composer-managed dependencies and settings for each of such modules independently. Every subdirectory with composer.json installed in it will have its own PSR-0/PSR-4 roots settings and vendor directory with External Libraries.

To manage composer.json files in your project:

In the Settings dialog (Control+Alt+S), go to Languages & Frameworks PHP and select the Composer Files tab.
A list of composer.json files detected by the IDE opens. IntelliJ IDEA marks the composer.json file from the project root directory as the project's Main by default.

From the Composer Files tab, you can:

Appoint a project main composer.json file other than that located in the project root.
Configure multiple composer.json files per project.

Appoint a project main composer.json

For the project's main composer.json file, Composer actions are also invoked from the Tools | Composer item in the main menu.

To appoint a custom main Composer file:

In the Settings dialog (Control+Alt+S), go to Languages & Frameworks PHP and select the Composer Files tab.
Select the Main item and specify a custom path to the composer.json file.

Configure multiple composer.json files per project

In the Settings dialog (Control+Alt+S), go to Languages & Frameworks PHP and select the Composer Files tab.
Use the and icons on the toolbar to add or delete Composer configuration files per subdirectories.

Work with composer.json

The composer.json file describes the dependencies of your project and may also contain other metadata. IntelliJ IDEA provides comprehensive coding assistance for working with composer.json and lets you perform many Composer-related tasks directly from the code editor.

Create a composer.json file

You can create composer.json files manually. If Composer hasn't yet been initialized in the project, a newly created composer.json will be automatically set as the project default.

Do one of the following:
- In the Project tool window Alt+1, select the directory or package in which you want to create a new file, and then choose File | New from the main menu.
- Right-click the corresponding directory or package and select New from the context menu.
- Press Alt+Insert.
In the popup menu, select composer.json File. IntelliJ IDEA creates a stub of the composer.json file and opens it in the editor.

Use code completion in composer.json

Inside composer.json, press Control+Space to use code completion when providing both the names of the sections and their content, for example:
- License type and minimum-stability version,
- Namespaces and paths in the autoload and autoload-dev sections,
- Required PHP version and extensions as well as packages' names and versions in the require and require-dev sections.

Use quick documentation in composer.json

Inside composer.json, press Control+Q to view quick documentation for the element at caret.

Inside composer.json, position the caret at an entity such as an installed package, a class or a method within a script, a file path, or a url. Then do any of the following:
- In the main menu, select Navigate | Declaration or Usages
- Press Control+B
Alternatively, Control+LeftClick the record.
If you have a test framework or code quality tool installed as a project dependency, IntelliJ IDEA displays next to the corresponding dependency record. Click it to jump directly to the corresponding Settings page.
For details on using test frameworks, see Prepare for testing; for details on working with code quality tools, see PHP code quality tools.

Manage dependencies

To install, update, or uninstall project dependencies, you need to update the records in the require or require-dev sections in composer.json and then run the corresponding Composer command.

To retrieve the available package updates and provide better coding assistance in composer.json, IntelliJ IDEA runs the update --dry-run command in the background every time you open a project or modify composer.json. If necessary, you can disable running the command. In the Settings dialog (Control+Alt+S), go to Languages & Frameworks | PHP | Composer and clear the Check for available package updates checkbox.

When you open a project or modify composer.json, IntelliJ IDEA checks whether the vendor directory is present. If it is missing, IntelliJ IDEA displays the notification message.

Click the Run 'composer install' shortcut link in the notification message to quickly install the project dependencies. If necessary, you can disable this notifcation by clearing the Notify about missing vendor directory checkbox on the PHP | Composer page of the Settings dialog (Control+Alt+S).

Install dependencies

Inside composer.json, add the desired dependency record to the require or require-dev section. Press Control+Space to get code completion both for the package name and version.
When specifying the package version, you can provide version constrains, too, for example >=1.0 <2.0. See the Composer official documentation for details.
Do one of the following:
- Click the Install shortcut link on top of the editor panel.
- If the Non-installed Composer packages inspection is enabled, IntelliJ IDEA will highlight the declared dependencies that are not currently installed. Press Alt+Enter and select whether you want to install a specific dependency or all dependencies at once.

When a new package is installed, IntelliJ IDEA creates a new subfolder under vendor and stores the package inside. If the composer.lock file is present in the current directory, the exact packages versions listed in it are installed. Otherwise, if the composer.lock file is missing, Composer will create it after installing the packages, thus locking your project to their specific versions.

Update dependencies

You can update packages to their latest versions individually, or update all the packages listed in the require and require-dev sections of composer.json at once.

When a new package version is available or the package versions requirements change, IntelliJ IDEA indicates this via the icon in the editor gutter. It also provides the hint on the currently installed version and the version the package can be updated to.
Click to update the package.
To update all packages, click the Update shortcut link on top of the composer.json editor panel.

Install/update dependencies with options

When installing or updating dependencies, IntelliJ IDEA can run the respective Composer commands with the --ignore-platform-reqs option.

The --ignore-platform-reqs option enables installation or update of dependencies even if your IntelliJ IDEA project has an invalid PHP interpreter version or is missing a PHP extension or library.

To run the install/update commands with an option, configure Composer in IntelliJ IDEA settings:

In the Settings dialog (Control+Alt+S), go to PHP | Composer and select the checkbox.

Uninstall dependencies

Remove the package record from the require or require-dev section of composer.json.
Click the Update shortcut link on top of the composer.json editor panel.

Use a custom package repository

Besides Packagist, you can use a custom package repository.

Inside composer.json, create a repositories section for your repository:
{ "name": "vendor_name/package_name", "repositories": [ { "type": "composer", "url": "https://packages.example.com" } ] }
After IntelliJ IDEA retrieves the packages information, you can install, update, and uninstall packages as usual.

Create and run Composer scripts

With Composer, you can create and run scripts, which are used for executing some custom code or package-specific commands during the Composer execution process.

Define a Composer script

Inside the scripts section of composer.json, create an event property, and list the desired scripts inside it. Each script can be a PHP callback defined as a static method, a command-line executable command, or a reference to an existing script.
Use code completion Control+Space to get suggestions for event names, classes' and static methods' names, and binaries installed under vendor/bin. To add a reference to an existing script, prepend it with the @ symbol.

Rename a Composer script

Position the caret at a script's definition or usage.
Invoke the Rename refactoring by selecting Refactor | Rename from the main menu or from the context menu, or press Shift+F6.
In the Rename dialog that opens, provide the desired name for a script.
Click Preview to observe possible changes in the Find tool window. Click Refactor to proceed.

Run a composer script

Click in the gutter next to the script you want to execute. From the list, select Run <script name>.
Right-click inside the script you want to run and select Run <script name> from the context menu.
Position the caret at the script you want to execute, press Alt+Enter and select the Run <script name> intention action.

When the script is executed, IntelliJ IDEA automatically creates a dedicated temporary Composer Script run/debug configuration for it. You can save it as a permanent run/debug configuration if necessary.

Create a Composer script run/debug configuration

You can execute Composer scripts by using run configurations of the Composer Script type. With the run configuration, you can execute a script at any point, add it to the Services tool window, or a compound configuration. Refer to Working with Run/Debug Configurations for details.

Do any of the following:
- In the editor, right-click inside the desired script record and select More Run/Debug | Modify Run Configuration from the context menu.
- Alternatively, choose Run | Edit Configurations from the main menu, then click and choose Composer Script from the list.
Provide the run/debug configuration parameters:
- Path to composer.json: in this field, provide the path to composer.json that contains the desired script's definition.
- Script: from this list, select one of the defined Composer scripts to execute.
- Command line parameters: in this field, type the additional command line parameters. These parameters will be passed as CLI arguments to the CLI handlers; inside PHP handlers, they can be retrieved as an array via $event->getArguments() calls.

Save a temporary Composer Script run/debug configuration

When you execute a Composer script from the editor, IntelliJ IDEA automatically creates a temporary run/debug configuration with the script parameters. A temporary run/debug configuration works the same way as a permanent run/debug configuration. You can change its settings using the Run/Debug Configuration dialog and optionally save it as permanent.

In the Run/Debug Configuration selector, choose Save <configuration name>.
In the Run/Debug Configuration dialog, select the configuration and click .

Execute a Composer script using a run/debug configuration

In the Run/Debug Configuration selector, select the desired run configuration. Then click on the main toolbar or press Shift+F10.
Press Alt+Shift+F10, select the desired run configuration from the list, and press Enter.

View the Composer log

When you execute a Composer-related command via the IntelliJ IDEA interface, the command's output is displayed in the dedicated Composer Log console:

Open Composer log

Having executed any Composer command for the first time, click the Show in log shortcut link in the Notifications tool window notification message:
Open composer.json in the editor and click the Show Log shortcut link on top of the editor panel.

View the folded Composer Log message

If a Composer command has been executed successfully, Composer Log will fold its execution details.

Click in the gutter to unfold the message.
Hover the mouse over the ellipsis to view the message in a tooltip:

When appointing a default composer.json in a project, you can enable IntelliJ IDEA's settings synchronization with composer.json. Composer Log will highlight such a change in the settings as it occurs. Click in the gutter it to quickly navigate to the corresponding Directories, PHP reference, Test Frameworks, or PHP command line tools settings pages.

Run additional Composer commands

IntelliJ IDEA provides the user interface for a set of additional Composer commands.

From the composer.json context menu, select Composer | <command name>.
Open composer.json in the editor, click on top of the composer.json editor panel, and choose the desired command from the list.
To run a command for the default composer.json, select Tools | Composer | <command name> from the main menu.

If Composer execution is not set up, the Composer Settings dialog will open, prompting you to choose how the Composer commands will be executed:

To run commands via a globally installed composer executable, choose 'composer' executable and specify its location in the field.
To run commands via the local composer.phar archive, choose composer.phar. Then, either specify the location of the existing composer.phar file in the field or select the Download composer.phar from getcomposer.org checkbox to download a new instance of the file. The composer.phar file will be saved under the project root folder specified in the Location field.
Then, choose one of the configured local PHP interpreters from the PHP interpreter list. Refer to Configuring Local PHP Interpreters for details.
To run commands via a remote interpreter, choose Remote interpreter.
- From the CLI Interpreter list, select a remote interpreter to use, or click and configure a new one as described in Configuring Remote PHP Interpreters.
  In most cases, IntelliJ IDEA detects path mappings automatically. If necessary, you can click in the Path mappings field and specify them manually in the Edit Project Path Mappings that opens.
- In the Composer executable field, provide the name of the Composer executable. You can click , and locate the executable in the Select Path On The Server dialog that opens.
If you rely on Docker, you can use the composer Official Docker image, which is preconfigured as a remote interpreter in IntelliJ IDEA out of the box. This image is not intended for production use. If necessary, you can create and manage your own Docker images in IntelliJ IDEA as described in Docker images.

Validate

Run this command to perform several validity checks against the composer.json file, which is recommended before committing composer.json to a VCS. Validation results are displayed in the Composer Log console.

The equivalent Composer CLI command is validate.

Before executing the command, choose the desired options in the Validation Settings dialog:

Allow unbound version constrains: If selected, version constraints without an upper bound (for example *, >3.1) will be permitted. Note that this will allow updates to any future version of a dependency, which may cause backward compatibility issues in the case of unexpected changes in dependencies.
The equivalent option of the Composer CLI command is --no-check-all.
Check if composer.lock is up-to-date: If selected, the version constraints listed in composer.lock will be checked against the ones listed in composer.json. If the version constraints do not match, it is recommended to fix this by updating packages. After the packages are updated to the required versions, the composer.lock and the composer.json files will be synchronized.
The equivalent option of the Composer CLI command is --no-check-lock.
Check if the package is Packagist-ready: If selected, the package's composer.json will be checked against the Packagist publishing requirements. Generally, for a package to be Packagist-ready, the name, description, and require sections in its composer.json file must be specified. Refer to the Packagist documentation for details on publishing packages.
The equivalent option of the Composer CLI command is --no-check-publish.
Validate package dependencies: If selected, the composer.json files of all installed dependencies of the current package will also be validated.
The equivalent option of the Composer CLI command is --with-dependencies.

Dump Autoloader

Run this command to generate the list of autoloaded classes. If the list already exists, it will be generated anew. This can be useful in situations when you introduce a new class in a project and need to include it to the list of autoloaded classes. Refer to the Composer documentation for more details on autoloading classes with Composer.

The equivalent Composer CLI command is dump-autoload.

Before executing the command, choose the desired options in the Autoloader Generation Settings dialog:

Skip scripts execution: If selected, the scripts defined in the scripts section of the composer.json file are not executed.
The equivalent option of the Composer CLI command is --no-scripts.
Optimize autoloader (Convert PSR-0/4 rules to a classmap): If selected, Composer will scan the given PSR-0/4 autoloading directories/files for the php and inc files and generate a single autoload_classmap key-value array to speed up autoloading. Note that if the number of classes is large, running this command can be time-consuming.
The equivalent option of the Composer CLI command is --optimize.
Autoload classes from the classmap only: If selected, only the classes listed in the class map will be autoloaded. Composer will not search for fallback PSR-4 directories for classes not listed in the class map. Since this naturally requires an existing class map, Composer will also execute the Optimize autoloader (Convert PSR-0/4 rules to a classmap) command to generate one, which can be a time-consuming process.
The equivalent option of the Composer CLI command is --classmap-authoritative.
Use APCu for caching found/not-found classes: If selected, caching via APCu will be enabled. When a class is found (or not found) in the class map, the corresponding record will be cached in APCu, so that it can be quickly retrieved on the next request.
The equivalent option of the Composer CLI command is --apcu.
Disable autoload-dev dependencies: If selected, the autoloaded namespaces and files listed in the autoload-dev section are not included into the autoloaded classes list.
The equivalent option of the Composer CLI command is --no-dev.

Check for Changes in Dependencies

Run this command to check if you have any local changes in the code of the package dependencies.

The equivalent Composer CLI command is status.

Clear Cache

Run this command to delete the Composer's cache directory, which contains the downloaded packages. By default, the cache directory is set to C:\Users\<user>\AppData\Local\Composer on Windows, and to ~/.composer/cache on Linux and macOS. Refer to the Composer documentation for details.

The equivalent Composer CLI command is clear-cache.

List Licenses

Run this command to view the name, version, and license type of every installed package.

The equivalent Composer CLI command is licenses.

Diagnose

Run this command to perform automated checks for the most common Composer problems (for example connectivity issues, Composer/PHP version used, disk space available, composer.json validity). If the problem is not identified, refer to the Composer troubleshooting guide.

The equivalent Composer CLI command is diagnose.

Simulate Update

Run this command to simulate updating the dependencies without actually running composer update. In doing so, you can verify whether all dependencies are resolved successfully and preview the changes while keeping everything intact.

The equivalent Composer CLI command is update --dry-run.

Self-Update

Run this command to update Composer itself (that is, the composer.phar file) to the latest version.

The equivalent Composer CLI command is self-update.

Run Composer from the command line

Command-line mode provides you with the full range of Composer commands. To use Composer in this mode, you need to configure it as an external command-line tool.

You can have several instances of Composer configured and switch between them from one project to another by specifying the relevant one during Composer initialization.

Configure Composer as a command line tool

In the Settings dialog (Control+Alt+S), go to Tools | Command Line Tool Support.
Click on the toolbar.
In the Command Line Tools dialog, choose Composer from the list, and specify its visibility level (Project or Global).
When you click OK, the dialog opens.
Specify how you want to launch Composer by choose one of the options: composer.phar or php script or composer executable. Depending on your choice, specify the paths to the PHP installation folder and composer.phar or to the composer executable file.
IntelliJ IDEA parses the contents of the specified .phar archive or executable file for Composer commands. When the file analysis is completed, IntelliJ IDEA returns to the Command Line Tools Support page where the specified file is added to the list of command line tools available in IntelliJ IDEA.
Click OK to apply changes and return to the Command Line Tool Support page. Optionally, click to edit the tool properties, or to customize the commands set. See Customize a tool for details.

Run a Composer command

From the main menu, choose Tools | Run Command or press Control twice.
In the Run Anything window that opens, type the call of the command in the <c> <command> format.
The command execution result is displayed in the Run tool window.

Terminate a command

Click on the Run tool window toolbar.

Last modified: 21 June 2023