How to use the command "rector" (with examples)

“rector” is an automated tool for updating and refactoring PHP 5.3+ code. It helps in automatically transforming legacy PHP code to newer versions, making it easier to maintain and follow modern PHP best practices. The command provides various use cases, each serving a specific purpose in the code refactoring process.

Use case 1: Process a specific directory

Code:

rector process path/to/directory

Motivation: This use case is useful when you want to process a specific directory and apply the transformations provided by “rector” to all the PHP files within that directory. It saves you from having to manually update each file by identifying the required changes and updating them automatically, ensuring consistency across the codebase.

Explanation:

• “rector”: The main command for running the “rector” tool.
• “process”: The action to process the specified directory.
• “path/to/directory”: The path to the directory that needs to be processed.

Example output: The command will execute the transformations defined by “rector” on all PHP files within the specified directory, applying the necessary updates to modernize the code.

Use case 2: Process a directory without applying changes (dry run)

Code:

rector process path/to/directory --dry-run

Motivation: Performing a dry run is a common practice when dealing with automated refactoring tools. This use case allows you to assess the potential changes before actually applying them. It helps in understanding the scope of modifications and validating the expected outcome.

Explanation:

• “–dry-run”: An optional flag that enables a dry run, meaning the changes will not be applied to the files. Instead, “rector” will display the potential changes that would be made if the command were executed without the flag.

Example output: The command will display a list of the transformations that would be applied to the files within the specified directory if the command was executed without the “–dry-run” flag. It helps you understand the expected changes before actually performing them.

Use case 3: Process a directory and apply coding standards

Code:

rector process path/to/directory --with-style

Motivation: Maintaining consistent coding standards across the codebase is crucial for code readability and maintainability. This use case allows you to automatically apply coding standards to your refactored code, ensuring it follows the guidelines defined by the project.

Explanation:

• “–with-style”: An optional flag that enables the application of coding standards during the refactoring process. It ensures that the refactored code complies with the defined coding standards.

Example output: The command will execute the refactoring process on the files within the specified directory, applying both the necessary transformations defined by “rector” and the coding standards to ensure the codebase follows the project guidelines.

Use case 4: Display a list of available levels

Code:

rector levels

Motivation: “rector” provides different levels of automated refactoring, each focusing on specific aspects of code improvement. This use case helps you understand the available levels, allowing you to choose the appropriate one for your refactoring process.

Explanation:

• “levels”: The subcommand for displaying the available levels of “rector”.

Example output: The command will display a list of available levels within “rector”. This can include levels like “php70”, “php71”, “php72”, etc., each targeting the refactoring required to move from specific PHP versions to newer ones. This helps you understand the options available for your specific refactoring needs.

Use case 5: Process a directory with a specific level

Code:

rector process path/to/directory --level level_name

Motivation: Different PHP projects may have different requirements when it comes to the target PHP version. This use case allows you to specify a specific level, enabling “rector” to apply refactoring transformations suitable for that level, ensuring compatibility with the target PHP version.

Explanation:

• “–level level_name”: An optional argument that allows you to specify the desired level for refactoring. This level should correspond to one of the available levels provided by “rector”.

Example output: The command will execute the refactoring process on the files within the specified directory, applying the transformations specific to the level specified. This ensures that the codebase is refactored according to the rules and requirements defined for that level, making it compatible with the target PHP version.

Conclusion:

The “rector” command provides a wide range of use cases covering different aspects of code refactoring. By leveraging these use cases, developers can automate the process of updating and refactoring PHP code, making it easier to maintain, follow modern best practices, and ensure consistency across the codebase.