Today Tighten announced the 1.0 release of the Laravel-focused code linter and fixer Duster.
Duster is a tool that brings together Laravel Pint, PHP_CodeSniffer, PHP-CS-Fixer, and Tightens Laravel-specific lints into Tlint to provide a powerful and comprehensive linting and fixing toolset for Laravel apps.
If you’ve read our articles on Sharing PHPCS Rules or Sharing PHP CS Fixer Rules, you’re already familiar with the idea of publishing a custom set of rules for your projects. Duster takes the core sentiments of Laravel in Pint, then adds the power of additional linters and fixers through the other three bundled tools. It sticks to the Tighten code style by default, but can also be fully configured to your liking.
Let’s take a look at how to install Duster, how to run it, how to integrate it into your automated workflows, and how to configure it (if you want – you might be happy with the default rules!)
There are several ways to run Duster in your application. However, the easiest way is to install it as a Composer dependency in your app.
composer require tightenco/duster --dev
You don’t have to publish or configure anything. Duster comes with a number of idiosyncratic styles, and if you like them, it’s ready to go as soon as the installation is complete.
There are two main features that Duster offers: “Fuzz” and “Fix”. Lints let you know when something in your code doesn’t match a rule. Fixing fixes this code.
First we can do the basics: fluff or fix the entire code base.
when we run
lintit gives us a lint of the entire codebase and runs all the linting tools:
This gives us the output for each tool and like any linter, returns a success or failure code that can be used in CI tools or other scripts.
We can walk too
fix to instruct all included tools to fix all possible problems in the whole codebase:
Only “dirty” files fluff
When you introduce a linter/fixer into an existing codebase, it can often seem overwhelming: there are so many small fixes to make that you might be tempted to throw the whole thing away.
One way to avoid running fixes (or a lot of fluff bugs) on code you’re not currently working on is Duster’s
--dirty Flag that only runs the linters/fixers on files that have uncommitted changes.
./vendor/bin/duster lint --dirty
./vendor/bin/duster fix --dirty
Why repair? And fluff?
There are two main reasons why Duster and many similar tools offer both fluffing and fixing. Why add fluff when you can always just fix anything?
First, some teams may prefer a workflow where broken code appears as a broken build (e.g., as a GitHub action) rather than fixed.
And secondly, some fluff cannot be fixed automatically. A computer can tell if your code is broken, but isn’t smart enough to fix it for you.
Integrate Duster into your CI
Like most code analysis tools, Dusters
lint The command returns a success or failure code depending on whether the lints were successful. This means you can use it
./vendor/bin/duster lint in any CI pipeline will cause your builds to fail if your lints don’t match. You can also use
./vendor/bin/duster fix as part of a Husky hook or a CI hook to automatically format your code.
If you use GitHub Actions, Duster makes it easy to publish an action configuration that does both
lint your code or
fix It. Run
./vendor/bin/duster github-actions and follow the instructions there to add the GitHub action to your code base.
Configuring Duster (and its tools)
Like Pint, Duster embodies the opinion of its developers (Tighten) on how code should be designed. But Duster itself and each of the imported tools can be configured to your liking.
Duster provides its own configuration file,
duster.json. This file allows you to define files and folders
exclude from the standard Laravel files, which it targets by default. You can also use it to define additional scripts that you want to run as part of your script
For example, you can add PHPStan to your
lint command with the following
"phpstan": ("./vendor/bin/phpstan", "analyse")
You can also define your own custom additions to the
You can configure any of Duster’s dependencies with their native configuration files. See the Customize section of the Duster readme for more information.
- PHP CS Fixer:
- A notice:
That’s it! In summary, Duster is a tool for fluffing and fixing code style issues in your Laravel apps. It’s headstrong, sticking to Tighten’s preferred standards by default, but it’s also configurable to your liking—including your own custom standards if you’ve published them.