Implementation Plan — Update Product Variant Prices (UPVP)

Target version: 1.5.3 (bump from current 1.5.2) Scope: Add a new section "Update product variant prices" to the existing Category Manipulations admin page. Goal: Allow admins to bulk-update the regular price of product variations by filtering on (a) one or more product categories and (b) a single variation attribute name + value pair. Provide a Dry Run preview, an Apply commit, and a live affected-count label. Operation must touch only product_variation records — never order items, carts, or order history.

1. Feature summary

On the page Products → Category Manipulations, append a new card titled "Update product variant prices" placed before the Important Notes card and after the Remove Not Assigned Media card. It contains:

Categories checkbox list — product-category tree (re-using the existing studiou-wcpcm-categories-list-container markup and styles). With Check All / Uncheck All buttons.
Variant attribute combobox — populated with the list of attribute names (heads) that are used for variations across the WooCommerce store (global pa_* taxonomies + product-level custom attributes flagged "used for variations").
Variant value combobox — populated dynamically based on the selected attribute (and scoped to the currently checked categories). Lists distinct values that exist on real variations.
New Price textbox — numeric input (type=number, step=0.01, min=0); server normalises with wc_format_decimal.
Dry Run button — counts and lists the variations that would be updated, without writing.
Apply button — saves set_regular_price() to all matching variations via the WooCommerce API.
Affected-count label — live counter; recalculated when filters change, after Dry Run, and after Apply.

Operation only modifies regular_price on product_variation posts. Sale prices, order line items, cart sessions and historical order data are not touched.

2. Files to create / modify

2.1 New files

(none) — all new logic fits into existing classes / views.

2.2 Modified files

File	Change
`studiou-wc-product-cat-manage.php`	Bump `Version:` header and `STUDIOU_WCPCM_VERSION` to `1.5.3`. Extend the `i18n` map in `wp_localize_script` with new UPVP strings.
`includes/class-studiou-wc-product-cat-manage-manipulator.php`	Add 4 new public AJAX handlers + 4 helper methods (see §3). Register the 4 actions in the constructor's `add_action(...)` block.
`views/manipulations.php`	Append the new "Update product variant prices" card before the Important Notes card.
`assets/css/admin.css`	Minor styling for the new section (results panel, affected-count label, preview table).
`assets/js/admin.js`	Add `initUpdateVariantPricesForm()` wrapped in the existing `safeInit()` pattern.
`languages/studiou-wc-product-cat-manage.pot`	Add new translation strings.
`languages/studiou-wc-product-cat-manage-cs_CZ.po`	Add Czech translations.
`languages/studiou-wc-product-cat-manage-cs_CZ.mo`	Regenerate (`msgfmt`).
`readme.md`	Bump version, new section in Features, new usage section, Version 1.5.3 changelog entry.
`CLAUDE.md`	Bump Current Version to 1.5.3, add 4 new methods to manipulator bullets, add 4 new AJAX endpoints, add bullet under Admin Menu Structure → Category Manipulations.
`directory-structure.txt`	No structural change — verify it still matches reality.

3. Backend implementation

All backend work goes into class-studiou-wc-product-cat-manage-manipulator.php. We extend the existing manipulator because UPVP is conceptually a category manipulation and shares helpers (get_categories_with_counts, AJAX boilerplate) with the existing manipulator. No new class.

3.1 New AJAX action registrations

Add inside Studiou_WC_Product_Cat_Manage_Manipulator::__construct(), alongside the existing add_action('wp_ajax_studiou_wcpcm_*', ...) lines:

add_action('wp_ajax_studiou_wcpcm_upvp_get_attributes',       array($this, 'handle_upvp_get_attributes_ajax'));
add_action('wp_ajax_studiou_wcpcm_upvp_get_attribute_values', array($this, 'handle_upvp_get_attribute_values_ajax'));
add_action('wp_ajax_studiou_wcpcm_upvp_count',                array($this, 'handle_upvp_count_ajax'));
add_action('wp_ajax_studiou_wcpcm_upvp_apply',                array($this, 'handle_upvp_apply_ajax'));

