class-give-db-donors.php — GiveWP – Donation Plugin and Fundraising Platform 2.4.5

give / includes / class-give-db-donors.php

give / includes Last commit date

class-give-db-donors.php

653 lines

1	<?php
2	/**
3	* Donors DB
4	*
5	* @package Give
6	* @subpackage Classes/Give_DB_Donors
7	* @copyright Copyright (c) 2016, GiveWP
8	* @license https://opensource.org/licenses/gpl-license GNU Public License
9	* @since 1.0
10	*/
11
12	// Exit if accessed directly.
13	if ( ! defined( 'ABSPATH' ) ) {
14	exit;
15	}
16
17	/**
18	* Give_DB_Donors Class
19	*
20	* This class is for interacting with the donor database table.
21	*
22	* @since 1.0
23	*/
24	class Give_DB_Donors extends Give_DB {
25
26	/**
27	* Give_DB_Donors constructor.
28	*
29	* Set up the Give DB Donor class.
30	*
31	* @since 1.0
32	* @access public
33	*/
34	public function __construct() {
35	/* @var WPDB $wpdb */
36	global $wpdb;
37
38	$wpdb->donors = $this->table_name = "{$wpdb->prefix}give_donors";
39	$this->primary_key = 'id';
40	$this->version = '1.0';
41
42	$this->bc_200_params();
43
44	parent::__construct();
45	}
46
47	/**
48	* Get columns and formats
49	*
50	* @since 1.0
51	* @access public
52	*
53	* @return array Columns and formats.
54	*/
55	public function get_columns() {
56	return array(
57	'id' => '%d',
58	'user_id' => '%d',
59	'name' => '%s',
60	'email' => '%s',
61	'payment_ids' => '%s',
62	'purchase_value' => '%f',
63	'purchase_count' => '%d',
64	'notes' => '%s',
65	'date_created' => '%s',
66	'token' => '%s',
67	'verify_key' => '%s',
68	'verify_throttle' => '%s',
69	);
70	}
71
72	/**
73	* Get default column values
74	*
75	* @since 1.0
76	* @access public
77	*
78	* @return array Default column values.
79	*/
80	public function get_column_defaults() {
81	return array(
82	'user_id' => 0,
83	'email' => '',
84	'name' => '',
85	'payment_ids' => '',
86	'purchase_value' => 0.00,
87	'purchase_count' => 0,
88	'notes' => '',
89	'date_created' => date( 'Y-m-d H:i:s' ),
90	'token' => '',
91	'verify_key' => '',
92	'verify_throttle' => '',
93	);
94	}
95
96	/**
97	* Add a donor
98	*
99	* @param array $data List of donor data to add.
100	*
101	* @since 1.0
102	* @access public
103	*
104	* @return int\|bool
105	*/
106	public function add( $data = array() ) {
107
108	$defaults = array(
109	'payment_ids' => '',
110	);
111
112	$args = wp_parse_args( $data, $defaults );
113
114	if ( empty( $args['email'] ) ) {
115	return false;
116	}
117
118	if ( ! empty( $args['payment_ids'] ) && is_array( $args['payment_ids'] ) ) {
119	$args['payment_ids'] = implode( ',', array_unique( array_values( $args['payment_ids'] ) ) );
120	}
121
122	$donor = $this->get_donor_by( 'email', $args['email'] );
123
124	// update an existing donor.
125	if ( $donor ) {
126
127	// Update the payment IDs attached to the donor
128	if ( ! empty( $args['payment_ids'] ) ) {
129
130	if ( empty( $donor->payment_ids ) ) {
131
132	$donor->payment_ids = $args['payment_ids'];
133
134	} else {
135
136	$existing_ids = array_map( 'absint', explode( ',', $donor->payment_ids ) );
137	$payment_ids = array_map( 'absint', explode( ',', $args['payment_ids'] ) );
138	$payment_ids = array_merge( $payment_ids, $existing_ids );
139	$donor->payment_ids = implode( ',', array_unique( array_values( $payment_ids ) ) );
140
141	}
142
143	$args['payment_ids'] = $donor->payment_ids;
144
145	}
146
147	$this->update( $donor->id, $args );
148
149	return $donor->id;
150
151	} else {
152
153	return $this->insert( $args, 'donor' );
154
155	}
156
157	}
158
159
160	/**
161	* Update a donor.
162	*
163	*
164	* @param int $row_id
165	* @param array $data
166	* @param string $where
167	*
168	* @return bool
169	*/
170	public function update( $row_id, $data = array(), $where = '' ) {
171
172	$status = parent::update( $row_id, $data, $where );
173
174	if ( $status ) {
175	Give_Cache::delete_group( $row_id, 'give-donors' );
176	}
177
178	return $status;
179	}
180
181	/**
182	* Insert a donor.
183	*
184	* @param array $data
185	* @param string $type
186	*
187	* @return int
188	*/
189	public function insert( $data, $type = '' ) {
190	$donor_id = parent::insert( $data, $type );
191
192	if ( $donor_id ) {
193	Give_Cache::delete_group( $donor_id, 'give-donors' );
194	}
195
196	return $donor_id;
197	}
198
199	/**
200	* Delete a donor.
201	*
202	* NOTE: This should not be called directly as it does not make necessary changes to
203	* the payment meta and logs. Use give_donor_delete() instead.
204	*
205	* @param bool\|string\|int $_id_or_email ID or Email of Donor.
206	*
207	* @since 1.0
208	* @access public
209	*
210	* @return bool\|int
211	*/
212	public function delete( $_id_or_email = false ) {
213
214	if ( empty( $_id_or_email ) ) {
215	return false;
216	}
217
218	$column = is_email( $_id_or_email ) ? 'email' : 'id';
219	$donor = $this->get_donor_by( $column, $_id_or_email );
220
221	if ( $donor->id > 0 ) {
222
223	global $wpdb;
224
225	/**
226	* Deleting the donor meta.
227	*
228	* @since 1.8.14
229	*/
230	Give()->donor_meta->delete_all_meta( $donor->id );
231
232	// Cache already deleted in delete_all_meta fn.
233
234	return $wpdb->delete( $this->table_name, array( 'id' => $donor->id ), array( '%d' ) );
235
236	} else {
237	return false;
238	}
239
240	}
241
242	/**
243	* Delete a donor by user ID.
244	*
245	* NOTE: This should not be called directly as it does not make necessary changes to
246	* the payment meta and logs. Use give_donor_delete() instead.
247	*
248	* @since 1.0
249	* @access public
250	*
251	* @param int\|bool $user_id
252	*
253	* @return bool\|int
254	*/
255	public function delete_by_user_id( $user_id = false ) {
256	global $wpdb;
257
258	if ( empty( $user_id ) ) {
259	return false;
260	}
261
262	/**
263	* Deleting the donor meta.
264	*
265	* @since 1.8.14
266	*/
267	$donor = new Give_Donor( $user_id, true );
268	if ( ! empty( $donor->id ) ) {
269	Give()->donor_meta->delete_all_meta( $donor->id );
270	}
271
272	// Cache is already deleted in delete_all_meta fn.
273
274	return $wpdb->delete( $this->table_name, array( 'user_id' => $user_id ), array( '%d' ) );
275	}
276
277	/**
278	* Checks if a donor exists
279	*
280	* @param string $value The value to search for. Default is empty.
281	* @param string $field The Donor ID or email to search in. Default is 'email'.
282	*
283	* @since 1.0
284	* @access public
285	*
286	* @return bool True is exists, false otherwise.
287	*/
288	public function exists( $value = '', $field = 'email' ) {
289
290	$columns = $this->get_columns();
291	if ( ! array_key_exists( $field, $columns ) ) {
292	return false;
293	}
294
295	return (bool) $this->get_column_by( 'id', $field, $value );
296
297	}
298
299	/**
300	* Attaches a payment ID to a donor
301	*
302	* @since 1.0
303	* @access public
304	*
305	* @param int $donor_id Donor ID.
306	* @param int $payment_id Payment ID.
307	*
308	* @return bool
309	*/
310	public function attach_payment( $donor_id = 0, $payment_id = 0 ) {
311
312	$donor = new Give_Donor( $donor_id );
313
314	if ( empty( $donor->id ) ) {
315	return false;
316	}
317
318	// Attach the payment, but don't increment stats, as this function previously did not
319	return $donor->attach_payment( $payment_id, false );
320
321	}
322
323	/**
324	* Removes a payment ID from a donor.
325	*
326	* @since 1.0
327	* @access public
328	*
329	* @param int $donor_id Donor ID.
330	* @param int $payment_id Payment ID.
331	*
332	* @return bool
333	*/
334	public function remove_payment( $donor_id = 0, $payment_id = 0 ) {
335
336	$donor = new Give_Donor( $donor_id );
337
338	if ( ! $donor ) {
339	return false;
340	}
341
342	// Remove the payment, but don't decrease stats, as this function previously did not
343	return $donor->remove_payment( $payment_id, false );
344
345	}
346
347	/**
348	* Increments donor's donation stats.
349	*
350	* @access public
351	*
352	* @param int $donor_id Donor ID.
353	* @param float $amount THe amount to increase.
354	*
355	* @return bool
356	*/
357	public function increment_stats( $donor_id = 0, $amount = 0.00 ) {
358
359	$donor = new Give_Donor( $donor_id );
360
361	if ( empty( $donor->id ) ) {
362	return false;
363	}
364
365	$increased_count = $donor->increase_purchase_count();
366	$increased_value = $donor->increase_value( $amount );
367
368	return ( $increased_count && $increased_value ) ? true : false;
369
370	}
371
372	/**
373	* Decrements donor's donation stats.
374	*
375	* @since 1.0
376	* @access public
377	*
378	* @param int $donor_id Donor ID.
379	* @param float $amount Amount.
380	*
381	* @return bool
382	*/
383	public function decrement_stats( $donor_id = 0, $amount = 0.00 ) {
384
385	$donor = new Give_Donor( $donor_id );
386
387	if ( ! $donor ) {
388	return false;
389	}
390
391	$decreased_count = $donor->decrease_donation_count();
392	$decreased_value = $donor->decrease_value( $amount );
393
394	return ( $decreased_count && $decreased_value ) ? true : false;
395
396	}
397
398	/**
399	* Retrieves a single donor from the database
400	*
401	* @since 1.0
402	* @access public
403	*
404	* @param string $field ID or email. Default is 'id'.
405	* @param mixed $value The Customer ID or email to search. Default is 0.
406	*
407	* @return mixed Upon success, an object of the donor. Upon failure, NULL
408	*/
409	public function get_donor_by( $field = 'id', $value = 0 ) {
410	$value = sanitize_text_field( $value );
411
412	// Bailout.
413	if ( empty( $field ) \|\| empty( $value ) ) {
414	return null;
415	}
416
417	// Verify values.
418	if ( 'id' === $field \|\| 'user_id' === $field ) {
419	// Make sure the value is numeric to avoid casting objects, for example,
420	// to int 1.
421	if ( ! is_numeric( $value ) ) {
422	return false;
423	}
424
425	$value = absint( $value );
426
427	if ( $value < 1 ) {
428	return false;
429	}
430
431	} elseif ( 'email' === $field ) {
432
433	if ( ! is_email( $value ) ) {
434	return false;
435	}
436
437	$value = trim( $value );
438	}
439
440	// Bailout
441	if ( ! $value ) {
442	return false;
443	}
444
445	// Set query params.
446	switch ( $field ) {
447	case 'id':
448	$args['donor'] = $value;
449	break;
450	case 'email':
451	$args['email'] = $value;
452	break;
453	case 'user_id':
454	$args['user'] = $value;
455	break;
456	default:
457	return false;
458	}
459
460	// Get donors.
461	$donor = new Give_Donors_Query( $args );
462
463	if ( ! $donor = $donor->get_donors() ) {
464	// Look for donor from an additional email.
465	$args = array(
466	'meta_query' => array(
467	array(
468	'key' => 'additional_email',
469	'value' => $value,
470	),
471	),
472	);
473
474	$donor = new Give_Donors_Query( $args );
475	$donor = $donor->get_donors();
476
477	if ( empty( $donor ) ) {
478	return false;
479	}
480	}
481
482	return current( $donor );
483	}
484
485	/**
486	* This function will return donor details by token id.
487	*
488	* Note: This function is for internal purposes only. Don't use this function as it will be deprecated soon.
489	*
490	* @param int $id Email Access Token ID.
491	*
492	* @since 2.3.1
493	*
494	* @return object
495	*/
496	public function get_donor_by_token( $id ) {
497	global $wpdb;
498	$row = $wpdb->get_row(
499	$wpdb->prepare( "SELECT * FROM {$wpdb->donors} WHERE verify_key = %s LIMIT 1", $id )
500	);
501	return $row;
502	}
503
504	/**
505	* Retrieve donors from the database.
506	*
507	* @since 1.0
508	* @access public
509	*
510	* @param array $args
511	*
512	* @return array\|object\|null Donors array or object. Null if not found.
513	*/
514	public function get_donors( $args = array() ) {
515	$this->bc_1814_params( $args );
516
517	$donors = new Give_Donors_Query( $args );
518
519	return $donors->get_donors();
520
521	}
522
523
524	/**
525	* Count the total number of donors in the database
526	*
527	* @since 1.0
528	* @access public
529	*
530	* @param array $args
531	*
532	* @return int Total number of donors.
533	*/
534	public function count( $args = array() ) {
535	$this->bc_1814_params( $args );
536	$args['count'] = true;
537
538	$cache_key = md5( 'give_donors_count' . serialize( $args ) );
539	$count = Give_Cache::get_group( $cache_key, 'donors' );
540
541	if ( is_null( $count ) ) {
542	$donors = new Give_Donors_Query( $args );
543	$count = $donors->get_donors();
544
545	Give_Cache::set_group( $cache_key, $count, 'donors', 3600 );
546	}
547
548	return absint( $count );
549
550	}
551
552	/**
553	* Create the table
554	*
555	* @since 1.0
556	* @access public
557	*
558	* @return void
559	*/
560	public function create_table() {
561
562	require_once( ABSPATH . 'wp-admin/includes/upgrade.php' );
563
564	$sql = "CREATE TABLE " . $this->table_name . " (
565	id bigint(20) NOT NULL AUTO_INCREMENT,
566	user_id bigint(20) NOT NULL,
567	email varchar(255) NOT NULL,
568	name mediumtext NOT NULL,
569	purchase_value mediumtext NOT NULL,
570	purchase_count bigint(20) NOT NULL,
571	payment_ids longtext NOT NULL,
572	notes longtext NOT NULL,
573	date_created datetime NOT NULL,
574	token VARCHAR(255) CHARACTER SET utf8 NOT NULL,
575	verify_key VARCHAR(255) CHARACTER SET utf8 NOT NULL,
576	verify_throttle DATETIME NOT NULL,
577	PRIMARY KEY (id),
578	UNIQUE KEY email (email),
579	KEY user (user_id)
580	) CHARACTER SET utf8 COLLATE utf8_general_ci;";
581
582	dbDelta( $sql );
583
584	update_option( $this->table_name . '_db_version', $this->version, false );
585	}
586
587	/**
588	* Add backward compatibility for old table name
589	*
590	* @since 2.0
591	* @access private
592	* @global wpdb $wpdb
593	*/
594	private function bc_200_params() {
595	/* @var wpdb $wpdb */
596	global $wpdb;
597
598	if (
599	! give_has_upgrade_completed( 'v20_rename_donor_tables' ) &&
600	$wpdb->query( $wpdb->prepare( "SHOW TABLES LIKE %s", "{$wpdb->prefix}give_customers" ) )
601	) {
602	$wpdb->donors = $this->table_name = "{$wpdb->prefix}give_customers";
603	}
604	}
605
606	/**
607	* Add backward compatibility for deprecated param
608	*
609	* @since 1.8.14
610	* @access private
611	*
612	* @param $args
613	*/
614	private function bc_1814_params( &$args ) {
615	// Backward compatibility: user_id
616	if ( ! empty( $args['user_id'] ) ) {
617	$args['user'] = $args['user_id'];
618	}
619
620	// Backward compatibility: id
621	if ( ! empty( $args['id'] ) ) {
622	$args['donor'] = $args['id'];
623	}
624
625	// Backward compatibility: name
626	if ( ! empty( $args['name'] ) ) {
627	$args['s'] = "name:{$args['name']}";
628	}
629
630	// Backward compatibility: date
631	// Donors created for a specific date or in a date range.
632	if ( ! empty( $args['date'] ) ) {
633
634	if ( is_array( $args['date'] ) ) {
635
636	if ( ! empty( $args['date']['start'] ) ) {
637	$args['date_query']['after'] = date( 'Y-m-d H:i:s', strtotime( $args['date']['start'] ) );
638	}
639
640	if ( ! empty( $args['date']['end'] ) ) {
641	$args['date_query']['before'] = date( 'Y-m-d H:i:s', strtotime( $args['date']['end'] ) );
642	}
643
644	} else {
645
646	$args['date_query']['year'] = date( 'Y', strtotime( $args['date'] ) );
647	$args['date_query']['month'] = date( 'm', strtotime( $args['date'] ) );
648	$args['date_query']['day'] = date( 'd', strtotime( $args['date'] ) );
649	}
650	}
651	}
652	}
653