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

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

give / includes Last commit date

class-give-db-donors.php

640 lines

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