Multiple Variations Support #235

faisal-alvi · 2024-11-13T13:52:26Z

All Submissions:

Does your code follow the WooCommerce Sniffs variant of WordPress coding standards?
Have you written new tests for your changes, as applicable?
Have you successfully run tests with your changes locally?
Will this change require new documentation or changes to existing documentation?

Changes proposed in this Pull Request:

This PR adds support for Multiple Variations.

Square and WooCommerce Attribute Types

Square options:
- Dynamic Options: Shared across multiple items, similar to WooCommerce’s taxonomy attributes; variation names cannot be changed.
- Static Options: Unique to individual items; variation names can be changed.
WooCommerce attributes:
- Taxonomy: Defined globally across products.
- Custom: Defined on a per-product basis.

Key Differences Between Dynamic and Static Options

Dynamic options can be shared across products and mirror WooCommerce’s taxonomy attributes, and variation names cannot be modified, as they are automatically generated by combining the attribute values. For example: “Red, Small.” Static options are unique to each item. If multiple options exist at Square, they must be dynamic.

Syncing Logic (Overview)

WooCommerce to Square Sync:
- Creates dynamic options if there are multiple WooCommerce attributes, regardless of the WooCommerce's attributes type.
- For a single attribute, it creates a static option at Square.
Square to WooCommerce Sync/Import:
- Creates taxonomy attributes if the option slug matches an existing WooCommerce taxonomy attribute.
- If only one option is received, it checks for an existing WooCommerce taxonomy attribute or creates a custom attribute if no match is found.

Syncing Logic for WooCommerce and Square (Detail)

From WooCommerce to Square:

If WooCommerce has more than one attribute and is set as the Source of Record (SOR), this PR will create dynamic options at Square, regardless of whether the attributes are taxonomy or custom. This is because we cannot create more than one static options for the single item (i.e product) at Square.
If there’s only one attribute, it creates a static option at Square.
If an attribute requires syncing, the PR creates an option at Square. New attribute values are also created at Square when synced from WooCommerce.

From Square to WooCommerce:

If the option name received from Square matches the slug of an existing WooCommerce taxonomy attribute, this PR creates a taxonomy attribute. If the merchant updates the slug in WooCommerce, it may not match next time and a custom attribute will be created instead.
If only one option is received, this PR checks against existing WooCommerce taxonomy attributes and attaches it if matched; otherwise, it creates a custom attribute at the product level. When creating a custom attribute, the PR reuses an existing custom attribute name, as Square does not provide the static option name. If no matching name exists, "Attribute" is assigned as the custom name.

Square API Limitations and Solutions

Square’s API only provides the option ID used in variations, not the display name. However, to match WooCommerce taxonomy attributes or to create a custom attribute, we need the option's display name. To address this, we fetch all options via another Square API (discussion link) and store the option names and their IDs in a transient (wc_square_options_data) with a 1-day expiration. The fetch_options_data() function initiates this before any import or sync process.

If a transient doesn’t have updated data, a sync may fail when creating an option with a name that already exists at Square, which would require a latest options data. This PR then stops the sync and sets the woocommerce_square_refresh_sync_cycle option to refresh the data.

Avoiding Attribute Name Conflicts

If WooCommerce’s taxonomy attribute is used, this PR passes the taxonomy name (e.g., “pa_color” rather than “Color”) to Square, preventing conflicts with custom attributes of the same name. The “pa_” prefix helps WooCommerce users distinguish between taxonomy and custom attributes, avoiding potential conflicts.

New Option for Tracking

This PR introduces a new _dynamic_options option with true/false values to track whether dynamic options are used for a product. This is not in use but may be useful in future.

Notes for Merchants

Avoid leaving any variation dropdowns set to “Any” in products with multiple attributes, as Square does not support empty values for dynamic options. <- this one is also handled in this PR so that plugin creates "Any" option item at Square and maintains to set "Any" (means no selection) at WooCommerce and vice versa. It was decided on slack here.
Avoid changing taxonomy attribute slugs or attribute names in WooCommerce, or renaming dynamic options in Square.
Avoid creating custom attributes with names identical to existing taxonomy attributes, it results in issues during import/sync. Products using the same-named custom attribute are updated (replaced) incorrectly with the taxonomy attributes.
Do not create custom attributes with names identical to existing taxonomy attributes.

Post-Tasks

#251 - Display Notices for Sync Limitations.
#252 - Importing/Syncing from Square to Woocommerce, all the dynamic option values are added to the attribute, for example, for colour attribute, if there is only red and green options are selected at Square, after the import/sync, it adds all of the dynamic option values to the Woocommerce attribute regardless of what selection. This is not creating any issue to the purchases of the side, but this should be addressed.
#254 - If merchant changes the name of the attribute, this will create a new option/attribute instead of using the previous one. Think of a way to handle this.

Closes #6, Closes #31 and Closes #231.

Steps to test the changes in this Pull Request:

Set WooCommerce as SOR.
Create the following product types in WooCommerce:
- Simple Product
- Variable Product with:
  - 1 Custom Attribute
  - 1 Taxonomy Attribute
  - 2 Taxonomy Attributes
  - 2 Custom Attributes
  - 1 Custom + 1 Taxonomy Attribute
  - 2 Taxonomy Attributes + 1 Custom Attribute
Confirm these products are auto-synced and correctly created in Square.
Confirm the same for manual sync using the “Sync” button in settings.
Import all products from Square to WooCommerce and verify they retain attributes without issues (e.g., taxonomy attribute not converted to custom).
Make changes to the random products and confirm it syncs to the Square and Imports back to the Woo without and issues, few examples:
1. add one more custom attribute to the “2 Taxonomy Attributes” product
2. remove 1 taxonomy attribute from the “2 Taxonomy Attributes + 1 Custom Attribute” product
3. add one more variation to any product
4. remove one variation from any product
5. change the dropdown of any variation in “1 Custom Attribute” product
6. change the dropdown of all variations in “2 Taxonomy Attributes + 1 Custom Attribute” product
7. add one more attribute value and create update the dropdown values of each variation
8. etc.
Set Square as SOR and perform all of the above steps (sorry :)) This time the chagnes from the point 6 should be made at Square.
Important: Confirm no issues affect existing users by creating all product types in trunk and performing sync/import in the fix branch.

Changelog entry

Add - Multiple Variations Support

…te the dynamic option meta

…dempotency_key

faisal-alvi · 2024-12-20T14:51:34Z

@dkotter over to you for code review.

vikrampm1 · 2025-01-16T15:16:27Z

@qasumitbagthariya bumping this up in your queue to try and wrap it up asap.

qasumitbagthariya · 2025-01-23T14:38:16Z

QA Update ✅

I have verified this PR in the multiple-variations-support branch which has been fixed and is functioning as intended.

I tested the following on this branch:
Verified all the cases related to variations and the steps provided in the PR description

Square SOR

Square_SOR.mov

Woocommerce SOR

Woo-SOR.mov

Testing Environment

WordPress: 6.7.1
Theme: Twenty Twenty-Four 1.3
WooCommerce - 9.5.1
PHP: 8.0.30
Web Server: Nginx 1.20.2
Browser: Chrome
OS: macOS 15.2
Branch: multiple-variations-support

Steps to Test- As mentioned in the PR description.
Test Results - It is working as expected.
Functional Demo / Screencast -
Special Notes - Ready for code review (Woo)
Testing Document status:
Cases related to this Issue/PR are added to the Critical Flow Wiki pages:

Yes
Not Required/Applicable for this PR

wjrosa · 2025-01-23T20:15:57Z

includes/API.php

