Update email preview to show processing order email (#52415)

* Move email preview rendering into separate class

* Allow setting WC_Email $object

This is needed so in an email preview, we can set order to be rendered in an email

* Render "Processing order" with dummy order in email preview

* Always show shipping address in email preview

* Allow fetching dummy email preview product

* Add changelog

* Add unit test for EmailPreview

* Clean up filters after rendering email preview

* Improve duplicate filter comment

* Replace __return_true with a function to prevent accidental filter removal

plugins/woocommerce/changelog/52225-email-preview-route

@@ -0,0 +1,5 @@
+Significance: patch
+Type: add
+Comment: This change replaces static email preview with order processing email. This is in development behind a hidden experimental flag and not yet ready for public use.
+
+

plugins/woocommerce/includes/admin/class-wc-admin.php

@@ -7,6 +7,8 @@
  * @version  2.6.0
  */
 
+use Automattic\WooCommerce\Internal\Admin\EmailPreview;
+
 if ( ! defined( 'ABSPATH' ) ) {
 	exit; // Exit if accessed directly.
 }
@@ -194,22 +196,8 @@ class WC_Admin {
 				die( 'Security check' );
 			}
 
-			// load the mailer class.
-			$mailer = WC()->mailer();
-
-			// get the preview email subject.
-			$email_heading = __( 'HTML email template', 'woocommerce' );
-
-			// get the preview email content.
-			ob_start();
-			include __DIR__ . '/views/html-email-template-preview.php';
-			$message = ob_get_clean();
-
-			// create a new email.
-			$email = new WC_Email();
-
-			// wrap the content with the email template and then add styles.
-			$message = apply_filters( 'woocommerce_mail_content', $email->style_inline( $mailer->wrap_message( $email_heading, $message ) ) );
+			$email_preview = wc_get_container()->get( EmailPreview::class );
+			$message       = $email_preview->render();
 
 			// print the preview email.
 			// phpcs:ignore WordPress.Security.EscapeOutput

plugins/woocommerce/includes/emails/class-wc-email.php

@@ -720,6 +720,16 @@ class WC_Email extends WC_Settings_API {
 		return sanitize_email( $from_email );
 	}
 
+	/**
+	 * Set the object for the outgoing email.
+	 *
+	 * @param object $object Object this email is for, e.g. customer, or product.
+	 * @return void
+	 */
+	public function set_object( $object ) { // phpcs:ignore Universal.NamingConventions.NoReservedKeywordParameterNames.objectFound
+		$this->object = $object;
+	}
+
 	/**
 	 * Send an email.
 	 *

plugins/woocommerce/src/Container.php

@@ -12,6 +12,7 @@ use Automattic\WooCommerce\Internal\DependencyManagement\ServiceProviders\CostOf
 use Automattic\WooCommerce\Internal\DependencyManagement\ServiceProviders\COTMigrationServiceProvider;
 use Automattic\WooCommerce\Internal\DependencyManagement\ServiceProviders\DownloadPermissionsAdjusterServiceProvider;
 use Automattic\WooCommerce\Internal\DependencyManagement\ServiceProviders\AssignDefaultCategoryServiceProvider;
+use Automattic\WooCommerce\Internal\DependencyManagement\ServiceProviders\EmailPreviewServiceProvider;
 use Automattic\WooCommerce\Internal\DependencyManagement\ServiceProviders\EnginesServiceProvider;
 use Automattic\WooCommerce\Internal\DependencyManagement\ServiceProviders\FeaturesServiceProvider;
 use Automattic\WooCommerce\Internal\DependencyManagement\ServiceProviders\LoggingServiceProvider;
@@ -63,6 +64,7 @@ final class Container {
 	private $service_providers = array(
 		AssignDefaultCategoryServiceProvider::class,
 		DownloadPermissionsAdjusterServiceProvider::class,
+		EmailPreviewServiceProvider::class,
 		OptionSanitizerServiceProvider::class,
 		OrdersDataStoreServiceProvider::class,
 		ProductAttributesLookupServiceProvider::class,

plugins/woocommerce/src/Internal/Admin/EmailPreview.php

@@ -0,0 +1,209 @@
+<?php
+/**
+ * Renders the email preview.
+ */
+
+declare( strict_types=1 );
+
+namespace Automattic\WooCommerce\Internal\Admin;
+
+use Automattic\WooCommerce\Utilities\FeaturesUtil;
+use WC_Email;
+use WC_Order;
+use WC_Product;
+
+defined( 'ABSPATH' ) || exit;
+
+
+/**
+ * EmailPreview Class.
+ */
+class EmailPreview {
+	/**
+	 * The single instance of the class.
+	 *
+	 * @var object
+	 */
+	protected static $instance = null;
+
+	/**
+	 * Get class instance.
+	 *
+	 * @return object Instance.
+	 */
+	final public static function instance() {
+		if ( null === static::$instance ) {
+			static::$instance = new static();
+		}
+		return static::$instance;
+	}
+
+	/**
+	 * Get the preview email content.
+	 *
+	 * @return string
+	 */
+	public function render() {
+		if ( FeaturesUtil::feature_is_enabled( 'email_improvements' ) ) {
+			return $this->render_preview_email();
+		}
+		return $this->render_legacy_preview_email();
+	}
+
+	/**
+	 * Return a dummy product when the product is not set in email classes.
+	 *
+	 * @param WC_Product $product Order item product.
+	 * @return WC_Product
+	 */
+	public function get_dummy_product_when_not_set( $product ) {
+		if ( $product ) {
+			return $product;
+		}
+		return $this->get_dummy_product();
+	}
+
+	/**
+	 * Get HTML of the legacy preview email.
+	 *
+	 * @return string
+	 */
+	private function render_legacy_preview_email() {
+		// load the mailer class.
+		$mailer = WC()->mailer();
+
+		// get the preview email subject.
+		$email_heading = __( 'HTML email template', 'woocommerce' );
+
+		// get the preview email content.
+		ob_start();
+		include WC()->plugin_path() . '/includes/admin/views/html-email-template-preview.php';
+		$message = ob_get_clean();
+
+		// create a new email.
+		$email = new WC_Email();
+
+		/**
+		 * Wrap the content with the email template and then add styles.
+		 *
+		 * @since 2.6.0
+		 */
+		return apply_filters( 'woocommerce_mail_content', $email->style_inline( $mailer->wrap_message( $email_heading, $message ) ) );
+	}
+
+	/**
+	 * Render HTML content of the preview email.
+	 *
+	 * @return string
+	 */
+	private function render_preview_email() {
+		$this->set_up_filters();
+
+		$email = $this->get_email();
+
+		$order = $this->get_dummy_order();
+		$email->set_object( $order );
+
+		$content = $email->get_content_html();
+
+		$this->clean_up_filters();
+
+		/** This filter is documented in src/Internal/Admin/EmailPreview.php */
+		return apply_filters( 'woocommerce_mail_content', $email->style_inline( $content ) ); // phpcs:ignore WooCommerce.Commenting.CommentHooks.MissingSinceComment
+	}
+
+	/**
+	 * Get a dummy order object without the need to create in the database.
+	 *
+	 * @return WC_Order
+	 */
+	private function get_dummy_order() {
+		$product = $this->get_dummy_product();
+
+		$order = new WC_Order();
+		$order->add_product( $product, 2 );
+		$order->set_id( 12345 );
+		$order->set_date_created( time() );
+		$order->set_currency( 'USD' );
+		$order->set_total( 100 );
+
+		$address = $this->get_dummy_address();
+		$order->set_billing_address( $address );
+		$order->set_shipping_address( $address );
+
+		return $order;
+	}
+
+	/**
+	 * Get a dummy product. Also used with `woocommerce_order_item_product` filter
+	 * when email templates tries to get the product from the database.
+	 *
+	 * @return WC_Product
+	 */
+	private function get_dummy_product() {
+		$product = new WC_Product();
+		$product->set_name( 'Dummy Product' );
+		$product->set_price( 25 );
+		return $product;
+	}
+
+	/**
+	 * Get a dummy address.
+	 *
+	 * @return array
+	 */
+	private function get_dummy_address() {
+		return array(
+			'first_name' => 'John',
+			'last_name'  => 'Doe',
+			'company'    => 'Company',
+			'email'      => 'john@company.com',
+			'phone'      => '555-555-5555',
+			'address_1'  => '123 Fake Street',
+			'city'       => 'Faketown',
+			'postcode'   => '12345',
+			'country'    => 'US',
+			'state'      => 'CA',
+		);
+	}
+
+	/**
+	 * Get the email class for email preview.
+	 *
+	 * @return WC_Email
+	 */
+	private function get_email() {
+		$emails = WC()->mailer()->get_emails();
+		$email  = $emails['WC_Email_Customer_Processing_Order'];
+		return $email;
+	}
+
+	/**
+	 * Set up filters for email preview.
+	 */
+	private function set_up_filters() {
+		// Always show shipping address in the preview email.
+		add_filter( 'woocommerce_order_needs_shipping_address', array( $this, 'enable_shipping_address' ) );
+		// Email templates fetch product from the database to show additional information, which are not
+		// saved in WC_Order_Item_Product. This filter enables fetching that data also in email preview.
+		add_filter( 'woocommerce_order_item_product', array( $this, 'get_dummy_product_when_not_set' ), 10, 1 );
+	}
+
+	/**
+	 * Clean up filters after email preview.
+	 */
+	private function clean_up_filters() {
+		remove_filter( 'woocommerce_order_needs_shipping_address', array( $this, 'enable_shipping_address' ) );
+		remove_filter( 'woocommerce_order_item_product', array( $this, 'get_dummy_product_when_not_set' ), 10 );
+	}
+
+	/**
+	 * Enable shipping address in the preview email. Not using __return_true so
+	 * we don't accidentally remove the same filter used by other plugin or theme.
+	 *
+	 * @return true
+	 */
+	public function enable_shipping_address() {
+		return true;
+	}
+}

plugins/woocommerce/src/Internal/DependencyManagement/ServiceProviders/EmailPreviewServiceProvider.php

@@ -0,0 +1,29 @@
+<?php
+declare( strict_types=1 );
+
+namespace Automattic\WooCommerce\Internal\DependencyManagement\ServiceProviders;
+
+use Automattic\WooCommerce\Internal\DependencyManagement\AbstractServiceProvider;
+use Automattic\WooCommerce\Internal\Admin\EmailPreview;
+
+/**
+ * Service provider for the EmailPreview namespace.
+ */
+class EmailPreviewServiceProvider extends AbstractServiceProvider {
+
+	/**
+	 * The classes/interfaces that are serviced by this service provider.
+	 *
+	 * @var array
+	 */
+	protected $provides = array(
+		EmailPreview::class,
+	);
+
+	/**
+	 * Register the classes.
+	 */
+	public function register() {
+		$this->share( EmailPreview::class );
+	}
+}

plugins/woocommerce/tests/php/src/Internal/Admin/EmailPreviewTest.php

@@ -0,0 +1,68 @@
+<?php
+declare( strict_types = 1 );
+
+namespace Automattic\WooCommerce\Tests\Internal\Admin;
+
+use Automattic\WooCommerce\Internal\Admin\EmailPreview;
+use WC_Emails;
+use WC_Unit_Test_Case;
+
+/**
+ * EmailPreviewTest test.
+ *
+ * @covers \Automattic\WooCommerce\Internal\Admin\EmailPreview
+ */
+class EmailPreviewTest extends WC_Unit_Test_Case {
+	/**
+	 * "System Under Test", an instance of the class to be tested.
+	 *
+	 * @var EmailPreview
+	 */
+	private $sut;
+
+	/**
+	 * Set up.
+	 */
+	public function setUp(): void {
+		parent::setUp();
+		$this->sut = new EmailPreview();
+		new WC_Emails();
+	}
+
+	/**
+	 * Tear down.
+	 */
+	public function tearDown(): void {
+		parent::tearDown();
+		update_option( 'woocommerce_feature_email_improvements_enabled', 'no' );
+	}
+
+	/**
+	 * Tests that it returns legacy email preview when feature flag is disabled.
+	 *
+	 * @return void
+	 */
+	public function test_it_returns_legacy_email_preview_by_default() {
+		$message        = $this->sut->render();
+		$legacy_title   = 'HTML email template';
+		$legacy_content = 'Lorem ipsum dolor sit amet';
+		$this->assertStringContainsString( $legacy_title, $message );
+		$this->assertStringContainsString( $legacy_content, $message );
+	}
+
+	/**
+	 * Tests that it returns processing order email preview when feature flag is enabled.
+	 *
+	 * @return void
+	 */
+	public function test_it_returns_order_email_preview_under_feature_flag() {
+		update_option( 'woocommerce_feature_email_improvements_enabled', 'yes' );
+		$message       = $this->sut->render();
+		$order_title   = 'Thank you for your order';
+		$order_content = "Just to let you know — we've received your order #12345, and it is now being processed:";
+		$order_product = 'Dummy Product';
+		$this->assertStringContainsString( $order_title, $message );
+		$this->assertStringContainsString( $order_content, $message );
+		$this->assertStringContainsString( $order_product, $message );
+	}
+}