woocommerce / woocommerce-sniffs

Collection of PHP_CodeSniffer sniffs for WooCommerce

WooCommerce Sniffs

Collection of PHP_CodeSniffer sniffs for WooCommerce.

Installation

composer require woocommerce/woocommerce-sniffs

Usage

Command line

./vendor/bin/phpcs --standard=WooCommerce-Core <file>

Config file

PHPCS config file:

<?xml version="1.0"?>
<ruleset name="WooCommerce Coding Standards">
	<description>My projects ruleset.</description>
	
	<!-- Configs -->
	<config name="minimum_supported_wp_version" value="4.7" />
	<config name="testVersion" value="7.2-" />

	<!-- Rules -->
	<rule ref="WooCommerce-Core" />

	<rule ref="WordPress.WP.I18n">
		<properties>
			<property name="text_domain" type="array" value="new-text-domain" />
		</properties>
	</rule>

	<rule ref="PHPCompatibility">
		<exclude-pattern>tests/</exclude-pattern>
	</rule>
</ruleset>

Changelog

See changelog for details

woocommerce-sniffs's Issues

Add Hook `@since` Validation

Right now our hook sniff only detects whether or not there is a @since tag. We should go a step further and also validate the version (support unknown or something too), as well as require a description. The validation for the description doesn't need to be robust; it just needs to make sure something is written after whitespace in the @since comment line.

Action Required: Fix Renovate Configuration

There is an error with this repository's Renovate configuration that needs to be fixed. As a precaution, Renovate will stop PRs until it is resolved.

Location: renovate.json
Error type: Invalid JSON (parsing failed)
Message: Syntax error: expecting end of expression or separator near "rang

Incompatibility with wp-coding-standards 3.0

our requirements could not be resolved to an installable set of packages.

  Problem 1
    - Root composer.json requires woocommerce/woocommerce-sniffs 0.1.3 -> satisfiable by woocommerce/woocommerce-sniffs[0.1.3].
    - woocommerce/woocommerce-sniffs 0.1.3 requires wp-coding-standards/wpcs ^2.3.0 -> found wp-coding-standards/wpcs[2.3.0] but it conflicts with your root composer.json require (^3.0).

Update WPCS to 2.0

@claudiosanches, what are your thoughts on updating the version of WPCS used in this repository to 2.0?

Fatal error: Uncaught TypeError: vsprintf()

Does this need a dependency update? I am seeing the following then trying to run the code checker sniffs:

PHP Fatal error: Uncaught TypeError: vsprintf(): Argument #2 ($values) must be of type array, string given in /home/helga/Sites/sandbox/wp-content/plugins/woocommerce-mix-and-match-products/vendor/squizlabs/php_codesniffer/src/Files/File.php:1056

using PHP 8.1.12 in Ubuntu

Create a rule encouraging the use of `wc_setcookie`

When setting cookies from within WooCommerce, we want to encourage devs to use our own wc_setcookie function (because that makes it easier to exercise control over the cookies we are setting, ie for GDPR reasons).

• I think we may have (or may inherit) a similar rule relating to wp_json_encode ... and this would be conceptually similar to that.
• Motivated by woocommerce/woocommerce#44116

Error message when @category is found

Right now the user will see the following message if the tag @category is found:

@category tags are prohibited

Should we change the message to suggest that @category can be replaced by @package?

Create sniff for hooks

We want to create a sniff to warn when hooks like do_action or apply_filters are used but without accompanying doc comments.

`WooCommerce.Commenting.CommentHooks.MissingSinceComment` should not throw an error if the hook is documented elsewhere in the codebase

In cases where a hook is fired in multiple different places in the codebase, it is a common convention to add the full doc block (including @since) in one of the places, and then in the other places just add a comment that looks something like this:

/** This filter is documented in includes/class-wc-logger.php. */

However, it does not appear that phpcs accounts for this, and is insisting that I add a @since tag to the above example.

Visual Studio Code (vscode) does not see WooCommerce-Core

Please provide an example of installation of the sniffs for Visual Studio Code.

I have installed them and defined in the workspace configuration but it shows an error: phpcs: The "WooCommerce-Core" coding standard is not installed. Please review your configuration an try again.

My composer.json file:

{
    "require-dev": {
        "wp-coding-standards/wpcs": "2.3.0",
        "squizlabs/php_codesniffer": "3.*"
    },
    "scripts": {
        "post-install-cmd": [
            "\"vendor/bin/phpcs\" --config-set installed_paths vendor/wp-coding-standards/wpcs"
        ],
        "post-update-cmd": [
            "\"vendor/bin/phpcs\" --config-set installed_paths vendor/wp-coding-standards/wpcs"
        ]
    },
    "require": {
        "woocommerce/woocommerce-sniffs": "^0.1.0"
    }
}

My project.code-workspace file:

{
	"folders": [
		{
			"path": "."
		}
	],
	"settings": {
		"phpcs.enable": true,
		"phpcs.standard": "WooCommerce-Core",
		"phpcs.executablePath": "vendor/bin/phpcs",
		"phpcs.showWarnings": true,
		"phpcs.composerJsonPath": "composer.json",
		"phpcs.errorSeverity": 5,
		"php.suggest.basic": true,
		"phpcs.lintOnType": false,
		"editor.insertSpaces": false
	}
}

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

This repository currently has no open or pending branches.

Detected dependencies

composer

composer.json

• php >=7.0
• wp-coding-standards/wpcs ^3.0.0
• dealerdirect/phpcodesniffer-composer-installer ^1.0.0
• phpcompatibility/phpcompatibility-wp ^2.1.0

---

• Check this box to trigger a request for Renovate to run again on this repository

Composer 2.2 "allow-plugins" config

I found out that Composer 2.2 introduces an allow-plugins setting, and without it composer install was failing...

{
    "config": {
        "allow-plugins": {
            "dealerdirect/phpcodesniffer-composer-installer": true
        }
    }
}

Some reference from the php code standards team (who obviously knows more than I do about this)

Consider making `:` count as a "full stop" for `Squiz.Commenting.FunctionComment.ParamCommentFullStop`

In the following doc block:

/**
 * Handle a log entry.
 *
 * @param int    $timestamp Log timestamp.
 * @param string $level     emergency|alert|critical|error|warning|notice|info|debug.
 * @param string $message   Log message.
 * @param array  $context   {
 *     Optional. Additional information for log handlers. Any data can be added here, but there are some array
 *     keys that have special behavior:
 *
 *     @type string $source    Determines which log file to write to. Must be at least 3 characters in length.
 *     @type bool   $backtrace True to include a backtrace that shows where the logging function got called.
 * }
 *
 * @return bool False if value was not handled and true if value was handled.
 */

The Squiz.Commenting.FunctionComment.ParamCommentFullStop rule gets triggered because of the colon on the $context param comment. This is fixable by switching it out for a ., but it might be nice to allow for colons in situations like this.

Upgrade composer requirements

wp-coding-standards/wpcs is now at ^2.3 and dealerdirect/phpcodesniffer-composer-installer is now at ^0.7, so WooCommerce-Core sniffs need to updated.