Added External Function contextlength Parameter validation.

Updated some External Parameter Descriptions.
SE-Stuttgart · Aug 18, 2024 · 63c6b7a · 63c6b7a
1 parent fc7b3a2
commit 63c6b7a
Show file tree

Hide file tree

Showing 3 changed files with 31 additions and 9 deletions.
diff --git a/classes/external/search_book_content.php b/classes/external/search_book_content.php
@@ -33,6 +33,7 @@
 use block_booksearch\data\data;
 use block_booksearch\search\search;
 use context_course;
+use invalid_parameter_exception;
 use stdClass;
 
 /**
@@ -51,17 +52,17 @@ public static function execute_parameters() {
             [
                 'courseid' => new external_value(
                     PARAM_INT,
-                    'Id of the course the user wants to access',
+                    get_string('parameter_course_id', 'block_booksearch'),
                     VALUE_REQUIRED
                 ),
                 'searchstring' => new external_value(
                     PARAM_TEXT,
-                    'String to search for in the course',
+                    get_string('parameter_search_string', 'block_booksearch'),
                     VALUE_REQUIRED
                 ),
                 'contextlength' => new external_value(
                     PARAM_INT,
-                    'Number of words surrounding the found query word in each direction',
+                    get_string('parameter_context_length', 'block_booksearch'),
                     VALUE_DEFAULT,
                     0
                 ),
@@ -76,10 +77,10 @@ public static function execute_parameters() {
     public static function execute_returns() {
         return new external_multiple_structure(
             new external_single_structure([
-                'filename' => new external_value(PARAM_TEXT, 'name of the pdf file that has a matching book.'),
-                'pagenumber' => new external_value(PARAM_INT, 'page number this searched occurance happens in filename book.'),
-                'bookchapterurl' => new external_value(PARAM_RAW, 'url to pagenumber book chapter.'),
-                'contextsnippet' => new external_value(PARAM_RAW, 'text snippet around the occurance.'),
+                'filename' => new external_value(PARAM_TEXT, get_string('parameter_file_name', 'block_booksearch')),
+                'pagenumber' => new external_value(PARAM_INT, get_string('parameter_page_number', 'block_booksearch')),
+                'bookchapterurl' => new external_value(PARAM_RAW, get_string('parameter_book_chapter_url', 'block_booksearch')),
+                'contextsnippet' => new external_value(PARAM_RAW, get_string('parameter_context_snippet', 'block_booksearch')),
             ])
         );
     }
@@ -113,10 +114,15 @@ public static function execute($courseid, $searchstring, $contextlength) {
         $searchstring = $params['searchstring'];
         $contextlength = $params['contextlength'];
 
+        // Check for valid context length.
+        if ($contextlength < 0) {
+            throw new invalid_parameter_exception(get_string('invalid_context_length', 'block_booksearch'));
+        }
+
         // Check permissions.
         list($isvalid, $course, $error) = block_booksearch_validate_course_access($courseid, $USER->id);
         if (!$isvalid) {
-            return '';
+            throw new invalid_parameter_exception(get_string('invalid_course', 'block_booksearch'));
         }
 
         $coursecontext = context_course::instance($course->id);

diff --git a/lang/en/block_booksearch.php b/lang/en/block_booksearch.php
@@ -50,3 +50,19 @@
 $string['error_course_not_found'] = 'Course not found.';
 $string['error_course_access_denied'] = 'Access to course denied.';
 $string['error_book_pdf_mismatch'] = 'There exists an mismatch of book and pdf.';
+
+// External Parameter Description.
+$string['parameter_course_id'] = 'Id of the course the user wants to access.';
+$string['parameter_search_string'] = 'String to search for in the course.';
+$string['parameter_context_length'] = "A positive integer indicating the number of words on each side of the search result
+ that get returned as additional context.";
+
+// External Parameter Error.
+$string['invalid_context_length'] = 'The parameter contextlength needs to be a positive integer.';
+$string['invalid_course'] = 'The parameter courseid needs to be a valid course id, you have access to.';
+
+// External Return Parameter Description.
+$string['parameter_file_name'] = 'Name of the PDF file that has a matching book.';
+$string['parameter_page_number'] = 'Page number where this searched occurrence happens in the filename book.';
+$string['parameter_book_chapter_url'] = 'URL to the book chapter with the page number.';
+$string['parameter_context_snippet'] = 'Text snippet around the occurrence.';
diff --git a/version.php b/version.php
@@ -23,7 +23,7 @@
  */
 defined('MOODLE_INTERNAL') || die();
 
-$plugin->version   = 2024081206;  // The current plugin version (Date: YYYYMMDDHH).
+$plugin->version   = 2024081800;  // The current plugin version (Date: YYYYMMDDHH).
 $plugin->requires  = 2020061510;  // Requires this Moodle version.
 $plugin->component = 'block_booksearch';  // Full name of the plugin (used for diagnostics).
 $plugin->release = '1.1.3';