first commit

search/classes/external/document_exporter.php

@@ -0,0 +1,141 @@
+<?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_search\external;
+
+use core\external\exporter;
+
+/**
+ * Contains related class for displaying information of a search result.
+ *
+ * @package   core_search
+ * @since     Moodle 4.3
+ */
+class document_exporter extends exporter {
+
+    /**
+     * Return the list of properties.
+     *
+     * @return array
+     */
+    protected static function define_properties() {
+        return [
+            'itemid' => [
+                'type' => PARAM_INT,
+                'description' => 'unique id in the search area scope',
+            ],
+            'componentname' => [
+                'type' => PARAM_ALPHANUMEXT,
+                'description' => 'component name',
+            ],
+            'areaname' => [
+                'type' => PARAM_ALPHANUMEXT,
+                'description' => 'search area name',
+            ],
+            'courseurl' => [
+                'type' => PARAM_URL,
+                'description' => 'result course url',
+            ],
+            'coursefullname' => [
+                'type' => PARAM_RAW,
+                'description' => 'result course fullname',
+            ],
+            'timemodified' => [
+                'type' => PARAM_INT,
+                'description' => 'result modified time',
+            ],
+            'title' => [
+                'type' => PARAM_RAW,
+                'description' => 'result title',
+            ],
+            'docurl' => [
+                'type' => PARAM_URL,
+                'description' => 'result url',
+            ],
+            'iconurl' => [
+                'type' => PARAM_URL,
+                'description' => 'icon url',
+                'optional' => true,
+                'default' => '',
+                'null' => NULL_ALLOWED,
+            ],
+            'content' => [
+                'type' => PARAM_RAW,
+                'description' => 'result contents',
+                'optional' => true,
+                'default' => '',
+                'null' => NULL_ALLOWED,
+            ],
+            'contextid' => [
+                'type' => PARAM_INT,
+                'description' => 'result context id',
+            ],
+            'contexturl' => [
+                'type' => PARAM_URL,
+                'description' => 'result context url',
+            ],
+            'description1' => [
+                'type' => PARAM_RAW,
+                'description' => 'extra result contents, depends on the search area',
+                'optional' => true,
+                'default' => '',
+                'null' => NULL_ALLOWED,
+            ],
+            'description2' => [
+                'type' => PARAM_RAW,
+                'description' => 'extra result contents, depends on the search area',
+                'optional' => true,
+                'default' => '',
+                'null' => NULL_ALLOWED,
+            ],
+            'multiplefiles' => [
+                'type' => PARAM_INT,
+                'description' => 'whether multiple files are returned or not',
+                'optional' => true,
+            ],
+            'filenames' => [
+                'type' => PARAM_RAW,
+                'description' => 'result file names if present',
+                'muultiple' => true,
+                'optional' => true,
+            ],
+            'filename' => [
+                'type' => PARAM_RAW,
+                'description' => 'result file name if present',
+                'optional' => true,
+            ],
+            'userid' => [
+                'type' => PARAM_INT,
+                'description' => 'user id',
+                'optional' => true,
+            ],
+            'userurl' => [
+                'type' => PARAM_URL,
+                'description' => 'user url',
+                'optional' => true,
+            ],
+            'userfullname' => [
+                'type' => PARAM_RAW,
+                'description' => 'user fullname',
+                'optional' => true,
+            ],
+            'textformat' => [
+                'type' => PARAM_INT,
+                'description' => 'text fields format, it is the same for all of them',
+            ]
+        ];
+    }
+}

search/classes/external/get_results.php

