class-wc-emails.php — WooCommerce 3.4.1

woocommerce / includes / class-wc-emails.php

woocommerce / includes Last commit date

class-wc-emails.php

660 lines

1	<?php
2	/**
3	* Transactional Emails Controller
4	*
5	* WooCommerce Emails Class which handles the sending on transactional emails and email templates. This class loads in available emails.
6	*
7	* @package WooCommerce/Classes/Emails
8	* @version 2.3.0
9	*/
10
11	defined( 'ABSPATH' ) \|\| exit;
12
13	/**
14	* Emails class.
15	*/
16	class WC_Emails {
17
18	/**
19	* Array of email notification classes
20	*
21	* @var array
22	*/
23	public $emails = array();
24
25	/**
26	* The single instance of the class
27	*
28	* @var WC_Emails
29	*/
30	protected static $_instance = null;
31
32	/**
33	* Background emailer class.
34	*
35	* @var WC_Background_Emailer
36	*/
37	protected static $background_emailer = null;
38
39	/**
40	* Main WC_Emails Instance.
41	*
42	* Ensures only one instance of WC_Emails is loaded or can be loaded.
43	*
44	* @since 2.1
45	* @static
46	* @return WC_Emails Main instance
47	*/
48	public static function instance() {
49	if ( is_null( self::$_instance ) ) {
50	self::$_instance = new self();
51	}
52	return self::$_instance;
53	}
54
55	/**
56	* Cloning is forbidden.
57	*
58	* @since 2.1
59	*/
60	public function __clone() {
61	wc_doing_it_wrong( __FUNCTION__, __( 'Cloning is forbidden.', 'woocommerce' ), '2.1' );
62	}
63
64	/**
65	* Unserializing instances of this class is forbidden.
66	*
67	* @since 2.1
68	*/
69	public function __wakeup() {
70	wc_doing_it_wrong( __FUNCTION__, __( 'Unserializing instances of this class is forbidden.', 'woocommerce' ), '2.1' );
71	}
72
73	/**
74	* Hook in all transactional emails.
75	*/
76	public static function init_transactional_emails() {
77	$email_actions = apply_filters(
78	'woocommerce_email_actions', array(
79	'woocommerce_low_stock',
80	'woocommerce_no_stock',
81	'woocommerce_product_on_backorder',
82	'woocommerce_order_status_pending_to_processing',
83	'woocommerce_order_status_pending_to_completed',
84	'woocommerce_order_status_processing_to_cancelled',
85	'woocommerce_order_status_pending_to_failed',
86	'woocommerce_order_status_pending_to_on-hold',
87	'woocommerce_order_status_failed_to_processing',
88	'woocommerce_order_status_failed_to_completed',
89	'woocommerce_order_status_failed_to_on-hold',
90	'woocommerce_order_status_on-hold_to_processing',
91	'woocommerce_order_status_on-hold_to_cancelled',
92	'woocommerce_order_status_on-hold_to_failed',
93	'woocommerce_order_status_completed',
94	'woocommerce_order_fully_refunded',
95	'woocommerce_order_partially_refunded',
96	'woocommerce_new_customer_note',
97	'woocommerce_created_customer',
98	)
99	);
100
101	if ( apply_filters( 'woocommerce_defer_transactional_emails', false ) ) {
102	self::$background_emailer = new WC_Background_Emailer();
103
104	foreach ( $email_actions as $action ) {
105	add_action( $action, array( __CLASS__, 'queue_transactional_email' ), 10, 10 );
106	}
107	} else {
108	foreach ( $email_actions as $action ) {
109	add_action( $action, array( __CLASS__, 'send_transactional_email' ), 10, 10 );
110	}
111	}
112	}
113
114	/**
115	* Queues transactional email so it's not sent in current request if enabled,
116	* otherwise falls back to send now.
117	*/
118	public static function queue_transactional_email() {
119	if ( is_a( self::$background_emailer, 'WC_Background_Emailer' ) ) {
120	self::$background_emailer->push_to_queue(
121	array(
122	'filter' => current_filter(),
123	'args' => func_get_args(),
124	)
125	);
126	} else {
127	call_user_func_array( array( __CLASS__, 'send_transactional_email' ), func_get_args() );
128	}
129	}
130
131	/**
132	* Init the mailer instance and call the notifications for the current filter.
133	*
134	* @internal
135	*
136	* @param string $filter Filter name.
137	* @param array $args Email args (default: []).
138	*/
139	public static function send_queued_transactional_email( $filter = '', $args = array() ) {
140	if ( apply_filters( 'woocommerce_allow_send_queued_transactional_email', true, $filter, $args ) ) {
141	self::instance(); // Init self so emails exist.
142
143	// Ensure gateways are loaded in case they need to insert data into the emails.
144	WC()->payment_gateways();
145	WC()->shipping();
146
147	do_action_ref_array( $filter . '_notification', $args );
148	}
149	}
150
151	/**
152	* Init the mailer instance and call the notifications for the current filter.
153	*
154	* @internal
155	*
156	* @param array $args Email args (default: []).
157	*/
158	public static function send_transactional_email( $args = array() ) {
159	try {
160	$args = func_get_args();
161	self::instance(); // Init self so emails exist.
162	do_action_ref_array( current_filter() . '_notification', $args );
163	} catch ( Exception $e ) {
164	if ( defined( 'WP_DEBUG' ) && WP_DEBUG ) {
165	trigger_error( 'Transactional email triggered fatal error for callback ' . current_filter(), E_USER_WARNING ); // phpcs:ignore WordPress.XSS.EscapeOutput.OutputNotEscaped, WordPress.PHP.DevelopmentFunctions.error_log_trigger_error
166	}
167	}
168	}
169
170	/**
171	* Constructor for the email class hooks in all emails that can be sent.
172	*/
173	public function __construct() {
174	$this->init();
175
176	// Email Header, Footer and content hooks.
177	add_action( 'woocommerce_email_header', array( $this, 'email_header' ) );
178	add_action( 'woocommerce_email_footer', array( $this, 'email_footer' ) );
179	add_action( 'woocommerce_email_order_details', array( $this, 'order_downloads' ), 10, 4 );
180	add_action( 'woocommerce_email_order_details', array( $this, 'order_details' ), 10, 4 );
181	add_action( 'woocommerce_email_order_meta', array( $this, 'order_meta' ), 10, 3 );
182	add_action( 'woocommerce_email_customer_details', array( $this, 'customer_details' ), 10, 3 );
183	add_action( 'woocommerce_email_customer_details', array( $this, 'email_addresses' ), 20, 3 );
184
185	// Hooks for sending emails during store events.
186	add_action( 'woocommerce_low_stock_notification', array( $this, 'low_stock' ) );
187	add_action( 'woocommerce_no_stock_notification', array( $this, 'no_stock' ) );
188	add_action( 'woocommerce_product_on_backorder_notification', array( $this, 'backorder' ) );
189	add_action( 'woocommerce_created_customer_notification', array( $this, 'customer_new_account' ), 10, 3 );
190
191	// Hook for replacing {site_title} in email-footer.
192	add_filter( 'woocommerce_email_footer_text', array( $this, 'email_footer_replace_site_title' ) );
193
194	// Let 3rd parties unhook the above via this hook.
195	do_action( 'woocommerce_email', $this );
196	}
197
198	/**
199	* Init email classes.
200	*/
201	public function init() {
202	// Include email classes.
203	include_once dirname( __FILE__ ) . '/emails/class-wc-email.php';
204
205	$this->emails['WC_Email_New_Order'] = include 'emails/class-wc-email-new-order.php';
206	$this->emails['WC_Email_Cancelled_Order'] = include 'emails/class-wc-email-cancelled-order.php';
207	$this->emails['WC_Email_Failed_Order'] = include 'emails/class-wc-email-failed-order.php';
208	$this->emails['WC_Email_Customer_On_Hold_Order'] = include 'emails/class-wc-email-customer-on-hold-order.php';
209	$this->emails['WC_Email_Customer_Processing_Order'] = include 'emails/class-wc-email-customer-processing-order.php';
210	$this->emails['WC_Email_Customer_Completed_Order'] = include 'emails/class-wc-email-customer-completed-order.php';
211	$this->emails['WC_Email_Customer_Refunded_Order'] = include 'emails/class-wc-email-customer-refunded-order.php';
212	$this->emails['WC_Email_Customer_Invoice'] = include 'emails/class-wc-email-customer-invoice.php';
213	$this->emails['WC_Email_Customer_Note'] = include 'emails/class-wc-email-customer-note.php';
214	$this->emails['WC_Email_Customer_Reset_Password'] = include 'emails/class-wc-email-customer-reset-password.php';
215	$this->emails['WC_Email_Customer_New_Account'] = include 'emails/class-wc-email-customer-new-account.php';
216
217	$this->emails = apply_filters( 'woocommerce_email_classes', $this->emails );
218
219	// include css inliner.
220	if ( ! class_exists( 'Emogrifier' ) && class_exists( 'DOMDocument' ) ) {
221	include_once dirname( __FILE__ ) . '/libraries/class-emogrifier.php';
222	}
223	}
224
225	/**
226	* Return the email classes - used in admin to load settings.
227	*
228	* @return array
229	*/
230	public function get_emails() {
231	return $this->emails;
232	}
233
234	/**
235	* Get from name for email.
236	*
237	* @return string
238	*/
239	public function get_from_name() {
240	return wp_specialchars_decode( get_option( 'woocommerce_email_from_name' ), ENT_QUOTES );
241	}
242
243	/**
244	* Get from email address.
245	*
246	* @return string
247	*/
248	public function get_from_address() {
249	return sanitize_email( get_option( 'woocommerce_email_from_address' ) );
250	}
251
252	/**
253	* Get the email header.
254	*
255	* @param mixed $email_heading Heading for the email.
256	*/
257	public function email_header( $email_heading ) {
258	wc_get_template( 'emails/email-header.php', array( 'email_heading' => $email_heading ) );
259	}
260
261	/**
262	* Get the email footer.
263	*/
264	public function email_footer() {
265	wc_get_template( 'emails/email-footer.php' );
266	}
267
268	/**
269	* Filter callback to replace {site_title} in email footer
270	*
271	* @since 3.3.0
272	* @param string $string Email footer text.
273	* @return string Email footer text with any replacements done.
274	*/
275	public function email_footer_replace_site_title( $string ) {
276	return str_replace( '{site_title}', $this->get_blogname(), $string );
277	}
278
279	/**
280	* Wraps a message in the woocommerce mail template.
281	*
282	* @param string $email_heading Heading text.
283	* @param string $message Email message.
284	* @param bool $plain_text Set true to send as plain text. Default to false.
285	*
286	* @return string
287	*/
288	public function wrap_message( $email_heading, $message, $plain_text = false ) {
289	// Buffer.
290	ob_start();
291
292	do_action( 'woocommerce_email_header', $email_heading, null );
293
294	echo wpautop( wptexturize( $message ) ); // WPCS: XSS ok.
295
296	do_action( 'woocommerce_email_footer', null );
297
298	// Get contents.
299	$message = ob_get_clean();
300
301	return $message;
302	}
303
304	/**
305	* Send the email.
306	*
307	* @param mixed $to Receiver.
308	* @param mixed $subject Email subject.
309	* @param mixed $message Message.
310	* @param string $headers Email headers (default: "Content-Type: text/html\r\n").
311	* @param string $attachments Attachments (default: "").
312	* @return bool
313	*/
314	public function send( $to, $subject, $message, $headers = "Content-Type: text/html\r\n", $attachments = '' ) {
315	// Send.
316	$email = new WC_Email();
317	return $email->send( $to, $subject, $message, $headers, $attachments );
318	}
319
320	/**
321	* Prepare and send the customer invoice email on demand.
322	*
323	* @param int\|WC_Order $order Order instance or ID.
324	*/
325	public function customer_invoice( $order ) {
326	$email = $this->emails['WC_Email_Customer_Invoice'];
327
328	if ( ! is_object( $order ) ) {
329	$order = wc_get_order( absint( $order ) );
330	}
331
332	$email->trigger( $order->get_id(), $order );
333	}
334
335	/**
336	* Customer new account welcome email.
337	*
338	* @param int $customer_id Customer ID.
339	* @param array $new_customer_data New customer data.
340	* @param bool $password_generated If password is generated.
341	*/
342	public function customer_new_account( $customer_id, $new_customer_data = array(), $password_generated = false ) {
343	if ( ! $customer_id ) {
344	return;
345	}
346
347	$user_pass = ! empty( $new_customer_data['user_pass'] ) ? $new_customer_data['user_pass'] : '';
348
349	$email = $this->emails['WC_Email_Customer_New_Account'];
350	$email->trigger( $customer_id, $user_pass, $password_generated );
351	}
352
353	/**
354	* Show the order details table
355	*
356	* @param WC_Order $order Order instance.
357	* @param bool $sent_to_admin If should sent to admin.
358	* @param bool $plain_text If is plain text email.
359	* @param string $email Email address.
360	*/
361	public function order_details( $order, $sent_to_admin = false, $plain_text = false, $email = '' ) {
362	if ( $plain_text ) {
363	wc_get_template(
364	'emails/plain/email-order-details.php', array(
365	'order' => $order,
366	'sent_to_admin' => $sent_to_admin,
367	'plain_text' => $plain_text,
368	'email' => $email,
369	)
370	);
371	} else {
372	wc_get_template(
373	'emails/email-order-details.php', array(
374	'order' => $order,
375	'sent_to_admin' => $sent_to_admin,
376	'plain_text' => $plain_text,
377	'email' => $email,
378	)
379	);
380	}
381	}
382
383	/**
384	* Show order downloads in a table.
385	*
386	* @since 3.2.0
387	* @param WC_Order $order Order instance.
388	* @param bool $sent_to_admin If should sent to admin.
389	* @param bool $plain_text If is plain text email.
390	* @param string $email Email address.
391	*/
392	public function order_downloads( $order, $sent_to_admin = false, $plain_text = false, $email = '' ) {
393	$show_downloads = $order->has_downloadable_item() && $order->is_download_permitted() && ! $sent_to_admin;
394
395	if ( ! $show_downloads ) {
396	return;
397	}
398
399	$downloads = $order->get_downloadable_items();
400	$columns = apply_filters(
401	'woocommerce_email_downloads_columns', array(
402	'download-product' => __( 'Product', 'woocommerce' ),
403	'download-expires' => __( 'Expires', 'woocommerce' ),
404	'download-file' => __( 'Download', 'woocommerce' ),
405	)
406	);
407
408	if ( $plain_text ) {
409	wc_get_template(
410	'emails/plain/email-downloads.php', array(
411	'order' => $order,
412	'sent_to_admin' => $sent_to_admin,
413	'plain_text' => $plain_text,
414	'email' => $email,
415	'downloads' => $downloads,
416	'columns' => $columns,
417	)
418	);
419	} else {
420	wc_get_template(
421	'emails/email-downloads.php', array(
422	'order' => $order,
423	'sent_to_admin' => $sent_to_admin,
424	'plain_text' => $plain_text,
425	'email' => $email,
426	'downloads' => $downloads,
427	'columns' => $columns,
428	)
429	);
430	}
431	}
432
433	/**
434	* Add order meta to email templates.
435	*
436	* @param WC_Order $order Order instance.
437	* @param bool $sent_to_admin If should sent to admin.
438	* @param bool $plain_text If is plain text email.
439	*/
440	public function order_meta( $order, $sent_to_admin = false, $plain_text = false ) {
441	$fields = apply_filters( 'woocommerce_email_order_meta_fields', array(), $sent_to_admin, $order );
442
443	/**
444	* Deprecated woocommerce_email_order_meta_keys filter.
445	*
446	* @since 2.3.0
447	*/
448	$_fields = apply_filters( 'woocommerce_email_order_meta_keys', array(), $sent_to_admin );
449
450	if ( $_fields ) {
451	foreach ( $_fields as $key => $field ) {
452	if ( is_numeric( $key ) ) {
453	$key = $field;
454	}
455
456	$fields[ $key ] = array(
457	'label' => wptexturize( $key ),
458	'value' => wptexturize( get_post_meta( $order->get_id(), $field, true ) ),
459	);
460	}
461	}
462
463	if ( $fields ) {
464
465	if ( $plain_text ) {
466
467	foreach ( $fields as $field ) {
468	if ( isset( $field['label'] ) && isset( $field['value'] ) && $field['value'] ) {
469	echo $field['label'] . ': ' . $field['value'] . "\n"; // WPCS: XSS ok.
470	}
471	}
472	} else {
473
474	foreach ( $fields as $field ) {
475	if ( isset( $field['label'] ) && isset( $field['value'] ) && $field['value'] ) {
476	echo '<p><strong>' . $field['label'] . ':</strong> ' . $field['value'] . '</p>'; // WPCS: XSS ok.
477	}
478	}
479	}
480	}
481	}
482
483	/**
484	* Is customer detail field valid?
485	*
486	* @param array $field Field data to check if is valid.
487	* @return boolean
488	*/
489	public function customer_detail_field_is_valid( $field ) {
490	return isset( $field['label'] ) && ! empty( $field['value'] );
491	}
492
493	/**
494	* Allows developers to add additional customer details to templates.
495	*
496	* In versions prior to 3.2 this was used for notes, phone and email but this data has moved.
497	*
498	* @param WC_Order $order Order instance.
499	* @param bool $sent_to_admin If should sent to admin.
500	* @param bool $plain_text If is plain text email.
501	*/
502	public function customer_details( $order, $sent_to_admin = false, $plain_text = false ) {
503	if ( ! is_a( $order, 'WC_Order' ) ) {
504	return;
505	}
506
507	$fields = array_filter( apply_filters( 'woocommerce_email_customer_details_fields', array(), $sent_to_admin, $order ), array( $this, 'customer_detail_field_is_valid' ) );
508
509	if ( ! empty( $fields ) ) {
510	if ( $plain_text ) {
511	wc_get_template( 'emails/plain/email-customer-details.php', array( 'fields' => $fields ) );
512	} else {
513	wc_get_template( 'emails/email-customer-details.php', array( 'fields' => $fields ) );
514	}
515	}
516	}
517
518	/**
519	* Get the email addresses.
520	*
521	* @param WC_Order $order Order instance.
522	* @param bool $sent_to_admin If should sent to admin.
523	* @param bool $plain_text If is plain text email.
524	*/
525	public function email_addresses( $order, $sent_to_admin = false, $plain_text = false ) {
526	if ( ! is_a( $order, 'WC_Order' ) ) {
527	return;
528	}
529	if ( $plain_text ) {
530	wc_get_template(
531	'emails/plain/email-addresses.php', array(
532	'order' => $order,
533	'sent_to_admin' => $sent_to_admin,
534	)
535	);
536	} else {
537	wc_get_template(
538	'emails/email-addresses.php', array(
539	'order' => $order,
540	'sent_to_admin' => $sent_to_admin,
541	)
542	);
543	}
544	}
545
546	/**
547	* Get blog name formatted for emails.
548	*
549	* @return string
550	*/
551	private function get_blogname() {
552	return wp_specialchars_decode( get_option( 'blogname' ), ENT_QUOTES );
553	}
554
555	/**
556	* Low stock notification email.
557	*
558	* @param WC_Product $product Product instance.
559	*/
560	public function low_stock( $product ) {
561	if ( 'no' === get_option( 'woocommerce_notify_low_stock', 'yes' ) ) {
562	return;
563	}
564
565	$subject = sprintf( '[%s] %s', $this->get_blogname(), __( 'Product low in stock', 'woocommerce' ) );
566	$message = sprintf(
567	/* translators: 1: product name 2: items in stock */
568	__( '%1$s is low in stock. There are %2$d left.', 'woocommerce' ),
569	html_entity_decode( strip_tags( $product->get_formatted_name() ), ENT_QUOTES, get_bloginfo( 'charset' ) ),
570	html_entity_decode( strip_tags( $product->get_stock_quantity() ) )
571	);
572
573	wp_mail(
574	apply_filters( 'woocommerce_email_recipient_low_stock', get_option( 'woocommerce_stock_email_recipient' ), $product ),
575	apply_filters( 'woocommerce_email_subject_low_stock', $subject, $product ),
576	apply_filters( 'woocommerce_email_content_low_stock', $message, $product ),
577	apply_filters( 'woocommerce_email_headers', '', 'low_stock', $product ),
578	apply_filters( 'woocommerce_email_attachments', array(), 'low_stock', $product )
579	);
580	}
581
582	/**
583	* No stock notification email.
584	*
585	* @param WC_Product $product Product instance.
586	*/
587	public function no_stock( $product ) {
588	if ( 'no' === get_option( 'woocommerce_notify_no_stock', 'yes' ) ) {
589	return;
590	}
591
592	$subject = sprintf( '[%s] %s', $this->get_blogname(), __( 'Product out of stock', 'woocommerce' ) );
593	/* translators: %s: product name */
594	$message = sprintf( __( '%s is out of stock.', 'woocommerce' ), html_entity_decode( strip_tags( $product->get_formatted_name() ), ENT_QUOTES, get_bloginfo( 'charset' ) ) );
595
596	wp_mail(
597	apply_filters( 'woocommerce_email_recipient_no_stock', get_option( 'woocommerce_stock_email_recipient' ), $product ),
598	apply_filters( 'woocommerce_email_subject_no_stock', $subject, $product ),
599	apply_filters( 'woocommerce_email_content_no_stock', $message, $product ),
600	apply_filters( 'woocommerce_email_headers', '', 'no_stock', $product ),
601	apply_filters( 'woocommerce_email_attachments', array(), 'no_stock', $product )
602	);
603	}
604
605	/**
606	* Backorder notification email.
607	*
608	* @param array $args Arguments.
609	*/
610	public function backorder( $args ) {
611	$args = wp_parse_args(
612	$args, array(
613	'product' => '',
614	'quantity' => '',
615	'order_id' => '',
616	)
617	);
618
619	$order = wc_get_order( $args['order_id'] );
620	if (
621	! $args['product'] \|\|
622	! is_object( $args['product'] ) \|\|
623	! $args['quantity'] \|\|
624	! $order
625	) {
626	return;
627	}
628
629	$subject = sprintf( '[%s] %s', $this->get_blogname(), __( 'Product backorder', 'woocommerce' ) );
630	/* translators: 1: product quantity 2: product name 3: order number */
631	$message = sprintf( __( '%1$s units of %2$s have been backordered in order #%3$s.', 'woocommerce' ), $args['quantity'], html_entity_decode( strip_tags( $args['product']->get_formatted_name() ), ENT_QUOTES, get_bloginfo( 'charset' ) ), $order->get_order_number() );
632
633	wp_mail(
634	apply_filters( 'woocommerce_email_recipient_backorder', get_option( 'woocommerce_stock_email_recipient' ), $args ),
635	apply_filters( 'woocommerce_email_subject_backorder', $subject, $args ),
636	apply_filters( 'woocommerce_email_content_backorder', $message, $args ),
637	apply_filters( 'woocommerce_email_headers', '', 'backorder', $args ),
638	apply_filters( 'woocommerce_email_attachments', array(), 'backorder', $args )
639	);
640	}
641
642	/**
643	* Adds Schema.org markup for order in JSON-LD format.
644	*
645	* @deprecated 3.0.0
646	* @see WC_Structured_Data::generate_order_data()
647	*
648	* @since 2.6.0
649	* @param WC_Order $order Order instance.
650	* @param bool $sent_to_admin If should sent to admin.
651	* @param bool $plain_text If is plain text email.
652	*/
653	public function order_schema_markup( $order, $sent_to_admin = false, $plain_text = false ) {
654	wc_deprecated_function( 'WC_Emails::order_schema_markup', '3.0', 'WC_Structured_Data::generate_order_data' );
655
656	WC()->structured_data->generate_order_data( $order, $sent_to_admin, $plain_text );
657	WC()->structured_data->output_structured_data();
658	}
659	}
660