How to enhance code consistency & efficiency with Laravel Pint

Laravel Pint

Have you ever opened up a PR only to play the game of "Find the change" through a wall of green and red diff, and to make matters worse, 99% of the changes are indentation or formatting? I think we all have.

The above scenario generally happens when somebody makes a change and their IDE tries to help, but formats a file based on their rules, which are different from your rules. Great intention, but poor results.

If you’re wondering how to end this madness, allow me to introduce you to Laravel Pint.

The importance of consistent code standards

In any software development project, maintaining consistent code standards is crucial for several reasons. First, it ensures that the code is readable and understandable by any developer who might work on it, reducing the likelihood of errors and making onboarding new team members more manageable. Consistency also improves collaboration, as developers can focus on solving problems, rather than deciphering different coding styles (or fighting that dreaded wall of green and red mentioned above). The basis of a great set of coding standards is not solely based on which rules you follow, but ensuring that everyone follows the same rules.

Moreover, in projects spanning multiple teams or repositories, consistent standards prevent discrepancies and maintain a unified codebase, streamlining development and deployment processes.

Laravel Pint: a new standard in code formatting (for Laravel)

Laravel Pint, an opinionated PHP code style fixer for Laravel projects, is designed to help developers maintain a consistent coding standard across their codebase. It extends the capabilities of PHP CS Fixer by specifically supporting Laravel's ecosystem, including Blade templates (with a plugin) - a key differentiator that can streamline the formatting process for Laravel developers.

Why Pint?

Laravel Pint is a streamlined, zero-config code formatting tool built on top of PHP CS Fixer but optimized for Laravel projects. Unlike PHP CS Fixer, which requires manual configuration and rule setup, Pint works out of the box with sensible defaults tailored for Laravel's coding standards, making it easier to integrate into projects. It also provides a simpler and more intuitive CLI experience, reducing setup time and maintenance. Since it's officially supported by Laravel, Pint ensures better compatibility with Laravel conventions, making it the preferred choice for developers working within the Laravel ecosystem.

Transitioning from CS Fixer to Laravel Pint

The transition from PHP CS Fixer to Laravel Pint is designed to be smooth and straightforward, just like other pints should be. Pint uses a zero-configuration approach by default, automatically adopting Laravel's recommended coding style. This simplicity means developers can integrate Pint into their workflow without a steep learning curve or the need to configure a myriad of options.

Migrating a custom CS Fixer configuration

If you've been using a custom PHP CS Fixer configuration, transitioning to Pint can still be seamless. Here's how to migrate your custom settings:

1. Identify rules: Start by identifying the rules you've customized in your PHP CS Fixer configuration (.php-cs-fixer.php). Map these rules to Pint's configuration style.

2. Create Pint configuration: Laravel Pint uses a .pint.json configuration file. You can create this file in your project's root directory and translate your custom rules from CS Fixer to Pint. While Pint aims to be zero-configuration, it does support customization for specific rules, and since it's built on top of PHP CS Fixer, all of your rules should work. While you're in here, this is a great time to evaluate your rules. Michele Locati's php-cs-fixer-configurator is a pretty awesome tool for this.

Example:

{
       "preset": "laravel",
       "rules": {
           "array_syntax": {"syntax": "short"},
           "binary_operator_spaces": {"default": "align_single_space"}
       }
   }

3. Test and adjust: Run Pint on your codebase and compare the results with your previous CS Fixer outputs. Adjust the rules as necessary to achieve the desired formatting.

Setting Pint up to manage Blade files

Out of the box, Blade files are not supported. But this is really easy to solve. Stillat have released their Blade parser. This tool is fantastic, as it helps check Blade syntax and any PHP within the Blade templates can easily be evaluated through your Pint rules. An added benefit of this parser is it can work with Prettier to format your Blade files through Prettier which can format your frontend CSS and JavaScript assets at the same time for formatted and consistent code-style everywhere.

Details on setting up the parser to work with Blade is available here: https://stillat.com/blade-parser/v1/formatting-configuration#content-configuring-laravel-pint

Running Pint

Now that you have Pint set up just the way you (or your team) likes it, it’s time to gain some real advantages.

The barebones run can be done with a simple:

./vendor/bin/pint

This will check your files and complain about anything it finds a little naughty in there. If you need some more detail you can throw a -v on the end there to get a more verbose output.