@@ -0,0 +1,158 @@
+<?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_search\external;
+
+use core_external\external_api;
+use core_external\external_function_parameters;
+use core_external\external_single_structure;
+use core_external\external_multiple_structure;
+use core_external\external_value;
+use moodle_exception;
+
+/**
+ * External function for retrieving search results.
+ *
+ * @package    core_search
+ * @copyright  2023 David Monllao & Juan Leyva <juan@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since      Moodle 4.3
+ */
+class get_results extends external_api {
+
+    /**
+     * Webservice parameters.
+     *
+     * @return external_function_parameters
+     */
+    public static function execute_parameters(): external_function_parameters {
+        return new external_function_parameters(
+            [
+                'query' => new external_value(PARAM_NOTAGS, 'the search query'),
+                'filters' => new external_single_structure(
+                    [
+                        'title' => new external_value(PARAM_NOTAGS, 'result title', VALUE_OPTIONAL),
+                        'areaids' => new external_multiple_structure(
+                            new external_value(PARAM_ALPHANUMEXT, 'areaid'), 'restrict results to these areas', VALUE_DEFAULT, []
+                        ),
+                        'courseids' => new external_multiple_structure(
+                            new external_value(PARAM_INT, 'courseid'), 'restrict results to these courses', VALUE_DEFAULT, []
+                        ),
+                        'contextids' => new external_multiple_structure(
+                            new external_value(PARAM_INT, 'contextid'), 'restrict results to these contexts', VALUE_DEFAULT, []
+                        ),
+                        'cat' => new external_value(PARAM_NOTAGS, 'category to filter areas', VALUE_DEFAULT, ''),
+                        'userids' => new external_multiple_structure(
+                            new external_value(PARAM_INT, 'userid'), 'restrict results to these users', VALUE_DEFAULT, []
+                        ),
+                        'groupids' => new external_multiple_structure(
+                            new external_value(PARAM_INT, 'groupid'), 'restrict results to these groups', VALUE_DEFAULT, []
+                        ),
+                        'mycoursesonly' => new external_value(PARAM_BOOL, 'only results from my courses', VALUE_DEFAULT, false),
+                        'order' => new external_value(PARAM_ALPHA, 'how to order', VALUE_DEFAULT, ''),
+                        'timestart' => new external_value(PARAM_INT, 'docs modified after this date', VALUE_DEFAULT, 0),
+                        'timeend' => new external_value(PARAM_INT, 'docs modified before this date', VALUE_DEFAULT, 0)
+                    ], 'filters to apply', VALUE_DEFAULT, []
+                ),
+                'page' => new external_value(PARAM_INT, 'results page number starting from 0, defaults to the first page',
+                    VALUE_DEFAULT, 0)
+            ]
+        );
+    }
+
+    /**
+     * Gets global search results based on the provided query and filters.
+     *
+     * @param string $query the search query
+     * @param array $filters filters to apply
+     * @param int $page results page
+     * @return array search results
+     */
+    public static function execute(string $query, array $filters = [], int $page = 0): array {
+        global $PAGE;
+
+        $params = self::validate_parameters(self::execute_parameters(),
+            [
+                'query' => $query,
+                'filters' => $filters,
+                'page' => $page,
+            ]
+        );
+
+        $system = \context_system::instance();
+        external_api::validate_context($system);
+
+        require_capability('moodle/search:query', $system);
+
+        if (\core_search\manager::is_global_search_enabled() === false) {
+            throw new moodle_exception('globalsearchdisabled', 'search');
+        }
+
+        $search = \core_search\manager::instance();
+
+        $data = new \stdClass();
+        // First, mandatory parameters for consistency with web.
+        $data->q = $params['query'];
+        $data->title = $params['filters']['title'] ?? '';
+        $data->timestart = $params['filters']['timestart'] ?? 0;
+        $data->timeend = $params['filters']['timeend'] ?? 0;
+        $data->areaids = $params['filters']['areaids'] ?? [];
+        $data->courseids = $params['filters']['courseids'] ?? [];
+        $data->contextids = $params['filters']['contextids'] ?? [];
+        $data->userids = $params['filters']['userids'] ?? [];
+        $data->groupids = $params['filters']['groupids'] ?? [];
+
+        $cat = $params['filters']['cat'] ?? '';
+        if (\core_search\manager::is_search_area_categories_enabled()) {
+            $cat = \core_search\manager::get_search_area_category_by_name($cat);
+        }
+        if ($cat instanceof \core_search\area_category) {
+            $data->cat = $cat->get_name();
+        }
+
+        $docs = $search->paged_search($data, $page);
+
+        $return = [
+            'totalcount' => $docs->totalcount,
+            'warnings' => [],
+            'results' => []
+        ];
+
+        // Convert results to simple data structures.
+        if ($docs) {
+            foreach ($docs->results as $doc) {
+                $return['results'][] = $doc->export_doc($PAGE->get_renderer('core'));
+            }
+        }
+        return $return;
+    }
+
+    /**
+     * Webservice returns.
+     *
+     * @return external_single_structure
+     */
+    public static function execute_returns(): external_single_structure {
+        return new external_single_structure(
+            [
+                'totalcount' => new external_value(PARAM_INT, 'Total number of results'),
+                'results' => new external_multiple_structure(
+                    \core_search\external\document_exporter::get_read_structure()
+                ),
+            ]
+        );
+    }
+}

