charitable / includes / users / class-charitable-donor.php

class-charitable-donor.php in Charitable – Donation & Fundraising Platform (Donation Forms, Recurring Donations & Fundraising Campaigns) 1.8.13, at includes/users/class-charitable-donor.php

531 lines 11.7 KB

Raw Download Zip

1	<?php
2	/**
3	* Donor model.
4	*
5	* @package Charitable/Classes/Charitable_Donor
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.0.0
10	* @version 1.6.54
11	*/
12
13	// Exit if accessed directly.
14	if ( ! defined( 'ABSPATH' ) ) {
15	exit;
16	}
17
18	if ( ! class_exists( 'Charitable_Donor' ) ) :
19
20	/**
21	* Charitable_Donor
22	*
23	* @since 1.0.0
24	*
25	* @property int $donor_id
26	* @property string $first_name
27	* @property string $last_name
28	* @property string $email
29	* @property string $date_joined
30	* @property string $data_erased
31	* @property int $contact_consent
32	*/
33	class Charitable_Donor {
34
35	/**
36	* The donor ID.
37	*
38	* @since 1.0.0
39	*
40	* @var int
41	*/
42	protected $donor_id;
43
44	/**
45	* The donor data from charitable_donors table.
46	*
47	* @since 1.0.0
48	*
49	* @var Object
50	*/
51	protected $data;
52
53	/**
54	* The donation ID.
55	*
56	* @since 1.0.0
57	*
58	* @var int
59	*/
60	protected $donation_id;
61
62	/**
63	* User object.
64	*
65	* @since 1.0.0
66	*
67	* @var Charitable_User
68	*/
69	protected $user;
70
71	/**
72	* Donation object.
73	*
74	* @since 1.0.0
75	*
76	* @var Charitable_Donation\|null
77	*/
78	protected $donation = null;
79
80	/**
81	* The donation object for the most recently made donation.
82	*
83	* @since 1.5.7
84	*
85	* @var Charitable_Donor
86	*/
87	protected $last_donation;
88
89	/**
90	* Whether the donor is anonymous.
91	*
92	* @since 1.8.3.1
93	*
94	* @var boolean
95	*/
96	public $is_anonymous;
97
98	/**
99	* Donor meta.
100	*
101	* @since 1.4.0
102	*
103	* @var mixed[]
104	*/
105	protected $donor_meta;
106
107	/**
108	* A mapping of user keys.
109	*
110	* @since 1.4.0
111	*
112	* @var string[]
113	*/
114	protected $mapped_keys;
115
116	/**
117	* Create class object.
118	*
119	* @since 1.0.0
120	*
121	* @param int $donor_id Donor ID.
122	* @param int $donation_id Donation ID. Passed if this object is created through a donation.
123	*/
124	public function __construct( $donor_id, $donation_id = false ) {
125	$this->donor_id = $donor_id;
126	$this->data = charitable_get_table( 'donors' )->get( $donor_id );
127	$this->donation_id = $donation_id;
128	}
129
130	/**
131	* Magic getter method. Looks for the specified key in as a property before using Charitable_User's __get method.
132	*
133	* @since 1.0.0
134	*
135	* @param string $key Key to search for.
136	* @return mixed
137	*/
138	public function __get( $key ) {
139	if ( isset( $this->$key ) ) {
140	return $this->$key;
141	}
142
143	if ( isset( $this->data->$key ) ) {
144	return $this->data->$key;
145	}
146
147	if ( method_exists( $this, 'get_' . $key ) ) {
148	return call_user_func( array( $this, 'get_' . $key ) );
149	}
150
151	return $this->get_user()->$key;
152	}
153
154	/**
155	* Display the donor name when echoing object.
156	*
157	* @since 1.4.0
158	*
159	* @return string
160	*/
161	public function __toString() {
162	return $this->get_name();
163	}
164
165	/**
166	* A thin wrapper around the Charitable_User::get() method.
167	*
168	* @since 1.2.4
169	*
170	* @param string $key The user property key.
171	* @return mixed
172	*/
173	public function get( $key ) {
174	return $this->get_user()->get( $key );
175	}
176
177	/**
178	* Return the Charitable_User object for this donor.
179	*
180	* @since 1.0.0
181	*
182	* @return Charitable_User
183	*/
184	public function get_user() {
185	if ( ! isset( $this->user ) ) {
186	$this->user = Charitable_User::init_with_donor( $this->donor_id );
187	}
188
189	return $this->user;
190	}
191
192	/**
193	* Return the Charitable_Donation object associated with this object.
194	*
195	* @since 1.0.0
196	*
197	* @return Charitable_Donation\|false
198	*/
199	public function get_donation() {
200	if ( ! isset( $this->donation ) ) {
201	$this->donation = $this->donation_id ? charitable_get_donation( $this->donation_id ) : false;
202	}
203
204	return $this->donation;
205	}
206
207	/**
208	* Return the Charitable_Donation object associated with this object.
209	*
210	* @since 1.3.5
211	*
212	* @return object[]
213	*/
214	public function get_donations() {
215	return $this->get_user()->get_donations();
216	}
217
218	/**
219	* Return whether contact consent has been given.
220	*
221	* @since 1.6.54
222	*
223	* @return boolean\|null If contact consent has been explicitly given or
224	* not given, returns a boolean. If the donor has
225	* never been presented with the opt-in checkbox,
226	* this will return null.
227	*/
228	public function get_contact_consent() {
229	return $this->data->contact_consent;
230	}
231
232	/**
233	* Attach a user ID to the donor record.
234	*
235	* @since 1.5.0
236	*
237	* @param int $user_id The user ID for the donor record.
238	* @return boolean
239	*/
240	public function set_user_id( $user_id ) {
241	return charitable_get_table( 'donors' )->update( $this->donor_id, array( 'user_id' => $user_id ), 'donor_id' );
242	}
243
244	/**
245	* Return the donor meta stored for the particular donation.
246	*
247	* @since 1.0.0
248	*
249	* @param string $key Optional key passed to return a particular meta field.
250	* @return array\|mixed\|false
251	*/
252	public function get_donor_meta( $key = '' ) {
253	if ( ! $this->get_donation() ) {
254	return $this->get_donor_meta_from_profile( $key );
255	}
256
257	if ( ! isset( $this->donor_meta ) ) {
258	$this->donor_meta = get_post_meta( $this->donation_id, 'donor', true );
259	}
260
261	return $this->get_donor_meta_from_set_meta( $key );
262	}
263
264	/**
265	* Return a donor's meta details from their profile, or their most recent donation.
266	*
267	* @since 1.5.7
268	*
269	* @param string $key Optional key passed to return a particular meta field.
270	* @return array\|mixed\|false
271	*/
272	protected function get_donor_meta_from_profile( $key ) {
273	if ( isset( $this->data->$key ) ) {
274	return $this->data->$key;
275	}
276
277	/* If the donor has a profile, return the values from that. */
278	if ( $this->get_user()->ID ) {
279	return $this->get_user()->get( $key );
280	}
281
282	/**
283	* If we still don't have any data about them, return the
284	* data from the last donation.
285	*/
286	$last_donation = $this->get_last_donation();
287
288	if ( is_null( $last_donation ) ) {
289	return false;
290	}
291
292	if ( ! isset( $this->donor_meta ) ) {
293	$this->donor_meta = $last_donation->get_donor_data();
294	}
295
296	return $this->get_donor_meta_from_set_meta( $key );
297	}
298
299	/**
300	* Return a specific key or the entire array of data from a set of donor data.
301	*
302	* @since 1.5.7
303	*
304	* @param string $key Optional key passed to return a particular meta field.
305	* @return array\|mixed
306	*/
307	protected function get_donor_meta_from_set_meta( $key ) {
308	if ( empty( $key ) ) {
309	return $this->donor_meta;
310	}
311
312	if ( isset( $this->donor_meta[ $key ] ) ) {
313	return $this->donor_meta[ $key ];
314	}
315
316	$mapped_keys = $this->get_mapped_keys();
317
318	if ( ! in_array( $key, $mapped_keys ) ) {
319	return '';
320	}
321
322	$key = array_search( $key, $mapped_keys );
323
324	if ( isset( $this->donor_meta[ $key ] ) ) {
325	return $this->donor_meta[ $key ];
326	}
327	}
328
329	/**
330	* Return the most recently made donation.
331	*
332	* @since 1.5.7
333	*
334	* @return Charitable_Donation\|null Null if no donation was found. A `Charitable_Donation` instance otherwise.
335	*/
336	public function get_last_donation() {
337	if ( ! isset( $this->last_donation ) ) {
338	$donation = new Charitable_Donations_Query(
339	array(
340	'number' => 1,
341	'donor_id' => $this->donor_id,
342	)
343	);
344
345	$this->last_donation = $donation->count() ? $donation->current() : null;
346	}
347
348	return $this->last_donation;
349	}
350
351	/**
352	* Return the donor's name stored for the particular donation.
353	*
354	* @since 1.0.0
355	*
356	* @return string
357	*/
358	public function get_name() {
359	$name = esc_html(
360	trim(
361	sprintf( '%s %s', $this->get_donor_meta( 'first_name' ), $this->get_donor_meta( 'last_name' ) )
362	)
363	);
364
365	/**
366	* Filter the donor name.
367	*
368	* @since 1.0.0
369	*
370	* @param string $name The donor's name.
371	* @param Charitable_Donor $donor This instance of `Charitable_Donor`.
372	*/
373	return apply_filters( 'charitable_donor_name', $name, $this );
374	}
375
376	/**
377	* Return the donor's email address.
378	*
379	* @since 1.2.4
380	*
381	* @return string
382	*/
383	public function get_email() {
384	return $this->get_donor_meta( 'email' );
385	}
386
387	/**
388	* Checks whether the donor has a valid email address.
389	*
390	* @since 1.6.0
391	*
392	* @return boolean
393	*/
394	public function has_valid_email() {
395	return charitable_is_valid_email_address( $this->get_donor_meta( 'email' ) );
396	}
397
398	/**
399	* Return the donor's address.
400	*
401	* @since 1.2.4
402	*
403	* @return string
404	*/
405	public function get_address() {
406	return $this->get_user()->get_address( $this->donation_id );
407	}
408
409	/**
410	* Return the donor avatar.
411	*
412	* @since 1.0.0
413	*
414	* @param int $size The side length to use for the avatar. The avatar is returned
415	* as a square image, so this is used for both height and width.
416	* @return string
417	*/
418	public function get_avatar( $size = 100 ) {
419
420	/**
421	* Filter the donor avatar.
422	*
423	* @since 1.2.0
424	*
425	* @param string $avatar The avatar HTML code.
426	* @param Charitable_Donor $donor This instance of `Charitable_Donor`.
427	*/
428	return apply_filters( 'charitable_donor_avatar', $this->get_user()->get_avatar( $size ), $this );
429	}
430
431	/**
432	* Return the donor location.
433	*
434	* @since 1.0.0
435	*
436	* @return string
437	*/
438	public function get_location() {
439	if ( ! $this->get_donor_meta() ) {
440	return $this->get_user()->get_location();
441	}
442
443	$meta = $this->get_donor_meta();
444	$city = isset( $meta['city'] ) ? $meta['city'] : '';
445	$state = isset( $meta['state'] ) ? $meta['state'] : '';
446	$country = isset( $meta['country'] ) ? $meta['country'] : '';
447	$region = strlen( $city ) ? $city : $state;
448
449	if ( strlen( $country ) ) {
450	if ( strlen( $region ) ) {
451	$location = sprintf( '%s, %s', $region, $country );
452	} else {
453	$location = $country;
454	}
455	} else {
456	$location = $region;
457	}
458
459	return apply_filters( 'charitable_donor_location', $location, $this );
460	}
461
462	/**
463	* Return the donation amount.
464	*
465	* If a donation ID was passed to the object constructor, this will return
466	* the total donated with this particular donation. Otherwise, this will
467	* return the total amount ever donated by the donor.
468	*
469	* @since 1.0.0
470	*
471	* @param int $campaign_id Optional. If set, returns total donated to this particular campaign.
472	* @return decimal
473	*/
474	public function get_amount( $campaign_id = false ) {
475	if ( $this->get_donation() ) {
476	return $this->get_donation_amount( $campaign_id );
477	}
478
479	return $this->get_user()->get_total_donated( $campaign_id );
480	}
481
482	/**
483	* Return the amount of the donation.
484	*
485	* @since 1.2.0
486	*
487	* @param int $campaign_id Optional. If set, returns the amount donated to the campaign.
488	* @return decimal
489	*/
490	public function get_donation_amount( $campaign_id = '' ) {
491	return apply_filters( 'charitable_donor_donation_amount', charitable_get_table( 'campaign_donations' )->get_donation_amount( $this->donation_id, $campaign_id ), $this, $campaign_id );
492	}
493
494	/**
495	* Return the array of mapped keys, where the key is mapped to a meta_key in the user meta table.
496	*
497	* @since 1.0.0
498	*
499	* @return array
500	*/
501	public function get_mapped_keys() {
502	if ( ! isset( $this->mapped_keys ) ) {
503	$this->mapped_keys = charitable_get_user_mapped_keys();
504	}
505
506	return $this->mapped_keys;
507	}
508
509	/**
510	* Return a value from the donor meta.
511	*
512	* @deprecated 1.7.0
513	*
514	* @since 1.2.4
515	* @since 1.4.0 Deprecated
516	*
517	* @param string $key The particular field to get the value for.
518	* @return mixed
519	*/
520	public function get_value( $key ) {
521	charitable_get_deprecated()->deprecated_function(
522	__METHOD__,
523	'1.4.0',
524	'Charitable_Donor::get_donor_meta()'
525	);
526	return $this->get_donor_meta( $key );
527	}
528	}
529
530	endif;
531