Fix most CodeSniffer and PHPDoc checker issues

innocampus · Sep 12, 2024 · 499dfcb · 499dfcb
1 parent 364d648
commit 499dfcb
Show file tree

Hide file tree

Showing 15 changed files with 232 additions and 78 deletions.
diff --git a/auth.php b/auth.php
@@ -15,17 +15,19 @@
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
+ * Calls Shibboleth authentication.
+ *
  * @package      availability_shibboleth2fa
  * @copyright    2021 Lars Bonczek, innoCampus, TU Berlin
  * @license      http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @noinspection PhpUnhandledExceptionInspection
+ *
+ * {@noinspection PhpUnhandledExceptionInspection}
  */
 
 use availability_shibboleth2fa\condition;
 
 require(__DIR__ . '/../../../config.php');
 
-/** @var core_renderer $OUTPUT because the type is not correctly annotated in Moodle */
 global $OUTPUT, $PAGE, $USER;
 
 $courseid = required_param('id', PARAM_INT);
@@ -35,8 +37,12 @@
 $course = get_course($courseid);
 
 $url = new moodle_url('/availability/condition/shibboleth2fa/auth.php', ['id' => $courseid]);
-if ($cmid) $url->param('cmid', $cmid);
-if ($sectionid) $url->param('sectionid', $sectionid);
+if ($cmid) {
+    $url->param('cmid', $cmid);
+}
+if ($sectionid) {
+    $url->param('sectionid', $sectionid);
+}
 $PAGE->set_url($url);
 
 require_login($course, false);
@@ -77,8 +83,12 @@
 }
 
 $redirecturl = new moodle_url('/availability/condition/shibboleth2fa/index.php', ['id' => $courseid]);