search/classes/external/get_search_areas_list.php

@@ -0,0 +1,117 @@
+<?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_search\external;
+
+use core_external\external_api;
+use core_external\external_function_parameters;
+use core_external\external_single_structure;
+use core_external\external_multiple_structure;
+use core_external\external_value;
+use core_external\external_warnings;
+use \core_search\manager;
+use moodle_exception;
+
+/**
+ * External function for return the list of search areas.
+ *
+ * @package    core_search
+ * @copyright  2023 Juan Leyva <juan@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since      Moodle 4.3
+ */
+class get_search_areas_list extends external_api {
+
+    /**
+     * Webservice parameters.
+     *
+     * @return external_function_parameters
+     */
+    public static function execute_parameters(): external_function_parameters {
+        return new external_function_parameters(
+            [
+                'cat' => new external_value(PARAM_NOTAGS, 'category to filter areas', VALUE_DEFAULT, ''),
+            ]
+        );
+    }
+
+
+    /**
+     * Return list of search areas.
+     *
+     * @param string $cat category to filter areas
+     * @return array search areas and warnings
+     */
+    public static function execute(string $cat = ''): array {
+
+        $params = self::validate_parameters(self::execute_parameters(), ['cat' => $cat]);
+
+        $system = \context_system::instance();
+        external_api::validate_context($system);
+
+        require_capability('moodle/search:query', $system);
+
+        if (manager::is_global_search_enabled() === false) {
+            throw new moodle_exception('globalsearchdisabled', 'search');
+        }
+
+        $areas = [];
+        $allsearchareas = manager::get_search_area_categories();
+        $enabledsearchareas = manager::get_search_areas_list(true);
+
+        foreach ($allsearchareas as $categoryid => $searchareacategory) {
+            if (!empty($params['cat']) && $params['cat'] != $categoryid) {
+                continue;
+            }
+
+            $searchareas = $searchareacategory->get_areas();
+            $catname = $searchareacategory->get_visiblename();
+            foreach ($searchareas as $areaid => $searcharea) {
+                if (key_exists($areaid, $enabledsearchareas)) {
+                    $name = $searcharea->get_visible_name();
+                    $areas[$name] = ['id' => $areaid, 'name' => $name, 'categoryid' => $categoryid, 'categoryname' => $catname];
+                }
+            }
+        }
+
+        ksort($areas);
+
+        return ['areas' => $areas, 'warnings' => []];
+    }
+
+    /**
+     * Webservice returns.
+     *
+     * @return external_single_structure
+     */
+    public static function execute_returns(): external_single_structure {
+        return new external_single_structure(
+            [
+                'areas' => new external_multiple_structure(
+                    new external_single_structure(
+                        [
+                            'id' => new external_value(PARAM_ALPHANUMEXT, 'search area id'),
+                            'categoryid' => new external_value(PARAM_NOTAGS, 'category id'),
+                            'categoryname' => new external_value(PARAM_NOTAGS, 'category name'),
+                            'name' => new external_value(PARAM_TEXT, 'search area name'),
+                        ], 'Search area'
+                    ), 'Search areas'
+                ),
+                'warnings' => new external_warnings()
+            ]
+        );
+    }
+}

