cartflows / docs / wiki / WordPress-Coding-Standards.md

WordPress-Coding-Standards.md in CartFlows – Funnel Builder & Checkout Plugin for WooCommerce 3.0.1, at docs/wiki/WordPress-Coding-Standards.md

219 lines 5.1 KB

Raw Download Zip

1	# WordPress Coding Standards
2
3	CartFlows enforces strict coding standards across PHP and JavaScript using automated tools integrated into the development workflow.
4
5	## PHP Standards
6
7	### PHPCS + WordPress Coding Standards
8
9	CartFlows uses PHP_CodeSniffer (PHPCS) with the WordPress Coding Standards ruleset plus VIP-Go rules.
10
11	Configuration file: `phpcs.xml.dist`
12
13	```bash
14	# Check coding standards
15	composer lint
16
17	# Auto-fix fixable violations
18	composer format
19	```
20
21	### Ruleset (`phpcs.xml.dist`)
22
23	The ruleset includes:
24
25	- WordPress — Core WordPress PHP standards
26	- WordPress-Extra — Additional WordPress best practices
27	- WordPress-Docs — Documentation requirements
28	- VIP-Go — Automattic VIP Go platform standards
29
30	### Custom Sanitizer Registration
31
32	`wc_clean` is registered as a recognized sanitizer function in `phpcs.xml.dist`. PHPCS will not flag it as an unrecognized sanitizer:
33
34	```xml
35	<rule ref="WordPress.Security.ValidatedSanitizedInput">
36	<properties>
37	<property name="customSanitizingFunctions" type="array">
38	<element value="wc_clean"/>
39	</property>
40	</properties>
41	</rule>
42	```
43
44	Use `wc_clean()` for WooCommerce data sanitization (it wraps `wp_kses_post` for arrays, `sanitize_text_field` for strings).
45
46	### Excluded Paths
47
48	These directories are excluded from PHPCS scanning:
49
50	```xml
51	<exclude-pattern>admin-core/assets/</exclude-pattern>
52	<exclude-pattern>vendor/</exclude-pattern>
53	<exclude-pattern>node_modules/</exclude-pattern>
54	<exclude-pattern>libraries/</exclude-pattern>
55	<exclude-pattern>tests/php/</exclude-pattern>
56	```
57
58	### Key Rules Applied
59
60	\| Category \| Rule \| Pattern \|
61	\|----------\|------\|---------\|
62	\| Input sanitization \| Always sanitize `$_POST`, `$_GET` \| `sanitize_text_field()`, `wc_clean()`, `absint()` \|
63	\| Output escaping \| Always escape output \| `esc_html()`, `esc_attr()`, `esc_url()`, `wp_kses_post()` \|
64	\| Nonce verification \| Verify before processing \| `wp_verify_nonce()` / `check_ajax_referer()` \|
65	\| Capability checks \| Before mutations \| `current_user_can( 'manage_options' )` \|
66	\| File access protection \| Top of every file \| `if ( ! defined( 'ABSPATH' ) ) { exit; }` \|
67
68	---
69
70	## PHPStan Static Analysis
71
72	Configuration file: `phpstan.neon`
73
74	```bash
75	# Run static analysis
76	composer phpstan
77	```
78
79	### Stubs
80
81	PHPStan uses custom stubs for CartFlows and WordPress:
82
83	\| Stub Package \| Purpose \|
84	\|-------------\|---------\|
85	\| `szepeviktor/phpstan-wordpress` \| WordPress function stubs \|
86	\| `php-stubs/wordpress-stubs` \| WordPress core stubs \|
87	\| `php-stubs/woocommerce-stubs` \| WooCommerce stubs \|
88	\| `tests/php/stubs/cf-stubs.php` \| CartFlows-specific stubs \|
89
90	Regenerate CartFlows stubs after significant class changes:
91	```bash
92	composer update-stubs
93	```
94
95	---
96
97	## JavaScript Standards
98
99	### ESLint
100
101	Configuration: `@wordpress/eslint-plugin` (WordPress standard ESLint config)
102
103	```bash
104	npm run lint-js # Check JS/JSX files
105	npm run lint-js:fix # Auto-fix violations
106	```
107
108	Key rules enforced:
109	- No `console.log` in production code
110	- Consistent React hook usage (rules-of-hooks)
111	- Import ordering
112	- No unused variables
113
114	### Prettier
115
116	Package: `wp-prettier` (WordPress-flavoured Prettier)
117
118	```bash
119	npm run pretty # Check formatting
120	npm run pretty:fix # Auto-fix formatting
121	```
122
123	Prettier handles:
124	- Consistent quote style (single quotes)
125	- Trailing commas
126	- Line length
127	- Bracket spacing
128
129	### Stylelint (CSS)
130
131	```bash
132	npm run lint-css # Check SCSS/CSS files
133	npm run lint-css:fix # Auto-fix violations
134	```
135
136	---
137
138	## Commit Message Standards
139
140	CartFlows uses the Conventional Commits format:
141
142	```
143	<type>: <short description>
144
145	[optional body]
146	```
147
148	### Types
149
150	\| Type \| Usage \|
151	\|------\|-------\|
152	\| `feat:` \| New feature \|
153	\| `fix:` \| Bug fix \|
154	\| `docs:` \| Documentation changes \|
155	\| `chore:` \| Build, tooling, or dependency updates \|
156	\| `refactor:` \| Code refactoring (no feature/bug change) \|
157	\| `test:` \| Adding or updating tests \|
158	\| `style:` \| Formatting, whitespace (no logic changes) \|
159
160	### Examples
161
162	```
163	feat: add order bump preview to step editor
164	fix: checkout fields not saving on mobile layout
165	docs: update REST API reference for flows endpoint
166	chore: bump @wordpress/scripts to 19.2.2
167	refactor: extract checkout field renderer to separate class
168	```
169
170	---
171
172	## Pre-commit Hook
173
174	Running `npm install` installs a git pre-commit hook. It runs before each commit to catch violations early.
175
176	Do not bypass with `--no-verify` unless explicitly approved by the team.
177
178	---
179
180	## File Header Standards
181
182	Every PHP file must start with:
183
184	```php
185	<?php
186	/**
187	* Brief description of the file.
188	*
189	* @package CartFlows
190	*/
191
192	// Exit if accessed directly.
193	if ( ! defined( 'ABSPATH' ) ) {
194	exit;
195	}
196	```
197
198	---
199
200	## IDE Integration
201
202	For VS Code, install:
203	- PHP Intelephense — PHP language server
204	- ESLint — JS linting
205	- Prettier — Code formatting
206	- Stylelint — CSS linting
207	- PHP CS Fixer — PHP formatting
208
209	Configure VS Code to use the project's `.eslintrc` and run Prettier on save.
210
211	---
212
213	## Related Pages
214
215	- [](Contributing-GuideContributing-Guide](Contributing-Guide](Contributing-Guide)
216	- [](Testing-GuideTesting-Guide](Testing-Guide](Testing-Guide)
217	- [](WordPress-Plugin-StructureWordPress-Plugin-Structure](WordPress-Plugin-Structure](WordPress-Plugin-Structure)
218	- [](Build-SystemBuild-System](Build-System](Build-System)
219