charitable / includes / abstracts / abstract-class-charitable-field.php

abstract-class-charitable-field.php in Charitable – Donation & Fundraising Platform (Donation Forms, Recurring Donations & Fundraising Campaigns) 1.7.0.2, at includes/abstracts/abstract-class-charitable-field.php

251 lines 5.5 KB

Raw Download Zip

1	<?php
2	/**
3	* Base Charitable_Field model.
4	*
5	* @package Charitable/Classes/Charitable_Field
6	* @author David Bisset
7	* @copyright Copyright (c) 2022, WP Charitable LLC
8	* @license http://opensource.org/licenses/gpl-2.0.php GNU Public License
9	* @since 1.5.0
10	* @version 1.6.0
11	*/
12
13	// Exit if accessed directly.
14	if ( ! defined( 'ABSPATH' ) ) {
15	exit;
16	}
17
18	if ( ! class_exists( 'Charitable_Field' ) ) :
19
20	/**
21	* Charitable_Field
22	*
23	* @since 1.5.0
24	*
25	* @property string $field
26	* @property string $label
27	* @property string $data_type
28	* @property false\|callable $value_callback
29	* @property boolean\|array $admin_form
30	* @property boolean $show_in_export
31	* @property boolean\|array $email_tag
32	*/
33	abstract class Charitable_Field implements Charitable_Field_Interface {
34
35	/**
36	* Field identifier.
37	*
38	* @since 1.5.0
39	*
40	* @var string
41	*/
42	protected $field;
43
44	/**
45	* Field arguments.
46	*
47	* @since 1.5.0
48	*
49	* @var array
50	*/
51	protected $args;
52
53	/**
54	* Raw field arguments. These are the arguments that were passed when instantiating the field.
55	*
56	* @since 1.6.0
57	*
58	* @var array
59	*/
60	protected $raw_args;
61
62	/**
63	* Create class object.
64	*
65	* @since 1.5.0
66	*
67	* @param string $field The field key.
68	* @param array $args Mixed arguments.
69	*/
70	public function __construct( $field, array $args = array() ) {
71	$this->field = $field;
72	$this->raw_args = $args;
73	$this->args = $this->parse_args( $args );
74	}
75
76	/**
77	* Set a field argument.
78	*
79	* Unlike __set(), this also supports setting a setting within an argument.
80	* For example, it allows you to modify the `label` of `donation_form`.
81	*
82	* @since 1.6.0
83	*
84	* @param string $key The field's key.
85	* @param string $setting The individual setting within an array-like argument.
86	* If not set, the entire argument is changed.
87	* @param mixed $value The field's value.
88	* @return Charitable_Field
89	*/
90	public function set( $key, $setting, $value ) {
91	if ( empty( $setting ) ) {
92	return $this->__set( $key, $value );
93	}
94
95	$arg = $this->args[ $key ];
96
97	if ( ! is_array( $arg ) ) {
98	charitable_get_deprecated()->doing_it_wrong(
99	__METHOD__,
100	sprintf(
101	/* translators: %1$s: argument key; %2$s: setting */
102	_x( 'Attempting to set an argument setting for a non-array argument. Argument: %1$s; Setting: %2$s', 'argument key', 'charitable' ),
103	$key,
104	$setting
105	),
106	'1.6.0'
107	);
108
109	return $this;
110	}
111
112	$arg[ $setting ] = $value;
113	$this->args[ $key ] = $this->sanitize_arg( $key, $arg );
114
115	return $this;
116	}
117
118	/**
119	* Set a specific argument.
120	*
121	* @since 1.5.0
122	*
123	* @param string $key The field's key.
124	* @param mixed $value The field's value.
125	* @return Charitable_Field
126	*/
127	public function __set( $key, $value ) {
128	$this->args[ $key ] = $this->sanitize_arg( $key, $value );
129	return $this;
130	}
131
132	/**
133	* Get a particular argument value.
134	*
135	* @since 1.5.0
136	*
137	* @param string $key The field's key.
138	* @return mixed
139	*/
140	public function __get( $key ) {
141	return 'field' == $key ? $this->field : $this->args[ $key ];
142	}
143
144	/**
145	* Checks whether a particular argument is set.
146	*
147	* @since 1.6.0
148	*
149	* @param string $key The field's key.
150	* @return boolean
151	*/
152	public function __isset( $key ) {
153	return 'field' == $key \|\| array_key_exists( $key, $this->args );
154	}
155
156	/**
157	* Return the default arguments for this field type.
158	*
159	* @since 1.5.0
160	*
161	* @return array
162	*/
163	protected function get_defaults() {
164	return array();
165	}
166
167	/**
168	* Parse the passed arguments against a set of defaults and sanitize them.
169	*
170	* @since 1.5.0
171	*
172	* @param array $args Mixed set of field arguments.
173	* @return array Parsed arguments.
174	*/
175	protected function parse_args( $args ) {
176	$args = array_merge( $this->get_defaults(), $args );
177	$keys = array_keys( $args );
178	$sanitized = array_map( array( $this, 'sanitize_arg' ), $keys, $args );
179
180	return array_combine( $keys, $sanitized );
181	}
182
183	/**
184	* Sanitize the argument.
185	*
186	* @since 1.5.0
187	*
188	* @param string $key The argument's key.
189	* @param mixed $value The argument's value.
190	* @return mixed The argument value after being registered.
191	*/
192	protected function sanitize_arg( $key, $value ) {
193	$method = 'sanitize_' . $key;
194	if ( method_exists( $this, $method ) ) {
195	return $this->$method( $value );
196	}
197
198	return $value;
199	}
200
201	/**
202	* Sanitize a form argument.
203	*
204	* @since 1.6.0
205	*
206	* @param mixed $value The argument setting.
207	* @param array $defaults Default form args.
208	* @return boolean\|array
209	*/
210	protected function sanitize_form_arg( $value, $defaults = array() ) {
211	if ( ! $value ) {
212	return false;
213	}
214
215	if ( ! is_array( $value ) ) {
216	return $defaults;
217	}
218
219	return array_merge( $defaults, $value );
220	}
221
222	/**
223	* Sanitize the email tag.
224	*
225	* @since 1.6.0
226	*
227	* @param mixed $value The argument setting.
228	* @return false\|array
229	*/
230	public function sanitize_email_tag( $value ) {
231	if ( false === $value ) {
232	return $value;
233	}
234
235	$label = array_key_exists( 'label', $this->raw_args ) ? $this->raw_args['label'] : '';
236	$defaults = array(
237	'description' => $label,
238	'preview' => $label,
239	'tag' => $this->field,
240	);
241
242	if ( ! is_array( $value ) ) {
243	return $defaults;
244	}
245
246	return array_merge( $defaults, $value );
247	}
248	}
249
250	endif;
251