How to Use PHP-CS-Fixer (with Examples)

PHP-CS-Fixer is an essential tool for PHP developers aimed at enforcing coding style standards within a codebase. It automatically detects and fixes coding style errors based on defined rules, ensuring that code is not only clean and readable but also consistent with best practices. Available as a command-line tool, PHP-CS-Fixer provides developers with the flexibility to apply various styling rules, making the process of maintaining code quality both efficient and straightforward.

Execute code style fixing in the current directory

Code:

php-cs-fixer fix

Motivation:

Running PHP-CS-Fixer in the current directory simplifies the process of maintaining code style standards across an entire project without needing to specify paths. It is particularly useful during development when changes are frequently made, helping developers maintain consistency and clean code throughout. By applying fixes automatically, it saves time and reduces errors from manual formatting.

Explanation:

The command php-cs-fixer fix searches for all PHP files in the current directory and its subdirectories, applying predefined style rules. The absence of additional arguments implies that it operates directly in the directory where the command is executed.

Example output:

Loading configuration file .php_cs
Using cache file ".php_cs.cache".
F
Legend: ?-unknown, I-invalid file syntax, file ignored, .-no changes, F-fixed

Fixed all files in 0.123 seconds, 10.000 MB memory used

Execute code style fixing for a specific directory

Code:

php-cs-fixer fix path/to/directory

Motivation:

Specifying a directory allows developers to apply code style fixes selectively on certain parts or modules of a project. This can be particularly useful for large projects or when iterating on specific features or bug fixes. It enables targeted enhancements without affecting the rest of the codebase.

Explanation:

By using php-cs-fixer fix path/to/directory, the tool targets the provided path. This flexibility lets the developer choose which directory should adhere to style rules, allowing for incremental improvements or focused refactoring.

Example output:

Loading configuration file .php_cs
Using cache file ".php_cs.cache".
F
Legend: ?-unknown, I-invalid file syntax, file ignored, .-no changes, F-fixed

Fixed all files in 0.134 seconds, 10.500 MB memory used

Execute code style linting without applying changes

Code:

php-cs-fixer fix --dry-run

Motivation:

The --dry-run option is invaluable when assessing the impact of style rules before making actual changes. It allows developers to review potential modifications, ensuring no unintended consequences occur. It’s an excellent way to gauge if configurations or rules need adjustment before any changes are committed.

Explanation:

The --dry-run flag tells PHP-CS-Fixer to scan the files and report fixes that would be performed, without actually modifying any files. This simulation helps developers preview changes and maintain control over their code revisions.

Example output:

Loading configuration file .php_cs
Using cache file ".php_cs.cache".
.......................................................
Fixed all files in 0.150 seconds, 10.700 MB memory used

Execute code style fixes using specific rules

Code:

php-cs-fixer fix --rules=rules

Motivation:

Customizing coding style enforcement using specific rules allows developers to tailor the tool to match individual or team preferences. This can help align the code with specific project standards or adhere to particular guidelines set by a development team or organization.

Explanation:

Here, --rules=rules specifies which coding style rules to apply. It might include a predefined set or custom-configured rules suited to the project’s needs. Specifying rules ensures that only desired changes are considered, providing precise control over code modifications.

Example output:

Loaded config default.
Using cache file ".php_cs.cache".
Legend: ?-unknown, I-invalid file syntax, file ignored, .-no changes, F-fixed

Fixed all files in 0.140 seconds, 14.800 MB memory used

Display the rules that have been applied

Code:

php-cs-fixer fix --verbose

Motivation:

A verbose output is beneficial for understanding what changes PHP-CS-Fixer is making to the codebase. It provides insight into the rules applied, helping developers learn from the modifications and adopt better coding practices. It also aids troubleshooting by showing explicit outputs for debugging and analysis.

Explanation:

The --verbose flag provides detailed logging about what operations are being performed. It lists all fixes applied to each file, making the code modification process transparent, which is especially useful during initial tool adoption or complex rule configurations.

Example output:

Loading configuration file .php_cs
Using cache file ".php_cs.cache".
   1) src/ExampleFile.php (trailing_comma_in_multiline_array)
   2) src/OtherFile.php (concat_space)

Fixed all files in 0.130 seconds, 11.000 MB memory used

Output the results in a different format

Code:

php-cs-fixer fix --format=txt|json|xml|checkstyle|junit|gitlab

Motivation:

Different teams or CI systems may require outputs in specific formats for integration and analysis purposes. By supporting various output formats, PHP-CS-Fixer allows compatibility with multiple tools and environments, facilitating automated quality checks and reporting in diverse development ecosystems.

Explanation:

The --format argument specifies the report’s format, which can be text, JSON, XML, or others. This flexibility ensures that PHP-CS-Fixer can be integrated seamlessly into various workflows or reporting systems and can provide human-readable or machine-parsable data as needed.

Example output (in JSON format):

{
    "files": {
        "src/ExampleFile.php": {
            "appliedFixers": [
                "trailing_comma_in_multiline_array"
            ]
        }
    },
    "memory": "12.000 MB",
    "time": "0.120 seconds"
}

Display files that require fixing

Code:

php-cs-fixer list-files

Motivation:

Identifying files that need attention without immediately applying fixes allows developers to focus efforts precisely where they are needed. It supports strategic code reviews and management by listing areas of the codebase that deviate from established standards, thus directing resources and attention to improve code quality progressively.

Explanation:

By running php-cs-fixer list-files, developers can view a list of files that require style corrections. This command isolates problematic files, promoting a focused and efficient approach to maintaining code quality.

Example output:

src/ExampleFile.php
src/OtherFile.php

Describe a rule or ruleset

Code:

php-cs-fixer describe rule

Motivation:

Comprehending what each rule enforces helps developers make informed decisions when configuring their style guidelines. Understanding the scope and impact of a rule facilitates better customization and ensures the rules align with the desired coding standards.

Explanation:

The describe command, followed by a rule, provides a detailed explanation of what that rule accomplishes. This educational resource aids developers in understanding and selecting appropriate rules for their project.

Example output:

Description of rule trailing_comma_in_multiline_array:
Arrays should have a trailing comma in a multiline configuration.

Conclusion:

PHP-CS-Fixer is a versatile and comprehensive tool that empowers PHP developers to enforce and maintain coding standards efficiently. Whether targeting entire codebases, specific directories, or utilizing various rule configurations, PHP-CS-Fixer offers essential functionalities that improve code quality and ensure consistency throughout a project’s lifecycle.