qdr.app.woo.plugins/studiou-wc-free-photo-product

QDR - Studiou WC Free Photo Product

WordPress (6.9.4+) / WooCommerce (10.6.2+) plugin that allows publishing special variable products with custom raw image upload for photo printing. Customers select a product variant using WooCommerce's native variation selector and upload their photo file, which gets stored in the WordPress media library under a configurable media category.

Requirements

• WordPress 6.9.4+
• WooCommerce 10.0+
• PHP 8.2+
• PHP ZipArchive extension (for admin ZIP download)
• Product Variant Table for WooCommerce plugin (folder slug: product-variant-table-for-woocommerce) — used to render variants as a table with per-row quantity inputs. Declared via the plugin header Requires Plugins: field and enforced at runtime by an admin notice if the plugin is missing or deactivated.

Installation

1. Upload the studiou-wc-free-photo-product folder to /wp-content/plugins/
2. Activate the plugin through the Plugins menu in WordPress
3. The plugin creates a custom database table {prefix}studiou_fpp_files on activation

Configuration

Creating a Free Photo Product

1. Create or edit a WooCommerce product and set its type to Variable
2. Add variations with attributes (e.g. size: 10x15, 20x30, A4) and prices
3. Go to the Free Photo tab in the product data panel (visible for Variable products)
4. Check Enable Free Photo
5. Select or create a Media Category - uploaded files will be assigned to this category
6. Set Max File Size (MB) - maximum allowed upload size per file (1-500 MB, default 50)
7. Optionally set Min Image Resolution (px) and Max Image Resolution (px) - width and height are interchangeable (portrait/landscape auto-detected). Leave empty to skip validation. RAW files that cannot be measured are skipped.
8. Copy the displayed Shortcode for use on custom pages

Product Detail Page

When a variable product has Free Photo enabled, the upload area automatically appears on the WooCommerce single product page below the product summary (below the variation table and Add to Cart buttons). The customer workflow is:

1. Upload a photo file via drag-and-drop or file browser (below the variation table)
2. The product gallery image updates to show the uploaded photo preview
3. Select a variant from the product variation table and click its Add to Cart button
4. If no photo is uploaded, the server blocks the add-to-cart and shows an error notice
5. The uploaded photo stays — the same photo can be used for multiple variants without re-uploading

The uploaded file reference is stored in two parallel locations — the WooCommerce session and a pair of first-party HttpOnly cookies (studiou_fpp_att_id / studiou_fpp_rec_id) written server-side on the same request that assembles the file. The cookie pair is required because Product Variant Table for WooCommerce 1.9.3+ and WooCommerce 10.7.0+ route Add to Cart through the WC Store API, which identifies its session via the Cart-Token request header rather than the classic wp_woocommerce_session_* cookie — and that path sees a different, empty session than the one the upload wrote to. The cookies travel with every same-origin request (classic admin-ajax and Store API fetch calls), so whichever endpoint PVT / WC decide to use, the upload reference is reachable. Both the session and the cookies persist across add-to-cart actions, allowing the same photo to be used for multiple variants without re-uploading; both are cleared when the user explicitly removes the uploaded photo.

Quantity Discount Tiers (per variation)

Each variation can optionally define a Quantity Discount Tiers table in its admin edit panel. Each row is a pair:

• From Qty — minimum quantity threshold (integer ≥ 1)
• Discount % — percentage discount (0–100) applied to the entire cart line

The tier with the largest From Qty that is still less than or equal to the line's quantity wins (flat step function). When no row matches (or no tiers are defined), the variation's explicit WooCommerce price is used unchanged.

Rules:

• Tiers are evaluated per cart line — each line uses its own quantity, no cross-line summing. This matches the typical case where each line has its own uploaded photo.
• Tiers are stored as post meta _studiou_fpp_qty_tiers on the product_variation post (PHP-serialized array, one sorted list per variation).
• The feature is gated to FPP-enabled parent products. Non-FPP variable products are not affected.
• The discounted unit price flows automatically into the cart subtotal, checkout, order line item, emails, invoices, and refunds — no special-casing anywhere else.

