PhpStorm 2018.2 Help

Composer Dependency Manager

PhpStorm integrates with the Composer dependency manager, which allows you to declare packages from Packagist as your project's dependencies and manage them from the IDE.

PhpStorm provides a dedicated user interface for the common Composer commands:

When you run the above commands, PhpStorm displays their output via the Composer Log console.

If you wish to use the full range of Composer commands in a PhpStorm project, you can configure and run Composer as an external command-line tool.

Downloading and installing Composer

You can download and install Composer manually as a system-wide standalone tool. To do so, refer to the Composer official documentation.

Alternatively, PhpStorm will prompt you to download Composer automatically when you create a new Composer project, initialize Composer, or invoke other Composer commands in an existing project. In this case, Composer is run via the configured local PHP interpreter.

Creating a new Composer project

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

To create a new Composer project

  1. Choose File | New Project or click Create New Project on the PhpStorm Welcome screen.

    The New Project dialog opens:

    ps new composer project
  2. In the dialog, specify the project's parameters:
    • Choose the project type and location:
      • In the left-hand pane, select Composer Project.

      • In the Location field on the right-hand pane, specify the folder where the project will be created.

    • 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 locally installed 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 downloaded 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.
    • In the Package area, select the package from the list, and choose the relevant version from the Version to install list. To search for a package, use the Filter packages search field.

  3. Click Create. 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 PhpStorm project opens.

Initializing Composer in an existing project

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

To initialize Composer in an existing project

  1. On the main menu, choose Tools | Composer | Init Composer.

    The Composer Settings dialog opens:

    ps composer settings dialog
  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 locally installed 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 downloaded 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.

Opening an existing Composer project in PhpStorm

When you open an existing Composer project, PhpStorm uses the information contained in the composer.json file to automatically apply the certain configuration options, e.g. the project's content roots and PHP language level.

  1. Click Open on the Welcome screen or choose File | Open on the main menu, then choose the folder where your Composer project is stored.

    PhpStorm will show a notification:

    ps_composer_notification_composer_json_detected.png
  2. Click Initialize Composer settings. In the Composer dialog that opens, specify the location of the composer.json file. If PhpStorm detects an existing file, the Path to composer.json field will be filled automatically:

    ps_composer_path_detected.png

  3. Configure the project settings:

    • By default, all packages under the vendor/*/* directory are excluded from the project and added as write-protected libraries. To protect them from editing, leave the Add packages as libraries checkbox selected. Otherwise, if you want to edit Composer packages under vendor/*/*, clear the Add packages as libraries checkbox.

    • Make sure the Synchronize IDE settings with composer.json checkbox is selected to automatically detect the PHP language level and configure project Source and Test roots based on the configuration from composer.json.

      PhpStorm is aware of PSR-0/PSR-4 source roots and of their namespace prefixes declared in the autoload and autoload-dev sections in composer.json. PhpStorm also detects the PHP language level based on the php setting in the require section.

      Because composer.json contains the most up-to-date information about the project configuration, this automatic synchronization ensures that the Source and Test folder exactly match the project structure and the correct PHP language level is set automatically.

      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.

    Click OK to apply the specified project settings and close the dialog.

  4. Set up Composer commands execution:
    • Do one of the following:
      • Open the Settings/Preferences dialog (Ctrl+Alt+S) and navigate to Languages and Frameworks | PHP | Composer.

      • If you have a single composer.json file in your project, choose Tools | Composer | Install on 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 locally installed 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 downloaded 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.

  5. Install the project dependencies:

    • If you have a single composer.json file in your project, choose Tools | Composer | Install on the main menu.

    • Otherwise, if you have several composer.json files, choose Composer | Install from the context menu of the relevant one. See also Appointing a default composer.json in a PhpStorm project.

    You can also open the composer.json file in the code editor and click the Install shortcut link on top of the editor panel.

Appointing a default composer.json in a PhpStorm project

You can have several composer.json files in one PhpStorm project. For each composer.json, actions are invoked from its context menu in the editor or in the Project view, or using the shortcut links on top of the editor panel. You can also appoint the default composer.json for your PhpStorm project. Composer actions for it are invoked from Tools | Composer on the main menu.

To appoint a default composer.json

  1. Open the Settings/Preferences dialog (Ctrl+Alt+S) and navigate to Languages and Frameworks | PHP | Composer.

  2. Specify the location of the default composer.json. If you have a single Composer configuration file in your PhpStorm project, the Path to composer.json field is filled automatically.

  3. By default, all packages under the vendor/*/* directory are excluded from the project and added as write-protected libraries. To protect them from editing, leave the Add packages as libraries checkbox selected.

    Otherwise, if you want to edit Composer packages under vendor/*/*, clear the Add packages as libraries checkbox.
  4. Make sure the Synchronize IDE settings with composer.json checkbox is selected to automatically detect the PHP language level and configure project Source and Test roots based on the configuration from composer.json.

    PhpStorm is aware of PSR-0/PSR-4 source roots and of their namespace prefixes declared in the autoload and autoload-dev sections in composer.json. PhpStorm also detects the PHP language level based on the php setting in the require section.

    Because composer.json contains the most up-to-date information about the project configuration, this automatic synchronization ensures that the Source and Test folder exactly match the project structure and the correct PHP language level is set automatically.

    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.

Installing dependencies

