WIP docs

catalyst · Jul 22, 2024 · 280ae32 · 280ae32
1 parent 2b0ee43
commit 280ae32
Show file tree

Hide file tree

Showing 8 changed files with 377 additions and 272 deletions.
diff --git a/classes/local/manager.php b/classes/local/manager.php
@@ -330,10 +330,10 @@ public static function get_available_fs_list() {
      * @return string
      */
     public static function get_client_classname_from_fs($filesystem) {
-		// Unit tests.
-		if($filesystem == '\tool_objectfs\tests\test_file_system') {
-			return '\tool_objectfs\tests\test_client';
-		}
+        // Unit tests need to return the test client.
+        if($filesystem == '\tool_objectfs\tests\test_file_system') {
+            return '\tool_objectfs\tests\test_client';
+        }
         $clientclass = str_replace('_file_system', '', $filesystem);
         return str_replace('tool_objectfs\\', 'tool_objectfs\\local\\store\\', $clientclass.'\\client');
     }

diff --git a/classes/local/store/object_client.php b/classes/local/store/object_client.php
@@ -25,6 +25,8 @@
 
 namespace tool_objectfs\local\store;
 
+use stdClass;
+
 interface object_client {
 
     /**
@@ -120,8 +122,6 @@ public function test_connection();
      */
     public function test_permissions($testdelete);
 
-	public function test_set_object_tag();
-
     /**
      * proxy_range_request
      * @param \stored_file $file
@@ -139,10 +139,24 @@ public function proxy_range_request(\stored_file $file, $ranges);
      */
     public function test_range_request($filesystem);
 
-	public function set_object_tags(string $contenthash, array $tags);
+    /**
+     * Tests setting an objects tag.
+     * @return stdClass containing 'success' and 'details' properties
+     */
+    public function test_set_object_tag(): stdClass;
 
-	public function supports_object_tagging(): bool;
+    /**
+     * Set the given objects tags in the external store.
+     * @param string $contenthash file content hash
+     * @param array $tags array of key=>value pairs to set as tags.
+     */
+    public function set_object_tags(string $contenthash, array $tags);
 
+    /**
+     * If the client supports object tagging feature.
+     * @return bool true if supports, else false
+     */
+    public function supports_object_tagging(): bool;
 }
 
 
diff --git a/classes/local/store/object_client_base.php b/classes/local/store/object_client_base.php
@@ -25,6 +25,8 @@
 
 namespace tool_objectfs\local\store;
 
+use stdClass;
+
 /**
  * [Description object_client_base]
  */
@@ -188,15 +190,28 @@ public function test_permissions($testdelete) {
         return (object)['success' => false, 'details' => ''];
     }
 
-	public function test_set_object_tag() {
-		return (object)['success' => false, 'details' => ''];
-	}
+    /**
+     * Tests setting an objects tag.
+     * @return stdClass containing 'success' and 'details' properties
+     */
+    public function test_set_object_tag(): stdClass {
+        return (object)['success' => false, 'details' => ''];
+    }
 
-	public function set_object_tags(string $contenthash, array $tags) {
-		return;
-	}
+    /**
+     * Set the given objects tags in the external store.
+     * @param string $contenthash file content hash
+     * @param array $tags array of key=>value pairs to set as tags.
+     */
+    public function set_object_tags(string $contenthash, array $tags) {
+        return;
+    }
 
-	public function supports_object_tagging(): bool {
-		return false;
-	}
+    /**
+     * If the client supports object tagging feature.
+     * @return bool true if supports, else false
+     */
+    public function supports_object_tagging(): bool {
+        return false;
+    }
 }