Each handler follows the established pattern in the file:

while (ob_get_level()) ob_end_clean(); ob_start();
error_reporting(0) save/restore.
wp_verify_nonce($_POST['nonce'], 'studiou-wcpcm-nonce').
current_user_can('manage_woocommerce').
try { ... } catch(Exception $e) { ... } finally { restore + ob_end_clean(); }.
Always-on error logging consistent with STUDIOU WC MEDIA: style — prefix STUDIOU WC UPVP:.

3.2 New methods on `Studiou_WC_Product_Cat_Manage_Manipulator`

/** Return list of attribute "heads" (names) usable for variations. */
public function get_variation_attribute_heads(): array
// Returns: [ ['key' => 'pa_color', 'label' => 'Color', 'is_taxonomy' => true], ... ]
// Source 1: every wc_get_attribute_taxonomies() entry (global attributes) -> key = 'pa_<slug>'
// Source 2: distinct meta_key starting with 'attribute_' on post_type='product_variation'
//           (covers custom non-taxonomy attributes flagged for variations)
//           -> key = substring after 'attribute_' (NOT prefixed with 'pa_')
// De-duplicate by key, sort by human label asc.

/** Return distinct values for a given attribute key, scoped to existing variations. */
public function get_variation_attribute_values(string $attribute_key, array $category_ids = []): array
// Returns: [ ['value' => 'red', 'label' => 'Red'], ... ] sorted by label.
// SQL strategy:
//   SELECT DISTINCT pm.meta_value
//     FROM {$wpdb->postmeta} pm
//     INNER JOIN {$wpdb->posts} v        ON v.ID = pm.post_id AND v.post_type = 'product_variation'
//                                                              AND v.post_status IN ('publish','private')
//     INNER JOIN {$wpdb->posts} p        ON p.ID = v.post_parent AND p.post_type = 'product'
//     [INNER JOIN {$wpdb->term_relationships} tr ON p.ID = tr.object_id
//      INNER JOIN {$wpdb->term_taxonomy}     tt ON tr.term_taxonomy_id = tt.term_taxonomy_id
//      WHERE tt.taxonomy = 'product_cat' AND tt.term_id IN (...)]
//    AND pm.meta_key = 'attribute_<sanitized key>'
//    AND pm.meta_value <> ''
// For taxonomy attributes (pa_*): meta_value is the term slug -> resolve labels via get_term_by('slug', ..., 'pa_<key>').
// For non-taxonomy: meta_value is already the label.
// All input goes through wc_sanitize_taxonomy_name() / sanitize_text_field. Use $wpdb->prepare with %d/%s placeholders.

/** Count + list variations that match the filter. */
public function find_matching_variations(array $category_ids, string $attribute_key, string $attribute_value): array
// Returns:
//   [
//     'count'  => int,
//     'ids'    => int[],          // all matching variation IDs
//     'sample' => array[]         // up to 20 entries:
//                                 //   [ 'id', 'sku', 'name', 'parent_name', 'current_price' ]
//   ]
// Same JOIN as above but selecting v.ID. Reads sample with WC API (wc_get_product) capped at 20.
// Uses $wpdb->prepare with implode(',', array_fill(0, count($category_ids), '%d')) for the IN list.

/** Apply new price to a list of variation IDs. */
public function apply_variant_price(array $variation_ids, string $new_price): array
// Returns ['updated'=>int, 'failed'=>int, 'failed_ids'=>int[], 'message'=>string].
// Steps for each ID:
//   $variation = wc_get_product($id);
//   if (!$variation || !$variation->is_type('variation')) { failed[] = id; continue; }
//   $variation->set_regular_price(wc_format_decimal($new_price));
//   $variation->save();
// After loop: foreach (unique parent_id) WC_Product_Variable::sync($parent_id);
//             wc_delete_product_transients($parent_id);
// Validation guard at entry: must be numeric, >= 0; otherwise return error.

3.3 Handler responsibilities (inputs → outputs)