search/classes/external/get_top_results.php

@@ -0,0 +1,131 @@
+<?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_search\external;
+
+use core_external\external_api;
+use core_external\external_function_parameters;
+use core_external\external_single_structure;
+use core_external\external_multiple_structure;
+use moodle_exception;
+
+/**
+ * External function for retrieving top search results.
+ *
+ * @package    core_search
+ * @copyright  2023 Juan Leyva <juan@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since      Moodle 4.3
+ */
+class get_top_results extends external_api {
+
+    /**
+     * Webservice parameters.
+     *
+     * @return external_function_parameters
+     */
+    public static function execute_parameters(): external_function_parameters {
+
+        $baseparameters = get_results::execute_parameters();
+
+        return new external_function_parameters(
+            [
+                'query' => $baseparameters->keys['query'],
+                'filters' => $baseparameters->keys['filters'],
+            ]
+        );
+    }
+
+    /**
+     * Gets top search results based on the provided query and filters.
+     *
+     * @param string $query the search query
+     * @param array $filters filters to apply
+     * @return array search results
+     */
+    public static function execute(string $query, array $filters = []): array {
+        global $PAGE;
+
+        $params = self::validate_parameters(self::execute_parameters(),
+            [
+                'query' => $query,
+                'filters' => $filters,
+            ]
+        );
+
+        $system = \context_system::instance();
+        external_api::validate_context($system);
+
+        require_capability('moodle/search:query', $system);
+
+        if (\core_search\manager::is_global_search_enabled() === false) {
+            throw new moodle_exception('globalsearchdisabled', 'search');
+        }
+
+        $search = \core_search\manager::instance();
+
+        $data = new \stdClass();
+        // First, mandatory parameters for consistency with web.
+        $data->q = $params['query'];
+        $data->title = $params['filters']['title'] ?? '';
+        $data->timestart = $params['filters']['timestart'] ?? 0;
+        $data->timeend = $params['filters']['timeend'] ?? 0;
+        $data->areaids = $params['filters']['areaids'] ?? [];
+        $data->courseids = $params['filters']['courseids'] ?? [];
+        $data->contextids = $params['filters']['contextids'] ?? [];
+        $data->userids = $params['filters']['userids'] ?? [];
+        $data->groupids = $params['filters']['groupids'] ?? [];
+
+        $cat = $params['filters']['cat'] ?? '';
+        if (\core_search\manager::is_search_area_categories_enabled()) {
+            $cat = \core_search\manager::get_search_area_category_by_name($cat);
+        }
+        if ($cat instanceof \core_search\area_category) {
+            $data->cat = $cat->get_name();
+        }
+
+        $docs = $search->search_top($data);
+
+        $return = [
+            'warnings' => [],
+            'results' => []
+        ];
+
+        // Convert results to simple data structures.
+        if ($docs) {
+            foreach ($docs as $doc) {
+                $return['results'][] = $doc->export_doc($PAGE->get_renderer('core'));
+            }
+        }
+        return $return;
+    }
+
+    /**
+     * Webservice returns.
+     *
+     * @return external_single_structure
+     */
+    public static function execute_returns(): external_single_structure {
+
+        return new external_single_structure(
+            [
+                'results' => new external_multiple_structure(
+                    \core_search\external\document_exporter::get_read_structure()
+                ),
+            ]
+        );
+    }
+}

search/classes/external/view_results.php

