PhpStorm 2024.1 Help

Rector

PhpStorm supports PHP code upgrade and refactoring functionality based on the Rector plugin, which is bundled and enabled in the IDE by default.

Rector provides code transformation rules for automated refactoring and upgrade of applications to a newer framework or PHP version. With PhpStorm, you can run Rector rules against a selected folder or file right from the Project tool window, compare the source and modified code in the diff viewer, and pick which changes to apply.

Before you start

Rector requires PHP version 7.2 and later and uses the local or remote PHP interpreter set for the project. Make sure the PHP interpreter is configured in PhpStorm on the PHP page, as described in Configure local PHP interpreters and Configure remote PHP interpreters.

For Docker Compose-based remote interpreters, make sure to use docker-compose exec mode to avoid spawning additional containers.

Install and configure Rector

Install Rector with Composer

  1. Inside composer.json, add the rector/rector dependency record to the require or require-dev key. To get code completion for the package name and version, press Ctrl+Space.

    "require-dev": { "rector/rector": "^0.15.13" },
  2. 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, PhpStorm 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.

For more information about installing Rector, refer to Rector documentation.

Add and edit a Rector config file

  1. Add a rector.php template file to the project root by either of the following:

    • Right-click the root folder in the Project tool window and select New | rector.php File from the context menu.

      PhpStorm invokes a rector init action, which creates a rector.php file in the same way as Rector's vendor/bin/rector init command executed from the command line would do.

    • Search and apply the rector init action from the search window (Ctrl+Shift+A).

      Search and apply rector init action
    • Run the rector init command from the Terminal tool window.

      vendor/bin/rector init
  2. Edit the generated rector.php file to specify which Rector rule or rule sets you need. Press Ctrl+Space to get code completion suggestions.

    Code completion for Rector rulesets

Run a Rector configuration

You can run Rector on a folder, a file, a selection of multiple folders or files, or from within the rector.php config file. PhpStorm creates a default run configuration, runs Rector, and outputs the list of files that have suggested changes in them.

As with any other run/debug configuration in PhpStorm, you can save as permanent, share, create from a template, group in folders, or save for later use a run configuration for Rector.

Run Rector on a folder or file

  • In the Project tool window, select the file or folder to run Rector on and choose Run | <File or folder name> (Rector) from the context menu of the selection:

    Run Rector configuration

    PhpStorm generates a default run configuration and runs the vendor/bin/rector process --dry-run command on the scope specified in the configuration.

Run Rector from rector.php

  1. Open rector.php in the editor.

  2. Click App run configurations test state run in the gutter and select Run '<project name>' (Rector) from the context menu. Alternatively, press Ctrl+Shift+F10 from anywhere in the file.

    Run rector from rector.php

    If you have $rectorConfig->paths defined in your rector.php file, then Rector runs on the specified scope of folders. Otherwise, the run configuration path is automatically set to the src/ folder in the project root.

Create a custom Rector configuration

You can create a custom run configuration or edit an existing default one—for example, to pass additional arguments to the vendor/bin/rector process command.

  1. In the Project tool window, select the file or folder and choose More Run/Debug | Modify Run Configuration | <File or folder name> (Rector) from the context menu.

    Alternatively, go to Run | Edit Configurations in the main menu, then click Add icon and choose Rector from the list.

  2. In the Rector configuration dialog that opens, edit the fields as required.

Review and apply changes

PhpStorm shows Rector execution results—that is, a list of files with suggested changes—in the Changes tab of the Run tool window. The Console tab contains the same execution output, but in the JSON format.

Rector execution results
  1. In the Changes tab, click a file from the list to open it and preview the suggested changes in the diff viewer.

    Rector diff viewer
  2. To apply the changes, select checkboxes for the relevant files in the Run tool window and click Apply.

Last modified: 17 April 2024