PHP CS Fixer: A Complete guide to Installation, Usage, and Integration

Photo by Steve Johnson on Unsplash

Code consistency is a crucial aspect of maintaining a clean and readable codebase. PHP CS Fixer is a powerful tool that helps enforce coding standards by automatically fixing PHP coding style issues. In this article, we will explore how to install and use PHP CS Fixer, integrate it into your development workflow, and even set it up in a GitLab CI/CD pipeline. Additionally, we’ll cover the available IDE plugins to streamline your coding experience.

Installing PHP CS Fixer

You can install PHP CS Fixer globally or locally in your project.

Global Installation

To install PHP CS Fixer globally using Composer, run:

composer global require friendsofphp/php-cs-fixer

Make sure your global Composer vendor/bin directory is in your system's PATH to run it from any location:

export PATH="~/.composer/vendor/bin:$PATH"

Introduction to PHP Composer

Local Installation

To install it as a development dependency in a specific project:

composer require --dev friendsofphp/php-cs-fixer

After installation, you can use it via:

vendor/bin/php-cs-fixer

Using PHP CS Fixer

Basic Usage

To check and fix PHP code style issues in a project:

php-cs-fixer fix /path/to/your/project

To dry-run (check for issues without fixing them):

php-cs-fixer fix --dry-run --diff

Configuring PHP CS Fixer

PHP CS Fixer allows customization through a .php-cs-fixer.php configuration file in the root of your project:

<?php
$finder = PhpCsFixer\Finder::create()
    ->in(__DIR__)
    ->exclude('vendor');

return PhpCsFixer\Config::create()
    ->setRules([
        '@PSR12' => true,
        'array_syntax' => ['syntax' => 'short'],
    ])
    ->setFinder($finder);

This configuration:

• Applies PSR-12 coding standards
• Ensures arrays use short syntax
• Ignores the vendor directory

To apply the custom configuration, simply run:

php-cs-fixer fix

PHP CS Fixer in VS Code

A convenient way to use PHP CS Fixer is through an IDE plugin. For VS Code, install the PHP CS Fixer extension.

Installation in VS Code

1. Open VS Code.
2. Go to Extensions (Ctrl+Shift+X).
3. Search for “PHP CS Fixer” and install it.
4. Configure it in settings.json:

{
    "php-cs-fixer.executablePath": "~/.composer/vendor/bin/php-cs-fixer",
    "php-cs-fixer.rules": "@PSR12",
    "editor.formatOnSave": true
}

Now, every time you save a PHP file, PHP CS Fixer will automatically format your code.

Understanding the PHP PSR-12 Standard

Integrating PHP CS Fixer into GitLab CI/CD

To ensure code consistency in your repository, you can add PHP CS Fixer as a step in your GitLab CI/CD pipeline.

Understanding GitLab CI/CD Cache: Usage, Limitations, and Best Practices

.gitlab-ci.yml Configuration

Create or modify the .gitlab-ci.yml file:

stages:
  - lint

php-cs-fixer:
  image: php:latest
  stage: lint
  before_script:
    - apt-get update && apt-get install -y unzip git
    - curl -sS https://getcomposer.org/installer | php
    - php composer.phar install --no-interaction
  script:
    - vendor/bin/php-cs-fixer fix --dry-run --diff
  only:
    - merge_requests

This configuration:

• Runs PHP CS Fixer on merge requests
• Checks for coding style violations without modifying files
• Shows differences if issues are found

To automatically fix and commit changes, modify the script to:

script:
  - vendor/bin/php-cs-fixer fix
  - git diff --exit-code || (git add . && git commit -m "Apply PHP CS Fixer" && git push)

Benefits of using PHP CS Fixer

• Code Consistency: Ensures uniform coding standards across the project.
• Automation: Reduces manual code reviews by enforcing coding styles automatically.
• Time-Saving: Quickly fixes coding style issues without developer intervention.
• CI/CD Integration: Helps maintain clean code in repositories by preventing non-standard commits.
• IDE Integration: Enhances the development experience by formatting code on save.

By integrating PHP CS Fixer into your workflow, you can maintain high code quality with minimal effort. Whether used locally, within an IDE, or as part of a CI/CD pipeline, it ensures your PHP code remains clean and consistent.

Do you use PHP CS Fixer in your projects? Let me know how it has helped your workflow in the comments!

My own PHP CS Fixer setup: A practical example