# NPS Survey - WordPress Plugin

## Project Overview
NPS Survey is a WordPress plugin library that provides Net Promoter Score survey functionality. It renders a popup survey in the WordPress admin dashboard to collect user feedback and ratings.

**Repository:** https://github.com/brainstormforce/nps-survey
**Author:** Brainstorm Force
**License:** GPL v2

## Tech Stack
- **Backend:** PHP (WordPress plugin, WPCS compliant)
- **Frontend:** React (JSX) with Zustand state management
- **Styling:** SCSS + Tailwind CSS
- **Build:** @wordpress/scripts (webpack-based)
- **Linting:** PHPCS (WordPress-Core/Docs/Extra), ESLint (@wordpress/eslint-plugin), Prettier
- **Static Analysis:** PHPStan (level 9) with WordPress stubs
- **Task Runner:** Grunt (i18n, version bumping, release packaging)

## Project Structure
```
nps-survey.php              # Main plugin entry point (defines constants)
nps-survey-plugin-loader.php # Autoloader and file loader (NPS_Survey namespace)
classes/
  nps-survey-script.php     # Core script/style enqueuing and REST API endpoints
src/                        # React frontend source
  index.js                  # Entry point
  app.js                    # Main app component
  components/               # React components (dialog, steps, button, etc.)
  store/                    # Zustand store (reducer, actions)
  utils/                    # Helper utilities
dist/                       # Built frontend assets (do not edit directly)
tests/php/stubs/            # PHPStan stubs
bin/                        # Build and release shell scripts
```

## Key Commands

### Frontend
```bash
npm run start          # Dev server with HMR
npm run build          # Production build
npm run lint-js        # ESLint check
npm run lint-js:fix    # ESLint + Prettier auto-fix
npm run lint-css       # Stylelint check
npm run pretty:fix     # Prettier auto-fix
npm run test:unit      # Jest unit tests
```

### Backend (PHP)
```bash
composer lint           # PHPCS check
composer format         # PHPCBF auto-fix
composer test           # PHPUnit tests
composer phpstan        # PHPStan analysis (level 9)
composer insights       # PHP Insights analysis
```

### Release
```bash
npm run release        # Build + package
npm run package        # Create release zip (bin/build.sh)
npm run i18n           # Generate translation POT file
```

## Coding Standards
- **PHP:** WordPress Coding Standards (WordPress-Core, WordPress-Docs, WordPress-Extra)
- **Text Domain:** `nps-survey`
- **PHP Compatibility:** 5.6+
- **JS/CSS:** WordPress ESLint and Prettier configs
- **Namespace:** `NPS_Survey` for PHP classes
- **ABSPATH guard:** All PHP files must have `if ( ! defined( 'ABSPATH' ) ) { exit; }` at the top

## Architecture Notes
- Plugin uses singleton pattern via `NPS_Survey_Plugin_Loader::get_instance()`
- PSR-4-like autoloading from the `NPS_Survey` namespace, resolving to project root
- Frontend is a standalone React app built with `@wordpress/scripts`, output to `dist/`
- State management uses Zustand (not WordPress data stores)
- REST API endpoints are registered in `classes/nps-survey-script.php`
- The plugin prevents duplicate loading via `NPS_SURVEY_FILE` constant check

## Version Management
- Version is defined in 4 places (keep in sync):
  1. `nps-survey.php` - Plugin header `Version:`
  2. `nps-survey.php` - `NPS_SURVEY_VER` constant
  3. `package.json` - `version` field
  4. `version.json` - `nps-survey` field
- Changelog: `changelog.txt` (format: `Version X.Y.Z - DD-MM-YYYY`)

## Git Workflow
- **Main branch:** `master`
- **Development branch:** `staging`
- PRs go from feature branches to `staging`, then `staging` to `master` for releases