Skip to content

About

Worksomes coding style

Topics

Resources

Stars

49 stars

Watchers

15 watching

Forks

Repository files navigation

Worksome Coding Style

Latest Stable Version Total Downloads Latest Unstable Version License

This repository contains the coding style followed by Worksome.

It includes configuration for ECS, PHPStan, and Rector.

Setup

Install this Composer package:

composer require --dev worksome/coding-style

Run the generate command for generating the config files:

composer generate-coding-style-stubs

Add the following section to your composer.json file:

"scripts": {
    "ecs": "vendor/bin/ecs",
    "ecs:fix": "vendor/bin/ecs --fix",
    "phpstan": "vendor/bin/phpstan analyse",
    "rector": "vendor/bin/rector process --dry-run --ansi",
    "rector:fix": "vendor/bin/rector process --ansi"
},

PHPStan

PHPStan extensions are registered via phpstan/extension-installer, which is installed alongside this package. Allow the plugin when prompted by Composer, or add it to your composer.json file:

"config": {
    "allow-plugins": {
        "phpstan/extension-installer": true
    }
}

The Worksome rules, along with the PHPStan extensions this package depends on, are then loaded automatically.

Laravel projects should also install Larastan and the Larastan strict rules:

composer require --dev larastan/larastan canvural/larastan-strict-rules

The Laravel rules (and Larastan within the Rector config) are only loaded when Larastan is installed, and the strict rules are only loaded when both packages are installed. Packages listed in the extension installer's ignore option are treated as not installed.

Note: Do not include the configuration files of any PHPStan extension that is registered with the extension installer (e.g. vendor/larastan/larastan/extension.neon or vendor/worksome/coding-style/larastan.neon) in your phpstan.neon file. PHPStan will fail if a file is included more than once.

Usage

To use it, simply run one of the scripts added to composer.

$ composer ecs
$ composer ecs:fix
$ composer phpstan
$ composer rector
$ composer rector:fix

ECS Rules

The Worksome code style extends the PSR-12 base rule set.

Additional / Customised Rules

Note: Customised rules have a ⚙️ icon.

Custom PHPStan rules

The Worksome code style includes the following custom PHPStan rules.

Generic

Rules that are applied to all projects.

Identifier: worksome.declareStrictTypes

This rule is used to ensure that all PHP files include with the declare(strict_types=1) statement.

Identifier: worksome.disallowTodoComments

This rule prevents to-do comments (containing the word TODO or TODOs, in any case) from being used. Jira should be used instead.

Identifier: worksome.disallowPhpunit

This rule prevents PHPUnit tests in favour of Pest PHP. It will allow abstract TestCase classes.

Identifier: worksome.exceptionSuffix

This rule ensures that all named classes implementing Throwable have an Exception suffix. Subclasses of Error may use an Error suffix instead (e.g. InvalidStateError). Anonymous classes are not checked, and the suffixes are not configurable.

Identifier: worksome.namespaceBasedSuffix

Sets up configuration for suffixing the following namespaces

  • App\Events: Event
  • App\Listeners: Listener
  • App\Policies: Policy
  • App\Jobs: Job

This makes sures events, listeners, policies and jobs has the same suffix.

Namespaces are matched by prefix, so applications with a root namespace other than App need their own entries in the namespaceAndSuffix parameter (e.g. Acme\Listeners: Listener).

Identifier: worksome.pascalCaseEnumCases

This rule ensures that all enum cases use pascal-casing (e.g. Case::PascalCase).

Laravel

Rules that are only applied in a Laravel context.

Identifier: worksome.laravel.configFilenameKebabCase

This rule ensures that all config files are named in kebab-case (lowercase letters and numbers, separated by hyphens). It only applies when the config directory is included in your PHPStan paths.

Identifier: worksome.laravel.disallowBladeOutsideOfResourcesDirectory

This rule ensures that no .blade.php files are placed outside of Laravel's resources directory. Only files within your PHPStan paths are checked, so a Blade file outside of them is not reported. The directory can be changed with the bladeResourcesDirectory parameter (defaults to %currentWorkingDirectory%/resources).

Identifier: worksome.laravel.disallowEnvironmentCheck

This rule will prevent checking the application environment, instead preferring that a driver based approach is used.

Identifier: worksome.laravel.kebabCaseArtisanCommands

This rule will enforce the use of kebab-case for Artisan commands.

Identifier: worksome.laravel.requireWithoutTimestamps

This rule enforces that all update, insert, save, saveQuietly, delete, restore, method calls within Laravel migration files are properly enclosed in a withoutTimestamps() context.

Third-party rules

The following are enabled through configuration of third-party rules:

  • Disallow env usage — Larastan's noEnvCallsOutsideOfConfig rule (identifier larastan.noEnvCallsOutsideOfConfig) ensures env() is only called in config files.
  • Disallow HasFactory usage — disallowedClasses ensures the HasFactory trait is not used, so that factory classes are called directly.

Custom PHP CS Fixer fixers

The Worksome code style includes the following custom PHP CS Fixer fixers, which are applied via ECS.

Makes sure that you always have a dollar sign in your properties defined in phpdoc.

/**
 * @property string $name
 */
class User {}

This removes all @param tags which has not specified a type or comment.

/**
 * @param string $name
 * @param $type some random type
 * @param $other
 */
public function someMethod($name, $type, $other): void
{}

In the example above, the @param $other tag will be removed.

This is mainly because PHPStan requires this before it sees the property as valid.

This ensures that generics types in PHPDoc comments contain a single space after the comma.

Custom Rector rules

The Worksome code style includes custom Rector rules for automatically refactoring code.

Generic

This ensures that specified PHP attributes are automatically removed when they are not allowed.

Replaces compact() calls with an explicit array, as part of the generic code quality set. Calls with variable names that cannot be resolved statically are left unchanged.

Credits

About

Worksomes coding style

Topics

Resources

Stars

49 stars

Watchers

15 watching

Forks

Releases

Packages

Used by

Contributors

Languages