<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

namespace core_course\external;

use context_module;

< use external_description;
< use external_files;
< use external_format_value;
< use external_util;
< use external_value;



> use core_external\external_description;
> use core_external\external_files;
> use core_external\external_format_value;
> use core_external\util as external_util;
> use core_external\external_value;



/**
 * This class helps implement the get_..._by_courses web service that every activity should have.
 *
 * It has helper methods to add the standard course-module fields to the results, and the declaration of the return value.
 *
 * @package    core_course
 * @copyright  2022 The Open University
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
abstract class helper_for_get_mods_by_courses {

    /**
     * Add the value of all the standard fields to the results to be returned by the service.
     * This is designed to be used in the implementation of the get_..._by_courses web service methods.
     *
     * Note that $modinstance is also updated in-place.
     *
     * @param \stdClass $modinstance one of the objects returned from a call to {@see get_all_instances_in_courses()}.
     * @param string $component the plugin name, e.g. 'mod_book'.
     * @param string $capabilityforgroups capability to check before including group/visible/section info in the results.
     * @param string|null $capabilityforintro capability to check before including intro info in the results.
     *      null means always include (the default).
     * @return array with the containing all the values declared in {@see standard_coursemodule_elements_returns()}.
     */
    public static function standard_coursemodule_element_values(\stdClass $modinstance, string $component,
            string $capabilityforgroups = 'moodle/course:manageactivities', string $capabilityforintro = null): array {
        self::format_name_and_intro($modinstance, $component);
        $context = context_module::instance($modinstance->coursemodule);

        // First, we return information that any user can see in the web interface.
        $moddetails['id'] = $modinstance->id;
        $moddetails['coursemodule'] = $modinstance->coursemodule;
        $moddetails['course'] = $modinstance->course;
        $moddetails['name'] = $modinstance->name;
        $moddetails['lang'] = clean_param($modinstance->lang, PARAM_LANG);
        if (!$capabilityforintro || has_capability($capabilityforintro, $context)) {
            $moddetails['intro'] = $modinstance->intro;
            $moddetails['introformat'] = $modinstance->introformat;
            $moddetails['introfiles'] = $modinstance->introfiles;
        }

        // Now add information only available to people who can edit.
        if (has_capability($capabilityforgroups, $context)) {
            $moddetails['section'] = $modinstance->section;
            $moddetails['visible'] = $modinstance->visible;
            $moddetails['groupmode'] = $modinstance->groupmode;
            $moddetails['groupingid'] = $modinstance->groupingid;
        }

        return $moddetails;
    }

    /**
     * Format the module name an introduction ready to be exported to a web service.
     *
     * Note that $modinstance is updated in-place.
     *
     * @param \stdClass $modinstance one of the objects returned from a call to {@see get_all_instances_in_courses()}.
     * @param string $component the plugin name, e.g. 'mod_book'.
     */
    public static function format_name_and_intro(\stdClass $modinstance, string $component) {
        $context = context_module::instance($modinstance->coursemodule);


<         $modinstance->name = external_format_string($modinstance->name, $context->id);



>         $modinstance->name = \core_external\util::format_string($modinstance->name, $context);




<         [$modinstance->intro, $modinstance->introformat] = external_format_text(
<                 $modinstance->intro, $modinstance->introformat, $context->id,



>         [$modinstance->intro, $modinstance->introformat] = \core_external\util::format_text(
>                 $modinstance->intro, $modinstance->introformat, $context,


                $component, 'intro', null, ['noclean' => true]);
        $modinstance->introfiles = external_util::get_area_files($context->id, $component, 'intro', false, false);
    }

    /**
     * Get the list of standard fields, to add to the declaration of the return values.
     *
     * Example usage combine the fields returned here with any extra ones your activity uses:
     *
     *   public static function execute_returns() {
     *       return new external_single_structure([
     *               'bigbluebuttonbns' => new external_multiple_structure(
     *                   new external_single_structure(array_merge(
     *                       helper_for_get_mods_by_courses::standard_coursemodule_elements_returns(),
     *                       [
     *                           'meetingid' => new external_value(PARAM_RAW, 'Meeting id'),
     *                           'timemodified' => new external_value(PARAM_INT, 'Last time the instance was modified'),
     *                       ]
     *                   ))
     *               ),
     *               'warnings' => new external_warnings(),
     *           ]
     *       );
     *   }
     *
     * @param bool $introoptional if true, the intro fields are marked as optional. Default false.
     * @return external_description[] array of standard fields, to which you can add your activity-specific ones.
     */
    public static function standard_coursemodule_elements_returns(bool $introoptional = false): array {
        return [
            'id' => new external_value(PARAM_INT, 'Activity instance id'),
            'coursemodule' => new external_value(PARAM_INT, 'Course module id'),
            'course' => new external_value(PARAM_INT, 'Course id'),
            'name' => new external_value(PARAM_RAW, 'Activity name'),
            'intro' => new external_value(PARAM_RAW, 'Activity introduction', $introoptional ? VALUE_OPTIONAL : VALUE_REQUIRED),
            'introformat' => new external_format_value('intro', $introoptional ? VALUE_OPTIONAL : VALUE_REQUIRED),
            'introfiles' => new external_files('Files in the introduction', VALUE_OPTIONAL),
            'section' => new external_value(PARAM_INT, 'Course section id', VALUE_OPTIONAL),
            'visible' => new external_value(PARAM_BOOL, 'Visible', VALUE_OPTIONAL),
            'groupmode' => new external_value(PARAM_INT, 'Group mode', VALUE_OPTIONAL),
            'groupingid' => new external_value(PARAM_INT, 'Group id', VALUE_OPTIONAL),
            'lang' => new external_value(PARAM_SAFEDIR, 'Forced activity language', VALUE_OPTIONAL),
        ];
    }
}