diff --git a/classes/local/store/object_file_system.php b/classes/local/store/object_file_system.php
@@ -354,7 +354,6 @@ public function copy_object_from_local_to_external_by_hash($contenthash, $object
 
         if ($initiallocation === OBJECT_LOCATION_LOCAL) {
             $success = $this->copy_from_local_to_external($contenthash);
-
             if ($success) {
                 $finallocation = OBJECT_LOCATION_DUPLICATED;
             }

diff --git a/classes/local/store/s3/client.php b/classes/local/store/s3/client.php
@@ -29,6 +29,7 @@
 use tool_objectfs\local\store\object_client_base;
 use tool_objectfs\local\store\signed_url;
 use local_aws\admin_settings_aws_region;
+use stdClass;
 use Throwable;
 
 define('AWS_API_VERSION', '2006-03-01');
@@ -391,42 +392,6 @@ public function test_permissions($testdelete) {
         return $permissions;
     }
 
-	public function test_set_object_tag() {
-		try {
-			// First ensure a test object exists to put tags on.	
-			// Note this will override the existing object if exists.
-			$key = $this->bucketkeyprefix . 'tagging_check_file';
-
-			$this->client->putObject([
-				'Bucket' => $this->bucket,
-				'Key' => $key, 
-				'Body' => 'test content'
-			]);
-
-		    // Next try to tag it - this will throw an exception if cannot set
-			// (for example, because it does not have permissions to).
-			$this->client->putObjectTagging([
-				'Bucket' => $this->bucket,
-				'Key' => $key,
-				'Tagging' => [
-					'TagSet' => [
-						[
-							'Key' => 'test',
-							'Value' => 'test',
-						]
-					]
-				]
-			]);
-		} catch (Throwable $e) {
-			return (object) [
-				'success' => false,
-				'details' => $e->getMessage(),
-			];	
-		}
-
-		// Success - no exceptions thrown.
-		return (object) ['success' => true, 'details' => ''];
-	}
 
     /**
      * get_exception_details
@@ -905,30 +870,80 @@ public function test_range_request($filesystem) {
         return (object)['result' => false, 'error' => get_string('fixturefilemissing', 'tool_objectfs')];
     }
 
-	public function set_object_tags(string $contenthash, array $tags) {
-		// First convert PHP array tags to XML string.
-		$s3tags = [];
-
-		foreach($tags as $key => $value) {
-			$s3tags[] = [
-				'Key' => $key,
-				'Value' => $value,
-			];
-		}
-
-		$key = $this->bucketkeyprefix . $this->get_filepath_from_hash($contenthash);
-
-		// Then put onto object.
-		$this->client->putObjectTagging([
-			'Bucket' => $this->bucket,
-			'Key' => $key,
-			'Tagging' => [
-				'TagSet' => $s3tags
-			]
-		]);
-	}
-
-	public function supports_object_tagging(): bool {
-		return true;
-	}
+    /**
+     * Tests setting an objects tag.
+     * @return stdClass containing 'success' and 'details' properties
+     */
+    public function test_set_object_tag(): stdClass {
+        try {
+            // First ensure a test object exists to put tags on.	
+            // Note this will override the existing object if exists.
+            $key = $this->bucketkeyprefix . 'tagging_check_file';
+
+            $this->client->putObject([
+                'Bucket' => $this->bucket,
+                'Key' => $key, 
+                'Body' => 'test content'
+            ]);
+
+            // Next try to tag it - this will throw an exception if cannot set
+            // (for example, because it does not have permissions to).
+            $this->client->putObjectTagging([
+                'Bucket' => $this->bucket,
+                'Key' => $key,
+                'Tagging' => [
+                    'TagSet' => [
+                        [
+                            'Key' => 'test',
+                            'Value' => 'test',
+                        ]
+                    ]
+                ]
+            ]);
+        } catch (Throwable $e) {
+            return (object) [
+                'success' => false,
+                'details' => $e->getMessage(),
+            ];	
+        }
+
+        // Success - no exceptions thrown.
+        return (object) ['success' => true, 'details' => ''];
+    }
+
+    /**
+     * Set the given objects tags in the external store.
+     * @param string $contenthash file content hash
+     * @param array $tags array of key=>value pairs to set as tags.
+     */
+    public function set_object_tags(string $contenthash, array $tags) {
+        // First convert PHP array tags to XML string.
+        $s3tags = [];
+
+        foreach($tags as $key => $value) {
+            $s3tags[] = [
+                'Key' => $key,
+                'Value' => $value,
+            ];
+        }
+
+        $key = $this->bucketkeyprefix . $this->get_filepath_from_hash($contenthash);
+
+        // Then put onto object.
+        $this->client->putObjectTagging([
+            'Bucket' => $this->bucket,
+            'Key' => $key,
+            'Tagging' => [
+                'TagSet' => $s3tags
+            ]
+        ]);
+    }
+
+    /**
+     * If the client supports object tagging feature.
+     * @return bool true if supports, else false
+     */
+    public function supports_object_tagging(): bool {
+        return true;
+    }
 }
diff --git a/classes/local/store/s3/file_system.php b/classes/local/store/s3/file_system.php
@@ -96,7 +96,7 @@ public function copy_from_local_to_external($contenthash) {
             return false;
         }
     }
-	
+
     /**
      * supports_presigned_urls
      * @return bool

diff --git a/classes/local/tag/file_type_source.php b/classes/local/tag/file_type_source.php
@@ -30,34 +30,34 @@ class file_type_source implements tag_source {
     /**
      * @var string Unknown/uncategorised
      */
-	public const TYPE_UNCATEGORISED = 'uncategorised';
+    public const TYPE_UNCATEGORISED = 'uncategorised';
 
     /**
      * @var string A course backup
      */
-	public const TYPE_COURSE_BACKUP = 'course_backup';
+    public const TYPE_COURSE_BACKUP = 'course_backup';
 
     /**
      * Identifier used in tagging file. Is the 'key' of the tag.
      * @return string
      */
-	public static function get_identifier(): string {
-		return 'type';
-	}
+    public static function get_identifier(): string {
+        return 'type';
+    }
 
     /**
      * Returns the tag value for the given file contenthash
      * @param string $contenthash
      * @return string|null the category of the file, one of TYPE_*
      */
-	public function get_value_for_contenthash(string $contenthash): ?string {
+    public function get_value_for_contenthash(string $contenthash): ?string {
         global $DB;
         // TODO are there other unknown course backup files ?
         $iscoursebackup = $DB->record_exists('files', ['contenthash' => $contenthash, 'component' => 'backup', 'filearea' => 'course']);
         if ($iscoursebackup) {
             return self::TYPE_COURSE_BACKUP;
         }
 
-		return self::TYPE_UNCATEGORISED;
-	}
+        return self::TYPE_UNCATEGORISED;
+    }
 }
-Original file line number
+Diff line change
@@ Expand Up / @@ -96,7 +96,7 @@ public function copy_from_local_to_external($contenthash) { @@
                 return false;
             }
         }
         /**
          * supports_presigned_urls
          * @return bool
@@ Expand Down @@