gamipress / includes / functions / points-types.php

points-types.php in GamiPress – Gamification plugin to reward points, badges & ranks in WordPress, now with AI trunk, at includes/functions/points-types.php

459 lines 14.9 KB

Raw Download Zip

1	<?php
2	/**
3	* Points Types Functions
4	*
5	* @package GamiPress\Points_Types_Functions
6	* @author GamiPress <contact@gamipress.com>, Ruben Garcia <rubengcdev@gmail.com>
7	* @since 1.4.6
8	*/
9	// Exit if accessed directly
10	if( !defined( 'ABSPATH' ) ) exit;
11
12	/**
13	* Get registered points types
14	*
15	* Returns a multidimensional array of slug, single name and plural name for all points types.
16	*
17	* @since 1.0.0
18	*
19	* @return array An array of our registered points types
20	*/
21	function gamipress_get_points_types() {
22
23	return GamiPress()->points_types;
24
25	}
26
27	/**
28	* Get registered points type slugs
29	*
30	* @since 1.0.0
31	*
32	* @return array An array of all our registered points type slugs (empty array if none)
33	*/
34	function gamipress_get_points_types_slugs() {
35
36	// Assume we have no registered points types
37	$points_type_slugs = array();
38
39	// If we do have any points types, loop through each and add their slug to our array
40	foreach ( GamiPress()->points_types as $slug => $data ) {
41	$points_type_slugs[] = $slug;
42	}
43
44	// Finally, return our data
45	return $points_type_slugs;
46
47	}
48
49	/**
50	* Get the desired points type
51	*
52	* @since 1.4.6
53	*
54	* @param string\|int\|WP_Post $points_type The points type
55	*
56	* @return array\|false The points type object if is registered, if not return false
57	*/
58	function gamipress_get_points_type( $points_type ) {
59
60	// Check if is an WP_Post
61	if( $points_type instanceof WP_Post ) {
62
63	if( $points_type->post_type === 'points-type' ) {
64	// If WP_Post given is an points type post, try to find it by ID
65	$points_type = $points_type->ID;
66	} else {
67	// Else the WP_Post given is an points post, so the points type is on post_type field
68	$points_type = $points_type->post_type;
69	}
70
71	}
72
73	if( gettype( $points_type ) === 'string' && isset( GamiPress()->points_types[$points_type] ) ) {
74	return GamiPress()->points_types[$points_type];
75	}
76
77	if( is_numeric( $points_type ) ) {
78	return gamipress_get_points_type_by_id( $points_type );
79	}
80
81	// Point type can not be found
82	return false;
83
84	}
85
86	/**
87	* Get the desired points type by ID
88	*
89	* @since 1.4.6
90	*
91	* @param int $points_type_id The points type ID
92	*
93	* @return array\|false The points type object if is registered, if not return false
94	*/
95	function gamipress_get_points_type_by_id( $points_type_id ) {
96
97	$points_type_id = absint( $points_type_id );
98
99	// Bail if wrong ID given
100	if( $points_type_id === 0 ) {
101	return false;
102	}
103
104	// Loop all registered points types to find what matches the given ID
105	foreach ( GamiPress()->points_types as $slug => $data ) {
106	if( absint( $data['ID'] ) === $points_type_id ) {
107	return $data;
108	}
109	}
110
111	// Point type can not be found
112	return false;
113
114	}
115
116	/**
117	* Get the desired points type ID
118	*
119	* @since 1.4.6
120	*
121	* @param string\|int\|WP_Post $points_type The points type
122	*
123	* @return int\|false The points type ID if is registered, if not return false
124	*/
125	function gamipress_get_points_type_id( $points_type ) {
126
127	$points_type = gamipress_get_points_type( $points_type );
128
129	if( $points_type ) {
130	return $points_type['ID'];
131	}
132
133	return false;
134
135	}
136
137	/**
138	* Get the desired points type singular name
139	*
140	* @since 1.4.6
141	*
142	* @param string\|int\|WP_Post $points_type The points type
143	* @param bool $force_return If set to true, will return "Point" if points type is not registered or singular name is empty
144	*
145	* @return array\|false The points type singular name if is registered, if not return false
146	*/
147	function gamipress_get_points_type_singular( $points_type, $force_return = false ) {
148
149	$points_type = gamipress_get_points_type( $points_type );
150
151	if( $points_type ) {
152
153	// If force return and points type singular name is empty, return "Point" as singular name
154	if( $force_return && empty( $points_type['singular_name'] ) ) {
155	return __( 'Point', 'gamipress' );
156	}
157
158	// Return the points type singular name
159	return $points_type['singular_name'];
160	}
161
162	return $force_return ? __( 'Point', 'gamipress' ) : false;
163
164	}
165
166	/**
167	* Get the desired points type plural name
168	*
169	* @since 1.4.6
170	*
171	* @param string\|int\|WP_Post $points_type The points type
172	* @param bool $force_return If set to true, will return "Points" if points type is not registered or plural name is empty
173	*
174	* @return array\|false The points type plural name if is registered, if not return false
175	*/
176	function gamipress_get_points_type_plural( $points_type, $force_return = false ) {
177
178	$points_type = gamipress_get_points_type( $points_type );
179
180	if( $points_type ) {
181
182	// If force return and points type plural name is empty, return "Points" as plural name
183	if( $force_return && empty( $points_type['plural_name'] ) ) {
184	return __( 'Points', 'gamipress' );
185	}
186
187	// Return the points type singular name
188	return $points_type['plural_name'];
189	}
190
191	return $force_return ? __( 'Points', 'gamipress' ) : false;
192
193	}
194
195	/**
196	* Return the singular or plural form based on the supplied amount
197	*
198	* @since 1.5.1
199	*
200	* @param int $amount The desired amount
201	* @param string\|int\|WP_Post $points_type The points type
202	* @param bool $force_return If set to true, will return "Point" or "Points" if points type is not registered or plural name is empty
203	*
204	* @return string The points type singular or plural based on the supplied amount
205	*/
206	function gamipress_get_points_amount_label( $amount, $points_type, $force_return = false ) {
207
208	// Get the singular or plural label based on points amount
209	$label = _n( gamipress_get_points_type_singular( $points_type, $force_return ), gamipress_get_points_type_plural( $points_type, $force_return ), $amount, 'gamipress' );
210
211	/**
212	* Points type label position (default after)
213	*
214	* @since 1.5.1
215	*
216	* @param string $label The points type singular or plural label
217	* @param int $amount The desired amount
218	* @param string\|int\|WP_Post $points_type The points type
219	* @param bool $force_return If set to true, will return "Point" or "Points" if points type is not registered or plural name is empty
220	*/
221	return apply_filters( 'gamipress_get_points_amount_label', $label, $amount, $points_type, $force_return );
222
223	}
224
225	/**
226	* Get the desired points type label position
227	*
228	* @since 1.5.1
229	*
230	* @param string\|int\|WP_Post $points_type
231	*
232	* @return string The points type plural name if is registered, if not return false
233	*/
234	function gamipress_get_points_type_label_position( $points_type ) {
235
236	$label_position = 'after';
237
238	$points_type_id = gamipress_get_points_type_id( $points_type );
239
240	if( $points_type_id ) {
241
242	// Get the points type label position (after or before)
243	$label_position = gamipress_get_post_meta( $points_type_id, '_gamipress_label_position' );
244
245	if( $label_position === '' ) {
246	$label_position = 'after';
247	}
248	}
249
250	/**
251	* Points type label position (default after)
252	*
253	* @since 1.5.1
254	*
255	* @param string $label_position The points type label position (after or before)
256	* @param string\|int\|WP_Post $points_type The points type given
257	*/
258	return apply_filters( 'gamipress_get_points_type_label_position', $label_position, $points_type );
259
260	}
261
262	/**
263	* Get the desired points type thousands separator
264	*
265	* @since 1.5.1
266	*
267	* @param string\|int\|WP_Post $points_type
268	*
269	* @return string The points type plural name if is registered, if not return false
270	*/
271	function gamipress_get_points_type_thousands_separator( $points_type ) {
272
273	$thousands_separator = '';
274
275	$points_type_id = gamipress_get_points_type_id( $points_type );
276
277	if( $points_type_id ) {
278
279	// Get the points type thousands separator
280	$thousands_separator = gamipress_get_post_meta( $points_type_id, '_gamipress_thousands_separator' );
281	}
282
283	/**
284	* Points type thousands separator
285	*
286	* @since 1.5.1
287	*
288	* @param string $thousands_separator The points type thousands separator
289	* @param string\|int\|WP_Post $points_type The points type given
290	*/
291	return apply_filters( 'gamipress_get_points_type_thousands_separator', $thousands_separator, $points_type );
292
293	}
294
295	/**
296	* Get the desired points type HTML display
297	*
298	* @since 7.8.4
299	*
300	* @param string\|int\|WP_Post $points_type
301	*
302	* @return string The points type plural name if is registered, if not return false
303	*/
304	function gamipress_get_points_type_html_display( $points_type ) {
305
306	$html_display = 'label_image_after';
307
308	$points_type_id = gamipress_get_points_type_id( $points_type );
309
310	if( $points_type_id ) {
311
312	// Get the points type HTML display
313	$html_display = gamipress_get_post_meta( $points_type_id, '_gamipress_html_display' );
314
315	if( $html_display === '' ) {
316	$html_display = 'label_image_after';
317	}
318	}
319
320	/**
321	* Points type HTML display (default label_image_after)
322	*
323	* @since 7.8.4
324	*
325	* @param string $html_display The points type HTML display
326	* @param string\|int\|WP_Post $points_type The points type given
327	*/
328	return apply_filters( 'gamipress_get_points_type_html_display', $html_display, $points_type );
329
330	}
331
332
333	/**
334	* Format an amount based on a points type to append the points type label
335	*
336	* @since 1.5.1
337	*
338	* @param int $amount The amount to be formatted
339	* @param string\|int\|WP_Post $points_type The points type
340	* @param bool $html To meet if HTML is allowed and format with the HTML format
341	*
342	* @return string The amount of points formatted using the points type plural or singular
343	*/
344	function gamipress_format_points( $amount, $points_type, $html = true ) {
345
346	$amount = floatval( $amount );
347
348	// Get the singular or plural label based on points amount
349	$label = gamipress_get_points_amount_label( $amount, $points_type, true );
350	$formatted_amount = gamipress_format_amount( $amount, $points_type );
351
352	$label_position = 'after';
353	$html_display = 'label_image_after';
354
355	if( $html ) {
356	// Apply points type settings for HTML
357	$html_display = gamipress_get_points_type_html_display( $points_type );
358	$image = '';
359
360	// Check if format uses the points type image
361	if( strpos( $html_display, 'image' ) !== false ) {
362	$image = gamipress_get_points_type_thumbnail( $points_type, 'gamipress-points', 'gamipress-points-thumbnail gamipress-points-thumbnail-inline' );
363
364	if( $image === '' ) {
365	// If desired format wants to use an image but points type does not have one assigned, fallback to label only format
366	if( strpos( $html_display, 'before' ) !== false ) {
367	$html_display = 'label_before';
368	} else {
369	$html_display = 'label_after';
370	}
371	}
372
373	}
374
375	switch( $html_display ) {
376	case 'label_image_after':
377	$formatted_amount = $formatted_amount . ' ' . $image . ' ' . $label;
378	break;
379	case 'image_after':
380	$formatted_amount = $formatted_amount . ' ' . $image;
381	break;
382	case 'label_after':
383	$formatted_amount = $formatted_amount . ' ' . $label;
384	break;
385	case 'label_image_before':
386	$formatted_amount = $image . ' ' . $label . ' ' . $formatted_amount;
387	break;
388	case 'image_before':
389	$formatted_amount = $image . ' ' . $formatted_amount;
390	break;
391	case 'label_before':
392	$formatted_amount = $label . ' ' . $formatted_amount;
393	break;
394	}
395	} else {
396	// Apply points type settings of label position (after or before)
397	$label_position = gamipress_get_points_type_label_position( $points_type );
398
399	if( $label_position === 'before' ) {
400	$formatted_amount = $label . ' ' . $formatted_amount;
401	} else {
402	// Make default after the default label position
403	$formatted_amount .= ' ' . $label;
404	}
405	}
406
407
408
409	/**
410	* Format points filter
411	*
412	* @since 1.5.1
413	*
414	* @param string $formatted_amount The formatted amount (with label)
415	* @param int $amount The original amount (without any format)
416	* @param string\|int\|WP_Post $points_type The points type given
417	* @param string $label_position The points type label position (after or before)
418	*/
419	return apply_filters( 'gamipress_format_points', $formatted_amount, $amount, $points_type, $html, $label_position, $html_display );
420
421	}
422
423	/**
424	* Format an amount based on settings
425	*
426	* @since 1.5.1
427	*
428	* @param int $amount The amount to be formatted
429	* @param string\|int\|WP_Post $points_type The points type
430	*
431	* @return string The amount formatted
432	*/
433	function gamipress_format_amount( $amount, $points_type ) {
434
435	$amount = floatval( $amount );
436
437	// Setup the formatting vars
438	$decimals = 0;
439	$decimals_sep = '';
440	$thousands_sep = gamipress_get_points_type_thousands_separator( $points_type );
441
442	// Format the amount
443	$formatted_amount = number_format( $amount, $decimals, $decimals_sep, $thousands_sep );
444
445	/**
446	* Format amount filter
447	*
448	* @since 1.5.1
449	*
450	* @param string $formatted_amount The formatted amount
451	* @param int $amount The original amount (without any format)
452	* @param string\|int\|WP_Post $points_type The points type given
453	* @param int $decimals Decimals to apply in format
454	* @param string $decimals_sep Decimals separator to apply in format
455	* @param string $thousands_sep Thousands separator to apply in format
456	*/
457	return apply_filters( 'gamipress_format_amount', $formatted_amount, $amount, $points_type, $decimals, $decimals_sep, $thousands_sep );
458
459	}