Frontend display — designed for the Product Variant Table for WooCommerce (pvtfw) plugin, which is a hard dependency of this plugin:

• Tier data for all variations of the current product is emitted as an inline <script>window.studiouFppTierData = {…}</script> via wp_footer.
• A persistent amber "Quantity discount available — save up to X%" notice is rendered above the variants table on any FPP product that has at least one tiered variation (hooked on woocommerce_single_product_summary priority 25).
• For each row of the <table class="variant"> rendered by pvtfw, the frontend JS:
  • Appends a compact tier summary strip beneath the price cell (e.g. 5+: −5% | 10+: −10% | 50+: −20%).
  • Binds the row's input.qty and .qty-count ± buttons so that changing the quantity updates the row's .woocommerce-Price-amount with the discounted unit price.
  • Shows a green −X% "save" badge next to the price when a tier is active, and reverts the price back to the original HTML when the quantity drops below the smallest tier.
• The frontend JS also contains a fallback branch that listens for WC's native found_variation / reset_data events on form.variations_form, so the plugin still degrades to sensible behavior if pvtfw is temporarily unavailable.
• Per-row price updates are display-only. The authoritative pricing happens server-side in woocommerce_before_calculate_totals (priority 20), which calls set_price() on the cart item's product instance. The pvtfw AJAX add-to-cart handler only forwards product_id, variation_id, and quantity — it does not send the displayed price — so there is no risk of client-side tampering.

Add-to-cart is blocked server-side until a photo is uploaded:

• Validation: woocommerce_add_to_cart_validation (priority 1) calls Studiou_WC_FPP_Single_Product::resolve_uploaded_file() which looks at the WC session first and then falls back to the studiou_fpp_att_id / studiou_fpp_rec_id cookies, verifies the referenced row in wp_studiou_fpp_files matches and is not yet attached to an order, and blocks with an error notice if nothing resolves.
• Safety net: woocommerce_add_to_cart action removes any FPP cart item that was added without a photo (catches edge cases where validation was bypassed).
• Product detection uses resolve_fpp_product_id() which checks the product itself, its parent, and the variation's parent to handle all add-to-cart methods.

On page reload, the previously uploaded file is restored — the upload preview and product gallery image are reconstructed from whichever transport currently carries the reference (WC session or the cookie pair). When the photo is removed, both are cleared and the original product image is restored. Add-to-cart buttons always look and behave normally — blocking is entirely server-side.

Shortcode

The shortcode can be used to embed the product with its variation selector and upload area on any page:

[studiou_free_photo_product id="123"]

Replace 123 with your product ID. The shortcode renders:

• Product image, name, and short description
• WooCommerce native variation selector and Add to Cart form
• Upload area with drag-and-drop, progress bar, and preview (injected into the form)

Accepted File Formats

JPEG, PNG, TIFF, BMP, PSD, WebP, and camera RAW formats: CR2 (Canon), NEF (Nikon), ARW (Sony), DNG (Adobe), ORF (Olympus), RW2 (Panasonic), RAF (Fuji).

Chunked Upload

Files are uploaded in 1 MB chunks via AJAX to bypass PHP upload_max_filesize and post_max_size limits. The server assembles chunks into the final file, creates a WordPress media attachment, and assigns it to the configured media category. The chunk size is defined by the STUDIOU_WCFPP_CHUNK_SIZE constant.

Admin Summary Page

Navigate to Products > Free Photo Files to manage uploaded files.

Features

• Filter by status (Ready / Downloaded / Solved), product, or file name search
• Inline status change per file via dropdown
• Single file download (automatically marks status as "downloaded" if currently "ready")
• Single file delete with media attachment cleanup
• Bulk actions with confirmation dialogs: Download as ZIP, Set Status (Ready / Downloaded / Solved), Delete
• Downloads always serve the original, unscaled file. WordPress auto-creates a -scaled.jpg for images above the big-image threshold (2560 px by default), but both single and ZIP downloads use wp_get_original_image_path() to return the raw upload.
• Order number links (HPOS-compatible)
• Customer name display
• Pagination (30 files per page, preserves active filters across pages)

File Statuses

