suredonation / inc / import / charitable / status-map.php

status-map.php in SureDonation – Donation Forms, Fundraising Campaigns & Donor Management 1.6.0, at inc/import/charitable/status-map.php

225 lines 7.2 KB

Raw Download Zip

1	<?php
2	/**
3	* Charitable gateway and status translation tables.
4	*
5	* Centralises the mapping from Charitable gateway slugs / donation statuses to
6	* SureDonation equivalents, plus runtime detection of whether a gateway
7	* (and its Pro recurring handler) is currently loaded on this site.
8	*
9	* @package SureDonation
10	* @since 1.5.1
11	*/
12
13	namespace SureDonation\Inc\Import\Charitable;
14
15	// Exit if accessed directly.
16	defined( 'ABSPATH' ) \|\| exit;
17
18	/**
19	* Status_Map class.
20	*
21	* All methods are pure and stateless; safe to call statically anywhere.
22	*
23	* @since 1.5.1
24	*/
25	class Status_Map {
26	/**
27	* Map a Charitable gateway slug to the SureDonation gateway slug we store
28	* on the donation row.
29	*
30	* `offline`, `paypal` and `stripe` pass through unchanged. PayPal Commerce
31	* collapses to `paypal`; Square variants collapse to `square`. Unknown
32	* slugs are preserved as-is so historical records keep their provenance
33	* even when SureDonation cannot transact through that gateway (same
34	* treatment as the GiveWP importer).
35	*
36	* @param string $charitable_gateway Charitable gateway slug.
37	* @return string SureDonation gateway slug (may equal the input).
38	* @since 1.5.1
39	*/
40	public static function map_gateway( $charitable_gateway ) {
41	$charitable_gateway = is_string( $charitable_gateway ) ? $charitable_gateway : '';
42
43	$passthrough = [ 'offline', 'paypal', 'stripe' ];
44	if ( in_array( $charitable_gateway, $passthrough, true ) ) {
45	return $charitable_gateway;
46	}
47
48	$map = [
49	'paypal_commerce' => 'paypal',
50	'square_core' => 'square',
51	'square' => 'square',
52	];
53
54	return $map[ $charitable_gateway ] ?? $charitable_gateway;
55	}
56
57	/**
58	* Map a Charitable donation status (post_status on the donation CPT) to
59	* the SureDonation `payment_status` value stored on the donations row.
60	*
61	* Charitable registers charitable-* post statuses; `charitable-completed`
62	* is labelled "Paid" and is the only revenue-bearing status by default.
63	* `charitable-preapproved` (authorized, not captured) maps to pending.
64	*
65	* @param string $charitable_status Charitable donation post_status.
66	* @return string SureDonation payment_status value.
67	* @since 1.5.1
68	*/
69	public static function map_donation_status( $charitable_status ) {
70	$charitable_status = is_string( $charitable_status ) ? $charitable_status : '';
71
72	$map = [
73	'charitable-completed' => 'completed',
74	'charitable-pending' => 'pending',
75	'charitable-preapproved' => 'pending',
76	'charitable-refunded' => 'refunded',
77	'charitable-failed' => 'failed',
78	'charitable-cancelled' => 'cancelled',
79	];
80
81	return $map[ $charitable_status ] ?? 'pending';
82	}
83
84	/**
85	* Map a Charitable Recurring plan status (post_status on the
86	* recurring_donation CPT) to SureDonation's subscription_status value.
87	*
88	* @param string $charitable_status Charitable recurring donation post_status.
89	* @return string SureDonation subscription_status value.
90	* @since 1.5.1
91	*/
92	public static function map_subscription_status( $charitable_status ) {
93	$charitable_status = is_string( $charitable_status ) ? $charitable_status : '';
94
95	$map = [
96	'charitable-active' => 'active',
97	'charitable-cancelled' => 'cancelled',
98	'charitable-expired' => 'expired',
99	'charitable-completed' => 'completed',
100	'charitable-failed' => 'past_due',
101	'charitable-pending' => 'pending',
102	];
103
104	return $map[ $charitable_status ] ?? 'pending';
105	}
106
107	/**
108	* Map a Charitable CSV-export donation status LABEL to the SureDonation
109	* payment_status value.
110	*
111	* Charitable's donation export writes human labels ("Paid", "Pre Approved"),
112	* not status slugs; raw charitable-* slugs are also accepted and delegated
113	* to map_donation_status().
114	*
115	* @param string $label Status label (or slug) from a CSV cell.
116	* @return string SureDonation payment_status value.
117	* @since 1.5.1
118	*/
119	public static function map_status_label( $label ) {
120	$label = is_string( $label ) ? strtolower( trim( $label ) ) : '';
121
122	if ( 0 === strpos( $label, 'charitable-' ) ) {
123	return self::map_donation_status( $label );
124	}
125
126	$map = [
127	'paid' => 'completed',
128	'pending' => 'pending',
129	'pre approved' => 'pending',
130	'refunded' => 'refunded',
131	'failed' => 'failed',
132	'canceled' => 'cancelled',
133	'cancelled' => 'cancelled',
134	];
135
136	return $map[ $label ] ?? 'pending';
137	}
138
139	/**
140	* Map a Charitable CSV-export gateway LABEL to the SureDonation gateway slug.
141	*
142	* @param string $label Gateway label (or slug) from a CSV cell.
143	* @return string SureDonation gateway slug.
144	* @since 1.5.1
145	*/
146	public static function map_gateway_label( $label ) {
147	$label = is_string( $label ) ? strtolower( trim( $label ) ) : '';
148
149	$map = [
150	'offline' => 'offline',
151	'offline payment' => 'offline',
152	'paypal' => 'paypal',
153	'paypal commerce' => 'paypal',
154	'stripe' => 'stripe',
155	'square' => 'square',
156	];
157
158	if ( isset( $map[ $label ] ) ) {
159	return $map[ $label ];
160	}
161
162	return self::map_gateway( sanitize_title( $label ) );
163	}
164
165	/**
166	* Check whether a SureDonation gateway is currently loaded on this site.
167	*
168	* Used by the migration tool to display per-gateway "live vs historical"
169	* badges in the data-found panel: records for gateways whose helper class
170	* is loaded will be fully functional after import; others import as
171	* historical-only ledger rows. (Square has no SureDonation gateway, so
172	* square records always import as historical.)
173	*
174	* @param string $sd_gateway SureDonation gateway slug.
175	* @return bool True if the gateway's helper class is loaded (or offline, which is always available).
176	* @since 1.5.1
177	*/
178	public static function is_gateway_live( $sd_gateway ) {
179	if ( 'offline' === $sd_gateway ) {
180	return true;
181	}
182
183	$detectors = [
184	'stripe' => 'SureDonation\\Inc\\Payments\\Stripe\\Stripe_Helper',
185	'paypal' => 'SureDonation\\Inc\\Payments\\PayPal\\PayPal_Helper',
186	'mollie' => 'SureDonation\\Inc\\Payments\\Mollie\\Mollie_Helper',
187	'razorpay' => 'SureDonation\\Inc\\Payments\\Razorpay\\Razorpay_Helper',
188	];
189
190	if ( ! isset( $detectors[ $sd_gateway ] ) ) {
191	return false;
192	}
193
194	return class_exists( $detectors[ $sd_gateway ] );
195	}
196
197	/**
198	* Check whether a SureDonation gateway's Pro recurring handler is loaded.
199	*
200	* Imported subscriptions for gateways whose handler is NOT loaded carry
201	* `gateway_live = false` in their donation_data so the donor dashboard can
202	* hide cancel/suspend/activate actions. This mitigates the
203	* default-to-Stripe fallback in
204	* suredonation-pro/inc/recurring/subscription-api.php:362.
205	*
206	* @param string $sd_gateway SureDonation gateway slug.
207	* @return bool True if the gateway's subscription handler class is loaded.
208	* @since 1.5.1
209	*/
210	public static function is_subscription_handler_live( $sd_gateway ) {
211	$detectors = [
212	'stripe' => 'SureDonationPro\\Inc\\Recurring\\Subscription_Handler',
213	'paypal' => 'SureDonationPro\\Inc\\Payments\\PayPal\\PayPal_Subscription_Handler',
214	'mollie' => 'SureDonationPro\\Inc\\Payments\\Mollie\\Mollie_Subscription_Handler',
215	'razorpay' => 'SureDonationPro\\Inc\\Payments\\Razorpay\\Razorpay_Subscription_Handler',
216	];
217
218	if ( ! isset( $detectors[ $sd_gateway ] ) ) {
219	return false;
220	}
221
222	return class_exists( $detectors[ $sd_gateway ] );
223	}
224	}
225