@@ -0,0 +1,125 @@
+<?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_search\external;
+
+use core_external\external_api;
+use core_external\external_function_parameters;
+use core_external\external_single_structure;
+use core_external\external_multiple_structure;
+use core_external\external_value;
+use core_external\external_warnings;
+use moodle_exception;
+
+/**
+ * External function for trigger view search results event.
+ *
+ * @package    core_search
+ * @copyright  2023 Juan Leyva <juan@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since      Moodle 4.3
+ */
+class view_results extends external_api {
+
+    /**
+     * Webservice parameters.
+     *
+     * @return external_function_parameters
+     */
+    public static function execute_parameters(): external_function_parameters {
+        return new external_function_parameters(
+            [
+                'query' => new external_value(PARAM_NOTAGS, 'the search query'),
+                'filters' => new external_single_structure(
+                    [
+                        'title' => new external_value(PARAM_NOTAGS, 'result title', VALUE_OPTIONAL),
+                        'areaids' => new external_multiple_structure(
+                            new external_value(PARAM_RAW, 'areaid'), 'restrict results to these areas', VALUE_DEFAULT, []
+                        ),
+                        'courseids' => new external_multiple_structure(
+                            new external_value(PARAM_INT, 'courseid'), 'restrict results to these courses', VALUE_DEFAULT, []
+                        ),
+                        'timestart' => new external_value(PARAM_INT, 'docs modified after this date', VALUE_DEFAULT, 0),
+                        'timeend' => new external_value(PARAM_INT, 'docs modified before this date', VALUE_DEFAULT, 0)
+                    ], 'filters to apply', VALUE_DEFAULT, []
+                ),
+                'page' => new external_value(PARAM_INT, 'results page number starting from 0, defaults to the first page',
+                    VALUE_DEFAULT, 0)
+            ]
+        );
+    }
+
+    /**
+     * Trigger view results event.
+     *
+     * @param string $query the search query
+     * @param array $filters filters to apply
+     * @param int $page results page
+     * @return array status and warnings
+     */
+    public static function execute(string $query, array $filters = [], int $page = 0): array {
+
+        $params = self::validate_parameters(self::execute_parameters(),
+            [
+                'query' => $query,
+                'filters' => $filters,
+                'page' => $page,
+            ]
+        );
+
+        $system = \context_system::instance();
+        external_api::validate_context($system);
+
+        require_capability('moodle/search:query', $system);
+
+        if (\core_search\manager::is_global_search_enabled() === false) {
+            throw new moodle_exception('globalsearchdisabled', 'search');
+        }
+
+        $filters = new \stdClass();
+        $filters->title = $params['filters']['title'] ?? '';
+        $filters->timestart = $params['filters']['timestart'] ?? 0;
+        $filters->timeend = $params['filters']['timeend'] ?? 0;
+        $filters->areaids = $params['filters']['areaids'] ?? [];
+        $filters->courseids = $params['filters']['courseids'] ?? [];
+
+        \core_search\manager::trigger_search_results_viewed([
+            'q' => $params['query'],
+            'page' => $params['page'],
+            'title' => !empty($filters->title) ? $filters->title : '',
+            'areaids' => !empty($filters->areaids) ? $filters->areaids : [],
+            'courseids' => !empty($filters->courseids) ? $filters->courseids : [],
+            'timestart' => isset($filters->timestart) ? $filters->timestart : 0,
+            'timeend' => isset($filters->timeend) ? $filters->timeend : 0
+        ]);
+
+        return ['status' => true, 'warnings' => []];
+    }
+
+    /**
+     * Webservice returns.
+     *
+     * @return external_single_structure
+     */
+    public static function execute_returns(): external_single_structure {
+        return new external_single_structure(
+            [
+                'status' => new external_value(PARAM_BOOL, 'status: true if success'),
+                'warnings' => new external_warnings()
+            ]
+        );
+    }
+}