Handler	Input ($_POST)	`data` on success
`handle_upvp_get_attributes_ajax`	`nonce`	`attributes: [{key,label,is_taxonomy}]`
`handle_upvp_get_attribute_values_ajax`	`nonce`, `attribute_key`, `category_ids[]` (optional)	`values: [{value,label}]`
`handle_upvp_count_ajax`	`nonce`, `category_ids[]`, `attribute_key`, `attribute_value`	`count, sample[]`
`handle_upvp_apply_ajax`	`nonce`, `category_ids[]`, `attribute_key`, `attribute_value`, `new_price`	`updated, failed, failed_ids, message`

All array inputs run through array_map('intval', ...); strings through sanitize_text_field; attribute_key additionally through wc_sanitize_taxonomy_name. The price stays raw, normalised in apply_variant_price.

3.4 Edge cases handled

Empty category list → error "Please select at least one category".
Empty attribute key → error.
Empty attribute value → error.
Non-numeric / negative price → error before any DB write.
Variation belongs to a non-variable parent (orphan) → counted as failed.
Attribute key collision between a taxonomy attribute and a same-labelled custom attribute — disambiguated by storing the full key (pa_color vs color) in the combobox value, not the label.
Order-line price preservation — operation never touches woocommerce_order_itemmeta. Document this explicitly in the Important Notes card and changelog.
Parent variable product price-range cache — re-synced via WC_Product_Variable::sync($parent_id) after the batch so the storefront price range stays correct.

4. Frontend implementation

4.1 View — `views/manipulations.php`

Insert a new card immediately before the existing  card:

<!-- Update Product Variant Prices Operation -->
<div class="studiou-wcpcm-card">
    <h2><?php echo esc_html__('Update product variant prices', 'studiou-wc-product-cat-manage'); ?></h2>

    <p><?php echo esc_html__('Bulk-update the regular price of product variations matching the selected categories and a chosen variation attribute. Only product records are modified — existing orders and cart contents are not affected.', 'studiou-wc-product-cat-manage'); ?></p>

    <form id="studiou-wcpcm-upvp-form" method="post" onsubmit="return false;">
        <table class="form-table">
            <!-- 1. Category checkbox list -->
            <tr>
                <th scope="row">
                    <label for="upvp_categories_list"><?php echo esc_html__('Select Categories', 'studiou-wc-product-cat-manage'); ?></label>
                </th>
                <td>
                    <div class="studiou-wcpcm-categories-list-container">
                        <div class="studiou-wcpcm-list-actions">
                            <button type="button" id="studiou-wcpcm-upvp-check-all" class="button">
                                <?php echo esc_html__('Check All', 'studiou-wc-product-cat-manage'); ?>
                            </button>
                            <button type="button" id="studiou-wcpcm-upvp-uncheck-all" class="button">
                                <?php echo esc_html__('Uncheck All', 'studiou-wc-product-cat-manage'); ?>
                            </button>
                        </div>
                        <div class="studiou-wcpcm-categories-list" id="upvp_categories_list">
                            <?php foreach ($categories as $category): ?>
                                <label class="studiou-wcpcm-category-item">
                                    <input type="checkbox" name="upvp_categories[]" value="<?php echo esc_attr($category['id']); ?>">
                                    <span><?php echo esc_html($category['display_name']); ?></span>
                                </label>
                            <?php endforeach; ?>
                        </div>
                    </div>
                </td>
            </tr>

            <!-- 2. Variant attribute combobox -->
            <tr>
                <th scope="row">
                    <label for="upvp_attribute"><?php echo esc_html__('Variant attribute', 'studiou-wc-product-cat-manage'); ?></label>
                </th>
                <td>
                    <select id="upvp_attribute" name="upvp_attribute" class="regular-text">
                        <option value=""><?php echo esc_html__('-- Select attribute --', 'studiou-wc-product-cat-manage'); ?></option>
                    </select>
                </td>
            </tr>

            <!-- 3. Variant value combobox -->
            <tr>
                <th scope="row">
                    <label for="upvp_attribute_value"><?php echo esc_html__('Variant attribute value', 'studiou-wc-product-cat-manage'); ?></label>
                </th>
                <td>
                    <select id="upvp_attribute_value" name="upvp_attribute_value" class="regular-text" disabled>
                        <option value=""><?php echo esc_html__('-- Select value --', 'studiou-wc-product-cat-manage'); ?></option>
                    </select>
                </td>
            </tr>

            <!-- 4. New price -->
            <tr>
                <th scope="row">
                    <label for="upvp_new_price"><?php echo esc_html__('New Price', 'studiou-wc-product-cat-manage'); ?></label>
                </th>
                <td>
                    <input type="number" step="0.01" min="0" id="upvp_new_price" name="upvp_new_price" class="regular-text">
                </td>
            </tr>

            <!-- 6. Affected-count label -->
            <tr>
                <th scope="row">
                    <?php echo esc_html__('Affected variations', 'studiou-wc-product-cat-manage'); ?>
                </th>
                <td>
                    <strong id="studiou-wcpcm-upvp-affected-count">0</strong>
                </td>
            </tr>
        </table>

        <!-- 5. Buttons -->
        <div class="submit-buttons">
            <button type="button" id="studiou-wcpcm-upvp-dry-run-button" class="button">
                <?php echo esc_html__('Dry Run', 'studiou-wc-product-cat-manage'); ?>
            </button>
            <button type="button" id="studiou-wcpcm-upvp-apply-button" class="button button-primary">
                <?php echo esc_html__('Apply', 'studiou-wc-product-cat-manage'); ?>
            </button>
            <span class="spinner"></span>
        </div>
    </form>

    <div class="studiou-wcpcm-upvp-results" style="display: none;">
        <h3><?php echo esc_html__('Results', 'studiou-wc-product-cat-manage'); ?></h3>
        <div id="studiou-wcpcm-upvp-message"></div>
    </div>
