Phoenix Nest Vehicle Condition Photos

A single-file WordPress plugin that captures pickup and return condition photos of a rental vehicle on the customer's own phone — no app, no login, no account — files them against the MotoPress booking, and locks each set after submit so the before/after pair is usable as dispute evidence.

The owner opens a bookmarked board on their phone, taps a booking, and shows a QR code. The customer scans it, takes six photos, and hits submit. The set locks and the link dies.

Live in production: phoenixnest.properties — Phoenix Nest Properties LLC (Destin, FL vehicle rentals).

Why this exists

Condition photos are a physical event, not form data. The booking happens online days ahead and the agreement is signed online right after — at neither moment is the customer standing next to the car. So the photos cannot ride:

• the booking form — the vehicle isn't there yet;
• the e-signature document — signer-input fields do text, not file uploads.

They need their own capture surface, opened twice per rental. And the business value is evidence: a photo set that can be quietly replaced later is worth nothing, so the lock is part of the feature, not a hardening extra.

The hard constraint is that the person holding the camera is a customer you cannot ask to install anything or create an account. That single requirement drives the whole design.

Architecture

sequenceDiagram
    actor O as Owner (phone)
    participant B as Owner board /pn-today/
    actor C as Customer (phone)
    participant P as Capture page /vehicle-photos/
    participant WP as WordPress

    Note over O,B: bookmarked once with ?k=SECRET<br/>then a derived HttpOnly cookie
    O->>B: open board for a chosen day
    B-->>O: cards — coming back · going out · still out
    alt customer is standing here
        O->>B: tap Show QR
        Note over B: QR drawn in-browser onto a canvas<br/>never sent to a QR-image API
    else customer has already gone
        O->>B: tap Send pickup or return photo link
        Note over B: phase is DERIVED, so there is no choice to offer
        B-->>O: green or red toast, dismissed with the X
    end
    C->>P: scan or tap → /vehicle-photos/?t=TOKEN (128-bit)
    Note over P: phase DERIVED from state —<br/>no pickup → pickup, pickup → return, both → read-only
    loop each of 6 slots
        C->>WP: one photo per AJAX request
        WP-->>C: thumbnail + progress
    end
    C->>WP: Submit
    Note over WP: re-check completeness server-side →<br/>write the phase lock → ROTATE the token
    WP-->>C: locked — this link is now dead

The four surfaces

