[redcap] Improve REDCap module 2 (#9904)

Contains a bunch of small improvements to the redcap module. It
is a preparatory PR to the import records script (#9905) but the changes
do make sense by themselves.

- Simplify `RedcapHttpCLient` URL parameter.
- Include record ID and unique event name in REDCap API records.
- Decouple REDCap record import from REDCap notification handling using
a new `RedcapRecordImporter` class.

Author: MaximeBICMTL

modules/redcap/php/client/models/records/redcaprecord.class.inc

@@ -26,10 +26,14 @@ use LORIS\redcap\client\RedcapProps;
 class RedcapRecord
 {
     /**
-     * The date at which the record was completed if it was completed using a
-     * survey.
+     * The REDCap record ID.
      */
-    public readonly ?\DateTimeImmutable $datetime;
+    public readonly string $record_id;
+
+    /**
+     * The REDCap unique event name.
+     */
+    public readonly string $unique_event_name;
 
     /**
      * The record completion status.
@@ -39,6 +43,12 @@ class RedcapRecord
      */
     public readonly int $complete;
 
+    /**
+     * The date and time at which the record was completed. This is an undocumented
+     * field in the REDCap API.
+     */
+    public readonly ?\DateTimeImmutable $datetime;
+
     private string $_form_name;
 
     private array $_props;
@@ -67,8 +77,10 @@ class RedcapRecord
             $datetime = null;
         }
 
-        $this->datetime = $datetime;
-        $this->complete = $props->getInt("{$form_name}_complete");
+        $this->record_id         = $props->getString('record_id');
+        $this->unique_event_name = $props->getString('redcap_event_name');
+        $this->datetime          = $datetime;
+        $this->complete          = $props->getInt("{$form_name}_complete");
     }
 
     /**

modules/redcap/php/client/redcaphttpclient.class.inc

@@ -46,7 +46,7 @@ class RedcapHttpClient
     private bool $_verbose;
 
     /**
-     * REDCap URL.
+     * REDCap API URL.
      */
     private string $_url;
 
@@ -70,18 +70,20 @@ class RedcapHttpClient
     /**
      * Create a new REDCap Client for a specific REDCap instance and project.
      *
-     * @param string $instance_api_url  A REDCap instance API URL.
+     * @param string $instance_url      A REDCap instance URL.
      * @param string $project_api_token A REDCap project API token.
      * @param bool   $verbose           Verbose mode.
      */
     public function __construct(
-        string $instance_api_url,
+        string $instance_url,
         string $project_api_token,
         bool $verbose = false
     ) {
-        $this->_url     = $instance_api_url;
+        $trimmed_url    = rtrim($instance_url, '/');
+        $api_url        = "{$trimmed_url}/api/";
+        $this->_url     = $api_url;
         $this->_token   = $project_api_token;
-        $this->_client  = new Client($instance_api_url);
+        $this->_client  = new Client($api_url);
         $this->_verbose = $verbose;
     }
 
@@ -784,7 +786,9 @@ class RedcapHttpClient
             'type'                   => 'flat',
             'csvDelimiter'           => '',
             'forms'                  => $instrument_names,
-            'fields'                 => [],
+            // The 'record_id' parameter adds both the 'record_id' and
+            // 'redcap_event_name' fields to the REDCap records.
+            'fields'                 => ['record_id'],
             'events'                 => $unique_event_names,
             'records'                => $record_ids,
             'rawOrLabel'             => 'raw',

modules/redcap/php/endpoints/notifications.class.inc

@@ -162,7 +162,7 @@ class Notifications extends Endpoint
         // get a new redcap client based on the notification info
         try {
             $redcap_client = new RedcapHttpClient(
-                "{$config->redcap_instance_url}/api/",
+                $config->redcap_instance_url,
                 $config->redcap_api_token,
             );
 

modules/redcap/php/redcapmapper.class.inc

@@ -89,25 +89,22 @@ class RedcapMapper
      * session creation is enabled for that visit in the REDCap module
      * configuration, or throws an error if it is not.
      *
-     * @param RedcapRecord $redcap_record     The REDCap record.
-     * @param string       $unique_event_name The unique event name associated with
-     *                                        that REDCap record.
-     * @param \Candidate   $candidate         The LORIS candidate associated with
-     *                                        that REDCap record.
+     * @param RedcapRecord $redcap_record The REDCap record.
+     * @param \Candidate   $candidate     The LORIS candidate associated with
+     *                                    that REDCap record.
      *
      * @return string The visit label of the relevant session.
      */
     public function getVisitLabel(
         RedcapRecord $redcap_record,
-        string $unique_event_name,
         \Candidate $candidate,
     ): string {
-        $visit_config = $this->getVisitConfig($unique_event_name);
+        $visit_config = $this->getVisitConfig($redcap_record->unique_event_name);
 
         // If no visit mappings are defined in the configuration, use the REDCap
         // unique event name as the visit label directly.
         if ($visit_config === null) {
-            return $unique_event_name;
+            return $redcap_record->unique_event_name;
         }
 
         $session = $this->checkOrCreateSession($candidate, $visit_config);
@@ -140,7 +137,7 @@ class RedcapMapper
         // Find the REDCap event that matches the REDCap notification event.
         $redcap_event = array_find(
             $redcap_events,
-            fn($redcap_event) => $unique_event_name === $redcap_event->unique_name,
+            fn($redcap_event) => $redcap_event->unique_name === $unique_event_name,
         );
 
         // There should always be a REDCap event that matches the REDCap