Moodle Client Utils

A comprehensive PHP utility library for interacting with Moodle's REST API. This package provides a clean, object-oriented interface to perform CRUD operations on users, categories, courses, cohorts, calendar events, and roles in any Moodle instance.

---

Overview

Moodle Client Utils is a sample client-side API utility suite that abstracts away the complexity of Moodle's web service layer. It handles authentication, request formatting, and response parsing so you can focus on your application logic.

Feature	Description
User Management	Create, read, update, and delete users
Category Management	Create, read, update, and delete course categories
Course Management	Create, read, update, and delete courses
Cohort Management	Create, read, update, delete cohorts and manage members
Role Management	Assign roles to users
Calendar Events	Create calendar events

---

Requirements

• PHP 5.6 or higher
• Moodle 3.0 or higher (with REST web services enabled)
• Moodle Web Service Token with appropriate permissions

Required Capabilities

The following Moodle capabilities must be enabled for the web service user:

webservice/rest:use
moodle/user:create
moodle/user:update
moodle/user:delete
moodle/user:viewdetails
moodle/user:viewhiddendetails
moodle/user:viewalldetails
moodle/user:editprofile
moodle/role:manage
moodle/role:assign
moodle/role:review
moodle/category:manage
moodle/category:viewcourselist
moodle/category:viewhiddencategories
moodle/course:create
moodle/course:view
moodle/course:update
moodle/course:delete
moodle/course:visibility
moodle/course:changecategory
moodle/course:changefullname
moodle/course:viewparticipants
moodle/course:configurecustomfields
moodle/cohort:assign
moodle/cohort:manage
moodle/cohort:view
moodle/calendar:manageentries

Required Web Service Functions

The following Moodle web service functions must be enabled:

core_user_create_users
core_user_delete_users
core_user_update_users
core_user_get_users
core_user_get_users_by_field
core_role_assign_roles
core_course_get_categories
core_course_create_categories
core_course_create_courses
core_course_get_courses
core_cohort_create_cohorts
core_cohort_add_cohort_members
core_calendar_create_calendar_events

---

Installation

1. Clone or download the repository:

   git clone https://github.com/sanjay-kumar001/moodle-client-utils.git

2. Include the required files in your PHP script:

   require_once('MoodleRest.php');
   require_once('Utils.php');

---

Configuration

Create or modify the Config.php file with your Moodle instance details:

<?php
$config = new stdClass();
$config->server = 'https://your-moodle-instance.com';
$config->token = 'your_webservice_token_here';
$config->server_address = $config->server . '/webservice/rest/server.php';
return $config;
?>

Important: The token must be generated from your Moodle site's Site Administration → Plugins → Web services → Manage tokens.

---

Core Classes

MoodleRest

The MoodleRest class is the underlying REST client that handles all API communication.

Constructor:

new MoodleRest($server_address, $token, $return_format)

Parameter	Type	Description
$server_address	string	Full URL to Moodle REST server script
$token	string	Moodle web service token
$return_format	constant	MoodleRest::RETURN_ARRAY (default), RETURN_JSON, or RETURN_XML

Available Methods:

Method	Description
setServerAddress($address)	Set the Moodle REST server URL
setToken($token)	Set the web service token
setReturnFormat($format)	Set return format (array, json, xml)
setDebug($enabled)	Enable/disable debug output
request($function, $parameters, $method)	Execute a Moodle web service function

Example:

$rest = new MoodleRest('https://moodle.example.com/webservice/rest/server.php', 'your_token');
$result = $rest->request('core_user_get_users', ['criteria' => []]);

---

Utils.php – Helper Functions

The Utils.php file provides wrapper functions for common Moodle operations. Each function internally uses MoodleRest to communicate with the Moodle API.

Helper Functions

Function	Description
get_moodle_data($ws_function, $param)	Perform a GET request to Moodle
push_data_to_moodle($ws_function, $param)	Perform a POST request to Moodle
get_key_map($data, $keyfield, $valuefield)	Build an associative array from response data
convert_to_timestamp($datetime)	Convert a datetime string to Unix timestamp

---

Usage Examples

User Management

Create Users

$users = [
    [
        'username'   => 'john_doe',
        'password'   => 'SecurePass123',
        'firstname'  => 'John',
        'lastname'   => 'Doe',
        'email'      => 'john.doe@example.com',
        'auth'       => 'manual',
        'phone1'     => '1234567890',
        'customfields' => [
            ['type' => 'user_type', 'value' => 'teacher']
        ]
    ]
];

