class-wc-emails.php — WooCommerce 3.6.0-rc.3

woocommerce / includes / class-wc-emails.php

woocommerce / includes Last commit date

class-wc-emails.php

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