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

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

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