phpcs.xml.dist

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

	<!--
		Setup instructions:

		1) Install PHPCS (e.g., `brew install homebrew/php/php-code-sniffer`)
		2) Install the WP Coding Standards (https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards)
		3) Edit CodeSniffer.conf and update `installed_paths` to point to where you installed the WP Coding Standards,
		   and any other tweaks you want to make.
		   See https://github.com/iandunn/dotfiles/blob/master/phpcs/CodeSniffer.conf for an example.
		4) Make sure this file is at the project root. You can symlink it there if your `meta.(git|svn).wordpress.org`
		   checkout is elsewhere.
		5) `cd` to a folder inside the project and run `phpcs`. You can use the `-a` flag to run it interactively.
		6) Run it before you generate a patch or create a commit. Setting up a git pre-commit or pre-push hook can
		   make that automatic.

		Note: It's possible to create a `phpcs.xml` file if you want to override anything here, but please make sure
		any code you contribute conforms to this file. If you think any of the rules here should change, start a
		discussion in #meta-wordcamp.

		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
	-->

	<!-- TODO
		Exclude 3rd party plugins/themes so this can be run from the project root without a ton of extraneous stuff
		<exclude-pattern>/build/*</exclude-pattern>

		disable WordPress.VIP.PostsPerPage.posts_per_page_posts_per_page for bin folder only
			should that be `WordPress.VIP.PostsPerPage.posts_per_page` ?

		Look through `General` and `Squiz` sniffs for anything you might want to add.
			Is there one that detects `\Foo` instead of `use Foo`?
			maximum nesting level?
			function length?
			unnecessary order-of-operations params, e.g., $foo = ( $bar || $qax ) ? 'bax' : 'quix';
			echoing html instead of breaking php or using an external view. e.g., echo '<div>foo</div>'; should be `?> <div>foo</div> <?php` (but on multiple lines of course)
			heredoc/nowdoc should never be used
			var assignment immediately followed by if/while/for statement, without a blank space inbetween. maybe not in all cases, though?
			closing divs with a comment after them. it adds clutter. when viewing source, this is an artifact from the days before browser dev tools. view in IDEs, this isn't necessary if the code is properly formatted.
			return statement at end of function w/out blank line above it
			no space between last @param and the @return in docblock. i know diff than core, but whitespace makes it easier to scan/read. should also have space above first @param. sometimes want no space between different types of tags, though.
			opening/closing <?php ?> tags without a blank line after/before them, except when doing single-line like <?php foo(); ?>
			align ? and : in multiple ternary operator statements
			don't un-align params in function calls - e.g., multiple add_meta_box( $a, $b, $c, $d, $e, $f, $g ) calls should have the params aligned.
			file missing `defined WPINC or die` at start
			don't add `@return void`, just leave return empty
			no space before ++,etc operators: e.g., `$attempt_count ++;`
			replace explicit references to central.wordcamp.org / ID `5` with `is_main_site()` or `get_main_site_id()`
			anonymous functions used with add_(action|filter), and maybe other places can detect w/out false positives. don't be lazy. should only be used with cases like array_filter.
			whitespace-only changes to lines that don't have logic changes, in a commit that does have logic changes. this indicates that a commit is mixing coding standards changes w/ logic changes, which adds diff noise to the logic change. they should be separate commits.
			unnecessary parenthesis in ternary conditions: $result = ( $condition ) ? 'foo' : 'bar'

		Maybe add WordCamp\Remote_CSS\output_cached_css and wcorg_json_encode_attr_i18n to customEscapingFunctions or whichever param is most appropriate
		Maybe do something similar for set_cache_headers and nonce verification

		Setup WordPress.WP.I18n text_domain property and test that it works, see https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/wiki/Customizable-sniff-properties#internationalization-setting-your-text-domain

		Don't add @package phpDoc? Clutters code without adding any real value. You know what "package" the file is part of because of the folder it's in; e.g., wp-content/plugins/wordcamp-payments

		Don't mush HTML elements together on the same line, unless it's really short. `<h1>The title</h1>` is ok, but `<h1><?php echo esc_html( get_the_title() ); ?></h1>` should have the h1 tags on separate lines.

		wp_enqueue_*() cachebusters should use filemtime() rather than a hardcoded int.

		Combine similar `use` statements on the same line. Like, all the core PHP objects, then all the WP objects on the 2nd line, then our custom objects on the 3rd line, etc.

		Prevent blank lines at start of function/class
	-->

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

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

	<!-- 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" />

		<!-- Workaround for https://github.com/WordPress/WordPress-Coding-Standards/issues/1244 -->
		<exclude name="WordPress.WP.DeprecatedFunctions.get_settingsFound" />

		<!-- 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" />

		<!--
		 ... 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>
				<property name="alignMultilineItems" value="!=100"/>
			</properties>
		</rule>

		<!-- @todo This is temporary until the above version works. -->
		<exclude name="WordPress.Arrays.MultipleStatementAlignment.DoubleArrowNotAligned" />

		<!-- 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" />

		<!-- The <?php and ?> tags can't be on a line by itself inside a <textarea>, otherwise it'll add whitespace to the content. -->
		<exclude name="Squiz.PHP.EmbeddedPhp.ContentBeforeOpen" />
		<exclude name="Squiz.PHP.EmbeddedPhp.ContentAfterEnd"   />

		<!-- 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" />
	</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>
</ruleset>