Merge pull request dokuwiki#4420 from dokuwiki/api-mediahistory

splitbrain · web-flow · commit 3ab4aa6a7ada · 2025-04-09T20:23:37.000+02:00
Add core.getMediaHistory API endpoint
diff --git a/_test/tests/Remote/ApiCoreTest.php b/_test/tests/Remote/ApiCoreTest.php
@@ -856,6 +856,53 @@ public function testGetMediaInfo()
         $this->assertEquals(221, $e->getCode(), 'Non existing media id given');
     }
 
+    //core.getMediaHistory
+    public function testGetMediaHistory()
+    {
+        global $conf;
+
+        $_SERVER['REMOTE_USER'] = 'testuser';
+
+        //image to be uploaded
+        $orig = mediaFN('wiki:dokuwiki-128.png');
+        $tmp = $conf['tmpdir'] . 'test.png';
+
+        //create image to be revised
+        $id = 'test:image3.png';
+        $media = mediaFN($id);
+
+        $rev = [];
+        for ($i = 0; $i < 2; $i++) {
+            $this->waitForTick();
+            copy($orig, $tmp);
+            media_save(['name' => $tmp], $id, true, AUTH_UPLOAD, 'rename');
+            $rev[$i] = filemtime($media);
+        }
+
+        $params = ['media' => $id, 'first' => 0]; // offset 0
+        $versions = $this->remote->call('core.getMediaHistory', $params);
+        $versions = json_decode(json_encode($versions), true);
+        $this->assertEquals(2, count($versions));
+        $this->assertEquals($rev[1], $versions[0]['revision']);
+        $this->assertEquals($rev[0], $versions[1]['revision']);
+
+        $params = ['media' => $id, 'first' => 1]; // offset 1
+        $versions = $this->remote->call('core.getMediaHistory', $params);
+        $versions = json_decode(json_encode($versions), true);
+        $this->assertEquals(1, count($versions));
+        $this->assertEquals($rev[0], $versions[0]['revision']);
+
+        $params = ['media' => $id, 'first' => 2]; // offset 2
+        $versions = $this->remote->call('core.getMediaHistory', $params);
+        $versions = json_decode(json_encode($versions), true);
+        $this->assertEquals(0, count($versions));
+
+        $params = ['media' => $id, 'first' => 2]; // offset 3
+        $versions = $this->remote->call('core.getMediaHistory', $params);
+        $versions = json_decode(json_encode($versions), true);
+        $this->assertEquals(0, count($versions));
+    }
+
     //core.saveMedia
     public function testSaveMedia()
     {
diff --git a/inc/Remote/ApiCore.php b/inc/Remote/ApiCore.php
@@ -4,6 +4,7 @@
 
 use Doku_Renderer_xhtml;
 use dokuwiki\ChangeLog\PageChangeLog;
+use dokuwiki\ChangeLog\MediaChangeLog;
 use dokuwiki\Extension\AuthPlugin;
 use dokuwiki\Extension\Event;
 use dokuwiki\Remote\Response\Link;
@@ -22,7 +23,7 @@
 class ApiCore
 {
     /** @var int Increased whenever the API is changed */
-    public const API_VERSION = 13;
+    public const API_VERSION = 14;
 
     /**
      * Returns details about the core methods
@@ -65,7 +66,7 @@ public function getMethods()
             'core.getMedia' => new ApiCall([$this, 'getMedia'], 'media'),
             'core.getMediaInfo' => new ApiCall([$this, 'getMediaInfo'], 'media'),
             'core.getMediaUsage' => new ApiCall([$this, 'getMediaUsage'], 'media'),
-            // todo: implement getMediaHistory
+            'core.getMediaHistory' => new ApiCall([$this, 'getMediaHistory'], 'media'),
 
             'core.saveMedia' => new ApiCall([$this, 'saveMedia'], 'media'),
             'core.deleteMedia' => new ApiCall([$this, 'deleteMedia'], 'media'),
@@ -463,7 +464,7 @@ public function getPageInfo($page, $rev = 0, $author = false, $hash = false)
     /**
      * Returns a list of available revisions of a given wiki page
      *
-     * The number of returned pages is set by `$conf['recent']`, but non accessible revisions pages
+     * The number of returned pages is set by `$conf['recent']`, but non accessible revisions
      * are skipped, so less than that may be returned.
      *
      * @link https://www.dokuwiki.org/config:recent
@@ -834,6 +835,11 @@ public function getMedia($media, $rev = 0)
             throw new AccessDeniedException('You are not allowed to read this media file', 211);
         }
 
+        // was the current revision requested?
+        if ($this->isCurrentMediaRev($media, $rev)) {
+            $rev = 0;
+        }
+
         $file = mediaFN($media, $rev);
         if (!@ file_exists($file)) {
             throw new RemoteException('The requested media file (revision) does not exist', 221);
@@ -865,6 +871,12 @@ public function getMediaInfo($media, $rev = 0, $author = false, $hash = false)
         if (auth_quickaclcheck($media) < AUTH_READ) {
             throw new AccessDeniedException('You are not allowed to read this media file', 211);
         }
+
+        // was the current revision requested?
+        if ($this->isCurrentMediaRev($media, $rev)) {
+            $rev = 0;
+        }
+
         if (!media_exists($media, $rev)) {
             throw new RemoteException('The requested media file does not exist', 221);
         }
@@ -903,6 +915,62 @@ public function getMediaUsage($media)
         return ft_mediause($media);
     }
 
+    /**
+     * Returns a list of available revisions of a given media file
+     *
+     * The number of returned files is set by `$conf['recent']`, but non accessible revisions
+     * are skipped, so less than that may be returned.
+     *
+     * Since API Version 14
+     *
+     * @link https://www.dokuwiki.org/config:recent
+     * @param string $media file id
+     * @param int $first skip the first n changelog lines, 0 starts at the current revision
+     * @return MediaChange[]
+     * @throws AccessDeniedException
+     * @throws RemoteException
+     * @author
+     */
+    public function getMediaHistory($media, $first = 0)
+    {
+        global $conf;
+
+        $media = cleanID($media);
+        // check that this media exists
+        if (auth_quickaclcheck($media) < AUTH_READ) {
+            throw new AccessDeniedException('You are not allowed to read this media file', 211);
+        }
+        if (!media_exists($media, 0)) {
+            throw new RemoteException('The requested media file does not exist', 221);
+        }
+
+        $medialog = new MediaChangeLog($media);
+        $medialog->setChunkSize(1024);
+        // old revisions are counted from 0, so we need to subtract 1 for the current one
+        $revisions = $medialog->getRevisions($first - 1, $conf['recent']);
+
+        $result = [];
+        foreach ($revisions as $rev) {
+            // the current revision needs to be checked against the current file path
+            $check = $this->isCurrentMediaRev($media, $rev) ? '' : $rev;
+            if (!media_exists($media, $check)) continue; // skip non-existing revisions
+
+            $info = $medialog->getRevisionInfo($rev);
+
+            $result[] = new MediaChange(
+                $media,
+                $rev,
+                $info['user'],
+                $info['ip'],
+                $info['sum'],
+                $info['type'],
+                $info['sizechange']
+            );
+        }
+
+        return $result;
+    }
+
     /**
      * Uploads a file to the wiki
      *
@@ -987,6 +1055,20 @@ public function deleteMedia($media)
         }
     }
 
+    /**
+     * Check if the given revision is the current revision of this file
+     *
+     * @param string $id
+     * @param int $rev
+     * @return bool
+     */
+    protected function isCurrentMediaRev(string $id, int $rev)
+    {
+        $current = @filemtime(mediaFN($id));
+        if ($current === $rev) return true;
+        return false;
+    }
+
     // endregion
 
 