</div>

$categories is already populated above via $manipulator->get_categories_with_counts().

4.2 JS — `assets/js/admin.js`

Add a single initUpdateVariantPricesForm() and register it inside the existing $(document).ready() block via the existing safeInit() wrapper:

safeInit('upvpForm', function() {
    if ($('#studiou-wcpcm-upvp-form').length) initUpdateVariantPricesForm();
});

Logic:

On init — request studiou_wcpcm_upvp_get_attributes; populate #upvp_attribute with <option value="key" data-istax="0|1">label</option>.
Check All / Uncheck All — same pattern as the existing batch-description and delete-products handlers.
On #upvp_attribute change — clear #upvp_attribute_value; if non-empty attribute, call studiou_wcpcm_upvp_get_attribute_values (passing currently-checked categories so the value list is scoped); enable the value combobox after population. Trigger affected-count refresh.
On any filter change (categories checkboxes, attribute, value) — debounced (300 ms) call to studiou_wcpcm_upvp_count; update #studiou-wcpcm-upvp-affected-count. Disable both Dry Run and Apply buttons while a count request is in-flight or while the count is 0.
Dry Run click — call count endpoint with full filter; render a results panel containing a small <table class="studiou-wcpcm-upvp-preview-table"> listing the sample variations: ID, SKU, Name, Parent, Current → New Price.
Apply click — JS confirm() ("This will update X variations. Continue?"); on accept, POST studiou_wcpcm_upvp_apply with the same filter + new price; on success render summary (updated, failed, failed_ids[]) and refresh the affected-count.

All XHR calls follow the existing AJAX boilerplate: spinner, notice area, console.log debug lines, showNotice() helper.

4.3 CSS — `assets/css/admin.css`

Append:

.studiou-wcpcm-upvp-results {
    background: #f9f9f9;
    padding: 15px;
    border: 1px solid #ddd;
    border-radius: 4px;
    margin-top: 30px;
}

#studiou-wcpcm-upvp-affected-count {
    font-size: 1.2em;
    color: #0073aa;
}

.studiou-wcpcm-upvp-preview-table {
    width: 100%;
    border-collapse: collapse;
    margin-top: 10px;
}