$result = create_users($users);
var_dump($result);

File reference: core_user_create_users.php

---

Get Users

// Get all users
$result = get_users();
var_dump($result);

// Get users by field
$field = 'username';
$values = ['john_doe'];
$result = get_users_by_field($field, $values);
var_dump($result);

File reference: core_user_get_users_by_field.php

---

Update Users

$users = [
    [
        'id'         => 45,        // Moodle user ID
        'firstname'  => 'John Updated'
    ]
];

$result = update_users($users);
var_dump($result);

File reference: core_user_update_users.php

---

Delete Users

$userids = [45, 46, 47];  // Array of user IDs
$result = delete_users($userids);
var_dump($result);

File reference: core_user_delete_users.php

---

Category Management

Create Categories

$categories = [
    [
        'name'       => 'Science',
        'idnumber'   => 'SCI-001',
        'description' => 'Science department courses',
        'parent'     => 0          // 0 for root category
    ]
];

$result = create_categories($categories);
var_dump($result);

---

Get Categories

$criteria = [
    ['key' => 'name', 'value' => 'Science']
];

$result = get_categories($criteria);
var_dump($result);

File reference: core_course_get_categories.php

Supported search criteria:

• id – Category ID (int)
• ids – Category IDs separated by commas (string)
• name – Category name (string)
• parent – Parent category ID (int)
• idnumber – Category ID number (string)

---

Update Categories

$categories = [
    [
        'id'          => 71,
        'name'        => 'Science - Updated',
        'description' => 'Updated description'
    ]
];

$result = update_categories($categories);
var_dump($result);

File reference: core_course_update_categories.php

---

Delete Categories

$categories = [
    [
        'id'        => 72,
        'recursive' => 1   // 1: delete all contents, 0: move to parent
    ]
];

$result = delete_categories($categories);
var_dump($result);

File reference: core_course_delete_categories.php

---

Course Management

Create Courses

$courses = [
    [
        'fullname'    => 'Introduction to Physics',
        'shortname'   => 'PHY101',
        'categoryid'  => 5,
        'idnumber'    => 'PHY-101',
        'summary'     => 'This course covers fundamental physics concepts.',
        'format'      => 'topics',  // topics, weeks, social, site
        'numsections' => 10,
        'startdate'   => convert_to_timestamp('2025-01-15'),
        'enddate'     => convert_to_timestamp('2025-05-15')
    ]
];

$result = create_courses($courses);
var_dump($result);

File reference: core_course_create_courses.php

Available course fields:

Field	Type	Description
fullname	string	Full course name
shortname	string	Course short name
categoryid	int	Category ID
idnumber	string	Course ID number
summary	string	Course summary
format	string	Course format: topics, weeks, social, site
numsections	int	Number of weeks/topics
startdate	int	Start timestamp
enddate	int	End timestamp
visible	int	1 = visible to students, 0 = hidden
showgrades	int	1 = show grades, 0 = hide

---

Update Courses

$courses = [
    [
        'id'        => 69,
        'fullname'  => 'Physics 101 - Updated',
        'shortname' => 'PHY101UPD'
    ]
];

$result = update_courses($courses);
var_dump($result);

File reference: core_course_update_courses.php

---

Delete Courses

$courseids = [69, 70, 71];
$result = delete_courses($courseids);
var_dump($result);

File reference: core_course_delete_courses.php

---

Cohort Management

Create Cohorts

$cohorts = [
    [
        'name'         => 'Student Cohort A',
        'idnumber'     => 'STU-A-001',
        'categorytype' => [
            'type'  => 'system',
            'value' => ''
        ]
    ]
];

$result = create_cohorts($cohorts);
var_dump($result);

File reference: core_cohort_create_cohorts.php

---

Get Cohorts

$cohortids = [57, 58, 59];
$result = get_cohorts($cohortids);
var_dump($result);

File reference: core_cohort_get_cohorts.php

---

Search Cohorts

$query = 'Student';
$context = [
    'contextlevel' => 'system',
    'instanceid'   => 0
];
$includes = 'all';  // parents, all

$result = search_cohorts($query, $context, $includes);
var_dump($result);

File reference: core_cohort_search_cohorts.php

---

Update Cohorts

$cohorts = [
    [
        'id'           => 56,
        'name'         => 'Student Cohort A - Updated',
        'idnumber'     => 'STU-A-001-UPD',
        'categorytype' => [
            'type'  => 'system',
            'value' => ''
        ]
    ]
];

