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.12, at includes/users/class-charitable-donor.php

524 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) 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	// echo 'donor idname:'; print_r( $this );
351	$name = esc_html(
352	trim(
353	sprintf( '%s %s', $this->get_donor_meta( 'first_name' ), $this->get_donor_meta( 'last_name' ) )
354	)
355	);
356
357	/**
358	* Filter the donor name.
359	*
360	* @since 1.0.0
361	*
362	* @param string $name The donor's name.
363	* @param Charitable_Donor $donor This instance of `Charitable_Donor`.
364	*/
365	return apply_filters( 'charitable_donor_name', $name, $this );
366	}
367
368	/**
369	* Return the donor's email address.
370	*
371	* @since 1.2.4
372	*
373	* @return string
374	*/
375	public function get_email() {
376	return $this->get_donor_meta( 'email' );
377	}
378
379	/**
380	* Checks whether the donor has a valid email address.
381	*
382	* @since 1.6.0
383	*
384	* @return boolean
385	*/
386	public function has_valid_email() {
387	return charitable_is_valid_email_address( $this->get_donor_meta( 'email' ) );
388	}
389
390	/**
391	* Return the donor's address.
392	*
393	* @since 1.2.4
394	*
395	* @return string
396	*/
397	public function get_address() {
398	return $this->get_user()->get_address( $this->donation_id );
399	}
400
401	/**
402	* Return the donor avatar.
403	*
404	* @since 1.0.0
405	*
406	* @param int $size The side length to use for the avatar. The avatar is returned
407	* as a square image, so this is used for both height and width.
408	* @return string
409	*/
410	public function get_avatar( $size = 100 ) {
411	// echo $this->get_user()->get_avatar( $size ) . '----';
412
413	/**
414	* Filter the donor avatar.
415	*
416	* @since 1.2.0
417	*
418	* @param string $avatar The avatar HTML code.
419	* @param Charitable_Donor $donor This instance of `Charitable_Donor`.
420	*/
421	return apply_filters( 'charitable_donor_avatar', $this->get_user()->get_avatar( $size ), $this );
422	}
423
424	/**
425	* Return the donor location.
426	*
427	* @since 1.0.0
428	*
429	* @return string
430	*/
431	public function get_location() {
432	if ( ! $this->get_donor_meta() ) {
433	return $this->get_user()->get_location();
434	}
435
436	$meta = $this->get_donor_meta();
437	$city = isset( $meta['city'] ) ? $meta['city'] : '';
438	$state = isset( $meta['state'] ) ? $meta['state'] : '';
439	$country = isset( $meta['country'] ) ? $meta['country'] : '';
440	$region = strlen( $city ) ? $city : $state;
441
442	if ( strlen( $country ) ) {
443	if ( strlen( $region ) ) {
444	$location = sprintf( '%s, %s', $region, $country );
445	} else {
446	$location = $country;
447	}
448	} else {
449	$location = $region;
450	}
451
452	return apply_filters( 'charitable_donor_location', $location, $this );
453	}
454
455	/**
456	* Return the donation amount.
457	*
458	* If a donation ID was passed to the object constructor, this will return
459	* the total donated with this particular donation. Otherwise, this will
460	* return the total amount ever donated by the donor.
461	*
462	* @since 1.0.0
463	*
464	* @param int $campaign_id Optional. If set, returns total donated to this particular campaign.
465	* @return decimal
466	*/
467	public function get_amount( $campaign_id = false ) {
468	if ( $this->get_donation() ) {
469	return $this->get_donation_amount( $campaign_id );
470	}
471
472	return $this->get_user()->get_total_donated( $campaign_id );
473	}
474
475	/**
476	* Return the amount of the donation.
477	*
478	* @since 1.2.0
479	*
480	* @param int $campaign_id Optional. If set, returns the amount donated to the campaign.
481	* @return decimal
482	*/
483	public function get_donation_amount( $campaign_id = '' ) {
484	return apply_filters( 'charitable_donor_donation_amount', charitable_get_table( 'campaign_donations' )->get_donation_amount( $this->donation_id, $campaign_id ), $this, $campaign_id );
485	}
486
487	/**
488	* Return the array of mapped keys, where the key is mapped to a meta_key in the user meta table.
489	*
490	* @since 1.0.0
491	*
492	* @return array
493	*/
494	public function get_mapped_keys() {
495	if ( ! isset( $this->mapped_keys ) ) {
496	$this->mapped_keys = charitable_get_user_mapped_keys();
497	}
498
499	return $this->mapped_keys;
500	}
501
502	/**
503	* Return a value from the donor meta.
504	*
505	* @deprecated 1.7.0
506	*
507	* @since 1.2.4
508	* @since 1.4.0 Deprecated
509	*
510	* @param string $key The particular field to get the value for.
511	* @return mixed
512	*/
513	public function get_value( $key ) {
514	charitable_get_deprecated()->deprecated_function(
515	__METHOD__,
516	'1.4.0',
517	'Charitable_Donor::get_donor_meta()'
518	);
519	return $this->get_donor_meta( $key );
520	}
521	}
522
523	endif;
524