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

CLAUDE.md - Studiou WC Free Photo Product

Project Overview

WordPress/WooCommerce plugin called studiou-wc-free-photo-product (QDR - Studiou WC Free Photo Product) v1.0.0. Allows publishing special variable products where customers upload custom raw images to be printed for a price.

Initial Requirements

1. WP (6.9.4) / WooCommerce (10.6.2) plugin with variants and custom raw image upload for photo printing. Frontend shows product with upload box, preview, and variant table.
2. Product configuration area: Media Category for uploaded files, Maximum raw file size. Shortcode to embed product on any page.
3. Uploaded raw files stored in WP media library with a specific media category per product. Chunked upload to bypass PHP upload size limits. Media files linked with product.
4. Admin summary page: list of uploaded files, download as ZIP (bulk), order number, delete, change state (downloaded, ready, solved).
5. HPOS support and localization (English, Czech).

Tech Stack

• PHP 8.2+, WordPress 6.9.4+, WooCommerce 10.0+
• jQuery for frontend/admin JS
• WordPress AJAX (admin-ajax.php) for all async operations
• Custom DB table via dbDelta for file tracking
• Custom taxonomy studiou_media_category on attachment post type

Architecture

• Main class: Studiou_WC_Free_Photo_Product in root plugin file
• Constants prefix: STUDIOU_WCFPP_
• CSS class prefix: studiou-fpp-
• JS namespace: studiouWcfppFront (frontend), studiouWcfpp (admin)
• Nonces: studiou-wcfpp-front-nonce (frontend), studiou-wcfpp-nonce (admin)
• Text domain: studiou-wc-free-photo-product

Key Classes

• Studiou_WC_FPP_DB - Custom table CRUD, media category taxonomy
• Studiou_WC_FPP_Product - WC product data tab, product meta
• Studiou_WC_FPP_Upload - Chunked upload AJAX, file assembly, attachment creation
• Studiou_WC_FPP_Shortcode - [studiou_free_photo_product id="X"]
• Studiou_WC_FPP_Cart - Cart item data, order item meta, order linking
• Studiou_WC_FPP_Admin - Summary page, status management, ZIP download

Coding Conventions

• Follow patterns from sibling plugin studiou-wc-product-cat-manage
• All PHP files start with if (!defined('WPINC')) { die; }
• AJAX handlers: verify nonce, check capabilities, try/catch with WP_DEBUG logging
• Output buffer cleanup in AJAX handlers
• Use wp_send_json_success / wp_send_json_error for all AJAX responses
• All user-facing strings wrapped in __() or esc_html_e() with text domain
• Sanitize all inputs: absint(), sanitize_text_field(), sanitize_file_name()
• Escape all outputs: esc_html(), esc_attr(), esc_url(), wp_kses_post()

Build / Deploy Notes

• Generate .mo from .po: php languages/generate-mo.php or wp i18n make-mo languages/
• Plugin creates DB table on activation via register_activation_hook
• Temp chunks stored in wp-content/uploads/studiou-fpp-chunks/ (cleaned on deactivation)
• Assembled files stored in wp-content/uploads/YYYY/MM/free-photo/

Version Bumping

When changing JS or CSS files, always bump the plugin version in the main PHP file header AND the STUDIOU_WCFPP_VERSION constant to bust browser cache.