charitable / includes / emails / fields / class-charitable-email-fields.php

class-charitable-email-fields.php in Charitable – Donation & Fundraising Platform (Donation Forms, Recurring Donations & Fundraising Campaigns) 1.8.13, at includes/emails/fields/class-charitable-email-fields.php

277 lines 7.1 KB

Raw Download Zip

1	<?php
2	/**
3	* Email Fields class.
4	*
5	* @package Charitable/Classes/Charitable_Email_Fields
6	* @author David Bisset
7	* @copyright Copyright (c) 2023, WP Charitable LLC
8	* @license http://opensource.org/licenses/gpl-2.0.php GNU Public License
9	* @since 1.5.0
10	* @version 1.5.0
11	*/
12
13	// Exit if accessed directly.
14	if ( ! defined( 'ABSPATH' ) ) {
15	exit;
16	}
17
18	if ( ! class_exists( 'Charitable_Email_Fields' ) ) :
19
20	/**
21	* Charitable_Email_Fields class.
22	*
23	* @since 1.5.0
24	*/
25	class Charitable_Email_Fields {
26
27	/**
28	* Email object.
29	*
30	* @since 1.5.0
31	*
32	* @var Charitable_Email
33	*/
34	private $email;
35
36	/**
37	* Whether this is an email preview.
38	*
39	* @since 1.5.0
40	*
41	* @var boolean
42	*/
43	private $preview;
44
45	/**
46	* An array of registered fields that are available for this email.
47	*
48	* @since 1.5.0
49	*
50	* @var array
51	*/
52	private $fields;
53
54	/**
55	* Set up class instance.
56	*
57	* @since 1.5.0
58	*
59	* @param Charitable_Email $email The email object.
60	* @param boolean $preview Whether this is an email preview.
61	*/
62	public function __construct( Charitable_Email $email, $preview = false ) {
63	$this->email = $email;
64	$this->preview = $preview;
65	$this->fields = $this->init_fields();
66	}
67
68	/**
69	* Returns whether this is an email preview.
70	*
71	* @since 1.5.0
72	*
73	* @return boolean
74	*/
75	public function is_preview() {
76	return $this->preview;
77	}
78
79	/**
80	* Get the fields that apply to the current email.
81	*
82	* @since 1.5.0
83	*
84	* @return array
85	*/
86	public function init_fields() {
87	$site_name = get_option( 'blogname' );
88	$home_url = home_url();
89	$fields = array(
90	'site_name' => array(
91	'description' => __( 'Your website title', 'charitable' ),
92	'value' => $site_name,
93	'preview' => $site_name,
94	),
95	'site_url' => array(
96	'description' => __( 'Your website URL', 'charitable' ),
97	'value' => $home_url,
98	'preview' => $home_url,
99	),
100	);
101
102	$object_types = $this->email->get_object_types();
103
104	if ( ! empty( $object_types ) ) {
105	$fields = array_merge( $fields, array_reduce( $object_types, array( $this, 'get_object_type_fields' ) ) );
106	}
107
108	$fields = array_merge( $fields, $this->email->email_fields() );
109
110	/**
111	* For backwards compatibility reasons, we still set hook the email's
112	* deprecated methods for adding fields. Some extensions define their
113	* own child versions of these methods, and expect them to be hooked
114	* automatically.
115	*
116	* This will be removed in or after Charitable 1.8.
117	*/
118	add_filter( 'charitable_email_content_fields', array( $this->email, 'add_donation_content_fields' ), 10, 2 );
119	add_filter( 'charitable_email_preview_content_fields', array( $this->email, 'add_preview_donation_content_fields' ), 10, 2 );
120	add_filter( 'charitable_email_content_fields', array( $this->email, 'add_campaign_content_fields' ), 10, 2 );
121	add_filter( 'charitable_email_preview_content_fields', array( $this->email, 'add_preview_campaign_content_fields' ), 10, 2 );
122
123	/**
124	* Filter the email content fields.
125	*
126	* @since 1.0.0
127	*
128	* @param array $fields Registered fields.
129	* @param Charitable_Email $email Instance of `Charitable_Email` type.
130	*/
131	$fields = apply_filters( 'charitable_email_content_fields', $fields, $this->email );
132
133	/**
134	* Finally, if we are previewing the email, parse any preview fields added
135	* through the `charitable_email_preview_content_fields` filter, which is
136	* deprecated as of 1.5.0.
137	*/
138	if ( $this->preview ) {
139	$fields = $this->parse_preview_fields( $fields );
140	}
141
142	return $fields;
143	}
144
145	/**
146	* Return the fields array.
147	*
148	* @since 1.5.0
149	*
150	* @return array
151	*/
152	public function get_fields() {
153	return $this->fields;
154	}
155
156	/**
157	* Get the value for a particular email field.
158	*
159	* @since 1.5.0
160	*
161	* @param string $field The field.
162	* @param array $args Mixed arguments.
163	* @return string
164	*/
165	public function get_field_value( $field, $args ) {
166	$value = '';
167
168	/* Get the field value if the field is registered and has a 'value' or 'callback' set. */
169	if ( array_key_exists( $field, $this->fields ) ) {
170	$value = $this->get_field_value_from_field_details( $this->fields[ $field ], $args );
171	}
172
173	/**
174	* Filter the returned value.
175	*
176	* @since 1.0.0
177	*
178	* @param string $value The field value.
179	* @param array $args Mixed arguments.
180	* @param Charitable_Email $email The Email object.
181	*/
182	return apply_filters( 'charitable_email_content_field_value_' . $field, $value, $args, $this->email );
183	}
184
185	/**
186	* Return a value for the field from its details.
187	*
188	* @since 1.5.0
189	*
190	* @param array $field_details Email field definition.
191	* @param array $args Mixed shortcode arguments.
192	* @return string
193	*/
194	private function get_field_value_from_field_details( array $field_details, array $args ) {
195	if ( array_key_exists( 'value', $field_details ) ) {
196	return $field_details['value'];
197	}
198
199	if ( $this->preview ) {
200	return array_key_exists( 'preview', $field_details ) ? $field_details['preview'] : '';
201	}
202
203	if ( array_key_exists( 'callback', $field_details ) ) {
204	return call_user_func( $field_details['callback'], '', $args, $this->email );
205	}
206
207	/* If we still don't have a value, return an empty string. */
208	return '';
209	}
210
211	/**
212	* Return the fields for a particular object type.
213	*
214	* @since 1.5.0
215	*
216	* @param null\|array $fields Object type fields so far.
217	* @param string $object_type Object type to add.
218	* @return array
219	*/
220	private function get_object_type_fields( $fields, $object_type ) {
221	if ( is_null( $fields ) ) {
222	$fields = array();
223	}
224
225	$words = str_replace( '_', ' ', $object_type );
226	$class = 'Charitable_Email_Fields_' . str_replace( ' ', '_', ucwords( $words ) );
227
228	if ( ! class_exists( $class ) ) {
229	return $fields;
230	}
231
232	$object = new $class( $this->email, $this->preview );
233
234	if ( ! is_a( $object, 'Charitable_Email_Fields_Interface' ) ) {
235	return $fields;
236	}
237
238	return array_merge( $fields, $object->get_fields() );
239	}
240
241	/**
242	* Parse preview fields registered through charitable_email_preview_content_fields hook.
243	*
244	* @since 1.5.0
245	*
246	* @param array $fields Registered email fields.
247	* @return array
248	*/
249	private function parse_preview_fields( $fields ) {
250	/**
251	* Filter preview values for content fields. This filter is deprecated,
252	* as preview values can be simply defined when setting up the content
253	* field.
254	*
255	* @deprecated
256	*
257	* @since 1.0.0
258	*
259	* @param array $fields Fields with their preview values. Single dimensional key => value array.
260	* @param Charitable_Email $email The instance of `Charitable_Email`.
261	*/
262	$preview_values = apply_filters( 'charitable_email_preview_content_fields', array(), $this->email );
263
264	foreach ( $preview_values as $key => $value ) {
265	if ( ! array_key_exists( $key, $fields ) ) {
266	continue;
267	}
268
269	$fields[ $key ]['preview'] = $value;
270	}
271
272	return $fields;
273	}
274	}
275
276	endif;
277