charitable / includes / donations / class-charitable-donation-log.php

class-charitable-donation-log.php in Charitable – Donation & Fundraising Platform (Donation Forms, Recurring Donations & Fundraising Campaigns) 1.8.11.3, at includes/donations/class-charitable-donation-log.php

391 lines 9.1 KB

Raw Download Zip

1	<?php
2	/**
3	* Responsible for getting and updating a donation's log.
4	*
5	* @package Charitable/Classes/Charitable_Donation_Log
6	* @author David Bisset
7	* @copyright Copyright (c) 2023, WP Charitable LLC
8	* @license http://opensource.org/licenses/gpl-2.0.php GNU Public License
9	* @since 1.5.4
10	* @version 1.6.37
11	*/
12
13	// Exit if accessed directly.
14	if ( ! defined( 'ABSPATH' ) ) {
15	exit;
16	}
17
18	if ( ! class_exists( 'Charitable_Donation_Log' ) ) :
19
20	/**
21	* Charitable_Donation_Log
22	*
23	* @since 1.5.4
24	*/
25	class Charitable_Donation_Log {
26
27	/**
28	* The donation ID.
29	*
30	* @since 1.5.4
31	*
32	* @var int
33	*/
34	private $donation_id;
35
36	/**
37	* The log.
38	*
39	* @since 1.5.4
40	*
41	* @var array
42	*/
43	private $log;
44
45	/**
46	* The meta log.
47	*
48	* @since 1.5.4
49	*
50	* @var array
51	*/
52	private $meta_log;
53
54	/**
55	* The email logs.
56	*
57	* @since 1.5.4
58	*
59	* @var array
60	*/
61	private $email_logs;
62
63	/**
64	* Create class object.
65	*
66	* @since 1.5.4
67	*
68	* @param int $donation_id The donation ID.
69	*/
70	public function __construct( $donation_id ) {
71	$this->donation_id = $donation_id;
72	}
73
74	/**
75	* Add a meta log.
76	*
77	* @since 1.5.4
78	*
79	* @param string $message The message to be logged.
80	* @return int\|bool Meta ID if the key didn't exist, true on successful update,
81	* false on failure.
82	*/
83	public function add( $message ) {
84	$log = $this->get_meta_log();
85
86	array_push(
87	$log,
88	array(
89	'time' => time(),
90	'message' => $message,
91	)
92	);
93
94	$ret = update_post_meta( $this->donation_id, '_donation_log', $log );
95
96	/* Clear the meta_log */
97	unset(
98	$this->meta_log,
99	$this->log
100	);
101
102	return $ret;
103	}
104
105	/**
106	* Return the raw meta log.
107	*
108	* This is stored as post meta with the `_donation_log` meta key.
109	*
110	* @since 1.5.4
111	*
112	* @return array
113	*/
114	public function get_meta_log() {
115	if ( ! isset( $this->meta_log ) ) {
116	$this->meta_log = get_post_meta( $this->donation_id, '_donation_log', true );
117
118	if ( ! is_array( $this->meta_log ) ) {
119	$this->meta_log = array();
120	}
121	}
122
123	return $this->meta_log;
124	}
125
126	/**
127	* Get all email sending logs.
128	*
129	* @since 1.5.4
130	*
131	* @return array
132	*/
133	public function get_email_logs() {
134	if ( ! isset( $this->email_logs ) ) {
135	$logs = array_filter( $this->query_email_logs(), array( $this, 'is_valid_email_log' ) );
136	$this->email_logs = array();
137
138	foreach ( $logs as $log ) {
139	$this->email_logs = array_merge( $this->email_logs, $this->parse_email_log( $log ) );
140	}
141	}
142
143	return $this->email_logs;
144	}
145
146	/**
147	* Returns all logs combined into a single array, ordered by time.
148	*
149	* @since 1.5.4
150	*
151	* @return array
152	*/
153	public function get_log() {
154	if ( ! isset( $this->log ) ) {
155	$this->log = array_merge_recursive( $this->get_meta_log(), $this->get_email_logs() );
156
157	/**
158	* Filter the list of donation logs.
159	*
160	* @since 1.5.0
161	*
162	* @param array $logs All of the logs.
163	* @param Charitable_Donation $donation Instance of `Charitable_Donation`.
164	*/
165	$this->log = apply_filters( 'charitable_donation_logs', $this->log, charitable_get_donation( $this->donation_id ) );
166
167	/* Order the logs by time. */
168	usort( $this->log, 'charitable_timestamp_sort' );
169	}
170
171	return $this->log;
172	}
173
174	/**
175	* Executes a query to retrieve all email logs.
176	*
177	* @since 1.5.4
178	*
179	* @global WPDB $wpdb
180	* @return array
181	*/
182	private function query_email_logs() {
183	global $wpdb;
184
185	$logs = $wpdb->get_results( // phpcs:ignore
186	$wpdb->prepare(
187	"SELECT meta_key, meta_value
188	FROM $wpdb->postmeta
189	WHERE meta_key LIKE %s
190	AND post_id = %d",
191	'_email_%_log',
192	$this->donation_id
193	)
194	);
195
196	if ( is_null( $logs ) ) {
197	$logs = array();
198	}
199
200	return $logs;
201	}
202
203	/**
204	* Receives an email log record as an object and returns an array
205	* with the time and message to show in the log.
206	*
207	* @since 1.5.0
208	*
209	* @param object $log The email log record.
210	* @return array
211	*/
212	private function parse_email_log( $log ) {
213	$email = $this->get_email_log_email_id( $log );
214	$email_name = $this->get_email_name( $email );
215	$action = $this->get_email_action( $email );
216	$logs = array();
217
218	foreach ( maybe_unserialize( $log->meta_value ) as $time => $sent ) {
219	$logs[] = array(
220	'time' => $time,
221	'message' => $this->get_email_log_message( $sent, $email_name, $action ),
222	);
223	}
224
225	return $logs;
226	}
227
228	/**
229	* Checks whether the email log record is valid.
230	*
231	* @since 1.5.4
232	*
233	* @param object $log An email log object containing meta_key and meta_value properties.
234	* @return boolean
235	*/
236	private function is_valid_email_log( $log ) {
237	return $this->log_has_required_props( $log ) && $this->is_valid_email_log_value( $log );
238	}
239
240	/**
241	* Checks whether the email log has the required properties.
242	*
243	* @since 1.5.4
244	*
245	* @param object $log An email log.
246	* @return boolean
247	*/
248	private function log_has_required_props( $log ) {
249	return isset( $log->meta_key ) && isset( $log->meta_value );
250	}
251
252	/**
253	* Returns whether the log is valid.
254	*
255	* @since 1.5.4
256	*
257	* @param object $log An email log.
258	* @return boolean
259	*/
260	private function is_valid_email_log_value( $log ) {
261	return is_array( maybe_unserialize( $log->meta_value ) );
262	}
263
264	/**
265	* Returns the email log's email id.
266	*
267	* @since 1.5.4
268	*
269	* @param object $log An email log.
270	* @return string\|false The string email ID if log key has a match, or false if not.
271	*/
272	private function get_email_log_email_id( $log ) {
273	$found = preg_match( '/^_email_(.*)_log$/', $log->meta_key, $matches );
274	$email = $found ? $matches[1] : false;
275
276	/**
277	* Filter the email id we've guessed from the log.
278	*
279	* @since 1.5.6
280	*
281	* @param string $email The email id we've come up with.
282	* @param string $meta_key The email log's meta key.
283	*/
284	return apply_filters( 'charitable_email_id_from_log', $email, $log->meta_key );
285	}
286
287	/**
288	* Return the name of the email.
289	*
290	* If the email still exists in the system as a registered email type, the official name of the
291	* email will be used. If it doesn't exist, such as in cases where the email was sent by an
292	* extension which is no long installed, the email ID will be formatted into a readable format.
293	*
294	* @since 1.5.4
295	*
296	* @param string $email Email ID.
297	* @return string
298	*/
299	private function get_email_name( $email ) {
300	$class = Charitable_Emails::get_instance()->get_email( $email );
301
302	/* Fallback to formatting the email ID as readable text. */
303	if ( false === $class ) {
304	return ucwords( str_replace( '_', ' ', $email ) );
305	}
306
307	$object = new $class; // phpcs:ignore
308
309	return $object->get_name();
310	}
311
312	/**
313	* Return the email resend action.
314	*
315	* If an email no longer exists, such as in cases where the email was sent by an extension which
316	* is no long installed, false will be returned.
317	*
318	* @since 1.5.4
319	*
320	* @param string $email Email ID.
321	* @return string\|false The email action link, or false if no action can be taken.
322	*/
323	private function get_email_action( $email ) {
324	if ( false === Charitable_Emails::get_instance()->get_email( $email ) ) {
325	return false;
326	}
327
328	return Charitable_Admin::get_instance()->get_donation_actions()->get_action_link( 'resend_' . $email, $this->donation_id );
329	}
330
331	/**
332	* Return an email log message.
333	*
334	* @since 1.5.4
335	*
336	* @param boolean $sent Whether the email was sent.
337	* @param string $email_name The email name.
338	* @param string\|false $action Action link if available, or false if not.
339	* @return string
340	*/
341	private function get_email_log_message( $sent, $email_name, $action ) {
342	if ( $sent ) {
343	return $this->get_sent_email_log_message( $email_name, $action );
344	}
345
346	return $this->get_unsent_email_log_message( $email_name, $action );
347	}
348
349	/**
350	* Return an email log message for a sent email.
351	*
352	* @since 1.5.4
353	*
354	* @param string $email_name The email name.
355	* @param string\|false $action Action link if available, or false if not.
356	* @return string
357	*/
358	private function get_sent_email_log_message( $email_name, $action ) {
359	// translators: %s is the email name.
360	$message = sprintf( __( '%s was sent successfully.', 'charitable' ), $email_name );
361
362	if ( false !== $action ) {
363	$message .= sprintf( ' <a href="%s">%s</a>', $action, __( 'Resend it now', 'charitable' ) );
364	}
365
366	return $message;
367	}
368
369	/**
370	* Return an email log message for an unsent email.
371	*
372	* @since 1.5.4
373	*
374	* @param string $email_name The email name.
375	* @param string\|false $action Action link if available, or false if not.
376	* @return string
377	*/
378	private function get_unsent_email_log_message( $email_name, $action ) {
379	// translators: %s is the email name.
380	$message = sprintf( __( '%s failed to send.', 'charitable' ), $email_name );
381
382	if ( false !== $action ) {
383	$message .= sprintf( ' <a href="%s">%s</a>', $action, __( 'Retry email send', 'charitable' ) );
384	}
385
386	return $message;
387	}
388	}
389
390	endif;
391