# Installing ProofKit

ProofKit adds artwork upload and proof approval to WooCommerce. Customers upload
a print file on the product page, the shop sends a proof, and the customer
approves it or asks for changes from an emailed link.

## Requirements

| Requirement | Minimum |
|---|---|
| WordPress | 6.5 |
| WooCommerce | 8.5 |
| PHP | 8.1 |
| Database | MySQL 5.7+ / MariaDB 10.4+ (meets WordPress 6.5's minimum) |

HTTPS is strongly recommended: proof links are bearer tokens and should not
travel over plain HTTP. ProofKit declares compatibility with WooCommerce HPOS
(custom order tables).

## Install

### From a zip

1. In wp-admin go to **Plugins → Add New → Upload Plugin**.
2. Choose `proofkit-<version>.zip`, click **Install Now**, then **Activate**.
3. If WooCommerce is not active, WordPress asks you to install/activate it
   first (the plugin header declares `Requires Plugins: woocommerce`). On
   WordPress versions without that feature, ProofKit shows an admin notice
   until WooCommerce is active.

### From WordPress.org

Once the plugin is approved:

1. Go to **Plugins → Add New**.
2. Search for **ProofKit**, click **Install Now**, then **Activate**.

No build step and no Composer install are required.

## First-run checklist

### 1. Plugin settings

Go to **WooCommerce → ProofKit**:

- **From name** and **From email** — what the proof email says it is from. Use
  an address on your own domain.
- **Email subject** — defaults to
  `Your proof is ready to review — order {order_number}`. `{order_number}` is
  replaced with the WooCommerce order number.
- **Proof link expiry (days)** — default 30; accepted range 1–365. Each resend
  creates a fresh link.
- **Maximum file size (MB)** — default 25; accepted range 1–100. Your PHP and
  web-server upload limits must be at least as large.
- **Allowed extensions** — defaults to `pdf, ai, eps, png, jpg, jpeg, tif, tiff`.
  **SVG is off by default** and should stay off unless you trust every customer:
  it is an active content format. When enabled, SVG is download-only and is
  never previewed in the browser.
- **Retention (months)** — default 12. Daily maintenance purges proofs and
  their files for orders older than this, including abandoned and unpaid
  orders (`pending`, `failed`, `on-hold`, artwork review, awaiting approval)
  as well as `completed`, `cancelled` and `refunded`. A paid order in
  `processing` is left alone until it is past the cutoff. Set it to match your
  own record-keeping policy.
- **Delete all ProofKit data when the plugin is uninstalled** — off by default.
  Leave it off unless you really want the plugin to remove its tables and files
  when deleted.

Save the settings once before taking orders.

### 2. Per-product artwork settings

For each product that needs a print file:

1. Open the product in wp-admin.
2. Go to **Product data → Artwork**.
3. Tick **Enable artwork upload**.
4. Choose whether artwork is **required** (add to cart is blocked without a
   file) or optional.
5. Add **customer instructions**, e.g. "PDF, AI, EPS, PNG or JPG. 300 DPI at
   final size. Include bleed."
6. Optionally override the maximum size and allowed extensions for this
   product.

Products without the checkbox enabled show no upload control and behave like
normal WooCommerce products.

### 3. Test the loop

Place one real order on the live site, send the proof to yourself, open the
emailed link on a phone, approve it, and confirm the order moves to
**Processing**. Do this before announcing the feature to customers.

For production, install an SMTP plugin or configure your host's transactional
email. WordPress's default `wp_mail()` is unreliable on shared hosting.

## Nginx

Nginx ignores `.htaccess`, so the files under the private directory are
reachable by direct URL until you deny the path. Add this to the `server` block
that serves WordPress:

```nginx
location ^~ /wp-content/uploads/proofkit-private/ {
    deny all;
    return 403;
}
```

Test and reload Nginx:

```sh
sudo nginx -t
sudo systemctl reload nginx
```

Use `sudo nginx -s reload` or your init system's equivalent if you do not use
systemd. Then open
`https://your-site.example/wp-content/uploads/proofkit-private/` — it must
return 403, not a directory listing or a download.

If WordPress is installed in a subdirectory or the uploads directory has moved,
adjust the path. ProofKit writes a copy of the rule as `nginx.conf.example`
inside the private directory when it creates or upgrades the directory. Apache
and LiteSpeed read the generated `.htaccess`; IIS reads the generated
`web.config` — test the same URL on those servers too, especially on Apache
with `AllowOverride None`.

See [security.md](security.md) for the full security checklist.

## The customer and order flow

| Stage | Customer sees | Shop sees |
|---|---|---|
| Product page | "Upload artwork" control, instructions, file type/size hints, progress and validation errors. | Nothing yet; the product's **Artwork** tab holds the rules. |
| Add to cart | Uploaded file name and size under the cart line item. Required uploads block add-to-cart until a valid file is present. | — |
| Checkout | Normal WooCommerce checkout with the artwork attached to the line item. | — |
| Order placed | Order-received page. With a verified artwork file and a completed payment the order becomes **Artwork review**; until the gateway confirms payment it keeps the gateway's status. | Order in **Artwork review** (`wc-artwork`) with a draft proof on the line item and a dashboard count. An optional product with no file, or an order whose payment has not completed, keeps its normal WooCommerce status. |
| Shop prepares proof | No email yet. | In the order screen, review the uploaded file. If there is no usable artwork, upload it; otherwise click **Send proof**. |
| Proof sent | Email with one **Review proof** button. | Order moves to **Awaiting proof approval** (`wc-proof`); the send is logged. |
| Proof page | Item name, version, browser preview, download-original link, the on-screen-colour disclaimer, **Approve** and **Request changes** (comment required). | View is logged with the proof. |
| Approved | Confirmation page; the link is used up. | Order moves to **Processing**; approval, note and IP hash are recorded. |
| Changes requested | Confirmation; the order returns to **Artwork review**. | The comment appears on the proof; upload a new version and send it again. |
| Expired/reused link | Friendly dead-end page (HTTP 403), no order data. | Send the latest draft proof, or upload a new version if the old one was superseded; old links stay dead. |

Proofs are per line item. A new version does not inherit approval: the customer
must approve the new file. Uploading a new version also supersedes the previous
one, so any pending link for it stops working.

## Blocks and block themes

Artwork upload has two supported render paths in v1:

- The classic single-product hook,
  `woocommerce_before_add_to_cart_button`, used by classic product templates.
- The `[proofkit_upload]` shortcode, which renders the same upload control
  anywhere on a product page. `product_id` is optional and defaults to the
  current product: `[proofkit_upload product_id="123"]`.

A block product template does not fire the classic hook, so add the shortcode
to the product template (for example in a Shortcode block) until a native block
ships. A block theme that still uses the classic product template does not need
it.

Required-artwork validation runs on both checkout paths. Classic checkout is
checked before the order is placed, and Store API (block) checkout returns the
same error for a required product. Adding to cart through the Store API carries
the upload token through to the order line item.

## Files and backups

Uploaded originals live in:

```
wp-content/uploads/proofkit-private/
```

Files are content-addressed as `{ab}/{cd}/{sha256}.{ext}`. Back up this
directory together with the database, on the same schedule. Each proof row
stores a relative path and a SHA-256, and every send or download re-checks the
hash:

- A database restored without these files: the proof rows exist, sends fail,
  and downloads return an error because the originals are gone.
- These files restored without the database: the files are orphaned, and the
  daily maintenance job deletes unreferenced files after 96 hours.

Restore them as a pair and test a restore on staging. On multisite, each site
has its own directory under its own uploads path.

## SVG

SVG is disabled by default. Enable it only for a shop that trusts its customers
and needs vector uploads. Even when enabled, ProofKit treats SVG as
download-only: it is never shown inline on the proof page, never previewed in a
browser, and is always served as an attachment. The upload check screens for
common script patterns, but that is not a full sanitiser; the download-only
rule is the control. Ask customers for PDF when possible.

## Troubleshooting

| Problem | What to check |
|---|---|
| Proof emails never arrive | Configure SMTP and send a test. Check spam and the From address/domain (SPF/DKIM). Also check **WooCommerce → Status → Logs** and the server mail log. If the proof is already `sent`, use **Resend proof email** in the order's ProofKit panel; it issues a fresh link without changing the status. |
| Upload rejected | Check the file extension is in the allowed list and the size is under both the ProofKit limit and PHP's `upload_max_filesize` / `post_max_size` and Nginx's `client_max_body_size`. SVG is rejected unless explicitly enabled, and is download-only when it is. Renaming a file does not make it valid: ProofKit checks the real type. |
| "Link expired" or the proof page is a dead end | The link's `link_expiry_days` has passed, it was already used to approve/request changes, or a newer version was uploaded and superseded that proof. Open the order and send the latest draft proof, or upload a new version first. Do not edit the database to revive a token. |
| Order stuck on "Pending payment" | Payment has not completed in WooCommerce. Check the payment gateway, failed-order emails and order notes. ProofKit moves an order to **Artwork review** only after the gateway reports it as paid (or on-hold) and a verified artwork file is attached; if the customer skipped an optional upload, verification failed (look for an order note), or payment never completed, the order keeps its normal status and the shop can upload a proof manually once it is paid. Do not move it straight to **Processing** as a shortcut. |
| Proof files missing from backups | Back up the database **and** `wp-content/uploads/proofkit-private/`, and restore them together. Hashes are re-checked on every send and download, so a database-only restore leaves proofs that cannot deliver their files. If you use a host that excludes uploads, add that directory explicitly. |
| Proof page works but downloads/approvals fail on Nginx | Make sure Nginx passes `/wp-json/` and `admin-post.php` to WordPress and does not block the REST namespace. Confirm the private directory has the deny rule from [Nginx](#nginx) above, and raise `client_max_body_size` and PHP upload limits if large files fail. |
| Upload control does not appear | Check the product's **Artwork** tab is enabled and saved. A block product template does not fire `woocommerce_before_add_to_cart_button`; add the `[proofkit_upload]` shortcode to that template. A fully custom classic template must also fire the standard add-to-cart hook. |

## Uninstall and data retention

- **Deactivate** stops the plugin and clears its scheduled maintenance event.
  It does **not** delete data.
- **Delete** (uninstall) keeps the custom tables, settings and
  `wp-content/uploads/proofkit-private/` by default, so reinstalling restores
  the shop's history.
- If **Delete all ProofKit data when the plugin is uninstalled** was enabled in
  **WooCommerce → ProofKit** before deletion, uninstall drops the three ProofKit
  tables, removes the settings and schema-version options, clears the cron
  event, deletes ProofKit's cached transients, removes the dismissible-notice
  user meta, strips the `_proofkit_*` order and line-item meta from WooCommerce
  orders (including HPOS orders), and deletes the private upload directory.
  On multisite, deleting from the Network Admin walks each site;
  deleting from a single site cleans only that site.
- Retention is separate from uninstall: the daily maintenance job purges proofs
  once an order is older than the configured number of months, including
  abandoned and unpaid orders (`pending`, `failed`, `on-hold`, artwork review,
  awaiting approval) as well as `completed`, `cancelled` and `refunded`.

Take a backup before uninstalling with delete-data enabled. There is no undo.

## Developer notes

ProofKit is plain PHP 8.1+, no Composer and no build step. Classes live under
the `ProofKit` namespace and autoload from `includes/class-*.php`.

### Storage

Proofs are stored under:

```
wp-content/uploads/proofkit-private/
```

Uploads are content-addressed as `{ab}/{cd}/{sha256}.{ext}` (the first four
hex characters of the hash form two directories). `tmp/` holds in-flight files.
The directory is protected with `index.php`, `.htaccess` and `web.config`, but
that is not the whole story: Nginx ignores `.htaccess`, so add the deny rule in
[Nginx](#nginx) above. Files are served by `Upload::send_file()` through the
REST endpoint after a capability or token check. Back up the whole directory.

### Cron

`proofkit_daily` runs once per day after activation (first run is scheduled for
03:00 the next day, site time). It purges expired tokens, stale temporary
uploads, unreferenced files older than 96 hours, and proofs past the retention
window for the statuses listed under **Retention (months)**. The handler is
`ProofKit\Install::run_maintenance()`.
It is a normal WP-Cron event; disable WP-Cron on a low-traffic site only if you
replace it with a real system cron hit to `wp-cron.php`.

### REST API

Namespace `proofkit/v1`:

| Method | Route | Purpose |
|---|---|---|
| `POST` | `/wp-json/proofkit/v1/upload` | Multipart `file` + `product_id`. Guests need a valid `wp_rest` nonce in `X-WP-Nonce`; logged-in users can use their cookie. Rate limited to 20 uploads/hour, keyed by user ID when logged in and by IP hash for guests; shop managers are exempt. Returns the signed upload token, name, size, SHA-256 and expiry. |
| `GET` | `/wp-json/proofkit/v1/file` | `proof_id`, `order_id`, `token` (respond/view scope), or an admin cookie with `manage_woocommerce`. Streams the original; never a public URL. |
| `POST` | `/wp-json/proofkit/v1/respond` | `proof_id`, `order_id`, `token`, `action` (`approve` or `changes`), `note`. Consumes the respond token. |

Upload descriptors are signed and valid for 72 hours; response/view tokens
expire according to the **Link expiry** setting.

### Hooks

The extension points that exist in 1.0.0 are:

- `proofkit_daily` — the cron action described above; add a callback if you
  need to run your own maintenance at the same time.
- `proofkit_privacy_erase_proof` — filters whether a WordPress personal-data
  erasure request deletes the artwork and approval records for an order.
  Default `false` keeps them as the shop's audit trail. Arguments:
  `(bool $erase, int $order_id)`. Return `true` to delete that order's proof
  files, rows, events and tokens.
- `woocommerce_email_subject_proofkit_proof_ready` — a WooCommerce email
  filter (three arguments: subject, email object, order). Use it to customise
  the proof email subject without editing the plugin:

```php
add_filter(
    'woocommerce_email_subject_proofkit_proof_ready',
    static function ( $subject, $email, $order ) {
        return sprintf( 'Proof for order %s', $order->get_order_number() );
    },
    10,
    3
);
```

Everything else is intentionally private. Do not rely on methods outside the
public class API documented above, and do not query `wp_posts`/`wp_postmeta` for
orders — use WooCommerce CRUD so HPOS keeps working.

### Other details

- Order statuses: `wc-artwork` (**Artwork review**) and `wc-proof`
  (**Awaiting proof approval**). Approval moves the order to `processing`;
  requesting changes moves it back to `wc-artwork`.
- Custom tables: `{prefix}proofkit_proofs`, `{prefix}proofkit_events`,
  `{prefix}proofkit_tokens`.
- Admin actions require `manage_woocommerce`, not `manage_options`.
- No telemetry, no phone-home, no external requests, and no upgrade prompts
  anywhere in the admin.
