Skip to content

README.md

Latest commit

 

History

History
337 lines (263 loc) · 10.9 KB

README.md

File metadata and controls

337 lines (263 loc) · 10.9 KB

PHP_CodeSniffer usage

Table of Contents

Out of the box usage

  • It will check the code standards for the src and tests directories.
  • The --standard=vendor/kununu/code-tools/phpcs.xml flag is used to specify the coding standard to be used.
  • Applied rules are listed below in the Kununu Custom Rules section.

Analyze and detect violations

vendor/bin/phpcs --standard=vendor/kununu/code-tools/phpcs.xml src/ tests/

Automatically fix violations

vendor/bin/phpcbf --standard=vendor/kununu/code-tools/phpcs.xml src/ tests/

Optionally you can add it to your project's composer.json

{
    "scripts": {
        "cs-check": "phpcs --standard=vendor/kununu/code-tools/phpcs.xml src/ tests/",
        "cs-fix": "phpcbf --standard=vendor/kununu/code-tools/phpcs.xml src/ tests/"
    }
}

Customized usage

  • You can customize the phpcs.xml file to include/exclude directories, files, or rules.
  • You can create your own ruleset.xml file and use it with the --standard flag.
  • The easiest way to customize the rules is to copy the phpcs.xml file to your project and modify it, for this we provide the following command:
vendor/bin/code-tools publish:config code-sniffer
  • The phpcs.xml file will be copied to your project, and you can modify it to suit your needs.
See some customization examples

Example of a customized phpcs.xml to include only the Kununu.PHP.NoNewLineBeforeDeclareStrict rule:

<?xml version="1.0"?>
<ruleset name="Custom">
    <config name="installed_paths" value="../../kununu/code-tools"/>

    <arg name="basepath" value="."/>
    <arg name="colors"/>
    <arg name="parallel" value="75"/>
    <arg value="p"/>
    <arg value="n"/>

    <description>Custom coding standard</description>

    <file>src</file>
    <file>tests</file>

    <exclude-pattern>*/tests/.results/*</exclude-pattern>

    <!-- Include only NoNewLineBeforeDeclareStrict sniff -->
    <rule ref="Kununu.PHP.NoNewLineBeforeDeclareStrict"/>
</ruleset>

Example of a customized phpcs.xml to include all Kununu rules except the Kununu.Files.LineLength rule:

<?xml version="1.0"?>
<ruleset name="code-tools">
    <config name="installed_paths" value="../../kununu/code-tools"/>

    <file>src</file>
    <file>tests</file>

    <arg name="basepath" value="."/>
    <arg name="colors"/>
    <arg name="parallel" value="75"/>
    <arg value="p"/>
    <arg value="n"/>

    <!-- Include all Kununu rules except Kununu.Files.LineLength -->
    <rule ref="Kununu">
        <exclude name="Kununu.Files.LineLength"/>
    </rule>
</ruleset>

Example of a customized phpcs.xml to include all Kununu rules + rules from other standards:

<?xml version="1.0"?>
<ruleset name="code-tools">
    <config name="installed_paths" value="../../kununu/code-tools"/>

    <file>src</file>
    <file>tests</file>

    <arg name="basepath" value="."/>
    <arg name="colors"/>
    <arg name="parallel" value="75"/>
    <arg value="p"/>
    <arg value="n"/>

    <!-- Include all Kununu rules -->
    <rule ref="Kununu"/>
    
    <!-- Include PSR12 rules -->
    <rule ref="PSR12"/>
</ruleset>

Warning!!!
Be careful when including rules, as some rules may conflict with other rules or standards.

Analyze and detect violations

vendor/bin/phpcs --standard=phpcs.xml src/ tests/

Automatically fix violations

vendor/bin/phpcbf --standard=phpcs.xml src/ tests/

Optionally you can add it to your project's composer.json

{
    "scripts": {
        "cs-check": "phpcs --standard=phpcs.xml src/ tests/",
        "cs-fix": "phpcbf --standard=phpcs.xml src/ tests/"
    }
}

CI usage

  • Though this is optional, if you include this in your project, you can/should use it in your CI pipeline to enforce the code standards on every PR.
  • You can use the following GH action in your .github/workflows directory to run the code standards check on every PR:
Example of a GH action 
name: CI
on:
  pull_request:

jobs:
  cs:
    name: cs
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.3'
          coverage: none

      - name: Cache Composer dependencies
        uses: actions/cache@v4
        with:
          path: /tmp/composer-cache
          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
          restore-keys: ${{ runner.os }}-composer

      - name: Install composer dependencies
        uses: php-actions/composer@v6
        with:
          php_version: '8.3'
          version: 2
          args: --optimize-autoloader --no-progress --no-interaction
          ssh_key: ${{ secrets.CLONE_SSH_KEY }}
          ssh_key_pub: ${{ secrets.CLONE_SSH_KEY_PUB }}

      - name: Run code style sniffers
        run: vendor/bin/phpcs --standard=vendor/kununu/code-tools/phpcs.xml #adjust the path to your phpcs.xml file if needed

Kununu Custom Rules

Rule Name Is automatically fixable by phpcbf?
Kununu.Files.LineLength No
Kununu.Formatting.MethodSignatureArguments Yes
Kununu.PHP.NoNewLineBeforeDeclareStrict Yes

Kununu.Files.LineLength

Property Name Type Default
absoluteLineLimit int 120
ignoreComments bool false
lineLimit int 100
ignoreUseStatements bool false

This sniff extends Generic.Files.LineLength sniff to provide ability to ignore use statements when calculating line lengths.

If the ignoreUseStatements property is set to true, any use statements will be ignored when calculating line lengths.

Is automatically fixable by phpcbf: No

<rule ref="Kununu.Files.LineLength">
    <properties>
        <property name="ignoreUseStatements" value="true" />
    </properties>
</rule>

See more details about the extended Generic.Files.LineLength sniff here

See it in action
  • phpcs
  • kununu/code-tools
  • git diff
  • kununu/code-tools

Kununu.Formatting.MethodSignatureArguments

Property Name Type Default
methodSignatureLengthHardBreak int 120
methodSignatureLengthSoftBreak int 80
methodSignatureNumberParameterSoftBreak int 3

This sniff checks the method signature and prevents the usage of multiline for short method signatures and single lines for long ones.

methodSignatureLengthHardBreak: Maximum length for a single-line method signature.
methodSignatureLengthSoftBreak: Length threshold for considering a method signature to be multiline.
methodSignatureNumberParameterSoftBreak: Maximum number of parameters allowed on a single line

Is automatically fixable by phpcbf: Yes

<rule ref="Kununu.Formatting.MethodSignatureArguments">
    <properties>
        <property name="methodSignatureLengthSoftBreak" value="80" />
        <property name="methodSignatureLengthHardBreak" value="120" />
        <property name="methodSignatureNumberParameterSoftBreak" value="3" />
    </properties>
</rule>
See it in action
  • phpcs
  • kununu/code-tools
  • phpcbf
  • kununu/code-tools
  • git diff
  • kununu/code-tools

Kununu.PHP.NoNewLineBeforeDeclareStrict

Property Name Type Default
none - -

This sniff checks that there is no new line before the declare(strict_types=1); statement.

Is automatically fixable by phpcbf: Yes

<rule ref="Kununu.PHP.NoNewLineBeforeDeclareStrict" />
See it in action
  • phpcs
  • kununu/code-tools
  • phpcbf
  • kununu/code-tools
  • git diff
  • kununu/code-tools

Kununu.Classes.EmptyLineAfterClassElements

Property Name Type Default
none - -

This sniff checks that there is a new line after the last class constant and last class property.

Is automatically fixable by phpcbf: Yes

<rule ref="Kununu.Classes.EmptyLineAfterClassElements" />
See it in action
  • phpcs
  • kununu/code-tools
  • phpcbf
  • kununu/code-tools
  • git diff
  • kununu/code-tools

How to disable rules

  • You can disable a rule by adding the following comment to the line you want to disable the rule for:
// phpcs:disable Kununu.Files.LineLength
$someVariable = 'This is a very long string that will exceed the line length limit';
// phpcs:enable
  • You can disable rules for a folder, a file, a block of code or a line, and you can choose to disable just one rule or all rules. See offical documentation here