.studiou-wcpcm-upvp-preview-table th,
.studiou-wcpcm-upvp-preview-table td {
    padding: 6px 10px;
    border-bottom: 1px solid #eee;
    text-align: left;
}

5. Translations

Add the following new English → Czech strings; register in the .pot, the cs_CZ.po, and recompile cs_CZ.mo with msgfmt.

English	Czech
Update product variant prices	Aktualizace cen variant produktů
Bulk-update the regular price of product variations matching the selected categories and a chosen variation attribute. Only product records are modified — existing orders and cart contents are not affected.	Hromadná aktualizace běžné ceny variant produktů odpovídajících vybraným kategoriím a zvolené vlastnosti varianty. Mění se pouze záznamy produktů — existující objednávky a obsah košíku nejsou dotčeny.
Variant attribute	Vlastnost varianty
Variant attribute value	Hodnota vlastnosti varianty
-- Select attribute --	-- Vyberte vlastnost --
-- Select value --	-- Vyberte hodnotu --
New Price	Nová cena
Dry Run	Zkušební běh
Apply	Provést
Affected variations	Dotčené varianty
Results	Výsledky
No variations match the current filter.	Žádné varianty neodpovídají vybranému filtru.
Successfully updated %d variations.	Úspěšně aktualizováno %d variant.
Failed to update %d variations.	Nepodařilo se aktualizovat %d variant.
Are you sure you want to update %d variations?	Opravdu chcete aktualizovat %d variant?
Please select an attribute	Vyberte prosím vlastnost
Please select an attribute value	Vyberte prosím hodnotu vlastnosti
Please enter a valid new price	Zadejte prosím platnou novou cenu
Loading attributes...	Načítání vlastností...
Loading values...	Načítání hodnot...
Dry run complete: %d variations would be updated to %s.	Zkušební běh dokončen: %d variant bude aktualizováno na %s.
Variant prices updated successfully	Ceny variant úspěšně aktualizovány
Variant prices update error	Chyba aktualizace cen variant
The update product variant prices operation only modifies the regular price of product variations. Order line items, cart contents, and historical order data are never modified.	Operace aktualizace cen variant mění pouze běžnou cenu variant produktů. Položky objednávek, obsah košíku ani historická data objednávek nejsou nikdy měněny.

Add matching keys to the i18n array in wp_localize_script(... 'studiouWcpcm', ...) in studiou-wc-product-cat-manage.php: upvpConfirmApply, upvpSelectAttribute, upvpSelectValue, upvpInvalidPrice, upvpLoadingAttributes, upvpLoadingValues, upvpDryRunComplete, upvpApplySuccess, upvpApplyError, upvpNoMatches.

6. Documentation updates

6.1 `readme.md`

Bump **Version: 1.5.2** → **Version: 1.5.3**.
Under Features → Category Management, add: **Update product variant prices** - bulk-update regular price of variations by category + attribute filter (NEW in v1.5.3).
Under Menu Structure → Category Management → Category Manipulations sub-list, add: Update product variant prices (NEW in v1.5.3).
Add a new usage section "Updating Product Variant Prices" mirroring the structure of the existing Manipulation usage sections, with the 6 controls listed and notes:
- Operation modifies only regular_price of product_variation records.
- Order line items, carts and historical data are not affected.
- Always run Dry Run first to preview the affected count and sample list.
- Parent variable products are re-synced (WC_Product_Variable::sync) after the batch so the storefront price range cache stays correct.

Append changelog entry Version 1.5.3 above 1.5.2:

### Version 1.5.3
- **NEW: Update product variant prices** - bulk-update regular price of product variations
- Filter by selected product categories (with Check All / Uncheck All)
- Variant attribute combobox (heads), populated from variation-eligible attributes
- Variant value combobox, dynamically scoped to the chosen attribute and selected categories
- New Price textbox with numeric validation
- Dry Run button shows affected count + sample preview, no DB writes
- Apply button commits via WooCommerce API (`set_regular_price` + `WC_Product_Variable::sync`)
- Live affected-count label updates on every filter change
- 4 new AJAX handlers: `studiou_wcpcm_upvp_get_attributes`, `studiou_wcpcm_upvp_get_attribute_values`, `studiou_wcpcm_upvp_count`, `studiou_wcpcm_upvp_apply`
- Operation never touches order items, cart sessions, or historical order data
- Added 23 new translation strings (English/Czech)

