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

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

• Cart block (JS flag | PHP flag).
• Checkout block (JS flag | PHP flag).
• Checkout Actions block (JS flag).
• Checkout Billing Address block (JS flag).
• Checkout Contact Information block (JS flag).
• Checkout Express Payment block (JS flag).
• Checkout Fields block (JS flag).
• Checkout Order Note block (JS flag).
• Checkout Order Summary block (JS flag).
• Checkout Payment block (JS flag).
• Checkout Shipping Address block (JS flag).
• Checkout Shipping Methods block (JS flag).
• Checkout Terms block (JS flag).
• Checkout Totals block (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).
• Mini Cart block (JS flag | PHP flag 1 | webpack flag).
• ⚛️ Add to cart (JS flag).
• ⚛️ Product category list (JS flag).
• ⚛️ Product SKU (JS flag).
• ⚛️ Product stock indicator (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

• Draft order and cleanup process (PHP flag).
• Payment API (PHP flag 1 | PHP flag 2).
• ⚛️ 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-1 | 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).
• Feature to create an account from the Checkout block (PHP flag).
• Checkout package (PHP Flag) which contains:
  • SlotFills used in Cart and Checkout.
  • Checkout Filters.
  • Inner Blocks registry for Cart & Checkout i2.
  • Components exposed to 3PD.

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).
• __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).
• __experimental_woocommerce_blocks_checkout_update_order_from_request hook gives extensions the chance to update orders based on the data in the request (experimental hook).
• __experimental_woocommerce_blocks_checkout_order_processed hook when order has completed processing and is ready for payment (experimental hook).
• __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.