+		$objects = $response->get_data()->getObjects() ? $response->get_data()->getObjects() : array();
+
+		foreach ( $objects as $object ) {
+			$options_data[ $object->getId() ]['name'] = $object->getItemOptionData()->getDisplayName();


Can any of the getters return null values? If so, it would be nice to add some checks to avoid errors.

wjrosa · 2025-01-23T20:22:06Z

includes/Handlers/Product/Woo_SOR.php

+		$attributes = $product->get_attributes();
+
+		$product_variation_ids = $product->get_children();
+		$catalog_variations    = $item_data->getVariations() ? $item_data->getVariations() : array();


Since PHP 7.0 we can change this to:

Suggested change

$catalog_variations = $item_data->getVariations() ? $item_data->getVariations() : array();

$catalog_variations = $item_data->getVariations() ?? array();

wjrosa · 2025-01-23T20:22:45Z

includes/Handlers/Product/Woo_SOR.php

+			) {
+				$options_ids  = array();
+				$result       = wc_square()->get_api()->retrieve_options_data();
+				$options_data = isset( $result[1] ) ? $result[1] : array();


Same as above:

Suggested change

$options_data = isset( $result[1] ) ? $result[1] : array();

$options_data = $result[1] ?? array();

wjrosa · 2025-01-23T20:27:16Z

includes/Handlers/Product/Woo_SOR.php

+			$variation_items       = $product->get_attributes();
+			$variation_item_values = array();
+
+			if ( 1 === count( $attributes ) ) {


I see that these changes contain multiple "actions" that could be new methods to make reading easier. Basically, every time we have a comment here, the following code could be a new method named after the explanation. But this is optional

wjrosa · 2025-01-23T20:32:51Z

includes/Sync/Manual_Synchronization.php

+		$new_cursor = isset( $result[2] ) ? $result[2] : null;
+
+		if ( ! empty( $new_cursor ) ) {
+			$this->set_attr( 'fetch_options_data_cursor', $new_cursor );


I believe this line can be moved outside the condition, as $new_cursor will be null per the default value above anyway.

wjrosa · 2025-01-23T20:35:57Z

includes/Sync/Product_Import.php

@@ -1056,6 +1297,8 @@ protected function save_variations( $product_id, $data ) {
 				$updated_attribute_keys = array();

 				foreach ( $variation['attributes'] as $attribute_key => $attribute ) {
+					// Set empty if attribute is to 'Any' to prevent it from being saved.
+					$attribute['option'] = isset( $attribute['option'] ) && 'Any' !== $attribute['option'] ? $attribute['option'] : '';


Maybe we should move Any to a new constant.

wjrosa

Looks good! Some multiple optional suggestions 👍

vikrampm1 · 2025-01-24T13:25:05Z

Thanks @wjrosa. @faisal-alvi see if you can make those optional suggested changes above and then we can move this to the next step.

faisal-alvi added 30 commits October 29, 2024 19:21

fetch options data

45942fa

prepare options data

4f0b842

Stop if there are no options

277167d

remove unnecessary older attributes data

f665807

prepare variation data

c9e10a7

use the newer version of variation data

51d93bd

Create transient only when step completes

f95af7d

adding since and throw in doc

3beeb06

vertically inlined equals

235fd1d

do not stop if options do no exist, we may have custom variations

344a2a7

remove extract options data logic

5d320f6

prepare attributes for custom variations

b10816f

add extract_attributes_from_square_options()

41c85d8

add extract_attributes_from_square_variations()

23de016

a few spacing adjustments

d480fb3

extract attributes as per the option type

8bc38f4

check for options just before when its needed

a7796b4

pass custom_meta in data for product

c7a3410

handle custom_meta and update meta

a1a8aa8

update the meta name to hide it

4c6e132

init attribute and variations

74b36fd

consider dynamic options if more than one attributes exits; also dele…

46d9c1e

…te the dynamic option meta

Set the product as a dynamic options product

4e569c3

Loop through the attributes to create options and values at Square.

ae96951

Set the item_option_id for each option to the product

e49c6b4

Check if Square already has the option created with the same name

6f1b741

If name does not exist, create a new option in Square

3d3b2af

Loop through the attribute values to create option values

c3e6d8d

Set the option values

c5ab52a

Push option object to Square to create a new one. Used timestamp as i…

d5fe986

…dempotency_key

github-actions bot added status: e2e tests passing and removed status: e2e tests passing labels Dec 20, 2024

use transient in a more safer way

51532ee

github-actions bot added status: e2e tests passing and removed status: e2e tests passing labels Dec 20, 2024

dkotter approved these changes Dec 20, 2024

View reviewed changes

dkotter requested a review from qasumitbagthariya December 20, 2024 21:08

faisal-alvi mentioned this pull request Jan 13, 2025

Document Woo<>Square object mappings #39

Open

Merge branch 'trunk' into multiple-variations-support

122ca65

qasumitbagthariya approved these changes Jan 23, 2025

View reviewed changes

qasumitbagthariya requested review from a team and wjrosa and removed request for a team January 23, 2025 14:38

wjrosa reviewed Jan 23, 2025

View reviewed changes

wjrosa approved these changes Jan 23, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Multiple Variations Support #235

Multiple Variations Support #235

faisal-alvi commented Nov 13, 2024 •

edited

Loading

faisal-alvi commented Dec 20, 2024

vikrampm1 commented Jan 16, 2025

qasumitbagthariya commented Jan 23, 2025

wjrosa Jan 23, 2025

wjrosa Jan 23, 2025

wjrosa Jan 23, 2025

wjrosa Jan 23, 2025

wjrosa Jan 23, 2025

wjrosa Jan 23, 2025

wjrosa left a comment

vikrampm1 commented Jan 24, 2025

	$catalog_variations = $item_data->getVariations() ? $item_data->getVariations() : array();
	$catalog_variations = $item_data->getVariations() ?? array();

	$options_data = isset( $result[1] ) ? $result[1] : array();
	$options_data = $result[1] ?? array();

Multiple Variations Support #235

Are you sure you want to change the base?

Multiple Variations Support #235

Conversation

faisal-alvi commented Nov 13, 2024 • edited Loading

All Submissions:

Changes proposed in this Pull Request:

Square and WooCommerce Attribute Types

Key Differences Between Dynamic and Static Options

Syncing Logic (Overview)

Syncing Logic for WooCommerce and Square (Detail)

Square API Limitations and Solutions

Avoiding Attribute Name Conflicts

New Option for Tracking

Notes for Merchants

Post-Tasks

Steps to test the changes in this Pull Request:

Changelog entry

faisal-alvi commented Dec 20, 2024

vikrampm1 commented Jan 16, 2025

qasumitbagthariya commented Jan 23, 2025

QA Update ✅

wjrosa Jan 23, 2025

Choose a reason for hiding this comment

wjrosa Jan 23, 2025

Choose a reason for hiding this comment

wjrosa Jan 23, 2025

Choose a reason for hiding this comment

wjrosa Jan 23, 2025

Choose a reason for hiding this comment

wjrosa Jan 23, 2025

Choose a reason for hiding this comment

wjrosa Jan 23, 2025

Choose a reason for hiding this comment

wjrosa left a comment

Choose a reason for hiding this comment

vikrampm1 commented Jan 24, 2025

faisal-alvi commented Nov 13, 2024 •

edited

Loading