migrate therinaldos.com data

wedding-pics/lib/public/FilesMetadata/AMetadataEvent.php

@@ -0,0 +1,68 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * @copyright 2023 Maxence Lange <maxence@artificial-owl.com>
+ *
+ * @author Maxence Lange <maxence@artificial-owl.com>
+ *
+ * @license GNU AGPL version 3 or any later version
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+namespace OCP\FilesMetadata;
+
+use OCP\EventDispatcher\Event;
+use OCP\Files\Node;
+use OCP\FilesMetadata\Model\IFilesMetadata;
+
+/**
+ * @since 28.0.0
+ */
+abstract class AMetadataEvent extends Event {
+	/**
+	 * @param Node $node
+	 * @param IFilesMetadata $metadata
+	 * @since 28.0.0
+	 */
+	public function __construct(
+		protected Node $node,
+		protected IFilesMetadata $metadata
+	) {
+		parent::__construct();
+	}
+
+	/**
+	 * returns related node
+	 *
+	 * @return Node
+	 * @since 28.0.0
+	 */
+	public function getNode(): Node {
+		return $this->node;
+	}
+
+	/**
+	 * returns metadata. if known, it already contains data from the database.
+	 * If the object is modified using its setters, changes are stored in database at the end of the event.
+	 *
+	 * @return IFilesMetadata
+	 * @since 28.0.0
+	 */
+	public function getMetadata(): IFilesMetadata {
+		return $this->metadata;
+	}
+}

wedding-pics/lib/public/FilesMetadata/Event/MetadataBackgroundEvent.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * @copyright 2023 Maxence Lange <maxence@artificial-owl.com>
+ *
+ * @author Maxence Lange <maxence@artificial-owl.com>
+ *
+ * @license GNU AGPL version 3 or any later version
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+namespace OCP\FilesMetadata\Event;
+
+use OCP\FilesMetadata\AMetadataEvent;
+
+/**
+ * MetadataBackgroundEvent is an event similar to MetadataLiveEvent but dispatched
+ * on a background thread instead of live thread. Meaning there is no limit to
+ * the time required for the generation of your metadata.
+ *
+ * @see AMetadataEvent::getMetadata()
+ * @see AMetadataEvent::getNode()
+ * @since 28.0.0
+ */
+class MetadataBackgroundEvent extends AMetadataEvent {
+}

wedding-pics/lib/public/FilesMetadata/Event/MetadataLiveEvent.php

@@ -0,0 +1,67 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * @copyright 2023 Maxence Lange <maxence@artificial-owl.com>
+ *
+ * @author Maxence Lange <maxence@artificial-owl.com>
+ *
+ * @license GNU AGPL version 3 or any later version
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+namespace OCP\FilesMetadata\Event;
+
+use OCP\FilesMetadata\AMetadataEvent;
+
+/**
+ * MetadataLiveEvent is an event initiated when a file is created or updated.
+ * The app contains the Node related to the created/updated file, and a FilesMetadata that already
+ * contains the currently known metadata.
+ *
+ * Setting new metadata, or modifying already existing metadata with different value, will trigger
+ * the save of the metadata in the database.
+ *
+ * @see AMetadataEvent::getMetadata()
+ * @see AMetadataEvent::getNode()
+ * @see MetadataLiveEvent::requestBackgroundJob()
+ * @since 28.0.0
+ */
+class MetadataLiveEvent extends AMetadataEvent {
+	private bool $runAsBackgroundJob = false;
+
+	/**
+	 * For heavy process, call this method if your app prefers to update metadata on a
+	 * background/cron job, instead of the live process.
+	 * A similar MetadataBackgroundEvent will be broadcast on next cron tick.
+	 *
+	 * @return void
+	 * @since 28.0.0
+	 */
+	public function requestBackgroundJob(): void {
+		$this->runAsBackgroundJob = true;
+	}
+
+	/**
+	 * return true if any app that catch this event requested a re-run as background job
+	 *
+	 * @return bool
+	 * @since 28.0.0
+	 */
+	public function isRunAsBackgroundJobRequested(): bool {
+		return $this->runAsBackgroundJob;
+	}
+}

wedding-pics/lib/public/FilesMetadata/Event/MetadataNamedEvent.php

