README

Duster

Automatically apply Tighten's default code style for Laravel apps.

Duster is built on top of the following tools:

TLint: lints Laravel and PHP code for issues not covered by other tools
- using the default Tighten preset
PHP_CodeSniffer: sniffs issues that can't be fixed automatically
- using the Tighten preset which is mostly PSR1 with some Tighten-specific rules
PHP CS Fixer: adds custom rules not supported by Laravel Pint
- CustomOrderedClassElementsFixer Tighten-specific order of class elements
Pint: Laravel's code style rules (with a few Tighten specific customizations)
- using the default Laravel preset with some Tighten-specific rules

You can view a list of the compiled rules and examples of what they do in the style guide.

Installation

You can install the package via composer:

composer require tightenco/duster --dev

Optionally you can publish a GitHub Actions config:

./vendor/bin/duster github-actions

Or you can publish Husky Hooks:

./vendor/bin/duster husky-hooks

If you are using a containerized environment and do not have PHP installed locally, you can use the --env option to specify it:

./vendor/bin/duster husky-hooks --env=ddev

Supported environments are ddev, warden lando, and sail.

Usage

To lint everything at once:

./vendor/bin/duster lint

To fix everything at once:

./vendor/bin/duster fix

To dust only files that have uncommitted changes according to Git, you may use the --dirty option:

./vendor/bin/duster lint --dirty
#or
./vendor/bin/duster fix --dirty

To view all available commands:

./vendor/bin/duster
#or
./vendor/bin/duster commands

Usage with Sail

./vendor/bin/sail php ./vendor/bin/duster

Alternatively, Sail has a bin script that eases the execution of package binaries, so you do the same thing like this:

./vendor/bin/sail bin duster

Customizing

If you need to include or exclude files or directories for each tool you can create a duster.json config file in your project root:

{
    "include": [
        "bin",
        "scripts",
        "src",
        "tests"
    ],
    "exclude": [
        "tests/fixtures"
        "**/folderToExclude/**"
    ]
}

To run additional scripts as part of Duster first add them to duster.json as part of scripts separated into lint and fix.

The key is the name of the command (used with the --using flag), and the value is an array of arguments passed to Symfony\Component\Process\Process.

{
    "scripts": {
        "lint": {
            "phpstan": ["./vendor/bin/phpstan", "analyse"]
        }
    },
    "processTimeout": 120
}

Duster will pick these up automatically when running either lint or fix. By default, additional scripts timeout after 60 seconds. You can overwrite this setting using the processTimeout key.

To customize which tools Duster runs, or the order in which they are executed you can use the --using flag and supply a comma-separated list of commands:

./vendor/bin/duster lint --using="phpstan,tlint,pint"

TLint

Create a tlint.json file in your project root. Learn more in the TLint documentation.

PHP_CodeSniffer

Create a .phpcs.xml.dist file in your project root with the following:

<?xml version="1.0"?>
<ruleset>
    <file>app</file>
    <file>config</file>
    <file>database</file>
    <file>public</file>
    <file>resources</file>
    <file>routes</file>
    <file>tests</file>

    <rule ref="Tighten"/>
</ruleset>

Now you can add customizations below the <rule ref="Tighten"/> line or even disable the Tighten rule to use your own ruleset. Learn more in this introductory article.

PHP CS Fixer

Create a .php-cs-fixer.dist.php file in your project root with the contents from Duster's .php-cs-fixer.dist.php file. Learn more in the PHP CS Fixer documentation.

Pint

Create a pint.json file in your project root, you can use Duster's pint.json file as a starting point. Learn more in the Pint documentation.

GitHub Action

There's a GitHub Action you use to clean-up your workflows.

Warning Heads Up! Workflows that commit to your repo will stop any currently running workflows and not trigger another workflow run.

One solution is to run your other workflows after Duster has completed by updating the trigger on those workflows:

on:
  # Commits made in Duster Fix will not trigger any workflows
  # This workflow is configured to run after Duster finishes
  workflow_run:
    workflows: ["Duster Fix"]
    types:
      - completed

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security-related issues, please email hello@tighten.co instead of using the issue tracker.

Credits

Matt Stauffer
Anthony Clark
Tom Witkowski - much of the original idea and syntax for this was inspired by his elbgoods/ci-test-tools package
All Contributors

License

The MIT License (MIT). Please see License File for more information.

tightenco / duster

Maintainers

Details