-if ($cmid) $redirecturl->param('cmid', $cmid);
-if ($sectionid) $redirecturl->param('sectionid', $sectionid);
+if ($cmid) {
+    $redirecturl->param('cmid', $cmid);
+}
+if ($sectionid) {
+    $redirecturl->param('sectionid', $sectionid);
+}
 
 if ($errormsg) {
     // Display error before redirecting.

diff --git a/classes/condition.php b/classes/condition.php
@@ -15,6 +15,10 @@
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
+ * Part of the required availability condition subsystem implementation.
+ *
+ * @see https://moodledev.io/docs/4.4/apis/plugintypes/availability#classesconditionphp
+ *
  * @package    availability_shibboleth2fa
  * @copyright  2021 Lars Bonczek, innoCampus, TU Berlin
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@@ -38,8 +42,15 @@
 use moodle_url;
 use stdClass;
 
-defined('MOODLE_INTERNAL') || die();
-
+/**
+ * Availability condition class.
+ *
+ * @see https://moodledev.io/docs/4.4/apis/plugintypes/availability#classesconditionphp
+ *
+ * @package    availability_shibboleth2fa
+ * @copyright  2021 Lars Bonczek, innoCampus, TU Berlin
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class condition extends abstract_condition {
 
     /** @var int|null cached ID of user with an exception */
@@ -49,18 +60,30 @@ class condition extends abstract_condition {
     private static array $exceptioncache = [];
 
     /**
-     * @inheritDoc
+     * {@inheritDoc}
+     *
+     * @param bool $not Set true if we are inverting the condition
+     * @param info $info Item we're checking
+     * @param bool $grabthelot Performance hint: if true, caches information required for all course-modules, to make the front page
+     *                         and similar pages work more quickly (works only for current user)
+     * @param int $userid User ID to check availability for
      * @throws dml_exception
      */
     public function is_available($not, info $info, $grabthelot, $userid): bool {
-        if ($grabthelot) self::preload_exceptions($userid);
+        if ($grabthelot) {
+            self::preload_exceptions($userid);
+        }
         $course = $info->get_course();
         $ret = self::is_course_available($course->id, $userid);
         return ($not xor $ret);
     }
 
     /**
-     * @inheritDoc
+     * {@inheritDoc}
+     *
+     * @param bool $full Set true if this is the 'full information' view
+     * @param bool $not Set true if we are inverting the condition
+     * @param info $info Item we're checking
      * @throws moodle_exception
      */
     public function get_description($full, $not, info $info): string {
@@ -91,12 +114,16 @@ public function get_description($full, $not, info $info): string {
         return $str;
     }
 
-    /** @inheritDoc */
+    /**
+     * {@inheritDoc}
+     */
     protected function get_debug_string(): string {
         return '';
     }
 
-    /** @inheritDoc */
+    /**
+     * {@inheritDoc}
+     */
     public function save(): stdClass {
         return (object) ['type' => 'shibboleth2fa'];
     }
@@ -123,7 +150,6 @@ public static function set_authenticated(): void {
     private static function preload_exceptions(int $userid): void {
         global $DB;
         self::$exceptioncacheuser = $userid;
-        // Fetch exception records.
         self::$exceptioncache = $DB->get_fieldset_select(
             table: 'availability_shibboleth2fa_e',
             return: 'courseid',
@@ -204,6 +230,9 @@ public static function is_course_available(int $courseid, int $userid): bool {
     }
 
     /**
+     * Callback for the {@see user_enrolment_deleted} event to remove a possible exception made for the user in that course.
+     *
+     * @param user_enrolment_deleted $event The event instance in question referencing a course and a user that unenrolled from it.
      * @throws dml_exception
      */
     public static function user_enrolment_deleted(user_enrolment_deleted $event): void {
@@ -212,6 +241,9 @@ public static function user_enrolment_deleted(user_enrolment_deleted $event): vo
     }
 
     /**
+     * Callback for the {@see course_deleted} event to remove all exceptions made for users in that course.
+     *
+     * @param course_deleted $event The event instance in question referencing the course that was deleted.
      * @throws dml_exception
      */
     public static function course_deleted(course_deleted $event): void {
@@ -220,6 +252,9 @@ public static function course_deleted(course_deleted $event): void {
     }
 
     /**
+     * Callback for the {@see user_deleted} event to remove all exceptions made for that user in any course.
+     *
+     * @param user_deleted $event The event instance in question referencing the user that was deleted.
      * @throws dml_exception
      */
     public static function user_deleted(user_deleted $event): void {

diff --git a/classes/event/user_2fa_loggedin.php b/classes/event/user_2fa_loggedin.php
@@ -15,6 +15,10 @@
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
+ * Definition of a custom event for when a user authenticates with this plugin.
+ *
+ * @see https://docs.moodle.org/dev/Events_API
+ *
  * @package    availability_shibboleth2fa
  * @copyright  2021 Lars Bonczek, innoCampus, TU Berlin
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@@ -27,8 +31,16 @@
 use core\event\base as base_event;
 use dml_exception;
 
-defined('MOODLE_INTERNAL') || die();
 
+/**
+ * Event class for when a user authenticates with this plugin.
+ *
+ * @see https://docs.moodle.org/dev/Events_API
+ *
+ * @package    availability_shibboleth2fa
+ * @copyright  2021 Lars Bonczek, innoCampus, TU Berlin
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class user_2fa_loggedin extends base_event {
 
     /**
@@ -62,6 +74,9 @@ public function get_description(): string {
         return "The user with id '$this->userid' authenticated using a second factor.";
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public static function get_objectid_mapping(): int {
         return base_event::NOT_MAPPED;
     }
@@ -76,8 +91,11 @@ public static function get_objectid_mapping(): int {
      */
     public static function create_and_trigger(int|null $userid = null): static {
         global $USER;
-        if (is_null($userid)) $userid = $USER->id;
-        /** @var static $event because the return type of the parent {@see create} method is not correctly annotated */
+        if (is_null($userid)) {
+            $userid = $USER->id;
+        }
+        // Because the return type of the parent `create` method is not correctly annotated, we do this here.
+        /** @var static $event */
         $event = static::create(['userid' => $userid, 'objectid' => $userid]);
         $event->trigger();
         return $event;

diff --git a/classes/exception_current_user_selector.php b/classes/exception_current_user_selector.php
@@ -15,39 +15,47 @@
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
+ * Definition of the {@see exception_current_user_selector} class.
+ *
  * @package    availability_shibboleth2fa
  * @copyright  2021 Lars Bonczek, innoCampus, TU Berlin
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 namespace availability_shibboleth2fa;
 
-global $CFG;
-
 use coding_exception;
 use dml_exception;
 use user_selector_base;
 
 defined('MOODLE_INTERNAL') || die();
-
+global $CFG;
 require_once("$CFG->dirroot/user/selector/lib.php");
 
 
 /**
  * TODO: Reduce code duplication with {@see exception_potential_user_selector}
  */
 class exception_current_user_selector extends user_selector_base {
+    /** @var int ID of the course that the exceptions apply to */
     protected int $courseid;
 
+    /**
+     * {@inheritDoc}
+     *
+     * @param string $name The control name/id for use in the HTML.
+     * @param array $options Other options needed to construct this selector. Must contain the `courseid`.
+     */
     public function __construct($name, $options) {
-        $this->courseid  = $options['courseid'];
+        $this->courseid = $options['courseid'];
         parent::__construct($name, $options);
     }
 
     /**
-     * Selected users
+     * Returns users for whom exceptions were defined in the associated course.
+     * {@inheritDoc}
      *
-     * @inheritDoc
+     * @param string $search the search string.
      * @throws coding_exception
      * @throws dml_exception
      */
@@ -85,10 +93,13 @@ public function find_users($search): array {
         return [$groupname => $availableusers];
     }
 
+    /**
+     * {@inheritDoc}
+     */
     protected function get_options(): array {
         $options = parent::get_options();
         $options['courseid'] = $this->courseid;
         $options['file'] = '/availability/condition/shibboleth2fa/classes/exception_current_user_selector.php';
         return $options;
     }
-}
+}
diff --git a/classes/exception_potential_user_selector.php b/classes/exception_potential_user_selector.php
@@ -15,39 +15,48 @@
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
+ * Definition of the {@see exception_potential_user_selector} class.
+ *
  * @package    availability_shibboleth2fa
  * @copyright  2021 Lars Bonczek, innoCampus, TU Berlin
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 namespace availability_shibboleth2fa;
 
-global $CFG;
 
 use coding_exception;
 use dml_exception;
 use user_selector_base;
 
 defined('MOODLE_INTERNAL') || die();
-
+global $CFG;
 require_once("$CFG->dirroot/user/selector/lib.php");
 
 
 /**
  * TODO: Reduce code duplication with {@see exception_current_user_selector}
  */
 class exception_potential_user_selector extends user_selector_base {
+    /** @var int ID of the course that the exceptions apply to */
     protected int $courseid;
 
+    /**
+     * {@inheritDoc}
+     *
+     * @param string $name The control name/id for use in the HTML.
+     * @param array $options Other options needed to construct this selector. Must contain the `courseid`.
+     */
     public function __construct($name, $options) {
-        $this->courseid  = $options['courseid'];
+        $this->courseid = $options['courseid'];
         parent::__construct($name, $options);
     }
 
     /**
-     * Candidate users
+     * Returns candidate users for whom exceptions can be set in the associated course.
+     * {@inheritDoc}
      *
-     * @inheritDoc
+     * @param string $search the search string.
      * @throws coding_exception
      * @throws dml_exception
      */
@@ -86,6 +95,9 @@ public function find_users($search): array {
         return [$groupname => $availableusers];
     }
 
+    /**
+     * {@inheritDoc}
+     */
     protected function get_options(): array {
         $options = parent::get_options();
         $options['courseid'] = $this->courseid;

diff --git a/classes/frontend.php b/classes/frontend.php
@@ -15,6 +15,10 @@
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
+ * Part of the required availability condition subsystem implementation.
+ *
+ * @see https://moodledev.io/docs/4.4/apis/plugintypes/availability#classesfrontendphp
+ *
  * @package    availability_shibboleth2fa
  * @copyright  2021 Lars Bonczek, innoCampus, TU Berlin
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@@ -29,8 +33,15 @@
 use section_info;
 use stdClass;
 
-defined('MOODLE_INTERNAL') || die();
-
+/**
+ * Class for front-end (editing form) functionality.
+ *
+ * @see https://moodledev.io/docs/4.4/apis/plugintypes/availability#classesfrontendphp
+ *
+ * @package    availability_shibboleth2fa
+ * @copyright  2021 Lars Bonczek, innoCampus, TU Berlin
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class frontend extends abstract_frontend {
 
     /**
@@ -52,7 +63,7 @@ protected function get_javascript_strings(): array {
      * @return bool
      * @throws coding_exception
      */
-    protected function allow_add($course, cm_info $cm = null, section_info $section = null): bool {
+    protected function allow_add($course, cm_info|null $cm = null, section_info|null $section = null): bool {
         $context = $cm ? $cm->context : context_course::instance($course->id);
         return has_capability('availability/shibboleth2fa:addinstance', $context);
     }