Libraries and library roots

A library is a third-party file or set of files used in a project as is.

PHP libraries are most commonly managed in projects by Composer, which declares them as dependencies and installs to folders in the vendor directory. To distinguish libraries from the project files but still include their classes and methods to the IDE's internal knowledge, PhpStorm marks library folders as library roots. For more information, refer to PHP library roots.

JavaScript libraries can be configured at the global (IDE) or project level, which defines reusability of the library within the IDE. For more information, refer to Configuring Javascript libraries.

PHP library roots

In PhpStorm, a library root is a folder with library files that is marked as Excluded and at the same time is added as a PHP include path in Settings | PHP | Include Path. PhpStorm treats this root type in the following way:

Despite being excluded, libraries are still indexed, which means that the classes and methods from libraries are available in auto-completion, search, reference resolution, and so on, but on a second-class citizen principle. You can exclude Composer-managed libraries from indexing completely.
Libraries are excluded from error checks.
All library files open in the Reader mode and are protected with a Non-Project Files Protection pop-up on modification attempts, such as direct intentional editing or update result from refactoring.

In the Project tool window, library roots are marked with a colored background only:

View library roots in a project

By default, all folders under the vendor directory are considered to be library roots by PhpStorm. Such folders are added to Settings | PHP | Include Path automatically.
You can remove library roots from the autogenerated list in Settings | PHP | Include Path manually, but note that, when you close and re-open the project, the list is regenerated by PhpStorm from the vendor folder anew.
The External Libraries node in the Project tool window contains library roots added as PHP include paths manually.
If the project contains only Composer-managed libraries, double-clicking External Libraries opens the list of library roots in Settings | PHP | Include Path.

Exclude libraries from indexing

You can exclude the contents of the vendor directory from indexing. To do so:

In the Settings dialog (Control+Alt+S), go to PHP | Composer, clear the Add packages as libraries checkbox, and apply the changes.
All folders under the vendor directory are now converted into regular project folders.
Select the folder you want to exclude in the Project tool window, and from its context menu, select Mark Directory as | Excluded.

Besides Composer, you can use a third-party tool or framework as a library in your project in the following ways:

Store the tool under the project content root.
Add the tool under the PHP home directory and specify a relative path to it manually.
Store the tool elsewhere and configure it as a custom command line tool.

In either case, you can use exploded and archived tool sources. PhpStorm recognizes most popular zip and TAR.GZ formats as well as the PHP native PHAR format.

Last modified: 27 October 2023