diff options
Diffstat (limited to 'lib/public/Files')
66 files changed, 1025 insertions, 614 deletions
diff --git a/lib/public/Files/Cache/ICache.php b/lib/public/Files/Cache/ICache.php index 6a64fc26386..cd610b15545 100644 --- a/lib/public/Files/Cache/ICache.php +++ b/lib/public/Files/Cache/ICache.php @@ -219,7 +219,7 @@ interface ICache { * search for files by mimetype * * @param string $mimetype either a full mimetype to search ('text/plain') or only the first part of a mimetype ('image') - * where it will search for all mimetypes in the group ('image/*') + * where it will search for all mimetypes in the group ('image/*') * @return ICacheEntry[] an array of cache entries where the mimetype matches the search * @since 9.0.0 * @deprecated 9.0.0 due to lack of pagination, not all backends might implement this @@ -231,7 +231,7 @@ interface ICache { * * @param ISearchQuery $query * @return ICacheEntry[] - * @throw \InvalidArgumentException if the cache is unable to perform the query + * @throws \InvalidArgumentException if the cache is unable to perform the query * @since 12.0.0 */ public function searchQuery(ISearchQuery $query); diff --git a/lib/public/Files/Cache/ICacheEntry.php b/lib/public/Files/Cache/ICacheEntry.php index 11d91e74105..28e673071fd 100644 --- a/lib/public/Files/Cache/ICacheEntry.php +++ b/lib/public/Files/Cache/ICacheEntry.php @@ -161,4 +161,12 @@ interface ICacheEntry extends ArrayAccess { * @since 25.0.0 */ public function getUnencryptedSize(): int; + + /** + * Get the file id of the parent folder + * + * @return int + * @since 32.0.0 + */ + public function getParentId(): int; } diff --git a/lib/public/Files/Cache/IFileAccess.php b/lib/public/Files/Cache/IFileAccess.php index 51945b55a25..7a993d81e7a 100644 --- a/lib/public/Files/Cache/IFileAccess.php +++ b/lib/public/Files/Cache/IFileAccess.php @@ -79,4 +79,36 @@ interface IFileAccess { * @since 29.0.0 */ public function getByFileIdsInStorage(array $fileIds, int $storageId): array; + + /** + * Retrieves files stored in a specific storage that have a specified ancestor in the file hierarchy. + * Allows filtering by mime types, encryption status, and limits the number of results. + * + * @param int $storageId The ID of the storage to search within. + * @param int $folderId The file ID of the ancestor to base the search on. + * @param int $fileIdCursor The last processed file ID. Only files with a higher ID will be included. Defaults to 0. + * @param int $maxResults The maximum number of results to retrieve. If set to 0, all matching files will be retrieved. + * @param list<int> $mimeTypeIds An array of mime types to filter the results. If empty, no mime type filtering will be applied. + * @param bool $endToEndEncrypted Whether to include EndToEndEncrypted files + * @param bool $serverSideEncrypted Whether to include ServerSideEncrypted files + * @return \Generator<ICacheEntry> A generator yielding matching files as cache entries. + * @throws \OCP\DB\Exception + * + * @since 32.0.0 + */ + public function getByAncestorInStorage(int $storageId, int $folderId, int $fileIdCursor = 0, int $maxResults = 100, array $mimeTypeIds = [], bool $endToEndEncrypted = true, bool $serverSideEncrypted = true): \Generator; + + /** + * Retrieves a list of all distinct mounts. + * Allows filtering by specific mount providers. + * Optionally rewrites home directory root paths to avoid cache and trashbin. + * + * @param list<string> $mountProviders An array of mount provider class names to filter. If empty, all providers will be included. + * @param bool $onlyUserFilesMounts Whether to rewrite the root IDs for home directories to only include user files and to only consider mounts with mount points in the user files. + * @return \Generator<array{storage_id: int, root_id: int, overridden_root: int}> A generator yielding mount configurations as an array containing 'storage_id', 'root_id', and 'override_root'. + * @throws \OCP\DB\Exception + * + * @since 32.0.0 + */ + public function getDistinctMounts(array $mountProviders = [], bool $onlyUserFilesMounts = true): \Generator; } diff --git a/lib/public/Files/Cache/IUpdater.php b/lib/public/Files/Cache/IUpdater.php index 3c2bc69715c..2bc702114b4 100644 --- a/lib/public/Files/Cache/IUpdater.php +++ b/lib/public/Files/Cache/IUpdater.php @@ -58,4 +58,11 @@ interface IUpdater { * @since 9.0.0 */ public function renameFromStorage(IStorage $sourceStorage, $source, $target); + + /** + * Copy a file or folder in the cache and update the size, etag and mtime of the parent folders + * + * @since 31.0.0 + */ + public function copyFromStorage(IStorage $sourceStorage, string $source, string $target): void; } diff --git a/lib/public/Files/Cache/IWatcher.php b/lib/public/Files/Cache/IWatcher.php index 75ab14f85c2..62b90f672c6 100644 --- a/lib/public/Files/Cache/IWatcher.php +++ b/lib/public/Files/Cache/IWatcher.php @@ -76,4 +76,10 @@ interface IWatcher { * @since 9.0.0 */ public function cleanFolder($path); + + /** + * register a callback to be called whenever the watcher triggers and update + * @since 31.0.0 + */ + public function onUpdate(callable $callback): void; } diff --git a/lib/public/Files/Config/Event/UserMountAddedEvent.php b/lib/public/Files/Config/Event/UserMountAddedEvent.php new file mode 100644 index 00000000000..8abd7512188 --- /dev/null +++ b/lib/public/Files/Config/Event/UserMountAddedEvent.php @@ -0,0 +1,26 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +namespace OCP\Files\Config\Event; + +use OCP\EventDispatcher\Event; +use OCP\Files\Config\ICachedMountInfo; + +/** + * Event emitted when a user mount was added. + * + * @since 32.0.0 + */ +class UserMountAddedEvent extends Event { + public function __construct( + public readonly ICachedMountInfo $mountPoint, + ) { + parent::__construct(); + } +} diff --git a/lib/public/Files/Config/Event/UserMountRemovedEvent.php b/lib/public/Files/Config/Event/UserMountRemovedEvent.php new file mode 100644 index 00000000000..0de7cfc4a99 --- /dev/null +++ b/lib/public/Files/Config/Event/UserMountRemovedEvent.php @@ -0,0 +1,26 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +namespace OCP\Files\Config\Event; + +use OCP\EventDispatcher\Event; +use OCP\Files\Config\ICachedMountInfo; + +/** + * Event emitted when a user mount was removed. + * + * @since 32.0.0 + */ +class UserMountRemovedEvent extends Event { + public function __construct( + public readonly ICachedMountInfo $mountPoint, + ) { + parent::__construct(); + } +} diff --git a/lib/public/Files/Config/Event/UserMountUpdatedEvent.php b/lib/public/Files/Config/Event/UserMountUpdatedEvent.php new file mode 100644 index 00000000000..f797bef134e --- /dev/null +++ b/lib/public/Files/Config/Event/UserMountUpdatedEvent.php @@ -0,0 +1,27 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +namespace OCP\Files\Config\Event; + +use OCP\EventDispatcher\Event; +use OCP\Files\Config\ICachedMountInfo; + +/** + * Event emitted when a user mount was moved. + * + * @since 32.0.0 + */ +class UserMountUpdatedEvent extends Event { + public function __construct( + public readonly ICachedMountInfo $oldMountPoint, + public readonly ICachedMountInfo $newMountPoint, + ) { + parent::__construct(); + } +} diff --git a/lib/public/Files/Config/ICachedMountFileInfo.php b/lib/public/Files/Config/ICachedMountFileInfo.php index 7b331059645..a9b30d8ba6d 100644 --- a/lib/public/Files/Config/ICachedMountFileInfo.php +++ b/lib/public/Files/Config/ICachedMountFileInfo.php @@ -1,4 +1,5 @@ <?php + /** * SPDX-FileCopyrightText: 2017 Nextcloud GmbH and Nextcloud contributors * SPDX-License-Identifier: AGPL-3.0-or-later diff --git a/lib/public/Files/Conversion/ConversionMimeProvider.php b/lib/public/Files/Conversion/ConversionMimeProvider.php new file mode 100644 index 00000000000..0daf4a10648 --- /dev/null +++ b/lib/public/Files/Conversion/ConversionMimeProvider.php @@ -0,0 +1,66 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +namespace OCP\Files\Conversion; + +use JsonSerializable; + +/** + * A tuple-like object representing both an original and target + * MIME type for a file conversion + * + * @since 31.0.0 + */ +class ConversionMimeProvider implements JsonSerializable { + /** + * @param string $from The source MIME type of a file + * @param string $to The target MIME type for the file + * @param string $extension The file extension for the target MIME type (e.g. 'png') + * @param string $displayName The human-readable name of the target MIME type (e.g. 'Image (.png)') + * + * @since 31.0.0 + */ + public function __construct( + private string $from, + private string $to, + private string $extension, + private string $displayName, + ) { + } + + public function getFrom(): string { + return $this->from; + } + + public function getTo(): string { + return $this->to; + } + + public function getExtension(): string { + return $this->extension; + } + + public function getDisplayName(): string { + return $this->displayName; + } + + /** + * @return array{from: string, to: string, extension: string, displayName: string} + * + * @since 31.0.0 + */ + public function jsonSerialize(): array { + return [ + 'from' => $this->from, + 'to' => $this->to, + 'extension' => $this->extension, + 'displayName' => $this->displayName, + ]; + } +} diff --git a/lib/public/Files/Conversion/IConversionManager.php b/lib/public/Files/Conversion/IConversionManager.php new file mode 100644 index 00000000000..ed418129d3b --- /dev/null +++ b/lib/public/Files/Conversion/IConversionManager.php @@ -0,0 +1,46 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +namespace OCP\Files\Conversion; + +use OCP\Files\File; + +/** + * @since 31.0.0 + */ +interface IConversionManager { + /** + * Determines whether or not conversion providers are available + * + * @since 31.0.0 + */ + public function hasProviders(): bool; + + /** + * Gets all supported MIME type conversions + * + * @return list<ConversionMimeProvider> + * + * @since 31.0.0 + */ + public function getProviders(): array; + + /** + * Convert a file to a given MIME type + * + * @param File $file The file to be converted + * @param string $targetMimeType The MIME type to convert the file to + * @param ?string $destination The destination to save the converted file + * + * @return string Path to the converted file + * + * @since 31.0.0 + */ + public function convert(File $file, string $targetMimeType, ?string $destination = null): string; +} diff --git a/lib/public/Files/Conversion/IConversionProvider.php b/lib/public/Files/Conversion/IConversionProvider.php new file mode 100644 index 00000000000..3b5c5945c99 --- /dev/null +++ b/lib/public/Files/Conversion/IConversionProvider.php @@ -0,0 +1,41 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +namespace OCP\Files\Conversion; + +use OCP\Files\File; + +/** + * This interface is implemented by apps that provide + * a file conversion provider + * + * @since 31.0.0 + */ +interface IConversionProvider { + /** + * Get an array of MIME type tuples this conversion provider supports + * + * @return list<ConversionMimeProvider> + * + * @since 31.0.0 + */ + public function getSupportedMimeTypes(): array; + + /** + * Convert a file to a given MIME type + * + * @param File $file The file to be converted + * @param string $targetMimeType The MIME type to convert the file to + * + * @return resource|string Resource or string content of the file + * + * @since 31.0.0 + */ + public function convertFile(File $file, string $targetMimeType): mixed; +} diff --git a/lib/public/Files/DavUtil.php b/lib/public/Files/DavUtil.php index 40d17c77c88..6dde3179bb8 100644 --- a/lib/public/Files/DavUtil.php +++ b/lib/public/Files/DavUtil.php @@ -1,4 +1,5 @@ <?php + /** * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors * SPDX-License-Identifier: AGPL-3.0-only diff --git a/lib/public/Files/EmptyFileNameException.php b/lib/public/Files/EmptyFileNameException.php index ec13a9fc2be..1630ce63ea2 100644 --- a/lib/public/Files/EmptyFileNameException.php +++ b/lib/public/Files/EmptyFileNameException.php @@ -1,4 +1,5 @@ <?php + /** * SPDX-FileCopyrightText: 2016 Nextcloud GmbH and Nextcloud contributors * SPDX-License-Identifier: AGPL-3.0-or-later diff --git a/lib/public/Files/Events/BeforeFileSystemSetupEvent.php b/lib/public/Files/Events/BeforeFileSystemSetupEvent.php new file mode 100644 index 00000000000..23791aa6ec1 --- /dev/null +++ b/lib/public/Files/Events/BeforeFileSystemSetupEvent.php @@ -0,0 +1,36 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-only + */ + +namespace OCP\Files\Events; + +use OCP\EventDispatcher\Event; +use OCP\IUser; + +/** + * Event triggered before the file system is setup + * + * @since 31.0.0 + */ +class BeforeFileSystemSetupEvent extends Event { + /** + * @since 31.0.0 + */ + public function __construct( + private IUser $user, + ) { + parent::__construct(); + } + + /** + * @since 31.0.0 + */ + public function getUser(): IUser { + return $this->user; + } +} diff --git a/lib/public/Files/Events/BeforeZipCreatedEvent.php b/lib/public/Files/Events/BeforeZipCreatedEvent.php index b55b36d3968..0363d385d36 100644 --- a/lib/public/Files/Events/BeforeZipCreatedEvent.php +++ b/lib/public/Files/Events/BeforeZipCreatedEvent.php @@ -10,23 +10,45 @@ declare(strict_types=1); namespace OCP\Files\Events; use OCP\EventDispatcher\Event; +use OCP\Files\Folder; /** + * This event is triggered before a archive is created when a user requested + * downloading a folder or multiple files. + * + * By setting `successful` to false the tar creation can be aborted and the download denied. + * * @since 25.0.0 */ class BeforeZipCreatedEvent extends Event { private string $directory; - private array $files; private bool $successful = true; private ?string $errorMessage = null; + private ?Folder $folder = null; /** + * @param list<string> $files * @since 25.0.0 + * @since 31.0.0 support `OCP\Files\Folder` as `$directory` parameter - passing a string is deprecated now */ - public function __construct(string $directory, array $files) { + public function __construct( + string|Folder $directory, + private array $files, + ) { parent::__construct(); - $this->directory = $directory; - $this->files = $files; + if ($directory instanceof Folder) { + $this->directory = $directory->getPath(); + $this->folder = $directory; + } else { + $this->directory = $directory; + } + } + + /** + * @since 31.0.0 + */ + public function getFolder(): ?Folder { + return $this->folder; } /** diff --git a/lib/public/Files/Events/Node/AbstractNodeEvent.php b/lib/public/Files/Events/Node/AbstractNodeEvent.php index 64b0e3a3aa5..7afb71277f6 100644 --- a/lib/public/Files/Events/Node/AbstractNodeEvent.php +++ b/lib/public/Files/Events/Node/AbstractNodeEvent.php @@ -21,7 +21,7 @@ abstract class AbstractNodeEvent extends Event implements IWebhookCompatibleEven * @since 20.0.0 */ public function __construct( - private Node $node + private Node $node, ) { } diff --git a/lib/public/Files/Events/Node/AbstractNodesEvent.php b/lib/public/Files/Events/Node/AbstractNodesEvent.php index 7941a9e596a..8fa8795d1df 100644 --- a/lib/public/Files/Events/Node/AbstractNodesEvent.php +++ b/lib/public/Files/Events/Node/AbstractNodesEvent.php @@ -22,7 +22,7 @@ abstract class AbstractNodesEvent extends Event implements IWebhookCompatibleEve */ public function __construct( private Node $source, - private Node $target + private Node $target, ) { } diff --git a/lib/public/Files/FileInfo.php b/lib/public/Files/FileInfo.php index 468013ac271..f9957f580e8 100644 --- a/lib/public/Files/FileInfo.php +++ b/lib/public/Files/FileInfo.php @@ -133,7 +133,9 @@ interface FileInfo { public function getId(); /** - * Check whether the file is encrypted + * Check whether the node is encrypted. + * If it is a file, then it is server side encrypted. + * If it is a folder, then it is end-to-end encrypted. * * @return bool * @since 7.0.0 diff --git a/lib/public/Files/Folder.php b/lib/public/Files/Folder.php index 3f05ff49890..a35d2d78bc9 100644 --- a/lib/public/Files/Folder.php +++ b/lib/public/Files/Folder.php @@ -60,6 +60,7 @@ interface Folder extends Node { * @param string $path relative path of the file or folder * @return \OCP\Files\Node * @throws \OCP\Files\NotFoundException + * @throws \OCP\Files\NotPermittedException * @since 6.0.0 */ public function get($path); @@ -198,4 +199,15 @@ interface Folder extends Node { * @since 9.1.0 */ public function getRecent($limit, $offset = 0); + + /** + * Verify if the given path is valid and allowed from this folder. + * + * @param string $path the path from this folder + * @param string $fileName + * @param bool $readonly Check only if the path is allowed for read-only access + * @throws InvalidPathException + * @since 32.0.0 + */ + public function verifyPath($fileName, $readonly = false): void; } diff --git a/lib/public/Files/ForbiddenException.php b/lib/public/Files/ForbiddenException.php index 338757e79eb..514ef8623d3 100644 --- a/lib/public/Files/ForbiddenException.php +++ b/lib/public/Files/ForbiddenException.php @@ -35,6 +35,6 @@ class ForbiddenException extends \Exception { * @since 9.0.0 */ public function getRetry() { - return (bool) $this->retry; + return (bool)$this->retry; } } diff --git a/lib/public/Files/GenericFileException.php b/lib/public/Files/GenericFileException.php index 288d668e3e7..66a3b5e5ac4 100644 --- a/lib/public/Files/GenericFileException.php +++ b/lib/public/Files/GenericFileException.php @@ -1,4 +1,5 @@ <?php + /** * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors * SPDX-License-Identifier: AGPL-3.0-or-later diff --git a/lib/public/Files/IAppData.php b/lib/public/Files/IAppData.php index e5a5c2b7143..4d0c4da6a8a 100644 --- a/lib/public/Files/IAppData.php +++ b/lib/public/Files/IAppData.php @@ -1,4 +1,5 @@ <?php + /** * SPDX-FileCopyrightText: 2016 Nextcloud GmbH and Nextcloud contributors * SPDX-License-Identifier: AGPL-3.0-or-later diff --git a/lib/public/Files/IFilenameValidator.php b/lib/public/Files/IFilenameValidator.php new file mode 100644 index 00000000000..9b7fa1e2e2e --- /dev/null +++ b/lib/public/Files/IFilenameValidator.php @@ -0,0 +1,52 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Files; + +/** + * @since 30.0.0 + */ +interface IFilenameValidator { + + /** + * It is recommended to use `\OCP\Files\Storage\IStorage::isFileValid` instead as this + * only checks if the filename is valid in general but not for a specific storage + * which might have additional naming rules. + * + * @param string $filename The filename to check for validity + * @return bool + * @since 30.0.0 + */ + public function isFilenameValid(string $filename): bool; + + /** + * It is recommended to use `\OCP\Files\Storage\IStorage::isFileValid` instead as this + * only checks if the filename is valid in general but not for a specific storage + * which might have additional naming rules. + * + * This will validate a filename and throw an exception with details on error. + * + * @param string $filename The filename to check for validity + * @throws \OCP\Files\InvalidPathException or one of its child classes in case of an error + * @since 30.0.0 + */ + public function validateFilename(string $filename): void; + + /** + * Sanitize a give filename to comply with admin setup naming constrains. + * + * If no sanitizing is needed the same name is returned. + * + * @param string $name The filename to sanitize + * @param null|string $charReplacement Character to use for replacing forbidden ones - by default underscore, dash or space is used if allowed. + * @throws \InvalidArgumentException if no character replacement was given (and the default could not be applied) or the replacement is not valid. + * @since 32.0.0 + */ + public function sanitizeFilename(string $name, ?string $charReplacement = null): string; + +} diff --git a/lib/public/Files/IMimeTypeDetector.php b/lib/public/Files/IMimeTypeDetector.php index 1c683cdd4b9..1e87cf932ce 100644 --- a/lib/public/Files/IMimeTypeDetector.php +++ b/lib/public/Files/IMimeTypeDetector.php @@ -14,11 +14,11 @@ namespace OCP\Files; * Interface IMimeTypeDetector * @since 8.2.0 * - * Interface to handle mimetypes (detection and icon retrieval) + * Interface to handle MIME type (detection and icon retrieval) **/ interface IMimeTypeDetector { /** - * detect mimetype only based on filename, content of file is not used + * Detect MIME type only based on filename, content of file is not used * @param string $path * @return string * @since 8.2.0 @@ -26,7 +26,7 @@ interface IMimeTypeDetector { public function detectPath($path); /** - * detect mimetype only based on the content of file + * Detect MIME type only based on the content of file * @param string $path * @return string * @since 18.0.0 @@ -34,7 +34,7 @@ interface IMimeTypeDetector { public function detectContent(string $path): string; /** - * detect mimetype based on both filename and content + * Detect MIME type based on both filename and content * * @param string $path * @return string @@ -43,7 +43,7 @@ interface IMimeTypeDetector { public function detect($path); /** - * Get a secure mimetype that won't expose potential XSS. + * Get a secure MIME type that won't expose potential XSS. * * @param string $mimeType * @return string @@ -52,7 +52,7 @@ interface IMimeTypeDetector { public function getSecureMimeType($mimeType); /** - * detect mimetype based on the content of a string + * Detect MIME type based on the content of a string * * @param string $data * @return string @@ -73,4 +73,26 @@ interface IMimeTypeDetector { * @since 28.0.0 */ public function getAllAliases(): array; + + /** + * Get all extension to MIME type mappings. + * + * The return format is an array of the file extension, as the key, + * mapped to a list where the first entry is the MIME type + * and the second entry is the secure MIME type (or null if none). + * Due to PHP idiosyncrasies if a numeric string is set as the extension, + * then also the array key (file extension) is a number instead of a string. + * + * @return array<list{string, string|null}> + * @since 32.0.0 + */ + public function getAllMappings(): array; + + /** + * Get all human readable mime names + * + * @return array<string,string> + * @since 32.0.0 + */ + public function getAllNamings(): array; } diff --git a/lib/public/Files/IMimeTypeLoader.php b/lib/public/Files/IMimeTypeLoader.php index 44261527d53..77c59fb2c0a 100644 --- a/lib/public/Files/IMimeTypeLoader.php +++ b/lib/public/Files/IMimeTypeLoader.php @@ -47,4 +47,14 @@ interface IMimeTypeLoader { * @since 8.2.0 */ public function reset(): void; + + /** + * Update filecache mimetype based on file extension + * + * @param string $ext + * @param int $mimeTypeId + * @return int + * @since 32.0.0 + */ + public function updateFilecache(string $ext, int $mimeTypeId): int; } diff --git a/lib/public/Files/InvalidDirectoryException.php b/lib/public/Files/InvalidDirectoryException.php index 7f87eed1a17..b9640209cbf 100644 --- a/lib/public/Files/InvalidDirectoryException.php +++ b/lib/public/Files/InvalidDirectoryException.php @@ -1,4 +1,5 @@ <?php + /** * SPDX-FileCopyrightText: 2016 Nextcloud GmbH and Nextcloud contributors * SPDX-License-Identifier: AGPL-3.0-or-later diff --git a/lib/public/Files/Lock/LockContext.php b/lib/public/Files/Lock/LockContext.php index 48d9f804fc4..5e61d3e2ec5 100644 --- a/lib/public/Files/Lock/LockContext.php +++ b/lib/public/Files/Lock/LockContext.php @@ -33,7 +33,7 @@ final class LockContext { public function __construct( Node $node, int $type, - string $owner + string $owner, ) { $this->node = $node; $this->type = $type; diff --git a/lib/public/Files/LockNotAcquiredException.php b/lib/public/Files/LockNotAcquiredException.php index 19e0bbc2543..93d861c248f 100644 --- a/lib/public/Files/LockNotAcquiredException.php +++ b/lib/public/Files/LockNotAcquiredException.php @@ -35,6 +35,6 @@ class LockNotAcquiredException extends \Exception { * @since 7.0.0 */ public function __toString(): string { - return __CLASS__ . ": [{$this->code}]: {$this->message}\n"; + return self::class . ": [{$this->code}]: {$this->message}\n"; } } diff --git a/lib/public/Files/Mount/IShareOwnerlessMount.php b/lib/public/Files/Mount/IShareOwnerlessMount.php new file mode 100644 index 00000000000..b73ee620859 --- /dev/null +++ b/lib/public/Files/Mount/IShareOwnerlessMount.php @@ -0,0 +1,18 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +namespace OCP\Files\Mount; + +/** + * Denotes that shares created under this mountpoint will be manageable by everyone with share permission. + * + * @since 31.0.0 + */ +interface IShareOwnerlessMount { +} diff --git a/lib/public/Files/Node.php b/lib/public/Files/Node.php index e3641a82df3..edef0a6157f 100644 --- a/lib/public/Files/Node.php +++ b/lib/public/Files/Node.php @@ -243,7 +243,7 @@ interface Node extends FileInfo { * Check the type of an existing lock. * * A shared lock can be changed to an exclusive lock is there is exactly one shared lock on the file, - * an exclusive lock can always be changed to a shared lock since there can only be one exclusive lock int he first place. + * an exclusive lock can always be changed to a shared lock since there can only be one exclusive lock in the first place. * * A locked exception will be thrown when these preconditions are not met. * Note that this is also the case if no existing lock exists for the file. diff --git a/lib/public/Files/Notify/IChange.php b/lib/public/Files/Notify/IChange.php index 8f252411a5a..c7c758eec11 100644 --- a/lib/public/Files/Notify/IChange.php +++ b/lib/public/Files/Notify/IChange.php @@ -1,4 +1,5 @@ <?php + /** * SPDX-FileCopyrightText: 2017 Nextcloud GmbH and Nextcloud contributors * SPDX-License-Identifier: AGPL-3.0-or-later diff --git a/lib/public/Files/Notify/INotifyHandler.php b/lib/public/Files/Notify/INotifyHandler.php index 8777779ca4a..09b3dbca919 100644 --- a/lib/public/Files/Notify/INotifyHandler.php +++ b/lib/public/Files/Notify/INotifyHandler.php @@ -1,4 +1,5 @@ <?php + /** * SPDX-FileCopyrightText: 2017 Nextcloud GmbH and Nextcloud contributors * SPDX-License-Identifier: AGPL-3.0-or-later diff --git a/lib/public/Files/Notify/IRenameChange.php b/lib/public/Files/Notify/IRenameChange.php index 3e1ae7ed447..b1bfae5fc00 100644 --- a/lib/public/Files/Notify/IRenameChange.php +++ b/lib/public/Files/Notify/IRenameChange.php @@ -1,4 +1,5 @@ <?php + /** * SPDX-FileCopyrightText: 2017 Nextcloud GmbH and Nextcloud contributors * SPDX-License-Identifier: AGPL-3.0-or-later diff --git a/lib/public/Files/ObjectStore/IObjectStoreMetaData.php b/lib/public/Files/ObjectStore/IObjectStoreMetaData.php new file mode 100644 index 00000000000..9683873be36 --- /dev/null +++ b/lib/public/Files/ObjectStore/IObjectStoreMetaData.php @@ -0,0 +1,47 @@ +<?php + +/** + * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-only + */ +namespace OCP\Files\ObjectStore; + +/** + * Interface IObjectStoreMetaData + * + * @psalm-type ObjectMetaData = array{mtime?: \DateTime, etag?: string, size?: int, mimetype?: string, filename?: string, original-path?: string, original-storage?: string} + * + * @since 32.0.0 + */ +interface IObjectStoreMetaData { + /** + * Get metadata for an object. + * + * @param string $urn + * @return ObjectMetaData + * + * @since 32.0.0 + */ + public function getObjectMetaData(string $urn): array; + + /** + * List all objects in the object store. + * + * If the object store implementation can do it efficiently, the metadata for each object is also included. + * + * @param string $prefix + * @return \Iterator<array{urn: string, metadata: ?ObjectMetaData}> + * + * @since 32.0.0 + */ + public function listObjects(string $prefix = ''): \Iterator; + + /** + * @param string $urn the unified resource name used to identify the object + * @param resource $stream stream with the data to write + * @param ObjectMetaData $metaData the metadata to set for the object + * @throws \Exception when something goes wrong, message will be logged + * @since 32.0.0 + */ + public function writeObjectWithMetaData(string $urn, $stream, array $metaData): void; +} diff --git a/lib/public/Files/Search/ISearchBinaryOperator.php b/lib/public/Files/Search/ISearchBinaryOperator.php index 661be44596d..fa7ef4d1bb3 100644 --- a/lib/public/Files/Search/ISearchBinaryOperator.php +++ b/lib/public/Files/Search/ISearchBinaryOperator.php @@ -1,4 +1,5 @@ <?php + /** * SPDX-FileCopyrightText: 2017 Nextcloud GmbH and Nextcloud contributors * SPDX-License-Identifier: AGPL-3.0-or-later diff --git a/lib/public/Files/Search/ISearchComparison.php b/lib/public/Files/Search/ISearchComparison.php index 01b69f5d24c..ab298fa0a57 100644 --- a/lib/public/Files/Search/ISearchComparison.php +++ b/lib/public/Files/Search/ISearchComparison.php @@ -1,4 +1,5 @@ <?php + /** * SPDX-FileCopyrightText: 2017 Nextcloud GmbH and Nextcloud contributors * SPDX-License-Identifier: AGPL-3.0-or-later @@ -51,7 +52,7 @@ interface ISearchComparison extends ISearchOperator { * @since 28.0.0 */ public const COMPARE_DEFINED = 'is-defined'; - + /** * @since 29.0.0 */ diff --git a/lib/public/Files/Search/ISearchOperator.php b/lib/public/Files/Search/ISearchOperator.php index a604bd96b9d..f6ae8edcbb1 100644 --- a/lib/public/Files/Search/ISearchOperator.php +++ b/lib/public/Files/Search/ISearchOperator.php @@ -1,4 +1,5 @@ <?php + /** * SPDX-FileCopyrightText: 2017 Nextcloud GmbH and Nextcloud contributors * SPDX-License-Identifier: AGPL-3.0-or-later diff --git a/lib/public/Files/Search/ISearchOrder.php b/lib/public/Files/Search/ISearchOrder.php index 23f71e2133e..e6e68849443 100644 --- a/lib/public/Files/Search/ISearchOrder.php +++ b/lib/public/Files/Search/ISearchOrder.php @@ -1,4 +1,5 @@ <?php + /** * SPDX-FileCopyrightText: 2017 Nextcloud GmbH and Nextcloud contributors * SPDX-License-Identifier: AGPL-3.0-or-later diff --git a/lib/public/Files/Search/ISearchQuery.php b/lib/public/Files/Search/ISearchQuery.php index 109998aee65..1b400c56e5b 100644 --- a/lib/public/Files/Search/ISearchQuery.php +++ b/lib/public/Files/Search/ISearchQuery.php @@ -1,4 +1,5 @@ <?php + /** * SPDX-FileCopyrightText: 2017 Nextcloud GmbH and Nextcloud contributors * SPDX-License-Identifier: AGPL-3.0-or-later diff --git a/lib/public/Files/SimpleFS/ISimpleFile.php b/lib/public/Files/SimpleFS/ISimpleFile.php index 2682c22580d..4e77299ab00 100644 --- a/lib/public/Files/SimpleFS/ISimpleFile.php +++ b/lib/public/Files/SimpleFS/ISimpleFile.php @@ -1,12 +1,15 @@ <?php + /** * SPDX-FileCopyrightText: 2016 Nextcloud GmbH and Nextcloud contributors * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Files\SimpleFS; +use OCP\Files\GenericFileException; use OCP\Files\NotFoundException; use OCP\Files\NotPermittedException; +use OCP\Lock\LockedException; /** * This interface allows to manage simple files. @@ -49,8 +52,10 @@ interface ISimpleFile { /** * Get the content * - * @throws NotPermittedException + * @throws GenericFileException + * @throws LockedException * @throws NotFoundException + * @throws NotPermittedException * @since 11.0.0 */ public function getContent(): string; @@ -59,8 +64,10 @@ interface ISimpleFile { * Overwrite the file * * @param string|resource $data - * @throws NotPermittedException + * @throws GenericFileException + * @throws LockedException * @throws NotFoundException + * @throws NotPermittedException * @since 11.0.0 */ public function putContent($data): void; diff --git a/lib/public/Files/SimpleFS/ISimpleFolder.php b/lib/public/Files/SimpleFS/ISimpleFolder.php index 79b9fca1dac..95efc676688 100644 --- a/lib/public/Files/SimpleFS/ISimpleFolder.php +++ b/lib/public/Files/SimpleFS/ISimpleFolder.php @@ -1,4 +1,5 @@ <?php + /** * SPDX-FileCopyrightText: 2016 Nextcloud GmbH and Nextcloud contributors * SPDX-License-Identifier: AGPL-3.0-or-later diff --git a/lib/public/Files/SimpleFS/ISimpleRoot.php b/lib/public/Files/SimpleFS/ISimpleRoot.php index 5c01c6a2a2e..6be8a1d47c9 100644 --- a/lib/public/Files/SimpleFS/ISimpleRoot.php +++ b/lib/public/Files/SimpleFS/ISimpleRoot.php @@ -1,4 +1,5 @@ <?php + /** * SPDX-FileCopyrightText: 2016 Nextcloud GmbH and Nextcloud contributors * SPDX-License-Identifier: AGPL-3.0-or-later diff --git a/lib/public/Files/Storage.php b/lib/public/Files/Storage.php deleted file mode 100644 index 049841075ca..00000000000 --- a/lib/public/Files/Storage.php +++ /dev/null @@ -1,445 +0,0 @@ -<?php - -/** - * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors - * SPDX-FileCopyrightText: 2016 ownCloud, Inc. - * SPDX-License-Identifier: AGPL-3.0-only - */ -// use OCP namespace for all classes that are considered public. -// This means that they should be used by apps instead of the internal Nextcloud classes - -namespace OCP\Files; - -use OCP\Files\Storage\IStorage; -use OCP\Lock\ILockingProvider; - -/** - * Provide a common interface to all different storage options - * - * All paths passed to the storage are relative to the storage and should NOT have a leading slash. - * - * @since 6.0.0 - * @deprecated 9.0.0 use \OCP\Files\Storage\IStorage instead - */ -interface Storage extends IStorage { - /** - * $parameters is a free form array with the configuration options needed to construct the storage - * - * @param array $parameters - * @since 6.0.0 - */ - public function __construct($parameters); - - /** - * Get the identifier for the storage, - * the returned id should be the same for every storage object that is created with the same parameters - * and two storage objects with the same id should refer to two storages that display the same files. - * - * @return string - * @since 6.0.0 - */ - public function getId(); - - /** - * see https://www.php.net/manual/en/function.mkdir.php - * implementations need to implement a recursive mkdir - * - * @param string $path - * @return bool - * @since 6.0.0 - */ - public function mkdir($path); - - /** - * see https://www.php.net/manual/en/function.rmdir.php - * - * @param string $path - * @return bool - * @since 6.0.0 - */ - public function rmdir($path); - - /** - * see https://www.php.net/manual/en/function.opendir.php - * - * @param string $path - * @return resource|false - * @since 6.0.0 - */ - public function opendir($path); - - /** - * see https://www.php.net/manual/en/function.is-dir.php - * - * @param string $path - * @return bool - * @since 6.0.0 - */ - public function is_dir($path); - - /** - * see https://www.php.net/manual/en/function.is-file.php - * - * @param string $path - * @return bool - * @since 6.0.0 - */ - public function is_file($path); - - /** - * see https://www.php.net/manual/en/function.stat.php - * only the following keys are required in the result: size and mtime - * - * @param string $path - * @return array|bool - * @since 6.0.0 - */ - public function stat($path); - - /** - * see https://www.php.net/manual/en/function.filetype.php - * - * @param string $path - * @return string|bool - * @since 6.0.0 - */ - public function filetype($path); - - /** - * see https://www.php.net/manual/en/function.filesize.php - * The result for filesize when called on a folder is required to be 0 - * - * @param string $path - * @return false|int|float - * @since 6.0.0 - */ - public function filesize($path); - - /** - * check if a file can be created in $path - * - * @param string $path - * @return bool - * @since 6.0.0 - */ - public function isCreatable($path); - - /** - * check if a file can be read - * - * @param string $path - * @return bool - * @since 6.0.0 - */ - public function isReadable($path); - - /** - * check if a file can be written to - * - * @param string $path - * @return bool - * @since 6.0.0 - */ - public function isUpdatable($path); - - /** - * check if a file can be deleted - * - * @param string $path - * @return bool - * @since 6.0.0 - */ - public function isDeletable($path); - - /** - * check if a file can be shared - * - * @param string $path - * @return bool - * @since 6.0.0 - */ - public function isSharable($path); - - /** - * get the full permissions of a path. - * Should return a combination of the PERMISSION_ constants defined in lib/public/constants.php - * - * @param string $path - * @return int - * @since 6.0.0 - */ - public function getPermissions($path); - - /** - * see https://www.php.net/manual/en/function.file_exists.php - * - * @param string $path - * @return bool - * @since 6.0.0 - */ - public function file_exists($path); - - /** - * see https://www.php.net/manual/en/function.filemtime.php - * - * @param string $path - * @return int|bool - * @since 6.0.0 - */ - public function filemtime($path); - - /** - * see https://www.php.net/manual/en/function.file_get_contents.php - * - * @param string $path - * @return string|false - * @since 6.0.0 - */ - public function file_get_contents($path); - - /** - * see https://www.php.net/manual/en/function.file_put_contents.php - * - * @param string $path - * @param mixed $data - * @return int|float|false - * @since 6.0.0 - */ - public function file_put_contents($path, $data); - - /** - * see https://www.php.net/manual/en/function.unlink.php - * - * @param string $path - * @return bool - * @since 6.0.0 - */ - public function unlink($path); - - /** - * see https://www.php.net/manual/en/function.rename.php - * - * @param string $source - * @param string $target - * @return bool - * @since 6.0.0 - */ - public function rename($source, $target); - - /** - * see https://www.php.net/manual/en/function.copy.php - * - * @param string $source - * @param string $target - * @return bool - * @since 6.0.0 - */ - public function copy($source, $target); - - /** - * see https://www.php.net/manual/en/function.fopen.php - * - * @param string $path - * @param string $mode - * @return resource|bool - * @since 6.0.0 - */ - public function fopen($path, $mode); - - /** - * get the mimetype for a file or folder - * The mimetype for a folder is required to be "httpd/unix-directory" - * - * @param string $path - * @return string|bool - * @since 6.0.0 - */ - public function getMimeType($path); - - /** - * see https://www.php.net/manual/en/function.hash-file.php - * - * @param string $type - * @param string $path - * @param bool $raw - * @return string|bool - * @since 6.0.0 - */ - public function hash($type, $path, $raw = false); - - /** - * see https://www.php.net/manual/en/function.disk-free-space.php - * - * @param string $path - * @return int|float|bool - * @since 6.0.0 - */ - public function free_space($path); - - /** - * search for occurrences of $query in file names - * - * @param string $query - * @return array|bool - * @since 6.0.0 - */ - public function search($query); - - /** - * see https://www.php.net/manual/en/function.touch.php - * If the backend does not support the operation, false should be returned - * - * @param string $path - * @param int $mtime - * @return bool - * @since 6.0.0 - */ - public function touch($path, $mtime = null); - - /** - * get the path to a local version of the file. - * The local version of the file can be temporary and doesn't have to be persistent across requests - * - * @param string $path - * @return string|false - * @since 6.0.0 - */ - public function getLocalFile($path); - - /** - * check if a file or folder has been updated since $time - * - * @param string $path - * @param int $time - * @return bool - * @since 6.0.0 - * - * hasUpdated for folders should return at least true if a file inside the folder is add, removed or renamed. - * returning true for other changes in the folder is optional - */ - public function hasUpdated($path, $time); - - /** - * get the ETag for a file or folder - * - * @param string $path - * @return string|false - * @since 6.0.0 - */ - public function getETag($path); - - /** - * Returns whether the storage is local, which means that files - * are stored on the local filesystem instead of remotely. - * Calling getLocalFile() for local storages should always - * return the local files, whereas for non-local storages - * it might return a temporary file. - * - * @return bool true if the files are stored locally, false otherwise - * @since 7.0.0 - */ - public function isLocal(); - - /** - * Check if the storage is an instance of $class or is a wrapper for a storage that is an instance of $class - * - * @template T of IStorage - * @param string $class - * @psalm-param class-string<T> $class - * @return bool - * @since 7.0.0 - * @psalm-assert-if-true T $this - */ - public function instanceOfStorage($class); - - /** - * A custom storage implementation can return an url for direct download of a give file. - * - * For now the returned array can hold the parameter url - in future more attributes might follow. - * - * @param string $path - * @return array|bool - * @since 8.0.0 - */ - public function getDirectDownload($path); - - /** - * @param string $path the path of the target folder - * @param string $fileName the name of the file itself - * @return void - * @throws InvalidPathException - * @since 8.1.0 - */ - public function verifyPath($path, $fileName); - - /** - * @param IStorage $sourceStorage - * @param string $sourceInternalPath - * @param string $targetInternalPath - * @return bool - * @since 8.1.0 - */ - public function copyFromStorage(IStorage $sourceStorage, $sourceInternalPath, $targetInternalPath); - - /** - * @param IStorage $sourceStorage - * @param string $sourceInternalPath - * @param string $targetInternalPath - * @return bool - * @since 8.1.0 - */ - public function moveFromStorage(IStorage $sourceStorage, $sourceInternalPath, $targetInternalPath); - - /** - * @param string $path The path of the file to acquire the lock for - * @param int $type \OCP\Lock\ILockingProvider::LOCK_SHARED or \OCP\Lock\ILockingProvider::LOCK_EXCLUSIVE - * @param \OCP\Lock\ILockingProvider $provider - * @throws \OCP\Lock\LockedException - * @since 8.1.0 - */ - public function acquireLock($path, $type, ILockingProvider $provider); - - /** - * @param string $path The path of the file to acquire the lock for - * @param int $type \OCP\Lock\ILockingProvider::LOCK_SHARED or \OCP\Lock\ILockingProvider::LOCK_EXCLUSIVE - * @param \OCP\Lock\ILockingProvider $provider - * @throws \OCP\Lock\LockedException - * @since 8.1.0 - */ - public function releaseLock($path, $type, ILockingProvider $provider); - - /** - * @param string $path The path of the file to change the lock for - * @param int $type \OCP\Lock\ILockingProvider::LOCK_SHARED or \OCP\Lock\ILockingProvider::LOCK_EXCLUSIVE - * @param \OCP\Lock\ILockingProvider $provider - * @throws \OCP\Lock\LockedException - * @since 8.1.0 - */ - public function changeLock($path, $type, ILockingProvider $provider); - - /** - * Test a storage for availability - * - * @since 8.2.0 - * @return bool - */ - public function test(); - - /** - * @since 8.2.0 - * @return array [ available, last_checked ] - */ - public function getAvailability(); - - /** - * @since 8.2.0 - * @param bool $isAvailable - */ - public function setAvailability($isAvailable); - - /** - * @since 12.0.0 - * @return mixed - */ - public function needsPartFile(); -} diff --git a/lib/public/Files/Storage/IChunkedFileWrite.php b/lib/public/Files/Storage/IChunkedFileWrite.php index 1095ee7cbfc..0cf27814f0e 100644 --- a/lib/public/Files/Storage/IChunkedFileWrite.php +++ b/lib/public/Files/Storage/IChunkedFileWrite.php @@ -1,4 +1,5 @@ <?php + /** * SPDX-FileCopyrightText: 2021 Nextcloud GmbH and Nextcloud contributors * SPDX-License-Identifier: AGPL-3.0-or-later @@ -24,28 +25,19 @@ interface IChunkedFileWrite extends IStorage { public function startChunkedWrite(string $targetPath): string; /** - * @param string $targetPath - * @param string $writeToken - * @param string $chunkId * @param resource $data - * @param int|null $size * @throws GenericFileException * @since 26.0.0 */ public function putChunkedWritePart(string $targetPath, string $writeToken, string $chunkId, $data, ?int $size = null): ?array; /** - * @param string $targetPath - * @param string $writeToken - * @return int * @throws GenericFileException * @since 26.0.0 */ public function completeChunkedWrite(string $targetPath, string $writeToken): int; /** - * @param string $targetPath - * @param string $writeToken * @throws GenericFileException * @since 26.0.0 */ diff --git a/lib/public/Files/Storage/IConstructableStorage.php b/lib/public/Files/Storage/IConstructableStorage.php new file mode 100644 index 00000000000..57749fa30fa --- /dev/null +++ b/lib/public/Files/Storage/IConstructableStorage.php @@ -0,0 +1,26 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-only + */ +// use OCP namespace for all classes that are considered public. +// This means that they should be used by apps instead of the internal Nextcloud classes + +namespace OCP\Files\Storage; + +/** + * Marks a storage as constructable. Allows to pass the storage as a string to a mounpoint and let it build the instance. + * + * @since 31.0.0 + */ +interface IConstructableStorage { + /** + * @param array $parameters is a free form array with the configuration options needed to construct the storage + * + * @since 31.0.0 + */ + public function __construct(array $parameters); +} diff --git a/lib/public/Files/Storage/IDisableEncryptionStorage.php b/lib/public/Files/Storage/IDisableEncryptionStorage.php index 98a4b4897da..19951da2015 100644 --- a/lib/public/Files/Storage/IDisableEncryptionStorage.php +++ b/lib/public/Files/Storage/IDisableEncryptionStorage.php @@ -1,4 +1,5 @@ <?php + /** * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors * SPDX-License-Identifier: AGPL-3.0-or-later diff --git a/lib/public/Files/Storage/ILockingStorage.php b/lib/public/Files/Storage/ILockingStorage.php index abec7d91b83..ceedf33ceab 100644 --- a/lib/public/Files/Storage/ILockingStorage.php +++ b/lib/public/Files/Storage/ILockingStorage.php @@ -21,27 +21,24 @@ interface ILockingStorage { /** * @param string $path The path of the file to acquire the lock for * @param int $type \OCP\Lock\ILockingProvider::LOCK_SHARED or \OCP\Lock\ILockingProvider::LOCK_EXCLUSIVE - * @param \OCP\Lock\ILockingProvider $provider * @throws \OCP\Lock\LockedException * @since 9.0.0 */ - public function acquireLock($path, $type, ILockingProvider $provider); + public function acquireLock(string $path, int $type, ILockingProvider $provider); /** * @param string $path The path of the file to acquire the lock for * @param int $type \OCP\Lock\ILockingProvider::LOCK_SHARED or \OCP\Lock\ILockingProvider::LOCK_EXCLUSIVE - * @param \OCP\Lock\ILockingProvider $provider * @throws \OCP\Lock\LockedException * @since 9.0.0 */ - public function releaseLock($path, $type, ILockingProvider $provider); + public function releaseLock(string $path, int $type, ILockingProvider $provider); /** * @param string $path The path of the file to change the lock for * @param int $type \OCP\Lock\ILockingProvider::LOCK_SHARED or \OCP\Lock\ILockingProvider::LOCK_EXCLUSIVE - * @param \OCP\Lock\ILockingProvider $provider * @throws \OCP\Lock\LockedException * @since 9.0.0 */ - public function changeLock($path, $type, ILockingProvider $provider); + public function changeLock(string $path, int $type, ILockingProvider $provider); } diff --git a/lib/public/Files/Storage/INotifyStorage.php b/lib/public/Files/Storage/INotifyStorage.php index 8656f709116..063ff815581 100644 --- a/lib/public/Files/Storage/INotifyStorage.php +++ b/lib/public/Files/Storage/INotifyStorage.php @@ -1,4 +1,5 @@ <?php + /** * SPDX-FileCopyrightText: 2016 Nextcloud GmbH and Nextcloud contributors * SPDX-License-Identifier: AGPL-3.0-or-later @@ -36,10 +37,9 @@ interface INotifyStorage { /** * Start the notification handler for this storage * - * @param $path * @return INotifyHandler * * @since 12.0.0 */ - public function notify($path); + public function notify(string $path); } diff --git a/lib/public/Files/Storage/ISharedStorage.php b/lib/public/Files/Storage/ISharedStorage.php new file mode 100644 index 00000000000..69fc60750c5 --- /dev/null +++ b/lib/public/Files/Storage/ISharedStorage.php @@ -0,0 +1,25 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Files\Storage; + +use OCP\Share\IShare; + +/** + * Interface for a storage that is based on a file share + * + * @since 30.0.0 + */ +interface ISharedStorage extends IStorage { + /** + * The the associated share + * + * @since 30.0.0 + */ + public function getShare(): IShare; +} diff --git a/lib/public/Files/Storage/IStorage.php b/lib/public/Files/Storage/IStorage.php index e18d6768346..5f6c8a0e8a0 100644 --- a/lib/public/Files/Storage/IStorage.php +++ b/lib/public/Files/Storage/IStorage.php @@ -23,17 +23,10 @@ use OCP\Files\InvalidPathException; * All paths passed to the storage are relative to the storage and should NOT have a leading slash. * * @since 9.0.0 + * @since 31.0.0 Moved the constructor to IConstructableStorage so that wrappers can use DI */ interface IStorage { /** - * $parameters is a free form array with the configuration options needed to construct the storage - * - * @param array $parameters - * @since 9.0.0 - */ - public function __construct($parameters); - - /** * Get the identifier for the storage, * the returned id should be the same for every storage object that is created with the same parameters * and two storage objects with the same id should refer to two storages that display the same files. @@ -47,280 +40,243 @@ interface IStorage { * see https://www.php.net/manual/en/function.mkdir.php * implementations need to implement a recursive mkdir * - * @param string $path * @return bool * @since 9.0.0 */ - public function mkdir($path); + public function mkdir(string $path); /** * see https://www.php.net/manual/en/function.rmdir.php * - * @param string $path * @return bool * @since 9.0.0 */ - public function rmdir($path); + public function rmdir(string $path); /** * see https://www.php.net/manual/en/function.opendir.php * - * @param string $path * @return resource|false * @since 9.0.0 */ - public function opendir($path); + public function opendir(string $path); /** * see https://www.php.net/manual/en/function.is-dir.php * - * @param string $path * @return bool * @since 9.0.0 */ - public function is_dir($path); + public function is_dir(string $path); /** * see https://www.php.net/manual/en/function.is-file.php * - * @param string $path * @return bool * @since 9.0.0 */ - public function is_file($path); + public function is_file(string $path); /** * see https://www.php.net/manual/en/function.stat.php * only the following keys are required in the result: size and mtime * - * @param string $path - * @return array|bool + * @return array|false * @since 9.0.0 */ - public function stat($path); + public function stat(string $path); /** * see https://www.php.net/manual/en/function.filetype.php * - * @param string $path - * @return string|bool + * @return string|false * @since 9.0.0 */ - public function filetype($path); + public function filetype(string $path); /** * see https://www.php.net/manual/en/function.filesize.php * The result for filesize when called on a folder is required to be 0 * - * @param string $path - * @return false|int|float + * @return int|float|false * @since 9.0.0 */ - public function filesize($path); + public function filesize(string $path); /** * check if a file can be created in $path * - * @param string $path * @return bool * @since 9.0.0 */ - public function isCreatable($path); + public function isCreatable(string $path); /** * check if a file can be read * - * @param string $path * @return bool * @since 9.0.0 */ - public function isReadable($path); + public function isReadable(string $path); /** * check if a file can be written to * - * @param string $path * @return bool * @since 9.0.0 */ - public function isUpdatable($path); + public function isUpdatable(string $path); /** * check if a file can be deleted * - * @param string $path * @return bool * @since 9.0.0 */ - public function isDeletable($path); + public function isDeletable(string $path); /** * check if a file can be shared * - * @param string $path * @return bool * @since 9.0.0 */ - public function isSharable($path); + public function isSharable(string $path); /** * get the full permissions of a path. * Should return a combination of the PERMISSION_ constants defined in lib/public/constants.php * - * @param string $path * @return int * @since 9.0.0 */ - public function getPermissions($path); + public function getPermissions(string $path); /** - * see https://www.php.net/manual/en/function.file_exists.php + * see https://www.php.net/manual/en/function.file-exists.php * - * @param string $path * @return bool * @since 9.0.0 */ - public function file_exists($path); + public function file_exists(string $path); /** * see https://www.php.net/manual/en/function.filemtime.php * - * @param string $path - * @return int|bool + * @return int|false * @since 9.0.0 */ - public function filemtime($path); + public function filemtime(string $path); /** - * see https://www.php.net/manual/en/function.file_get_contents.php + * see https://www.php.net/manual/en/function.file-get-contents.php * - * @param string $path * @return string|false * @since 9.0.0 */ - public function file_get_contents($path); + public function file_get_contents(string $path); /** - * see https://www.php.net/manual/en/function.file_put_contents.php + * see https://www.php.net/manual/en/function.file-put-contents.php * - * @param string $path - * @param mixed $data * @return int|float|false * @since 9.0.0 */ - public function file_put_contents($path, $data); + public function file_put_contents(string $path, mixed $data); /** * see https://www.php.net/manual/en/function.unlink.php * - * @param string $path * @return bool * @since 9.0.0 */ - public function unlink($path); + public function unlink(string $path); /** * see https://www.php.net/manual/en/function.rename.php * - * @param string $source - * @param string $target * @return bool * @since 9.0.0 */ - public function rename($source, $target); + public function rename(string $source, string $target); /** * see https://www.php.net/manual/en/function.copy.php * - * @param string $source - * @param string $target * @return bool * @since 9.0.0 */ - public function copy($source, $target); + public function copy(string $source, string $target); /** * see https://www.php.net/manual/en/function.fopen.php * - * @param string $path - * @param string $mode - * @return resource|bool + * @return resource|false * @since 9.0.0 */ - public function fopen($path, $mode); + public function fopen(string $path, string $mode); /** * get the mimetype for a file or folder * The mimetype for a folder is required to be "httpd/unix-directory" * - * @param string $path - * @return string|bool + * @return string|false * @since 9.0.0 */ - public function getMimeType($path); + public function getMimeType(string $path); /** * see https://www.php.net/manual/en/function.hash-file.php * - * @param string $type - * @param string $path - * @param bool $raw - * @return string|bool + * @return string|false * @since 9.0.0 */ - public function hash($type, $path, $raw = false); + public function hash(string $type, string $path, bool $raw = false); /** - * see https://www.php.net/manual/en/function.free_space.php + * see https://www.php.net/manual/en/function.disk-free-space.php * - * @param string $path - * @return int|float|bool + * @return int|float|false * @since 9.0.0 */ - public function free_space($path); + public function free_space(string $path); /** * see https://www.php.net/manual/en/function.touch.php * If the backend does not support the operation, false should be returned * - * @param string $path - * @param int $mtime * @return bool * @since 9.0.0 */ - public function touch($path, $mtime = null); + public function touch(string $path, ?int $mtime = null); /** * get the path to a local version of the file. * The local version of the file can be temporary and doesn't have to be persistent across requests * - * @param string $path * @return string|false * @since 9.0.0 */ - public function getLocalFile($path); + public function getLocalFile(string $path); /** * check if a file or folder has been updated since $time * - * @param string $path - * @param int $time * @return bool * @since 9.0.0 * * hasUpdated for folders should return at least true if a file inside the folder is add, removed or renamed. * returning true for other changes in the folder is optional */ - public function hasUpdated($path, $time); + public function hasUpdated(string $path, int $time); /** * get the ETag for a file or folder * - * @param string $path * @return string|false * @since 9.0.0 */ - public function getETag($path); + public function getETag(string $path); /** * Returns whether the storage is local, which means that files @@ -338,51 +294,41 @@ interface IStorage { * Check if the storage is an instance of $class or is a wrapper for a storage that is an instance of $class * * @template T of IStorage - * @param string $class * @psalm-param class-string<T> $class * @return bool * @since 9.0.0 * @psalm-assert-if-true T $this */ - public function instanceOfStorage($class); + public function instanceOfStorage(string $class); /** * A custom storage implementation can return an url for direct download of a give file. * * For now the returned array can hold the parameter url - in future more attributes might follow. * - * @param string $path - * @return array|bool + * @return array|false * @since 9.0.0 */ - public function getDirectDownload($path); + public function getDirectDownload(string $path); /** - * @param string $path the path of the target folder - * @param string $fileName the name of the file itself * @return void * @throws InvalidPathException * @since 9.0.0 */ - public function verifyPath($path, $fileName); + public function verifyPath(string $path, string $fileName); /** - * @param IStorage $sourceStorage - * @param string $sourceInternalPath - * @param string $targetInternalPath * @return bool * @since 9.0.0 */ - public function copyFromStorage(IStorage $sourceStorage, $sourceInternalPath, $targetInternalPath); + public function copyFromStorage(IStorage $sourceStorage, string $sourceInternalPath, string $targetInternalPath); /** - * @param IStorage $sourceStorage - * @param string $sourceInternalPath - * @param string $targetInternalPath * @return bool * @since 9.0.0 */ - public function moveFromStorage(IStorage $sourceStorage, $sourceInternalPath, $targetInternalPath); + public function moveFromStorage(IStorage $sourceStorage, string $sourceInternalPath, string $targetInternalPath); /** * Test a storage for availability @@ -400,23 +346,28 @@ interface IStorage { /** * @since 9.0.0 - * @param bool $isAvailable + * @return void + */ + public function setAvailability(bool $isAvailable); + + /** + * @since 12.0.0 + * @since 31.0.0 moved from Storage to IStorage + * @return bool */ - public function setAvailability($isAvailable); + public function needsPartFile(); /** - * @param string $path path for which to retrieve the owner + * @return string|false * @since 9.0.0 */ - public function getOwner($path); + public function getOwner(string $path); /** - * @param string $path - * @param IStorage|null $storage * @return ICache * @since 9.0.0 */ - public function getCache($path = '', $storage = null); + public function getCache(string $path = '', ?IStorage $storage = null); /** * @return IPropagator @@ -448,7 +399,7 @@ interface IStorage { * This can be used for storages that do not have a dedicated owner, where we want to * pass the user that we setup the mountpoint for along to the storage layer * - * @param string|null $user Owner user id + * @param ?string $user Owner user id * @return void * @since 30.0.0 */ diff --git a/lib/public/Files/Storage/IStorageFactory.php b/lib/public/Files/Storage/IStorageFactory.php index 7c207ca9f0a..24f87d2e775 100644 --- a/lib/public/Files/Storage/IStorageFactory.php +++ b/lib/public/Files/Storage/IStorageFactory.php @@ -19,20 +19,15 @@ interface IStorageFactory { * * $callback should be a function of type (string $mountPoint, Storage $storage) => Storage * - * @param string $wrapperName - * @param callable $callback * @return bool true if the wrapper was added, false if there was already a wrapper with this - * name registered + * name registered * @since 8.0.0 */ - public function addStorageWrapper($wrapperName, $callback); + public function addStorageWrapper(string $wrapperName, callable $callback); /** - * @param \OCP\Files\Mount\IMountPoint $mountPoint - * @param string $class - * @param array $arguments - * @return \OCP\Files\Storage + * @return IStorage * @since 8.0.0 */ - public function getInstance(IMountPoint $mountPoint, $class, $arguments); + public function getInstance(IMountPoint $mountPoint, string $class, array $arguments); } diff --git a/lib/public/Files/Storage/IWriteStreamStorage.php b/lib/public/Files/Storage/IWriteStreamStorage.php index 6da34563848..b03f46ef2bc 100644 --- a/lib/public/Files/Storage/IWriteStreamStorage.php +++ b/lib/public/Files/Storage/IWriteStreamStorage.php @@ -19,9 +19,8 @@ interface IWriteStreamStorage extends IStorage { /** * Write the data from a stream to a file * - * @param string $path * @param resource $stream - * @param int|null $size the size of the stream if known in advance + * @param ?int $size the size of the stream if known in advance * @return int the number of bytes written * @throws GenericFileException * @since 15.0.0 diff --git a/lib/public/Files/Template/BeforeGetTemplatesEvent.php b/lib/public/Files/Template/BeforeGetTemplatesEvent.php new file mode 100644 index 00000000000..9fb7453a50c --- /dev/null +++ b/lib/public/Files/Template/BeforeGetTemplatesEvent.php @@ -0,0 +1,52 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +namespace OCP\Files\Template; + +use OCP\EventDispatcher\Event; + +/** + * @since 30.0.0 + */ +class BeforeGetTemplatesEvent extends Event { + /** @var array<Template> */ + private array $templates; + /** @var bool */ + private bool $withFields; + + /** + * @param array<Template> $templates + * + * @since 30.0.0 + */ + public function __construct(array $templates, bool $withFields = false) { + parent::__construct(); + + $this->templates = $templates; + $this->withFields = $withFields; + } + + /** + * @return array<Template> + * + * @since 30.0.0 + */ + public function getTemplates(): array { + return $this->templates; + } + + /** + * @return bool + * + * @since 32.0.0 + */ + public function shouldGetFields(): bool { + return $this->withFields; + } +} diff --git a/lib/public/Files/Template/Field.php b/lib/public/Files/Template/Field.php new file mode 100644 index 00000000000..e047e83a29e --- /dev/null +++ b/lib/public/Files/Template/Field.php @@ -0,0 +1,55 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +namespace OCP\Files\Template; + +/** + * @since 30.0.0 + */ +abstract class Field implements \JsonSerializable { + public ?string $alias = null; + public ?string $tag = null; + public ?int $id = null; + + /** + * @since 30.0.0 + */ + public function __construct( + private string $index, + private FieldType $type, + ) { + } + + /** + * @since 30.0.0 + */ + abstract public function setValue(mixed $value): void; + + /** + * @return array{ + * index: string, + * type: string, + * alias: ?string, + * tag: ?string, + * id: ?int, + * content?: string, + * checked?: bool, + * } + * @since 30.0.0 + */ + public function jsonSerialize(): array { + return [ + 'index' => $this->index, + 'type' => $this->type->value, + 'alias' => $this->alias, + 'tag' => $this->tag, + 'id' => $this->id, + ]; + } +} diff --git a/lib/public/Files/Template/FieldFactory.php b/lib/public/Files/Template/FieldFactory.php new file mode 100644 index 00000000000..f14d44a8573 --- /dev/null +++ b/lib/public/Files/Template/FieldFactory.php @@ -0,0 +1,32 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +namespace OCP\Files\Template; + +use OCP\Files\Template\Fields\CheckBoxField; +use OCP\Files\Template\Fields\RichTextField; + +/** + * @since 30.0.0 + */ +class FieldFactory { + /** + * @since 30.0.0 + */ + public static function createField( + string $index, + FieldType $type, + ): Field { + return match ($type) { + FieldType::RichText => new RichTextField($index, $type), + FieldType::CheckBox => new CheckBoxField($index, $type), + default => throw new InvalidFieldTypeException(), + }; + } +} diff --git a/lib/public/Files/Template/FieldType.php b/lib/public/Files/Template/FieldType.php new file mode 100644 index 00000000000..2d059cadc17 --- /dev/null +++ b/lib/public/Files/Template/FieldType.php @@ -0,0 +1,19 @@ +<?php + +/** + * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +namespace OCP\Files\Template; + +/** + * @since 30.0.0 + */ +enum FieldType: string { + case RichText = 'rich-text'; + case CheckBox = 'checkbox'; + case DropDownList = 'drop-down-list'; + case Picture = 'picture'; + case Date = 'date'; +} diff --git a/lib/public/Files/Template/Fields/CheckBoxField.php b/lib/public/Files/Template/Fields/CheckBoxField.php new file mode 100644 index 00000000000..6fab3ce66a6 --- /dev/null +++ b/lib/public/Files/Template/Fields/CheckBoxField.php @@ -0,0 +1,56 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +namespace OCP\Files\Template\Fields; + +use OCP\Files\Template\Field; +use OCP\Files\Template\FieldType; + +/** + * @since 30.0.0 + */ +class CheckBoxField extends Field { + private bool $checked = false; + + /** + * @since 30.0.0 + */ + public function __construct(string $index, FieldType $type) { + parent::__construct($index, $type); + } + + /** + * @since 30.0.0 + */ + public function setValue(mixed $value): void { + if (!is_bool($value)) { + throw new \Exception('Invalid value for checkbox field type'); + } + + $this->checked = $value; + } + + /** + * @return array{ + * index: string, + * type: string, + * alias: ?string, + * tag: ?string, + * id: ?int, + * content?: string, + * checked?: bool, + * } + * @since 30.0.0 + */ + public function jsonSerialize(): array { + $jsonProperties = parent::jsonSerialize(); + + return array_merge($jsonProperties, ['checked' => $this->checked]); + } +} diff --git a/lib/public/Files/Template/Fields/RichTextField.php b/lib/public/Files/Template/Fields/RichTextField.php new file mode 100644 index 00000000000..93ead68747c --- /dev/null +++ b/lib/public/Files/Template/Fields/RichTextField.php @@ -0,0 +1,56 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +namespace OCP\Files\Template\Fields; + +use OCP\Files\Template\Field; +use OCP\Files\Template\FieldType; + +/** + * @since 30.0.0 + */ +class RichTextField extends Field { + private string $content = ''; + + /** + * @since 30.0.0 + */ + public function __construct(string $index, FieldType $type) { + parent::__construct($index, $type); + } + + /** + * @since 30.0.0 + */ + public function setValue(mixed $value): void { + if (!is_string($value)) { + throw new \Exception('Invalid value for rich-text field type'); + } + + $this->content = $value; + } + + /** + * @return array{ + * index: string, + * type: string, + * alias: ?string, + * tag: ?string, + * id: ?int, + * content?: string, + * checked?: bool, + * } + * @since 30.0.0 + */ + public function jsonSerialize(): array { + $jsonProperties = parent::jsonSerialize(); + + return array_merge($jsonProperties, ['content' => $this->content]); + } +} diff --git a/lib/public/Files/Template/FileCreatedFromTemplateEvent.php b/lib/public/Files/Template/FileCreatedFromTemplateEvent.php index ed585504f70..0636d1dc251 100644 --- a/lib/public/Files/Template/FileCreatedFromTemplateEvent.php +++ b/lib/public/Files/Template/FileCreatedFromTemplateEvent.php @@ -17,15 +17,17 @@ use OCP\Files\File; class FileCreatedFromTemplateEvent extends Event { private $template; private $target; + private $templateFields; /** * @param File|null $template * @param File $target * @since 21.0.0 */ - public function __construct(?File $template, File $target) { + public function __construct(?File $template, File $target, array $templateFields) { $this->template = $template; $this->target = $target; + $this->templateFields = $templateFields; } /** @@ -37,6 +39,14 @@ class FileCreatedFromTemplateEvent extends Event { } /** + * @return array + * @since 30.0.0 + */ + public function getTemplateFields(): array { + return $this->templateFields; + } + + /** * @return File * @since 21.0.0 */ diff --git a/lib/public/Files/Template/ICustomTemplateProvider.php b/lib/public/Files/Template/ICustomTemplateProvider.php index 305f2c9a55e..6136bc4f1c0 100644 --- a/lib/public/Files/Template/ICustomTemplateProvider.php +++ b/lib/public/Files/Template/ICustomTemplateProvider.php @@ -17,7 +17,7 @@ interface ICustomTemplateProvider { /** * Return a list of additional templates that the template provider is offering * - * @return File[] + * @return Template[] * @since 21.0.0 */ public function getCustomTemplates(string $mimetype): array; diff --git a/lib/public/Files/Template/ITemplateManager.php b/lib/public/Files/Template/ITemplateManager.php index 5adcc0ded25..df81bc5604e 100644 --- a/lib/public/Files/Template/ITemplateManager.php +++ b/lib/public/Files/Template/ITemplateManager.php @@ -33,12 +33,21 @@ interface ITemplateManager { /** * Get a list of available file creators and their offered templates * - * @return array + * @return list<array{app: string, label: string, extension: string, iconClass: ?string, iconSvgInline: ?string, mimetypes: list<string>, ratio: ?float, actionLabel: string, templates: list<Template>}> * @since 21.0.0 */ public function listTemplates(): array; /** + * Get the fields for a given template + * + * @param int $fileId + * @return array + * @since 32.0.0 + */ + public function listTemplateFields(int $fileId): array; + + /** * @return bool * @since 21.0.0 */ @@ -67,9 +76,11 @@ interface ITemplateManager { /** * @param string $filePath * @param string $templateId + * @param string $templateType + * @param array $templateFields Since 30.0.0 * @return array * @throws GenericFileException * @since 21.0.0 */ - public function createFromTemplate(string $filePath, string $templateId = '', string $templateType = 'user'): array; + public function createFromTemplate(string $filePath, string $templateId = '', string $templateType = 'user', array $templateFields = []): array; } diff --git a/lib/public/Files/Template/InvalidFieldTypeException.php b/lib/public/Files/Template/InvalidFieldTypeException.php new file mode 100644 index 00000000000..a0c5297526c --- /dev/null +++ b/lib/public/Files/Template/InvalidFieldTypeException.php @@ -0,0 +1,15 @@ +<?php + +/** + * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +namespace OCP\Files\Template; + +/** + * Exception for invalid template field type + * @since 30.0.0 + */ +class InvalidFieldTypeException extends \Exception { +} diff --git a/lib/public/Files/Template/RegisterTemplateCreatorEvent.php b/lib/public/Files/Template/RegisterTemplateCreatorEvent.php index 4f739b1f9d3..a9e7fa01252 100644 --- a/lib/public/Files/Template/RegisterTemplateCreatorEvent.php +++ b/lib/public/Files/Template/RegisterTemplateCreatorEvent.php @@ -1,4 +1,5 @@ <?php + /** * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors * SPDX-License-Identifier: AGPL-3.0-or-later @@ -17,7 +18,7 @@ class RegisterTemplateCreatorEvent extends Event { * @since 30.0.0 */ public function __construct( - private ITemplateManager $templateManager + private ITemplateManager $templateManager, ) { } diff --git a/lib/public/Files/Template/Template.php b/lib/public/Files/Template/Template.php index 94f5cec268f..7f01c2afa48 100644 --- a/lib/public/Files/Template/Template.php +++ b/lib/public/Files/Template/Template.php @@ -24,6 +24,8 @@ final class Template implements \JsonSerializable { private $hasPreview = false; /** @var string|null */ private $previewUrl = null; + /** @var list<Field> */ + private $fields = []; /** * @since 21.0.0 @@ -49,6 +51,37 @@ final class Template implements \JsonSerializable { } /** + * @param list<Field> $fields + * @since 30.0.0 + */ + public function setFields(array $fields): void { + $this->fields = $fields; + } + + /** + * @return array{ + * templateType: string, + * templateId: string, + * basename: string, + * etag: string, + * fileid: int, + * filename: string, + * lastmod: int, + * mime: string, + * size: int|float, + * type: string, + * hasPreview: bool, + * previewUrl: ?string, + * fields: list<array{ + * index: string, + * type: string, + * alias: ?string, + * tag: ?string, + * id: ?int, + * content?: string, + * checked?: bool, + * }>, + * } * @since 21.0.0 */ public function jsonSerialize(): array { @@ -64,7 +97,8 @@ final class Template implements \JsonSerializable { 'size' => $this->file->getSize(), 'type' => $this->file->getType(), 'hasPreview' => $this->hasPreview, - 'previewUrl' => $this->previewUrl + 'previewUrl' => $this->previewUrl, + 'fields' => array_map(static fn (Field $field) => $field->jsonSerialize(), $this->fields), ]; } } diff --git a/lib/public/Files/Template/TemplateFileCreator.php b/lib/public/Files/Template/TemplateFileCreator.php index b8174ec3ea0..809bd3d0bc2 100644 --- a/lib/public/Files/Template/TemplateFileCreator.php +++ b/lib/public/Files/Template/TemplateFileCreator.php @@ -13,7 +13,7 @@ namespace OCP\Files\Template; */ final class TemplateFileCreator implements \JsonSerializable { protected $appId; - /** @var string[] $mimetypes */ + /** @var list<string> $mimetypes */ protected $mimetypes = []; protected $actionName; protected $fileExtension; @@ -34,7 +34,7 @@ final class TemplateFileCreator implements \JsonSerializable { * @since 21.0.0 */ public function __construct( - string $appId, string $actionName, string $fileExtension + string $appId, string $actionName, string $fileExtension, ) { $this->appId = $appId; $this->actionName = $actionName; @@ -121,7 +121,7 @@ final class TemplateFileCreator implements \JsonSerializable { /** * @since 21.0.0 - * @return array{app: string, label: string, extension: string, iconClass: ?string, iconSvgInline: ?string, mimetypes: string[], ratio: ?float, actionLabel: string} + * @return array{app: string, label: string, extension: string, iconClass: ?string, iconSvgInline: ?string, mimetypes: list<string>, ratio: ?float, actionLabel: string} */ public function jsonSerialize(): array { return [ |