| 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 |
use Get_Instance; |
| 34 |
|
| 35 |
/** |
| 36 |
* Constructor — register the exporter + eraser with WordPress. |
| 37 |
* |
| 38 |
* @since 1.2.0 |
| 39 |
*/ |
| 40 |
public function __construct() { |
| 41 |
add_filter( 'wp_privacy_personal_data_exporters', [ $this, 'register_exporters' ] ); |
| 42 |
add_filter( 'wp_privacy_personal_data_erasers', [ $this, 'register_erasers' ] ); |
| 43 |
} |
| 44 |
|
| 45 |
/** |
| 46 |
* Register the SureDonation personal-data exporter. |
| 47 |
* |
| 48 |
* @since 1.2.0 |
| 49 |
* @param array<string, mixed> $exporters Registered exporters. |
| 50 |
* @return array<string, mixed> |
| 51 |
*/ |
| 52 |
public function register_exporters( $exporters ) { |
| 53 |
if ( ! is_array( $exporters ) ) { |
| 54 |
$exporters = []; |
| 55 |
} |
| 56 |
$exporters['suredonation'] = [ |
| 57 |
'exporter_friendly_name' => __( 'SureDonation Donations', 'suredonation' ), |
| 58 |
'callback' => [ $this, 'export' ], |
| 59 |
]; |
| 60 |
return $exporters; |
| 61 |
} |
| 62 |
|
| 63 |
/** |
| 64 |
* Register the SureDonation personal-data eraser. |
| 65 |
* |
| 66 |
* @since 1.2.0 |
| 67 |
* @param array<string, mixed> $erasers Registered erasers. |
| 68 |
* @return array<string, mixed> |
| 69 |
*/ |
| 70 |
public function register_erasers( $erasers ) { |
| 71 |
if ( ! is_array( $erasers ) ) { |
| 72 |
$erasers = []; |
| 73 |
} |
| 74 |
$erasers['suredonation'] = [ |
| 75 |
'eraser_friendly_name' => __( 'SureDonation Donations', 'suredonation' ), |
| 76 |
'callback' => [ $this, 'erase' ], |
| 77 |
]; |
| 78 |
return $erasers; |
| 79 |
} |
| 80 |
|
| 81 |
/** |
| 82 |
* Export a donor's personal data (donor profile + their donations). |
| 83 |
* |
| 84 |
* Paginated per the WordPress exporter contract: the donor profile is emitted on |
| 85 |
* the first page and donations are returned in fixed-size batches, so a donor with |
| 86 |
* many donations doesn't load them all into one response. |
| 87 |
* |
| 88 |
* @since 1.2.0 |
| 89 |
* @param string $email_address The email being exported. |
| 90 |
* @param int $page 1-based page number supplied by WordPress. |
| 91 |
* @return array{data: array<int, array<string, mixed>>, done: bool} |
| 92 |
*/ |
| 93 |
public function export( $email_address, $page = 1 ) { |
| 94 |
$email = sanitize_email( (string) $email_address ); |
| 95 |
$page = max( 1, (int) $page ); |
| 96 |
$batch = 100; |
| 97 |
$export = []; |
| 98 |
|
| 99 |
// Donor profile is emitted once, on the first page. |
| 100 |
$donor = 1 === $page ? Donors::get_by_email( $email ) : null; |
| 101 |
if ( is_array( $donor ) && ! empty( $donor ) ) { |
| 102 |
$export[] = [ |
| 103 |
'group_id' => 'suredonation-donor', |
| 104 |
'group_label' => __( 'SureDonation Donor', 'suredonation' ), |
| 105 |
'item_id' => 'suredonation-donor-' . absint( Helper::get_string_value( $donor['id'] ?? 0 ) ), |
| 106 |
'data' => self::name_value_rows( |
| 107 |
[ |
| 108 |
__( 'Name', 'suredonation' ) => $donor['name'] ?? '', |
| 109 |
__( 'Email', 'suredonation' ) => $donor['email'] ?? '', |
| 110 |
__( 'Phone', 'suredonation' ) => $donor['phone'] ?? '', |
| 111 |
__( 'Company', 'suredonation' ) => $donor['company'] ?? '', |
| 112 |
__( 'Address', 'suredonation' ) => $donor['address'] ?? '', |
| 113 |
] |
| 114 |
), |
| 115 |
]; |
| 116 |
} |
| 117 |
|
| 118 |
$donations = Donations::get_by_donor_email( $email, $batch, ( $page - 1 ) * $batch ); |
| 119 |
$donations = is_array( $donations ) ? $donations : []; |
| 120 |
foreach ( $donations as $donation ) { |
| 121 |
if ( ! is_array( $donation ) ) { |
| 122 |
continue; |
| 123 |
} |
| 124 |
|
| 125 |
// Mirrors the eraser's field set — everything the eraser treats as donor |
| 126 |
// PII (incl. ip / user-agent / referrer) must also be disclosed on export. |
| 127 |
$rows = [ |
| 128 |
__( 'Amount', 'suredonation' ) => $donation['amount'] ?? '', |
| 129 |
__( 'Currency', 'suredonation' ) => $donation['currency'] ?? '', |
| 130 |
__( 'Status', 'suredonation' ) => $donation['status'] ?? '', |
| 131 |
__( 'Date', 'suredonation' ) => $donation['created_at'] ?? '', |
| 132 |
__( 'Donor Name', 'suredonation' ) => $donation['donor_name'] ?? '', |
| 133 |
__( 'Donor Email', 'suredonation' ) => $donation['donor_email'] ?? '', |
| 134 |
__( 'Donor Phone', 'suredonation' ) => $donation['donor_phone'] ?? '', |
| 135 |
__( 'Comment', 'suredonation' ) => $donation['donor_comment'] ?? '', |
| 136 |
__( 'IP Address', 'suredonation' ) => $donation['ip_address'] ?? '', |
| 137 |
__( 'User Agent', 'suredonation' ) => $donation['user_agent'] ?? '', |
| 138 |
__( 'Referrer', 'suredonation' ) => $donation['referer_url'] ?? '', |
| 139 |
]; |
| 140 |
|
| 141 |
// Include the extra submitted form fields (label => value) if present. |
| 142 |
$fields = isset( $donation['donation_data']['fields'] ) && is_array( $donation['donation_data']['fields'] ) ? $donation['donation_data']['fields'] : []; |
| 143 |
foreach ( $fields as $field ) { |
| 144 |
if ( ! is_array( $field ) || ! isset( $field['label'] ) ) { |
| 145 |
continue; |
| 146 |
} |
| 147 |
// Deduplicate repeated labels ("Label", "Label (2)", …) — a duplicate |
| 148 |
// key would silently overwrite the earlier field's value in the export. |
| 149 |
$label = Helper::get_string_value( $field['label'] ); |
| 150 |
$unique = $label; |
| 151 |
$suffix = 2; |
| 152 |
while ( array_key_exists( $unique, $rows ) ) { |
| 153 |
$unique = $label . ' (' . $suffix . ')'; |
| 154 |
++$suffix; |
| 155 |
} |
| 156 |
$rows[ $unique ] = $field['value'] ?? ''; |
| 157 |
} |
| 158 |
|
| 159 |
$export[] = [ |
| 160 |
'group_id' => 'suredonation-donations', |
| 161 |
'group_label' => __( 'SureDonation Donations', 'suredonation' ), |
| 162 |
'item_id' => 'suredonation-donation-' . absint( Helper::get_string_value( $donation['id'] ?? 0 ) ), |
| 163 |
'data' => self::name_value_rows( $rows ), |
| 164 |
]; |
| 165 |
} |
| 166 |
|
| 167 |
// Done once a page returns fewer donations than the batch size. |
| 168 |
$done = count( $donations ) < $batch; |
| 169 |
|
| 170 |
if ( $done ) { |
| 171 |
/** |
| 172 |
* Fires when a personal-data export including SureDonation data completes. |
| 173 |
* |
| 174 |
* @since 1.2.0 |
| 175 |
*/ |
| 176 |
do_action( 'suredonation_privacy_data_exported' ); |
| 177 |
} |
| 178 |
|
| 179 |
return [ |
| 180 |
'data' => $export, |
| 181 |
'done' => $done, |
| 182 |
]; |
| 183 |
} |
| 184 |
|
| 185 |
/** |
| 186 |
* Erase a donor's personal data, honoring the retention period. |
| 187 |
* |
| 188 |
* Donations still inside the Minimum Data Retention Period are retained; older |
| 189 |
* donations are fully anonymized. The donor profile is anonymized only when all |
| 190 |
* of their donations were erased (none retained). |
| 191 |
* |
| 192 |
* Handled in a single pass (not paginated like export): the donor-profile decision |
| 193 |
* needs to know whether *any* donation across the whole set was retained, which |
| 194 |
* can't be determined from one page in isolation. |
| 195 |
* |
| 196 |
* @since 1.2.0 |
| 197 |
* @param string $email_address The email being erased. |
| 198 |
* @param int $page Page number (unused — all data handled at once). |
| 199 |
* @return array{items_removed: bool, items_retained: bool, messages: array<int, string>, done: bool} |
| 200 |
*/ |
| 201 |
public function erase( $email_address, $page = 1 ) { |
| 202 |
unset( $page ); |
| 203 |
$email = sanitize_email( (string) $email_address ); |
| 204 |
$items_removed = false; |
| 205 |
$items_retained = false; |
| 206 |
$erase_failed = false; |
| 207 |
$messages = []; |
| 208 |
|
| 209 |
$donations = Donations::get_by_donor_email( $email ); |
| 210 |
foreach ( is_array( $donations ) ? $donations : [] as $donation ) { |
| 211 |
if ( ! is_array( $donation ) || ! isset( $donation['id'] ) ) { |
| 212 |
continue; |
| 213 |
} |
| 214 |
|
| 215 |
if ( ! Privacy_Settings::is_donation_erasable( Helper::get_string_value( $donation['created_at'] ?? '' ) ) ) { |
| 216 |
$items_retained = true; |
| 217 |
continue; |
| 218 |
} |
| 219 |
|
| 220 |
// Strip the personal-data keys from donation_data, keep the rest |
| 221 |
// (e.g. refunds/notes are operational records, not donor PII). |
| 222 |
$donation_data = isset( $donation['donation_data'] ) && is_array( $donation['donation_data'] ) ? $donation['donation_data'] : []; |
| 223 |
unset( $donation_data['fields'] ); |
| 224 |
|
| 225 |
// The receipt PDF is generated from the donor's name/email/address — |
| 226 |
// erasure must remove the file from disk, not just the DB columns. |
| 227 |
$receipt_deleted = Receipt_Generator::delete_receipt( Helper::get_string_value( $donation['receipt_pdf_url'] ?? '' ) ); |
| 228 |
|
| 229 |
// Besides the direct PII columns, clear pseudonymous identifiers that |
| 230 |
// re-link the record to the donor at the payment provider (Stripe |
| 231 |
// customer/subscription ids) and the gateway log (can embed the donor's |
| 232 |
// email). transaction_id and subscription_status are kept deliberately: |
| 233 |
// the transaction reference is required for financial reconciliation / |
| 234 |
// refund handling and identifies the payment, not the person; the |
| 235 |
// status is a non-identifying enum. |
| 236 |
$anonymized = [ |
| 237 |
'donor_name' => wp_privacy_anonymize_data( 'text', Helper::get_string_value( $donation['donor_name'] ?? '' ) ), |
| 238 |
'donor_email' => wp_privacy_anonymize_data( 'email', $email ), |
| 239 |
'donor_phone' => '', |
| 240 |
'donor_comment' => '', |
| 241 |
'ip_address' => wp_privacy_anonymize_data( 'ip', Helper::get_string_value( $donation['ip_address'] ?? '' ) ), |
| 242 |
'user_agent' => '', |
| 243 |
'referer_url' => '', |
| 244 |
'donation_data' => $donation_data, |
| 245 |
'customer_id' => '', |
| 246 |
'subscription_id' => '', |
| 247 |
'parent_subscription_id' => 0, |
| 248 |
'log' => '', |
| 249 |
]; |
| 250 |
|
| 251 |
// Clear the receipt pointer only when the file is actually gone — |
| 252 |
// otherwise keep it so a retried erasure can still find the file. |
| 253 |
if ( $receipt_deleted ) { |
| 254 |
$anonymized['receipt_pdf_url'] = ''; |
| 255 |
} |
| 256 |
|
| 257 |
$updated = Donations::update( absint( Helper::get_string_value( $donation['id'] ) ), $anonymized ); |
| 258 |
|
| 259 |
// Donations::update() returns int|false — only report data as removed |
| 260 |
// when the write actually succeeded; a confirmed erasure for data still |
| 261 |
// in the database would be a silent compliance failure. |
| 262 |
if ( false !== $updated && $receipt_deleted ) { |
| 263 |
$items_removed = true; |
| 264 |
} else { |
| 265 |
$erase_failed = true; |
| 266 |
} |
| 267 |
} |
| 268 |
|
| 269 |
// Anonymize the donor profile only when nothing is being retained for them |
| 270 |
// (and nothing failed to erase — a failed donation write means PII may still |
| 271 |
// reference this donor). All-or-nothing by design (Charitable-style model): |
| 272 |
// while any donation is retained, its row still carries the donor's identity, |
| 273 |
// so scrubbing only the profile would not reduce what is held; the profile is |
| 274 |
// erased together with the last retained donation once the window lapses. |
| 275 |
$donor = Donors::get_by_email( $email ); |
| 276 |
if ( is_array( $donor ) && ! empty( $donor ) && ! $items_retained && ! $erase_failed ) { |
| 277 |
$donor_id = absint( Helper::get_string_value( $donor['id'] ?? 0 ) ); |
| 278 |
if ( $donor_id > 0 ) { |
| 279 |
Donors::clear_stripe_customer_id_by_email( $email ); |
| 280 |
$updated = Donors::update( |
| 281 |
$donor_id, |
| 282 |
[ |
| 283 |
// Keep the email unique per donor to respect the UNIQUE column. |
| 284 |
'email' => 'deleted-' . $donor_id . '@site.invalid', |
| 285 |
'name' => wp_privacy_anonymize_data( 'text', Helper::get_string_value( $donor['name'] ?? '' ) ), |
| 286 |
'phone' => '', |
| 287 |
'company' => '', |
| 288 |
'address' => '', |
| 289 |
] |
| 290 |
); |
| 291 |
|
| 292 |
// Same int|false contract as the donation updates above. |
| 293 |
if ( false !== $updated ) { |
| 294 |
$items_removed = true; |
| 295 |
} else { |
| 296 |
$erase_failed = true; |
| 297 |
} |
| 298 |
} |
| 299 |
} |
| 300 |
|
| 301 |
if ( $items_retained ) { |
| 302 |
$messages[] = __( 'Some donation data was retained because it falls within the configured data retention period.', 'suredonation' ); |
| 303 |
} |
| 304 |
|
| 305 |
if ( $erase_failed ) { |
| 306 |
$messages[] = __( 'Some SureDonation data could not be erased due to a database or filesystem error. Please retry or contact the site administrator.', 'suredonation' ); |
| 307 |
} |
| 308 |
|
| 309 |
/** |
| 310 |
* Fires when a personal-data erasure request has been processed for SureDonation data. |
| 311 |
* |
| 312 |
* @since 1.2.0 |
| 313 |
* @param array{items_removed: bool, items_retained: bool, erase_failed: bool} $outcome Erasure outcome flags. |
| 314 |
*/ |
| 315 |
do_action( |
| 316 |
'suredonation_privacy_data_erased', |
| 317 |
[ |
| 318 |
'items_removed' => $items_removed, |
| 319 |
'items_retained' => $items_retained, |
| 320 |
'erase_failed' => $erase_failed, |
| 321 |
] |
| 322 |
); |
| 323 |
|
| 324 |
return [ |
| 325 |
'items_removed' => $items_removed, |
| 326 |
'items_retained' => $items_retained, |
| 327 |
'messages' => $messages, |
| 328 |
'done' => true, |
| 329 |
]; |
| 330 |
} |
| 331 |
|
| 332 |
/** |
| 333 |
* Convert a label => value map into the WordPress exporter row shape. |
| 334 |
* |
| 335 |
* @since 1.2.0 |
| 336 |
* @param array<string, mixed> $map Label => value pairs. |
| 337 |
* @return array<int, array{name: string, value: string}> |
| 338 |
*/ |
| 339 |
private static function name_value_rows( $map ) { |
| 340 |
$rows = []; |
| 341 |
foreach ( $map as $label => $value ) { |
| 342 |
$rows[] = [ |
| 343 |
'name' => (string) $label, |
| 344 |
'value' => Helper::get_string_value( $value ), |
| 345 |
]; |
| 346 |
} |
| 347 |
return $rows; |
| 348 |
} |
| 349 |
} |
| 350 |
|
