MDL-69166 core_payment: Add paymentarea to the payment subsystem
[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 defined('MOODLE_INTERNAL') || die();
33 /**
34  * Helper class for the payment subsystem.
35  *
36  * @copyright  2019 Shamim Rezaie <shamim@moodle.com>
37  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
38  */
39 class helper {
41     /**
42      * Returns an accumulated list of supported currencies by all payment gateways.
43      *
44      * @return string[] An array of the currency codes in the three-character ISO-4217 format
45      */
46     public static function get_supported_currencies(): array {
47         $currencies = [];
49         $plugins = \core_plugin_manager::instance()->get_enabled_plugins('pg');
50         foreach ($plugins as $plugin) {
51             /** @var \pg_paypal\gateway $classname */
52             $classname = '\pg_' . $plugin . '\gateway';
54             $currencies += component_class_callback($classname, 'get_supported_currencies', [], []);
55         }
57         $currencies = array_unique($currencies);
59         return $currencies;
60     }
62     /**
63      * Returns the list of gateways that can process payments in the given currency.
64      *
65      * @param string $component
66      * @param string $paymentarea
67      * @param int $componentid
68      * @return string[]
69      */
70     public static function get_gateways_for_currency(string $component, string $paymentarea, int $componentid): array {
71         $gateways = [];
73         [
74             'amount' => $amount,
75             'currency' => $currency,
76             'accountid' => $accountid,
77         ] = self::get_cost($component, $paymentarea, $componentid);
78         $account = new account($accountid);
79         if (!$account->get('id') || !$account->get('enabled')) {
80             return $gateways;
81         }
83         foreach ($account->get_gateways() as $plugin => $gateway) {
84             if (!$gateway->get('enabled')) {
85                 continue;
86             }
87             /** @var gateway $classname */
88             $classname = '\pg_' . $plugin . '\gateway';
90             $currencies = component_class_callback($classname, 'get_supported_currencies', [], []);
91             if (in_array($currency, $currencies)) {
92                 $gateways[] = $plugin;
93             }
94         }
96         return $gateways;
97     }
99     /**
100      * Calculates the cost with the surcharge
101      *
102      * @param float $amount amount in the currency units
103      * @param float $surcharge surcharge in percents
104      * @param string $currency currency, used for calculating the number of fractional digits
105      * @return float
106      */
107     public static function get_cost_with_surcharge(float $amount, float $surcharge, string $currency): float {
108         return round($amount + $amount * $surcharge / 100, 2); // TODO number of digits depends on currency.
109     }
111     /**
112      * Returns human-readable amount with fixed number of fractional digits and currency indicator
113      *
114      * @param float $amount
115      * @param string $currency
116      * @return string
117      * @throws \coding_exception
118      */
119     public static function get_cost_as_string(float $amount, string $currency): string {
120         if (class_exists('NumberFormatter') && function_exists('numfmt_format_currency')) {
121             $locale = get_string('localecldr', 'langconfig');
122             $fmt = \NumberFormatter::create($locale, \NumberFormatter::CURRENCY);
123             $localisedcost = numfmt_format_currency($fmt, $amount, $currency);
124         } else {
125             $localisedcost = sprintf("%.2f %s", $amount, $currency); // TODO number of digits depends on currency.
126         }
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('pg_' . $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 componentid belongs to
145      * @param string $paymentarea
146      * @param int $componentid 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 $componentid, string $description): array {
151         [
152             'amount' => $amount,
153             'currency' => $currency
154         ] = self::get_cost($component, $paymentarea, $componentid);
156         return [
157             'id' => 'gateways-modal-trigger',
158             'role' => 'button',
159             'data-component' => $component,
160             'data-paymentarea' => $paymentarea,
161             'data-componentid' => $componentid,
162             'data-cost' => self::get_cost_as_string($amount, $currency),
163             'data-description' => $description,
164         ];
165     }
167     /**
168      * Asks the cost from the related component.
169      *
170      * @param string $component Name of the component that the componentid belongs to
171      * @param string $paymentarea
172      * @param int $componentid An internal identifier that is used by the component
173      * @return array['amount' => float, 'currency' => string, 'accountid' => int]
174      * @throws \moodle_exception
175      */
176     public static function get_cost(string $component, string $paymentarea, int $componentid): array {
177         $cost = component_class_callback("$component\\payment\\provider", 'get_cost', [$paymentarea, $componentid]);
179         if ($cost === null || !is_array($cost) || !array_key_exists('amount', $cost)
180                 || !array_key_exists('currency', $cost) || !array_key_exists('accountid', $cost) ) {
181             throw new \moodle_exception('callbacknotimplemented', 'core_payment', '', $component);
182         }
184         return $cost;
185     }
187     /**
188      * Returns the gateway configuration for given component and gateway
189      *
190      * @param string $component
191      * @param string $paymentarea
192      * @param int $componentid
193      * @param string $gatewayname
194      * @return array
195      * @throws \moodle_exception
196      */
197     public static function get_gateway_configuration(string $component, string $paymentarea, int $componentid,
198             string $gatewayname): array {
199         $x = self::get_cost($component, $paymentarea, $componentid);
200         $gateway = null;
201         $account = new account($x['accountid']);
202         if ($account && $account->get('enabled')) {
203             $gateway = $account->get_gateways()[$gatewayname] ?? null;
204         }
205         if (!$gateway) {
206             throw new \moodle_exception('gatewaynotfound', 'payment');
207         }
208         return $gateway->get_configuration();
209     }
211     /**
212      * Delivers what the user paid for.
213      *
214      * @uses \core_payment\local\callback\provider::deliver_order()
215      *
216      * @param string $component Name of the component that the componentid belongs to
217      * @param string $paymentarea
218      * @param int $componentid An internal identifier that is used by the component
219      * @param int $paymentid payment id as inserted into the 'payments' table, if needed for reference
220      * @return bool Whether successful or not
221      */
222     public static function deliver_order(string $component, string $paymentarea, int $componentid, int $paymentid): bool {
223         $result = component_class_callback("$component\\payment\\provider", 'deliver_order',
224                 [$paymentarea, $componentid, $paymentid]);
226         if ($result === null) {
227             throw new \moodle_exception('callbacknotimplemented', 'core_payment', '', $component);
228         }
230         return $result;
231     }
233     /**
234      * Stores essential information about the payment and returns the "id" field of the payment record in DB.
235      * Each payment gateway may then store the additional information their way.
236      *
237      * @param int $accountid Account id
238      * @param string $component Name of the component that the componentid belongs to
239      * @param string $paymentarea
240      * @param int $componentid An internal identifier that is used by the component
241      * @param int $userid Id of the user who is paying
242      * @param float $amount Amount of payment
243      * @param string $currency Currency of payment
244      * @param string $gateway The gateway that is used for the payment
245      * @return int
246      */
247     public static function save_payment(int $accountid, string $component, string $paymentarea, int $componentid, int $userid,
248             float $amount, string $currency, string $gateway): int {
249         global $DB;
251         $record = new \stdClass();
252         $record->component = $component;
253         $record->paymentarea = $paymentarea;
254         $record->componentid = $componentid;
255         $record->userid = $userid;
256         $record->amount = $amount;
257         $record->currency = $currency;
258         $record->gateway = $gateway;
259         $record->accountid = $accountid;
260         $record->timecreated = $record->timemodified = time();
262         $id = $DB->insert_record('payments', $record);
264         return $id;
265     }
267     /**
268      * This functions adds the settings that are common for all payment gateways.
269      *
270      * @param \admin_settingpage $settings The settings object
271      * @param string $gateway The gateway name prefic with pg_
272      */
273     public static function add_common_gateway_settings(\admin_settingpage $settings, string $gateway): void {
274         $settings->add(new \admin_setting_configtext($gateway . '/surcharge', get_string('surcharge', 'core_payment'),
275                 get_string('surcharge_desc', 'core_payment'), 0, PARAM_INT));
277     }
279     /**
280      * Save a new or edited payment account (used in management interface)
281      *
282      * @param \stdClass $data
283      * @return account
284      */
285     public static function save_payment_account(\stdClass $data): account {
287         if (empty($data->id)) {
288             $account = new account(0, $data);
289             $account->save();
290             account_created::create_from_account($account)->trigger();
291         } else {
292             $account = new account($data->id);
293             $account->from_record($data);
294             $account->save();
295             account_updated::create_from_account($account)->trigger();
296         }
298         return $account;
299     }
301     /**
302      * Delete a payment account (used in management interface)
303      *
304      * @param account $account
305      */
306     public static function delete_payment_account(account $account): void {
307         global $DB;
308         if ($DB->record_exists('payments', ['accountid' => $account->get('id')])) {
309             $account->set('archived', 1);
310             $account->save();
311             account_updated::create_from_account($account, ['archived' => 1])->trigger();
312             return;
313         }
315         foreach ($account->get_gateways(false) as $gateway) {
316             if ($gateway->get('id')) {
317                 $gateway->delete();
318             }
319         }
320         $event = account_deleted::create_from_account($account);
321         $account->delete();
322         $event->trigger();
323     }
325     /**
326      * Restore archived payment account (used in management interface)
327      *
328      * @param account $account
329      */
330     public static function restore_payment_account(account $account): void {
331         $account->set('archived', 0);
332         $account->save();
333         account_updated::create_from_account($account, ['restored' => 1])->trigger();
334     }
336     /**
337      * Save a payment gateway linked to an existing account (used in management interface)
338      *
339      * @param \stdClass $data
340      * @return account_gateway
341      */
342     public static function save_payment_gateway(\stdClass $data): account_gateway {
343         if (empty($data->id)) {
344             $records = account_gateway::get_records(['accountid' => $data->accountid, 'gateway' => $data->gateway]);
345             if ($records) {
346                 $gateway = reset($records);
347             } else {
348                 $gateway = new account_gateway(0, $data);
349             }
350         } else {
351             $gateway = new account_gateway($data->id);
352         }
353         unset($data->accountid, $data->gateway, $data->id);
354         $gateway->from_record($data);
356         $account = $gateway->get_account();
357         $gateway->save();
358         account_updated::create_from_account($account)->trigger();
359         return $gateway;
360     }
362     /**
363      * Returns the list of payment accounts in the given context (used in management interface)
364      *
365      * @param \context $context
366      * @return account[]
367      */
368     public static function get_payment_accounts_to_manage(\context $context, bool $showarchived = false): array {
369         $records = account::get_records(['contextid' => $context->id] + ($showarchived ? [] : ['archived' => 0]));
370         \core_collator::asort_objects_by_method($records, 'get_formatted_name');
371         return $records;
372     }
374     /**
375      * Get list of accounts available in the given context
376      *
377      * @param \context $context
378      * @return array
379      */
380     public static function get_payment_accounts_menu(\context $context): array {
381         global $DB;
382         [$sql, $params] = $DB->get_in_or_equal($context->get_parent_context_ids(true));
383         $accounts = array_filter(account::get_records_select('contextid '.$sql, $params), function($account) {
384             return $account->is_available() && !$account->get('archived');
385         });
386         return array_map(function($account) {
387             return $account->get_formatted_name();
388         }, $accounts);
389     }