The plugin does three jobs: it decides, every hour, which orders are due a reminder; it emails a link signed for that one order; and it adds a photo field to the product's own review form. Four rules govern them.
The flow, step by step
- Every hour a WordPress cron event runs a sweep (
gmrrf_send_remindersin the free edition,gmrr_send_remindersin the full edition). It exists only while reminders are switched on. - The sweep finds orders that are in the status you chose and were placed at least Ask after (days) ago, newest first, and asks up to the batch size of them. Orders already asked are left out, and an order with nothing to ask about is read past rather than counted, so the orders behind it are always reached — a backlog is worked through a batch an hour. In the full edition it does this once for each reminder in the sequence.
- Each order is judged now (the ask rule, below). If nothing is left to ask about, it is skipped.
- The order is claimed (the claim rule), then the email is sent to the billing address — unless that address has opted out.
- The customer opens the link. A Leave a review page lists the products that order may still review. Each one links to the product's own review form, carrying the link with it. The page is drawn inside your theme's own header and footer.
- The customer reviews, with a photo if photos are on. The review is an ordinary WordPress comment and goes through your normal moderation.
- You approve it. The photo now shows with the review. Full edition: if the thank-you coupon is on, the coupon is created.
Rule 1 — the link belongs to one order
The review link carries the order id and a token. The token is an HMAC over the order id and the order's own key, signed with your site's auth salts. So:
- It cannot be made from an order number. Order numbers are small integers anybody could count through; the key is not.
- Changing an order's key closes every link already emailed for it.
- An unknown or broken token shows exactly the same page as a good link with nothing left on it — "There is nothing here to review. The link may have been used already, or the order may have changed." — so the link cannot be used to find out which orders exist.
The page lists only products that order bought. A variation is listed as its parent product, because that is where WooCommerce keeps reviews. A line refunded in full is left out.
The review itself is written on the product's normal review form, the one your theme styles and WooCommerce validates. That means your WooCommerce review settings still apply: if Reviews can only be left by "verified owners" is on, or WordPress requires users to be signed in to comment, the customer has to meet those rules too.
A review posted from a link is checked again when it arrives: the product reviewed must be one that order may still review, or the review is refused with "This review link is not for that product." — so an altered request cannot review something the customer never bought. A review that passes is marked as from a verified owner (WooCommerce's own verified flag), because the link proves the purchase. A review posted without a link is left to WordPress and WooCommerce exactly as before.
Rule 2 — a photo is bytes from a stranger
A review form is a file upload anybody who bought something can reach, so uploads are treated strictly:
- The type is checked against the file itself, through WordPress's
wp_check_filetype_and_ext(), not the name the browser sent.shell.php.jpgis refused. - Only JPG, PNG, GIF and WebP are accepted. SVG is deliberately left out: it is a document that can carry script.
- The number of photos and the size of each are checked where the files are accepted, not only in the form. Extra photos are dropped with a message; a photo that is too large or not an image is refused by name.
- WordPress's own
wp_handle_upload()moves the file. The photo becomes an attachment that belongs to its review, not to any post, and deleting the review deletes its photos. - Nothing is stored for a comment WordPress has already marked as spam.
- A photo is only shown on an approved review. A pending review's photos stay hidden, or the moderation queue would mean nothing.
Free edition: one photo, up to 4 MB. Full edition: up to the Photos per review and Largest photo (MB) you set.
Rule 3 — never ask about something they no longer have
A week is long enough for an order to be refunded. So every decision is taken when the reminder is due, not when the order was marked delivered:
- The order must still be in the chosen status.
- It must have a billing email.
- A line refunded in full drops out.
- Full edition: excluded products and categories drop out. (The free edition applies exclusions the full edition saved, too.)
- A product this customer has already reviewed — found in WordPress's own comments by their email address — drops out.
If nothing is left, the order is not asked. "How did you get on with your purchase?" for an order the shop refunded on Tuesday is the worst email this kind of plugin can send.
Rule 4 — one order is asked once
Before anything is mailed, the reminder is written onto the order in the meta key _gmrr_sent and the order is saved. The sweep then reads it back from a fresh copy of the order; only the run whose write is there sends. WordPress cron can start two sweeps at once on a busy site, and this is what stops both asking the same person.
In the full edition _gmrr_sent holds the list of reminders the order has had, so each reminder in the sequence is sent once.
If code holds a reminder back (by returning false from the email filter), the order stays claimed: one customer not asked, rather than asked again every hour.
Nothing is emailed inside the request that changed the order. Marking forty orders complete is a bulk edit, and forty emails inside it is how it times out — the hourly sweep sends them instead.
Unsubscribing
Every reminder ends with an unsubscribe link carrying a token signed over the customer's address, beside the order's own signed review link — the token alone cannot be turned back into an address, so the order is how the plugin knows whose address to check it against. An address on the opt-out list (the option gmrr_optouts) is never sent a reminder. The link opens a page of its own, inside your theme, that always says the same thing — "You will not receive any more review requests from us." — so it shows on any home page, and it cannot be used to test whether an address is a customer.
Full edition: the thank-you coupon
When a review is approved and Send a single-use coupon when a review is approved is on, the plugin first claims the review (comment meta _gmrr_coupon set to pending), then creates the coupon and stores its code there. Unapproving and approving again does not create a second coupon. If saving the coupon fails, the claim is released so the next approval can try again.
Next: FAQ and troubleshooting.
