Описание

Библиотека представляет собой пакет, состоящий из собственно библиотеки и системного плагина для хранения настроек связи Joomla и Moodle. PHP библиотека является нативным Joomla 4 / Joomla 5  расширением.

LMS Moodle является, пожалуй, самой известной и популярной бесплатной Learning Management System - движком для создания онлайн-курсов. Однако, из-за узкой специфики (курсы и обучение) полноценные сайты создавать на ней не стоит. Поэтому для тех, кто занимается онлайн-обучением, обычно создаются 2 сайта: один на Joomla для собственно сайта, а второй - для обучения - на Moodle.

Возможности библиотеки

• выполнение внешних запросов к штатному REST API Moodle с помощью Joomla API
• для настроек интеграции используется системный плагин
• проверка структуры данных и типов данных для методов перед выполнением запроса. Если в схеме обнаружена ошибка - запрос не будет выполнен.
• начата работа над созданием коллекции Joomla Form (ex. JForm) полей для использования их в расширениях - плагинах, модулях, компонентах и т.д.
• при корректной настройке интеграции в системном плагине можно посмотреть список доступных для работы в Joomla методов REST API Moodle
• методы для сохранения сопоставления пользователей Joomla и Moodle в собственной таблице в базе данных
• возможность выполнения запроса на свою кастомную точку входа в Moodle, а не к REST API

Как использовать библиотеку для связи с LMS Moodle в Joomla

Видео

В этом видео (Joomla 5 и Moodle 4.3):

1. Полная инструкция по включению и настройке REST API в Moodle. Также REST API называется внешние службы или веб-сервисы. Инструкция включает в себя создание роли, пользователя, самой внешней службы, токена и т.д.
2. Установка и настройка библиотеки для интеграции Joomla 5 и Moodle 4.3. PHP библиотека WT JMoodle позволяет пользоваться методами REST API Moodle внутри Joomla и оперировать в Joomla данными Moodle.

Установите и настройте библиотеку для Moodle и Joomla

• Установите библиотеку JMoodle в Joomla
• Перейдите в Ваш Moodle и создаёте токен для Joomla
• Укажите этот токен в системном плагине WT JMoodle, в котором хранятся настройки интеграции Moodle и Joomla

Как создать токен внешней службы (web services) в Moodle для Joomla?

Для получения токена нужно выполнить следующие действия:

1. Создать специального пользователя в Moodle, от имени которого Joomla будет действовать в Moodle и обращаться к методам REST API. Администрирование / Пользователи / Учётные записи / Добавить пользователя. Не назначайте этого пользователя администратором сайта.
2. Создать роль для специального пользователя Moodle и назначить ей необходимые права доступа в Администрирование / Пользователи / Права / Определить роли. Наличие или отсутствие в этом разделе доступов (контекста роли и прав) будет влиять на работу с некоторыми методами REST API. Необходимые для методов права доступа видно на этапе добавления функций для веб-службы.
3. Создать Внешнюю службу в Администрирование / Сервер / Веб-службы / Внешние службы.
4. После создания внешней службы из списка внешних служб перейдите в функции созданной службы и добавьте необходимые для работы интеграции методы REST API. Добавьте метод core_webservice_get_site_info для того, чтобы в Joomla увидеть, что интеграция действительно работает, а так же список доступных для REST API методов.
5. Создайте токен в Администрирование / Сервер / Веб-службы / Управление ключами для специально созданного пользователя, из-под которого Joomla будет обращаться к REST API.

Если Вы всё сделали правильно, то Вы должны увидеть список доступных методов REST API Moodle во вкладке REST API methods в Joomla.

Как выполнить запрос к Moodle webservices (REST API) из Joomla?

Пример кода ниже иллюстрирует выполнение простейшего запроса:

<?php
use Webtolk\JMoodle\JMoodle;

$moodle = new JMoodle();

/**
 * Request method. 
 * 
 * @param   string  $method  Moodle REST API method
 * @param   array   $data    data for Moodle REST API method
 *
 * @return array
 */
$result_jmoodle = $moodle->request('core_webservice_get_site_info');

Посмотрите файл поля Joomla Form, например, MoodleinfoField, в нём образец выполнения запроса и обработки полученных данных:

<?php
use Webtolk\JMoodle\JMoodle;

