woocommerce/plugins/woocommerce-blocks/docs/internal-developers/blocks/feature-flags-and-experimental-interfaces.md

Features Flags and Experimental Interfaces

Table of contents

• Blocks behind flags
  • Feature plugin flag
  • Experimental flag
• Features behind flags
  • Feature plugin flag
  • Experimental plugin flag
• Processes and commands that use a flag
• Usages of __experimental prefix
  • PHP filters and actions
  • JS methods
  • Slots
  • Misc
• Usages of experimental prefix

We have feature gating system setup in our plugin that defines what is accessible to the public and what is not, it has three phases:

• Core flag WOOCOMMERCE_BLOCKS_PHASE=1: anything that is not hidden behind a flag, falls under this category, and it contains all of the code that runs on WooCommerce Core plugin.
• Feature plugin flag WOOCOMMERCE_BLOCKS_PHASE=2: anything that is behind this flag is code that is shipped to our feature plugin, the files of blocks behind this flag are also present in WooCommerce Core, just not active.
• Experimental flag WOOCOMMERCE_BLOCKS_PHASE=3: This flag contains things that we're not shipping yet, so unfinished work mostly. These features are only available in developer builds of the plugin.

We also use an __experimental prefix for any experimental interfaces. This is a signal to those reading our code that it should not be implemented in for production use. Currently this prefix is used in the following ways:

• Prefixing references that are experimental. An example would be PHP action or filter slugs.
• Prefixing functions or methods that are experimental.

Blocks behind flags

The majority of our feature flagging is blocks, this is a list of them:

Feature plugin flag

• Products (Beta) block (JS flag).
• ⚛️ Product SKU (JS flag).
• ⚛️ Product stock indicator (JS flag).

Experimental flag

• Cart block (JS flag | PHP flag).
• Cart Express Checkout block (JS flag).
• Cart Items block (JS flag).
• Cart Line Items block (JS flag).
• Cart Order Summary block (JS flag).
• Cart Totals block (JS flag).
• Empty Cart block (JS flag).
• Filled Cart block (JS flag).
• Cart Proceed to checkout block (JS flag).
• Single Product block (JS flag | PHP flag | webpack flag).
• Products on Sale (JS flag).
• ⚛️ Add to cart (JS flag).
• ⚛️ Product category list (JS flag).
• ⚛️ Product tag list (JS flag).

Features behind flags

We also have individual features or code blocks behind a feature flag, this is a list of them:

Feature plugin flag

• ⚛️ Product Price new controls (JS flag 1 | JS flag 2-1 | JS flag 2-2 | JS flag 2-3 | JS flag 2-4 | JS flag 2-5 | JS flag 3-2).
• ⚛️ Product Title new controls (JS flag 1 | JS flag 2-1 | JS flag 2-2 | JS flag 2-3 | JS flag 3-1 | JS flag 3-2 | JS flag 3-3).
• Utility function to pass styles to a block (JS flag).

Experimental plugin flag

• Inserting Product Element blocks globally from the inserter (JS flag).

Processes and commands that use a flag

• npm run build:deploy uses the feature plugin flag (env flag).
• GitHub actions uses the experimental flag when running automated tests (env flags 1 | env flags 2).
• webpack creates a blocks.ini when running (env flag).
• webpack filters out experimental blocks when building. (env flag).
• certain E2E tests are skipped if the environment is not met (env flag 1 | env flag 2 | env flag 3 | env flag 4 | env flag 5 | env flag 6).

Usages of __experimental prefix

PHP filters and actions

• __experimental_woocommerce_blocks_payment_gateway_features_list hook that allows modification of the features supported by PayPal Standard. (experimental hook).
• Deprecated - __experimental_woocommerce_blocks_checkout_update_order_meta hook when the draft order has been created or updated from the cart and is now ready for extensions to modify the metadata (experimental hook). Deprecated in PR 5017.
• Deprecated - __experimental_woocommerce_blocks_checkout_update_order_from_request hook gives extensions the chance to update orders based on the data in the request (deprecated experimental hook). Deprecated in PR 5015.
• Deprecated - __experimental_woocommerce_blocks_checkout_order_processed hook when order has completed processing and is ready for payment (deprecated experimental hook). Deprecated in PR 5014.
• __experimental_woocommerce_blocks_add_data_attributes_to_namespace hook that allows 3PD to add a namespace of blocks to receive block attributes as data- attributes (experimental property).
• __experimental_woocommerce_blocks_add_data_attributes_to_block hook that allows 3PD to add a block to recieve block attributes as data- attributes (experimental property).

JS methods

• __experimentalDeRegisterPaymentMethod function used to deregister a payment method, only used in tests (experimental function).
• __experimentalDeRegisterExpressPaymentMethod function used to deregister an express payment method, only used in tests (experimental function).
• __experimentalRegisterCheckoutFilters and __experimentalApplyCheckoutFilter methods included with @woocommerce/blocks-checkout package. They allow registering and applying a filter to certain parts of the Cart and Checkout blocks (experimental method 1 | experimental method 2).

Slots

• __experimentalOrderMeta slot that allows extensions to add content to the order meta in the Cart and Checkout blocks (experimental slot).
• __experimentalOrderShippingPackages slot that allows extensions to add content to the shipping packages in the Cart and Checkout blocks (experimental slot).
• __experimentalDiscountsMeta slot that allows extensions to add content to the shipping packages in the Cart and Checkout blocks (experimental slot).

Misc

• __experimental_woocommerce_blocks_hidden property in a Cart item data array that allows overwriting the hidden property. This is useful to make some cart item data visible/hidden depending if it needs to be displayed in Blocks or shortcode (experimental property).

Usages of experimental prefix

useStoreEvents makes use of an experimental__ prefix for wp-hook actions (since __experimental is not a valid prefix in that context).

• experimental__woocommerce_blocks- is used for store events.
• experimental__woocommerce_blocks-checkout- is used for checkout events.

Current list of events:

• experimental__woocommerce_blocks-cart-add-item - Fired when an item is added to the cart.
• experimental__woocommerce_blocks-cart-set-item-quantity - Fired when cart item quantity is changed by the customer.
• experimental__woocommerce_blocks-cart-remove-item - Fired when a cart item is removed from the cart.
• experimental__woocommerce_blocks-product-view-link - Fired when a product link is clicked.
• experimental__woocommerce_blocks-product-list-render - Fired when a product list is rendered.
• experimental__woocommerce_blocks-product-search - Fired when a search is submitted.
• experimental__woocommerce_blocks-store-notice-create - Fired when a store notice is created.
• experimental__woocommerce_blocks-product-render - Fired when a single product block is rendered.
• experimental__woocommerce_blocks-checkout-submit - Fired when the checkout form is submitted.
• experimental__woocommerce_blocks-checkout-set-selected-shipping-rate - Fired when a shipping rate is chosen on checkout.
• experimental__woocommerce_blocks-checkout-set-active-payment-method - Fired when a payment method is chosen on checkout.
• experimental__woocommerce_blocks-checkout-render-checkout-form - Fired when the checkout form is rendered.
• experimental__woocommerce_blocks-checkout-set-email-address - Fired when an email address is added during checkout.
• experimental__woocommerce_blocks-checkout-set-shipping-address - Fired when a shipping address is added during checkout.
• experimental__woocommerce_blocks-checkout-set-billing-address - Fired when a billing address is added during checkout.
• experimental__woocommerce_blocks-checkout-set-phone-number - Fired when a phone number is added during checkout.