6.2 `CLAUDE.md`

Bump Current Version 1.5.2 → 1.5.3.
Under class-studiou-wc-product-cat-manage-manipulator.php bullet list, add: Update product variant prices (regular_price only, by category + attribute filter) (NEW in v1.5.3).
Under Views (views/) → manipulations.php, add: Update product variant prices (checkbox list + 2 comboboxes + price input + Dry Run/Apply buttons + live affected-count label) (NEW in v1.5.3).
Under Admin Menu Structure → Category Manipulations, add bullet: Update product variant prices (NEW in v1.5.3).
Under AJAX Handlers → Category Operations, append entries 11–14:
- studiou_wcpcm_upvp_get_attributes — list variation attribute heads (NEW in v1.5.3)
- studiou_wcpcm_upvp_get_attribute_values — list values for selected attribute (NEW in v1.5.3)
- studiou_wcpcm_upvp_count — count + sample of variations matching current filter (NEW in v1.5.3)
- studiou_wcpcm_upvp_apply — commit new regular price to matching variations (NEW in v1.5.3)
Renumber the Product Operations section (currently starts at 11) accordingly.
Add Testing Notes → Update Product Variant Prices Operations (NEW in v1.5.3) section listing the test cases from §7 below.

6.3 `directory-structure.txt`

No structural change. Verify it is still accurate (existing classes get methods added; no new files).

7. Step-by-step execution order

Bump version constant + plugin header to 1.5.3.
Implement get_variation_attribute_heads, get_variation_attribute_values, find_matching_variations, apply_variant_price in Studiou_WC_Product_Cat_Manage_Manipulator (no AJAX yet).
Add the 4 AJAX handler methods + register them in the constructor.
Append the UPVP card to views/manipulations.php (before Important Notes).
Add CSS rules.
Add initUpdateVariantPricesForm() to admin.js, hook through existing safeInit().
Extend wp_localize_script i18n map with new keys.
Update .pot, cs_CZ.po; regenerate cs_CZ.mo with msgfmt.
Update readme.md, CLAUDE.md. Verify directory-structure.txt.
Manual smoke test — see §8.
Hard-refresh in browser (studiou.cz strips ?ver= query strings — note in commit message).

8. Test plan

Manual UI tests on a dev WC store with at least one variable product per fixture below:

Happy path (taxonomy attribute) — Pick 1 category containing variable products with pa_color = red. Pick attribute Color, value Red, price 19.99. Affected-count updates as filters change. Dry Run shows correct count + sample table. Apply → updated count matches; spot-check a variation in WP admin shows new regular price; parent variable product price range reflects the update.
Happy path (custom non-taxonomy attribute) — Same flow on a product whose Size attribute is product-level (not global).
Multi-category — Select two sibling categories; variations counted only once each.
No matches — Filter that yields zero variations: Apply button stays disabled, label shows 0.
Invalid price — Empty / negative / non-numeric → error notice, no DB write.
Permission — User without manage_woocommerce cannot trigger AJAX.
Nonce — Tampered nonce → Security check failed.
Order data integrity — Place a test order with a variation, run UPVP, confirm the order line item retains the original price.
Translations — Switch site to cs_CZ, confirm UPVP labels render in Czech.
Cache busting — Asset version query string updates from 1.5.2 to 1.5.3. Hard-refresh on studiou.cz.
Parent re-sync — After Apply, variable-product price range on storefront reflects the new regular price (sync transient cleared via wc_delete_product_transients).

9. Rollback

Purely additive change — no schema migrations, no destructive operations, no changes to existing handlers. To roll back: revert the listed files to 1.5.2 and re-enqueue assets. No data cleanup required because UPVP only writes to existing product_variation records' _regular_price postmeta via the WC API.

inplementation-plan-upvp.md 26 KB Bezpośredni odnośnik Historia Czysty