$moodle = new JMoodle();

// Здесь мы проверяем можем ли мы сделать запрос к REST API Moodle - заполнены ли токен и хост? 
if (!$moodle::canDoRequest())
{
    return ''; // или false или то, что Вам необходимо
}

// Выполняем запрос к методу Moodle webservice. Смотрите в информацию в документации Moodle
// Возвращает массив с данными из Moodle или с кодом и описанием ошибки
$result_jmoodle = $moodle->request('core_webservice_get_site_info');

// Check if we have an empty response for core_webservice_get_site_info method
if (count($result_jmoodle) == 0)
{
    return '<div class="alert alert-danger row">
                <div class="col-2 h1">400</div>
                <div class="col-10">There is no Moodle host response</div>
            </div>';
}

// Проверяем, есть ли ошибка и её описание

if (isset($result_jmoodle['error_code']) && !empty($result_jmoodle['error_code']))
{
    return '<div class="alert alert-danger row">
                <div class="col-2 h1">' . $result_jmoodle['error_code'] . '</div>
                <div class="col-10">' . $result_jmoodle['error_message'] . '</div>
            </div>';
}

// Проверяем получили ли мы нужные данные, несмотря на HTTP code == 200
if (!array_key_exists('sitename', $result_jmoodle) || empty($result_jmoodle['sitename']))
{
    return '<div class="alert alert-danger row">
                <div class="col-2 h1">400</div>
                <div class="col-10">Moodle return wrong response</div>
            </div>';
}

// Всё OK, мы получили нужные данные из Moodle в Joomla
$result_jmoodle['sitename']; // 'Мой тестовый Moodle'
$result_jmoodle['release']; // 'Moodle 4.3 (Build: 20231009)'
$result_jmoodle['userpictureurl']; // 'Здесь url картинки профиля из Moodle'

// и так далее...

Выполнение запроса на свою собственную точку входа в Moodle

Некоторые расширения для Moodle позволяют обращаться к ним минуя интерфейс REST API. Для этого в библиотеку добавлен метод customRequest().

<?php
use Webtolk\JMoodle\JMoodle;

$moodle = new JMoodle();

$data = [
	'param' => 'value'
];

$file = JPATH_SITE.'/123.txt';

$curl_options    = [
			CURLOPT_COOKIEJAR      => $file,
			CURLOPT_RETURNTRANSFER => 1,
			CURLOPT_HEADER         => 1,
			CURLOPT_SSL_VERIFYPEER => false
		];
$moodle_reposnse = $moodle->customRequest('/path/to/file/in/moodle.php', $data, 'POST', $curl_options);

Структура библиотеки для Moodle и Joomla

Эта библиотека создана для Joomla разработчиков. Файлы библиотеки устанавливаются в libraries/Webtolk/JMoodle/src.

- src
-- Fields
-- Helper
-- Interfaces
- JMoodle.php
- JMoodleClientException.php

Fields

Fields - это нативные Joomla Form (бывший JForm) классы полей, которые Вы можете использовать в своих расширениях: модулях, плагинах, компонентах и так далее. Эта папка будет постепенно наполняться.

Пример использования этих полей в Вашем XML для расширения (Joomla 4 и Joomla 5):

Поле Moodleinfo

Это поле отображает информацию о Вашем Moodle. Если Вы видите эту информацию, значит интеграция Joomla и Moodle настроена и работает правильно.

<field addfieldprefix="Webtolk\JMoodle\Fields"
                       type="moodleinfo"
                       name="moodleinfo"/>

Поле Moodlerestapimethods

Это поле отображает список доступных из Joomla для работы методов REST API Moodle для указанного токена.

<field addfieldprefix="Webtolk\JMoodle\Fields"
                       type="moodlerestapimethods"
                       name="moodlerestapimethods"
                       collapsible="true"
                />

Атрибут collapsible="true" не обязателен. Если он не указан или равен false - список методов будет отображён в развёрнутом виде.

Helper

Helper - это папка, в которой находятся хелперы для методов REST API Moodle (webservices). Эти классы проверяют структуру и тип обязательных данных запроса до того, как сам запрос будет отправлен в Moodle. Если структура массива данных или тип данных не будет соответствовать документации Moodle, то хелпер класса вернёт ошибку и её описание, а сам запрос не будет выполнен..

