currency-functions.php — GiveWP – Donation Plugin and Fundraising Platform 2.18.0

give / includes / currency-functions.php

give / includes Last commit date

currency-functions.php

474 lines

1	<?php
2	/**
3	* Currency Functions
4	*
5	* @package Give
6	* @subpackage Functions
7	* @copyright Copyright (c) 2017, GiveWP
8	* @license https://opensource.org/licenses/gpl-license GNU Public License
9	* @since 1.8.17
10	*/
11
12	/**
13	* Get the set currency
14	*
15	* @since 1.0
16	* @since 1.8.15 Upgrade function to handle dynamic currency
17	*
18	* @param int $donation_or_form_id Donation or Form ID
19	* @param array\|object $args Additional data
20	*
21	* @return string The currency code
22	*/
23	function give_get_currency( $donation_or_form_id = null, $args = [] ) {
24
25	// Get currency from donation
26	if ( is_numeric( $donation_or_form_id ) && 'give_payment' === get_post_type( $donation_or_form_id ) ) {
27	$currency = give_get_meta( $donation_or_form_id, '_give_payment_currency', true );
28
29	if ( empty( $currency ) ) {
30	$currency = give_get_option( 'currency', 'USD' );
31	}
32	} else {
33	$currency = give_get_option( 'currency', 'USD' );
34	}
35
36	/**
37	* Filter the currency on basis of donation, form id, or additional data.
38	*
39	* @since 1.0
40	*/
41	return apply_filters( 'give_currency', $currency, $donation_or_form_id, $args );
42	}
43
44	/**
45	* Get the set currency position
46	*
47	* @since 1.3.6
48	*
49	* @return string The currency code
50	*/
51	function give_get_currency_position() {
52
53	$currency_pos = give_get_option( 'currency_position', 'before' );
54
55	return apply_filters( 'give_currency_position', $currency_pos );
56	}
57
58	/**
59	* Get Currencies List
60	*
61	* @since 1.8.17
62	*
63	* @return array $currencies A list of the available currencies
64	*/
65	function give_get_currencies_list() {
66	$currencies = Give_Cache_Setting::get_option( 'currencies' );
67
68	/**
69	* Filter the currencies
70	* Note: you can register new currency by using this filter
71	* array(
72	* 'admin_label' => '', // required
73	* 'symbol' => '', // required
74	* 'setting' => '' // required
75	* ....
76	* )
77	*
78	* @since 1.8.15
79	* @deprecated 2.10.4 Use give_register_currency filter hook to register new currency.
80	* Example code to register new currency:
81	*
82	* add_filter( 'give_register_currency', 'give_add_costarican_currency', 10, 1 );
83	* function give_add_costarican_currency( $currencies ) {
84	* $currencies['VND'] = array(
85	* 'admin_label' => __( 'Vietnamese đồng (₫)', 'give' ),
86	* 'symbol' => '₫',
87	* 'setting' => array(
88	* 'currency_position' => 'after',
89	* 'thousands_separator' => '.',
90	* 'decimal_separator' => ',',
91	* 'number_decimals' => 2,
92	* )
93	* );
94	*
95	* return $currencies;
96	* }
97	*
98	* @param array $currencies
99	*/
100	return (array) apply_filters( 'give_currencies', $currencies );
101	}
102
103	/**
104	* Get Currencies
105	*
106	* @since 1.0
107	*
108	* @param string $info Specify currency info
109	*
110	* @return array $currencies A list of the available currencies
111	*/
112	function give_get_currencies( $info = 'admin_label' ) {
113
114	$currencies = give_get_currencies_list();
115
116	// Backward compatibility: handle old way of currency registration.
117	// Backward compatibility: Return desired result.
118	if ( ! empty( $currencies ) ) {
119	foreach ( $currencies as $currency_code => $currency_setting ) {
120	if ( is_string( $currency_setting ) ) {
121	$currencies[ $currency_code ] = [
122	'admin_label' => $currency_setting,
123	];
124	}
125
126	$currencies[ $currency_code ] = wp_parse_args(
127	$currencies[ $currency_code ],
128	[
129	'admin_label' => '',
130	'symbol' => $currency_code,
131	'setting' => [],
132	]
133	);
134	}
135
136	if ( ! empty( $info ) && is_string( $info ) && 'all' !== $info ) {
137	$currencies = wp_list_pluck( $currencies, $info );
138	}
139	}
140
141	return $currencies;
142	}
143
144
145	/**
146	* Get all currency symbols
147	*
148	* @since 1.8.14
149	*
150	* @param bool $decode_currencies
151	*
152	* @return array
153	*/
154	function give_currency_symbols( $decode_currencies = false ) {
155	$currencies = give_get_currencies( 'symbol' );
156
157	if ( $decode_currencies ) {
158	array_walk(
159	$currencies,
160	function ( &$currency_symbol ) {
161	$currency_symbol = html_entity_decode( $currency_symbol, ENT_COMPAT, 'UTF-8' );
162	}
163	);
164	}
165
166	/**
167	* Filter the currency symbols
168	*
169	* @since 1.8.14
170	*
171	* @param array $currencies
172	*/
173	return apply_filters( 'give_currency_symbols', $currencies );
174	}
175
176
177	/**
178	* Give Currency Symbol
179	*
180	* Given a currency determine the symbol to use. If no currency given, site default is used. If no symbol is determine,
181	* the currency string is returned.
182	*
183	* @since 1.0
184	*
185	* @param string $currency The currency string.
186	* @param bool $decode_currency Option to HTML decode the currency symbol.
187	*
188	* @return string The symbol to use for the currency
189	*/
190	function give_currency_symbol( $currency = '', $decode_currency = false ) {
191
192	if ( empty( $currency ) ) {
193	$currency = give_get_currency();
194	}
195
196	$currencies = give_currency_symbols( $decode_currency );
197	$symbol = array_key_exists( $currency, $currencies ) ? $currencies[ $currency ] : $currency;
198
199	/**
200	* Filter the currency symbol
201	*
202	* @since 1.0
203	*
204	* @param string $symbol
205	* @param string $currency
206	*/
207	return apply_filters( 'give_currency_symbol', $symbol, $currency );
208	}
209
210
211	/**
212	* Get currency name.
213	*
214	* @since 1.8.8
215	*
216	* @param string $currency_code
217	*
218	* @return string
219	*/
220	function give_get_currency_name( $currency_code ) {
221	$currency_name = '';
222	$currency_names = give_get_currencies();
223
224	if ( $currency_code && array_key_exists( $currency_code, $currency_names ) ) {
225	$currency_name = explode( '(', $currency_names[ $currency_code ] );
226	$currency_name = trim( current( $currency_name ) );
227	}
228
229	/**
230	* Filter the currency name
231	*
232	* @since 1.8.8
233	*
234	* @param string $currency_name
235	* @param string $currency_code
236	*/
237	return apply_filters( 'give_currency_name', $currency_name, $currency_code );
238	}
239
240	/**
241	* Formats the currency displayed.
242	*
243	* @since 1.0
244	*
245	* @param string $price The donation amount.
246	* @param array $args It accepts 'currency_code', 'decode_currency' and 'form_id'.
247	*
248	* @return mixed\|string
249	*/
250	function give_currency_filter( $price = '', $args = [] ) {
251
252	// Get functions arguments.
253	$func_args = func_get_args();
254
255	// Backward compatibility: modify second param to array
256	if ( isset( $func_args[1] ) && is_string( $func_args[1] ) ) {
257	$args = [
258	'currency_code' => isset( $func_args[1] ) ? $func_args[1] : '',
259	'decode_currency' => isset( $func_args[2] ) ? $func_args[2] : false,
260	'form_id' => isset( $func_args[3] ) ? $func_args[3] : '',
261	];
262
263	give_doing_it_wrong( __FUNCTION__, 'Pass second argument as Array.' );
264	}
265
266	// Set default values.
267	$args = wp_parse_args(
268	$args,
269	[
270	'currency_code' => '',
271	'decode_currency' => false,
272	'form_id' => '',
273	]
274	);
275
276	if ( empty( $args['currency_code'] ) \|\| ! array_key_exists( (string) $args['currency_code'], give_get_currencies() ) ) {
277	$args['currency_code'] = give_get_currency( $args['form_id'] );
278	}
279
280	$args['position'] = give_get_option( 'currency_position', 'before' );
281
282	/**
283	* @since 2.16.0 Check for a numeric value before comparing to zero.
284	* @link https://www.php.net/manual/en/migration80.incompatible.php
285	*/
286	$negative = is_numeric( $price ) && $price < 0;
287
288	if ( $negative ) {
289	// Remove proceeding "-".
290	$price = substr( $price, 1 );
291	}
292
293	$args['symbol'] = give_currency_symbol( $args['currency_code'], $args['decode_currency'] );
294
295	switch ( $args['currency_code'] ) :
296	case 'GBP':
297	case 'BRL':
298	case 'EUR':
299	case 'USD':
300	case 'AUD':
301	case 'CAD':
302	case 'HKD':
303	case 'MXN':
304	case 'NZD':
305	case 'SGD':
306	case 'JPY':
307	case 'THB':
308	case 'INR':
309	case 'IDR':
310	case 'IRR':
311	case 'TRY':
312	case 'RUB':
313	case 'SEK':
314	case 'PLN':
315	case 'PHP':
316	case 'TWD':
317	case 'MYR':
318	case 'CZK':
319	case 'DKK':
320	case 'HUF':
321	case 'ILS':
322	case 'MAD':
323	case 'KRW':
324	case 'ZAR':
325	$formatted = ( 'before' === $args['position'] ? $args['symbol'] . $price : $price . $args['symbol'] );
326	break;
327	case 'NOK':
328	$formatted = ( 'before' === $args['position'] ? $args['symbol'] . ' ' . $price : $price . ' ' . $args['symbol'] );
329	break;
330	default:
331	$formatted = ( 'before' === $args['position'] ? $args['symbol'] . ' ' . $price : $price . ' ' . $args['symbol'] );
332	break;
333	endswitch;
334
335	/**
336	* Filter formatted amount
337	*
338	* @since 1.8.17
339	*/
340	$formatted = apply_filters( 'give_currency_filter', $formatted, $args, $price );
341
342	/**
343	* Filter formatted amount with currency
344	*
345	* Filter name depends upon current value of currency and currency position.
346	* For example :
347	* if currency is USD and currency position is before then
348	* filter name will be give_usd_currency_filter_before
349	*
350	* and if currency is USD and currency position is after then
351	* filter name will be give_usd_currency_filter_after
352	*/
353	$formatted = apply_filters(
354	'give_' . strtolower( $args['currency_code'] ) . "_currency_filter_{$args['position']}",
355	$formatted,
356	$args['currency_code'],
357	$price,
358	$args
359	);
360
361	if ( $negative ) {
362	// Prepend the minus sign before the currency sign.
363	$formatted = '-' . $formatted;
364	}
365
366	return $formatted;
367	}
368
369	/**
370	* This function is used to fetch list of zero based currencies.
371	*
372	* @since 2.3.0
373	*
374	* @return array
375	*/
376	function give_get_zero_based_currencies() {
377
378	$zero_based_currencies = [
379	'JPY', // Japanese Yen.
380	'KRW', // South Korean Won.
381	'CLP', // Chilean peso.
382	'ISK', // Icelandic króna.
383	'BIF', // Burundian franc.
384	'DJF', // Djiboutian franc.
385	'GNF', // Guinean franc.
386	'KHR', // Cambodian riel.
387	'KPW', // North Korean won.
388	'LAK', // Lao kip.
389	'LKR', // Sri Lankan rupee.
390	'MGA', // Malagasy ariary.
391	'MZN', // Mozambican metical.
392	'VUV', // Vanuatu vatu.
393	];
394
395	/**
396	* This filter hook can be used to update the list of zero based currencies.
397	*
398	* @since 2.3.0
399	*/
400	return apply_filters( 'give_get_zero_based_currencies', $zero_based_currencies );
401	}
402
403	/**
404	* Zero Decimal based Currency.
405	*
406	* @since 1.8.14
407	* @since 2.2.0 Modified list.
408	* @see https://github.com/impress-org/give/issues/2191
409	*
410	* @param string $currency Currency code
411	*
412	* @return bool
413	*/
414	function give_is_zero_based_currency( $currency = '' ) {
415
416	$zero_based_currency = give_get_zero_based_currencies();
417
418	// Set default currency.
419	if ( empty( $currency ) ) {
420	$currency = give_get_currency();
421	}
422
423	// Check for Zero Based Currency.
424	if ( in_array( $currency, $zero_based_currency ) ) {
425	return true;
426	}
427
428	return false;
429	}
430
431
432	/**
433	* Check if currency support right to left direction or not.
434	*
435	* @param string $currency
436	*
437	* @return bool
438	*/
439	function give_is_right_to_left_supported_currency( $currency = '' ) {
440	$zero_based_currency = apply_filters(
441	'give_right_to_left_supported_currency',
442	[
443	'IRR',
444	'RIAL',
445	'MAD',
446	'AED',
447	'BHD',
448	'KWD',
449	'OMR',
450	'SAR',
451	'TND', // https://en.wikipedia.org/wiki/Tunisian_dinar
452	'QAR', // https://en.wikipedia.org/wiki/Qatari_riyal
453	'LYD', // https://en.wikipedia.org/wiki/Libyan_dinar
454	'LBP', // https://en.wikipedia.org/wiki/Lebanese_pound
455	'IRT', // https://en.wikipedia.org/wiki/Iranian_toman
456	'IQD', // https://en.wikipedia.org/wiki/Iraqi_dinar
457	'DZD', // https://en.wikipedia.org/wiki/Algerian_dinar
458	'AFN', // https://en.wikipedia.org/wiki/Afghan_afghani
459	]
460	);
461
462	// Set default currency.
463	if ( empty( $currency ) ) {
464	$currency = give_get_currency();
465	}
466
467	// Check for Zero Based Currency.
468	if ( in_array( $currency, $zero_based_currency ) ) {
469	return true;
470	}
471
472	return false;
473	}
474