Status	Meaning
Ready	File uploaded, awaiting processing
Downloaded	File has been downloaded by admin (set automatically on download)
Solved	File has been printed / order fulfilled

Cart and Order Integration

The plugin integrates with WooCommerce's native add-to-cart flow using the resolve_uploaded_file() helper that reads WC session first and then the studiou_fpp_att_id / studiou_fpp_rec_id cookie pair as a fallback. When a photo is uploaded, the file reference is written to both transports in the same request that assembles the file. When any add-to-cart button is clicked — whether it goes through classic admin-ajax or the WC Store API — woocommerce_add_cart_item_data runs the same resolver and attaches the file data to the cart item. Both the session and the cookies persist so the same photo can be reused for multiple variants. The woocommerce_add_to_cart_validation filter uses the same resolver to ensure a photo is uploaded before the item can be added. This approach works with any theme or plugin that handles variable product display (individual variation buttons, dropdowns, tables, Store API block cart, etc.).

When a customer adds a photo product to the cart:

• The cart item thumbnail shows the uploaded photo — works with both classic cart (woocommerce_cart_item_thumbnail filter) and block cart (woocommerce_product_get_image_id / woocommerce_product_variation_get_image_id filters that override the product image for the Store API)
• The uploaded file name is shown as "Uploaded Photo" in the cart
• On checkout, the file record is linked to the order and order item
• In the order admin, order item thumbnails show the uploaded photo instead of the product image
• The uploaded photo file name appears as order item metadata
• A Download uploaded photo button with the original file name is shown below the order item meta in admin (downloading automatically marks the file status as "downloaded")
• Files linked to orders cannot be removed by the customer

Media Categories

The plugin registers a custom taxonomy studiou_media_category on the attachment post type. Categories are visible in the Media Library admin column and can be managed from:

• Free Photo product tab (inline add via "+" button)
• Media Library sidebar

Each product has one assigned media category. All files uploaded for that product are tagged with it.

HPOS Support

The plugin declares full compatibility with WooCommerce High-Performance Order Storage (HPOS / Custom Order Tables). Order edit links in the admin summary page use the correct URL format based on whether HPOS is enabled.

Localization

Supported languages:

• English (default)
• Czech (cs_CZ)

Translation files are in the languages/ directory.

To compile the .mo file from .po:

# Using the included helper script
php languages/generate-mo.php

# Or using WP-CLI
wp i18n make-mo languages/

# Or using gettext
msgfmt languages/studiou-wc-free-photo-product-cs_CZ.po -o languages/studiou-wc-free-photo-product-cs_CZ.mo

Text domain: studiou-wc-free-photo-product

Database

The plugin creates one custom table on activation:

{prefix}studiou_fpp_files

Column	Type	Description
id	bigint	Primary key
product_id	bigint	WC product ID
variation_id	bigint	WC variation ID
order_id	bigint	WC order ID (set on checkout)
order_item_id	bigint	WC order item ID (set on checkout)
attachment_id	bigint	WP media attachment ID
customer_id	bigint	WP user ID (0 for guests)
session_key	varchar(64)	WC session key for guest users
file_name	varchar(255)	Original uploaded file name
status	varchar(20)	ready / downloaded / solved
created_at	datetime	Upload timestamp
updated_at	datetime	Last update timestamp

File Structure

studiou-wc-free-photo-product/
├── studiou-wc-free-photo-product.php        Main plugin file
├── includes/
│   ├── class-studiou-wc-fpp-db.php          Database + media taxonomy
│   ├── class-studiou-wc-fpp-product.php     Product data tab
│   ├── class-studiou-wc-fpp-upload.php      Chunked upload handler
│   ├── class-studiou-wc-fpp-shortcode.php   Shortcode renderer
│   ├── class-studiou-wc-fpp-single-product.php  Product page upload area
│   ├── class-studiou-wc-fpp-cart.php        Cart/order integration (native WC flow)
│   ├── class-studiou-wc-fpp-admin.php       Admin summary page
│   └── class-studiou-wc-fpp-pricing.php     Per-variation quantity discount tiers
├── views/
│   ├── frontend-product.php                 Shortcode template
│   ├── single-product-upload.php            Upload area for product page
│   └── admin-summary.php                    Admin file list template
├── assets/
│   ├── css/admin.css                        Admin styles
│   ├── css/frontend.css                     Frontend styles
│   ├── js/admin.js                          Admin JS
│   └── js/frontend.js                       Frontend JS (chunked upload)
└── languages/
    ├── studiou-wc-free-photo-product.pot    Translation template
    ├── studiou-wc-free-photo-product-cs_CZ.po  Czech translation
    └── generate-mo.php                      MO file generator

