f0792b1c932a11dd57ac63e46b9cbcc04839ef57
[moodle.git] / payment / classes / helper.php
1 <?php
2 // This file is part of Moodle - http://moodle.org/
3 //
4 // Moodle is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
8 //
9 // Moodle is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 // GNU General Public License for more details.
13 //
14 // You should have received a copy of the GNU General Public License
15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
17 /**
18  * Contains helper class for the payment subsystem.
19  *
20  * @package    core_payment
21  * @copyright  2019 Shamim Rezaie <shamim@moodle.com>
22  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23  */
25 namespace core_payment;
27 use core_payment\event\account_created;
28 use core_payment\event\account_deleted;
29 use core_payment\event\account_updated;
31 /**
32  * Helper class for the payment subsystem.
33  *
34  * @copyright  2019 Shamim Rezaie <shamim@moodle.com>
35  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
36  */
37 class helper {
39     /**
40      * Returns an accumulated list of supported currencies by all payment gateways.
41      *
42      * @return string[] An array of the currency codes in the three-character ISO-4217 format
43      */
44     public static function get_supported_currencies(): array {
45         $currencies = [];
47         $plugins = \core_plugin_manager::instance()->get_enabled_plugins('paygw');
48         foreach ($plugins as $plugin) {
49             /** @var \paygw_paypal\gateway $classname */
50             $classname = '\paygw_' . $plugin . '\gateway';
52             $currencies += component_class_callback($classname, 'get_supported_currencies', [], []);
53         }
55         $currencies = array_unique($currencies);
57         return $currencies;
58     }
60     /**
61      * Returns the list of gateways that can process payments in the given currency.
62      *
63      * @param string $component
64      * @param string $paymentarea
65      * @param int $itemid
66      * @return string[]
67      */
68     public static function get_available_gateways(string $component, string $paymentarea, int $itemid): array {
69         $gateways = [];
71         $payable = static::get_payable($component, $paymentarea, $itemid);
72         $account = new account($payable->get_account_id());
74         if (!$account->get('id') || !$account->get('enabled')) {
75             return $gateways;
76         }
78         $currency = $payable->get_currency();
79         foreach ($account->get_gateways() as $plugin => $gateway) {
80             if (!$gateway->get('enabled')) {
81                 continue;
82             }
83             /** @var gateway $classname */
84             $classname = '\paygw_' . $plugin . '\gateway';
86             $currencies = component_class_callback($classname, 'get_supported_currencies', [], []);
87             if (in_array($currency, $currencies)) {
88                 $gateways[] = $plugin;
89             }
90         }
92         return $gateways;
93     }
95     /**
96      * Rounds the cost based on the currency fractional digits, can also apply surcharge
97      *
98      * @param float $amount amount in the currency units
99      * @param string $currency currency, used for calculating the number of fractional digits
100      * @param float $surcharge surcharge in percents
101      * @return float
102      */
103     public static function get_rounded_cost(float $amount, string $currency, float $surcharge = 0): float {
104         $amount = $amount * (100 + $surcharge) / 100;
106         $locale = get_string('localecldr', 'langconfig');
107         $fmt = \NumberFormatter::create($locale, \NumberFormatter::CURRENCY);
108         $localisedcost = numfmt_format_currency($fmt, $amount, $currency);
110         return numfmt_parse_currency($fmt, $localisedcost, $currency);
111     }
113     /**
114      * Returns human-readable amount with correct number of fractional digits and currency indicator, can also apply surcharge
115      *
116      * @param float $amount amount in the currency units
117      * @param string $currency The currency
118      * @param float $surcharge surcharge in percents
119      * @return string
120      */
121     public static function get_cost_as_string(float $amount, string $currency, float $surcharge = 0): string {
122         $amount = $amount * (100 + $surcharge) / 100;
124         $locale = get_string('localecldr', 'langconfig');
125         $fmt = \NumberFormatter::create($locale, \NumberFormatter::CURRENCY);
126         $localisedcost = numfmt_format_currency($fmt, $amount, $currency);
128         return $localisedcost;
129     }
131     /**
132      * Returns the percentage of surcharge that is applied when using a gateway
133      *
134      * @param string $gateway Name of the gateway
135      * @return float
136      */
137     public static function get_gateway_surcharge(string $gateway): float {
138         return (float)get_config('paygw_' . $gateway, 'surcharge');
139     }
141     /**
142      * Returns the attributes to place on a pay button.
143      *
144      * @param string $component Name of the component that the itemid belongs to
145      * @param string $paymentarea
146      * @param int $itemid An internal identifier that is used by the component
147      * @param string $description Description of the payment
148      * @return array
149      */
150     public static function gateways_modal_link_params(string $component, string $paymentarea, int $itemid,
151             string $description): array {
153         $payable = static::get_payable($component, $paymentarea, $itemid);
155         return [
156             'id' => 'gateways-modal-trigger',
157             'role' => 'button',
158             'data-action' => 'core_payment/triggerPayment',
159             'data-component' => $component,
160             'data-paymentarea' => $paymentarea,
161             'data-itemid' => $itemid,
162             'data-cost' => static::get_cost_as_string($payable->get_amount(), $payable->get_currency()),
163             'data-description' => $description,
164         ];
165     }
167     /**
168      * @param string $component
169      * @return string
170      * @throws \coding_exception
171      */
172     private static function get_service_provider_classname(string $component) {
173         $providerclass = "$component\\payment\\service_provider";
175         if (class_exists($providerclass)) {
176             $rc = new \ReflectionClass($providerclass);
177             if ($rc->implementsInterface(local\callback\service_provider::class)) {
178                 return $providerclass;
179             }
180         }
182         throw new \coding_exception("$component does not have an eligible implementation of payment service_provider.");
183     }
185     /**
186      * Asks the payable from the related component.
187      *
188      * @param string $component Name of the component that the itemid belongs to
189      * @param string $paymentarea
190      * @param int $itemid An internal identifier that is used by the component
191      * @return local\entities\payable
192      */
193     public static function get_payable(string $component, string $paymentarea, int $itemid): local\entities\payable {
194         $providerclass = static::get_service_provider_classname($component);
196         return component_class_callback($providerclass, 'get_payable', [$paymentarea, $itemid]);
197     }
199     /**
200      * Returns the gateway configuration for given component and gateway
201      *
202      * @param string $component
203      * @param string $paymentarea
204      * @param int $itemid
205      * @param string $gatewayname
206      * @return array
207      * @throws \moodle_exception
208      */
209     public static function get_gateway_configuration(string $component, string $paymentarea, int $itemid,
210             string $gatewayname): array {
211         $payable = self::get_payable($component, $paymentarea, $itemid);
212         $gateway = null;
213         $account = new account($payable->get_account_id());
214         if ($account && $account->get('enabled')) {
215             $gateway = $account->get_gateways()[$gatewayname] ?? null;
216         }
217         if (!$gateway) {
218             throw new \moodle_exception('gatewaynotfound', 'payment');
219         }
220         return $gateway->get_configuration();
221     }
223     /**
224      * Delivers what the user paid for.
225      *
226      * @uses \core_payment\local\callback\service_provider::deliver_order()
227      *
228      * @param string $component Name of the component that the itemid belongs to
229      * @param string $paymentarea
230      * @param int $itemid An internal identifier that is used by the component
231      * @param int $paymentid payment id as inserted into the 'payments' table, if needed for reference
232      * @param int $userid The userid the order is going to deliver to
233      * @return bool Whether successful or not
234      */
235     public static function deliver_order(string $component, string $paymentarea, int $itemid, int $paymentid, int $userid): bool {
236         $providerclass = static::get_service_provider_classname($component);
237         $result = component_class_callback($providerclass, 'deliver_order', [$paymentarea, $itemid, $paymentid, $userid]);
239         return $result;
240     }
242     /**
243      * Stores essential information about the payment and returns the "id" field of the payment record in DB.
244      * Each payment gateway may then store the additional information their way.
245      *
246      * @param int $accountid Account id
247      * @param string $component Name of the component that the itemid belongs to
248      * @param string $paymentarea
249      * @param int $itemid An internal identifier that is used by the component
250      * @param int $userid Id of the user who is paying
251      * @param float $amount Amount of payment
252      * @param string $currency Currency of payment
253      * @param string $gateway The gateway that is used for the payment
254      * @return int
255      */
256     public static function save_payment(int $accountid, string $component, string $paymentarea, int $itemid, int $userid,
257             float $amount, string $currency, string $gateway): int {
258         global $DB;
260         $record = new \stdClass();
261         $record->component = $component;
262         $record->paymentarea = $paymentarea;
263         $record->itemid = $itemid;
264         $record->userid = $userid;
265         $record->amount = $amount;
266         $record->currency = $currency;
267         $record->gateway = $gateway;
268         $record->accountid = $accountid;
269         $record->timecreated = $record->timemodified = time();
271         $id = $DB->insert_record('payments', $record);
273         return $id;
274     }
276     /**
277      * This functions adds the settings that are common for all payment gateways.
278      *
279      * @param \admin_settingpage $settings The settings object
280      * @param string $gateway The gateway name prefixed with paygw_
281      */
282     public static function add_common_gateway_settings(\admin_settingpage $settings, string $gateway): void {
283         $settings->add(new \admin_setting_configtext($gateway . '/surcharge', get_string('surcharge', 'core_payment'),
284                 get_string('surcharge_desc', 'core_payment'), 0, PARAM_INT));
286     }
288     /**
289      * Save a new or edited payment account (used in management interface)
290      *
291      * @param \stdClass $data
292      * @return account
293      */
294     public static function save_payment_account(\stdClass $data): account {
296         if (empty($data->id)) {
297             $account = new account(0, $data);
298             $account->save();
299             account_created::create_from_account($account)->trigger();
300         } else {
301             $account = new account($data->id);
302             $account->from_record($data);
303             $account->save();
304             account_updated::create_from_account($account)->trigger();
305         }
307         return $account;
308     }
310     /**
311      * Delete a payment account (used in management interface)
312      *
313      * @param account $account
314      */
315     public static function delete_payment_account(account $account): void {
316         global $DB;
317         if ($DB->record_exists('payments', ['accountid' => $account->get('id')])) {
318             $account->set('archived', 1);
319             $account->save();
320             account_updated::create_from_account($account, ['archived' => 1])->trigger();
321             return;
322         }
324         foreach ($account->get_gateways(false) as $gateway) {
325             if ($gateway->get('id')) {
326                 $gateway->delete();
327             }
328         }
329         $event = account_deleted::create_from_account($account);
330         $account->delete();
331         $event->trigger();
332     }
334     /**
335      * Restore archived payment account (used in management interface)
336      *
337      * @param account $account
338      */
339     public static function restore_payment_account(account $account): void {
340         $account->set('archived', 0);
341         $account->save();
342         account_updated::create_from_account($account, ['restored' => 1])->trigger();
343     }
345     /**
346      * Save a payment gateway linked to an existing account (used in management interface)
347      *
348      * @param \stdClass $data
349      * @return account_gateway
350      */
351     public static function save_payment_gateway(\stdClass $data): account_gateway {
352         if (empty($data->id)) {
353             $records = account_gateway::get_records(['accountid' => $data->accountid, 'gateway' => $data->gateway]);
354             if ($records) {
355                 $gateway = reset($records);
356             } else {
357                 $gateway = new account_gateway(0, $data);
358             }
359         } else {
360             $gateway = new account_gateway($data->id);
361         }
362         unset($data->accountid, $data->gateway, $data->id);
363         $gateway->from_record($data);
365         $account = $gateway->get_account();
366         $gateway->save();
367         account_updated::create_from_account($account)->trigger();
368         return $gateway;
369     }
371     /**
372      * Returns the list of payment accounts in the given context (used in management interface)
373      *
374      * @param \context $context
375      * @return account[]
376      */
377     public static function get_payment_accounts_to_manage(\context $context, bool $showarchived = false): array {
378         $records = account::get_records(['contextid' => $context->id] + ($showarchived ? [] : ['archived' => 0]));
379         \core_collator::asort_objects_by_method($records, 'get_formatted_name');
380         return $records;
381     }
383     /**
384      * Get list of accounts available in the given context
385      *
386      * @param \context $context
387      * @return array
388      */
389     public static function get_payment_accounts_menu(\context $context): array {
390         global $DB;
391         [$sql, $params] = $DB->get_in_or_equal($context->get_parent_context_ids(true));
392         $accounts = array_filter(account::get_records_select('contextid '.$sql, $params), function($account) {
393             return $account->is_available() && !$account->get('archived');
394         });
395         return array_map(function($account) {
396             return $account->get_formatted_name();
397         }, $accounts);
398     }