You can install specific packages individually, and PhpStorm will update your composer.json automatically. Alternatively, you can list the packages you need in the require and require-dev sections of the composer.json and then install them all at once.

If the composer.lock file is present in the current directory, the exact packages versions listed in it will be 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.

Learn more about adding dependencies on the Composer Official website.

To install a specific package

  1. Do one of the following:
    • On the context menu of composer.json, choose Composer | Manage Dependencies.

    • To install a package from the default composer.json, choose Tools | Composer | Manage Dependencies on the main menu.

  2. In the Manage Composer Dependencies dialog that opens, select the required package from the Available Packages list. To find a package, use the search field. The list shows all the available packages; the packages that are already installed are marked with a checkmark.

    Choose the relevant version from the Version to install list.

  3. Optionally, customize the package installation. In the Command line parameters text box, type the additional command line parameters.

  4. Click Install to start installation. To exit the dialog, click Close.

When the package is installed, PhpStorm creates a new subfolder under vendor and stores the new package in this subfolder. The corresponding package records are added to the require or the require-dev section of the composer.json file as well as to the composer.lock file.

To install all packages at once

  • Do any of the following:

    • On the context menu of composer.json, choose Composer | Install.

    • Open composer.json in the editor the and click the Install shortcut link on top of the editor panel.

    • To install all packages listed in the default composer.json, choose Tools | Composer | Install on the main menu.

PhpStorm installs all the packages listed in the require and require-dev sections of the composer.json file.

Updating dependencies

You can update specific packages to their latest versions individually, and PhpStorm will update your composer.json automatically. Alternatively, you can update all the packages listed in the require and require-dev sections of the composer.json file at once.

To update a specific package

  1. Do one of the following:
    • On the context menu of composer.json, choose Composer | Manage Dependencies.

    • To update a package from the default composer.json, choose Tools | Composer | Manage Dependencies on the main menu.

  2. Select the required package from the Available Packages list among the packages marked with a tick and click Update.

To updating all packages at once

  • Do any of the following:

    • On the context menu of composer.json, choose Composer | Update.

    • Open composer.json in the editor the and click the Update shortcut link on top of the editor panel.

    • To update all packages listed in the default composer.json, choose Tools | Composer | Install on the main menu.

PhpStorm updates all the packages listed in the require and require-dev sections of the composer.json file.

Uninstalling dependencies

To uninstall a package

  1. Do any of the following:

    • On the context menu of composer.json, choose Composer | Manage Dependencies.

    • To uninstall a package listed in the default composer.json, choose Tools | Composer | Manage Dependencies on the main menu.

  2. In the Available Packages list, select the package to uninstall among the packages marked with a tick and click Remove.

When the package is uninstalled, PhpStorm updates the require or the require-dev section of composer.json automatically.

Viewing the Composer Log

ps composer log panel

To open Composer Log

  • Do any of the following:

    • Having executed any Composer command for the first time, click the Show in log shortcut link in the Event Log notification message:

      ps composer event log message
    • Open composer.json in the editor and click the Show Log shortcut link on top of the editor panel.

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

To view the folded Composer Log message

  • Do any of the following:

    • Click the plus icon in the left gutter to unfold the message.

    • Hover the mouse over the ellipsis to view the message in a tooltip:

      ps composer folded message hover

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

Running Additional Composer Commands

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

To run an additional Composer command

  1. Do any of the following:

    • On the context menu of composer.json, choose Composer | <command name>.

    • Open composer.json in the editor, click cogwheel black with arrow 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, choose Tools | Composer | <command name> on the main menu.

If Composer execution is not set up, the Composer Settings dialog box 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 locally installed 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 downloaded 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.

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 (e.g. *, >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 autoloader 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 autoloader 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 license.

Diagnose

Run this command to perform automated checks for the most common Composer problems (e.g. 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.

Self-Update

Run this command to update Composer itself (i.e. the composer.phar file) to the latest version.

The equivalent Composer CLI command is self-update.

Running 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. For details on working with command-line tools, refer to PHP Command Line Tools.

To integrate Composer with PhpStorm as an external command-line tool

  1. Choose File | Settings | Tools | Command Line Tool Support for Windows and Linux or PhpStorm | Preferences | Tools | Command Line Tool Support for macOS.

    On the Command Line Tool Support page that opens, click icons general add svg.

  2. In the Command Line Tools dialog that opens, choose Composer from the list. Using the Visibility option button, specify whether the tool will be available globally, i.e. in any PhpStorm project, or in the current project only:
    ps cli tool composer

    Click OK to apply your changes.

  3. In the Command Line Tool Support: Composer dialog that 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.

    PhpStorm parses the contents of the specified .phar archive or executable file for Composer commands. When the file analysis is completed, PhpStorm returns to the Command Line Tools Support page where the specified file is added to the list of command line tools available in PhpStorm.

    Click OK to apply your changes. The Composer tool will be added to the list of tools on the Command Line Tools Support page.

  4. Select the Enable checkbox next to the added tool, specify the alias to use in calls, customize the command set if necessary, and choose where to show the Input pane for running commands. Refer to How do I customize a tool? and Input pane location for details.

The Composer command-line tool is now added, and you can run commands with it. Open the Input pane (Tools | Run Command) and type <alias> (c by default) and press Ctrl+Space to invoke completion. The command execution result is displayed in the Output tab with the name of the command. Learn more from How do I run a command?.

Last modified: 10 October 2018

See Also