Имя класса Helper

Имя класса хелпера формируется динамически в методе getMethodHelperClass библиотеки (файл: libraries\Webtolk\JMoodle\src\JMoodle.php) исходя из названия запрашиваемого метода REST API Moodle. Логика формирования имени класса хелпера следующая:

• получаем имя метода Moodle
• разбиваем его на массив по символу нижнего подчёркивания _. Так класс хелпера для core_webservice_get_site_info будет находиться в namespace Webtolk\JMoodle\Helper\Core\Webservice - Webtolk\JMoodle\Helper\Core\Webservice. Если имя метода содержит в себе слово Self, мы переименовываем его в MySelf. Так, хелперы для методов Moodle webservices enrol_self_... будут находиться в namespace Enrol\MySelf - Webtolk\JMoodle\Helper\Enrol\MySelf. Так сделано потому, что слово Self является зарезервированным в PHP.

Пример пустого класса Helper для методов

В этом примере не происходит никакой предобработки и проверки данных. В Moodle уходит тот массив, который Вы сформировали:

<?php 
namespace Webtolk\JMoodle\Helper\Core\Create;

defined('_JEXEC') or die;
use Webtolk\JMoodle\Interfaces\MethodhelperInterface;

class Create implements MethodhelperInterface
{
    public function checkData(string $method, array $data = []): array
    {
        return $data;
    }
}

Пример класса хелпера для namespace Core\User

Этот Helper проверяет структуру данных и тип данных для всех методов REST API Moodle core_user_.... Здесь указан пример для метода core_user_create_users.

<?php
namespace Webtolk\JMoodle\Helper\Core\User;

defined('_JEXEC') or die;

use Webtolk\JMoodle\Interfaces\MethodhelperInterface;

class User implements MethodhelperInterface
{
	public function checkData(string $method, array $data = []): array
	{
	    // Call a check method
		return $this->$method($data);
	}

	/**
	 * Check data for core_user_create_users Moodle REST API method
	 *
	 * @param   array  $data  Users data for create in Moodle
	 *
	 * @return array $data array if check is success. Array with error description if check is false
	 *
	 * @since 1.0.0
	 */
	private function core_user_create_users(array $data = []): array
	{
		if (!array_key_exists('users', $data))
		{
			return [
				'error_code'    => 400,
				'error_message' => 'Empty users array specified'
			];
		}

		$users = $data['users'];

		if (count($users) < 1)
		{
			return [
				'error_code'    => 400,
				'error_message' => 'Empty users array specified'
			];
		}

		foreach ($users as $user)
		{
			if (!array_key_exists('createpassword', $user) || $user['createpassword'] != 1)
			{
				if (!array_key_exists('password', $user) || empty($user['password']))
				{
					return [
						'error_code'    => 400,
						'error_message' => 'Invalid password: you must provide a password, or set createpassword.'
					];
				}
			}

			if (!array_key_exists('username', $user) ||
				!array_key_exists('email', $user) ||
				!array_key_exists('firstname', $user) ||
				!array_key_exists('lastname', $user) ||
				empty($user['username']) ||
				empty($user['email']) ||
				empty($user['firstname']) ||
				empty($user['lastname'])
			)
			{
				return [
					'error_code'    => 400,
					'error_message' => 'One of the required fields (username, email, firstname, lastname) for user which you are creating are not specified or empty'
				];
			}
		}

		return $data;
	}
// И так далее...
}

Аналогичным образом происходят проверки для методов Moodle webservices:

• core_user_update_users
• core_user_delete_users
• core_user_get_users
• core_user_get_users_by_field
• core_user_add_user_device
• core_user_add_user_private_files
• core_user_agree_site_policy
• core_user_get_course_user_profiles
• core_user_get_private_files_info
• core_user_get_user_preferences
• core_user_remove_user_device
• core_user_search_identity
• core_user_set_user_preferences
• core_user_update_picture
• core_user_update_user_device_public_key
• core_user_update_user_preferences
• core_user_view_user_list
• core_user_view_user_profile

Готовые на данный момент классы helper

• Webtolk\JMoodle\Helper\Core\User
• Webtolk\JMoodle\Helper\Enrol\Manual

Interfaces

В этой папке находятся интерфейсы, в которых зафиксированы методы и типы данных для них для корректной работы библиотеки.