Tuning PhpStorm Indexing for Large PHP Projects

PhpStorm slows down and suggests irrelevant classes as your PHP project grows

In a mature PHP application, PhpStorm may start to lag while you type, and code completion may surface classes from vendor dependencies instead of your own source code. The cause is usually indexing: PhpStorm scans files to build a model of symbols, classes, and relationships so it can offer completion, navigation, and inspections. When every directory under the project root is treated equally, that model includes thousands of dependency files you rarely need to navigate.

The practical fix is to tell PhpStorm which directories are application source, which are dependencies, and which should be ignored entirely. This narrows the index, speeds up the IDE, and makes completion prioritize your code.

What indexing means in PhpStorm

Indexing is the background process PhpStorm uses to parse PHP files and build an internal map of classes, methods, constants, and references. That map powers features such as Go to Declaration, Find Usages, and code completion. You can see indexing in progress from the status bar at the bottom of the IDE window. A large project with many indexed files uses more CPU and memory, especially right after you open the project or run Composer updates.

Configure project directories for PHP source

Open the project settings. In PhpStorm, go to File > Settings (or PhpStorm > Settings on macOS), then Project: YourProject > Directories. The list shows every folder in the project root with labels such as Sources, Tests, Resource Root, Excluded, and Library Files.

For a typical Composer-based PHP project:

• Mark src/ or app/ as Sources so PhpStorm treats it as application code.
• Mark tests/ as Tests so test helpers are available but separated from production source.
• Mark vendor/ as Excluded if you do not need to jump into dependency source code during normal development.
• Mark var/, storage/, runtime/, and build output folders as Excluded to keep generated files out of the index.

Excluding a directory removes it from indexing and search results. PhpStorm will no longer parse those files for completion or inspections, which reduces background work.

Worked example: exclude vendor and verify completion

Assume your project root is /var/www/myapp and you run PhpStorm on Linux as a normal user with read access to the project files. No elevated permissions are required to change directory markers.

1. Open PhpStorm and load /var/www/myapp.
2. Open Settings > Project: myapp > Directories.
3. Select the vendor folder in the tree.
4. Click Excluded, or right-click the folder and choose Mark Directory as > Excluded.
5. Apply the changes and wait for the indexing indicator in the status bar to finish.

Open a PHP file in src/ and type part of a class name from your application, such as UserRepository. Press Ctrl+Space or Cmd+Space on macOS to trigger completion. The IDE should surface your application class before any similarly named class from vendor/. If vendor remains excluded, you can still use Composer-installed classes through autoloading, but PhpStorm will not offer them as local completion candidates unless you explicitly import them.

To confirm the scope change, use Find Usages on a class in src/ (Alt+F7). The results should not include files under vendor/ unless your code explicitly references them.

Trade-off: navigation versus speed

Excluding vendor/ makes the IDE faster, but it also removes direct navigation into dependency source code. If you regularly need to read framework or library internals, keep vendor/ indexed and instead exclude only large generated folders such as storage/ or build output. You can toggle the marker at any time, so treat it as a per-project decision rather than a permanent rule.

Plugin compatibility can also affect what PhpStorm understands. Framework plugins for Laravel or Symfony rely on the indexed project model, so a heavily excluded project may reduce their effectiveness. Check that your installed plugins are compatible with the PHP interpreter version configured under Settings > Languages & Frameworks > PHP.

Actionable check

After changing directory markers, open the Events log or status bar and confirm indexing has stopped. Then open a file in your main source directory and run code completion. If the suggestions match your application classes and the IDE feels responsive, the configuration worked. If completion still surfaces mostly dependency classes, review the Directories list to ensure no source folder was accidentally marked Excluded.