@@ -0,0 +1,74 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * @copyright 2023 Maxence Lange <maxence@artificial-owl.com>
+ *
+ * @author Maxence Lange <maxence@artificial-owl.com>
+ *
+ * @license GNU AGPL version 3 or any later version
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+namespace OCP\FilesMetadata\Event;
+
+use OCP\Files\Node;
+use OCP\FilesMetadata\AMetadataEvent;
+use OCP\FilesMetadata\Model\IFilesMetadata;
+
+/**
+ * MetadataNamedEvent is an event similar to MetadataBackgroundEvent completed with a target name,
+ * used to limit the refresh of metadata only listeners capable of filtering themselves out.
+ *
+ * Meaning that when using this event, your app must implement a filter on the event's registered
+ * name returned by getName()
+ *
+ * This event is mostly triggered when a registered name is added to the files scan
+ *    i.e. ./occ files:scan --generate-metadata [name]
+ *
+ * @see AMetadataEvent::getMetadata()
+ * @see AMetadataEvent::getNode()
+ * @see MetadataNamedEvent::getName()
+ * @since 28.0.0
+ */
+class MetadataNamedEvent extends AMetadataEvent {
+	/**
+	 * @param Node $node
+	 * @param IFilesMetadata $metadata
+	 * @param string $name name assigned to the event
+	 *
+	 * @since 28.0.0
+	 */
+	public function __construct(
+		Node $node,
+		IFilesMetadata $metadata,
+		private string $name = ''
+	) {
+		parent::__construct($node, $metadata);
+	}
+
+	/**
+	 * get the assigned name for the event.
+	 * This is used to know if your app is the called one when running the
+	 *    ./occ files:scan --generate-metadata [name]
+	 *
+	 * @return string
+	 * @since 28.0.0
+	 */
+	public function getName(): string {
+		return $this->name;
+	}
+}

wedding-pics/lib/public/FilesMetadata/Exceptions/FilesMetadataException.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * @copyright 2023 Maxence Lange <maxence@artificial-owl.com>
+ *
+ * @author Maxence Lange <maxence@artificial-owl.com>
+ *
+ * @license GNU AGPL version 3 or any later version
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+namespace OCP\FilesMetadata\Exceptions;
+
+use Exception;
+
+/**
+ * @since 28.0.0
+ */
+class FilesMetadataException extends Exception {
+}

wedding-pics/lib/public/FilesMetadata/Exceptions/FilesMetadataKeyFormatException.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * @copyright 2023 Maxence Lange <maxence@artificial-owl.com>
+ *
+ * @author Maxence Lange <maxence@artificial-owl.com>
+ *
+ * @license GNU AGPL version 3 or any later version
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+namespace OCP\FilesMetadata\Exceptions;
+
+/**
+ * @since 28.0.0
+ */
+class FilesMetadataKeyFormatException extends FilesMetadataException {
+}

wedding-pics/lib/public/FilesMetadata/Exceptions/FilesMetadataNotFoundException.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * @copyright 2023 Maxence Lange <maxence@artificial-owl.com>
+ *
+ * @author Maxence Lange <maxence@artificial-owl.com>
+ *
+ * @license GNU AGPL version 3 or any later version
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+namespace OCP\FilesMetadata\Exceptions;
+
+/**
+ * @since 28.0.0
+ */
+class FilesMetadataNotFoundException extends FilesMetadataException {
+}

wedding-pics/lib/public/FilesMetadata/Exceptions/FilesMetadataTypeException.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * @copyright 2023 Maxence Lange <maxence@artificial-owl.com>
+ *
+ * @author Maxence Lange <maxence@artificial-owl.com>
+ *
+ * @license GNU AGPL version 3 or any later version
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+namespace OCP\FilesMetadata\Exceptions;
+
+/**
+ * @since 28.0.0
+ */
+class FilesMetadataTypeException extends FilesMetadataException {
+}

wedding-pics/lib/public/FilesMetadata/IFilesMetadataManager.php

