# Development Guide — PCDesigner

How to set up, build, test, and contribute to the plugin.

## 1. Prerequisites

| Tool | Version | Notes |
|---|---|---|
| PHP | 7.4 / 8.0 / 8.1 / 8.2 | 5.6 supported but new code targets 7.4 |
| Composer | 2.x | for `vendor/` |
| Node.js | 16.x (legacy) | `assets/package.json` is gulp 3 |
| MySQL / MariaDB | 5.7+ / 10.4+ | InnoDB |
| WordPress | 6.x | latest two majors |
| WooCommerce | 8.x / 10.x | HPOS enabled |
| Imagick PHP ext. | optional but recommended | falls back to GD |
| `wp-cli` | latest | for ops |
| `wp-env` (or Local, Lando) | latest | dev container |

## 2. Local setup

### Option A — `wp-env`

```bash
npm i -g @wordpress/env
cd pc-designer-web-to-print-solution
echo '{
  "core": "WordPress/WordPress",
  "plugins": [".", "https://downloads.wordpress.org/plugin/woocommerce.zip"],
  "config": { "WP_DEBUG": true, "WP_DEBUG_LOG": true, "SCRIPT_DEBUG": true }
}' > .wp-env.json
wp-env start
```

Open `http://localhost:8888`, install + activate WooCommerce, then activate this plugin.

### Option B — Local / Lando

Mount this repo into `wp-content/plugins/web-to-print-online-designer/`. Copy the same `WP_DEBUG` flags into `wp-config.php`.

## 3. First-time configuration

1. Run setup wizard: `/wp-admin/admin.php?page=nbd-setup`.
2. Connect to Printcart Dashboard (you need a sandbox account).
3. Toggle "Online Design" on a product → load the storefront → confirm canvas appears.
4. Add to cart, finish checkout, verify the design thumbnail in admin order.

## 4. Build / asset pipeline

The legacy toolchain in `assets/package.json` is gulp 3 + webpack 4 + node-sass. It works on Node 14–16.

```bash
cd assets
npm install --legacy-peer-deps
# scripts under gulpfile.js (if present); otherwise see existing minified bundles
```

> The repo ships pre-built bundles. **Do not commit only minified files** — always commit source alongside.

For new front-end work, prefer:

- Vanilla ES modules + a small build step (esbuild, vite).
- React islands for new admin screens (mount inside an existing PHP view).
- Avoid extending AngularJS.

## 5. Composer

```bash
composer install --no-dev
# new dependency
composer require <vendor/package>
```

Don't add a heavy dependency without discussing — `vendor/` is already 29 MB.

## 6. Coding conventions

- 4-space indent, no tabs.
- PHP 7.4 baseline syntax.
- Class names: PascalCase, file `class-foo.php`.
- Function names: `nbd_*` (new) or `nbdesigner_*` (legacy).
- Hook prefixes: `nbd_`.
- All user-facing strings: `__('…', 'web-to-print-online-designer')`.
- Translator comments above non-obvious strings.
- Doc comments on public methods.
- Avoid `global $variable` — prefer dependency injection.
- Use WP API: `wp_remote_*`, `wpdb->prepare`, `wp_safe_redirect`.

## 7. Testing

There is no PHPUnit harness in the repo today. Recommended additions:

- `tests/phpunit/` with WP-CLI scaffold (`wp scaffold plugin-tests …`).
- `tests/wpenv/` smoke scripts run via WP-CLI.
- `tests/cypress/` end-to-end for the editor.

Until then, smoke checklist (run before every PR):

- [ ] Activate on clean WP + WC, no notice.
- [ ] Setup wizard completes.
- [ ] Storefront editor loads on product.
- [ ] Add to cart → checkout → order shows thumbnail.
- [ ] PDF download works (sync + async).
- [ ] Admin product builder loads.
- [ ] HPOS on/off both work (toggle in WC settings).
- [ ] Mobile editor (375×812) usable.

## 8. Linting

```bash
# PHP syntax
find includes -name '*.php' -print0 | xargs -0 -n1 php -l

# WordPress coding standards
composer global require dealerdirect/phpcodesniffer-composer-installer wp-coding-standards/wpcs
phpcs --standard=WordPress includes/

# JS
npx eslint assets/js/ --ext .js  # add config if missing
```

## 9. Branching

- `main` — released code.
- `claude/<task-slug>` — AI / pair-programming tasks (see organization rule).
- `feature/<topic>` — engineer features.
- `release/<version>` — release prep.
- `hotfix/<issue>` — production fix.

PRs target the same parent branch; never push directly to `main`.

## 10. Versioning

- Header `Version:` in `nbdesigner.php` is the source of truth.
- Bump `NBDESIGNER_VERSION` constant at the same time.
- Update `readme.txt` `Stable tag:` and prepend changelog entry.
- Tag git: `vX.Y.Z`.

Semver-ish:

- MAJOR — breaking change requiring merchant action
- MINOR — new feature, backwards compatible
- PATCH — fix only

## 11. Releasing

1. Pre-release on staging with full smoke test + 24 h soak.
2. Build production bundles (`assets/`, ensure source maps are not shipped).
3. `composer install --no-dev --optimize-autoloader` for release zip.
4. Strip dev files (`.git`, `.github`, `node_modules`, `tests`, `.wp-env.json`).
5. Tag git, attach zip in release notes.
6. Submit to WP.org (free), update Printcart Cloud changelog (paid).

## 12. Debug aids

- Set `WP_DEBUG`, `WP_DEBUG_LOG`, `SCRIPT_DEBUG`.
- Add `define('NBDESIGNER_MODE_DEV', true);` to load unminified bundles.
- Add `define('NBDESIGNER_MODE_DEBUG', true);` for verbose logs in `wp-content/uploads/nbdesigner/logs/`.
- Use Query Monitor plugin for SQL hot spots.
- Use Debug Bar for transient inspection.

## 13. Where to put new code

| You're adding | Put it in |
|---|---|
| New AJAX handler | new method in an existing thematic class, or new class file |
| New REST endpoint | `class-api.php` (own namespace) or extend WC namespace |
| New admin setting | `includes/settings/<tab>.php` |
| New editor tool (Fabric) | `assets/js/tools/<tool>.js` + register in modern bundle |
| New email | `templates/emails/<event>.php` |
| New niche | `includes/niches/<slug>/` (proposed convention) |
| New cloud integration | `class-printcart-api.php` extension or new bridge class |
| New background task | extend `WP_Background_Process` in `includes/background-processes/` |

## 14. Prohibited

- Editing `vendor/`, `lib/`, `data/_icc/` directly.
- Adding AngularJS code.
- Force-pushing to `main`.
- Bypassing nonce / capability checks.
- Hard-coded paths to `printcart.com` (use the helper).
- Committing real API keys (use `wp-config.php` constants and `.env`-style overrides).