give / src / Donations / Models / Donation.php

Donation.php in GiveWP – Donation Plugin and Fundraising Platform 4.16.8.1, at src/Donations/Models/Donation.php

358 lines 9.0 KB

Raw Download Zip

1	<?php
2
3	namespace Give\Donations\Models;
4
5	use DateTime;
6	use Give\BetaFeatures\Facades\FeatureFlag;
7	use Give\Campaigns\Models\Campaign;
8	use Give\Donations\DataTransferObjects\DonationQueryData;
9	use Give\Donations\Factories\DonationFactory;
10	use Give\Donations\Properties\BillingAddress;
11	use Give\Donations\ValueObjects\DonationMode;
12	use Give\Donations\ValueObjects\DonationStatus;
13	use Give\Donations\ValueObjects\DonationType;
14	use Give\Donors\Models\Donor;
15	use Give\EventTickets\Models\EventTicket;
16	use Give\EventTickets\Repositories\EventTicketRepository;
17	use Give\Framework\Exceptions\Primitives\Exception;
18	use Give\Framework\Exceptions\Primitives\InvalidArgumentException;
19	use Give\Framework\Models\Contracts\ModelCrud;
20	use Give\Framework\Models\Contracts\ModelHasFactory;
21	use Give\Framework\Models\Model;
22	use Give\Framework\Models\ModelQueryBuilder;
23	use Give\Framework\Models\ValueObjects\Relationship;
24	use Give\Framework\PaymentGateways\PaymentGateway;
25	use Give\Framework\Receipts\DonationReceipt;
26	use Give\Framework\Support\ValueObjects\Money;
27	use Give\Subscriptions\Models\Subscription;
28
29	/**
30	* Class Donation
31	*
32	* @since 4.6.0 Add event tickets property
33	* @since 3.9.0 Add phone property
34	* @since 2.23.0 add type property; remove parentId property
35	* @since 2.20.0 update amount type, fee recovered, and exchange rate
36	* @since 2.19.6
37	*
38	* @property int $id
39	* @property int $campaignId
40	* @property int $formId
41	* @property string $formTitle
42	* @property DateTime $createdAt
43	* @property DateTime $updatedAt
44	* @property DonationStatus $status
45	* @property DonationMode $mode
46	* @property DonationType $type
47	* @property Money $amount amount charged to the gateway
48	* @property Money $feeAmountRecovered
49	* @property string $exchangeRate
50	* @property string $gatewayId
51	* @property int $donorId
52	* @property string $honorific
53	* @property string $firstName
54	* @property string $lastName
55	* @property string $email
56	* @property string $phone
57	* @property int $subscriptionId
58	* @property BillingAddress $billingAddress
59	* @property string $purchaseKey
60	* @property string $donorIp
61	* @property bool $anonymous
62	* @property string $levelId
63	* @property string $gatewayTransactionId
64	* @property Donor $donor
65	* @property Campaign $campaign
66	* @property Subscription $subscription
67	* @property DonationNote[] $notes
68	* @property EventTicket[] $eventTickets
69	* @property string $company
70	* @property string $comment
71	*/
72	class Donation extends Model implements ModelCrud, ModelHasFactory
73	{
74	/**
75	* @inheritdoc
76	*/
77	protected $properties = [
78	'id' => 'int',
79	'campaignId' => 'int',
80	'formId' => 'int',
81	'formTitle' => 'string',
82	'purchaseKey' => 'string',
83	'donorIp' => 'string',
84	'createdAt' => DateTime::class,
85	'updatedAt' => DateTime::class,
86	'status' => DonationStatus::class,
87	'type' => DonationType::class,
88	'mode' => DonationMode::class,
89	'amount' => Money::class,
90	'feeAmountRecovered' => Money::class,
91	'exchangeRate' => ['string', '1'],
92	'gatewayId' => 'string',
93	'donorId' => 'int',
94	'honorific' => 'string',
95	'firstName' => 'string',
96	'lastName' => 'string',
97	'email' => 'string',
98	'phone' => 'string',
99	'subscriptionId' => ['int', 0],
100	'billingAddress' => BillingAddress::class,
101	'anonymous' => ['bool', false],
102	'levelId' => ['string', ''],
103	'gatewayTransactionId' => 'string',
104	'company' => 'string',
105	'comment' => 'string',
106	];
107
108	/**
109	* @inheritdoc
110	*/
111	protected $relationships = [
112	'campaign' => Relationship::BELONGS_TO,
113	'donor' => Relationship::BELONGS_TO,
114	'subscription' => Relationship::BELONGS_TO,
115	'notes' => Relationship::HAS_MANY,
116	'eventTickets' => Relationship::HAS_MANY,
117	];
118
119	/**
120	* Find donation by ID
121	*
122	* @since 2.19.6
123	*
124	* @param int $id
125	*
126	* @return Donation\|null
127	*/
128	public static function find($id)
129	{
130	return give()->donations->getById($id);
131	}
132
133	/**
134	* @since 2.20.0 return mutated model instance
135	* @since 2.19.6
136	*
137	* @throws Exception\|InvalidArgumentException
138	*/
139	public static function create(array $attributes): Donation
140	{
141	$donation = new static($attributes);
142
143	give()->donations->insert($donation);
144
145	return $donation;
146	}
147
148	/**
149	* @since 2.20.0 mutate model in repository and return void
150	* @since 2.19.6
151	*
152	* @return void
153	*
154	* @throws Exception\|InvalidArgumentException
155	*/
156	public function save()
157	{
158	if (!$this->id) {
159	give()->donations->insert($this);
160	} else {
161	give()->donations->update($this);
162	}
163	}
164
165	/**
166	* @since 2.19.6
167	*
168	* @throws Exception\|InvalidArgumentException
169	*/
170	public function delete(): bool
171	{
172	return give()->donations->delete($this);
173	}
174
175	/**
176	* @since 4.6.0
177	*
178	* @throws Exception\|InvalidArgumentException
179	*/
180	public function trash(): bool
181	{
182	return give()->donations->trash($this);
183	}
184
185	/**
186	* @since 4.12.0
187	*
188	* @throws Exception\|InvalidArgumentException
189	*/
190	public function unTrash(): bool
191	{
192	return give()->donations->unTrash($this);
193	}
194
195	/**
196	* @since 2.19.6
197	*
198	* @return ModelQueryBuilder<Donor>
199	*/
200	public function donor(): ModelQueryBuilder
201	{
202	return give()->donors->queryById($this->donorId);
203	}
204
205	/**
206	* @since 2.19.6
207	*
208	* @return ModelQueryBuilder<Subscription>
209	*/
210	public function subscription(): ModelQueryBuilder
211	{
212	if ($this->subscriptionId) {
213	return give()->subscriptions->queryById($this->subscriptionId);
214	}
215
216	return give()->subscriptions->queryByDonationId($this->id);
217	}
218
219	/**
220	* @since 4.0.0
221	*
222	* @return ModelQueryBuilder<Campaign>
223	*/
224	public function campaign(): ModelQueryBuilder
225	{
226	return give()->campaigns->queryById($this->campaignId);
227	}
228
229	/**
230	* @since 2.19.6
231	*
232	* @return int\|null
233	*/
234	public function getSequentialId()
235	{
236	return give()->donations->getSequentialId($this->id);
237	}
238
239	/**
240	* @since 2.19.6
241	*
242	* @return ModelQueryBuilder<DonationNote>
243	*/
244	public function notes(): ModelQueryBuilder
245	{
246	return give()->donations->notes->queryByDonationId($this->id);
247	}
248
249	/**
250	* Returns the amount charged in the currency the GiveWP site is set to
251	*
252	* @since 2.20.0
253	*/
254	public function amountInBaseCurrency(): Money
255	{
256	return $this->amount->inBaseCurrency($this->exchangeRate);
257	}
258
259	/**
260	* Returns the donation amount the donor "intended", which means it is the amount without recovered fees. So if the
261	* donor paid $100, but the donation was charged $105 with a $5 fee, this method will return $100.
262	*
263	* @since 2.20.0
264	*/
265	public function intendedAmount(): Money
266	{
267	return $this->feeAmountRecovered === null
268	? $this->amount
269	: $this->amount->subtract($this->feeAmountRecovered);
270	}
271
272	/**
273	* @since 4.6.0
274	*/
275	public function eventTicketsAmount(): Money
276	{
277	return give(EventTicketRepository::class)->getTotalByDonation($this);
278	}
279
280	/**
281	* @since 4.6.0
282	*/
283	public function eventTickets(): ModelQueryBuilder
284	{
285	return give(EventTicketRepository::class)->queryByDonationId($this->id);
286	}
287
288	/**
289	* Returns the amount intended in the currency the GiveWP site is set to
290	*
291	* @since 2.20.0
292	*/
293	public function intendedAmountInBaseCurrency(): Money
294	{
295	return $this->intendedAmount()->inBaseCurrency($this->exchangeRate);
296	}
297
298	/**
299	* Returns the gateway instance for this donation
300	*
301	* @since 2.20.0
302	*/
303	public function gateway(): PaymentGateway
304	{
305	return give()->gateways->getPaymentGateway($this->gatewayId);
306	}
307
308	/**
309	* @since 4.3.0
310	*/
311	public function receipt(): DonationReceipt
312	{
313	return give()->donations->getConfirmationPageReceipt($this);
314	}
315
316	/**
317	* @since 2.20.0
318	*
319	* @inheritDoc
320	*/
321	protected function getPropertyDefaults(): array
322	{
323	return array_merge(parent::getPropertyDefaults(), [
324	'mode' => give_is_test_mode() ? DonationMode::TEST() : DonationMode::LIVE(),
325	'donorIp' => give_get_ip(),
326	'billingAddress' => new BillingAddress(),
327	]);
328	}
329
330	/**
331	* @since 2.19.6
332	*
333	* @return ModelQueryBuilder<Donation>
334	*/
335	public static function query(): ModelQueryBuilder
336	{
337	return give()->donations->prepareQuery();
338	}
339
340	/**
341	* @since 2.19.6
342	*
343	* @param object $object
344	*/
345	public static function fromQueryBuilderObject($object): Donation
346	{
347	return DonationQueryData::fromObject($object)->toDonation();
348	}
349
350	/**
351	* @since 2.19.6
352	*/
353	public static function factory(): DonationFactory
354	{
355	return new DonationFactory(static::class);
356	}
357	}
358