Code Style - v1.1.0

Customization Guide

This guide explains how to customize the ArtisanPack UI Code Standards to better fit your project's specific needs.

Customizing Sniffs in phpcs.xml

You can customize the behavior of individual sniffs by setting properties in your phpcs.xml file. This allows you to adjust the standard without modifying the package itself.

Basic Customization

Here's an example of how to customize the indentation sniff to use 2 spaces instead of tabs:

<?xml version="1.0"?>
<ruleset name="YourProjectStandard">
    <description>Your project's coding standard</description>

    <!-- Use ArtisanPackUI standard -->
    <rule ref="ArtisanPackUIStandard"/>

    <!-- Customize indentation -->
    <rule ref="ArtisanPackUI.Formatting.Indentation">
        <properties>
            <property name="indent" value="2"/>
            <property name="tabIndent" value="false"/>
        </properties>
    </rule>

    <!-- Specify paths to check -->
    <file>app</file>
    <file>src</file>
    <file>tests</file>

    <!-- Exclude paths -->
    <exclude-pattern>*/vendor/*</exclude-pattern>
    <exclude-pattern>*/node_modules/*</exclude-pattern>
</ruleset>

Common Customization Options

Here are some common properties you can customize for various sniffs:

Indentation

<rule ref="ArtisanPackUI.Formatting.Indentation">
    <properties>
        <!-- Number of spaces for indentation (if not using tabs) -->
        <property name="indent" value="4"/>

        <!-- Whether to use tabs (true) or spaces (false) for indentation -->
        <property name="tabIndent" value="true"/>
    </properties>
</rule>

LineLength

Note: The LineLength sniff has been disabled in the standard ruleset. The following customization options are no longer applicable unless you explicitly re-enable the sniff.

<!-- This sniff is disabled by default -->
<rule ref="ArtisanPackUI.Formatting.LineLength">
    <properties>
        <!-- Maximum line length -->
        <property name="lineLimit" value="120"/>

        <!-- Maximum line length for comments -->
        <property name="commentLineLimit" value="120"/>

        <!-- Number of spaces to replace a tab with when measuring line length -->
        <property name="tabWidth" value="4"/>

        <!-- Whether to ignore comment lines completely -->
        <property name="ignoreComments" value="false"/>

        <!-- Whether to show warnings (true) or errors (false) for long lines -->
        <property name="warnOnly" value="true"/>
    </properties>
</rule>

Braces

<rule ref="ArtisanPackUI.Formatting.Braces">
    <properties>
        <!-- Whether to require braces on the same line as the declaration -->
        <property name="sameLine" value="true"/>
    </properties>
</rule>

Spacing

<rule ref="ArtisanPackUI.Formatting.Spacing">
    <properties>
        <!-- Number of spaces around operators -->
        <property name="operatorSpacing" value="1"/>

        <!-- Whether to require spaces inside parentheses -->
        <property name="spaceInsideParentheses" value="true"/>
    </properties>
</rule>

YodaConditionals

<rule ref="ArtisanPackUI.Formatting.YodaConditionals">
    <properties>
        <!-- Whether to enforce Yoda conditionals -->
        <property name="enforce" value="true"/>
    </properties>
</rule>

Excluding Sniffs

If you want to use the ArtisanPackUI standard but exclude specific sniffs, you can do so in your phpcs.xml file:

<?xml version="1.0"?>
<ruleset name="YourProjectStandard">
    <description>Your project's coding standard</description>

    <!-- Use ArtisanPackUI standard -->
    <rule ref="ArtisanPackUIStandard">
        <!-- Exclude specific sniffs -->
        <exclude name="ArtisanPackUI.Formatting.YodaConditionals"/>
        <exclude name="ArtisanPackUI.Formatting.MagicMethods"/>
    </rule>

    <!-- Specify paths to check -->
    <file>app</file>
    <file>src</file>
    <file>tests</file>

    <!-- Exclude paths -->
    <exclude-pattern>*/vendor/*</exclude-pattern>
    <exclude-pattern>*/node_modules/*</exclude-pattern>
</ruleset>

Excluding Files or Directories

You can exclude specific files or directories from being checked:

<?xml version="1.0"?>
<ruleset name="YourProjectStandard">
    <description>Your project's coding standard</description>

    <!-- Use ArtisanPackUI standard -->
    <rule ref="ArtisanPackUIStandard"/>

    <!-- Specify paths to check -->
    <file>app</file>
    <file>src</file>
    <file>tests</file>

    <!-- Exclude paths -->
    <exclude-pattern>*/vendor/*</exclude-pattern>
    <exclude-pattern>*/node_modules/*</exclude-pattern>
    <exclude-pattern>app/Legacy/*</exclude-pattern>
    <exclude-pattern>src/ThirdParty/*</exclude-pattern>
</ruleset>

Creating a Custom Ruleset

For more advanced customization, you can create your own ruleset that extends the ArtisanPackUI standard:

Create a file named MyStandard/ruleset.xml in your project:

<?xml version="1.0"?>
<ruleset name="MyStandard">
    <description>My custom coding standard based on ArtisanPackUI</description>

    <!-- Include ArtisanPackUI standard -->
    <rule ref="ArtisanPackUIStandard">
        <!-- Exclude any sniffs you don't want -->
        <exclude name="ArtisanPackUI.Formatting.YodaConditionals"/>
    </rule>

    <!-- Add your own custom rules or include other standards -->
    <rule ref="PSR12.Classes.ClassDeclaration"/>
</ruleset>

Use your custom standard in your phpcs.xml file:

<?xml version="1.0"?>
<ruleset name="YourProjectStandard">
    <description>Your project's coding standard</description>

    <!-- Use your custom standard -->
    <rule ref="MyStandard"/>

    <!-- Specify paths to check -->
    <file>app</file>
    <file>src</file>
    <file>tests</file>

    <!-- Exclude paths -->
    <exclude-pattern>*/vendor/*</exclude-pattern>
    <exclude-pattern>*/node_modules/*</exclude-pattern>
</ruleset>

Troubleshooting

If you encounter issues with your customizations:

Run PHP_CodeSniffer with the -v flag to see more detailed output:

./vendor/bin/phpcs -v

Check that your XML syntax is correct.
Ensure that the properties you're trying to customize actually exist in the sniff.

For more help, refer to the PHP_CodeSniffer documentation.