@@ -0,0 +1,169 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * @copyright 2023 Maxence Lange <maxence@artificial-owl.com>
+ *
+ * @author Maxence Lange <maxence@artificial-owl.com>
+ *
+ * @license GNU AGPL version 3 or any later version
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+namespace OCP\FilesMetadata;
+
+use OCP\DB\QueryBuilder\IQueryBuilder;
+use OCP\Files\Node;
+use OCP\FilesMetadata\Exceptions\FilesMetadataException;
+use OCP\FilesMetadata\Exceptions\FilesMetadataNotFoundException;
+use OCP\FilesMetadata\Model\IFilesMetadata;
+use OCP\FilesMetadata\Model\IMetadataValueWrapper;
+
+/**
+ * Manager for FilesMetadata; manage files' metadata.
+ *
+ * @since 28.0.0
+ */
+interface IFilesMetadataManager {
+	/** @since 28.0.0 */
+	public const PROCESS_LIVE = 1;
+	/** @since 28.0.0 */
+	public const PROCESS_BACKGROUND = 2;
+	/** @since 28.0.0 */
+	public const PROCESS_NAMED = 4;
+
+	/**
+	 * initiate the process of refreshing the metadata in relation to a node
+	 * usually, this process:
+	 * - get current metadata from database, if available, or create a new one
+	 * - dispatch a MetadataLiveEvent,
+	 * - save new metadata in database, if metadata have been changed during the event
+	 * - refresh metadata indexes if needed,
+	 * - prep a new cronjob if an app request it during the event,
+	 *
+	 * @param Node $node related node
+	 * @param int $process type of process
+	 * @param string $namedEvent limit process to a named event
+	 *
+	 * @return IFilesMetadata
+	 * @see self::PROCESS_BACKGROUND
+	 * @see self::PROCESS_LIVE
+	 * @see self::PROCESS_NAMED
+	 * @since 28.0.0
+	 */
+	public function refreshMetadata(
+		Node $node,
+		int $process = self::PROCESS_LIVE,
+		string $namedEvent = ''
+	): IFilesMetadata;
+
+	/**
+	 * returns metadata of a file id
+	 *
+	 * @param int $fileId file id
+	 * @param boolean $generate Generate if metadata does not exist
+	 *
+	 * @return IFilesMetadata
+	 * @throws FilesMetadataNotFoundException if not found
+	 * @since 28.0.0
+	 */
+	public function getMetadata(int $fileId, bool $generate = false): IFilesMetadata;
+
+	/**
+	 * returns metadata of multiple file ids
+	 *
+	 * @param int[] $fileIds file ids
+	 *
+	 * @return array File ID is the array key, files without metadata are not returned in the array
+	 * @psalm-return array<int, IFilesMetadata>
+	 * @since 28.0.0
+	 */
+	public function getMetadataForFiles(array $fileIds): array;
+
+	/**
+	 * save metadata to database and refresh indexes.
+	 * metadata are saved if new data are available.
+	 * on update, a check on syncToken is done to avoid conflict (race condition)
+	 *
+	 * @param IFilesMetadata $filesMetadata
+	 *
+	 * @throws FilesMetadataException if metadata seems malformed
+	 * @since 28.0.0
+	 */
+	public function saveMetadata(IFilesMetadata $filesMetadata): void;
+
+	/**
+	 * delete metadata and its indexes
+	 *
+	 * @param int $fileId file id
+	 *
+	 * @return void
+	 * @since 28.0.0
+	 */
+	public function deleteMetadata(int $fileId): void;
+
+	/**
+	 * generate and return a MetadataQuery to help building sql queries
+	 *
+	 * @param IQueryBuilder $qb
+	 * @param string $fileTableAlias alias of the table that contains data about files
+	 * @param string $fileIdField alias of the field that contains file ids
+	 *
+	 * @return IMetadataQuery|null NULL if table are not set yet or never used
+	 * @see IMetadataQuery
+	 * @since 28.0.0
+	 */
+	public function getMetadataQuery(
+		IQueryBuilder $qb,
+		string $fileTableAlias,
+		string $fileIdField
+	): ?IMetadataQuery;
+
+	/**
+	 * returns all type of metadata currently available.
+	 * The list is stored in a IFilesMetadata with null values but correct type.
+	 *
+	 * @return IFilesMetadata
+	 * @since 28.0.0
+	 */
+	public function getKnownMetadata(): IFilesMetadata;
+
+	/**
+	 * initiate a metadata key with its type.
+	 * The call is mandatory before using the metadata property in a webdav request.
+	 * It is not needed to only use this method when the app is enabled: the method can be
+	 * called each time during the app loading as the metadata will only be initiated if not known
+	 *
+	 * @param string $key metadata key
+	 * @param string $type metadata type
+	 * @param bool $indexed TRUE if metadata can be search
+	 * @param int $editPermission remote edit permission via Webdav PROPPATCH
+	 *
+	 * @see IMetadataValueWrapper::TYPE_INT
+	 * @see IMetadataValueWrapper::TYPE_FLOAT
+	 * @see IMetadataValueWrapper::TYPE_BOOL
+	 * @see IMetadataValueWrapper::TYPE_ARRAY
+	 * @see IMetadataValueWrapper::TYPE_STRING_LIST
+	 * @see IMetadataValueWrapper::TYPE_INT_LIST
+	 * @see IMetadataValueWrapper::TYPE_STRING
+	 * @see IMetadataValueWrapper::EDIT_FORBIDDEN
+	 * @see IMetadataValueWrapper::EDIT_REQ_OWNERSHIP
+	 * @see IMetadataValueWrapper::EDIT_REQ_WRITE_PERMISSION
+	 * @see IMetadataValueWrapper::EDIT_REQ_READ_PERMISSION
+	 * @since 28.0.0
+	 */
+	public function initMetadata(string $key, string $type, bool $indexed, int $editPermission): void;
+}

