give / src / API / REST / V3 / Routes / Donors / DonorStatisticsController.php

DonorStatisticsController.php in GiveWP – Donation Plugin and Fundraising Platform 4.18.0, at src/API/REST/V3/Routes/Donors/DonorStatisticsController.php

220 lines 7.3 KB

Raw Download Zip

1	<?php
2
3	namespace Give\API\REST\V3\Routes\Donors;
4
5	use Exception;
6	use Give\API\REST\V3\Routes\Donors\ValueObjects\DonorRoute;
7	use Give\API\REST\V3\Support\CURIE;
8	use Give\Campaigns\Models\Campaign;
9	use Give\Donors\DonorStatisticsQuery;
10	use Give\Donors\Models\Donor;
11	use Give\Framework\Permissions\Facades\UserPermissions;
12	use WP_Error;
13	use WP_REST_Controller;
14	use WP_REST_Request;
15	use WP_REST_Response;
16	use WP_REST_Server;
17
18	/**
19	* @since 4.4.0
20	*/
21	class DonorStatisticsController extends WP_REST_Controller
22	{
23	/**
24	* @since 4.4.0
25	*/
26	public function __construct()
27	{
28	$this->namespace = DonorRoute::NAMESPACE;
29	$this->rest_base = DonorRoute::BASE;
30	}
31
32	/**
33	* @since 4.13.0 add schema
34	* @since 4.4.0
35	*/
36	public function register_routes()
37	{
38	register_rest_route($this->namespace, '/' . $this->rest_base . '/(?P<donorId>[\d]+)/statistics', [
39	[
40	'methods' => WP_REST_Server::READABLE,
41	'callback' => [$this, 'get_item'],
42	'permission_callback' => [$this, 'get_item_permissions_check'],
43	'args' => [
44	'donorId' => [
45	'description' => __('The donor ID.', 'give'),
46	'type' => 'integer',
47	'required' => true,
48	],
49	'mode' => [
50	'description' => __('The mode of donations to filter by "live" or "test".', 'give'),
51	'type' => 'string',
52	'default' => 'live',
53	'enum' => ['live', 'test'],
54	],
55	'campaignId' => [
56	'description' => __('The ID of the campaign to filter donors by - zero or empty mean "all campaigns".', 'give'),
57	'type' => 'integer',
58	'default' => 0,
59	],
60	],
61	],
62	'schema' => [$this, 'get_item_schema'],
63	]);
64	}
65
66	/**
67	* Get a single donor statistics.
68	*
69	* @since 4.4.0
70	*
71	* @param WP_REST_Request $request Full data about the request.
72	*
73	* @return WP_REST_Response\|WP_Error Response object on success, or WP_Error object on failure.
74	*
75	* @throws Exception
76	*/
77	public function get_item($request)
78	{
79	$donor = Donor::find($request->get_param('donorId'));
80	if (!$donor) {
81	return new WP_Error('donor_not_found', __('Donor not found', 'give'), ['status' => 404]);
82	}
83
84	$query = new DonorStatisticsQuery($donor, $request->get_param('mode'));
85
86	if ($campaign = Campaign::find($request->get_param('campaignId'))) {
87	$query = $query->filterByCampaign($campaign);
88	}
89
90	$item = [
91	'donations' => [
92	'lifetimeAmount' => $query->getLifetimeDonationsAmount(),
93	'highestAmount' => $query->getHighestDonationAmount(),
94	'averageAmount' => $query->getAverageDonationAmount(),
95	'count' => $query->getDonationsCount(),
96	'first' => $query->getFirstDonation(),
97	'last' => $query->getLastDonation()
98	],
99	'donorType' => $query->getDonorType(),
100	'preferredPaymentMethod' => $query->preferredPaymentMethod(),
101	];
102
103	$response = $this->prepare_item_for_response($item, $request);
104
105	return rest_ensure_response($response);
106	}
107
108	/**
109	* @since 4.14.0 replace logic with UserPermissions facade
110	* @since 4.4.0
111	*
112	* @param WP_REST_Request $request
113	*
114	* @return bool
115	*/
116	public function get_item_permissions_check($request): bool
117	{
118	return UserPermissions::donors()->canView();
119	}
120
121	/**
122	* @since 4.14.0 Add donor link to the response
123	* @since 4.4.0
124	*/
125	public function prepare_item_for_response($item, $request): WP_REST_Response
126	{
127	$self_url = rest_url(sprintf(
128	'%s/%s/%d/%s',
129	$this->namespace,
130	$this->rest_base,
131	$request->get_param('donorId'),
132	'statistics'
133	));
134
135	$self_url = add_query_arg([
136	'mode' => $request->get_param('mode'),
137	'campaignId' => $request->get_param('campaignId'),
138	], $self_url);
139
140	$donor_url = rest_url(sprintf(
141	'%s/%s/%d',
142	$this->namespace,
143	$this->rest_base,
144	$request->get_param('donorId')
145	));
146
147	$donor_url = add_query_arg([
148	'mode' => $request->get_param('mode'),
149	'campaignId' => $request->get_param('campaignId'),
150	], $donor_url);
151
152	$links = [
153	'self' => ['href' => $self_url],
154	CURIE::relationUrl('donor') => [
155	'href' => $donor_url,
156	'embeddable' => true,
157	],
158	];
159
160	$response = new WP_REST_Response($item);
161	$response->add_links($links);
162
163	return $response;
164	}
165
166	/**
167	* @since 4.14.0 Moved from getSchema to get_item_schema and added response schema
168	* @since 4.13.0
169	*/
170	public function get_item_schema(): array
171	{
172	return [
173	'$schema' => 'http://json-schema.org/draft-04/schema#',
174	'title' => 'givewp/donor-statistics',
175	'description' => esc_html__('Provides statistics for a specific donor.', 'give'),
176	'type' => 'object',
177	'properties' => [
178	'donations' => [
179	'type' => 'object',
180	'description' => esc_html__('Donation statistics', 'give'),
181	'properties' => [
182	'lifetimeAmount' => [
183	'type' => ['integer', 'number'],
184	'description' => esc_html__('Total lifetime donation amount', 'give'),
185	],
186	'highestAmount' => [
187	'type' => ['integer', 'number'],
188	'description' => esc_html__('Highest single donation amount', 'give'),
189	],
190	'averageAmount' => [
191	'type' => ['integer', 'number'],
192	'description' => esc_html__('Average donation amount', 'give'),
193	],
194	'count' => [
195	'type' => 'integer',
196	'description' => esc_html__('Total number of donations', 'give'),
197	],
198	'first' => [
199	'type' => ['object', 'null'],
200	'description' => esc_html__('First donation details', 'give'),
201	],
202	'last' => [
203	'type' => ['object', 'null'],
204	'description' => esc_html__('Last donation details', 'give'),
205	],
206	],
207	],
208	'donorType' => [
209	'type' => 'string',
210	'description' => esc_html__('Type of donor', 'give'),
211	],
212	'preferredPaymentMethod' => [
213	'type' => ['string', 'null'],
214	'description' => esc_html__('Preferred payment method', 'give'),
215	],
216	],
217	];
218	}
219	}
220