charitable / includes / admin / reports / class-charitable-export-donations.php

class-charitable-export-donations.php in Charitable – Donation & Fundraising Platform (Donation Forms, Recurring Donations & Fundraising Campaigns) 1.8.13, at includes/admin/reports/class-charitable-export-donations.php

298 lines 8.8 KB

Raw Download Zip

1	<?php
2	/**
3	* Class that is responsible for generating a CSV export of donations.
4	*
5	* @package Charitable/Classes/Charitable_Export_Donations
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.45
11	*/
12
13	/* Exit if accessed directly */
14	if ( ! defined( 'ABSPATH' ) ) {
15	exit;
16	}
17
18	if ( ! class_exists( 'Charitable_Export_Donations' ) ) :
19
20	/**
21	* Charitable_Export_Donations
22	*
23	* @since 1.0.0
24	*/
25	class Charitable_Export_Donations extends Charitable_Export {
26
27	/* The type of export. */
28	const EXPORT_TYPE = 'donations';
29
30	/**
31	* Default arguments.
32	*
33	* @since 1.0.0
34	*
35	* @var mixed[]
36	*/
37	protected $defaults;
38
39	/**
40	* List of donation statuses.
41	*
42	* @since 1.0.0
43	*
44	* @var string[]
45	*/
46	protected $statuses;
47
48	/**
49	* Exportable donation fields.
50	*
51	* @since 1.5.0
52	*
53	* @var array
54	*/
55	protected $fields;
56
57	/**
58	* Set Charitable_Donation objects.
59	*
60	* @since 1.5.0
61	*
62	* @var Charitable_Donation[]
63	*/
64	protected $donations = array();
65
66	/**
67	* Format money fields.
68	*
69	* @since 1.8.1.4
70	*
71	* @var mixed[]
72	*/
73	protected $format_money_fields = array();
74
75	/**
76	* Create class object.
77	*
78	* @since 1.0.0
79	* @since 1.8.1.4 Added formatting money fields.
80	*
81	* @param mixed[] $args Arguments for the report.
82	*/
83	public function __construct( $args ) {
84	$this->defaults = array(
85	'start_date' => '',
86	'end_date' => '',
87	'campaign_id' => 'all',
88	'status' => 'all',
89	);
90
91	$this->statuses = charitable_get_valid_donation_statuses();
92	$this->fields = array_map( array( $this, 'get_field_label' ), charitable()->donation_fields()->get_export_fields() );
93
94	add_filter( 'charitable_export_data_key_value', array( $this, 'suppliment_charitable_export_data' ), 10, 3 );
95
96	$this->format_money_fields = apply_filters(
97	'charitable_export_donations_format_money_fields',
98	array(
99	'amount',
100	'subtotal',
101	'total',
102	'total_donation_with_fees',
103	)
104	);
105
106	parent::__construct( $args );
107	}
108
109	/**
110	* Suppliments the data exported for campaigns with custom field data.
111	*
112	* @param mixed[]\|false $custom_field_data Optional. Custom field data to add to the exported data. Default false.
113	* @param string\|false $key Optional. The key to use for the custom field data. Default false.
114	* @param mixed[] $data Optional. The exported data. Default empty array.
115	*
116	* @return mixed[] The exported data with custom field data added.
117	*/
118	public function suppliment_charitable_export_data( $custom_field_data = false, $key = false, $data = array() ) {
119
120	if ( in_array( $key, $this->format_money_fields, true ) ) {
121	/*
122	* Core 'subtotal' and 'total' have no value_callback, so they arrive here as
123	* raw database amounts (period as the decimal separator, e.g. "101.78"). Other
124	* money fields ('amount', and addon-provided totals such as Fee Relief's
125	* 'total_donation_with_fees') arrive already localized. On comma-decimal locales,
126	* running a raw DB amount through charitable_format_money() without the db_format
127	* flag makes the "." read as a thousands separator and get stripped
128	* (101.78 -> "10 178,00"). So pass db_format = true only for the raw DB amounts.
129	*/
130	$db_format_fields = apply_filters(
131	'charitable_export_donations_db_format_money_fields',
132	array( 'subtotal', 'total' )
133	);
134	$db_format = in_array( $key, $db_format_fields, true );
135
136	return html_entity_decode( trim( charitable_format_money( $custom_field_data, false, $db_format ) ) );
137	}
138
139	return $custom_field_data;
140	}
141
142
143	/**
144	* Filter the date and time fields.
145	*
146	* @since 1.0.0
147	*
148	* @param mixed $value The value to set.
149	* @param string $key The key to set.
150	* @param array $data The set of data.
151	* @return mixed
152	*/
153	public function set_custom_field_data( $value, $key, $data ) {
154	if ( array_key_exists( $key, $this->fields ) ) {
155	$donation = $this->get_donation( $data['donation_id'] );
156	$value = charitable_get_sanitized_donation_field_value( $donation->get( $key ), $key );
157	}
158
159	return $value;
160	}
161
162	/**
163	* Return the CSV column headers.
164	*
165	* The columns are set as a key=>label array, where the key is used to retrieve the data for that column.
166	*
167	* @since 1.0.0
168	*
169	* @return string[]
170	*/
171	protected function get_csv_columns() {
172	$non_field_columns = array(
173	'campaign_id' => '',
174	'campaign_name' => '',
175	'amount' => '',
176	);
177
178	$default_columns = array(
179	'donation_id' => __( 'Donation ID', 'charitable' ),
180	'campaign_id' => __( 'Campaign ID', 'charitable' ),
181	'campaign_name' => __( 'Campaign Title', 'charitable' ),
182	'first_name' => __( 'First Name', 'charitable' ),
183	'last_name' => __( 'Last Name', 'charitable' ),
184	'email' => __( 'Email', 'charitable' ),
185	'address' => __( 'Address', 'charitable' ),
186	'address_2' => __( 'Address 2', 'charitable' ),
187	'city' => __( 'City', 'charitable' ),
188	'state' => __( 'State', 'charitable' ),
189	'postcode' => __( 'Postcode', 'charitable' ),
190	'country' => __( 'Country', 'charitable' ),
191	'phone' => __( 'Phone Number', 'charitable' ),
192	'donor_address' => __( 'Address Formatted', 'charitable' ),
193	'amount' => __( 'Donation Amount', 'charitable' ),
194	'date' => __( 'Date of Donation', 'charitable' ),
195	'time' => __( 'Time of Donation', 'charitable' ),
196	'status_label' => __( 'Donation Status', 'charitable' ),
197	'gateway_label' => __( 'Donation Gateway', 'charitable' ),
198	'test_mode' => __( 'Made in Test Mode', 'charitable' ),
199	'contact_consent' => __( 'Contact Consent', 'charitable' ),
200	);
201
202	/**
203	* Filter the list of columns in the export.
204	*
205	* As of Charitable 1.5, the recommended way to add or remove columns to the
206	* donation export is through the Donation Fields API. This filter is primarily
207	* provided for backwards compatibility and also provides a way to change export
208	* column headers without changing the label for the Donation Field.
209	*
210	* @since 1.0.0
211	*
212	* @param array $columns List of columns.
213	* @param array $args Export args.
214	*/
215	$filtered = apply_filters( 'charitable_export_donations_columns', $default_columns, $this->args );
216
217	return $this->get_merged_fields( $default_columns, $this->fields, $non_field_columns, $filtered );
218	}
219
220	/**
221	* Return a Donation object for the given ID.
222	*
223	* @since 1.5.0
224	*
225	* @param int $donation_id The donation ID.
226	* @return Charitable_Donation
227	*/
228	protected function get_donation( $donation_id ) {
229	if ( ! array_key_exists( $donation_id, $this->donations ) ) {
230	$this->donations[ $donation_id ] = charitable_get_donation( $donation_id );
231	}
232
233	return $this->donations[ $donation_id ];
234	}
235
236	/**
237	* Get the data to be exported.
238	*
239	* @since 1.0.0
240	*
241	* @return array
242	*/
243	protected function get_data() {
244	$query_args = array();
245
246	if ( strlen( $this->args['start_date'] ) ) {
247	$query_args['start_date'] = charitable_sanitize_date_alt_format( $this->args['start_date'], 'Y-m-d 00:00:00' );
248	}
249
250	if ( strlen( $this->args['end_date'] ) ) {
251	$query_args['end_date'] = charitable_sanitize_date_alt_format( $this->args['end_date'], 'Y-m-d 23:59:59' );
252	}
253
254	if ( 'all' !== $this->args['campaign_id'] ) {
255	$query_args['campaign_id'] = $this->args['campaign_id'];
256	}
257
258	if ( 'all' !== $this->args['status'] ) {
259	$query_args['status'] = $this->args['status'];
260	}
261
262	/**
263	* Filter name with misspelling.
264	*
265	* @deprecated 1.7.0
266	*
267	* @since 1.3.5
268	*/
269	$query_args = apply_filters( 'chairtable_export_donations_query_args', $query_args, $this->args ); // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound -- 'chairtable_export_donations_query_args' is a legacy hook (note: typo in hook name) that cannot be renamed.
270
271	/**
272	* Filter donations query arguments.
273	*
274	* @since 1.3.5
275	*
276	* @param array $query_args The query arguments.
277	* @param array $args The export arguments.
278	*/
279	$query_args = apply_filters( 'charitable_export_donations_query_args', $query_args, $this->args );
280
281	return charitable_get_table( 'campaign_donations' )->get_donations_report( $query_args );
282	}
283
284	/**
285	* Return the field label for a registered Donation Field.
286	*
287	* @since 1.5.0
288	*
289	* @param Charitable_Donation_Field $field Instance of `Charitable_Donation_Field`.
290	* @return string
291	*/
292	protected function get_field_label( Charitable_Donation_Field $field ) {
293	return $field->label;
294	}
295	}
296
297	endif;
298