phpcs.xml.dist

<?xml version="1.0"?>
<ruleset name="OpenStation">
	<description>Coding standards for the OpenStation plugin.</description>

	<!--
		Files this ruleset applies to. Extensions live in this monorepo
		for development convenience but ship as separate WordPress
		plugins; they're scanned independently against their own ruleset
		and excluded here so their text-domains and prefixes don't trip
		the parent-plugin scan.
	-->
	<file>.</file>
	<exclude-pattern>/extensions/</exclude-pattern>
	<exclude-pattern>/node_modules/</exclude-pattern>
	<exclude-pattern>/vendor/</exclude-pattern>
	<exclude-pattern>/dist/</exclude-pattern>
	<exclude-pattern>/assets/vendor/</exclude-pattern>
	<exclude-pattern>/tests/</exclude-pattern>
	<exclude-pattern>/.scratch/</exclude-pattern>
	<!--
		Agent worktrees. A checkout under `.claude/worktrees/` holds a
		COPY of the repo at some other revision — often pre-rename code
		that has since been fixed on trunk. Scanning it makes a local,
		throwaway directory able to fail a CI gate about the real source
		(observed: 5,368 errors, none of them in the repo proper), and
		makes the gate's result depend on what happens to be checked out
		next to it.
	-->
	<exclude-pattern>/.claude/</exclude-pattern>
	<!-- House sniff sources — PHPCS-convention code, not plugin code. -->
	<exclude-pattern>/tools/phpcs/</exclude-pattern>

	<!--
		PHP only.

		Without this, PHPCS applies its CSS and JS sniffs to everything
		under `assets/`. On a fresh clone that is invisible — the built
		bundles are gitignored — but on any checkout where `npm run build`
		has run it walks ~70 minified IIFEs, reports several hundred
		thousand violations and exhausts a 1GB memory limit before it can
		finish. The stylesheets are covered by the editorconfig; the
		bundles are build output and are nobody's to hand-edit.
	-->
	<arg name="extensions" value="php"/>

	<!-- Readable local runs; `-q` in CI keeps the log short. -->
	<arg name="basepath" value="."/>
	<arg name="colors"/>
	<arg name="parallel" value="8"/>
	<arg value="sp"/>

	<!-- Inherit the WordPress plugin standard. -->
	<rule ref="WordPress"/>

	<!--
		Custom prefix allowlist.

		The Plugin Check derives the canonical prefix from the plugin
		slug, which stays `desktop-mode` — that is the WordPress.org
		directory and the plugin's update path, so it cannot change.
		The code is prefixed for the brand instead, hence the explicit
		list: `openstation_*` / `OPENSTATION_*` for the plugin itself
		(one word, like `wordpress_` rather than `word_press_`), plus
		the `wpdc` / `wpdm` namespaces the bundled phpMyAdmin and
		cron-manager extensions keep — their window ids are persisted
		and their prebuilt bundles hardcode the selectors.
	-->
	<rule ref="WordPress.NamingConventions.PrefixAllGlobals">
		<properties>
			<property name="prefixes" type="array">
				<element value="openstation"/>
				<element value="OPENSTATION"/>
				<element value="wpdc"/>
				<element value="wpdm"/>
			</property>
		</properties>
	</rule>

	<!--
		`bin/` holds standalone CLI scripts run as `php bin/<script>.php`,
		not plugin runtime. PHPCS reads their top-level variables as
		globals, so every local in a procedural script trips the prefix
		rule and `$locale` / `$domain` read as clobbering WordPress's own
		globals. Neither is true — nothing there is ever loaded into a
		WordPress request. The rest of the standard still applies.
	-->
	<rule ref="WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedVariableFound">
		<exclude-pattern>/bin/</exclude-pattern>
	</rule>
	<rule ref="WordPress.WP.GlobalVariablesOverride">
		<exclude-pattern>/bin/</exclude-pattern>
	</rule>

	<!--
		Properties on PHP's own classes. `ZipArchive::$numFiles` and the
		DOM node interface are camelCase because PHP declares them that
		way; we only read them.
	-->
	<rule ref="WordPress.NamingConventions.ValidVariableName">
		<properties>
			<property name="allowed_custom_properties" type="array">
				<element value="numFiles"/>
				<element value="documentElement"/>
				<element value="childNodes"/>
				<element value="nodeType"/>
				<element value="nodeName"/>
				<element value="nodeValue"/>
				<element value="localName"/>
			</property>
		</properties>
	</rule>

	<!--
		Text domain consistency. Stays `desktop-mode`: WordPress.org
		delivers language packs keyed on the directory slug, so the
		domain has to keep matching it even though the brand changed.
	-->
	<rule ref="WordPress.WP.I18n">
		<properties>
			<property name="text_domain" type="array">
				<element value="desktop-mode"/>
			</property>
		</properties>
	</rule>

	<!--
		Advisory, not blocking.

		CI gates on errors (`phpcs -n`), so everything below still reports
		on a full local run and still shows up in review, but a violation
		does not fail the build. Each one is a case where the sniff is
		measuring something real that this codebase answers differently,
		and where silencing it outright would throw away the signal.
	-->

	<!--
		Custom tables. The plugin owns eight of them (see AGENTS.md,
		"`desktop_mode_*` values are frozen"); `$wpdb` is the only way to
		reach them, and `WP_Query` has no bearing on a placements or
		shares lookup. The aggregate stats under `includes/my-wordpress/`
		do read core tables directly, and there the caching advice is
		worth keeping visible — hence warning rather than excluded.
	-->
	<rule ref="WordPress.DB.DirectDatabaseQuery">
		<type>warning</type>
	</rule>

	<!--
		Table names cannot be placeholders below WordPress 6.2, which
		introduced `%i`. The plugin supports 6.0, so every custom-table
		query interpolates `{$tables['…']}` into the SQL and passes the
		values through `prepare()`. The other interpolations flagged here
		are `implode( ',', array_fill( …, '%d' ) )` placeholder lists and
		`$charset_collate` on CREATE TABLE — all structural, none of them
		user input. Revisit if the minimum ever moves to 6.2.
	-->
	<rule ref="WordPress.DB.PreparedSQL.InterpolatedNotPrepared">
		<type>warning</type>
	</rule>

	<!--
		Docblock coverage. 1186 of the 1248 functions under `includes/`
		carry one, so the standard matches the house style and the gap is
		a tail to close rather than a convention to abandon — but closing
		it is its own piece of work, and holding CI red until then would
		just teach everyone to ignore the job.

		`InvalidEndChar` and `MissingParamComment` are excluded outright:
		this codebase writes long explanatory prose comments that
		deliberately do not terminate in a full stop, and re-punctuating
		them would be churn for its own sake.
	-->
	<rule ref="Squiz.Commenting.FunctionComment.Missing">
		<type>warning</type>
	</rule>
	<rule ref="Squiz.Commenting.FunctionComment.MissingParamTag">
		<type>warning</type>
	</rule>
	<rule ref="Squiz.Commenting.FunctionComment.MissingParamName">
		<type>warning</type>
	</rule>
	<rule ref="Squiz.Commenting.FileComment">
		<type>warning</type>
	</rule>
	<rule ref="Generic.Commenting.DocComment.MissingShort">
		<type>warning</type>
	</rule>
	<rule ref="Squiz.Commenting.FunctionComment.MissingParamComment">
		<severity>0</severity>
	</rule>
	<rule ref="Squiz.Commenting.FunctionComment.ParamCommentFullStop">
		<severity>0</severity>
	</rule>
	<rule ref="Squiz.Commenting.InlineComment.InvalidEndChar">
		<severity>0</severity>
	</rule>

	<!--
		App Framework template helpers. `.os.php` views are host-
		agnostic, so they escape with `OpenStation\App\Html\esc()` /
		`json()` / `attr()` rather than `esc_html()`, and build markup
		with `tag()`, which escapes every attribute it emits. Naming
		them here lets the output-escaping sniff recognise them.
	-->
	<rule ref="WordPress.Security.EscapeOutput">
		<properties>
			<property name="customEscapingFunctions" type="array">
				<element value="esc"/>
				<element value="json"/>
				<element value="attr"/>
			</property>
			<property name="customAutoEscapedFunctions" type="array">
				<element value="tag"/>
			</property>
		</properties>
	</rule>

	<!--
		`.os.php` is the App Framework's file format (an app file is a
		PHP file that returns an App). The extra dot is the format's
		signature, not a naming slip.
	-->
	<rule ref="WordPress.Files.FileName.NotHyphenatedLowercase">
		<exclude-pattern>*.os.php</exclude-pattern>
	</rule>

	<!-- PHP / WP version targets — match plugin headers. -->
	<config name="testVersion" value="7.4-"/>
	<config name="minimum_supported_wp_version" value="6.0"/>

	<!--
		House sniffs, from `tools/phpcs/` (the directory itself is
		excluded from scanning above — sniff sources follow PHPCS's own
		conventions, not WordPress's).

		`OpenStation.Files.FileLength` is a WARNING by design: past
		1,000 lines a file gets one encouraging nudge to split toward
		the 300–600-line comfort zone. `phpcs -n` (the default gate)
		hides it; `npm run lint:php:all` and editors show it. Twin rule
		for TypeScript: `local-rules/os-file-length` in `.eslintrc.cjs`.
	-->
	<!--
		`installed_paths` here REPLACES the value Composer's phpcs
		installer wrote into vendor (it does not append), so the
		vendor standards must be restated alongside our own directory.
		Keep this list in step with `CodeSniffer.conf`'s when a new
		standards package lands via Composer.
	-->
	<config name="installed_paths" value="tools/phpcs,vendor/phpcompatibility/php-compatibility,vendor/phpcompatibility/phpcompatibility-paragonie,vendor/phpcompatibility/phpcompatibility-wp,vendor/phpcsstandards/phpcsextra,vendor/phpcsstandards/phpcsutils,vendor/wp-coding-standards/wpcs"/>
	<rule ref="OpenStation.Files.FileLength"/>
</ruleset>