PHP CS Fixer - Laravel Coding Style Ruleset

.php_cs.laravel.php

<?php

use PhpCsFixer\Config;
use PhpCsFixer\Finder;

$rules = [
    'array_syntax' => ['syntax' => 'short'],
    'binary_operator_spaces' => [
        'default' => 'single_space',
        'operators' => ['=>' => null]
    ],
    'blank_line_after_namespace' => true,
    'blank_line_after_opening_tag' => true,
    'blank_line_before_statement' => [
        'statements' => ['return']
    ],
    'braces' => true,
    'cast_spaces' => true,
    'class_attributes_separation' => [
        'elements' => ['method']
    ],
    'class_definition' => true,
    'concat_space' => [
        'spacing' => 'none'
    ],
    'declare_equal_normalize' => true,
    'elseif' => true,
    'encoding' => true,
    'full_opening_tag' => true,
    'fully_qualified_strict_types' => true, // added by Shift
    'function_declaration' => true,
    'function_typehint_space' => true,
    'heredoc_to_nowdoc' => true,
    'include' => true,
    'increment_style' => ['style' => 'post'],
    'indentation_type' => true,
    'linebreak_after_opening_tag' => true,
    'line_ending' => true,
    'lowercase_cast' => true,
    'lowercase_constants' => true,
    'lowercase_keywords' => true,
    'lowercase_static_reference' => true, // added from Symfony
    'magic_method_casing' => true, // added from Symfony
    'magic_constant_casing' => true,
    'method_argument_space' => true,
    'native_function_casing' => true,
    'no_alias_functions' => true,
    'no_extra_blank_lines' => [
        'tokens' => [
            'extra',
            'throw',
            'use',
            'use_trait',
        ]
    ],
    'no_blank_lines_after_class_opening' => true,
    'no_blank_lines_after_phpdoc' => true,
    'no_closing_tag' => true,
    'no_empty_phpdoc' => true,
    'no_empty_statement' => true,
    'no_leading_import_slash' => true,
    'no_leading_namespace_whitespace' => true,
    'no_mixed_echo_print' => [
        'use' => 'echo'
    ],
    'no_multiline_whitespace_around_double_arrow' => true,
    'multiline_whitespace_before_semicolons' => [
        'strategy' => 'no_multi_line'
    ],
    'no_short_bool_cast' => true,
    'no_singleline_whitespace_before_semicolons' => true,
    'no_spaces_after_function_name' => true,
    'no_spaces_around_offset' => true,
    'no_spaces_inside_parenthesis' => true,
    'no_trailing_comma_in_list_call' => true,
    'no_trailing_comma_in_singleline_array' => true,
    'no_trailing_whitespace' => true,
    'no_trailing_whitespace_in_comment' => true,
    'no_unneeded_control_parentheses' => true,
    'no_unreachable_default_argument_value' => true,
    'no_useless_return' => true,
    'no_whitespace_before_comma_in_array' => true,
    'no_whitespace_in_blank_line' => true,
    'normalize_index_brace' => true,
    'not_operator_with_successor_space' => true,
    'object_operator_without_whitespace' => true,
    'ordered_imports' => ['sortAlgorithm' => 'alpha'],
    'phpdoc_indent' => true,
    'phpdoc_inline_tag' => true,
    'phpdoc_no_access' => true,
    'phpdoc_no_package' => true,
    'phpdoc_no_useless_inheritdoc' => true,
    'phpdoc_scalar' => true,
    'phpdoc_single_line_var_spacing' => true,
    'phpdoc_summary' => true,
    'phpdoc_to_comment' => true,
    'phpdoc_trim' => true,
    'phpdoc_types' => true,
    'phpdoc_var_without_name' => true,
    'psr4' => true,
    'self_accessor' => true,
    'short_scalar_cast' => true,
    'simplified_null_return' => false, // disabled by Shift
    'single_blank_line_at_eof' => true,
    'single_blank_line_before_namespace' => true,
    'single_class_element_per_statement' => true,
    'single_import_per_statement' => true,
    'single_line_after_imports' => true,
    'single_line_comment_style' => [
        'comment_types' => ['hash']
    ],
    'single_quote' => true,
    'space_after_semicolon' => true,
    'standardize_not_equals' => true,
    'switch_case_semicolon_to_colon' => true,
    'switch_case_space' => true,
    'ternary_operator_spaces' => true,
    'trailing_comma_in_multiline_array' => true,
    'trim_array_spaces' => true,
    'unary_operator_spaces' => true,
    'visibility_required' => [
        'elements' => ['method', 'property']
    ],
    'whitespace_after_comma_in_array' => true,
];