Hooks and Filters

AJAX Actions

Action	Auth	Description
studiou_wcfpp_upload_chunk	Both	Upload a file chunk
studiou_wcfpp_remove_upload	Both	Remove an uploaded file (pre-order)
studiou_wcfpp_set_upload_session	Both	Store uploaded file reference in WC session
studiou_wcfpp_clear_upload_session	Both	Clear uploaded file reference from WC session
studiou_wcfpp_add_media_category	Admin	Create a new media category
studiou_wcfpp_update_status	Admin	Update single file status
studiou_wcfpp_bulk_status	Admin	Bulk update file statuses
studiou_wcfpp_delete_files	Admin	Delete files (single or bulk)
studiou_wcfpp_download_zip	Admin	Generate ZIP of selected files

WooCommerce Hooks Used

Hook	Type	Description
woocommerce_single_product_summary (priority 35)	Action	Renders upload area below the variation table
woocommerce_add_to_cart_validation	Filter	Validates photo is uploaded
woocommerce_add_cart_item_data	Filter	Captures file data into cart item
woocommerce_cart_item_thumbnail	Filter	Replaces cart item thumbnail (classic cart)
woocommerce_product_get_image_id	Filter	Returns uploaded photo as product image (block cart)
woocommerce_product_variation_get_image_id	Filter	Returns uploaded photo as variation image (block cart)
woocommerce_get_item_data	Filter	Displays file name in cart
woocommerce_checkout_create_order_line_item	Action	Saves file meta to order item
woocommerce_checkout_order_processed	Action	Links file record to order (classic checkout)
woocommerce_store_api_checkout_order_processed	Action	Links file record to order (block checkout)
woocommerce_thankyou	Action	Fallback linking on thank-you page
woocommerce_admin_order_item_thumbnail	Filter	Replaces order item thumbnail with uploaded photo
woocommerce_after_order_itemmeta	Action	Shows download link for uploaded photo in order admin
woocommerce_product_data_tabs	Filter	Adds Free Photo product tab
woocommerce_product_data_panels	Action	Renders Free Photo settings panel
woocommerce_process_product_meta	Action	Saves Free Photo product meta
woocommerce_variation_options_pricing (priority 20)	Action	Renders the quantity discount tier editor on each variation panel
woocommerce_save_product_variation	Action	Sanitizes and saves quantity discount tiers per variation
woocommerce_available_variation	Filter	Injects tier data into the variations form JSON so the frontend JS can render the tier table and live price
woocommerce_before_calculate_totals (priority 20)	Action	Applies the quantity discount to the cart item's product via set_price()

Product Meta Keys

Key	Description
_studiou_fpp_enabled	"yes" / "no"
_studiou_fpp_media_category	Term ID of media category
_studiou_fpp_max_file_size	Max upload size in MB
_studiou_fpp_min_width	Min image width in px (0 = no limit)
_studiou_fpp_min_height	Min image height in px (0 = no limit)
_studiou_fpp_max_width	Max image width in px (0 = no limit)
_studiou_fpp_max_height	Max image height in px (0 = no limit)

Variation Meta Keys

Key	Description
_studiou_fpp_qty_tiers	Array of {from_qty, percent} rows defining the quantity discount tier table for the variation (sorted ascending by from_qty)

Order Item Meta Keys

Key	Description
_studiou_fpp_attachment_id	WP attachment ID
_studiou_fpp_file_record_id	File record ID in custom table
_studiou_fpp_file_name	Original file name
_studiou_fpp_thumb_url	Thumbnail URL (for reliable display)

License

GPL v2 or later

Author

Dalibor Votruba - quadarax.com