Duster Documentation

Duster uses Pint (which uses PHP CS Fixer under the hood) to automatically fix PHP code issues. The default style guide enforces specific rules for indentation, syntax, spacing, and structure. Common rules include:

• Array Syntax: Uses short array syntax [1, 2] instead of array(1, 2).
• Braces: Enforces proper placement of braces for classes, functions, and control structures.
• Namespaces: Ensures a single blank line after the namespace declaration and no spacing/comments within the namespace line.
• Imports: Uses use statements for global classes, functions, and constants instead of fully qualified names.
• Keywords: Enforces correct casing for true, false, and null (lowercase) and uses elseif instead of else if.

TLint is a tool that performs both linting (identifying issues) and fixing (automatically correcting issues).

Key characteristics:

• Every formatter includes a corresponding linter.
• Not every linter has an associated formatter (some issues can only be flagged, not automatically fixed).
• It enforces specific coding standards and Laravel best practices through various formatters.

Because commits made by Duster Fix do not trigger new workflows, you should configure your other workflows to run after the Duster Fix workflow has completed using the workflow_run event.

on:
  # This workflow is configured to run after Duster finishes
  workflow_run:
    workflows: ["Duster Fix"]
    types:
      - completed

You can scaffold configuration files for automation:

• To publish a GitHub Actions config: ./vendor/bin/duster github-actions

• To publish Husky Hooks: ./vendor/bin/duster husky-hooks

If you are using a containerized environment (like DDEV, Warden, Lando, or Sail) and do not have PHP installed locally, use the --env flag to specify the environment.

# Example for Husky hooks in a DDEV environment
./vendor/bin/duster husky-hooks --env=ddev

Install Duster as a development dependency using Composer to automatically apply Tighten's default code style to your Laravel application.

composer require tightenco/duster --dev

If you are using Laravel Sail, you can execute Duster through the Sail binary. You can either call PHP directly through Sail or use the bin helper script.

# Option 1: Direct execution
./vendor/bin/sail php ./vendor/bin/duster

# Option 2: Using the Sail bin helper
./vendor/bin/sail bin duster

Use the following commands to manage your code style:

• lint: Checks all files for style issues.
• fix: Automatically fixes all detectable style issues.
• --dirty: When used with lint or fix, Duster will only process files that have uncommitted changes according to Git.

To see all available commands, run ./vendor/bin/duster or ./vendor/bin/duster commands.

# Lint everything
./vendor/bin/duster lint

# Fix everything
./vendor/bin/duster fix

# Lint only files with uncommitted changes
./vendor/bin/duster lint --dirty

The single_line_comment_style formatter ensures that single-line comments and multi-line comments containing only one line of content use the // syntax instead of #.

[
  'comment_types' => [
    0 => 'hash',
  ],
]

The phpdoc_separation rule groups similar annotations together and separates different types with a blank line. You can define these groups using the groups configuration.

[
  'groups' => [
    0 =>   [
      0 => 'deprecated',
      1 => 'link',
      2 => 'see',
      3 => 'since',
    ],
    1 =>   [
      0 => 'author',
      1 => 'copyright',
      2 => 'license',
    ],
    2 =>   [
      0 => 'category',
      1 => 'package',
      2 => 'subpackage',
    ],
    3 =>   [
      0 => 'property',
      1 => 'property-read',
      2 => 'property-write',
    ],
    4 =>   [
      0 => 'param',
      1 => 'return',
    ],
  ],
]

Configure how binary operators are surrounded by spaces. The default is single_space.

[
  'default' => 'single_space',
]

Control the position of opening braces for various structures.

Key configuration options include:

• control_structures_opening_brace: e.g., same_line.
• functions_opening_brace: e.g., next_line_unless_newline_at_signature_end.
• classes_opening_brace: e.g., next_line_unless_newline_at_signature_end.
• anonymous_functions_opening_brace: e.g., same_line.
• allow_single_line_anonymous_functions: boolean.

[
  'control_structures_opening_brace' => 'same_line',
  'functions_opening_brace' => 'next_line_unless_newline_at_signature_end',
  'anonymous_functions_opening_brace' => 'same_line',
  'classes_opening_brace' => 'next_line_unless_newline_at_signature_end',
  'anonymous_classes_opening_brace' => 'next_line_unless_newline_at_signature_end',
  'allow_single_line_empty_anonymous_classes' => true,
  'allow_single_line_anonymous_functions' => false,
]

The ordered_imports rule sorts use statements. Use sort_algorithm (e.g., 'alpha') and imports_order to define the priority of different import types.

[
  'sort_algorithm' => 'alpha',
  'imports_order' => [
    0 => 'const',
    1 => 'class',
    2 => 'function',
  ],
]