Other options that are super useful are:

• --test: to view issues but not act on them

• --dirty: to only fix issues on the uncommitted files

• --repair: to fix the issues but still exit out with a non-zero code (this is particularly useful for actions and workflows)

NB: With any script that modifies code: check your code after this has run. There's no benefit in having beautifully formatted code that doesn't work. I mean obviously your 100% code-coverage test suite will catch this, but check it yourself, you know, just in case.

Setting up Pint in pre-commit workflows

Integrating Pint into your pre-commit workflow is a critical step to ensure that code style consistency is maintained across your project. Just as a pint is meant to be enjoyed, not kept on the bar, Laravel Pint isn't super useful if we install it and leave it. Here's a simple way to set this up using Git hooks:

1. Install Pint: First, install Laravel Pint via Composer. If you've followed along up till here, this is done already…

composer require laravel/pint --dev

2. Create a Git Hook: Set up a pre-commit Git hook to run Pint automatically. In your project's .git/hooks directory, create a new file named pre-commit and add the following script:

#!/bin/sh
./vendor/bin/pint --dirty --test
if [ $? -ne 0 ]; then
    echo "Code style issues found! Please fix them before committing."
    exit 1
fi

3. Make the hook executable: Ensure the script is executable by running:

chmod +x .git/hooks/pre-commit

This setup will automatically check for code style issues using Pint before each commit, ensuring that only properly formatted code is committed to the repository.

Adding a GitHub Action for Laravel Pint

To enforce code style checks on pull requests and ensure consistency across contributions, you can set up a GitHub Action to run Pint. Here's a basic configuration:

1. Create GitHub workflow: In your repository, navigate to .github/workflows and create a file named pint.yml.

2. Define the action: Add the following configuration:

name: Laravel Pint
 
on:
  pull_request:
    push:
      branches:
        - main
 
jobs:
  pint:
    runs-on: ubuntu-latest
      steps:
       - uses: actions/checkout@v2
 
       - name: Set up PHP
         uses: shivammathur/setup-php@v2
         with:
           php-version: '8.4' # Replace with your PHP version
 
       - name: Install dependencies
         run: composer install --no-progress --prefer-dist --no-suggest
 
       - name: Run Laravel Pint
         run: ./vendor/bin/pint --test

This action will run Laravel Pint on every push or pull request, ensuring that your code adheres to the defined style rules.

You will notice that this is set to run with --test, this is so that it can highlight any errors but not take action, just in case it's looking to make a change you may not want.

Bringing a Codebase Up to Speed

For projects that have not consistently adhered to a code standard, the task of bringing the entire codebase up to speed can be daunting. Here are some valuable tips to help streamline this process:

1. Start small: Begin by applying Pint to a single directory or set of files. This approach makes it easier to manage and review changes incrementally.

2. Automated fixes: Pint will automatically correct style violations. This feature can save a significant amount of time, especially for larger codebases.

3. Review and refactor: After automatic fixes, manually review the changes to ensure they don't inadvertently alter the logic. It's also a good opportunity to refactor any messy code.

4. Gradual enforcement: Implement Pint in your CI/CD pipeline and set it to fail builds if the code does not meet the required standards. This practice enforces code style adherence gradually, giving the team time to adapt.

5. Team training and documentation: Educate your team on the importance of code consistency and how to use Pint. Provide clear documentation and examples to help developers understand and adopt the new standards.

I have a preference for a quick code-freeze, formatting is implemented and checked, then work carries on as usual. It’s better to have the whole project brought up together than have to deal with formatting diffs in feature PRs.

Conclusion

Migrating from PHP CS Fixer to Laravel Pint offers a straightforward path to improving code consistency, especially for Laravel projects that utilize Blade templates. By integrating Pint into your pre-commit workflows and GitHub Actions, and following a structured approach to reformatting your codebase, you can achieve a cleaner, more maintainable codebase. The benefits of this transition are clear: better readability, easier collaboration, and a unified coding standard that can be enforced across multiple projects. Embracing Laravel Pint is a step toward more efficient and harmonious development practices.

The only challenge our team still faces in this process is getting everyone to consistently refer to it as "Pint" (like the measurement) or "Pint" (rhyming with "mint").

PS. It's supposed to be pronounced to rhyme with "mint"...