| 1 |
<?php |
| 2 |
/** |
| 3 |
* Privacy Data — WordPress personal-data export/erase integration. |
| 4 |
* |
| 5 |
* Registers SureDonation with WordPress Tools → Export/Erase Personal Data so a |
| 6 |
* donor's data can be exported or erased on request. Erasure honors the Privacy |
| 7 |
* settings' Minimum Data Retention Period (full erase — no per-field retention): |
| 8 |
* donations still inside the retention window are retained; older ones are fully |
| 9 |
* anonymized. |
| 10 |
* |
| 11 |
* @package SureDonation |
| 12 |
* @since 1.2.0 |
| 13 |
*/ |
| 14 |
|
| 15 |
namespace SureDonation\Inc\Privacy; |
| 16 |
|
| 17 |
use SureDonation\Inc\Database\Tables\Donations; |
| 18 |
use SureDonation\Inc\Database\Tables\Donors; |
| 19 |
use SureDonation\Inc\Helper; |
| 20 |
use SureDonation\Inc\Pdf\Receipt_Generator; |
| 21 |
use SureDonation\Inc\Traits\Get_Instance; |
| 22 |
|
| 23 |
if ( ! defined( 'ABSPATH' ) ) { |
| 24 |
exit; // Exit if accessed directly. |
| 25 |
} |
| 26 |
|
| 27 |
/** |
| 28 |
* Privacy_Data class. |
| 29 |
* |
| 30 |
* @since 1.2.0 |
| 31 |
*/ |
| 32 |
class Privacy_Data { |
| 33 |
/** |
| 34 |
* The donation_data keys that hold the donor's own personal data and are |
| 35 |
* removed on erasure. Everything else in the column is an operational |
| 36 |
* record (refunds, notes, subscription metadata) and is written back. |
| 37 |
* |
| 38 |
* `gift_aid` is written by SureDonation Pro: a UK Gift Aid declaration |
| 39 |
* carries the donor's legal name and home address. It is named here, in |
| 40 |
* free, because an eraser that ran only while Pro was active would report |
| 41 |
* a completed erasure with that address still on the row the moment Pro |
| 42 |
* was deactivated, and the anonymised email would then hide the row from |
| 43 |
* every later request. |
| 44 |
* |
| 45 |
* @since 1.6.1 |
| 46 |
*/ |
| 47 |
public const ERASED_DONATION_DATA_KEYS = [ 'fields', 'gift_aid' ]; |
| 48 |
|
| 49 |
use Get_Instance; |
| 50 |
|
| 51 |
/** |
| 52 |
* Constructor — register the exporter + eraser with WordPress. |
| 53 |
* |
| 54 |
* @since 1.2.0 |
| 55 |
*/ |
| 56 |
public function __construct() { |
| 57 |
add_filter( 'wp_privacy_personal_data_exporters', [ $this, 'register_exporters' ] ); |
| 58 |
add_filter( 'wp_privacy_personal_data_erasers', [ $this, 'register_erasers' ] ); |
| 59 |
} |
| 60 |
|
| 61 |
/** |
| 62 |
* Register the SureDonation personal-data exporter. |
| 63 |
* |
| 64 |
* @since 1.2.0 |
| 65 |
* @param array<string, mixed> $exporters Registered exporters. |
| 66 |
* @return array<string, mixed> |
| 67 |
*/ |
| 68 |
public function register_exporters( $exporters ) { |
| 69 |
if ( ! is_array( $exporters ) ) { |
| 70 |
$exporters = []; |
| 71 |
} |
| 72 |
$exporters['suredonation'] = [ |
| 73 |
'exporter_friendly_name' => __( 'SureDonation Donations', 'suredonation' ), |
| 74 |
'callback' => [ $this, 'export' ], |
| 75 |
]; |
| 76 |
return $exporters; |
| 77 |
} |
| 78 |
|
| 79 |
/** |
| 80 |
* Register the SureDonation personal-data eraser. |
| 81 |
* |
| 82 |
* @since 1.2.0 |
| 83 |
* @param array<string, mixed> $erasers Registered erasers. |
| 84 |
* @return array<string, mixed> |
| 85 |
*/ |
| 86 |
public function register_erasers( $erasers ) { |
| 87 |
if ( ! is_array( $erasers ) ) { |
| 88 |
$erasers = []; |
| 89 |
} |
| 90 |
$erasers['suredonation'] = [ |
| 91 |
'eraser_friendly_name' => __( 'SureDonation Donations', 'suredonation' ), |
| 92 |
'callback' => [ $this, 'erase' ], |
| 93 |
]; |
| 94 |
return $erasers; |
| 95 |
} |
| 96 |
|
| 97 |
/** |
| 98 |
* Export a donor's personal data (donor profile + their donations). |
| 99 |
* |
| 100 |
* Paginated per the WordPress exporter contract: the donor profile is emitted on |
| 101 |
* the first page and donations are returned in fixed-size batches, so a donor with |
| 102 |
* many donations doesn't load them all into one response. |
| 103 |
* |
| 104 |
* @since 1.2.0 |
| 105 |
* @param string $email_address The email being exported. |
| 106 |
* @param int $page 1-based page number supplied by WordPress. |
| 107 |
* @return array{data: array<int, array<string, mixed>>, done: bool} |
| 108 |
*/ |
| 109 |
public function export( $email_address, $page = 1 ) { |
| 110 |
$email = sanitize_email( (string) $email_address ); |
| 111 |
$page = max( 1, (int) $page ); |
| 112 |
$batch = 100; |
| 113 |
$export = []; |
| 114 |
|
| 115 |
// Donor profile is emitted once, on the first page. |
| 116 |
$donor = 1 === $page ? Donors::get_by_email( $email ) : null; |
| 117 |
if ( is_array( $donor ) && ! empty( $donor ) ) { |
| 118 |
$export[] = [ |
| 119 |
'group_id' => 'suredonation-donor', |
| 120 |
'group_label' => __( 'SureDonation Donor', 'suredonation' ), |
| 121 |
'item_id' => 'suredonation-donor-' . absint( Helper::get_string_value( $donor['id'] ?? 0 ) ), |
| 122 |
'data' => self::name_value_rows( |
| 123 |
[ |
| 124 |
__( 'Name', 'suredonation' ) => $donor['name'] ?? '', |
| 125 |
__( 'Email', 'suredonation' ) => $donor['email'] ?? '', |
| 126 |
__( 'Phone', 'suredonation' ) => $donor['phone'] ?? '', |
| 127 |
__( 'Company', 'suredonation' ) => $donor['company'] ?? '', |
| 128 |
__( 'Address', 'suredonation' ) => $donor['address'] ?? '', |
| 129 |
] |
| 130 |
), |
| 131 |
]; |
| 132 |
} |
| 133 |
|
| 134 |
$donations = Donations::get_by_donor_email( $email, $batch, ( $page - 1 ) * $batch ); |
| 135 |
$donations = is_array( $donations ) ? $donations : []; |
| 136 |
foreach ( $donations as $donation ) { |
| 137 |
if ( ! is_array( $donation ) ) { |
| 138 |
continue; |
| 139 |
} |
| 140 |
|
| 141 |
// Mirrors the eraser's field set — everything the eraser treats as donor |
| 142 |
// PII (incl. ip / user-agent / referrer) must also be disclosed on export. |
| 143 |
$rows = [ |
| 144 |
__( 'Amount', 'suredonation' ) => $donation['amount'] ?? '', |
| 145 |
__( 'Currency', 'suredonation' ) => $donation['currency'] ?? '', |
| 146 |
__( 'Status', 'suredonation' ) => $donation['status'] ?? '', |
| 147 |
__( 'Date', 'suredonation' ) => $donation['created_at'] ?? '', |
| 148 |
__( 'Donor Name', 'suredonation' ) => $donation['donor_name'] ?? '', |
| 149 |
__( 'Donor Email', 'suredonation' ) => $donation['donor_email'] ?? '', |
| 150 |
__( 'Donor Phone', 'suredonation' ) => $donation['donor_phone'] ?? '', |
| 151 |
__( 'Comment', 'suredonation' ) => $donation['donor_comment'] ?? '', |
| 152 |
__( 'IP Address', 'suredonation' ) => $donation['ip_address'] ?? '', |
| 153 |
__( 'User Agent', 'suredonation' ) => $donation['user_agent'] ?? '', |
| 154 |
__( 'Referrer', 'suredonation' ) => $donation['referer_url'] ?? '', |
| 155 |
]; |
| 156 |
|
| 157 |
// Include the extra submitted form fields (label => value) if present. |
| 158 |
$fields = isset( $donation['donation_data']['fields'] ) && is_array( $donation['donation_data']['fields'] ) ? $donation['donation_data']['fields'] : []; |
| 159 |
foreach ( $fields as $field ) { |
| 160 |
if ( ! is_array( $field ) || ! isset( $field['label'] ) ) { |
| 161 |
continue; |
| 162 |
} |
| 163 |
// Deduplicate repeated labels ("Label", "Label (2)", …) — a duplicate |
| 164 |
// key would silently overwrite the earlier field's value in the export. |
| 165 |
$label = Helper::get_string_value( $field['label'] ); |
| 166 |
$unique = $label; |
| 167 |
$suffix = 2; |
| 168 |
while ( array_key_exists( $unique, $rows ) ) { |
| 169 |
$unique = $label . ' (' . $suffix . ')'; |
| 170 |
++$suffix; |
| 171 |
} |
| 172 |
$rows[ $unique ] = $field['value'] ?? ''; |
| 173 |
} |
| 174 |
|
| 175 |
// The Gift Aid declaration (SureDonation Pro) is the record actually |
| 176 |
// filed with HMRC and holds the corrected name and address; the |
| 177 |
// submitted fields above keep whatever the donor first typed. |
| 178 |
$gift_aid = isset( $donation['donation_data']['gift_aid'] ) && is_array( $donation['donation_data']['gift_aid'] ) ? $donation['donation_data']['gift_aid'] : []; |
| 179 |
if ( [] !== $gift_aid ) { |
| 180 |
$rows[ __( 'Gift Aid Declared', 'suredonation' ) ] = true === ( $gift_aid['declared'] ?? false ) ? __( 'Yes', 'suredonation' ) : __( 'No', 'suredonation' ); |
| 181 |
foreach ( [ |
| 182 |
'first_name' => __( 'Gift Aid First Name', 'suredonation' ), |
| 183 |
'last_name' => __( 'Gift Aid Last Name', 'suredonation' ), |
| 184 |
'house' => __( 'Gift Aid House Name or Number', 'suredonation' ), |
| 185 |
'postcode' => __( 'Gift Aid Postcode', 'suredonation' ), |
| 186 |
'country' => __( 'Gift Aid Country', 'suredonation' ), |
| 187 |
] as $key => $label ) { |
| 188 |
if ( isset( $gift_aid[ $key ] ) && is_scalar( $gift_aid[ $key ] ) ) { |
| 189 |
$rows[ $label ] = (string) $gift_aid[ $key ]; |
| 190 |
} |
| 191 |
} |
| 192 |
} |
| 193 |
|
| 194 |
$export[] = [ |
| 195 |
'group_id' => 'suredonation-donations', |
| 196 |
'group_label' => __( 'SureDonation Donations', 'suredonation' ), |
| 197 |
'item_id' => 'suredonation-donation-' . absint( Helper::get_string_value( $donation['id'] ?? 0 ) ), |
| 198 |
'data' => self::name_value_rows( $rows ), |
| 199 |
]; |
| 200 |
} |
| 201 |
|
| 202 |
// Done once a page returns fewer donations than the batch size. |
| 203 |
$done = count( $donations ) < $batch; |
| 204 |
|
| 205 |
if ( $done ) { |
| 206 |
/** |
| 207 |
* Fires when a personal-data export including SureDonation data completes. |
| 208 |
* |
| 209 |
* @since 1.2.0 |
| 210 |
*/ |
| 211 |
do_action( 'suredonation_privacy_data_exported' ); |
| 212 |
} |
| 213 |
|
| 214 |
return [ |
| 215 |
'data' => $export, |
| 216 |
'done' => $done, |
| 217 |
]; |
| 218 |
} |
| 219 |
|
| 220 |
/** |
| 221 |
* Erase a donor's personal data, honoring the retention period. |
| 222 |
* |
| 223 |
* Donations still inside the Minimum Data Retention Period are retained; older |
| 224 |
* donations are fully anonymized. The donor profile is anonymized only when all |
| 225 |
* of their donations were erased (none retained). |
| 226 |
* |
| 227 |
* Handled in a single pass (not paginated like export): the donor-profile decision |
| 228 |
* needs to know whether *any* donation across the whole set was retained, which |
| 229 |
* can't be determined from one page in isolation. |
| 230 |
* |
| 231 |
* @since 1.2.0 |
| 232 |
* @param string $email_address The email being erased. |
| 233 |
* @param int $page Page number (unused — all data handled at once). |
| 234 |
* @return array{items_removed: bool, items_retained: bool, messages: array<int, string>, done: bool} |
| 235 |
*/ |
| 236 |
public function erase( $email_address, $page = 1 ) { |
| 237 |
unset( $page ); |
| 238 |
$email = sanitize_email( (string) $email_address ); |
| 239 |
$items_removed = false; |
| 240 |
$items_retained = false; |
| 241 |
$erase_failed = false; |
| 242 |
$messages = []; |
| 243 |
|
| 244 |
$donations = Donations::get_by_donor_email( $email ); |
| 245 |
foreach ( is_array( $donations ) ? $donations : [] as $donation ) { |
| 246 |
if ( ! is_array( $donation ) || ! isset( $donation['id'] ) ) { |
| 247 |
continue; |
| 248 |
} |
| 249 |
|
| 250 |
if ( ! Privacy_Settings::is_donation_erasable( Helper::get_string_value( $donation['created_at'] ?? '' ) ) ) { |
| 251 |
$items_retained = true; |
| 252 |
continue; |
| 253 |
} |
| 254 |
|
| 255 |
// Strip the personal-data keys from donation_data, keep the rest |
| 256 |
// (e.g. refunds/notes are operational records, not donor PII). |
| 257 |
$donation_data = isset( $donation['donation_data'] ) && is_array( $donation['donation_data'] ) ? $donation['donation_data'] : []; |
| 258 |
foreach ( self::ERASED_DONATION_DATA_KEYS as $key ) { |
| 259 |
unset( $donation_data[ $key ] ); |
| 260 |
} |
| 261 |
|
| 262 |
// The receipt PDF is generated from the donor's name/email/address — |
| 263 |
// erasure must remove the file from disk, not just the DB columns. |
| 264 |
$receipt_deleted = Receipt_Generator::delete_receipt( Helper::get_string_value( $donation['receipt_pdf_url'] ?? '' ) ); |
| 265 |
|
| 266 |
// Besides the direct PII columns, clear pseudonymous identifiers that |
| 267 |
// re-link the record to the donor at the payment provider (Stripe |
| 268 |
// customer/subscription ids) and the gateway log (can embed the donor's |
| 269 |
// email). transaction_id and subscription_status are kept deliberately: |
| 270 |
// the transaction reference is required for financial reconciliation / |
| 271 |
// refund handling and identifies the payment, not the person; the |
| 272 |
// status is a non-identifying enum. |
| 273 |
$anonymized = [ |
| 274 |
'donor_name' => wp_privacy_anonymize_data( 'text', Helper::get_string_value( $donation['donor_name'] ?? '' ) ), |
| 275 |
'donor_email' => wp_privacy_anonymize_data( 'email', $email ), |
| 276 |
'donor_phone' => '', |
| 277 |
'donor_comment' => '', |
| 278 |
'ip_address' => wp_privacy_anonymize_data( 'ip', Helper::get_string_value( $donation['ip_address'] ?? '' ) ), |
| 279 |
'user_agent' => '', |
| 280 |
'referer_url' => '', |
| 281 |
'donation_data' => $donation_data, |
| 282 |
'customer_id' => '', |
| 283 |
'subscription_id' => '', |
| 284 |
'parent_subscription_id' => 0, |
| 285 |
'log' => '', |
| 286 |
]; |
| 287 |
|
| 288 |
// Clear the receipt pointer once nothing further will be done with |
| 289 |
// it — otherwise keep it so a retried erasure can still find the |
| 290 |
// file. A pointer refused by containment also reports true and is |
| 291 |
// dropped deliberately: no caller can act on it, so retaining it |
| 292 |
// would fail the erasure forever with no remedy for the admin. |
| 293 |
if ( $receipt_deleted ) { |
| 294 |
$anonymized['receipt_pdf_url'] = ''; |
| 295 |
} |
| 296 |
|
| 297 |
$updated = Donations::update( absint( Helper::get_string_value( $donation['id'] ) ), $anonymized ); |
| 298 |
|
| 299 |
// Donations::update() returns int|false — only report data as removed |
| 300 |
// when the write actually succeeded; a confirmed erasure for data still |
| 301 |
// in the database would be a silent compliance failure. |
| 302 |
if ( false !== $updated && $receipt_deleted ) { |
| 303 |
$items_removed = true; |
| 304 |
} else { |
| 305 |
$erase_failed = true; |
| 306 |
} |
| 307 |
} |
| 308 |
|
| 309 |
// Anonymize the donor profile only when nothing is being retained for them |
| 310 |
// (and nothing failed to erase — a failed donation write means PII may still |
| 311 |
// reference this donor). All-or-nothing by design (Charitable-style model): |
| 312 |
// while any donation is retained, its row still carries the donor's identity, |
| 313 |
// so scrubbing only the profile would not reduce what is held; the profile is |
| 314 |
// erased together with the last retained donation once the window lapses. |
| 315 |
$donor = Donors::get_by_email( $email ); |
| 316 |
if ( is_array( $donor ) && ! empty( $donor ) && ! $items_retained && ! $erase_failed ) { |
| 317 |
$donor_id = absint( Helper::get_string_value( $donor['id'] ?? 0 ) ); |
| 318 |
if ( $donor_id > 0 ) { |
| 319 |
Donors::clear_stripe_customer_id_by_email( $email ); |
| 320 |
|
| 321 |
// Clear the per-account Stripe customer identifiers added with |
| 322 |
// multi-account support: the donor_data map (folded into the |
| 323 |
// anonymization write below) and the per-account user-meta cache. |
| 324 |
$donor_data = isset( $donor['donor_data'] ) && is_array( $donor['donor_data'] ) ? $donor['donor_data'] : []; |
| 325 |
unset( $donor_data['stripe_customers'] ); |
| 326 |
|
| 327 |
$wp_user = get_user_by( 'email', $email ); |
| 328 |
if ( $wp_user instanceof \WP_User ) { |
| 329 |
delete_user_meta( $wp_user->ID, '_stripe_customer_id' ); |
| 330 |
global $wpdb; |
| 331 |
// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, WordPress.DB.PreparedSQL.InterpolatedNotPrepared -- One-off GDPR erase of prefixed per-account customer-id meta; $wpdb->usermeta is trusted. |
| 332 |
$meta_keys = $wpdb->get_col( $wpdb->prepare( "SELECT meta_key FROM {$wpdb->usermeta} WHERE user_id = %d AND meta_key LIKE %s", $wp_user->ID, $wpdb->esc_like( '_suredonation_stripe_customer_id_' ) . '%' ) ); |
| 333 |
if ( is_array( $meta_keys ) ) { |
| 334 |
foreach ( $meta_keys as $meta_key ) { |
| 335 |
delete_user_meta( $wp_user->ID, (string) $meta_key ); |
| 336 |
} |
| 337 |
} |
| 338 |
} |
| 339 |
|
| 340 |
$updated = Donors::update( |
| 341 |
$donor_id, |
| 342 |
[ |
| 343 |
// Keep the email unique per donor to respect the UNIQUE column. |
| 344 |
'email' => 'deleted-' . $donor_id . '@site.invalid', |
| 345 |
'name' => wp_privacy_anonymize_data( 'text', Helper::get_string_value( $donor['name'] ?? '' ) ), |
| 346 |
'phone' => '', |
| 347 |
'company' => '', |
| 348 |
'address' => '', |
| 349 |
'donor_data' => $donor_data, |
| 350 |
] |
| 351 |
); |
| 352 |
|
| 353 |
// Same int|false contract as the donation updates above. |
| 354 |
if ( false !== $updated ) { |
| 355 |
$items_removed = true; |
| 356 |
} else { |
| 357 |
$erase_failed = true; |
| 358 |
} |
| 359 |
} |
| 360 |
} |
| 361 |
|
| 362 |
if ( $items_retained ) { |
| 363 |
$messages[] = __( 'Some donation data was retained because it falls within the configured data retention period.', 'suredonation' ); |
| 364 |
} |
| 365 |
|
| 366 |
if ( $erase_failed ) { |
| 367 |
$messages[] = __( 'Some SureDonation data could not be erased due to a database or filesystem error. Please retry or contact the site administrator.', 'suredonation' ); |
| 368 |
} |
| 369 |
|
| 370 |
/** |
| 371 |
* Fires when a personal-data erasure request has been processed for SureDonation data. |
| 372 |
* |
| 373 |
* @since 1.2.0 |
| 374 |
* @param array{items_removed: bool, items_retained: bool, erase_failed: bool} $outcome Erasure outcome flags. |
| 375 |
*/ |
| 376 |
do_action( |
| 377 |
'suredonation_privacy_data_erased', |
| 378 |
[ |
| 379 |
'items_removed' => $items_removed, |
| 380 |
'items_retained' => $items_retained, |
| 381 |
'erase_failed' => $erase_failed, |
| 382 |
] |
| 383 |
); |
| 384 |
|
| 385 |
return [ |
| 386 |
'items_removed' => $items_removed, |
| 387 |
'items_retained' => $items_retained, |
| 388 |
'messages' => $messages, |
| 389 |
'done' => true, |
| 390 |
]; |
| 391 |
} |
| 392 |
|
| 393 |
/** |
| 394 |
* Convert a label => value map into the WordPress exporter row shape. |
| 395 |
* |
| 396 |
* @since 1.2.0 |
| 397 |
* @param array<string, mixed> $map Label => value pairs. |
| 398 |
* @return array<int, array{name: string, value: string}> |
| 399 |
*/ |
| 400 |
private static function name_value_rows( $map ) { |
| 401 |
$rows = []; |
| 402 |
foreach ( $map as $label => $value ) { |
| 403 |
$rows[] = [ |
| 404 |
'name' => (string) $label, |
| 405 |
'value' => Helper::get_string_value( $value ), |
| 406 |
]; |
| 407 |
} |
| 408 |
return $rows; |
| 409 |
} |
| 410 |
} |
| 411 |
|
