More API class documentation - refs BT#17288

plugin/zoom/lib/API/BaseMeetingTrait.php

@@ -3,6 +3,12 @@
 
 namespace Chamilo\PluginBundle\Zoom\API;
 
+/**
+ * Trait BaseMeetingTrait.
+ * Common meeting properties definitions.
+ *
+ * @package Chamilo\PluginBundle\Zoom\API
+ */
 trait BaseMeetingTrait
 {
     /** @var string */

plugin/zoom/lib/API/Client.php

@@ -6,9 +6,11 @@ namespace Chamilo\PluginBundle\Zoom\API;
 use Exception;
 
 /**
- * Interface Client
+ * Interface Client.
  * Two implementations are currently possible : OAuth and JWT.
  *
+ * @see https://marketplace.zoom.us/docs/api-reference/zoom-api
+ *
  * @package Chamilo\PluginBundle\Zoom\API
  */
 interface Client

plugin/zoom/lib/API/CreatedRegistration.php

@@ -5,6 +5,12 @@ namespace Chamilo\PluginBundle\Zoom\API;
 
 use Exception;
 
+/**
+ * Class CreatedRegistration.
+ * An instance of this class is returned by the Zoom serveur upon recording a registrant to a meeting.
+ *
+ * @package Chamilo\PluginBundle\Zoom\API
+ */
 class CreatedRegistration
 {
     use JsonDeserializableTrait;

plugin/zoom/lib/API/CustomQuestion.php

@@ -3,6 +3,12 @@
 
 namespace Chamilo\PluginBundle\Zoom\API;
 
+/**
+ * Class CustomQuestion.
+ * A list of instances of this class is included in a MeetingRegistrant instance.
+ *
+ * @package Chamilo\PluginBundle\Zoom\API
+ */
 class CustomQuestion
 {
     /** @var string */

plugin/zoom/lib/API/GlobalDialInNumber.php

@@ -5,6 +5,12 @@ namespace Chamilo\PluginBundle\Zoom\API;
 
 use Exception;
 
+/**
+ * Class GlobalDialInNumber.
+ * A list of these is included in a meeting settings.
+ *
+ * @package Chamilo\PluginBundle\Zoom\API
+ */
 class GlobalDialInNumber
 {
     use JsonDeserializableTrait;

plugin/zoom/lib/API/JWTClient.php

@@ -9,7 +9,7 @@ use Firebase\JWT\JWT;
 /**
  * Class JWTClient.
  *
- * @see https://marketplace.zoom.us/docs/api-reference/zoom-api
+ * @see https://marketplace.zoom.us/docs/guides/auth/jwt
  *
  * @package Chamilo\PluginBundle\Zoom
  */

plugin/zoom/lib/API/JsonDeserializableTrait.php

@@ -5,6 +5,12 @@ namespace Chamilo\PluginBundle\Zoom\API;
 
 use Exception;
 
+/**
+ * Trait JsonDeserializableTrait.
+ * Utility fonctions to help convert server-generated JSON to API class instances.
+ *
+ * @package Chamilo\PluginBundle\Zoom\API
+ */
 trait JsonDeserializableTrait
 {
     /**

plugin/zoom/lib/API/MeetingInstance.php

@@ -7,9 +7,12 @@ use Exception;
 
 /**
  * Class MeetingInstance
- * A meeting can have one or more instances.
+ * A meeting (numerical id) can have one or more instances (string UUID).
  * Each instance has its own start time, participants and recording files.
  *
+ * @see MeetingInstances
+ * @see PastMeeting for the full record
+ *
  * @package Chamilo\PluginBundle\Zoom\API
  */
 class MeetingInstance

plugin/zoom/lib/API/MeetingInstances.php

@@ -6,7 +6,9 @@ namespace Chamilo\PluginBundle\Zoom\API;
 use Exception;
 
 /**
- * Class MeetingInstances.
+ * Class MeetingInstances. The list of one meeting's ended instances.
+ *
+ * @see MeetingInstance
  *
  * @package Chamilo\PluginBundle\Zoom\API
  */

plugin/zoom/lib/API/MeetingList.php

@@ -6,7 +6,9 @@ namespace Chamilo\PluginBundle\Zoom\API;
 use Exception;
 
 /**
- * Class MeetingList.
+ * Class MeetingList. Lists Meetings.
+ *
+ * @see MeetingListItem
  *
  * @package Chamilo\PluginBundle\Zoom\API
  */

plugin/zoom/lib/API/MeetingListItem.php

@@ -5,6 +5,13 @@ namespace Chamilo\PluginBundle\Zoom\API;
 
 use Exception;
 
+/**
+ * Class MeetingListItem. Item of a list of meetings.
+ *
+ * @see MeetingList
+ *
+ * @package Chamilo\PluginBundle\Zoom\API
+ */
 class MeetingListItem
 {
     use BaseMeetingTrait;

plugin/zoom/lib/API/MeetingRegistrant.php

@@ -5,6 +5,12 @@ namespace Chamilo\PluginBundle\Zoom\API;
 
 use Exception;
 
+/**
+ * Class MeetingRegistrant.
+ * Structure of the information to send the server in order to register someone to a meeting.
+ *
+ * @package Chamilo\PluginBundle\Zoom\API
+ */
 class MeetingRegistrant
 {
     use JsonDeserializableTrait;

plugin/zoom/lib/API/MeetingRegistrantList.php

@@ -5,6 +5,13 @@ namespace Chamilo\PluginBundle\Zoom\API;
 
 use Exception;
 
+/**
+ * Class MeetingRegistrantList. List of meeting registrants.
+ *
+ * @see MeetingRegistrantListItem
+ *
+ * @package Chamilo\PluginBundle\Zoom\API
+ */
 class MeetingRegistrantList
 {
     use Pagination;

plugin/zoom/lib/API/MeetingRegistrantListItem.php

@@ -3,6 +3,13 @@
 
 namespace Chamilo\PluginBundle\Zoom\API;
 
+/**
+ * Class MeetingRegistrantListItem. Item in a list of meeting registrants.
+ *
+ * @see MeetingRegistrantList
+ *
+ * @package Chamilo\PluginBundle\Zoom\API
+ */
 class MeetingRegistrantListItem extends MeetingRegistrant
 {
     /** @var string Registrant ID. */

plugin/zoom/lib/API/MeetingSettings.php

@@ -5,6 +5,11 @@ namespace Chamilo\PluginBundle\Zoom\API;
 
 use Exception;
 
+/**
+ * Class MeetingSettings. An instance of this class is included in each Meeting instance.
+ *
+ * @package Chamilo\PluginBundle\Zoom\API
+ */
 class MeetingSettings
 {
     use JsonDeserializableTrait;

plugin/zoom/lib/API/Pagination.php

@@ -7,7 +7,7 @@ use Exception;
 
 /**
  * Trait Pagination
- * properties for Pagination and PaginationToken objects, which are paginated lists of items,
+ * properties for Pagination objects, which are paginated lists of items,
  * retrieved in chunks from the server over one or several API calls, one per page.
  *
  * @package Chamilo\PluginBundle\Zoom\API
@@ -16,26 +16,20 @@ trait Pagination
 {
     use JsonDeserializableTrait;
 
-    /** @var int */
+    /** @var int The number of pages returned for the request made. */
     public $page_count;
 
-    /** @var int counting from 1 */
+    /** @var int The page number of the current results, counting from 1 */
     public $page_number;
 
-    /** @var int */
+    /** @var int The number of records returned with a single API call. Default 30, max 300. */
     public $page_size;
 
-    /** @var int */
+    /** @var int The total number of all the records available across pages. */
     public $total_records;
 
-    /** @var string The next page token is used to paginate through large result sets.
-     * A next page token will be returned whenever the set of available results exceeds the current page size.
-     * The expiration period for this token is 15 minutes.
-     */
-    public $next_page_token;
-
     /**
-     * Retrieves items from the server.
+     * Retrieves all items from the server, possibly generating several API calls.
      *
      * @param string $arrayPropertyName item array property name
      * @param Client $client

plugin/zoom/lib/API/PaginationToken.php

@@ -0,0 +1,73 @@
+<?php
+/* For licensing terms, see /license.txt */
+
+namespace Chamilo\PluginBundle\Zoom\API;
+
+use Exception;
+
+/**
+ * Trait PaginationToken
+ * properties for PaginationToken objects, which are paginated lists of items,
+ * retrieved in chunks from the server over one or several API calls, one per page.
+ *
+ * @package Chamilo\PluginBundle\Zoom\API
+ */
+trait PaginationToken
+{
+    use JsonDeserializableTrait;
+
+    /** @var int The number of pages returned for the request made. */
+    public $page_count;
+
+    /** @var int The number of records returned within a single API call. Default 30, max 300. */
+    public $page_size;
+
+    /** @var int The number of all records available across pages. */
+    public $total_records;
+
+    /** @var string The next page token is used to paginate through large result sets.
+     * A next page token will be returned whenever the set of available results exceeds the current page size.
+     * The expiration period for this token is 15 minutes.
+     */
+    public $next_page_token;
+
+    /**
+     * Retrieves all items from the server, possibly generating several API calls.
+     *
+     * @param string $arrayPropertyName item array property name
+     * @param Client $client
+     * @param string $relativePath      relative path to pass to Client::send
+     * @param array  $parameters        parameter array to pass to Client::send
+     *
+     * @throws Exception
+     *
+     * @return array united list of items
+     */
+    protected static function loadItems($arrayPropertyName, $client, $relativePath, $parameters = [])
+    {
+        $items = [];
+        $pageSize = 300;
+        $totalRecords = 0;
+        $nextPageToken = '';
+        do {
+            $response = static::fromJson(
+                $client->send(
+                    'GET',
+                    $relativePath,
+                    array_merge(['page_size' => $pageSize, 'next_page_token' => $nextPageToken], $parameters)
+                )
+            );
+            $items = array_merge($items, $response->$arrayPropertyName);
+            $nextPageToken = $response->next_page_token;
+            if (0 === $totalRecords) {
+                $pageSize = $response->page_size;
+                $totalRecords = $response->total_records;
+            }
+        } while (!empty($nextPagetoken));
+        if (count($items) !== $totalRecords) {
+            error_log('Zoom announced '.$totalRecords.' records but returned '.count($items));
+        }
+
+        return $items;
+    }
+}

plugin/zoom/lib/API/ParticipantList.php

@@ -7,13 +7,15 @@ use Exception;
 
 /**
  * Class ParticipantList
- * List of past meetings participants.
+ * List of past meeting instance participants.
+ *
+ * @see ParticipantListItem;
  *
  * @package Chamilo\PluginBundle\Zoom\API
  */
 class ParticipantList
 {
-    use Pagination;
+    use PaginationToken;
 
     /** @var ParticipantListItem[] */
     public $participants;

plugin/zoom/lib/API/ParticipantListItem.php

@@ -3,6 +3,13 @@
 
 namespace Chamilo\PluginBundle\Zoom\API;
 
+/**
+ * Class ParticipantListItem. Item in a list of past meeting instance participants.
+ *
+ * @see ParticipantList
+ *
+ * @package Chamilo\PluginBundle\Zoom\API
+ */
 class ParticipantListItem
 {
     /** @var string participant UUID */

plugin/zoom/lib/API/PastMeeting.php

@@ -6,8 +6,12 @@ namespace Chamilo\PluginBundle\Zoom\API;
 use Exception;
 
 /**
- * Class PastMeeting
- * A past meeting, as returned from the server.
+ * Class PastMeeting.
+ * A past meeting, really a past meeting instance, as returned from the server.
+ *
+ * Each past meeting instance is identified by its own UUID.
+ * Many past meeting instances can be part of the same meeting, identified by property 'id'.
+ * Each instance has its own start time, participants and recording files.
  *
  * @package Chamilo\PluginBundle\Zoom\API
  */

plugin/zoom/lib/API/RecordingFile.php

@@ -5,6 +5,13 @@ namespace Chamilo\PluginBundle\Zoom\API;
 
 use Exception;
 
+/**
+ * Class RecordingFile. A video, audio or text file, part of a past meeting instance recording.
+ *
+ * @see RecordingMeeting
+ *
+ * @package Chamilo\PluginBundle\Zoom\API
+ */
 class RecordingFile
 {
     use JsonDeserializableTrait;

plugin/zoom/lib/API/RecordingList.php

@@ -6,9 +6,16 @@ namespace Chamilo\PluginBundle\Zoom\API;
 use DateTime;
 use Exception;
 
+/**
+ * Class RecordingList. A list of past meeting instance recordings generated between two dates.
+ *
+ * @see RecordingMeeting
+ *
+ * @package Chamilo\PluginBundle\Zoom\API
+ */
 class RecordingList
 {
-    use Pagination;
+    use PaginationToken;
 
     /** @var string Start Date */
     public $from;
@@ -24,20 +31,6 @@ class RecordingList
         $this->meetings = [];
     }
 
-    /**
-     * Retrieves all recordings.
-     *
-     * @param Client $client
-     *
-     * @throws Exception
-     *
-     * @return MeetingListItem[] all recordings
-     */
-    public static function loadAllRecordings($client)
-    {
-        return static::loadItems('recordings', $client, 'users/me/recordings');
-    }
-
     /**
      * Retrieves all recordings from a period of time.
      *

plugin/zoom/lib/API/RecordingMeeting.php

@@ -5,6 +5,16 @@ namespace Chamilo\PluginBundle\Zoom\API;
 
 use Exception;
 
+/**
+ * Class RecordingMeeting.
+ * A meeting instance can be recorded, hence creating an instance of this class.
+ * Contains a list of recording files.
+ *
+ * @see PastMeeting
+ * @see RecordingFile
+ *
+ * @package Chamilo\PluginBundle\Zoom\API
+ */
 class RecordingMeeting
 {
     use JsonDeserializableTrait;

plugin/zoom/lib/API/TrackingField.php

@@ -5,6 +5,11 @@ namespace Chamilo\PluginBundle\Zoom\API;
 
 use Exception;
 
+/**
+ * Class TrackingField. Instances of this class can be listed in a meeting object.
+ *
+ * @package Chamilo\PluginBundle\Zoom\API
+ */
 class TrackingField
 {
     use JsonDeserializableTrait;

plugin/zoom/lib/CourseMeeting.php

@@ -5,6 +5,12 @@ namespace Chamilo\PluginBundle\Zoom;
 
 use Exception;
 
+/**
+ * Class CourseMeeting. A remote Zoom meeting linked to a local course.
+ * An instance of this class is required to create a remote meeting from scratch.
+ *
+ * @package Chamilo\PluginBundle\Zoom
+ */
 class CourseMeeting extends API\Meeting
 {
     use CourseMeetingTrait;

plugin/zoom/lib/CourseMeetingInfoGet.php

@@ -5,6 +5,11 @@ namespace Chamilo\PluginBundle\Zoom;
 
 use Exception;
 
+/**
+ * Class CourseMeetingInfoGet. A full Meeting as returned by the server and locally linked to a course.
+ *
+ * @package Chamilo\PluginBundle\Zoom
+ */
 class CourseMeetingInfoGet extends API\MeetingInfoGet
 {
     use CourseMeetingTrait;

plugin/zoom/lib/CourseMeetingList.php

@@ -3,6 +3,13 @@
 
 namespace Chamilo\PluginBundle\Zoom;
 
+/**
+ * Class CourseMeetingList. A List of course meetings.
+ *
+ * @see CourseMeetingListItem
+ *
+ * @package Chamilo\PluginBundle\Zoom
+ */
 class CourseMeetingList extends API\MeetingList
 {
     /**

plugin/zoom/lib/CourseMeetingListItem.php

@@ -5,6 +5,13 @@ namespace Chamilo\PluginBundle\Zoom;
 
 use Exception;
 
+/**
+ * Class CourseMeetingListItem. An item from a course meeting list.
+ *
+ * @see CourseMeetingList
+ *
+ * @package Chamilo\PluginBundle\Zoom
+ */
 class CourseMeetingListItem extends API\MeetingListItem
 {
     use CourseMeetingTrait;

plugin/zoom/lib/CourseMeetingTrait.php

@@ -13,6 +13,7 @@ use Database;
 /**
  * Trait CourseMeetingTrait.
  * A Zoom meeting linked to a (course, session) pair.
+ * The course and session IDs are stored in the meeting agenda on write operations, read and removed on retrieval.
  *
  * @package Chamilo\PluginBundle\Zoom
  */

plugin/zoom/lib/DisplayableMeetingTrait.php

@@ -9,6 +9,11 @@ use DateTime;
 use DateTimeZone;
 use Exception;
 
+/**
+ * Trait DisplayableMeetingTrait. Extra properties to help formatting web views and time operations.
+ *
+ * @package Chamilo\PluginBundle\Zoom
+ */
 trait DisplayableMeetingTrait
 {
     use API\BaseMeetingTrait;

plugin/zoom/lib/File.php

@@ -5,6 +5,11 @@ namespace Chamilo\PluginBundle\Zoom;
 
 use Exception;
 
+/**
+ * Class File. A RecordingFile with extra help properties for the web view.
+ *
+ * @package Chamilo\PluginBundle\Zoom
+ */
 class File extends API\RecordingFile
 {
     /** @var string */

plugin/zoom/lib/Recording.php

@@ -8,6 +8,12 @@ use DateTime;
 use DateTimeZone;
 use Exception;
 
+/**
+ * Class Recording. A RecordingMeeting with extra help properties and a list of File instances
+ * (instead of RecordingFile instances).
+ *
+ * @package Chamilo\PluginBundle\Zoom
+ */
 class Recording extends API\RecordingMeeting
 {
     /** @var File[] List of recording file. */

plugin/zoom/lib/RecordingList.php

@@ -6,6 +6,11 @@ namespace Chamilo\PluginBundle\Zoom;
 use DateTime;
 use Exception;
 
+/**
+ * Class RecordingList. A list of past meeting instance recordings generated between two dates.
+ *
+ * @package Chamilo\PluginBundle\Zoom
+ */
 class RecordingList extends API\RecordingList
 {
     /**

plugin/zoom/lib/UserMeetingRegistrant.php

@@ -6,6 +6,11 @@ namespace Chamilo\PluginBundle\Zoom;
 use Chamilo\UserBundle\Entity\User;
 use Exception;
 
+/**
+ * Class UserMeetingRegistrant. Used to register a local user to a meeting.
+ *
+ * @package Chamilo\PluginBundle\Zoom
+ */
 class UserMeetingRegistrant extends API\MeetingRegistrant
 {
     use UserMeetingRegistrantTrait;

plugin/zoom/lib/UserMeetingRegistrantList.php

@@ -5,6 +5,13 @@ namespace Chamilo\PluginBundle\Zoom;
 
 use Exception;
 
+/**
+ * Class UserMeetingRegistrantList. A list of users registered to a meeting.
+ *
+ * @see UserMeetingRegistrantListItem
+ *
+ * @package Chamilo\PluginBundle\Zoom
+ */
 class UserMeetingRegistrantList extends API\MeetingRegistrantList
 {
     /**

plugin/zoom/lib/UserMeetingRegistrantListItem.php

@@ -5,6 +5,13 @@ namespace Chamilo\PluginBundle\Zoom;
 
 use Exception;
 
+/**
+ * Class UserMeetingRegistrantListItem. An item of a user registrant list.
+ *
+ * @see UserMeetingRegistrantList
+ *
+ * @package Chamilo\PluginBundle\Zoom
+ */
 class UserMeetingRegistrantListItem extends API\MeetingRegistrantListItem
 {
     use UserMeetingRegistrantTrait;

plugin/zoom/lib/UserMeetingRegistrantTrait.php

@@ -6,6 +6,13 @@ namespace Chamilo\PluginBundle\Zoom;
 use Chamilo\UserBundle\Entity\User;
 use Database;
 
+/**
+ * Trait UserMeetingRegistrantTrait.
+ * A Zoom meeting registrant linked to a local user.
+ * The user id is stored in the registrant's email address on write operations, read and removed on retrieval.
+ *
+ * @package Chamilo\PluginBundle\Zoom
+ */
 trait UserMeetingRegistrantTrait
 {
     /** @var bool whether the remote zoom record contains a local user's identifier */

plugin/zoom/lib/zoom_plugin.class.php

@@ -18,6 +18,9 @@ use Chamilo\PluginBundle\Zoom\RecordingList;
 use Chamilo\PluginBundle\Zoom\UserMeetingRegistrant;
 use Chamilo\PluginBundle\Zoom\UserMeetingRegistrantListItem;
 
+/**
+ * Class ZoomPlugin. Integrates Zoom meetings in courses.
+ */
 class ZoomPlugin extends Plugin
 {
     public $isCoursePlugin = true;