suredonation / inc / privacy / privacy-settings.php

privacy-settings.php in SureDonation – Donation Forms, Fundraising Campaigns & Donor Management 1.2.0, at inc/privacy/privacy-settings.php

179 lines 6.4 KB

Raw Download Zip

1	<?php
2	/**
3	* Privacy Settings
4	*
5	* Single source of truth for the SureDonation Privacy settings (Global Settings →
6	* Privacy): the option key, defaults, and the configurable option lists. Shared by
7	* the settings REST API, the donation-form renderer, and (in a later phase) the
8	* WordPress personal-data export/erase integration, so the schema is defined once.
9	*
10	* @package SureDonation
11	* @since 1.2.0
12	*/
13
14	namespace SureDonation\Inc\Privacy;
15
16	use SureDonation\Inc\Helper;
17
18	if ( ! defined( 'ABSPATH' ) ) {
19	exit; // Exit if accessed directly.
20	}
21
22	/**
23	* Privacy_Settings class.
24	*
25	* @since 1.2.0
26	*/
27	class Privacy_Settings {
28	/**
29	* Key within the consolidated suredonation_options array that stores the
30	* Privacy settings.
31	*
32	* @since 1.2.0
33	*/
34	public const OPTION_KEY = 'privacy_settings';
35
36	/**
37	* Default Privacy settings.
38	*
39	* @since 1.2.0
40	* @return array<string, mixed>
41	*/
42	public static function get_defaults() {
43	return [
44	// Data retention (consumed by the export/erase integration). 'none',
45	// a number of years '1'..'10', or 'forever'.
46	'minimum_data_retention_period' => 'none',
47
48	// Contact-consent checkbox on the donation form.
49	'contact_consent_field' => false,
50	'contact_consent_required' => false,
51	'contact_consent_label' => __( 'I consent to being contacted.', 'suredonation' ),
52
53	// Privacy policy statement on the donation form.
54	'privacy_policy_field' => false,
55	'privacy_policy_text' => __( 'Your personal data will be used to process your donation. Read our [privacy_policy].', 'suredonation' ),
56	// Page assigned for the [privacy_policy] link. Falls back to WP core's
57	// wp_page_for_privacy_policy when unset (0).
58	'privacy_page_id' => 0,
59
60	// Terms & conditions statement on the donation form.
61	'terms_conditions_field' => false,
62	'terms_conditions_text' => __( 'By donating you agree to our [terms].', 'suredonation' ),
63	// Page assigned for the [terms] link ([privacy_policy] uses WP core's
64	// wp_page_for_privacy_policy).
65	'terms_page_id' => 0,
66	];
67	}
68
69	/**
70	* Resolve the stored Privacy settings merged over the defaults.
71	*
72	* @since 1.2.0
73	* @return array<string, mixed>
74	*/
75	public static function get_settings() {
76	$stored = Helper::get_suredonation_option( self::OPTION_KEY, [] );
77	return wp_parse_args( is_array( $stored ) ? $stored : [], self::get_defaults() );
78	}
79
80	/**
81	* Options for the "Minimum Data Retention Period" select.
82	*
83	* @since 1.2.0
84	* @return array<int\|string, string> Map of value => label (numeric-string keys become int keys in PHP).
85	*/
86	public static function get_retention_period_options() {
87	$options = [
88	'none' => __( 'None', 'suredonation' ),
89	];
90
91	for ( $years = 1; $years <= 10; $years++ ) {
92	$options[ (string) $years ] = sprintf(
93	/* translators: %d: number of years. */
94	_n( '%d year', '%d years', $years, 'suredonation' ),
95	$years
96	);
97	}
98
99	$options['forever'] = __( 'Forever', 'suredonation' );
100
101	return $options;
102	}
103
104	/**
105	* Sanitize a raw Privacy settings payload against the schema.
106	*
107	* @since 1.2.0
108	* @param array<string, mixed> $raw Raw values (e.g. from a REST request).
109	* @return array<string, mixed> Sanitized settings (only known keys).
110	*/
111	public static function sanitize( $raw ) {
112	$raw = is_array( $raw ) ? $raw : [];
113
114	$retention = isset( $raw['minimum_data_retention_period'] ) ? sanitize_text_field( Helper::get_string_value( $raw['minimum_data_retention_period'] ) ) : 'none';
115	$valid_terms = array_map( 'strval', array_keys( self::get_retention_period_options() ) );
116	if ( ! in_array( $retention, $valid_terms, true ) ) {
117	$retention = 'none';
118	}
119
120	return [
121	'minimum_data_retention_period' => $retention,
122	'contact_consent_field' => ! empty( $raw['contact_consent_field'] ),
123	'contact_consent_required' => ! empty( $raw['contact_consent_required'] ),
124	'contact_consent_label' => isset( $raw['contact_consent_label'] ) ? sanitize_text_field( Helper::get_string_value( $raw['contact_consent_label'] ) ) : '',
125	'privacy_policy_field' => ! empty( $raw['privacy_policy_field'] ),
126	'privacy_policy_text' => isset( $raw['privacy_policy_text'] ) ? wp_kses_post( Helper::get_string_value( $raw['privacy_policy_text'] ) ) : '',
127	'privacy_page_id' => isset( $raw['privacy_page_id'] ) ? absint( Helper::get_string_value( $raw['privacy_page_id'] ) ) : 0,
128	'terms_conditions_field' => ! empty( $raw['terms_conditions_field'] ),
129	'terms_conditions_text' => isset( $raw['terms_conditions_text'] ) ? wp_kses_post( Helper::get_string_value( $raw['terms_conditions_text'] ) ) : '',
130	'terms_page_id' => isset( $raw['terms_page_id'] ) ? absint( Helper::get_string_value( $raw['terms_page_id'] ) ) : 0,
131	];
132	}
133
134	/**
135	* Whether a donation dated $created_at may have its personal data erased,
136	* per the configured Minimum Data Retention Period.
137	*
138	* - 'none' → always erasable.
139	* - 'forever' → never erasable.
140	* - '1'..'10' → erasable only once older than that many years.
141	*
142	* @since 1.2.0
143	* @param string $created_at Donation created-at timestamp (MySQL datetime).
144	* @return bool True when the donation's personal data may be erased.
145	*/
146	public static function is_donation_erasable( $created_at ) {
147	$settings = self::get_settings();
148	$period = isset( $settings['minimum_data_retention_period'] ) ? Helper::get_string_value( $settings['minimum_data_retention_period'] ) : 'none';
149
150	if ( 'none' === $period ) {
151	return true;
152	}
153
154	if ( 'forever' === $period ) {
155	return false;
156	}
157
158	$years = (int) $period;
159	if ( $years <= 0 ) {
160	// Unexpected/garbage period with a numeric window configured — fail
161	// closed (retain) rather than erase data that may be legally retained.
162	return false;
163	}
164
165	// created_at is stored in GMT (Donations::add() uses current_time( 'mysql', true )),
166	// and WordPress runs PHP with the UTC timezone, so strtotime() parses it as UTC —
167	// comparable against time() directly. No conversion: get_gmt_from_date() would treat
168	// it as site-local and shift the retention boundary by the site's UTC offset.
169	$created_ts = strtotime( (string) $created_at );
170	if ( false === $created_ts ) {
171	// Unparseable date — fail closed (retain) while a retention window is set.
172	return false;
173	}
174
175	// Erasable once the donation is older than the retention window.
176	return $created_ts < time() - ( $years * YEAR_IN_SECONDS );
177	}
178	}
179