/home/edulekha/www/wp-content/plugins/wp-slimstat/.cursorrules
# WP-SlimStat Project Rules (Master)
## WordPress Coding Standards
* **Indentation:** Tabs (not spaces).
* **Naming:** Prefix public classes, functions, hooks, and globals with `wp_slimstat_*`; Pro uses `WpSlimstatPro\…` namespaces.
* **Brace/Spacing:** Follow WP PHP Coding Standards (opening brace on same line; standard spacing).
* **Yoda Conditions:** `if ( 'value' === $var )`.
* **Docs:** PHPDoc for all classes, methods, hooks; meaningful inline comments.
## Version Support
* **Minimum WordPress:** **5.6+**
* **Minimum PHP:** **7.4+** (ensure forward compatibility with PHP 8.0–8.3).
* Use typed properties, arrow functions, and `declare(strict_types=1);` where appropriate; avoid deprecated 8.x-removed features.
## GPL Compliance & Open Source
* **License:** GPLv2+ (or GPL-compatible) for all code/assets.
* **No Encrypted/Obfuscated Code:** Ship sources for any minified assets.
* **Headers:** Add GPL license headers to new files; keep build scripts open.
## Secure Coding Practices
* **Sanitize Inputs:** `sanitize_text_field()`, `intval()`, `sanitize_email()`, `sanitize_key()`, `wp_unslash()` + `esc_url_raw()` where relevant.
* **Escape Outputs:** `esc_html()`, `esc_attr()`, `esc_url()`, `wp_kses_post()` by context.
* **DB Safety:** Always use `$wpdb->prepare()`; no raw interpolated SQL.
* **No Unsafe Functions:** No `eval()`/dynamic include of user-controlled paths.
* **Types & Validation:** Validate type/format before processing.
## Security & Permissions
* **Nonces + Caps:** Nonce check + capability check for every state-changing action (`manage_options` or custom `slimstat_*`).
* **AJAX/REST:** Use `permission_callback`; never expose raw queries; validate/sanitize all params.
* **Escaping Everywhere:** Output is escaped at render time; never echo unsanitized DB/user values.
* **Indexes:** Ensure SlimStat tables are indexed for safe, fast queries.
## Nonce & Permission Checks (Forms)
* `wp_nonce_field()` in forms; `wp_verify_nonce()` on submit.
* `current_user_can()` for admin actions; respect roles/capabilities.
* CSRF prevention on all POST/AJAX routes.
## Privacy & GDPR Compliance (Analytics-Specific)
* **Consent Required:** No tracking without opt-in; integrate with WP privacy policy tools/consent UI.
* **Anonymization:** Hash or truncate IPs before storage; avoid storing direct personal identifiers.
* **Respect Opt-Out:** Front-end opt-out (cookie/localStorage). Honor globally.
* **Retention:** Admin setting for data retention; purge via WP-Cron.
* **No External Calls by Default:** Geolocation/3rd-party services are **opt-in** with clear disclosure.
* **WP Privacy API:** Implement personal data exporters/erasers where applicable.
* **No Regressions:** New code must maintain or improve GDPR posture.
## No External Calls Without Opt-In
* **No Silent Phone-Home:** Any remote request must be user-initiated or explicitly enabled.
* **Documented:** List endpoints, purpose, and data sent.
* **No Usage Telemetry** without explicit, revocable consent.
## WordPress Plugin Directory Guidelines
* **No Crippleware:** Free plugin fully works; Pro extends via addons/hooks.
* **No Unauthorized Ads/Links:** "Powered by" is opt-in only.
* **Admin Notices:** Relevant, dismissible, minimal.
* **Graceful Fallbacks:** External service failures don't break the site.
* **Repository Eligibility:** Follow all WP.org rules strictly.
## Architecture & Code Organization
### Core (Free)
* **Pattern:** Procedural singleton (`wp_slimstat` static class) + small focused classes.
* **Structure:**
* Admin logic in `admin/`
* Admin views/templates in `admin/view/` (minimal logic)
* Data & services in `src/`
* **Separation of Concerns:** Keep templates thin; move logic into classes.
### Pro
* **Pattern:** Modern OOP with namespaces + DI container.
* **Namespaces:** `WpSlimstatPro\…` with directories like `src/Admin/`, `src/Addon/`.
* **Services:** Register via service providers (DI); avoid mixing paradigms with Free.
### Extensibility
* **Hooks:** Provide `do_action()`/`apply_filters()` for key lifecycle points.
* **Free vs Pro Boundaries:** Pro adds features via hooks/classes, not hidden gates in Free.
* **Schema Versioning:** Migrate with `dbDelta()` behind version checks.
## Consistency Across Free & Pro
* **Hook Stability:** Maintain BC for public hooks/APIs; deprecate gradually.
* **Identifiers:** Don't rename/remove globals/options without a migration path.
* **Text Domains:** `wp-slimstat` (Free), `wp-slimstat-pro` (Pro); i18n everywhere.
* **Modularity:** Avoid monoliths; keep logical file/module boundaries.
## Performance & Resource Usage
* **Scalable Storage:** Use dedicated SlimStat tables; avoid `postmeta/options` for logs.
* **Batch/Async:** Heavy jobs via WP-Cron/batches (e.g., IP lookups, aggregations).
* **Caching:** Transients/object cache for repeated aggregates.
* **Big Data Safety:** No `SELECT *` on large tables; paginate; limit columns; ensure indexes.
* **Memory & Time:** Optimize for high-traffic sites.
## Error Handling & Logging
* **Graceful Failures:** Try/catch risky code; never fatal in admin/front.
* **Admin Notices:** Friendly, non-sensitive error messages.
* **Logging:** `WP_DEBUG_LOG`/`error_log()`; never log personal data.
* **Uninstall:** `uninstall.php` cleans tables/options/settings introduced by SlimStat.
## Documentation
* **PHPDoc:** For public methods/classes; document filter/action signatures.
* **Readme/Changelog:** Keep `readme.txt` + `CHANGELOG.md` current for user-impacting changes.
* **Comments:** Clarify complex logic; err on the side of over-explaining.
## Internationalization & Accessibility
* **i18n:** Wrap all user-facing strings; load text domain early.
* **RTL & a11y:** RTL-ready admin UI; semantic headings; ARIA where appropriate.
## File Naming & Placement
* **Core:** Files prefixed `wp-slimstat-*`; class files in `src/` by concern.
* **Pro:** Namespaced classes under `src/…`; service providers by feature area.
* **Admin:** Views under `admin/view/`; logic in `admin/` classes.
## Testing Requirements
* **Unit Tests:** `WP_UnitTestCase` for data layer/edge cases.
* **Large Dataset Tests:** Validate performance on millions of rows (synthetic fixtures OK).
* **Security Tests:** Inputs sanitized, outputs escaped; nonce/cap checks present.
* **Integration:** Confirm new features don't break existing reports/tracking.
* **Cross-Version:** Test WP 5.6+ and PHP 7.4–8.3.
## Development Workflow
* **CI/CD:** Run PHPCS (WordPress rules), unit tests, and linting on every PR.
* **Static Analysis:** PHPStan/Psalm (with WP stubs) at level 6–8.
* **E2E (critical flows):** Playwright/Cypress hitting a test site to ensure visits get logged.
* **Build Hygiene:** No `var_dump()`/echo in shipped code; remove debug code before release.
## Backward Compatibility
* **Hooks:** If changing a hook, add `_deprecated_hook()` and a replacement filter/action.
* **Options/Tables:** Migrate options/DB schema on upgrade; never drop data silently.
## Packaging & Deployment
* **Plugin Headers (main file):**
* `Requires at least: 5.6`
* `Requires PHP: 7.4`
* `Tested up to: [latest]`
* `Stable tag: [x.y.z]`
* **Readme Compliance:** Changelog per release; stable tag matches Git tag.
* **Exclude Dev Files:** Use `.gitattributes`/build script to exclude tests, CI configs, node_modules, etc.
## Multisite & WooCommerce Considerations
* **Multisite:** Data stored per-site; test network activate/deactivate; no cross-site leakage.
* **WooCommerce Tracking:** Use official hooks (`woocommerce_thankyou`, `woocommerce_add_to_cart`, etc.) for ecommerce events; no template overrides for tracking.
* **Graceful Deactivation:** Turning off Pro must not corrupt/lose Free data or break admin UI.
## Data Portability
* **Export/Erase:** Implement `wp_privacy_personal_data_exporter` and `…_eraser` for SlimStat's stored data (if any is personal).
* **Formats:** Provide CSV/JSON exports with proper escaping and column headers.
## Code Review Checklist (pre-PR)
1. ✅ WP Coding Standards (PHPCS clean)
2. ✅ Nonce + capability checks on mutations
3. ✅ Inputs sanitized; outputs escaped
4. ✅ GDPR-safe (consent, anonymization, opt-out honored)
5. ✅ Architecture consistent (Free vs Pro patterns)
6. ✅ Efficient queries; indexes present; no N+1
7. ✅ Graceful error handling; no sensitive logs
8. ✅ Docs updated (PHPDoc, readme, changelog)
9. ✅ Tests pass (unit/integration); manual smoke tests on fresh & large datasets
10. ✅ Backward compatible (hooks, options, schema)