wedding-pics/lib/public/FilesMetadata/IMetadataQuery.php

@@ -0,0 +1,92 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * @copyright 2023 Maxence Lange <maxence@artificial-owl.com>
+ *
+ * @author Maxence Lange <maxence@artificial-owl.com>
+ *
+ * @license GNU AGPL version 3 or any later version
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+namespace OCP\FilesMetadata;
+
+use OCP\FilesMetadata\Model\IFilesMetadata;
+
+/**
+ * Model that help building queries with metadata and metadata indexes
+ *
+ * @since 28.0.0
+ */
+interface IMetadataQuery {
+	/** @since 28.0.0 */
+	public const EXTRA = 'metadata';
+
+	/**
+	 * Add metadata linked to file id to the query
+	 *
+	 * @see self::extractMetadata()
+	 * @since 28.0.0
+	 */
+	public function retrieveMetadata(): void;
+
+	/**
+	 * extract metadata from a result row
+	 *
+	 * @param array $row result row
+	 *
+	 * @return IFilesMetadata metadata
+	 * @see self::retrieveMetadata()
+	 * @since 28.0.0
+	 */
+	public function extractMetadata(array $row): IFilesMetadata;
+
+	/**
+	 * join the metadata_index table, based on a metadataKey.
+	 * This will prep the query for condition based on this specific metadataKey.
+	 * If a link to the metadataKey already exists, returns known alias.
+	 *
+	 * TODO: investigate how to support a search done on multiple values for same key (AND).
+	 *
+	 * @param string $metadataKey metadata key
+	 * @param bool $enforce limit the request only to existing metadata
+	 *
+	 * @return string generated table alias
+	 * @since 28.0.0
+	 */
+	public function joinIndex(string $metadataKey, bool $enforce = false): string;
+
+	/**
+	 * returns the name of the field for metadata key to be used in query expressions
+	 *
+	 * @param string $metadataKey metadata key
+	 *
+	 * @return string table field
+	 * @since 28.0.0
+	 */
+	public function getMetadataKeyField(string $metadataKey): string;
+
+	/**
+	 * returns the name of the field for metadata string value to be used in query expressions
+	 *
+	 * @param string $metadataKey metadata key
+	 *
+	 * @return string table field
+	 * @since 28.0.0
+	 */
+	public function getMetadataValueField(string $metadataKey): string;
+}

wedding-pics/lib/public/FilesMetadata/Model/IFilesMetadata.php

