From f8f551358486c13aff95feb66a23a63c91deae2a Mon Sep 17 00:00:00 2001
From: Andreas Gohr <andi@splitbrain.org>
Date: Thu, 30 Nov 2023 19:57:15 +0100
Subject: First go at refactoring the API mechanisms

This introduces an ApiCall class that wraps around the actual method
that produces the result. This replaces various loose array structures
that provided the meta information before.

The ApiCall streamlines the aggregation of meta information between core
and plugin methods. Now all data is produced by Reflection based
introspection. Certain aspects can be overridden if needed. See
ApiCore::getRemoteInfo() for examples

This change removes the _getMethods() method from remote plugins and
introduces a getMethods() method. The two are NOT compatible as the
latter now returns a list of ApiCalls. However when looking at the
existing plugins, it seems that _getMethods() was nearly 100% obsolete
with the Reflection based default implementation. So most plugins will
not be affected at all. Some might now export one or two more methods
than before because of poor visibility settings (eg. not declaring
private/protected methods as such).

This change removes the RPC_CALL_ADD hook. Only a single plugin ever
implemented it. I'm not sure what this hook was supposed to do anyway.
Being able to declare arbitrarily named API endpoints seems wrong to me
anyway.

The new ApiCall now also supports passing named instead of positional
parameters. This will open up a new opportunity to get a proper openapi
spec running.

Next step is fixing the tests.
---
 _test/tests/Remote/ApiCallTest.php | 98 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 98 insertions(+)
 create mode 100644 _test/tests/Remote/ApiCallTest.php

(limited to '_test')

diff --git a/_test/tests/Remote/ApiCallTest.php b/_test/tests/Remote/ApiCallTest.php
new file mode 100644
index 000000000..8f7404c2d
--- /dev/null
+++ b/_test/tests/Remote/ApiCallTest.php
@@ -0,0 +1,98 @@
+<?php
+
+namespace dokuwiki\test\Remote;
+
+use dokuwiki\Remote\ApiCall;
+
+class ApiCallTest extends \DokuWikiTest
+{
+    /**
+     * This is a test
+     *
+     * With more information
+     * in several lines
+     * @param string $foo First variable
+     * @param int $bar
+     * @something else
+     * @something other
+     * @another tag
+     * @return string  The return
+     */
+    public function dummyMethod1($foo, $bar)
+    {
+        return 'dummy';
+    }
+
+    public function testMethodDocBlock()
+    {
+        $call = new ApiCall([$this, 'dummyMethod1']);
+
+        $this->assertEquals('This is a test', $call->getSummary());
+        $this->assertEquals("With more information\nin several lines", $call->getDescription());
+
+        $this->assertEquals(
+            [
+                'foo' => [
+                    'type' => 'string',
+                    'description' => 'First variable',
+                ],
+                'bar' => [
+                    'type' => 'int',
+                    'description' => '',
+                ]
+            ],
+            $call->getArgs()
+        );
+
+        $this->assertEquals(
+            [
+                'type' => 'string',
+                'description' => 'The return'
+            ],
+            $call->getReturn()
+        );
+
+        // remove one parameter
+        $call->limitArgs(['foo']);
+        $this->assertEquals(
+            [
+                'foo' => [
+                    'type' => 'string',
+                    'description' => 'First variable',
+                ],
+            ],
+            $call->getArgs()
+        );
+    }
+
+    public function testFunctionDocBlock()
+    {
+        $call = new ApiCall('date');
+        $call->setArgDescription('format', 'The format');
+
+        $this->assertEquals(
+            [
+                'format' => [
+                    'type' => 'string',
+                    'description' => 'The format',
+                ],
+                'timestamp' => [
+                    'type' => 'int',
+                    'description' => '',
+                ]
+            ],
+            $call->getArgs()
+        );
+    }
+
+    public function testExecution()
+    {
+        $call = new ApiCall([$this, 'dummyMethod1']);
+        $this->assertEquals('dummy', $call(['bar', 1]), 'positional parameters');
+        $this->assertEquals('dummy', $call(['foo' => 'bar', 'bar' => 1]), 'named parameters');
+
+        $call = new ApiCall('date');
+        $this->assertEquals('2023-11-30', $call(['Y-m-d', 1701356591]), 'positional parameters');
+        $this->assertEquals('2023-11-30', $call(['format' => 'Y-m-d', 'timestamp' => 1701356591]), 'named parameters');
+    }
+}
-- 
cgit v1.2.3