feature-flags-and-experimental-interfaces.md

📣 Announcement: New documentation location

The documentation for WooCommerce Blocks has moved to the WooCommerce monorepo.

Please refer to the documentation in the new location as the files in this repository will no longer be updated and the repository will be archived.

---

Features Flags and Experimental Interfaces

Table of contents

• Blocks behind flags
  • Feature plugin flag
  • Experimental flag
• Features behind flags
  • Feature 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

Experimental flag

• Product Gallery (PHP flag | webpack flag | BlockTemplatesController).
• Product Gallery Large Image (PHP flag | webpack flag).
• Product Gallery Next/Previous Buttons (PHP flag | webpack flag).
• Product Gallery Pager (PHP flag | webpack flag).
• Product Gallery Thumbnails (PHP flag | webpack flag).
• Collection Filters (PHP flag | webpack flag | JS flag).
• Collection Stock Filter (PHP flag | webpack flag | JS flag).
• Collection Price Filter (PHP flag | webpack flag).
• Collection Attribute Filter (PHP flag | webpack flag).
• ⚛️ Add to cart (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).
• ⚛️ Product Title new controls (JS flag 1 | JS flag 2-1 | JS flag 2-2 | JS flag 2-3 | JS flag 2-4 | JS flag 3-1 | JS flag 3-2).

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).

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 allows overwriting the hidden property for cart item data. This is useful to make some cart item data visible/hidden depending if it needs to be displayed in the Cart Block or the Cart Shortcode (experimental property). This was added in this PR to resolve this issue with Subscriptions. This property will not be needed if the blocks replace the shortcode experience, since in that scenario, the hidden property would be sufficient.

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.