@@ -0,0 +1,367 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * @copyright 2023 Maxence Lange <maxence@artificial-owl.com>
+ *
+ * @author Maxence Lange <maxence@artificial-owl.com>
+ *
+ * @license GNU AGPL version 3 or any later version
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+namespace OCP\FilesMetadata\Model;
+
+use JsonSerializable;
+use OCP\FilesMetadata\Exceptions\FilesMetadataNotFoundException;
+use OCP\FilesMetadata\Exceptions\FilesMetadataTypeException;
+
+/**
+ * Model that represent metadata linked to a specific file.
+ *
+ * Example of json stored in the database
+ * {
+ *   "mymeta": {
+ *     "value": "this is a test",
+ *     "type": "string",
+ *     "indexed": false,
+ *     "editPermission": 1
+ *   },
+ *   "myapp-anothermeta": {
+ *     "value": 42,
+ *     "type": "int",
+ *     "indexed": true,
+ *     "editPermission": 0
+ *   }
+ * }
+ *
+ * @see IMetadataValueWrapper
+ * @since 28.0.0
+ */
+interface IFilesMetadata extends JsonSerializable {
+	/**
+	 * returns the file id linked to this metadata
+	 *
+	 * @return int related file id
+	 * @since 28.0.0
+	 */
+	public function getFileId(): int;
+
+	/**
+	 * returns last time metadata were updated in the database
+	 *
+	 * @return int timestamp
+	 * @since 28.0.0
+	 */
+	public function lastUpdateTimestamp(): int;
+
+	/**
+	 * returns the token known at the time the metadata were extracted from database
+	 *
+	 * @return string token
+	 * @since 28.0.0
+	 */
+	public function getSyncToken(): string;
+
+	/**
+	 * returns all current metadata keys
+	 *
+	 * @return string[] list of keys
+	 * @since 28.0.0
+	 */
+	public function getKeys(): array;
+
+	/**
+	 * returns true if search metadata key exists
+	 *
+	 * @param string $needle metadata key to search
+	 *
+	 * @return bool TRUE if key exist
+	 * @since 28.0.0
+	 */
+	public function hasKey(string $needle): bool;
+
+	/**
+	 * return the list of metadata keys set as indexed
+	 *
+	 * @return string[] list of indexes
+	 * @since 28.0.0
+	 */
+	public function getIndexes(): array;
+
+	/**
+	 * returns true if key exists and is set as indexed
+	 *
+	 * @param string $key metadata key
+	 *
+	 * @return bool
+	 * @since 28.0.0
+	 */
+	public function isIndex(string $key): bool;
+
+	/**
+	 * set remote edit permission
+	 * (Webdav PROPPATCH)
+	 *
+	 * @param string $key metadata key
+	 * @param int $permission remote edit permission
+	 *
+	 * @since 28.0.0
+	 */
+	public function setEditPermission(string $key, int $permission): void;
+
+	/**
+	 * returns remote edit permission
+	 * (Webdav PROPPATCH)
+	 *
+	 * @param string $key metadata key
+	 *
+	 * @return int
+	 * @since 28.0.0
+	 */
+	public function getEditPermission(string $key): int;
+
+	/**
+	 * returns string value for a metadata key
+	 *
+	 * @param string $key metadata key
+	 *
+	 * @return string metadata value
+	 * @throws FilesMetadataNotFoundException
+	 * @throws FilesMetadataTypeException
+	 * @since 28.0.0
+	 */
+	public function getString(string $key): string;
+
+	/**
+	 * returns int value for a metadata key
+	 *
+	 * @param string $key metadata key
+	 *
+	 * @return int metadata value
+	 * @throws FilesMetadataNotFoundException
+	 * @throws FilesMetadataTypeException
+	 * @since 28.0.0
+	 */
+	public function getInt(string $key): int;
+
+	/**
+	 * returns float value for a metadata key
+	 *
+	 * @param string $key metadata key
+	 *
+	 * @return float metadata value
+	 * @throws FilesMetadataNotFoundException
+	 * @throws FilesMetadataTypeException
+	 * @since 28.0.0
+	 */
+	public function getFloat(string $key): float;
+
+	/**
+	 * returns bool value for a metadata key
+	 *
+	 * @param string $key metadata key
+	 *
+	 * @return bool metadata value
+	 * @throws FilesMetadataNotFoundException
+	 * @throws FilesMetadataTypeException
+	 * @since 28.0.0
+	 */
+	public function getBool(string $key): bool;
+
+	/**
+	 * returns array for a metadata key
+	 *
+	 * @param string $key metadata key
+	 *
+	 * @return array metadata value
+	 * @throws FilesMetadataNotFoundException
+	 * @throws FilesMetadataTypeException
+	 * @since 28.0.0
+	 */
+	public function getArray(string $key): array;
+
+	/**
+	 * returns string[] value for a metadata key
+	 *
+	 * @param string $key metadata key
+	 *
+	 * @return string[] metadata value
+	 * @throws FilesMetadataNotFoundException
+	 * @throws FilesMetadataTypeException
+	 * @since 28.0.0
+	 */
+	public function getStringList(string $key): array;
+
+	/**
+	 * returns int[] value for a metadata key
+	 *
+	 * @param string $key metadata key
+	 *
+	 * @return int[] metadata value
+	 * @throws FilesMetadataNotFoundException
+	 * @throws FilesMetadataTypeException
+	 * @since 28.0.0
+	 */
+	public function getIntList(string $key): array;
+
+	/**
+	 * returns the value type of the metadata (string, int, ...)
+	 *
+	 * @param string $key metadata key
+	 *
+	 * @return string value type
+	 * @throws FilesMetadataNotFoundException
+	 * @see IMetadataValueWrapper::TYPE_STRING
+	 * @see IMetadataValueWrapper::TYPE_INT
+	 * @see IMetadataValueWrapper::TYPE_FLOAT
+	 * @see IMetadataValueWrapper::TYPE_BOOL
+	 * @see IMetadataValueWrapper::TYPE_ARRAY
+	 * @see IMetadataValueWrapper::TYPE_STRING_LIST
+	 * @see IMetadataValueWrapper::TYPE_INT_LIST
+	 * @since 28.0.0
+	 */
+	public function getType(string $key): string;
+
+	/**
+	 * set a metadata key/value pair for string value
+	 *
+	 * @param string $key metadata key
+	 * @param string $value metadata value
+	 * @param bool $index set TRUE if value must be indexed
+	 *
+	 * @return self
+	 * @since 28.0.0
+	 */
+	public function setString(string $key, string $value, bool $index = false): self;
+
+	/**
+	 * set a metadata key/value pair for int value
+	 *
+	 * @param string $key metadata key
+	 * @param int $value metadata value
+	 * @param bool $index set TRUE if value must be indexed
+	 *
+	 * @return self
+	 * @since 28.0.0
+	 */
+	public function setInt(string $key, int $value, bool $index = false): self;
+
+	/**
+	 * set a metadata key/value pair for float value
+	 *
+	 * @param string $key metadata key
+	 * @param float $value metadata value
+	 *
+	 * @return self
+	 * @since 28.0.0
+	 */
+	public function setFloat(string $key, float $value): self;
+
+	/**
+	 * set a metadata key/value pair for bool value
+	 *
+	 * @param string $key metadata key
+	 * @param bool $value metadata value
+	 * @param bool $index set TRUE if value must be indexed
+	 *
+	 * @return self
+	 * @since 28.0.0
+	 */
+	public function setBool(string $key, bool $value, bool $index = false): self;
+
+	/**
+	 * set a metadata key/value pair for array
+	 *
+	 * @param string $key metadata key
+	 * @param array $value metadata value
+	 *
+	 * @return self
+	 * @since 28.0.0
+	 */
+	public function setArray(string $key, array $value): self;
+
+	/**
+	 * set a metadata key/value pair for list of string
+	 *
+	 * @param string $key metadata key
+	 * @param string[] $value metadata value
+	 * @param bool $index set TRUE if each values from the list must be indexed
+	 *
+	 * @return self
+	 * @since 28.0.0
+	 */
+	public function setStringList(string $key, array $value, bool $index = false): self;
+
+	/**
+	 * set a metadata key/value pair for list of int
+	 *
+	 * @param string $key metadata key
+	 * @param int[] $value metadata value
+	 * @param bool $index set TRUE if each values from the list must be indexed
+	 *
+	 * @return self
+	 * @since 28.0.0
+	 */
+	public function setIntList(string $key, array $value, bool $index = false): self;
+
+	/**
+	 * unset a metadata
+	 *
+	 * @param string $key metadata key
+	 *
+	 * @return self
+	 * @since 28.0.0
+	 */
+	public function unset(string $key): self;
+
+	/**
+	 * unset metadata with key starting with prefix
+	 *
+	 * @param string $keyPrefix metadata key prefix
+	 *
+	 * @return self
+	 * @since 28.0.0
+	 */
+	public function removeStartsWith(string $keyPrefix): self;
+
+	/**
+	 * returns true if object have been updated since last import
+	 *
+	 * @return bool TRUE if metadata have been modified
+	 * @since 28.0.0
+	 */
+	public function updated(): bool;
+
+	/**
+	 * returns metadata in a simple array with METADATA_KEY => METADATA_VALUE
+	 *
+	 * @return array metadata
+	 * @since 28.0.0
+	 */
+	public function asArray(): array;
+
+	/**
+	 * deserialize the object from a json
+	 *
+	 * @param array $data serialized version of the object
+	 *
+	 * @return self
+	 * @see jsonSerialize
+	 * @since 28.0.0
+	 */
+	public function import(array $data): self;
+}

