MDL-33453 Make it clear what search_references() and search_references_count() are...
authorDavid Mudrák <david@moodle.com>
Fri, 22 Jun 2012 13:22:27 +0000 (15:22 +0200)
committerDavid Mudrák <david@moodle.com>
Tue, 26 Jun 2012 14:28:30 +0000 (16:28 +0200)
Initially it was not clear enough that these two methods are supposed to
be used for looking for references to a stored_file only. So the docs
comments are improved and unittests added to illustrate the usage.

The patch also removes the unittest for get_references_by_storedfile()
as its usage is already covered in other test methods.

lib/filestorage/file_storage.php
lib/filestorage/tests/file_storage_test.php

index 933c5c3..2b248d1 100644 (file)
@@ -1656,6 +1656,7 @@ class file_storage {
      *
      * @param string $str
      * @param bool $cleanparams if set to true, array elements will be passed through {@link clean_param()}
+     * @throws file_reference_exception if the $str does not have the expected format
      * @return array
      */
     public static function unpack_reference($str, $cleanparams = false) {
@@ -1681,7 +1682,13 @@ class file_storage {
     }
 
     /**
-     * Returns all aliases that link to an external file identified by the given reference
+     * Returns all aliases that refer to some stored_file via the given reference
+     *
+     * All repositories that provide access to a stored_file are expected to use
+     * {@link self::pack_reference()}. This method can't be used if the given reference
+     * does not use this format or if you are looking for references to an external file
+     * (for example it can't be used to search for all aliases that refer to a given
+     * Dropbox or Box.net file).
      *
      * Aliases in user draft areas are excluded from the returned list.
      *
@@ -1695,6 +1702,10 @@ class file_storage {
             throw new coding_exception('NULL is not a valid reference to an external file');
         }
 
+        // Give {@link self::unpack_reference()} a chance to throw exception if the
+        // reference is not in a valid format.
+        self::unpack_reference($reference);
+
         $referencehash = sha1($reference);
 
         $sql = "SELECT ".self::instance_sql_fields('f', 'r')."
@@ -1714,7 +1725,13 @@ class file_storage {
     }
 
     /**
-     * Returns the number of aliases that link to an external file identified by the given reference
+     * Returns the number of aliases that refer to some stored_file via the given reference
+     *
+     * All repositories that provide access to a stored_file are expected to use
+     * {@link self::pack_reference()}. This method can't be used if the given reference
+     * does not use this format or if you are looking for references to an external file
+     * (for example it can't be used to count aliases that refer to a given Dropbox or
+     * Box.net file).
      *
      * Aliases in user draft areas are not counted.
      *
@@ -1728,6 +1745,10 @@ class file_storage {
             throw new coding_exception('NULL is not a valid reference to an external file');
         }
 
+        // Give {@link self::unpack_reference()} a chance to throw exception if the
+        // reference is not in a valid format.
+        self::unpack_reference($reference);
+
         $referencehash = sha1($reference);
 
         $sql = "SELECT COUNT(f.id)
@@ -1737,7 +1758,7 @@ class file_storage {
                  WHERE r.referencehash = ?
                        AND (f.component <> ? OR f.filearea <> ?)";
 
-        return $DB->count_records_sql($sql, array($referencehash, 'user', 'draft'));
+        return (int)$DB->count_records_sql($sql, array($referencehash, 'user', 'draft'));
     }
 
     /**
index d787bba..dfc4fa0 100644 (file)
@@ -400,16 +400,6 @@ class filestoragelib_testcase extends advanced_testcase {
         $this->assertFalse($doesntexist);
     }
 
-    public function test_get_references_by_storedfile() {
-        $user = $this->setup_three_private_files();
-        $fs = get_file_storage();
-
-        $areafiles = $fs->get_area_files($user->ctxid, 'user', 'private');
-        $testfile = reset($areafiles);
-        $references = $fs->get_references_by_storedfile($testfile);
-        // TODO MDL-33368 Verify result!!
-    }
-
     public function test_get_external_files() {
         $user = $this->setup_three_private_files();
         $fs = get_file_storage();
@@ -583,15 +573,75 @@ class filestoragelib_testcase extends advanced_testcase {
     }
 
     public function test_search_references() {
+        $user = $this->setup_three_private_files();
         $fs = get_file_storage();
-        $references = $fs->search_references('testsearch');
-        // TODO MDL-33368 Verify result!!
-    }
+        $repos = repository::get_instances(array('type'=>'user'));
+        $repo = reset($repos);
 
-    public function test_search_references_count() {
-        $fs = get_file_storage();
-        $references = $fs->search_references_count('testsearch');
-        // TODO MDL-33368 Verify result!!
+        $alias1 = array(
+            'contextid' => $user->ctxid,
+            'component' => 'user',
+            'filearea'  => 'private',
+            'itemid'    => 0,
+            'filepath'  => '/aliases/',
+            'filename'  => 'alias-to-1.txt'
+        );
+
+        $alias2 = array(
+            'contextid' => $user->ctxid,
+            'component' => 'user',
+            'filearea'  => 'private',
+            'itemid'    => 0,
+            'filepath'  => '/aliases/',
+            'filename'  => 'another-alias-to-1.txt'
+        );
+
+        $reference = file_storage::pack_reference(array(
+            'contextid' => $user->ctxid,
+            'component' => 'user',
+            'filearea'  => 'private',
+            'itemid'    => 0,
+            'filepath'  => '/',
+            'filename'  => '1.txt'
+        ));
+
+        // There are no aliases now.
+        $result = $fs->search_references($reference);
+        $this->assertEquals(array(), $result);
+
+        $result = $fs->search_references_count($reference);
+        $this->assertSame($result, 0);
+
+        // Create two aliases and make sure they are returned.
+        $fs->create_file_from_reference($alias1, $repo->id, $reference);
+        $fs->create_file_from_reference($alias2, $repo->id, $reference);
+
+        $result = $fs->search_references($reference);
+        $this->assertTrue(is_array($result));
+        $this->assertEquals(count($result), 2);
+        foreach ($result as $alias) {
+            $this->assertTrue($alias instanceof stored_file);
+        }
+
+        $result = $fs->search_references_count($reference);
+        $this->assertSame($result, 2);
+
+        // The method can't be used for references to files outside the filepool
+        $exceptionthrown = false;
+        try {
+            $fs->search_references('http://dl.dropbox.com/download/1234567/naked-dougiamas.jpg');
+        } catch (file_reference_exception $e) {
+            $exceptionthrown = true;
+        }
+        $this->assertTrue($exceptionthrown);
+
+        $exceptionthrown = false;
+        try {
+            $fs->search_references_count('http://dl.dropbox.com/download/1234567/naked-dougiamas.jpg');
+        } catch (file_reference_exception $e) {
+            $exceptionthrown = true;
+        }
+        $this->assertTrue($exceptionthrown);
     }
 
     public function test_delete_area_files() {