$project_path = getcwd();
$finder = Finder::create()
    ->in([
        $project_path . '/app',
        $project_path . '/config',
        $project_path . '/database',
        $project_path . '/resources',
        $project_path . '/routes',
        $project_path . '/tests',
    ])
    ->name('*.php')
    ->notName('*.blade.php')
    ->ignoreDotFiles(true)
    ->ignoreVCS(true);

return Config::create()
    ->setFinder($finder)
    ->setRules($rules)
    ->setRiskyAllowed(true)
    ->setUsingCache(true);

no_extra_blank_lines and phpdoc_indent are duplicated

And no_extra_blank_lines has two different constraints 🤔

Corrected.

    'concat_space' => [
        'spacing' => 'none'
    ],

What is the reason for this?

Here it says "use a space before and after ."

https://github.com/php-fig-rectified/fig-rectified-standards/blob/master/PSR-2-R-coding-style-guide-additions.md#multi-line-declarationconditionconcatenation

Because it's Laravel's standard - https://docs.styleci.io/presets#laravel

Unless my tired eyes are deceiving me, I think that no_unused_use or no_unused_imports is missing? It's in the Style CI Laravel preset.

Great resource!

What do you think about adding return_type_declaration => true?

PSR-12 sais:

When you have a return type declaration present, there MUST be one space after the colon followed by the type declaration. The colon and declaration MUST be on the same line as the argument list closing parenthesis with no spaces between the two characters.

public function functionName(int $arg1, $arg2): string

https://www.php-fig.org/psr/psr-12/#45-method-and-function-arguments

Update: also seems to be in the Laravel preset, https://docs.styleci.io/presets#laravel

Is there a way to make 2 spaces in docblocks like in basic Laravel Skeleton?

@perifer I will review this and see if it belongs in this native ruleset.

@slavarazum, I think that's a tricky one. There are some settings for docblocks. But I couldn't lock it down just right. Let me know if you find anything.

@jasonmccreary
Also, haven't found appropriate rule, when setup ruleset for Laravel projects before...

https://laravel.com/docs/6.x/contributions#coding-style

Laravel follows PSR2 Standard, I think we can simplify this config by adding @PSR2 rule and remove all direct rules from it.

I would much prefer if it just did some basic PSR2, for those using their own linter like PHP_Code_Sniffer linting rules like simplified_null_return cause me nothing but hassle.

Yeah, I actually got bitten by the simplified_null_return too. Think I'll remove it as it's a risky rule anyway. 😅

@jasonmccreary Yeah that would be great 😄 , I don't expect you to support other linters but if I included an php_cs file with an empty rules array and without installing the php_cs_fixer package would that stop any lints from running in a shift? Or would you need me to have the package as a dependency

@dmason30, you're welcome to try. Can't guarantee Shift would be as accurate as some tasks still rely on a basic code style. Not many though. If you want to throw a dummy .php_cs file in your project, I'd recommend at least using the PSR-2 preset. It'd be a one-liner and likely give you the same results.

TBH, the fuss about Shift applying the Laravel code style has never made much sense to me. Shift does everything in atomic commits which can be ignored/reviewed/reverted easily. In addition, you can reapply your own code style before merging Shift's PR. So while I appreciate the "personal style" aspect, it's a painless "fix" compared to the overall upgrade process.

I have no real issue with it running the lint - it normally introduces me to rules that I end up adding to our custom configuration which means less changes are made each time we do a shift. I am happy with 99% of the changes it makes its just I feel I need to sanity check it each time because it includes risky changes and our custom linter handles reverting any non-risky changes where we need it too. When it changes 2000 files its a bit of a task to go through it.

TBH I am leaning towards having a tweaked version of this config in our projects and adding that to our linting step and using PHP_Code_Sniffer for some of the rules php_cs_fixer doesn't have.

Hi guys, I have been using this ruleset for many projects even without using laravel shift in these projects.

Inspired by this article, Sharing PHP-CS-Fixer rules across projects and teams, I have made this config into a package (WIP for now).

Wanted to ask:

• To anyone: Is this useful? At least it is for me now 😬....

• To @jasonmccreary:
  Is it ok to use this ruleset as an opensource package?
  Is it ok to use Laravel Shift name a few times in the readme?
  Is it ok to use the ShiftCS name as a namespace in this package?
  Is it ok to use the shift-php-cs name as the name of the package?