wedding-pics/lib/public/FilesMetadata/Model/IMetadataValueWrapper.php

@@ -0,0 +1,334 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * @copyright 2023 Maxence Lange <maxence@artificial-owl.com>
+ *
+ * @author Maxence Lange <maxence@artificial-owl.com>
+ *
+ * @license GNU AGPL version 3 or any later version
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+namespace OCP\FilesMetadata\Model;
+
+use JsonSerializable;
+use OCP\FilesMetadata\Exceptions\FilesMetadataNotFoundException;
+use OCP\FilesMetadata\Exceptions\FilesMetadataTypeException;
+
+/**
+ * Model that store the value of a single metadata.
+ * It stores the value, its type and the index status.
+ *
+ * @see IFilesMetadata
+ * @since 28.0.0
+ */
+interface IMetadataValueWrapper extends JsonSerializable {
+	/** @since 28.0.0 */
+	public const TYPE_STRING = 'string';
+	/** @since 28.0.0 */
+	public const TYPE_INT = 'int';
+	/** @since 28.0.0 */
+	public const TYPE_FLOAT = 'float';
+	/** @since 28.0.0 */
+	public const TYPE_BOOL = 'bool';
+	/** @since 28.0.0 */
+	public const TYPE_ARRAY = 'array';
+	/** @since 28.0.0 */
+	public const TYPE_STRING_LIST = 'string[]';
+	/** @since 28.0.0 */
+	public const TYPE_INT_LIST = 'int[]';
+
+	/** @since 28.0.0 */
+	public const EDIT_FORBIDDEN = 0;
+	/** @since 28.0.0 */
+	public const EDIT_REQ_OWNERSHIP = 1;
+	/** @since 28.0.0 */
+	public const EDIT_REQ_WRITE_PERMISSION = 2;
+	/** @since 28.0.0 */
+	public const EDIT_REQ_READ_PERMISSION = 3;
+
+
+	/**
+	 * Unless a call of import() to deserialize an object is expected, a valid value type is needed here.
+	 *
+	 * @param string $type value type
+	 *
+	 * @see self::TYPE_INT
+	 * @see self::TYPE_FLOAT
+	 * @see self::TYPE_BOOL
+	 * @see self::TYPE_ARRAY
+	 * @see self::TYPE_STRING_LIST
+	 * @see self::TYPE_INT_LIST
+	 * @see self::TYPE_STRING
+	 * @since 28.0.0
+	 */
+	public function __construct(string $type);
+
+	/**
+	 * returns the value type
+	 *
+	 * @return string value type
+	 * @see self::TYPE_INT
+	 * @see self::TYPE_FLOAT
+	 * @see self::TYPE_BOOL
+	 * @see self::TYPE_ARRAY
+	 * @see self::TYPE_STRING_LIST
+	 * @see self::TYPE_INT_LIST
+	 * @see self::TYPE_STRING
+	 * @since 28.0.0
+	 */
+	public function getType(): string;
+
+	/**
+	 * returns if the set value type is the one expected
+	 *
+	 * @param string $type value type
+	 *
+	 * @return bool
+	 * @see self::TYPE_INT
+	 * @see self::TYPE_FLOAT
+	 * @see self::TYPE_BOOL
+	 * @see self::TYPE_ARRAY
+	 * @see self::TYPE_STRING_LIST
+	 * @see self::TYPE_INT_LIST
+	 * @see self::TYPE_STRING
+	 * @since 28.0.0
+	 */
+	public function isType(string $type): bool;
+
+	/**
+	 * throws an exception if the type is not correctly set
+	 *
+	 * @param string $type value type
+	 *
+	 * @return self
+	 * @throws FilesMetadataTypeException if type cannot be confirmed
+	 * @see self::TYPE_INT
+	 * @see self::TYPE_BOOL
+	 * @see self::TYPE_ARRAY
+	 * @see self::TYPE_STRING_LIST
+	 * @see self::TYPE_INT_LIST
+	 * @see self::TYPE_STRING
+	 * @see self::TYPE_FLOAT
+	 * @since 28.0.0
+	 */
+	public function assertType(string $type): self;
+
+	/**
+	 * set a string value
+	 *
+	 * @param string $value string to be set as value
+	 *
+	 * @return self
+	 * @throws FilesMetadataTypeException if wrapper was not set to store a string
+	 * @since 28.0.0
+	 */
+	public function setValueString(string $value): self;
+
+	/**
+	 * set a int value
+	 *
+	 * @param int $value int to be set as value
+	 *
+	 * @return self
+	 * @throws FilesMetadataTypeException if wrapper was not set to store an int
+	 * @since 28.0.0
+	 */
+	public function setValueInt(int $value): self;
+
+	/**
+	 * set a float value
+	 *
+	 * @param float $value float to be set as value
+	 *
+	 * @return self
+	 * @throws FilesMetadataTypeException if wrapper was not set to store a float
+	 * @since 28.0.0
+	 */
+	public function setValueFloat(float $value): self;
+
+	/**
+	 * set a bool value
+	 *
+	 * @param bool $value bool to be set as value
+	 *
+	 * @return self
+	 * @throws FilesMetadataTypeException if wrapper was not set to store a bool
+	 * @since 28.0.0
+	 */
+	public function setValueBool(bool $value): self;
+
+	/**
+	 * set an array value
+	 *
+	 * @param array $value array to be set as value
+	 *
+	 * @return self
+	 * @throws FilesMetadataTypeException if wrapper was not set to store an array
+	 * @since 28.0.0
+	 */
+	public function setValueArray(array $value): self;
+
+	/**
+	 * set a string list value
+	 *
+	 * @param string[] $value string list to be set as value
+	 *
+	 * @return self
+	 * @throws FilesMetadataTypeException if wrapper was not set to store a string list
+	 * @since 28.0.0
+	 */
+	public function setValueStringList(array $value): self;
+
+	/**
+	 * set an int list value
+	 *
+	 * @param int[] $value int list to be set as value
+	 *
+	 * @return self
+	 * @throws FilesMetadataTypeException if wrapper was not set to store an int list
+	 * @since 28.0.0
+	 */
+	public function setValueIntList(array $value): self;
+
+
+	/**
+	 * get stored value
+	 *
+	 * @return string set value
+	 * @throws FilesMetadataTypeException if wrapper was not set to store a string
+	 * @throws FilesMetadataNotFoundException if value is not set
+	 * @since 28.0.0
+	 */
+	public function getValueString(): string;
+
+	/**
+	 * get stored value
+	 *
+	 * @return int set value
+	 * @throws FilesMetadataTypeException if wrapper was not set to store an int
+	 * @throws FilesMetadataNotFoundException if value is not set
+	 * @since 28.0.0
+	 */
+	public function getValueInt(): int;
+
+	/**
+	 * get stored value
+	 *
+	 * @return float set value
+	 * @throws FilesMetadataTypeException if wrapper was not set to store a float
+	 * @throws FilesMetadataNotFoundException if value is not set
+	 * @since 28.0.0
+	 */
+	public function getValueFloat(): float;
+
+	/**
+	 * get stored value
+	 *
+	 * @return bool set value
+	 * @throws FilesMetadataTypeException if wrapper was not set to store a bool
+	 * @throws FilesMetadataNotFoundException if value is not set
+	 * @since 28.0.0
+	 */
+	public function getValueBool(): bool;
+
+	/**
+	 * get stored value
+	 *
+	 * @return array set value
+	 * @throws FilesMetadataTypeException if wrapper was not set to store an array
+	 * @throws FilesMetadataNotFoundException if value is not set
+	 * @since 28.0.0
+	 */
+	public function getValueArray(): array;
+
+	/**
+	 * get stored value
+	 *
+	 * @return string[] set value
+	 * @throws FilesMetadataTypeException if wrapper was not set to store a string list
+	 * @throws FilesMetadataNotFoundException if value is not set
+	 * @since 28.0.0
+	 */
+	public function getValueStringList(): array;
+
+	/**
+	 * get stored value
+	 *
+	 * @return int[] set value
+	 * @throws FilesMetadataTypeException if wrapper was not set to store an int list
+	 * @throws FilesMetadataNotFoundException if value is not set
+	 * @since 28.0.0
+	 */
+	public function getValueIntList(): array;
+
+	/**
+	 * get stored value
+	 *
+	 * @return string|int|float|bool|array|string[]|int[] set value
+	 * @throws FilesMetadataNotFoundException if value is not set
+	 * @since 28.0.0
+	 */
+	public function getValueAny(): mixed;
+
+	/**
+	 * @param bool $indexed TRUE to set the stored value as an indexed value
+	 *
+	 * @return self
+	 * @since 28.0.0
+	 */
+	public function setIndexed(bool $indexed): self;
+
+	/**
+	 * returns if value is an indexed value
+	 *
+	 * @return bool TRUE if value is an indexed value
+	 * @since 28.0.0
+	 */
+	public function isIndexed(): bool;
+
+	/**
+	 * set remote edit permission
+	 * (Webdav PROPPATCH)
+	 *
+	 * @param int $permission edit permission
+	 *
+	 * @return self
+	 * @since 28.0.0
+	 */
+	public function setEditPermission(int $permission): self;
+
+	/**
+	 * get remote edit permission
+	 * (Webdav PROPPATCH)
+	 *
+	 * @return int edit permission
+	 * @since 28.0.0
+	 */
+	public function getEditPermission(): int;
+
+	/**
+	 * deserialize the object from a json
+	 *
+	 * @param array $data serialized version of the object
+	 *
+	 * @return self
+	 * @see jsonSerialize
+	 * @since 28.0.0
+	 */
+	public function import(array $data): self;
+}