Commit d7f1e03ff1e for woocommerce
commit d7f1e03ff1ee52630f1703015c5c9094f375b5eb
Author: Taha Paksu <3295+tpaksu@users.noreply.github.com>
Date: Tue Nov 17 11:33:01 2026 +0300
Match the block fulfillment email heading to the number of items (#71030)
* [WOOPLUG-8256] Match the block fulfillment email heading to the item count
* Add changefile(s) from automation for the following project(s): woocommerce
* [WOOPLUG-8256] Stop the email editor stripping the heading tag
* [WOOPLUG-8256] Cover the block template heading wiring with a test
* [WOOPLUG-8256] Pin the template heading test to a sentinel heading
---------
Co-authored-by: woocommercebot <woocommercebot@users.noreply.github.com>
diff --git a/plugins/woocommerce/changelog/71030-wooplug-8256-block-fulfillment-heading b/plugins/woocommerce/changelog/71030-wooplug-8256-block-fulfillment-heading
new file mode 100644
index 00000000000..ab2276d051f
--- /dev/null
+++ b/plugins/woocommerce/changelog/71030-wooplug-8256-block-fulfillment-heading
@@ -0,0 +1,4 @@
+Significance: patch
+Type: fix
+
+Match the heading to the number of items sent in fulfillment emails built with the email editor.
diff --git a/plugins/woocommerce/src/Internal/EmailEditor/PersonalizationTags/OrderTagsProvider.php b/plugins/woocommerce/src/Internal/EmailEditor/PersonalizationTags/OrderTagsProvider.php
index 08c6063e064..30922e8b23e 100644
--- a/plugins/woocommerce/src/Internal/EmailEditor/PersonalizationTags/OrderTagsProvider.php
+++ b/plugins/woocommerce/src/Internal/EmailEditor/PersonalizationTags/OrderTagsProvider.php
@@ -342,5 +342,26 @@ class OrderTagsProvider extends AbstractTagProvider {
Personalization_Tag::VALUE_TYPE_TEXT,
)
);
+
+ $registry->register(
+ new Personalization_Tag(
+ __( 'Fulfillment Heading', 'woocommerce' ),
+ 'woocommerce/fulfillment-heading',
+ __( 'Order', 'woocommerce' ),
+ function ( array $context ): string {
+ $wc_email = $context['wc_email'] ?? null;
+ // The fulfillment emails are the only consumers of this tag.
+ if ( ! $wc_email instanceof \WC_Email || ! str_starts_with( $wc_email->id, 'customer_fulfillment_' ) ) {
+ return '';
+ }
+ // get_heading() returns filtered output, so it is cast rather than trusted.
+ return (string) $wc_email->get_heading();
+ },
+ array(),
+ null,
+ array( Integration::EMAIL_POST_TYPE ),
+ Personalization_Tag::VALUE_TYPE_TEXT,
+ )
+ );
}
}
diff --git a/plugins/woocommerce/templates/emails/block/customer-fulfillment-created.php b/plugins/woocommerce/templates/emails/block/customer-fulfillment-created.php
index 0d01906d7e9..53b25d5dd0c 100644
--- a/plugins/woocommerce/templates/emails/block/customer-fulfillment-created.php
+++ b/plugins/woocommerce/templates/emails/block/customer-fulfillment-created.php
@@ -24,7 +24,7 @@ defined( 'ABSPATH' ) || exit;
?>
<!-- wp:heading -->
-<h2 class="wp-block-heading"> <?php echo esc_html__( 'Your item is on the way!', 'woocommerce' ); ?> </h2>
+<h2 class="wp-block-heading"> <?php echo '<!--[woocommerce/fulfillment-heading]--> '; // The non-breaking space is used to prevent the comment from being removed by the email editor. ?> </h2>
<!-- /wp:heading -->
<!-- wp:paragraph -->
diff --git a/plugins/woocommerce/tests/php/src/Internal/EmailEditor/PersonalizationTags/OrderTagsProviderTest.php b/plugins/woocommerce/tests/php/src/Internal/EmailEditor/PersonalizationTags/OrderTagsProviderTest.php
index afcc6697e0d..534a13e69e2 100644
--- a/plugins/woocommerce/tests/php/src/Internal/EmailEditor/PersonalizationTags/OrderTagsProviderTest.php
+++ b/plugins/woocommerce/tests/php/src/Internal/EmailEditor/PersonalizationTags/OrderTagsProviderTest.php
@@ -3,10 +3,12 @@ declare( strict_types = 1 );
namespace Automattic\WooCommerce\Tests\Internal\EmailEditor\PersonalizationTags;
+use Automattic\WooCommerce\Admin\Features\Fulfillments\Fulfillment;
use Automattic\WooCommerce\EmailEditor\Engine\Logger\Email_Editor_Logger;
use Automattic\WooCommerce\EmailEditor\Engine\PersonalizationTags\Personalization_Tags_Registry;
use Automattic\WooCommerce\EmailEditor\Engine\Personalizer;
use Automattic\WooCommerce\Internal\EmailEditor\PersonalizationTags\OrderTagsProvider;
+use Automattic\WooCommerce\Internal\EmailEditor\WCTransactionalEmails\WCTransactionalEmailPostsGenerator;
use WC_Helper_Order;
use WC_Unit_Test_Case;
@@ -101,4 +103,130 @@ class OrderTagsProviderTest extends WC_Unit_Test_Case {
$this->assertSame( '<p><b>Leave</b> at the door</p>', $html );
}
+
+ /**
+ * @testdox Registers the fulfillment heading tag.
+ */
+ public function test_registers_fulfillment_heading_tag(): void {
+ $tag = $this->registry->get_by_token( '[woocommerce/fulfillment-heading]' );
+
+ $this->assertNotNull( $tag, 'The fulfillment heading tag should be registered.' );
+ $this->assertSame( __( 'Order', 'woocommerce' ), $tag->get_category() );
+ }
+
+ /**
+ * @testdox The fulfillment heading tag uses the plural heading when the fulfillment has several items.
+ */
+ public function test_fulfillment_heading_tag_uses_plural_heading(): void {
+ $email = $this->create_fulfillment_email( 2 );
+
+ $heading = $this->registry->get_by_token( '[woocommerce/fulfillment-heading]' )->execute_callback( array( 'wc_email' => $email ) );
+
+ $this->assertSame( 'Your items are on the way!', $heading );
+ }
+
+ /**
+ * @testdox The fulfillment heading tag uses the singular heading when the fulfillment has one item.
+ */
+ public function test_fulfillment_heading_tag_uses_singular_heading(): void {
+ $email = $this->create_fulfillment_email( 1 );
+
+ $heading = $this->registry->get_by_token( '[woocommerce/fulfillment-heading]' )->execute_callback( array( 'wc_email' => $email ) );
+
+ $this->assertSame( 'Your item is on the way!', $heading );
+ }
+
+ /**
+ * @testdox The fulfillment heading tag returns an empty string for an email that is not about a fulfillment.
+ */
+ public function test_fulfillment_heading_tag_for_another_email_type(): void {
+ $bootstrap = \WC_Unit_Tests_Bootstrap::instance();
+ require_once $bootstrap->plugin_dir . '/includes/emails/class-wc-email.php';
+ require_once $bootstrap->plugin_dir . '/includes/emails/class-wc-email-customer-completed-order.php';
+
+ $heading = $this->registry->get_by_token( '[woocommerce/fulfillment-heading]' )->execute_callback( array( 'wc_email' => new \WC_Email_Customer_Completed_Order() ) );
+
+ $this->assertSame( '', $heading );
+ }
+
+ /**
+ * @testdox The fulfillment heading tag escapes the heading exactly once in HTML.
+ */
+ public function test_fulfillment_heading_tag_escapes_the_heading_once_in_html(): void {
+ $email = $this->create_fulfillment_email( 1 );
+ $filter = function () {
+ return 'Packed & ready';
+ };
+ add_filter( 'woocommerce_email_heading_customer_fulfillment_created', $filter );
+
+ $personalizer = new Personalizer( $this->registry );
+ $personalizer->set_context( array( 'wc_email' => $email ) );
+
+ $html = $personalizer->personalize_content( '<h2><!--[woocommerce/fulfillment-heading]--></h2>' );
+
+ remove_filter( 'woocommerce_email_heading_customer_fulfillment_created', $filter );
+
+ $this->assertSame( '<h2>Packed & ready</h2>', $html );
+ }
+
+ /**
+ * @testdox The block fulfillment created template takes its heading from the tag.
+ */
+ public function test_block_template_heading_comes_from_the_tag(): void {
+ $email = $this->create_fulfillment_email( 2 );
+
+ // A heading no template could contain, so the assertion fails if the markup carries its own.
+ $filter = function () {
+ return 'Heading taken from the email';
+ };
+ add_filter( 'woocommerce_email_heading_customer_fulfillment_created', $filter );
+
+ $markup = WCTransactionalEmailPostsGenerator::render_block_template_html( $email );
+ $personalizer = new Personalizer( $this->registry );
+ $personalizer->set_context( array( 'wc_email' => $email ) );
+ $html = $personalizer->personalize_content( $markup );
+
+ remove_filter( 'woocommerce_email_heading_customer_fulfillment_created', $filter );
+
+ $this->assertStringContainsString( 'Heading taken from the email', $html );
+ }
+
+ /**
+ * @testdox The fulfillment heading tag returns an empty string without email context.
+ */
+ public function test_fulfillment_heading_tag_without_email_context(): void {
+ $tag = $this->registry->get_by_token( '[woocommerce/fulfillment-heading]' );
+
+ $this->assertSame( '', $tag->execute_callback( array() ) );
+ }
+
+ /**
+ * Build a triggered fulfillment created email whose fulfillment covers the order at the given quantity.
+ *
+ * @param int $quantity Quantity fulfilled per order item.
+ * @return \WC_Email_Customer_Fulfillment_Created
+ */
+ private function create_fulfillment_email( int $quantity ): \WC_Email_Customer_Fulfillment_Created {
+ $bootstrap = \WC_Unit_Tests_Bootstrap::instance();
+ require_once $bootstrap->plugin_dir . '/includes/emails/class-wc-email.php';
+ require_once $bootstrap->plugin_dir . '/includes/emails/class-wc-email-customer-fulfillment-created.php';
+
+ $order = WC_Helper_Order::create_order();
+ $items = array();
+ foreach ( array_keys( $order->get_items() ) as $item_id ) {
+ $items[] = array(
+ 'item_id' => $item_id,
+ 'qty' => $quantity,
+ );
+ }
+
+ $fulfillment = new Fulfillment();
+ $fulfillment->set_items( $items );
+
+ // The fulfillment is private on the email, so triggering is the only way to attach it.
+ $email = new \WC_Email_Customer_Fulfillment_Created();
+ $email->trigger( $order->get_id(), $fulfillment, $order );
+
+ return $email;
+ }
}