IReferenceManager.php 2.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384
  1. <?php
  2. declare(strict_types=1);
  3. /**
  4. * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors
  5. * SPDX-License-Identifier: AGPL-3.0-or-later
  6. */
  7. namespace OCP\Collaboration\Reference;
  8. /**
  9. * @since 25.0.0
  10. */
  11. interface IReferenceManager {
  12. /**
  13. * Return all reference identifiers within a string as an array
  14. *
  15. * @return string[] Array of found references (urls)
  16. * @since 25.0.0
  17. */
  18. public function extractReferences(string $text): array;
  19. /**
  20. * Resolve a given reference id to its metadata with all available providers
  21. *
  22. * This method has a fallback to always provide the open graph metadata,
  23. * but may still return null in case this is disabled or the fetching fails
  24. *
  25. * @since 25.0.0
  26. * @since 30.0.0 optional arguments `$public` and `$sharingToken`
  27. */
  28. public function resolveReference(string $referenceId, bool $public = false, string $sharingToken = ''): ?IReference;
  29. /**
  30. * Get a reference by its cache key
  31. *
  32. * @since 25.0.0
  33. */
  34. public function getReferenceByCacheKey(string $cacheKey): ?IReference;
  35. /**
  36. * Explicitly get a reference from the cache to avoid heavy fetches for cases
  37. * the cache can then be filled with a separate request from the frontend
  38. *
  39. * @since 25.0.0
  40. * @since 30.0.0 optional arguments `$public` and `$sharingToken`
  41. */
  42. public function getReferenceFromCache(string $referenceId, bool $public = false, string $sharingToken = ''): ?IReference;
  43. /**
  44. * Invalidate all cache entries with a prefix or just one if the cache key is provided
  45. *
  46. * @since 25.0.0
  47. */
  48. public function invalidateCache(string $cachePrefix, ?string $cacheKey = null): void;
  49. /**
  50. * Get information on discoverable reference providers (id, title, icon and order)
  51. * If the provider is searchable, also get the list of supported unified search providers
  52. *
  53. * @return IDiscoverableReferenceProvider[]
  54. * @since 26.0.0
  55. */
  56. public function getDiscoverableProviders(): array;
  57. /**
  58. * Update or set the last used timestamp for a provider
  59. *
  60. * @param string $userId
  61. * @param string $providerId
  62. * @param int|null $timestamp use current timestamp if null
  63. * @return bool
  64. * @since 26.0.0
  65. */
  66. public function touchProvider(string $userId, string $providerId, ?int $timestamp = null): bool;
  67. /**
  68. * Get all known last used timestamps for reference providers
  69. *
  70. * @return int[]
  71. * @since 26.0.0
  72. */
  73. public function getUserProviderTimestamps(): array;
  74. }