Proyectos de Subversion Moodle

<?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 qbank_managecategories\external;

use core_external\external_api;
use core_external\external_function_parameters;
use core_external\external_value;
use core_external\external_single_structure;
use core_external\external_multiple_structure;
use core_question\category_manager;
use moodle_exception;
use context;
use qbank_managecategories\helper;

/**
 * External class used for category reordering.
 *
 * @package    qbank_managecategories
 * @category   external
 * @copyright  2024 Catalyst IT Europe Ltd.
 * @author     Mark Johnson <mark.johnson@catalyst-eu.net>
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
class move_category extends external_api {
    /**
     * Describes the parameters for update_category_order webservice.
     * @return external_function_parameters
     */
    public static function execute_parameters(): external_function_parameters {
        return new external_function_parameters([
            'pagecontextid' => new external_value(PARAM_INT, 'The context of the current page'),
            'categoryid' => new external_value(PARAM_INT, 'Category being moved'),
            'targetparentid' => new external_value(PARAM_INT, 'The ID of the parent category to move to.'),
            'precedingsiblingid' => new external_value(
                PARAM_INT,
                'The ID of the preceding category. Null if this is being moved to top of its parent',
                allownull: NULL_ALLOWED,
            ),
        ]);
    }

    /**
     * Returns description of method result value.
     *
     * This function will always return a set of state updates for the core/reactive state.
     * {@link https://moodledev.io/docs/4.2/guides/javascript/reactive#controlling-the-state-from-the-backend}
     *
     * @return external_multiple_structure
     */
    public static function execute_returns(): external_multiple_structure {
        return new external_multiple_structure(
            new external_single_structure(
                [
                    'name' => new external_value(PARAM_ALPHA, 'State object name (always "categories" from this function).'),
                    'action' => new external_value(PARAM_ALPHA, 'State update type (always "put" from this function).'),
                    'fields' => new external_single_structure(
                        [
                            'id' => new external_value(PARAM_INT, 'The ID of the category that was updated.'),
                            'sortorder' => new external_value(PARAM_INT, 'The new sortorder', VALUE_OPTIONAL),
                            'parent' => new external_value(PARAM_INT, 'The ID of the new parent category.', VALUE_OPTIONAL),
                            'context' => new external_value(PARAM_INT, 'The ID of the new context.', VALUE_OPTIONAL),
                            'draghandle' => new external_value(
                                PARAM_BOOL,
                                'Should this category have a drag handle?',
                                VALUE_OPTIONAL
                            ),
                        ]
                    ),
                ],
                'An individual state update',
            ),
            'Category state updates',
        );
    }

    /**
     * Move category to new location.
     *
     * @param int $pagecontextid ID of the context of the current page.
     * @param int $categoryid ID of the category to move.
     * @param int $targetparentid The ID of the parent category to move to.
     * @param ?int $precedingsiblingid The ID of the preceding category. Null if this is being moved to top of its parent.
     * @return array Reactive state updates representing the changes made to the categories.
     */
    public static function execute(
        int $pagecontextid,
        int $categoryid,
        int $targetparentid,
        ?int $precedingsiblingid = null
    ): array {
        // Update category location.
        global $DB, $CFG;

        require_once($CFG->libdir . '/questionlib.php');

        $context = context::instance_by_id($pagecontextid);
        self::validate_context($context);
        $manager = new category_manager();

        $origincategory = $DB->get_record('question_categories', ['id' => $categoryid], '*', MUST_EXIST);
        $targetparent = $DB->get_record('question_categories', ['id' => $targetparentid], '*', MUST_EXIST);
        if ($precedingsiblingid) {
            $precedingsibling = $DB->get_record('question_categories', ['id' => $precedingsiblingid], '*', MUST_EXIST);
        }

        // Check permission for original and destination contexts.
        $manager->require_manage_category(context::instance_by_id($origincategory->contextid));

        if ($origincategory->contextid != $targetparent->contextid) {
            $manager->require_manage_category(context::instance_by_id($targetparent->contextid));
        }

        $originstateupdate = self::make_state_update($origincategory->id);
        $stateupdates = [];

        $transaction = $DB->start_delegated_transaction();

        // Set new parent.
        if ($origincategory->parent !== $targetparent->id) {
            $newsiblings = $DB->get_fieldset('question_categories', 'id', ['parent' => $targetparent->id]);
            if (
                count($newsiblings) == 1
                && $manager->is_only_child_of_top_category_in_context(reset($newsiblings))
            ) {
                // If we are moving to a top-level parent that only had 1 category before, allow re-ordering of that category.
                $stateupdates[] = self::make_state_update(reset($newsiblings), draghandle: true);
            }
            $originstateupdate->fields->parent = $targetparent->id;
        }

        // Change to the same context.
        if ($origincategory->contextid !== $targetparent->contextid) {
            // Check for duplicate idnumber.
            if (
                !is_null($origincategory->idnumber)
                && !$manager->idnumber_is_unique_in_context($origincategory->idnumber, $targetparent->contextid)
            ) {
                $transaction->rollback(new moodle_exception('idnumberexists', 'qbank_managecategories'));
            }
            $originstateupdate->fields->context = $targetparent->contextid;
        }

        // Update sort order.
        if ($precedingsiblingid) {
            $sortorder = $precedingsibling->sortorder + 1;
        } else {
            $sortorder = 1;
        }
        $originstateupdate->fields->sortorder = $sortorder;

        // Save the updated parent, context and sortorder.
        $manager->update_category(
            $categoryid,
            helper::combine_id_context($targetparent),
            $origincategory->name,
            $origincategory->info,
            $origincategory->infoformat,
            $origincategory->idnumber,
            $sortorder,
        );

        // Get other categories which are after the new position, and update their sortorder.
        $params = [
            'parent' => $targetparent->id,
            'sortorder' => $sortorder,
            'origincategoryid' => $origincategory->id,
        ];
        $select = "
            parent = :parent
            AND id <> :origincategoryid
            AND sortorder >= :sortorder";
        $sort = "sortorder ASC";
        $toupdatesortorder = $DB->get_records_select('question_categories', $select, $params, $sort);
        foreach ($toupdatesortorder as $category) {
            $DB->set_field('question_categories', 'sortorder', ++$sortorder, ['id' => $category->id]);
            $stateupdates[] = self::make_state_update($category->id, sortorder: $sortorder);
        }

        if (isset($originstateupdate->fields->parent)) {
            // If the category has moved parent, re-order the original siblings to fill the gap.
            $originsortorder = 1;
            $params = [
                'parent' => $origincategory->parent,
            ];
            $select = "parent = :parent";
            $sort = "sortorder ASC";
            $originsiblings = $DB->get_records_select('question_categories', $select, $params, $sort);
            if (
                count($originsiblings) == 1
                && $manager->is_only_child_of_top_category_in_context(reset($originsiblings)->id)
            ) {
                // If this is now the only category in the context, don't allow re-ordering.
                $stateupdates[] = self::make_state_update(
                    reset($originsiblings)->id,
                    sortorder: $originsortorder,
                    draghandle: false,
                );
            } else {
                foreach ($originsiblings as $category) {
                    if ($category->sortorder !== $originsortorder) {
                        $DB->set_field('question_categories', 'sortorder', $originsortorder, ['id' => $category->id]);
                        $stateupdates[] = self::make_state_update($category->id, sortorder: $originsortorder);
                    }
                    $originsortorder++;
                }
            }
        }

        $transaction->allow_commit();

        // Return the updated for the moved category, followed by any additional updates that happened as a result.
        array_unshift($stateupdates, $originstateupdate);

        return $stateupdates;
    }

    /**
     * Generate a category state update based on the provided fields.
     *
     * @param int $id Category ID, required.
     * @param int|null $sortorder New sortorder, optional.
     * @param int|null $parent Category ID of new parent, optional.
     * @param bool|null $draghandle Set display of the drag handle. Optional.
     * @return \stdClass The update object.
     */
    protected static function make_state_update(
        int $id,
        ?int $sortorder = null,
        ?int $parent = null,
        ?bool $draghandle = null,
    ): \stdClass {
        $update = (object)[
            'name' => 'categories',
            'action' => 'put',
            'fields' => (object)[
                'id' => $id,
            ],
        ];
        if (!is_null($sortorder)) {
            $update->fields->sortorder = $sortorder;
        }
        if (!is_null($parent)) {
            $update->fields->parent = $parent;
        }
        if (!is_null($draghandle)) {
            $update->fields->draghandle = $draghandle;
        }
        return $update;
    }
}