five-for-the-future/phpcs.xml.dist

<?xml version="1.0" ?>
<ruleset name="WordCamp.org Coding Standards">
	<description>Apply customized version of WordPress Coding Standards to WordCamp.org projects.</description>

	<!--
		Setup instructions:

		1) Install PHPCS & all required code standards using `composer install`
		2) Run `composer run phpcs`. You can use the `-a` flag to run it interactively.

		See these links for useful information:
			- https://github.com/squizlabs/PHP_CodeSniffer/wiki/Annotated-ruleset.xml
			- https://github.com/squizlabs/PHP_CodeSniffer/wiki/Customisable-Sniff-Properties
			- https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/wiki/Customizable-sniff-properties
	-->

	<!-- Exclude 3rd-party files -->
	<exclude-pattern>*/vendor/*</exclude-pattern>
	<exclude-pattern>*/node_modules/*</exclude-pattern>

	<!-- Exclude the wporg parent theme (for this project) -->
	<exclude-pattern>/themes/pub/wporg</exclude-pattern>

	<!-- Exclude all plugins except our pledge plugin -->
	<exclude-pattern>/plugins/(?!wporg-5ftf)</exclude-pattern>

	<!-- Show sniff codes in all reports -->
	<arg value="ps" />
	<arg name="colors" />

	<!-- Scan all (php) files in the current folder and subfolders -->
	<file>.</file>
	<arg name="extensions" value="php" />

	<rule ref="WordPress-Core">
		<!-- I don't see anything wrong with this :) -->
		<exclude name="Squiz.PHP.EmbeddedPhp.ContentAfterOpen" />
		<exclude name="Squiz.PHP.EmbeddedPhp.ContentBeforeEnd" />

		<!-- I've never heard a compelling argument for this, and it clutters the directory listing with irrelevant noise. -->
		<exclude name="WordPress.Files.FileName.InvalidClassFileName" />

		<!-- It's often obvious what the placeholder is, so whether or not to include a comment is a judgement call. -->
		<exclude name="WordPress.WP.I18n.MissingTranslatorsComment" />

		<!-- I know it's a language construct, but it just looks better using the function call syntax. -->
		<exclude name="PEAR.Files.IncludingFile.BracketsNotRequired" />

		<!-- This requires passing a whitelist of prefixes in order to work, which is not practical for a large and varied codebase. It's also fixes a problem that we're unlikely to cause. -->
		<exclude name="WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedConstantFound" />
		<exclude name="WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedVariableFound" />
		<exclude name="WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound" />

		<!-- Aligning things make the code more readable. `Generic.WhiteSpace.DisallowSpaceIndent` will catch accidental uses of all spaces. -->
		<exclude name="WordPress.WhiteSpace.PrecisionAlignment.Found" />
		<exclude name="Generic.Functions.FunctionCallArgumentSpacing.TooMuchSpaceAfterComma" />
		<exclude name="WordPress.WhiteSpace.OperatorSpacing.SpacingBefore" />
		<exclude name="WordPress.Arrays.ArrayDeclarationSpacing.SpaceBeforeArrayCloser" />
		<exclude name="PEAR.Functions.FunctionCallSignature.SpaceBeforeCloseBracket" />
		<exclude name="PEAR.Functions.FunctionCallSignature.SpaceAfterOpenBracket" />
		<exclude name="Squiz.Strings.ConcatenationSpacing.PaddingFound" />

		<!-- There are cases where having multiple items on a single line is appropriate. e.g., a list of 100 currency codes. -->
		<exclude name="WordPress.Arrays.ArrayDeclarationSpacing.ArrayItemNoNewLine" />
		<exclude name="PEAR.Functions.FunctionCallSignature.ContentAfterOpenBracket" />
		<exclude name="PEAR.Functions.FunctionCallSignature.CloseBracketLine" />
		<exclude name="PEAR.Functions.FunctionCallSignature.MultipleArguments" />

		<!--
		 ... In multidimensional arrays, items in the child arrays should be aligned, but the parent arrays should
		 ... not be aligned, since they are not on neighboring lines.
		 ...
		 ... @todo This isn't working, see `WordCamp\Blocks\Sessions\get_attributes_schema()`.
		 ... @see https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/issues/1565
		 -->
		<rule ref="WordPress.Arrays.MultipleStatementAlignment">
			<properties>
				<!-- Don't align multi-line items if ALL items in the array are multi-line. -->
				<property name="alignMultilineItems" value="!=100"/>
				<!-- Array assignment operator should always be on the same line as the array key. -->
				<property name="ignoreNewlines" value="false"/>
			</properties>
		</rule>

		<!-- Warn about mis-aligned array items, but don't automatically "fix" them, because arrays in function calls get extra lines added.
		     See https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/issues/1305 -->
		<exclude phpcbf-only="true" name="PEAR.Functions.FunctionCallSignature" />

		<!-- trigger_error() isn't only development function. In development environments it conveniently displays an error, but in
		     (properly configured) production environment, it logs the error instead. -->
		<exclude name="WordPress.PHP.DevelopmentFunctions.error_log_trigger_error" />

		<!-- print_r() is perfectly accepted in some circumstances, like WP_CLI commands. -->
		<exclude name="WordPress.PHP.DevelopmentFunctions.error_log_print_r" />

		<!-- Exclude short array syntax as it is consistently already in the codebase :) -->
		<exclude name="Generic.Arrays.DisallowShortArraySyntax"/>
		<exclude name="Universal.Arrays.DisallowShortArraySyntax"/>
	</rule>

	<!-- Ignore the CPT template filename, since it is based on the CPT name, and can't change. -->
	<rule ref="WordPress.Files.FileName.NotHyphenatedLowercase">
		<exclude-pattern>*/template-parts/content-5ftf_pledge.php$</exclude-pattern>
		<exclude-pattern>*/archive-5ftf_pledge.php$</exclude-pattern>
		<exclude-pattern>*/single-5ftf_pledge.php$</exclude-pattern>
	</rule>

	<rule ref="WordPress-Docs">
		<!-- If files/variables are given descriptive names like they should be, then an explicit description is usually unnecessary, so leave this as a judgement call. -->
		<exclude name="Squiz.Commenting.FunctionComment.MissingParamComment" />
		<exclude name="Squiz.Commenting.FileComment.Missing" />
		<exclude name="Squiz.Commenting.ClassComment.Missing" />
		<exclude name="Squiz.Commenting.FunctionComment.MissingParamTag" />
		<exclude name="Generic.Commenting.DocComment.MissingShort" />
		<exclude name="Squiz.Commenting.VariableComment.Missing" />
		<exclude name="Squiz.Commenting.VariableComment.MissingVar" />

		<!-- I don't see how these are useful. -->
		<exclude name="Squiz.Commenting.FileComment.MissingPackageTag" />

		<!-- We really only use basic exceptions, so this is kind of overkill and tedious. -->
		<exclude name="Squiz.Commenting.FunctionComment.EmptyThrows" />

		<!-- Whitespace makes things more readable. -->
		<exclude name="Squiz.Commenting.FileComment.SpacingAfterOpen" />

		<!-- There are some valid cases of this, like in identifying a closing tag from another file; e.g., in `themes/campsite-2017/footer.php`. -->
		<exclude name="Squiz.Commenting.InlineComment.SpacingAfter" />

		<!-- It's not wrong for WordPress plugin file headers. -->
		<exclude name="Squiz.Commenting.FileComment.WrongStyle" />

		<!-- Class comments are generally not useful, so they're left out, but then PHPCS confuses the plugin headers for a class comment -->
		<exclude name="Squiz.Commenting.ClassComment.WrongStyle" />
		<exclude name="Squiz.Commenting.ClassComment.SpacingAfter" />

		<!-- WordPress have translators comment which requires no space after `//` -->
		<exclude name="Squiz.Commenting.InlineComment.NoSpaceBefore" />
	</rule>

	<rule ref="WordPress-Extra">
		<!-- I think it's better to have all the `use` statements come right after the namespace line. -->
		<exclude name="PSR2.Namespaces.NamespaceDeclaration.BlankLineAfter" />
	</rule>
	
	<!-- Verify that the text_domain is set to the desired text-domain. Multiple valid text domains can be
	     provided as a comma-delimited list. -->
	<rule ref="WordPress.WP.I18n">
		<properties>
			<property name="text_domain" type="array" value="wporg-5ftf" />
		</properties>
	</rule>
</ruleset>