$result = update_cohorts($cohorts);
var_dump($result);

File reference: core_cohort_update_cohorts.php

---

Delete Cohorts

$cohortids = [56, 57];
$result = delete_cohorts($cohortids);
var_dump($result);

File reference: core_cohort_delete_cohorts.php

---

Cohort Members

Add Members to Cohort

$members = [
    [
        'cohorttype' => [
            'type'  => 'idnumber',
            'value' => 'STU-A-001'
        ],
        'usertype' => [
            'type'  => 'username',
            'value' => 'john_doe'
        ]
    ]
];

$result = add_cohort_members($members);
var_dump($result);

File reference: core_cohort_add_cohort_members.php

---

Get Cohort Members

$cohortids = [57, 58];
$result = get_cohort_members($cohortids);
var_dump($result);

File reference: core_cohort_get_cohort_members.php

---

Remove Members from Cohort

$members = [
    [
        'cohortid' => 71,
        'userid'   => 55
    ]
];

$result = delete_cohort_members($members);
var_dump($result);

File reference: core_cohort_delete_cohort_members.php

---

Role Management

Assign Roles

$assignments = [
    [
        'roleid'  => 5,   // Role ID (e.g., 5 = teacher)
        'userid'  => 45,  // User ID
        'contextid' => 1  // Context ID
    ]
];

$result = assign_roles($assignments);
var_dump($result);

File reference: core_role_assign_roles.php

---

Calendar Events

Create Calendar Events

$events = [
    [
        'name'         => 'Mid-term Exam',
        'description'  => 'Mid-term examination for all courses',
        'courseid'     => 69,
        'eventtype'    => 'course',
        'timestart'    => convert_to_timestamp('2025-03-15 09:00:00'),
        'timeduration' => 120,  // Duration in minutes
        'repeats'      => 0     // Number of repeats
    ]
];

$result = create_calendar_events($events);
var_dump($result);

File reference: core_calendar_create_calendar_events.php

---

File Structure

moodle-client-utils/
├── Config.php                          # Configuration file
├── MoodleRest.php                      # REST API client class
├── Utils.php                           # Utility wrapper functions
├── core_user_create_users.php          # Example: Create users
├── core_user_update_users.php          # Example: Update users
├── core_user_delete_users.php          # Example: Delete users
├── core_user_get_users_by_field.php    # Example: Get users by field
├── core_course_create_categories.php   # Example: Create categories
├── core_course_get_categories.php      # Example: Get categories
├── core_course_update_categories.php   # Example: Update categories
├── core_course_delete_categories.php   # Example: Delete categories
├── core_course_create_courses.php      # Example: Create courses
├── core_course_update_courses.php      # Example: Update courses
├── core_course_delete_courses.php      # Example: Delete courses
├── core_cohort_create_cohorts.php      # Example: Create cohorts
├── core_cohort_get_cohorts.php         # Example: Get cohorts
├── core_cohort_search_cohorts.php      # Example: Search cohorts
├── core_cohort_update_cohorts.php      # Example: Update cohorts
├── core_cohort_delete_cohorts.php      # Example: Delete cohorts
├── core_cohort_add_cohort_members.php  # Example: Add cohort members
├── core_cohort_get_cohort_members.php  # Example: Get cohort members
├── core_cohort_delete_cohort_members.php # Example: Remove cohort members
├── core_role_assign_roles.php          # Example: Assign roles
├── core_calendar_create_calendar_events.php # Example: Create calendar events
└── user_fields.txt                     # Reference: User field mappings

---

Debugging

Enable debug output to inspect API requests and responses:

$MoodleRest = new MoodleRest($server_address, $token);
$MoodleRest->setDebug(true);
$result = $MoodleRest->request('core_user_get_users', ['criteria' => []]);

Debug output includes:

• Request method (GET/POST)
• Full URL with parameters
• Raw response data

---

Error Handling

The library uses PHP's native error handling with trigger_error(). Common errors:

Error	Cause
Empty server address	Server address not set in Config.php or constructor
Empty token	Web service token not set
Empty function	No web service function specified in request()
Invalid return format	Return format must be 'json', 'xml', or 'array'
Invalid parameter value detected	Malformed request parameters

---

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to your branch
5. Submit a pull request

---

License

This project is open-source and available under the MIT License.

---

Credits

• MoodleRest class by Lawrence Lagerlof
• Moodle Client Utils by Sanjay Kumar

---

Support

For issues, questions, or feature requests, please open an issue on GitHub.