Merge pull request #29661 from nextcloud/enhancement/calendar-search-properties-api

Document and type allowed property names for calendar property searches

2 files changed, 77 insertions, 5 deletions

diff --git a/apps/dav/lib/CalDAV/CalDavBackend.php b/apps/dav/lib/CalDAV/CalDavBackend.php
index 7094358a2c6..5aa499be159 100644
--- a/apps/dav/lib/CalDAV/CalDavBackend.php
+++ b/apps/dav/lib/CalDAV/CalDavBackend.php
@@ -170,10 +170,25 @@ class CalDavBackend extends AbstractBackend implements SyncSupport, Subscription
 		'{http://calendarserver.org/ns/}subscribed-strip-attachments' => 'stripattachments',
 	];
 
-	/** @var array properties to index */
-	public static $indexProperties = ['CATEGORIES', 'COMMENT', 'DESCRIPTION',
-		'LOCATION', 'RESOURCES', 'STATUS', 'SUMMARY', 'ATTENDEE', 'CONTACT',
-		'ORGANIZER'];
+	/**
+	 * properties to index
+	 *
+	 * This list has to be kept in sync with ICalendarQuery::SEARCH_PROPERTY_*
+	 *
+	 * @see \OCP\Calendar\ICalendarQuery
+	 */
+	private const INDEXED_PROPERTIES = [
+		'CATEGORIES',
+		'COMMENT',
+		'DESCRIPTION',
+		'LOCATION',
+		'RESOURCES',
+		'STATUS',
+		'SUMMARY',
+		'ATTENDEE',
+		'CONTACT',
+		'ORGANIZER'
+	];
 
 	/** @var array parameters to index */
 	public static $indexParameters = [
@@ -2948,7 +2963,7 @@ class CalDavBackend extends AbstractBackend implements SyncSupport, Subscription
 			}
 
 			foreach ($component->children() as $property) {
-				if (in_array($property->name, self::$indexProperties)) {
+				if (in_array($property->name, self::INDEXED_PROPERTIES, true)) {
 					$value = $property->getValue();
 					// is this a shitty db?
 					if (!$this->db->supports4ByteText()) {
diff --git a/lib/public/Calendar/ICalendarQuery.php b/lib/public/Calendar/ICalendarQuery.php
index 142810d3fb9..6a1fff619f6 100644
--- a/lib/public/Calendar/ICalendarQuery.php
+++ b/lib/public/Calendar/ICalendarQuery.php
@@ -23,6 +23,7 @@ declare(strict_types=1);
  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  *
  */
+
 namespace OCP\Calendar;
 
 use DateTimeImmutable;
@@ -35,6 +36,56 @@ use DateTimeImmutable;
 interface ICalendarQuery {
 
 	/**
+	 * @since 24.0.0
+	 */
+	public const SEARCH_PROPERTY_CATEGORIES = 'CATEGORIES';
+
+	/**
+	 * @since 24.0.0
+	 */
+	public const SEARCH_PROPERTY_COMMENT = 'COMMENT';
+
+	/**
+	 * @since 24.0.0
+	 */
+	public const SEARCH_PROPERTY_DESCRIPTION = 'DESCRIPTION';
+
+	/**
+	 * @since 24.0.0
+	 */
+	public const SEARCH_PROPERTY_LOCATION = 'LOCATION';
+
+	/**
+	 * @since 24.0.0
+	 */
+	public const SEARCH_PROPERTY_RESOURCES = 'RESOURCES';
+
+	/**
+	 * @since 24.0.0
+	 */
+	public const SEARCH_PROPERTY_STATUS = 'STATUS';
+
+	/**
+	 * @since 24.0.0
+	 */
+	public const SEARCH_PROPERTY_SUMMARY = 'SUMMARY';
+
+	/**
+	 * @since 24.0.0
+	 */
+	public const SEARCH_PROPERTY_ATTENDEE = 'ATTENDEE';
+
+	/**
+	 * @since 24.0.0
+	 */
+	public const SEARCH_PROPERTY_CONTACT = 'CONTACT';
+
+	/**
+	 * @since 24.0.0
+	 */
+	public const SEARCH_PROPERTY_ORGANIZER = 'ORGANIZER';
+
+	/**
 	 * Limit the results to the calendar uri(s)
 	 *
 	 * @since 23.0.0
@@ -51,6 +102,12 @@ interface ICalendarQuery {
 	/**
 	 * Define the property name(s) to search for
 	 *
+	 * Note: Nextcloud only indexes *some* properties. You can not search for
+	 *       arbitrary properties.
+	 *
+	 * @param string $value any of the ICalendarQuery::SEARCH_PROPERTY_* values
+	 * @psalm-param ICalendarQuery::SEARCH_PROPERTY_* $value
+	 *
 	 * @since 23.0.0
 	 */
 	public function addSearchProperty(string $value): void;