You can see the Work In Progress here... https://github.com/eduarguz/shift-php-cs

@eduarguz. Absolutely no problem. Any link to laravelshift.com in your readme would be appreciated.

Shouldn't be 'ordered_imports' => ['sortAlgorithm' => 'length'], for Laravel 🤔?

No, they changed it some versions ago.

I added 'php_unit_method_casing' => true to match laravel's test name style

A reminder this is the laravel/laravel code style, not necessary the framework style. There are very slight differences.

Furthermore, from my understanding, that's not a valid value. You should explicitly set case one way or the other.

@jasonmccreary good to know thanks.

I understood it as that the default, when set, is camel,
No harm in being explicit ['case' => 'camel_case'] 😀

Anyone has an idea of how to fix blade file styles.

I have an issue with one of the parameters when using optionnal parameters in routing with Dependancy Injection, for exemple :

this code is just for exemple purpose

Route::get('user/{name?}', function ($name = null, Request $request) {
    return $name;
});

is transform into :

Route::get('user/{name?}', function ($name, Request $request) {
    return $name;
});

passing 'no_unreachable_default_argument_value' => true, to 'no_unreachable_default_argument_value' => false, resolve this issue

@Arkhas I think you can swap the parameters order, this happens due to Laravel's magic parameter injection. Saw that somewhere but could not find the link :(

@Arkhas, the proper way to write that closure would be:

Route::get('user/{name?}', function (Request $request, $name = null) {
    return $name;
});

Per the rule that you noted, the way you have it has an "unreachable parameter" and technically incorrect from a PHP standpoint. You're relying on the magic dependency resolution of Laravel to allow that order. Which could change in the future.

@jasonmccreary are you using this setting in Shift production? Just wondering as tlint is using 1 space. Just trying to figure out which standard to use. tighten/tlint#194

'concat_space' => [
        'spacing' => 'none'
    ],

Thanks, Kevin

@delta1186, Laravel does not have a space between the concat operator.

This style file violates its own rules since it does not have trailing commas in many places.

@pmeth, cool.

Thanks so much @laravel-shift

@delta1186 +1
it should be like the following to be like Laravel shift.
@laravel-shift ?

'concat_space' => [
        'spacing' => 'one'
    ],

I think this one is better, because it just uses @PSR and removes a lot of direct rules.
https://github.com/stechstudio/Laravel-PHP-CS-Fixer/blob/master/config/fixer.php

I just created this 100% match of the current Laravel preset of StyleCI:
https://gist.github.com/wilmardo/800225d791610e3c332e885c42225839

The formatting is so that the linecount of the rules is exactly the same as the amount of lines in the StyleCI page, the order is exactly the same so a crossreference should be easy :)

@tainmar, again, Laravel does not use a space between the string concat operator at this time.

@wilmardo, nice. Unfortunately you hardcoded the $project_path. You should use relative paths to make is more sharable.

@jasonmccreary I know but Laravel Shift does use a space between the string concat operator. So all the Pull Requests from Laravel Shift are being made with a space and I therefore do have a lot of files changed only because of this rule, making the PR from Shift unreadable.

@tainmar, it should not. Please email Shift support with your Shift number and we can see what happened.

@jasonmccreary apologies. I in fact had an old .php_cs at the root of my project that shift used.

@wilmardo, nice. Unfortunately you hardcoded the $project_path. You should use relative paths to make is more sharable.

How would you go about it? Asking cause trying to use @wilmardo config.

@talelmishali I applied the suggestion in the current revision:

$project_path = getcwd();

https://gist.github.com/wilmardo/800225d791610e3c332e885c42225839#file-php-cs-dist-php-L128

@talelmishali I applied the suggestion in the current revision:

$project_path = getcwd();

https://gist.github.com/wilmardo/800225d791610e3c332e885c42225839#file-php-cs-dist-php-L128

Thanks!

Using phpdoc_to_comment transforms /** @var */ to /* @var */, this breaks static analysis tools like vscode-intelephense, larastan and others.

For example to correctly scope $this inside closures:

Blueprint::macro('identifier', function (string $column = 'id') {
    /** @var \Illuminate\Database\Schema\Blueprint $this */
    return $this->char($column, 32);
});

Two asterisks are required at the beginning of a comment. See nunomaduro/larastan#166 (comment)