diff options
Diffstat (limited to 'core/Controller/ReferenceApiController.php')
| -rw-r--r-- | core/Controller/ReferenceApiController.php | 47 |
1 files changed, 41 insertions, 6 deletions
diff --git a/core/Controller/ReferenceApiController.php b/core/Controller/ReferenceApiController.php index 3df2e41c2a9..c16ca348d88 100644 --- a/core/Controller/ReferenceApiController.php +++ b/core/Controller/ReferenceApiController.php @@ -5,6 +5,7 @@ declare(strict_types=1); * @copyright Copyright (c) 2022 Julius Härtl <jus@bitgrid.net> * * @author Julius Härtl <jus@bitgrid.net> + * @author Kate Döen <kate.doeen@nextcloud.com> * * @license GNU AGPL version 3 or any later version * @@ -24,11 +25,18 @@ declare(strict_types=1); namespace OC\Core\Controller; +use OCA\Core\ResponseDefinitions; +use OCP\AppFramework\Http; use OCP\AppFramework\Http\DataResponse; use OCP\Collaboration\Reference\IDiscoverableReferenceProvider; use OCP\Collaboration\Reference\IReferenceManager; +use OCP\Collaboration\Reference\Reference; use OCP\IRequest; +/** + * @psalm-import-type CoreReference from ResponseDefinitions + * @psalm-import-type CoreReferenceProvider from ResponseDefinitions + */ class ReferenceApiController extends \OCP\AppFramework\OCSController { public function __construct( string $appName, @@ -41,6 +49,13 @@ class ReferenceApiController extends \OCP\AppFramework\OCSController { /** * @NoAdminRequired + * + * Extract references from a text + * + * @param string $text Text to extract from + * @param bool $resolve Resolve the references + * @param int $limit Maximum amount of references to extract + * @return DataResponse<Http::STATUS_OK, array{references: array<string, CoreReference|mixed|null>}, array{}> */ public function extract(string $text, bool $resolve = false, int $limit = 1): DataResponse { $references = $this->referenceManager->extractReferences($text); @@ -52,7 +67,7 @@ class ReferenceApiController extends \OCP\AppFramework\OCSController { break; } - $result[$reference] = $resolve ? $this->referenceManager->resolveReference($reference) : null; + $result[$reference] = $resolve ? $this->referenceManager->resolveReference($reference)->jsonSerialize() : null; } return new DataResponse([ @@ -62,11 +77,17 @@ class ReferenceApiController extends \OCP\AppFramework\OCSController { /** * @NoAdminRequired + * + * Resolve a reference + * + * @param string $reference Reference to resolve + * @return DataResponse<Http::STATUS_OK, array{references: array<string, ?CoreReference>}, array{}> */ public function resolveOne(string $reference): DataResponse { - $resolvedReference = $this->referenceManager->resolveReference(trim($reference)); + /** @var ?CoreReference $resolvedReference */ + $resolvedReference = $this->referenceManager->resolveReference(trim($reference))?->jsonSerialize(); - $response = new DataResponse(['references' => [ $reference => $resolvedReference ]]); + $response = new DataResponse(['references' => [$reference => $resolvedReference]]); $response->cacheFor(3600, false, true); return $response; } @@ -74,7 +95,11 @@ class ReferenceApiController extends \OCP\AppFramework\OCSController { /** * @NoAdminRequired * - * @param string[] $references + * Resolve multiple references + * + * @param string[] $references References to resolve + * @param int $limit Maximum amount of references to resolve + * @return DataResponse<Http::STATUS_OK, array{references: array<string, CoreReference|mixed|null>}, array{}> */ public function resolve(array $references, int $limit = 1): DataResponse { $result = []; @@ -84,16 +109,20 @@ class ReferenceApiController extends \OCP\AppFramework\OCSController { break; } - $result[$reference] = $this->referenceManager->resolveReference($reference); + $result[$reference] = $this->referenceManager->resolveReference($reference)?->jsonSerialize(); } return new DataResponse([ - 'references' => array_filter($result) + 'references' => $result ]); } /** * @NoAdminRequired + * + * Get the providers + * + * @return DataResponse<Http::STATUS_OK, CoreReferenceProvider[], array{}> */ public function getProvidersInfo(): DataResponse { $providers = $this->referenceManager->getDiscoverableProviders(); @@ -105,6 +134,12 @@ class ReferenceApiController extends \OCP\AppFramework\OCSController { /** * @NoAdminRequired + * + * Touch a provider + * + * @param string $providerId ID of the provider + * @param int|null $timestamp Timestamp of the last usage + * @return DataResponse<Http::STATUS_OK, array{success: bool}, array{}> */ public function touchProvider(string $providerId, ?int $timestamp = null): DataResponse { if ($this->userId !== null) { |