The upload notice carries the owner key, and that is the trade. The board renders nothing without the cookie or k, so a keyless link would open a blank page on any device that had never been set up — worse than not sending it. So the message is a credential: it grants the whole board (every customer's name and dates, live capture tokens and codes, the send buttons). It goes to the site's own admin address and nowhere else, the link is last in the body with nothing after it (a half-linkified credential is its own failure), and Settings → Vehicle Photos → regenerate revokes every copy at once. The booking is pinned with q=#<id> rather than the customer's email — pn_vc_matches_search() already matches the id, a search replaces the day window so it resolves whatever the dates are, and no customer address ends up in an inbox or a server log. The # is rawurlencode()d because add_query_arg() does not encode: a raw one truncates the URL into a fragment and the board opens on today. | Settings | The owner link, and a regenerate button that also invalidates every phone's cookie. |

Data model

WP attachments hung off the booking post. No custom tables.

A mail plugin that replaces wp_mail() is trusted, and finding that out cost a red lie (v1.2.4). pn_vc_mail_transport() judged delivery from $GLOBALS['phpmailer']->Mailer, treating mail as "PHP mail(), which WP Engine discards". FluentSMTP — active on this site — declares its own wp_mail(), rebuilds core's body, calls $phpmailer->isMail() (pinning Mailer to mail) and then hands the message to its provider driver. So every send read as undelivered while FluentSMTP's own log said sent. Mailer cannot separate the two; who owns wp_mail() can, so that check now runs first (pn_vc_wp_mail_is_core_file(), via ReflectionFunction) and an unknown path still counts as core, keeping the stricter reading. A red lie is not the safe direction — it costs the owner exactly what a false green costs him. | booking meta | _pn_vc_pickup_done_at · _pn_vc_return_done_at | the phase locks — phase is derived from these, never passed in a URL |

Security model

Installation

# From wp-content/plugins/
git clone https://github.com/codebyshoaib/phoenix-vehicle-condition.git

Or upload the ZIP via Plugins → Add New → Upload Plugin, then Activate.

Requirements: WordPress 5.7+, PHP 7.4+, MotoPress Booking Calendar (or any booking CPT — see pn_vc_booking_post_types()).

Setup

1. Create a page at /vehicle-photos/ containing [pn_vc_capture].
2. Create a page at /pn-today/ containing [pn_vc_today].
3. Settings → Vehicle Photos → open the owner link on the phone once and add it to the home screen.
4. Exclude both paths from any page cache. A cached page ships a stale security nonce, and every upload then fails with a misleading "check your signal".

The plugin fails loud with an admin notice if either page is missing.

Engineering notes

• The owner board doesn't render through the theme, on purpose. Measured on a real phone, the site's header put 660 of 844 px of chrome above the first booking, and the page builder's h1/button/a rules overrode the plugin's styles — repainting the primary action as a theme button with an underlined link inside it. Specificity wars against a page builder are unwinnable and unstable across its updates, so the board emits its own minimal document (5.8 KB instead of ~300 KB) with apple-mobile-web-app-capable so the home-screen bookmark opens without browser chrome. The customer page stays in-theme, where branding earns its keep.
• Two kinds of timestamp, and mixing them is a real bug. Pickup/return come from a datetime-local field and are wall-clock — there is no timezone in 2026-07-23 08:00 to convert from. The photo locks are written by current_time('mysql') and genuinely are site time. Formatting the first like the second showed an 8 am pickup as 4:00 am and pushed an evening pickup onto the next day, where it vanished off the board. pn_vc_fmt_local() and pn_vc_fmt() exist separately for this reason.
• 'post_status' => 'any' is a trap. It expands to statuses registered exclude_from_search => false. Booking plugins routinely register their own statuses, so 'any' can return zero rows with no error at all. Enumerate get_post_stati() minus trash/auto-draft instead.
• Never gate behaviour on has_shortcode( $post->post_content ) alone. A page built in a page builder keeps the shortcode in postmeta while do_shortcode still runs — so noindex, cache headers and the entire JS payload silently don't happen, and the page looks perfect. Match the request path too.
• Classification rides in with the INSERT. _pn_vc_phase/_pn_vc_slot are passed via meta_input so they land in the same query as the attachment. Written afterwards, a resize that dies mid-request (a 48 MP HEIC against ImageMagick limits) leaves an attachment invisible to every query, never replaced, never deleted, and publicly readable.
• The QR is generated in the browser, never fetched. The encoded URL contains a booking secret; handing it to a QR-image API hands over the booking. qrcode-generator (MIT) is vendored for this reason.
• Bump the asset version when an asset changes. Confirmed the hard way: with the file correct on disk and the URL unchanged, a CDN happily served the old stylesheet.
• Watch the PHP function-hoisting trap. A top-level if ( function_exists('…') ) return; guard is always true — PHP hoists top-level declarations at compile time — so the file returns before registering a single hook. Functions exist; nothing is wired; nothing errors. The self-test asserts the registrations for exactly this reason.

Tests

php tests/selftest.php     # → OK (110 assertions)

No framework, no fixtures, no WordPress: it stubs the WP functions the plugin touches and asserts the things that fail silently — hook registration, the phase machine and its lock, the day-board roles, the timezone split above, secret normalisation, the short-code scope, and photo keying. Excluded on purpose: the AJAX handlers and rendering, which need a real request.

Part of a four-plugin system

Each plugin owns one job and one set of meta keys, so a bug in a reporting screen can never take down the booking flow.

flowchart LR
    F["1 · booking fields<br/><code>_phoenix_*</code>"] --> E["2 · e-sign bridge<br/><code>_pn_esign_doc_id</code>"]
    E --> V["3 · condition photos<br/><code>_pn_vc_*</code> + attachments"]
    F --> R["4 · customer records<br/>reads only"]
    E --> R
    V --> R

This plugin is self-contained: it reads booking meta written by 1, and 4 reads its keys — but it calls no other plugin's functions, so deactivating any of them degrades a display rather than breaking a capture.

Author

Shoaib Ud Din — Full-stack engineer LinkedIn · GitHub

License

GPL-2.0-or-later — consistent with the WordPress plugin ecosystem. assets/qrcode.min.js is qrcode-generator v2.0.4 by Kazuhiko Arase, MIT licensed, vendored unmodified.