diff options
Diffstat (limited to 'lib/public/Files')
141 files changed, 3095 insertions, 2949 deletions
diff --git a/lib/public/Files/AlreadyExistsException.php b/lib/public/Files/AlreadyExistsException.php index ede7c446f49..1935243a79c 100644 --- a/lib/public/Files/AlreadyExistsException.php +++ b/lib/public/Files/AlreadyExistsException.php @@ -1,35 +1,12 @@ <?php -/** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Morris Jobke <hey@morrisjobke.de> - * @author Robin Appelman <robin@icewind.nl> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * - */ /** - * Public interface of ownCloud for apps to use. - * Files/AlreadyExistsException class + * 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 ownCloud classes +// This means that they should be used by apps instead of the internal Nextcloud classes namespace OCP\Files; diff --git a/lib/public/Files/AppData/IAppDataFactory.php b/lib/public/Files/AppData/IAppDataFactory.php new file mode 100644 index 00000000000..e23b9cadfcb --- /dev/null +++ b/lib/public/Files/AppData/IAppDataFactory.php @@ -0,0 +1,24 @@ +<?php + +/** + * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Files\AppData; + +use OCP\Files\IAppData; + +/** + * A factory allows you to get the AppData folder for an application. + * + * @since 25.0.0 + */ +interface IAppDataFactory { + /** + * Get the AppData folder for the specified $appId + * @param string $appId + * @return IAppData + * @since 25.0.0 + */ + public function get(string $appId): IAppData; +} diff --git a/lib/public/Files/Cache/AbstractCacheEvent.php b/lib/public/Files/Cache/AbstractCacheEvent.php index 31d31699804..b2f01b2e470 100644 --- a/lib/public/Files/Cache/AbstractCacheEvent.php +++ b/lib/public/Files/Cache/AbstractCacheEvent.php @@ -3,29 +3,9 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2019 Robin Appelman <robin@icewind.nl> - * - * @author Joas Schilling <coding@schilljs.com> - * @author Robin Appelman <robin@icewind.nl> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Cache; use OCP\EventDispatcher\Event; diff --git a/lib/public/Files/Cache/CacheEntryInsertedEvent.php b/lib/public/Files/Cache/CacheEntryInsertedEvent.php index 5c57103259e..c3afe0f034f 100644 --- a/lib/public/Files/Cache/CacheEntryInsertedEvent.php +++ b/lib/public/Files/Cache/CacheEntryInsertedEvent.php @@ -3,27 +3,9 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2020 Robin Appelman <robin@icewind.nl> - * - * @author Robin Appelman <robin@icewind.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2020 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Cache; /** diff --git a/lib/public/Files/Cache/CacheEntryRemovedEvent.php b/lib/public/Files/Cache/CacheEntryRemovedEvent.php index 92075e4282b..d0f8c47b430 100644 --- a/lib/public/Files/Cache/CacheEntryRemovedEvent.php +++ b/lib/public/Files/Cache/CacheEntryRemovedEvent.php @@ -3,27 +3,9 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2020 Robin Appelman <robin@icewind.nl> - * - * @author Robin Appelman <robin@icewind.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2020 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Cache; /** diff --git a/lib/public/Files/Cache/CacheEntryUpdatedEvent.php b/lib/public/Files/Cache/CacheEntryUpdatedEvent.php index 94b1dd7a8b3..91dcf5340aa 100644 --- a/lib/public/Files/Cache/CacheEntryUpdatedEvent.php +++ b/lib/public/Files/Cache/CacheEntryUpdatedEvent.php @@ -3,27 +3,9 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2020 Robin Appelman <robin@icewind.nl> - * - * @author Robin Appelman <robin@icewind.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2020 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Cache; /** diff --git a/lib/public/Files/Cache/CacheInsertEvent.php b/lib/public/Files/Cache/CacheInsertEvent.php index 08ab15f9a2d..18a64cfb36b 100644 --- a/lib/public/Files/Cache/CacheInsertEvent.php +++ b/lib/public/Files/Cache/CacheInsertEvent.php @@ -3,27 +3,9 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2019 Robin Appelman <robin@icewind.nl> - * - * @author Robin Appelman <robin@icewind.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Cache; /** diff --git a/lib/public/Files/Cache/CacheUpdateEvent.php b/lib/public/Files/Cache/CacheUpdateEvent.php index 54397045398..7c2a290bd1d 100644 --- a/lib/public/Files/Cache/CacheUpdateEvent.php +++ b/lib/public/Files/Cache/CacheUpdateEvent.php @@ -3,27 +3,9 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2019 Robin Appelman <robin@icewind.nl> - * - * @author Robin Appelman <robin@icewind.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Cache; /** diff --git a/lib/public/Files/Cache/ICache.php b/lib/public/Files/Cache/ICache.php index 95ca29c2aa8..cd610b15545 100644 --- a/lib/public/Files/Cache/ICache.php +++ b/lib/public/Files/Cache/ICache.php @@ -1,46 +1,46 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Robin Appelman <robin@icewind.nl> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ - namespace OCP\Files\Cache; +use OCP\Files\Search\ISearchOperator; use OCP\Files\Search\ISearchQuery; /** * Metadata cache for a storage * - * The cache stores the metadata for all files and folders in a storage and is kept up to date trough the following mechanisms: + * The cache stores the metadata for all files and folders in a storage and is kept up to date through the following mechanisms: * * - Scanner: scans the storage and updates the cache where needed - * - Watcher: checks for changes made to the filesystem outside of the ownCloud instance and rescans files and folder when a change is detected - * - Updater: listens to changes made to the filesystem inside of the ownCloud instance and updates the cache where needed + * - Watcher: checks for changes made to the filesystem outside of the Nextcloud instance and rescans files and folder when a change is detected + * - Updater: listens to changes made to the filesystem inside of the Nextcloud instance and updates the cache where needed * - ChangePropagator: updates the mtime and etags of parent folders whenever a change to the cache is made to the cache by the updater * * @since 9.0.0 */ interface ICache { + /** + * @since 9.0.0 + */ public const NOT_FOUND = 0; + + /** + * @since 9.0.0 + */ public const PARTIAL = 1; //only partial data available, file not cached in the database + + /** + * @since 9.0.0 + */ public const SHALLOW = 2; //folder in cache, but not all child files are completely scanned + + /** + * @since 9.0.0 + */ public const COMPLETE = 3; /** @@ -119,7 +119,7 @@ interface ICache { /** * get the file id for a file * - * A file id is a numeric id for a file or folder that's unique within an owncloud instance which stays the same for the lifetime of a file + * A file id is a numeric id for a file or folder that's unique within an Nextcloud instance which stays the same for the lifetime of a file * * File ids are easiest way for apps to store references to a file since unlike paths they are not affected by renames or sharing * @@ -180,6 +180,17 @@ interface ICache { public function moveFromCache(ICache $sourceCache, $sourcePath, $targetPath); /** + * Copy a file or folder in the cache + * + * @param ICache $sourceCache + * @param ICacheEntry $sourceEntry + * @param string $targetPath + * @return int fileid of copied entry + * @since 22.0.0 + */ + public function copyFromCache(ICache $sourceCache, ICacheEntry $sourceEntry, string $targetPath): int; + + /** * Get the scan status of a file * * - ICache::NOT_FOUND: File is not in the cache @@ -208,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 @@ -220,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); @@ -232,7 +243,7 @@ interface ICache { * use the one with the highest id gives the best result with the background scanner, since that is most * likely the folder where we stopped scanning previously * - * @return string|bool the path of the folder or false when no folder matched + * @return string|false the path of the folder or false when no folder matched * @since 9.0.0 */ public function getIncomplete(); @@ -254,4 +265,30 @@ interface ICache { * @since 9.0.0 */ public function normalize($path); + + /** + * Get the query expression required to filter files within this storage. + * + * In the most basic case this is just comparing the storage id + * but storage wrappers can add additional expressions to filter down things further + * + * @return ISearchOperator + * @since 22.0.0 + */ + public function getQueryFilterForStorage(): ISearchOperator; + + /** + * Construct a cache entry from a search result row *if* the entry belongs to this storage. + * + * This method will be called for every item in the search results, including results from different storages. + * It's the responsibility of this method to return `null` for all results that don't belong to this storage. + * + * Additionally some implementations might need to further process the resulting entry such as modifying the path + * or permissions of the result. + * + * @param ICacheEntry $rawEntry + * @return ICacheEntry|null + * @since 22.0.0 + */ + public function getCacheEntryFromSearchResult(ICacheEntry $rawEntry): ?ICacheEntry; } diff --git a/lib/public/Files/Cache/ICacheEntry.php b/lib/public/Files/Cache/ICacheEntry.php index 7a0e22496e0..28e673071fd 100644 --- a/lib/public/Files/Cache/ICacheEntry.php +++ b/lib/public/Files/Cache/ICacheEntry.php @@ -1,26 +1,10 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Robin Appelman <robin@icewind.nl> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ - namespace OCP\Files\Cache; use ArrayAccess; @@ -29,12 +13,16 @@ use ArrayAccess; * meta data for a file or folder * * @since 9.0.0 + * @template-extends ArrayAccess<string,mixed> * * This interface extends \ArrayAccess since v21.0.0, previous versions only * implemented it in the private implementation. Hence php would allow using the * object as array, while strictly speaking it didn't support this. */ interface ICacheEntry extends ArrayAccess { + /** + * @since 9.0.0 + */ public const DIRECTORY_MIMETYPE = 'httpd/unix-directory'; /** @@ -124,8 +112,8 @@ interface ICacheEntry extends ArrayAccess { public function getEtag(); /** - * Get the permissions for the file stored as bitwise combination of \OCP\PERMISSION_READ, \OCP\PERMISSION_CREATE - * \OCP\PERMISSION_UPDATE, \OCP\PERMISSION_DELETE and \OCP\PERMISSION_SHARE + * Get the permissions for the file stored as bitwise combination of \OCP\Constants::PERMISSION_READ, \OCP\Constants::PERMISSION_CREATE + * \OCP\Constants::PERMISSION_UPDATE, \OCP\Constants::PERMISSION_DELETE and \OCP\Constants::PERMISSION_SHARE * * @return int * @since 9.0.0 @@ -163,4 +151,22 @@ interface ICacheEntry extends ArrayAccess { * @since 18.0.0 */ public function getUploadTime(): ?int; + + /** + * Get the unencrypted size + * + * This might be different from the result of getSize + * + * @return int + * @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/ICacheEvent.php b/lib/public/Files/Cache/ICacheEvent.php index 56f6f46df1c..a5659efd4a6 100644 --- a/lib/public/Files/Cache/ICacheEvent.php +++ b/lib/public/Files/Cache/ICacheEvent.php @@ -3,28 +3,9 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2019 Robin Appelman <robin@icewind.nl> - * - * @author Joas Schilling <coding@schilljs.com> - * @author Robin Appelman <robin@icewind.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Cache; use OCP\Files\Storage\IStorage; diff --git a/lib/public/Files/Cache/IFileAccess.php b/lib/public/Files/Cache/IFileAccess.php new file mode 100644 index 00000000000..7a993d81e7a --- /dev/null +++ b/lib/public/Files/Cache/IFileAccess.php @@ -0,0 +1,114 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Files\Cache; + +/** + * Low level access to the file cache. + * + * This is intended for use cases where data from the filecache needs to be loaded, but the full filesystem apis are + * insufficient or too inefficient for the use-case. + * + * @since 29.0.0 + */ +interface IFileAccess { + /** + * Get a filecache data by file id from a specific storage. + * + * This is preferred over `getByFileId` when the storage id is known as it + * can be more efficient in some setups. + * + * @param int $fileId + * @param int $storageId + * @return ICacheEntry|null + * + * @since 29.0.0 + */ + public function getByFileIdInStorage(int $fileId, int $storageId): ?ICacheEntry; + + /** + * Get a filecache data by path and storage id. + * + * @param string $path + * @param int $storageId + * @return ICacheEntry|null + * + * @since 29.0.0 + */ + public function getByPathInStorage(string $path, int $storageId): ?ICacheEntry; + + /** + * Get a filecache data by file id. + * + * If the storage id is known then `getByFileIdInStorage` is preferred as it can be more efficient in some setups. + * + * @param int $fileId + * @return ICacheEntry|null + * + * @since 29.0.0 + */ + public function getByFileId(int $fileId): ?ICacheEntry; + + /** + * Get filecache data by file ids. + * + * If the storage id is known then `getByFileIdsInStorage` is preferred as it can be more efficient in some setups. + * + * @param int[] $fileIds + * @return array<int, ICacheEntry> + * + * @since 29.0.0 + */ + public function getByFileIds(array $fileIds): array; + + /** + * Get filecache data by file ids from a specific storage. + * + * This is prefered over `getByFileIds` when the storage id is known as it + * can be more efficient in some setups. + * + * @param int[] $fileIds + * @param int $storageId + * @return array<int, ICacheEntry> + * + * @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/IPropagator.php b/lib/public/Files/Cache/IPropagator.php index e5fb875453d..703cba59599 100644 --- a/lib/public/Files/Cache/IPropagator.php +++ b/lib/public/Files/Cache/IPropagator.php @@ -1,25 +1,10 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Robin Appelman <robin@icewind.nl> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ - namespace OCP\Files\Cache; /** @@ -50,7 +35,8 @@ interface IPropagator { /** * @param string $internalPath * @param int $time + * @param int $sizeDifference * @since 9.0.0 */ - public function propagateChange($internalPath, $time); + public function propagateChange($internalPath, $time, $sizeDifference = 0); } diff --git a/lib/public/Files/Cache/IScanner.php b/lib/public/Files/Cache/IScanner.php index 3b00fa2af13..9b3c283b436 100644 --- a/lib/public/Files/Cache/IScanner.php +++ b/lib/public/Files/Cache/IScanner.php @@ -1,26 +1,10 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Robin Appelman <robin@icewind.nl> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ - namespace OCP\Files\Cache; /** @@ -29,12 +13,34 @@ namespace OCP\Files\Cache; * @since 9.0.0 */ interface IScanner { + /** + * @since 9.0.0 + */ public const SCAN_RECURSIVE_INCOMPLETE = 2; // only recursive into not fully scanned folders + + /** + * @since 9.0.0 + */ public const SCAN_RECURSIVE = true; + + /** + * @since 9.0.0 + */ public const SCAN_SHALLOW = false; + /** + * @since 12.0.0 + */ public const REUSE_NONE = 0; + + /** + * @since 9.0.0 + */ public const REUSE_ETAG = 1; + + /** + * @since 9.0.0 + */ public const REUSE_SIZE = 2; /** @@ -45,7 +51,7 @@ interface IScanner { * @param int $parentId * @param array | null $cacheData existing data in the cache for the file to be scanned * @param bool $lock set to false to disable getting an additional read lock during scanning - * @return array an array of metadata of the scanned file + * @return array | null an array of metadata of the scanned file * @throws \OC\ServerNotAvailableException * @throws \OCP\Lock\LockedException * @since 9.0.0 @@ -59,7 +65,7 @@ interface IScanner { * @param bool $recursive * @param int $reuse * @param bool $lock set to false to disable getting an additional read lock during scanning - * @return array an array of the meta data of the scanned file or folder + * @return array | null an array of the meta data of the scanned file or folder * @since 9.0.0 */ public function scan($path, $recursive = self::SCAN_RECURSIVE, $reuse = -1, $lock = true); diff --git a/lib/public/Files/Cache/IUpdater.php b/lib/public/Files/Cache/IUpdater.php index 7211b52a9d2..2bc702114b4 100644 --- a/lib/public/Files/Cache/IUpdater.php +++ b/lib/public/Files/Cache/IUpdater.php @@ -1,25 +1,10 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Robin Appelman <robin@icewind.nl> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ - namespace OCP\Files\Cache; use OCP\Files\Storage\IStorage; @@ -54,7 +39,7 @@ interface IUpdater { * @param int $time * @since 9.0.0 */ - public function update($path, $time = null); + public function update($path, $time = null, ?int $sizeDifference = null); /** * Remove $path from the cache and update the size, etag and mtime of the parent folders @@ -73,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 9fc37c9b0ba..62b90f672c6 100644 --- a/lib/public/Files/Cache/IWatcher.php +++ b/lib/public/Files/Cache/IWatcher.php @@ -1,26 +1,10 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Robin Appelman <robin@icewind.nl> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ - namespace OCP\Files\Cache; /** @@ -29,8 +13,19 @@ namespace OCP\Files\Cache; * @since 9.0.0 */ interface IWatcher { + /** + * @since 9.0.0 + */ public const CHECK_NEVER = 0; // never check the underlying filesystem for updates + + /** + * @since 9.0.0 + */ public const CHECK_ONCE = 1; // check the underlying filesystem for updates once every request for each file + + /** + * @since 9.0.0 + */ public const CHECK_ALWAYS = 2; // always check the underlying filesystem for updates /** @@ -81,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 17adf5a4209..a9b30d8ba6d 100644 --- a/lib/public/Files/Config/ICachedMountFileInfo.php +++ b/lib/public/Files/Config/ICachedMountFileInfo.php @@ -1,26 +1,9 @@ <?php + /** - * @copyright Copyright (c) 2017 Robin Appelman <robin@icewind.nl> - * - * @author Robin Appelman <robin@icewind.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2017 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Config; /** @@ -35,11 +18,11 @@ interface ICachedMountFileInfo extends ICachedMountInfo { * @return string * @since 13.0.0 */ - public function getInternalPath(); + public function getInternalPath(): string; /** * @return string * @since 13.0.0 */ - public function getPath(); + public function getPath(): string; } diff --git a/lib/public/Files/Config/ICachedMountInfo.php b/lib/public/Files/Config/ICachedMountInfo.php index bf7481e2ebb..cb9c0205d3d 100644 --- a/lib/public/Files/Config/ICachedMountInfo.php +++ b/lib/public/Files/Config/ICachedMountInfo.php @@ -1,26 +1,10 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Robin Appelman <robin@icewind.nl> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ - namespace OCP\Files\Config; use OCP\Files\Node; @@ -36,31 +20,31 @@ interface ICachedMountInfo { * @return IUser * @since 9.0.0 */ - public function getUser(); + public function getUser(): IUser; /** * @return int the numeric storage id of the mount * @since 9.0.0 */ - public function getStorageId(); + public function getStorageId(): int; /** * @return int the fileid of the root of the mount * @since 9.0.0 */ - public function getRootId(); + public function getRootId(): int; /** - * @return Node the root node of the mount + * @return Node|null the root node of the mount * @since 9.0.0 */ - public function getMountPointNode(); + public function getMountPointNode(): ?Node; /** * @return string the mount point of the mount for the user * @since 9.0.0 */ - public function getMountPoint(); + public function getMountPoint(): string; /** * Get the id of the configured mount @@ -68,7 +52,7 @@ interface ICachedMountInfo { * @return int|null mount id or null if not applicable * @since 9.1.0 */ - public function getMountId(); + public function getMountId(): ?int; /** * Get the internal path (within the storage) of the root of the mount @@ -76,5 +60,21 @@ interface ICachedMountInfo { * @return string * @since 11.0.0 */ - public function getRootInternalPath(); + public function getRootInternalPath(): string; + + /** + * Get the class of the mount provider that this mount originates from + * + * @return string + * @since 24.0.0 + */ + public function getMountProvider(): string; + + /** + * Get a key that uniquely identifies the mount + * + * @return string + * @since 28.0.0 + */ + public function getKey(): string; } diff --git a/lib/public/Files/Config/IHomeMountProvider.php b/lib/public/Files/Config/IHomeMountProvider.php index c0d4b0a80f3..b193e9ba22e 100644 --- a/lib/public/Files/Config/IHomeMountProvider.php +++ b/lib/public/Files/Config/IHomeMountProvider.php @@ -1,25 +1,10 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Robin Appelman <robin@icewind.nl> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ - namespace OCP\Files\Config; use OCP\Files\Storage\IStorageFactory; diff --git a/lib/public/Files/Config/IMountProvider.php b/lib/public/Files/Config/IMountProvider.php index 629b74b4fe6..b59813a866d 100644 --- a/lib/public/Files/Config/IMountProvider.php +++ b/lib/public/Files/Config/IMountProvider.php @@ -1,26 +1,10 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Morris Jobke <hey@morrisjobke.de> - * @author Robin Appelman <robin@icewind.nl> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ - namespace OCP\Files\Config; use OCP\Files\Storage\IStorageFactory; diff --git a/lib/public/Files/Config/IMountProviderCollection.php b/lib/public/Files/Config/IMountProviderCollection.php index a4131514662..db5188372c1 100644 --- a/lib/public/Files/Config/IMountProviderCollection.php +++ b/lib/public/Files/Config/IMountProviderCollection.php @@ -1,26 +1,10 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Morris Jobke <hey@morrisjobke.de> - * @author Robin Appelman <robin@icewind.nl> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ - namespace OCP\Files\Config; use OCP\IUser; @@ -40,6 +24,16 @@ interface IMountProviderCollection { public function getMountsForUser(IUser $user); /** + * Get the configured mount points for the user from a specific mount provider + * + * @param \OCP\IUser $user + * @param class-string<IMountProvider>[] $mountProviderClasses + * @return \OCP\Files\Mount\IMountPoint[] + * @since 24.0.0 + */ + public function getUserMountsForProviderClasses(IUser $user, array $mountProviderClasses): array; + + /** * Get the configured home mount for this user * * @param \OCP\IUser $user diff --git a/lib/public/Files/Config/IRootMountProvider.php b/lib/public/Files/Config/IRootMountProvider.php index 48d2e9722d3..e2a32fc346a 100644 --- a/lib/public/Files/Config/IRootMountProvider.php +++ b/lib/public/Files/Config/IRootMountProvider.php @@ -3,27 +3,9 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2020, Morris Jobke <hey@morrisjobke.de> - * - * @author Morris Jobke <hey@morrisjobke.de> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2020 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Config; use OCP\Files\Storage\IStorageFactory; diff --git a/lib/public/Files/Config/IUserMountCache.php b/lib/public/Files/Config/IUserMountCache.php index cdb95078bc8..a5b68ded66d 100644 --- a/lib/public/Files/Config/IUserMountCache.php +++ b/lib/public/Files/Config/IUserMountCache.php @@ -1,30 +1,14 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Julius Härtl <jus@bitgrid.net> - * @author Morris Jobke <hey@morrisjobke.de> - * @author Robin Appelman <robin@icewind.nl> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ - namespace OCP\Files\Config; use OCP\Files\Mount\IMountPoint; +use OCP\Files\NotFoundException; use OCP\IUser; /** @@ -38,9 +22,10 @@ interface IUserMountCache { * * @param IUser $user * @param IMountPoint[] $mounts + * @param array|null $mountProviderClasses * @since 9.0.0 */ - public function registerMounts(IUser $user, array $mounts); + public function registerMounts(IUser $user, array $mounts, ?array $mountProviderClasses = null); /** * Get all cached mounts for a user @@ -111,7 +96,7 @@ interface IUserMountCache { * Get the used space for users * * Note that this only includes the space in their home directory, - * not any incoming shares or external storages. + * not any incoming shares or external storage. * * @param IUser[] $users * @return int[] [$userId => $userSpace] @@ -125,4 +110,26 @@ interface IUserMountCache { * @since 20.0.0 */ public function clear(): void; + + /** + * Get all cached mounts for a user + * + * @param IUser $user + * @param string $path + * @return ICachedMountInfo + * @throws NotFoundException + * @since 24.0.0 + */ + public function getMountForPath(IUser $user, string $path): ICachedMountInfo; + + /** + * Get all cached mounts for a user inside a path + * + * @param IUser $user + * @param string $path + * @return ICachedMountInfo[] + * @throws NotFoundException + * @since 24.0.0 + */ + public function getMountsInPath(IUser $user, string $path): array; } diff --git a/lib/public/Files/ConnectionLostException.php b/lib/public/Files/ConnectionLostException.php new file mode 100644 index 00000000000..3fd97b48901 --- /dev/null +++ b/lib/public/Files/ConnectionLostException.php @@ -0,0 +1,15 @@ +<?php + +declare(strict_types=1); +/** + * SPDX-FileCopyrightText: 2023-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-only + */ +namespace OCP\Files; + +/** + * Exception for lost connection with the + * @since 25.0.11 + */ +class ConnectionLostException extends \RuntimeException { +} 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 new file mode 100644 index 00000000000..6dde3179bb8 --- /dev/null +++ b/lib/public/Files/DavUtil.php @@ -0,0 +1,79 @@ +<?php + +/** + * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-only + */ + +namespace OCP\Files; + +use OCP\Constants; +use OCP\Files\Mount\IMovableMount; + +/** + * This class provides different helper functions related to WebDAV protocol + * + * @since 25.0.0 + */ +class DavUtil { + /** + * Compute the fileId to use for dav responses + * + * @param int $id Id of the file returned by FileInfo::getId + * @since 25.0.0 + */ + public static function getDavFileId(int $id): string { + $instanceId = \OC_Util::getInstanceId(); + $id = sprintf('%08d', $id); + return $id . $instanceId; + } + + /** + * Compute the format needed for returning permissions for dav + * + * @since 25.0.0 + */ + public static function getDavPermissions(FileInfo $info): string { + $permissions = $info->getPermissions(); + $p = ''; + if ($info->isShared()) { + $p .= 'S'; + } + if ($permissions & Constants::PERMISSION_SHARE) { + $p .= 'R'; + } + if ($info->isMounted()) { + $p .= 'M'; + } + if ($permissions & Constants::PERMISSION_READ) { + $p .= 'G'; + } + if ($permissions & Constants::PERMISSION_DELETE) { + $p .= 'D'; + } + if ($permissions & Constants::PERMISSION_UPDATE) { + $p .= 'NV'; // Renameable, Movable + } + + // since we always add update permissions for the root of movable mounts + // we need to check the shared cache item directly to determine if it's writable + $storage = $info->getStorage(); + if ($info->getInternalPath() === '' && $info->getMountPoint() instanceof IMovableMount) { + $rootEntry = $storage->getCache()->get(''); + $isWritable = $rootEntry->getPermissions() & Constants::PERMISSION_UPDATE; + } else { + $isWritable = $permissions & Constants::PERMISSION_UPDATE; + } + + if ($info->getType() === FileInfo::TYPE_FILE) { + if ($isWritable) { + $p .= 'W'; + } + } else { + if ($permissions & Constants::PERMISSION_CREATE) { + $p .= 'CK'; + } + } + return $p; + } +} diff --git a/lib/public/Files/EmptyFileNameException.php b/lib/public/Files/EmptyFileNameException.php index 65decb098d5..1630ce63ea2 100644 --- a/lib/public/Files/EmptyFileNameException.php +++ b/lib/public/Files/EmptyFileNameException.php @@ -1,26 +1,9 @@ <?php + /** - * @copyright Copyright (c) 2016 Joas Schilling <coding@schilljs.com> - * - * @author Joas Schilling <coding@schilljs.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/>. - * + * SPDX-FileCopyrightText: 2016 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files; /** diff --git a/lib/public/Files/EntityTooLargeException.php b/lib/public/Files/EntityTooLargeException.php index 66d924cf54a..f703d3cf414 100644 --- a/lib/public/Files/EntityTooLargeException.php +++ b/lib/public/Files/EntityTooLargeException.php @@ -1,35 +1,12 @@ <?php -/** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Morris Jobke <hey@morrisjobke.de> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * @author Thomas Müller <thomas.mueller@tmit.eu> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * - */ /** - * Public interface of ownCloud for apps to use. - * Files/EntityTooLargeException class + * 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 ownCloud classes +// This means that they should be used by apps instead of the internal Nextcloud classes namespace OCP\Files; diff --git a/lib/public/Files/Events/BeforeDirectFileDownloadEvent.php b/lib/public/Files/Events/BeforeDirectFileDownloadEvent.php new file mode 100644 index 00000000000..550a5e17496 --- /dev/null +++ b/lib/public/Files/Events/BeforeDirectFileDownloadEvent.php @@ -0,0 +1,69 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Files\Events; + +use OCP\EventDispatcher\Event; + +/** + * This event is triggered when a user tries to download a file + * directly. + * + * @since 25.0.0 + */ +class BeforeDirectFileDownloadEvent extends Event { + private string $path; + private bool $successful = true; + private ?string $errorMessage = null; + + /** + * @since 25.0.0 + */ + public function __construct(string $path) { + parent::__construct(); + $this->path = $path; + } + + /** + * @since 25.0.0 + */ + public function getPath(): string { + return $this->path; + } + + /** + * @since 25.0.0 + */ + public function isSuccessful(): bool { + return $this->successful; + } + + /** + * Set if the event was successful + * + * @since 25.0.0 + */ + public function setSuccessful(bool $successful): void { + $this->successful = $successful; + } + + /** + * Get the error message, if any + * @since 25.0.0 + */ + public function getErrorMessage(): ?string { + return $this->errorMessage; + } + + /** + * @since 25.0.0 + */ + public function setErrorMessage(string $errorMessage): void { + $this->errorMessage = $errorMessage; + } +} diff --git a/lib/public/Files/Events/BeforeFileScannedEvent.php b/lib/public/Files/Events/BeforeFileScannedEvent.php index c233c9e4a0e..70c9d23c156 100644 --- a/lib/public/Files/Events/BeforeFileScannedEvent.php +++ b/lib/public/Files/Events/BeforeFileScannedEvent.php @@ -3,27 +3,9 @@ declare(strict_types=1); /** - * @copyright 2019 Christoph Wurst <christoph@winzerhof-wurst.at> - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Events; use OCP\EventDispatcher\Event; @@ -32,7 +14,6 @@ use OCP\EventDispatcher\Event; * @since 18.0.0 */ class BeforeFileScannedEvent extends Event { - /** @var string */ private $absolutePath; 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/BeforeFolderScannedEvent.php b/lib/public/Files/Events/BeforeFolderScannedEvent.php index 5c8c05e9a21..cd72c79e8d8 100644 --- a/lib/public/Files/Events/BeforeFolderScannedEvent.php +++ b/lib/public/Files/Events/BeforeFolderScannedEvent.php @@ -3,27 +3,9 @@ declare(strict_types=1); /** - * @copyright 2019 Christoph Wurst <christoph@winzerhof-wurst.at> - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Events; use OCP\EventDispatcher\Event; @@ -32,7 +14,6 @@ use OCP\EventDispatcher\Event; * @since 18.0.0 */ class BeforeFolderScannedEvent extends Event { - /** @var string */ private $absolutePath; diff --git a/lib/public/Files/Events/BeforeZipCreatedEvent.php b/lib/public/Files/Events/BeforeZipCreatedEvent.php new file mode 100644 index 00000000000..0363d385d36 --- /dev/null +++ b/lib/public/Files/Events/BeforeZipCreatedEvent.php @@ -0,0 +1,98 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +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 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|Folder $directory, + private array $files, + ) { + parent::__construct(); + 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; + } + + /** + * @since 25.0.0 + */ + public function getDirectory(): string { + return $this->directory; + } + + /** + * @since 25.0.0 + */ + public function getFiles(): array { + return $this->files; + } + + /** + * @since 25.0.0 + */ + public function isSuccessful(): bool { + return $this->successful; + } + + /** + * Set if the event was successful + * + * @since 25.0.0 + */ + public function setSuccessful(bool $successful): void { + $this->successful = $successful; + } + + /** + * Get the error message, if any + * @since 25.0.0 + */ + public function getErrorMessage(): ?string { + return $this->errorMessage; + } + + /** + * @since 25.0.0 + */ + public function setErrorMessage(string $errorMessage): void { + $this->errorMessage = $errorMessage; + } +} diff --git a/lib/public/Files/Events/FileCacheUpdated.php b/lib/public/Files/Events/FileCacheUpdated.php index f370aec1cf2..7b3877bb05d 100644 --- a/lib/public/Files/Events/FileCacheUpdated.php +++ b/lib/public/Files/Events/FileCacheUpdated.php @@ -3,27 +3,9 @@ declare(strict_types=1); /** - * @copyright 2019 Christoph Wurst <christoph@winzerhof-wurst.at> - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Events; use OCP\EventDispatcher\Event; @@ -33,7 +15,6 @@ use OCP\Files\Storage\IStorage; * @since 18.0.0 */ class FileCacheUpdated extends Event { - /** @var IStorage */ private $storage; @@ -46,7 +27,7 @@ class FileCacheUpdated extends Event { * @since 18.0.0 */ public function __construct(IStorage $storage, - string $path) { + string $path) { parent::__construct(); $this->storage = $storage; $this->path = $path; diff --git a/lib/public/Files/Events/FileScannedEvent.php b/lib/public/Files/Events/FileScannedEvent.php index 69c0dd3c538..9ede4e2425f 100644 --- a/lib/public/Files/Events/FileScannedEvent.php +++ b/lib/public/Files/Events/FileScannedEvent.php @@ -3,27 +3,9 @@ declare(strict_types=1); /** - * @copyright 2019 Christoph Wurst <christoph@winzerhof-wurst.at> - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Events; use OCP\EventDispatcher\Event; @@ -32,7 +14,6 @@ use OCP\EventDispatcher\Event; * @since 18.0.0 */ class FileScannedEvent extends Event { - /** @var string */ private $absolutePath; diff --git a/lib/public/Files/Events/FolderScannedEvent.php b/lib/public/Files/Events/FolderScannedEvent.php index 642d14b4499..5e14bbfb6a8 100644 --- a/lib/public/Files/Events/FolderScannedEvent.php +++ b/lib/public/Files/Events/FolderScannedEvent.php @@ -3,27 +3,9 @@ declare(strict_types=1); /** - * @copyright 2019 Christoph Wurst <christoph@winzerhof-wurst.at> - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Events; use OCP\EventDispatcher\Event; @@ -32,7 +14,6 @@ use OCP\EventDispatcher\Event; * @since 18.0.0 */ class FolderScannedEvent extends Event { - /** @var string */ private $absolutePath; diff --git a/lib/public/Files/Events/InvalidateMountCacheEvent.php b/lib/public/Files/Events/InvalidateMountCacheEvent.php new file mode 100644 index 00000000000..a29281ddcec --- /dev/null +++ b/lib/public/Files/Events/InvalidateMountCacheEvent.php @@ -0,0 +1,40 @@ +<?php + +declare(strict_types=1); +/** + * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +namespace OCP\Files\Events; + +use OCP\EventDispatcher\Event; +use OCP\IUser; + +/** + * Used to notify the filesystem setup manager that the available mounts for a user have changed + * + * @since 24.0.0 + */ +class InvalidateMountCacheEvent extends Event { + private ?IUser $user; + + /** + * @param IUser|null $user user + * + * @since 24.0.0 + */ + public function __construct(?IUser $user) { + parent::__construct(); + $this->user = $user; + } + + /** + * @return IUser|null user + * + * @since 24.0.0 + */ + public function getUser(): ?IUser { + return $this->user; + } +} diff --git a/lib/public/Files/Events/Node/AbstractNodeEvent.php b/lib/public/Files/Events/Node/AbstractNodeEvent.php index 2e36e62bb2a..7afb71277f6 100644 --- a/lib/public/Files/Events/Node/AbstractNodeEvent.php +++ b/lib/public/Files/Events/Node/AbstractNodeEvent.php @@ -3,45 +3,26 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2020, Roeland Jago Douma <roeland@famdouma.nl> - * - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2020 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Events\Node; use OCP\EventDispatcher\Event; +use OCP\EventDispatcher\IWebhookCompatibleEvent; +use OCP\EventDispatcher\JsonSerializer; use OCP\Files\Node; /** * @since 20.0.0 */ -abstract class AbstractNodeEvent extends Event { - - /** @var Node */ - private $node; - +abstract class AbstractNodeEvent extends Event implements IWebhookCompatibleEvent { /** * @since 20.0.0 */ - public function __construct(Node $node) { - $this->node = $node; + public function __construct( + private Node $node, + ) { } /** @@ -50,4 +31,13 @@ abstract class AbstractNodeEvent extends Event { public function getNode(): Node { return $this->node; } + + /** + * @since 30.0.0 + */ + public function getWebhookSerializable(): array { + return [ + 'node' => JsonSerializer::serializeFileInfo($this->node), + ]; + } } diff --git a/lib/public/Files/Events/Node/AbstractNodesEvent.php b/lib/public/Files/Events/Node/AbstractNodesEvent.php index e27569a6b89..8fa8795d1df 100644 --- a/lib/public/Files/Events/Node/AbstractNodesEvent.php +++ b/lib/public/Files/Events/Node/AbstractNodesEvent.php @@ -3,48 +3,27 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2020, Roeland Jago Douma <roeland@famdouma.nl> - * - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2020 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Events\Node; use OCP\EventDispatcher\Event; +use OCP\EventDispatcher\IWebhookCompatibleEvent; +use OCP\EventDispatcher\JsonSerializer; use OCP\Files\Node; /** * @since 20.0.0 */ -abstract class AbstractNodesEvent extends Event { - - /** @var Node */ - private $source; - /** @var Node */ - private $target; - +abstract class AbstractNodesEvent extends Event implements IWebhookCompatibleEvent { /** * @since 20.0.0 */ - public function __construct(Node $source, Node $target) { - $this->source = $source; - $this->target = $target; + public function __construct( + private Node $source, + private Node $target, + ) { } /** @@ -60,4 +39,14 @@ abstract class AbstractNodesEvent extends Event { public function getTarget(): Node { return $this->target; } + + /** + * @since 30.0.0 + */ + public function getWebhookSerializable(): array { + return [ + 'source' => JsonSerializer::serializeFileInfo($this->source), + 'target' => JsonSerializer::serializeFileInfo($this->target), + ]; + } } diff --git a/lib/public/Files/Events/Node/BeforeNodeCopiedEvent.php b/lib/public/Files/Events/Node/BeforeNodeCopiedEvent.php index 23d23d0068d..c7c014cfd64 100644 --- a/lib/public/Files/Events/Node/BeforeNodeCopiedEvent.php +++ b/lib/public/Files/Events/Node/BeforeNodeCopiedEvent.php @@ -3,27 +3,9 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2020, Roeland Jago Douma <roeland@famdouma.nl> - * - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2020 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Events\Node; /** diff --git a/lib/public/Files/Events/Node/BeforeNodeCreatedEvent.php b/lib/public/Files/Events/Node/BeforeNodeCreatedEvent.php index 30898fd9444..3f42687576d 100644 --- a/lib/public/Files/Events/Node/BeforeNodeCreatedEvent.php +++ b/lib/public/Files/Events/Node/BeforeNodeCreatedEvent.php @@ -3,27 +3,9 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2020, Roeland Jago Douma <roeland@famdouma.nl> - * - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2020 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Events\Node; /** diff --git a/lib/public/Files/Events/Node/BeforeNodeDeletedEvent.php b/lib/public/Files/Events/Node/BeforeNodeDeletedEvent.php index 1d887278bea..83d9402dbeb 100644 --- a/lib/public/Files/Events/Node/BeforeNodeDeletedEvent.php +++ b/lib/public/Files/Events/Node/BeforeNodeDeletedEvent.php @@ -3,31 +3,22 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2020, Roeland Jago Douma <roeland@famdouma.nl> - * - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2020 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Events\Node; +use OCP\Exceptions\AbortedEventException; + /** * @since 20.0.0 */ class BeforeNodeDeletedEvent extends AbstractNodeEvent { + /** + * @since 28.0.0 + * @deprecated 29.0.0 - use OCP\Exceptions\AbortedEventException instead + */ + public function abortOperation(?\Throwable $ex = null) { + throw new AbortedEventException($ex?->getMessage() ?? 'Operation aborted'); + } } diff --git a/lib/public/Files/Events/Node/BeforeNodeReadEvent.php b/lib/public/Files/Events/Node/BeforeNodeReadEvent.php index 98724ba65fd..ae688fccb30 100644 --- a/lib/public/Files/Events/Node/BeforeNodeReadEvent.php +++ b/lib/public/Files/Events/Node/BeforeNodeReadEvent.php @@ -3,27 +3,9 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2020, Roeland Jago Douma <roeland@famdouma.nl> - * - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2020 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Events\Node; /** diff --git a/lib/public/Files/Events/Node/BeforeNodeRenamedEvent.php b/lib/public/Files/Events/Node/BeforeNodeRenamedEvent.php index f65e47415d4..54714b8f7e2 100644 --- a/lib/public/Files/Events/Node/BeforeNodeRenamedEvent.php +++ b/lib/public/Files/Events/Node/BeforeNodeRenamedEvent.php @@ -3,31 +3,22 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2020, Roeland Jago Douma <roeland@famdouma.nl> - * - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2020 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Events\Node; +use OCP\Exceptions\AbortedEventException; + /** * @since 20.0.0 */ class BeforeNodeRenamedEvent extends AbstractNodesEvent { + /** + * @since 28.0.0 + * @deprecated 29.0.0 - use OCP\Exceptions\AbortedEventException instead + */ + public function abortOperation(?\Throwable $ex = null) { + throw new AbortedEventException($ex?->getMessage() ?? 'Operation aborted'); + } } diff --git a/lib/public/Files/Events/Node/BeforeNodeTouchedEvent.php b/lib/public/Files/Events/Node/BeforeNodeTouchedEvent.php index 20d69be9b31..ed2e561e947 100644 --- a/lib/public/Files/Events/Node/BeforeNodeTouchedEvent.php +++ b/lib/public/Files/Events/Node/BeforeNodeTouchedEvent.php @@ -3,27 +3,9 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2020, Roeland Jago Douma <roeland@famdouma.nl> - * - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2020 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Events\Node; /** diff --git a/lib/public/Files/Events/Node/BeforeNodeWrittenEvent.php b/lib/public/Files/Events/Node/BeforeNodeWrittenEvent.php index d13416498db..61d3afb9cd6 100644 --- a/lib/public/Files/Events/Node/BeforeNodeWrittenEvent.php +++ b/lib/public/Files/Events/Node/BeforeNodeWrittenEvent.php @@ -3,27 +3,9 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2020, Roeland Jago Douma <roeland@famdouma.nl> - * - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2020 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Events\Node; /** diff --git a/lib/public/Files/Events/Node/FilesystemTornDownEvent.php b/lib/public/Files/Events/Node/FilesystemTornDownEvent.php new file mode 100644 index 00000000000..2076b739b51 --- /dev/null +++ b/lib/public/Files/Events/Node/FilesystemTornDownEvent.php @@ -0,0 +1,19 @@ +<?php + +declare(strict_types=1); +/** + * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +namespace OCP\Files\Events\Node; + +use OCP\EventDispatcher\Event; + +/** + * Event fired after the filesystem has been torn down + * + * @since 24.0.0 + */ +class FilesystemTornDownEvent extends Event { +} diff --git a/lib/public/Files/Events/Node/NodeCopiedEvent.php b/lib/public/Files/Events/Node/NodeCopiedEvent.php index 9ce96842a80..8913f34835e 100644 --- a/lib/public/Files/Events/Node/NodeCopiedEvent.php +++ b/lib/public/Files/Events/Node/NodeCopiedEvent.php @@ -3,27 +3,9 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2020, Roeland Jago Douma <roeland@famdouma.nl> - * - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2020 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Events\Node; /** diff --git a/lib/public/Files/Events/Node/NodeCreatedEvent.php b/lib/public/Files/Events/Node/NodeCreatedEvent.php index 3a6a2d56d65..ffcbc9a9f10 100644 --- a/lib/public/Files/Events/Node/NodeCreatedEvent.php +++ b/lib/public/Files/Events/Node/NodeCreatedEvent.php @@ -3,27 +3,9 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2020, Roeland Jago Douma <roeland@famdouma.nl> - * - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2020 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Events\Node; /** diff --git a/lib/public/Files/Events/Node/NodeDeletedEvent.php b/lib/public/Files/Events/Node/NodeDeletedEvent.php index fef6c28651e..58689e2c3d9 100644 --- a/lib/public/Files/Events/Node/NodeDeletedEvent.php +++ b/lib/public/Files/Events/Node/NodeDeletedEvent.php @@ -3,27 +3,9 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2020, Roeland Jago Douma <roeland@famdouma.nl> - * - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2020 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Events\Node; /** diff --git a/lib/public/Files/Events/Node/NodeRenamedEvent.php b/lib/public/Files/Events/Node/NodeRenamedEvent.php index eb7072f7048..f126d191d7f 100644 --- a/lib/public/Files/Events/Node/NodeRenamedEvent.php +++ b/lib/public/Files/Events/Node/NodeRenamedEvent.php @@ -3,27 +3,9 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2020, Roeland Jago Douma <roeland@famdouma.nl> - * - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2020 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Events\Node; /** diff --git a/lib/public/Files/Events/Node/NodeTouchedEvent.php b/lib/public/Files/Events/Node/NodeTouchedEvent.php index d82b14396c2..88037311b4a 100644 --- a/lib/public/Files/Events/Node/NodeTouchedEvent.php +++ b/lib/public/Files/Events/Node/NodeTouchedEvent.php @@ -3,27 +3,9 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2020, Roeland Jago Douma <roeland@famdouma.nl> - * - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2020 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Events\Node; /** diff --git a/lib/public/Files/Events/Node/NodeWrittenEvent.php b/lib/public/Files/Events/Node/NodeWrittenEvent.php index 29806c21f4b..b6bb949167c 100644 --- a/lib/public/Files/Events/Node/NodeWrittenEvent.php +++ b/lib/public/Files/Events/Node/NodeWrittenEvent.php @@ -3,27 +3,9 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2020, Roeland Jago Douma <roeland@famdouma.nl> - * - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2020 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Events\Node; /** diff --git a/lib/public/Files/Events/NodeAddedToCache.php b/lib/public/Files/Events/NodeAddedToCache.php index f1ffd755f68..4ea20a3f3c1 100644 --- a/lib/public/Files/Events/NodeAddedToCache.php +++ b/lib/public/Files/Events/NodeAddedToCache.php @@ -3,27 +3,9 @@ declare(strict_types=1); /** - * @copyright 2019 Christoph Wurst <christoph@winzerhof-wurst.at> - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Events; use OCP\EventDispatcher\Event; @@ -33,7 +15,6 @@ use OCP\Files\Storage\IStorage; * @since 18.0.0 */ class NodeAddedToCache extends Event { - /** @var IStorage */ private $storage; @@ -46,7 +27,7 @@ class NodeAddedToCache extends Event { * @since 18.0.0 */ public function __construct(IStorage $storage, - string $path) { + string $path) { parent::__construct(); $this->storage = $storage; $this->path = $path; diff --git a/lib/public/Files/Events/NodeAddedToFavorite.php b/lib/public/Files/Events/NodeAddedToFavorite.php new file mode 100644 index 00000000000..2a2725063b6 --- /dev/null +++ b/lib/public/Files/Events/NodeAddedToFavorite.php @@ -0,0 +1,49 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2023 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Files\Events; + +use OCP\EventDispatcher\Event; +use OCP\IUser; + +/** + * @since 28.0.0 + */ +class NodeAddedToFavorite extends Event { + /** + * @since 28.0.0 + */ + public function __construct( + protected IUser $user, + protected int $fileId, + protected string $path, + ) { + parent::__construct(); + } + + /** + * @since 28.0.0 + */ + public function getUser(): IUser { + return $this->user; + } + + /** + * @since 28.0.0 + */ + public function getFileId(): int { + return $this->fileId; + } + + /** + * @since 28.0.0 + */ + public function getPath(): string { + return $this->path; + } +} diff --git a/lib/public/Files/Events/NodeRemovedFromCache.php b/lib/public/Files/Events/NodeRemovedFromCache.php index 0437bc001a7..01c8c21f71d 100644 --- a/lib/public/Files/Events/NodeRemovedFromCache.php +++ b/lib/public/Files/Events/NodeRemovedFromCache.php @@ -3,27 +3,9 @@ declare(strict_types=1); /** - * @copyright 2019 Christoph Wurst <christoph@winzerhof-wurst.at> - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Events; use OCP\EventDispatcher\Event; @@ -33,7 +15,6 @@ use OCP\Files\Storage\IStorage; * @since 18.0.0 */ class NodeRemovedFromCache extends Event { - /** @var IStorage */ private $storage; @@ -46,7 +27,7 @@ class NodeRemovedFromCache extends Event { * @since 18.0.0 */ public function __construct(IStorage $storage, - string $path) { + string $path) { parent::__construct(); $this->storage = $storage; $this->path = $path; diff --git a/lib/public/Files/Events/NodeRemovedFromFavorite.php b/lib/public/Files/Events/NodeRemovedFromFavorite.php new file mode 100644 index 00000000000..3b2f75346c4 --- /dev/null +++ b/lib/public/Files/Events/NodeRemovedFromFavorite.php @@ -0,0 +1,49 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2023 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Files\Events; + +use OCP\EventDispatcher\Event; +use OCP\IUser; + +/** + * @since 28.0.0 + */ +class NodeRemovedFromFavorite extends Event { + /** + * @since 28.0.0 + */ + public function __construct( + protected IUser $user, + protected int $fileId, + protected string $path, + ) { + parent::__construct(); + } + + /** + * @since 28.0.0 + */ + public function getUser(): IUser { + return $this->user; + } + + /** + * @since 28.0.0 + */ + public function getFileId(): int { + return $this->fileId; + } + + /** + * @since 28.0.0 + */ + public function getPath(): string { + return $this->path; + } +} diff --git a/lib/public/Files/File.php b/lib/public/Files/File.php index 79955bbb849..d0aceeaba37 100644 --- a/lib/public/Files/File.php +++ b/lib/public/Files/File.php @@ -1,35 +1,12 @@ <?php -/** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Julius Härtl <jus@bitgrid.net> - * @author Morris Jobke <hey@morrisjobke.de> - * @author Robin Appelman <robin@icewind.nl> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * - */ /** - * Public interface of ownCloud for apps to use. - * Files/File interface + * 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 ownCloud classes +// This means that they should be used by apps instead of the internal Nextcloud classes namespace OCP\Files; @@ -46,6 +23,7 @@ interface File extends Node { * * @return string * @throws NotPermittedException + * @throws GenericFileException * @throws LockedException * @since 6.0.0 */ @@ -74,7 +52,7 @@ interface File extends Node { * Open the file as stream, resulting resource can be operated as stream like the result from php's own fopen * * @param string $mode - * @return resource + * @return resource|false * @throws NotPermittedException * @throws LockedException * @since 6.0.0 diff --git a/lib/public/Files/FileInfo.php b/lib/public/Files/FileInfo.php index bad67269a50..f9957f580e8 100644 --- a/lib/public/Files/FileInfo.php +++ b/lib/public/Files/FileInfo.php @@ -1,34 +1,14 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Felix Heidecke <felix@heidecke.me> - * @author Joas Schilling <coding@schilljs.com> - * @author Julius Härtl <jus@bitgrid.net> - * @author Morris Jobke <hey@morrisjobke.de> - * @author Robin Appelman <robin@icewind.nl> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * @author Thomas Müller <thomas.mueller@tmit.eu> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ - namespace OCP\Files; +use OCP\Files\Storage\IStorage; + /** * Interface FileInfo * @@ -83,7 +63,7 @@ interface FileInfo { * Get the size in bytes for the file or folder * * @param bool $includeMounts whether or not to include the size of any sub mounts, since 16.0.0 - * @return int + * @return int|float * @since 7.0.0 */ public function getSize($includeMounts = true); @@ -139,7 +119,7 @@ interface FileInfo { /** * Get the storage the file or folder is storage on * - * @return \OCP\Files\Storage + * @return IStorage * @since 7.0.0 */ public function getStorage(); @@ -153,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 @@ -249,13 +231,16 @@ interface FileInfo { /** * Get the owner of the file * - * @return \OCP\IUser + * @return ?\OCP\IUser * @since 9.0.0 */ public function getOwner(); /** - * Get the stored checksum for this file + * Get the stored checksum(s) for this file + * + * Checksums are stored in the format TYPE:CHECKSUM, here may be multiple checksums separated by a single space + * e.g. MD5:d3b07384d113edec49eaa6238ad5ff00 SHA1:f1d2d2f924e986ac86fdf7b36c94bcdf32beec15 * * @return string * @since 9.0.0 @@ -295,4 +280,21 @@ interface FileInfo { * @since 18.0.0 */ public function getUploadTime(): int; + + /** + * Get the fileid or the parent folder + * or -1 if this item has no parent folder (because it is the root) + * + * @return int + * @since 28.0.0 + */ + public function getParentId(): int; + + /** + * Get the metadata, if available + * + * @return array<string, int|string|bool|float|string[]|int[]> + * @since 28.0.0 + */ + public function getMetadata(): array; } diff --git a/lib/public/Files/FileNameTooLongException.php b/lib/public/Files/FileNameTooLongException.php index d1c6c6f9e04..ae1022cca50 100644 --- a/lib/public/Files/FileNameTooLongException.php +++ b/lib/public/Files/FileNameTooLongException.php @@ -1,34 +1,12 @@ <?php -/** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Morris Jobke <hey@morrisjobke.de> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * @author Thomas Müller <thomas.mueller@tmit.eu> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * - */ /** - * Public interface of ownCloud for apps to use. - * Files/ReservedWordException class + * 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 ownCloud classes +// This means that they should be used by apps instead of the internal Nextcloud classes namespace OCP\Files; diff --git a/lib/public/Files/Folder.php b/lib/public/Files/Folder.php index 3e90abdd944..a35d2d78bc9 100644 --- a/lib/public/Files/Folder.php +++ b/lib/public/Files/Folder.php @@ -1,36 +1,12 @@ <?php -/** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Morris Jobke <hey@morrisjobke.de> - * @author Robin Appelman <robin@icewind.nl> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * @author Vincent Petry <vincent@nextcloud.com> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * - */ /** - * Public interface of ownCloud for apps to use. - * Files/Folder interface + * 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 ownCloud classes +// This means that they should be used by apps instead of the internal Nextcloud classes namespace OCP\Files; @@ -55,7 +31,7 @@ interface Folder extends Node { * * @param string $path absolute path of an item in the folder * @throws \OCP\Files\NotFoundException - * @return string + * @return string|null * @since 6.0.0 */ public function getRelativePath($path); @@ -84,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); @@ -148,11 +125,23 @@ interface Folder extends Node { public function searchByTag($tag, $userId); /** - * get a file or folder inside the folder by it's internal id + * search for files by system tag + * + * @param string|int $tag tag name + * @param string $userId user id to ensure access on returned nodes + * @return \OCP\Files\Node[] + * @since 28.0.0 + */ + public function searchBySystemTag(string $tagName, string $userId, int $limit = 0, int $offset = 0); + + /** + * get a file or folder inside the folder by its internal id * * This method could return multiple entries. For example once the file/folder * is shared or mounted (files_external) to the user multiple times. * + * Note that the different entries can have different permissions. + * * @param int $id * @return \OCP\Files\Node[] * @since 6.0.0 @@ -160,6 +149,24 @@ interface Folder extends Node { public function getById($id); /** + * get a file or folder inside the folder by its internal id + * + * Unlike getById, this method only returns a single node even if the user has + * access to the file with the requested id multiple times. + * + * This method provides no guarantee about which of the nodes in returned and the + * returned node might, for example, have less permissions than other nodes for the same file + * + * Apps that require accurate information about the users access to the file should use getById + * instead of pick the correct node out of the result. + * + * @param int $id + * @return Node|null + * @since 29.0.0 + */ + public function getFirstNodeById(int $id): ?Node; + + /** * Get the amount of free space inside the folder * * @return int @@ -192,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 d0f0d10eae1..514ef8623d3 100644 --- a/lib/public/Files/ForbiddenException.php +++ b/lib/public/Files/ForbiddenException.php @@ -1,29 +1,12 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Joas Schilling <coding@schilljs.com> - * @author Lukas Reschke <lukas@statuscode.ch> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * 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 ownCloud classes +// This means that they should be used by apps instead of the internal Nextcloud classes namespace OCP\Files; @@ -33,7 +16,6 @@ namespace OCP\Files; * @since 9.0.0 */ class ForbiddenException extends \Exception { - /** @var bool */ private $retry; @@ -43,7 +25,7 @@ class ForbiddenException extends \Exception { * @param \Exception|null $previous previous exception for cascading * @since 9.0.0 */ - public function __construct($message, $retry, \Exception $previous = null) { + public function __construct($message, $retry, ?\Exception $previous = null) { parent::__construct($message, 0, $previous); $this->retry = $retry; } @@ -53,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 780db6fc112..66a3b5e5ac4 100644 --- a/lib/public/Files/GenericFileException.php +++ b/lib/public/Files/GenericFileException.php @@ -1,26 +1,9 @@ <?php + /** - * @copyright 2018, Roeland Jago Douma <roeland@famdouma.nl> - * - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files; /** diff --git a/lib/public/Files/IAppData.php b/lib/public/Files/IAppData.php index 8cc54a02fd9..4d0c4da6a8a 100644 --- a/lib/public/Files/IAppData.php +++ b/lib/public/Files/IAppData.php @@ -1,27 +1,9 @@ <?php + /** - * @copyright 2016 Roeland Jago Douma <roeland@famdouma.nl> - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2016 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files; use OCP\Files\SimpleFS\ISimpleRoot; 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/IHomeStorage.php b/lib/public/Files/IHomeStorage.php index 074e7a09301..6f2ca82ef72 100644 --- a/lib/public/Files/IHomeStorage.php +++ b/lib/public/Files/IHomeStorage.php @@ -1,41 +1,29 @@ <?php -/** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Joas Schilling <coding@schilljs.com> - * @author Morris Jobke <hey@morrisjobke.de> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * - */ /** - * Public interface of ownCloud for apps to use. - * Files/Storage interface + * 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 ownCloud classes +// 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\IUser; + /** * Interface IHomeStorage * * @since 7.0.0 */ -interface IHomeStorage { +interface IHomeStorage extends IStorage { + /** + * Get the user for this home storage + * + * @return IUser + * @since 28.0.0 + */ + public function getUser(): IUser; } diff --git a/lib/public/Files/IMimeTypeDetector.php b/lib/public/Files/IMimeTypeDetector.php index a73b60e19b8..1e87cf932ce 100644 --- a/lib/public/Files/IMimeTypeDetector.php +++ b/lib/public/Files/IMimeTypeDetector.php @@ -1,28 +1,12 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Joas Schilling <coding@schilljs.com> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * 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 ownCloud classes +// This means that they should be used by apps instead of the internal Nextcloud classes namespace OCP\Files; @@ -30,12 +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 @@ -43,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 @@ -51,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 @@ -60,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 @@ -69,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 @@ -84,4 +67,32 @@ interface IMimeTypeDetector { * @since 8.2.0 */ public function mimeTypeIcon($mimeType); + + /** + * @return array<string,string> + * @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 5b54b8c7619..77c59fb2c0a 100644 --- a/lib/public/Files/IMimeTypeLoader.php +++ b/lib/public/Files/IMimeTypeLoader.php @@ -1,25 +1,10 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Robin McCorkell <robin@mccorkell.me.uk> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ - namespace OCP\Files; /** @@ -29,7 +14,6 @@ namespace OCP\Files; * Interface to load mimetypes **/ interface IMimeTypeLoader { - /** * Get a mimetype from its ID * @@ -37,7 +21,7 @@ interface IMimeTypeLoader { * @return string|null * @since 8.2.0 */ - public function getMimetypeById($id); + public function getMimetypeById(int $id): ?string; /** * Get a mimetype ID, adding the mimetype to the DB if it does not exist @@ -46,7 +30,7 @@ interface IMimeTypeLoader { * @return int * @since 8.2.0 */ - public function getId($mimetype); + public function getId(string $mimetype): int; /** * Test if a mimetype exists in the database @@ -55,12 +39,22 @@ interface IMimeTypeLoader { * @return bool * @since 8.2.0 */ - public function exists($mimetype); + public function exists(string $mimetype): bool; /** * Clear all loaded mimetypes, allow for re-loading * * @since 8.2.0 */ - public function reset(); + 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/IRootFolder.php b/lib/public/Files/IRootFolder.php index eb3c19ce664..fb8532f8c81 100644 --- a/lib/public/Files/IRootFolder.php +++ b/lib/public/Files/IRootFolder.php @@ -1,32 +1,17 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Bernhard Posselt <dev@bernhard-posselt.com> - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Julius Härtl <jus@bitgrid.net> - * @author Morris Jobke <hey@morrisjobke.de> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ - namespace OCP\Files; use OC\Hooks\Emitter; use OC\User\NoUserException; +use OCP\Files\Cache\ICacheEntry; +use OCP\Files\Mount\IMountPoint; +use OCP\Files\Node as INode; /** * Interface IRootFolder @@ -34,16 +19,72 @@ use OC\User\NoUserException; * @since 8.0.0 */ interface IRootFolder extends Folder, Emitter { - /** * Returns a view to user's files folder * * @param string $userId user ID - * @return \OCP\Files\Folder + * @return Folder * @throws NoUserException * @throws NotPermittedException * * @since 8.2.0 */ public function getUserFolder($userId); + + /** + * Get a file or folder by fileid, inside a parent path + * + * @param int $id + * @param string $path + * @return Node[] + * + * @since 24.0.0 + */ + public function getByIdInPath(int $id, string $path); + + /** + * get a file or folder inside the folder by its internal id + * + * Unlike getByIdInPath, this method only returns a single node even if the user has + * access to the file with the requested id multiple times. + * + * This method provides no guarantee about which of the nodes in returned and the + * returned node might, for example, have less permissions than other nodes for the same file + * + * Apps that require accurate information about the users access to the file should use getByIdInPath + * instead of pick the correct node out of the result. + * + * @param int $id + * @return Node|null + * @since 29.0.0 + */ + public function getFirstNodeByIdInPath(int $id, string $path): ?Node; + + /** + * @return IMountPoint[] + * + * @since 28.0.0 + */ + public function getMountsIn(string $mountPoint): array; + + /** + * Create a `Node` for a file or folder from the cache entry and mountpoint + * + * @param ICacheEntry $cacheEntry + * @param IMountPoint $mountPoint + * @return Node + * @since 28.0.0 + */ + public function getNodeFromCacheEntryAndMount(ICacheEntry $cacheEntry, IMountPoint $mountPoint): INode; + + /** + * @since 28.0.0 + */ + public function getMount(string $mountPoint): IMountPoint; + + /** + * @return string + * @since 30.0.0 + */ + public function getAppDataDirectoryName(): string; } diff --git a/lib/public/Files/InvalidCharacterInPathException.php b/lib/public/Files/InvalidCharacterInPathException.php index 57fb2134bb0..f34a5778bcf 100644 --- a/lib/public/Files/InvalidCharacterInPathException.php +++ b/lib/public/Files/InvalidCharacterInPathException.php @@ -1,34 +1,12 @@ <?php -/** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Morris Jobke <hey@morrisjobke.de> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * @author Thomas Müller <thomas.mueller@tmit.eu> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * - */ /** - * Public interface of ownCloud for apps to use. - * Files/InvalidCharacterInPathException class + * 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 ownCloud classes +// This means that they should be used by apps instead of the internal Nextcloud classes namespace OCP\Files; diff --git a/lib/public/Files/InvalidContentException.php b/lib/public/Files/InvalidContentException.php index 98e79c61fc2..bf5d1306751 100644 --- a/lib/public/Files/InvalidContentException.php +++ b/lib/public/Files/InvalidContentException.php @@ -1,35 +1,12 @@ <?php -/** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Morris Jobke <hey@morrisjobke.de> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * @author Thomas Müller <thomas.mueller@tmit.eu> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * - */ /** - * Public interface of ownCloud for apps to use. - * Files/InvalidContentException class + * 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 ownCloud classes +// This means that they should be used by apps instead of the internal Nextcloud classes namespace OCP\Files; diff --git a/lib/public/Files/InvalidDirectoryException.php b/lib/public/Files/InvalidDirectoryException.php index dfb428710ea..b9640209cbf 100644 --- a/lib/public/Files/InvalidDirectoryException.php +++ b/lib/public/Files/InvalidDirectoryException.php @@ -1,26 +1,9 @@ <?php + /** - * @copyright Copyright (c) 2016 Joas Schilling <coding@schilljs.com> - * - * @author Joas Schilling <coding@schilljs.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/>. - * + * SPDX-FileCopyrightText: 2016 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files; /** diff --git a/lib/public/Files/InvalidPathException.php b/lib/public/Files/InvalidPathException.php index 8eaeb2f3bc7..1c944f26844 100644 --- a/lib/public/Files/InvalidPathException.php +++ b/lib/public/Files/InvalidPathException.php @@ -1,35 +1,12 @@ <?php -/** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Morris Jobke <hey@morrisjobke.de> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * @author Thomas Müller <thomas.mueller@tmit.eu> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * - */ /** - * Public interface of ownCloud for apps to use. - * Files/InvalidPathException class + * 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 ownCloud classes +// This means that they should be used by apps instead of the internal Nextcloud classes namespace OCP\Files; diff --git a/lib/public/Files/Lock/ILock.php b/lib/public/Files/Lock/ILock.php new file mode 100644 index 00000000000..4adb45b7b18 --- /dev/null +++ b/lib/public/Files/Lock/ILock.php @@ -0,0 +1,145 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +namespace OCP\Files\Lock; + +/** + * @since 24.0.0 + */ +interface ILock { + /** + * User owned manual lock + * + * This lock type is initiated by a user manually through the web UI or clients + * and will limit editing capabilities on the file to the lock owning user. + * + * @since 24.0.0 + */ + public const TYPE_USER = 0; + + /** + * App owned lock + * + * This lock type is created by collaborative apps like Text or Office to avoid + * outside changes through WevDAV or other apps. + * @since 24.0.0 + * + */ + public const TYPE_APP = 1; + + /** + * Token owned lock + * + * This lock type will bind the ownership to the provided lock token. Any request + * that aims to modify the file will be required to sent the token, the user + * itself is not able to write to files without the token. This will allow + * to limit the locking to an individual client. + * + * @since 24.0.0 + */ + public const TYPE_TOKEN = 2; + + /** + * WebDAV Lock scope exclusive + * + * @since 24.0.0 + */ + public const LOCK_EXCLUSIVE = 1; + + /** + * WebDAV Lock scope shared + * + * @since 24.0.0 + */ + public const LOCK_SHARED = 2; + + /** + * Lock only the resource the lock is applied to + * + * @since 24.0.0 + */ + public const LOCK_DEPTH_ZERO = 0; + + /** + * Lock app resources under the locked one with infinite depth + * + * @since 24.0.0 + */ + public const LOCK_DEPTH_INFINITE = -1; + + /** + * Type of the lock + * + * @psalm-return ILock::TYPE_* + * @since 24.0.0 + */ + public function getType(): int; + + /** + * Owner that holds the lock + * + * Depending on the lock type this is: + * - ILock::TYPE_USER: A user id + * - ILock::TYPE_APP: An app id + * - ILock::TYPE_TOKEN: A user id + * + * @since 24.0.0 + */ + public function getOwner(): string; + + /** + * File id that the lock is holding + * + * @since 24.0.0 + */ + public function getFileId(): int; + + /** + * Timeout of the lock in seconds starting from the created at time + * + * @since 24.0.0 + */ + public function getTimeout(): int; + + /** + * Unix timestamp of the lock creation time + * + * @since 24.0.0 + */ + public function getCreatedAt(): int; + + /** + * Token string as a unique identifier for the lock, usually a UUID + * + * @since 24.0.0 + */ + public function getToken(): string; + + /** + * Lock depth to apply the lock to child resources + * + * @since 24.0.0 + */ + public function getDepth(): int; + + /** + * WebDAV lock scope + * + * @since 24.0.0 + * @psalm-return ILock::LOCK_EXCLUSIVE|ILock::LOCK_SHARED + */ + public function getScope(): int; + + /** + * String representation of the lock to identify it through logging + * + * @since 24.0.0 + */ + public function __toString(): string; +} diff --git a/lib/public/Files/Lock/ILockManager.php b/lib/public/Files/Lock/ILockManager.php new file mode 100644 index 00000000000..d19116a9b3d --- /dev/null +++ b/lib/public/Files/Lock/ILockManager.php @@ -0,0 +1,59 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +namespace OCP\Files\Lock; + +use OCP\PreConditionNotMetException; + +/** + * Manage app integrations with files_lock with collaborative editors + * + * The OCP parts are mainly for exposing the ability to lock/unlock for apps and + * to give the files_lock app a way to register and then be triggered by the apps + * while the actual locking implementation is kept in the LockProvider and DAV + * plugin from files_lock app. + * + * @since 24.0.0 + */ +interface ILockManager extends ILockProvider { + /** + * @throws PreConditionNotMetException if there is already a lock provider registered + * @since 24.0.0 + * @deprecated 30.0.0 Use registerLazyLockProvider + */ + public function registerLockProvider(ILockProvider $lockProvider): void; + + /** + * @param string $lockProviderClass + * @return void + * @since 30.0.0 + */ + public function registerLazyLockProvider(string $lockProviderClass): void; + + /** + * @return bool + * @since 24.0.0 + */ + public function isLockProviderAvailable(): bool; + + /** + * Run within the scope of a given lock condition + * + * The callback will also be executed if no lock provider is present + * + * @since 24.0.0 + */ + public function runInScope(LockContext $lock, callable $callback): void; + + /** + * @throws NoLockProviderException if there is no lock provider available + * @since 24.0.0 + */ + public function getLockInScope(): ?LockContext; +} diff --git a/lib/public/Files/Lock/ILockProvider.php b/lib/public/Files/Lock/ILockProvider.php new file mode 100644 index 00000000000..be0306e3188 --- /dev/null +++ b/lib/public/Files/Lock/ILockProvider.php @@ -0,0 +1,40 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +namespace OCP\Files\Lock; + +use OCP\PreConditionNotMetException; + +/** + * @since 24.0.0 + */ +interface ILockProvider { + /** + * @throws PreConditionNotMetException + * @throws NoLockProviderException + * @psalm-return list<ILock> + * @since 24.0.0 + */ + public function getLocks(int $fileId): array; + + /** + * @throws PreConditionNotMetException + * @throws OwnerLockedException + * @throws NoLockProviderException + * @since 24.0.0 + */ + public function lock(LockContext $lockInfo): ILock; + + /** + * @throws PreConditionNotMetException + * @throws NoLockProviderException + * @since 24.0.0 + */ + public function unlock(LockContext $lockInfo): void; +} diff --git a/lib/public/Files/Lock/LockContext.php b/lib/public/Files/Lock/LockContext.php new file mode 100644 index 00000000000..5e61d3e2ec5 --- /dev/null +++ b/lib/public/Files/Lock/LockContext.php @@ -0,0 +1,82 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +namespace OCP\Files\Lock; + +use OCP\Files\Node; + +/** + * Structure to identify a specific lock context to request or + * describe a lock with the affected node and ownership information + * + * This is used to match a lock/unlock request or file operation to existing locks + * + * @since 24.0.0 + */ +final class LockContext { + private Node $node; + private int $type; + private string $owner; + + /** + * @param Node $node Node that is owned by the lock + * @param int $type Type of the lock owner + * @param string $owner Unique identifier for the lock owner based on the type + * @since 24.0.0 + */ + public function __construct( + Node $node, + int $type, + string $owner, + ) { + $this->node = $node; + $this->type = $type; + $this->owner = $owner; + } + + /** + * @since 24.0.0 + */ + public function getNode(): Node { + return $this->node; + } + + /** + * @return int + * @since 24.0.0 + */ + public function getType(): int { + return $this->type; + } + + /** + * @return string user id / app id / lock token depending on the type + * @since 24.0.0 + */ + public function getOwner(): string { + return $this->owner; + } + + /** + * @since 24.0.0 + */ + public function __toString(): string { + $typeString = 'unknown'; + if ($this->type === ILock::TYPE_USER) { + $typeString = 'ILock::TYPE_USER'; + } + if ($this->type === ILock::TYPE_APP) { + $typeString = 'ILock::TYPE_APP'; + } + if ($this->type === ILock::TYPE_TOKEN) { + $typeString = 'ILock::TYPE_TOKEN'; + } + return "$typeString $this->owner " . $this->getNode()->getId(); + } +} diff --git a/lib/public/Files/Lock/NoLockProviderException.php b/lib/public/Files/Lock/NoLockProviderException.php new file mode 100644 index 00000000000..460cdc76e6e --- /dev/null +++ b/lib/public/Files/Lock/NoLockProviderException.php @@ -0,0 +1,18 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +namespace OCP\Files\Lock; + +use Exception; + +/** + * @since 24.0.0 + */ +class NoLockProviderException extends Exception { +} diff --git a/lib/public/Files/Lock/OwnerLockedException.php b/lib/public/Files/Lock/OwnerLockedException.php new file mode 100644 index 00000000000..ff51ebfc401 --- /dev/null +++ b/lib/public/Files/Lock/OwnerLockedException.php @@ -0,0 +1,36 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +namespace OCP\Files\Lock; + +use OCP\Lock\LockedException; + +/** + * @since 24.0.0 + */ +class OwnerLockedException extends LockedException { + private ILock $lock; + + /** + * @since 24.0.0 + */ + public function __construct(ILock $lock) { + $this->lock = $lock; + $path = ''; + $readablePath = ''; + parent::__construct($path, null, $lock->getOwner(), $readablePath); + } + + /** + * @since 24.0.0 + */ + public function getLock(): ILock { + return $this->lock; + } +} diff --git a/lib/public/Files/LockNotAcquiredException.php b/lib/public/Files/LockNotAcquiredException.php index 47539c4979f..93d861c248f 100644 --- a/lib/public/Files/LockNotAcquiredException.php +++ b/lib/public/Files/LockNotAcquiredException.php @@ -1,36 +1,12 @@ <?php -/** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Morris Jobke <hey@morrisjobke.de> - * @author Owen Winkler <a_github@midnightcircus.com> - * @author Robin Appelman <robin@icewind.nl> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * - */ /** - * Public interface of ownCloud for apps to use. - * Files/LockNotAcquiredException class + * 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 ownCloud classes +// This means that they should be used by apps instead of the internal Nextcloud classes namespace OCP\Files; @@ -48,18 +24,17 @@ class LockNotAcquiredException extends \Exception { /** * @since 7.0.0 */ - public function __construct($path, $lockType, $code = 0, \Exception $previous = null) { - $message = \OC::$server->getL10N('core')->t('Could not obtain lock type %d on "%s".', [$lockType, $path]); + public function __construct($path, $lockType, $code = 0, ?\Exception $previous = null) { + $message = \OCP\Util::getL10N('core')->t('Could not obtain lock type %d on "%s".', [$lockType, $path]); parent::__construct($message, $code, $previous); } /** * custom string representation of object * - * @return string * @since 7.0.0 */ - public function __toString() { - return __CLASS__ . ": [{$this->code}]: {$this->message}\n"; + public function __toString(): string { + return self::class . ": [{$this->code}]: {$this->message}\n"; } } diff --git a/lib/public/Files/Mount/IMountManager.php b/lib/public/Files/Mount/IMountManager.php index e01e3df88a4..43a771c07ce 100644 --- a/lib/public/Files/Mount/IMountManager.php +++ b/lib/public/Files/Mount/IMountManager.php @@ -1,32 +1,15 @@ <?php declare(strict_types=1); - /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Morris Jobke <hey@morrisjobke.de> - * @author Robin Appelman <robin@icewind.nl> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ - namespace OCP\Files\Mount; +use OCP\Files\Config\ICachedMountInfo; + /** * Interface IMountManager * @@ -34,11 +17,10 @@ namespace OCP\Files\Mount; * @since 8.2.0 */ interface IMountManager { - /** * Add a new mount * - * @param \OCP\Files\Mount\IMountPoint $mount + * @param IMountPoint $mount * @since 8.2.0 */ public function addMount(IMountPoint $mount); @@ -64,16 +46,16 @@ interface IMountManager { * Find the mount for $path * * @param string $path - * @return \OCP\Files\Mount\IMountPoint|null + * @return IMountPoint * @since 8.2.0 */ - public function find(string $path); + public function find(string $path): ?IMountPoint; /** * Find all mounts in $path * * @param string $path - * @return \OCP\Files\Mount\IMountPoint[] + * @return IMountPoint[] * @since 8.2.0 */ public function findIn(string $path): array; @@ -89,13 +71,13 @@ interface IMountManager { * Find mounts by storage id * * @param string $id - * @return \OCP\Files\Mount\IMountPoint[] + * @return IMountPoint[] * @since 8.2.0 */ public function findByStorageId(string $id): array; /** - * @return \OCP\Files\Mount\IMountPoint[] + * @return IMountPoint[] * @since 8.2.0 */ public function getAll(): array; @@ -104,8 +86,18 @@ interface IMountManager { * Find mounts by numeric storage id * * @param int $id - * @return \OCP\Files\Mount\IMountPoint[] + * @return IMountPoint[] * @since 8.2.0 */ public function findByNumericId(int $id): array; + + /** + * Return the mount matching a cached mount info (or mount file info) + * + * @param ICachedMountInfo $info + * + * @return IMountPoint|null + * @since 28.0.0 + */ + public function getMountFromMountInfo(ICachedMountInfo $info): ?IMountPoint; } diff --git a/lib/public/Files/Mount/IMountPoint.php b/lib/public/Files/Mount/IMountPoint.php index 7315fd97035..8989a885fda 100644 --- a/lib/public/Files/Mount/IMountPoint.php +++ b/lib/public/Files/Mount/IMountPoint.php @@ -1,26 +1,10 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Morris Jobke <hey@morrisjobke.de> - * @author Robin Appelman <robin@icewind.nl> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ - namespace OCP\Files\Mount; /** @@ -28,7 +12,6 @@ namespace OCP\Files\Mount; * @since 8.0.0 */ interface IMountPoint { - /** * get complete path to the mount point * @@ -48,7 +31,7 @@ interface IMountPoint { /** * Get the storage that is mounted * - * @return \OC\Files\Storage\Storage + * @return \OCP\Files\Storage\IStorage|null * @since 8.0.0 */ public function getStorage(); @@ -56,7 +39,7 @@ interface IMountPoint { /** * Get the id of the storages * - * @return string + * @return string|null * @since 8.0.0 */ public function getStorageId(); @@ -64,7 +47,7 @@ interface IMountPoint { /** * Get the id of the storages * - * @return int + * @return int|null * @since 9.1.0 */ public function getNumericStorageId(); @@ -121,11 +104,19 @@ interface IMountPoint { public function getMountId(); /** - * Get the type of mount point, used to distinguish things like shares and external storages + * Get the type of mount point, used to distinguish things like shares and external storage * in the web interface * * @return string * @since 12.0.0 */ public function getMountType(); + + /** + * Get the class of the mount provider that this mount originates from + * + * @return string + * @since 24.0.0 + */ + public function getMountProvider(): string; } diff --git a/lib/public/Files/Mount/IMovableMount.php b/lib/public/Files/Mount/IMovableMount.php new file mode 100644 index 00000000000..dc4df7618c0 --- /dev/null +++ b/lib/public/Files/Mount/IMovableMount.php @@ -0,0 +1,32 @@ +<?php + +declare(strict_types=1); +/** + * SPDX-FileCopyrightText: 2023 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Files\Mount; + +/** + * Denotes that the mount point can be (re)moved by the user + * + * @since 28.0.0 + */ +interface IMovableMount { + /** + * Move the mount point to $target + * + * @param string $target the target mount point + * @return bool + * @since 28.0.0 + */ + public function moveMount($target); + + /** + * Remove the mount points + * + * @return bool + * @since 28.0.0 + */ + public function removeMount(); +} 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/Mount/ISystemMountPoint.php b/lib/public/Files/Mount/ISystemMountPoint.php new file mode 100644 index 00000000000..ae1d51621ea --- /dev/null +++ b/lib/public/Files/Mount/ISystemMountPoint.php @@ -0,0 +1,18 @@ +<?php + +declare(strict_types=1); +/** + * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Files\Mount; + +/** + * Mark a mountpoint as containing system data, meaning that the data is not user specific + * + * Example use case is signaling to the encryption wrapper that system-wide keys should be used for a mountpoint + * + * @since 25.0.0 + */ +interface ISystemMountPoint extends IMountPoint { +} diff --git a/lib/public/Files/Node.php b/lib/public/Files/Node.php index 02becc0de34..edef0a6157f 100644 --- a/lib/public/Files/Node.php +++ b/lib/public/Files/Node.php @@ -1,41 +1,16 @@ <?php -/** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Bernhard Posselt <dev@bernhard-posselt.com> - * @author Joas Schilling <coding@schilljs.com> - * @author Jörn Friedrich Dreyer <jfd@butonic.de> - * @author Julius Härtl <jus@bitgrid.net> - * @author Morris Jobke <hey@morrisjobke.de> - * @author Robin Appelman <robin@icewind.nl> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * - */ /** - * Public interface of ownCloud for apps to use. - * Files/Node interface + * 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 ownCloud classes +// 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\LockedException; /** @@ -69,7 +44,7 @@ interface Node extends FileInfo { public function delete(); /** - * Cope the file or folder to a new location + * Copy the file or folder to a new location * * @param string $targetPath the absolute target path * @return Node @@ -93,7 +68,7 @@ interface Node extends FileInfo { /** * Get the storage backend the file or folder is stored on * - * @return Storage + * @return IStorage * @throws NotFoundException * @since 6.0.0 */ @@ -150,7 +125,7 @@ interface Node extends FileInfo { * Get the size of the file or folder in bytes * * @param bool $includeMounts - * @return int + * @return int|float * @throws InvalidPathException * @throws NotFoundException * @since 6.0.0 @@ -268,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/NotEnoughSpaceException.php b/lib/public/Files/NotEnoughSpaceException.php index 337b86712e7..f2a0b60a916 100644 --- a/lib/public/Files/NotEnoughSpaceException.php +++ b/lib/public/Files/NotEnoughSpaceException.php @@ -1,35 +1,12 @@ <?php -/** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Morris Jobke <hey@morrisjobke.de> - * @author Robin Appelman <robin@icewind.nl> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * - */ /** - * Public interface of ownCloud for apps to use. - * Files/NotEnoughSpaceException class + * 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 ownCloud classes +// This means that they should be used by apps instead of the internal Nextcloud classes namespace OCP\Files; diff --git a/lib/public/Files/NotFoundException.php b/lib/public/Files/NotFoundException.php index 853138b9d5e..28edb082e81 100644 --- a/lib/public/Files/NotFoundException.php +++ b/lib/public/Files/NotFoundException.php @@ -1,35 +1,12 @@ <?php -/** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Morris Jobke <hey@morrisjobke.de> - * @author Robin Appelman <robin@icewind.nl> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * - */ /** - * Public interface of ownCloud for apps to use. - * Files/NotFoundException class + * 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 ownCloud classes +// This means that they should be used by apps instead of the internal Nextcloud classes namespace OCP\Files; diff --git a/lib/public/Files/NotPermittedException.php b/lib/public/Files/NotPermittedException.php index 661f7c2ce44..3b5cf637cb8 100644 --- a/lib/public/Files/NotPermittedException.php +++ b/lib/public/Files/NotPermittedException.php @@ -1,35 +1,12 @@ <?php -/** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Morris Jobke <hey@morrisjobke.de> - * @author Robin Appelman <robin@icewind.nl> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * - */ /** - * Public interface of ownCloud for apps to use. - * Files/NotPermittedException class + * 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 ownCloud classes +// This means that they should be used by apps instead of the internal Nextcloud classes namespace OCP\Files; diff --git a/lib/public/Files/Notify/IChange.php b/lib/public/Files/Notify/IChange.php index dd9fbc64bee..c7c758eec11 100644 --- a/lib/public/Files/Notify/IChange.php +++ b/lib/public/Files/Notify/IChange.php @@ -1,27 +1,9 @@ <?php + /** - * @copyright Copyright (c) 2017 Robin Appelman <robin@icewind.nl> - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Robin Appelman <robin@icewind.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2017 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Notify; /** @@ -30,9 +12,24 @@ namespace OCP\Files\Notify; * @since 12.0.0 */ interface IChange { + /** + * @since 12.0.0 + */ public const ADDED = 1; + + /** + * @since 12.0.0 + */ public const REMOVED = 2; + + /** + * @since 12.0.0 + */ public const MODIFIED = 3; + + /** + * @since 12.0.0 + */ public const RENAMED = 4; /** diff --git a/lib/public/Files/Notify/INotifyHandler.php b/lib/public/Files/Notify/INotifyHandler.php index 80cd3e08165..09b3dbca919 100644 --- a/lib/public/Files/Notify/INotifyHandler.php +++ b/lib/public/Files/Notify/INotifyHandler.php @@ -1,26 +1,9 @@ <?php + /** - * @copyright Copyright (c) 2017 Robin Appelman <robin@icewind.nl> - * - * @author Robin Appelman <robin@icewind.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2017 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Notify; /** diff --git a/lib/public/Files/Notify/IRenameChange.php b/lib/public/Files/Notify/IRenameChange.php index 7630d40aed8..b1bfae5fc00 100644 --- a/lib/public/Files/Notify/IRenameChange.php +++ b/lib/public/Files/Notify/IRenameChange.php @@ -1,26 +1,9 @@ <?php + /** - * @copyright Copyright (c) 2017 Robin Appelman <robin@icewind.nl> - * - * @author Robin Appelman <robin@icewind.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2017 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Notify; /** diff --git a/lib/public/Files/ObjectStore/IObjectStore.php b/lib/public/Files/ObjectStore/IObjectStore.php index e9d948682f8..35099ef8ba8 100644 --- a/lib/public/Files/ObjectStore/IObjectStore.php +++ b/lib/public/Files/ObjectStore/IObjectStore.php @@ -1,28 +1,10 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Jörn Friedrich Dreyer <jfd@butonic.de> - * @author Morris Jobke <hey@morrisjobke.de> - * @author Robin Appelman <robin@icewind.nl> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ - namespace OCP\Files\ObjectStore; use OCP\Files\NotFoundException; @@ -33,7 +15,6 @@ use OCP\Files\NotFoundException; * @since 7.0.0 */ interface IObjectStore { - /** * @return string the container or bucket name where objects are stored * @since 7.0.0 @@ -52,10 +33,11 @@ interface IObjectStore { /** * @param string $urn the unified resource name used to identify the object * @param resource $stream stream with the data to write + * @param string|null $mimetype the mimetype to set for the remove object @since 22.0.0 * @throws \Exception when something goes wrong, message will be logged * @since 7.0.0 */ - public function writeObject($urn, $stream); + public function writeObject($urn, $stream, ?string $mimetype = null); /** * @param string $urn the unified resource name used to identify the object 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/ObjectStore/IObjectStoreMultiPartUpload.php b/lib/public/Files/ObjectStore/IObjectStoreMultiPartUpload.php new file mode 100644 index 00000000000..7989e27dfc8 --- /dev/null +++ b/lib/public/Files/ObjectStore/IObjectStoreMultiPartUpload.php @@ -0,0 +1,40 @@ +<?php + +declare(strict_types=1); +/** + * SPDX-FileCopyrightText: 2021 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Files\ObjectStore; + +use Aws\Result; + +/** + * @since 26.0.0 + */ +interface IObjectStoreMultiPartUpload { + /** + * @since 26.0.0 + */ + public function initiateMultipartUpload(string $urn): string; + + /** + * @since 26.0.0 + */ + public function uploadMultipartPart(string $urn, string $uploadId, int $partId, $stream, $size): Result; + + /** + * @since 26.0.0 + */ + public function completeMultipartUpload(string $urn, string $uploadId, array $result): int; + + /** + * @since 26.0.0 + */ + public function abortMultipartUpload(string $urn, string $uploadId): void; + + /** + * @since 26.0.0 + */ + public function getMultipartUploads(string $urn, string $uploadId): array; +} diff --git a/lib/public/Files/ReservedWordException.php b/lib/public/Files/ReservedWordException.php index 81f25fb4366..68af12fd440 100644 --- a/lib/public/Files/ReservedWordException.php +++ b/lib/public/Files/ReservedWordException.php @@ -1,34 +1,12 @@ <?php -/** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Morris Jobke <hey@morrisjobke.de> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * @author Thomas Müller <thomas.mueller@tmit.eu> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * - */ /** - * Public interface of ownCloud for apps to use. - * Files/ReservedWordException class + * 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 ownCloud classes +// This means that they should be used by apps instead of the internal Nextcloud classes namespace OCP\Files; diff --git a/lib/public/Files/Search/ISearchBinaryOperator.php b/lib/public/Files/Search/ISearchBinaryOperator.php index d02ec9f36bd..fa7ef4d1bb3 100644 --- a/lib/public/Files/Search/ISearchBinaryOperator.php +++ b/lib/public/Files/Search/ISearchBinaryOperator.php @@ -1,35 +1,28 @@ <?php + /** - * @copyright Copyright (c) 2017 Robin Appelman <robin@icewind.nl> - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Robin Appelman <robin@icewind.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2017 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Search; /** * @since 12.0.0 */ interface ISearchBinaryOperator extends ISearchOperator { + /** + * @since 12.0.0 + */ public const OPERATOR_AND = 'and'; + + /** + * @since 12.0.0 + */ public const OPERATOR_OR = 'or'; + + /** + * @since 12.0.0 + */ public const OPERATOR_NOT = 'not'; /** diff --git a/lib/public/Files/Search/ISearchComparison.php b/lib/public/Files/Search/ISearchComparison.php index 6fb09433c92..ab298fa0a57 100644 --- a/lib/public/Files/Search/ISearchComparison.php +++ b/lib/public/Files/Search/ISearchComparison.php @@ -1,47 +1,75 @@ <?php + /** - * @copyright Copyright (c) 2017 Robin Appelman <robin@icewind.nl> - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Robin Appelman <robin@icewind.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2017 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Search; /** * @since 12.0.0 + * + * @psalm-type ParamSingleValue = \DateTime|int|string|bool + * @psalm-type ParamValue = ParamSingleValue|list<ParamSingleValue> */ interface ISearchComparison extends ISearchOperator { + /** + * @since 12.0.0 + */ public const COMPARE_EQUAL = 'eq'; + + /** + * @since 12.0.0 + */ public const COMPARE_GREATER_THAN = 'gt'; + + /** + * @since 12.0.0 + */ public const COMPARE_GREATER_THAN_EQUAL = 'gte'; + + /** + * @since 12.0.0 + */ public const COMPARE_LESS_THAN = 'lt'; + + /** + * @since 12.0.0 + */ public const COMPARE_LESS_THAN_EQUAL = 'lte'; + + /** + * @since 12.0.0 + */ public const COMPARE_LIKE = 'like'; /** + * @since 23.0.0 + */ + public const COMPARE_LIKE_CASE_SENSITIVE = 'clike'; + + /** + * @since 28.0.0 + */ + public const COMPARE_DEFINED = 'is-defined'; + + /** + * @since 29.0.0 + */ + public const COMPARE_IN = 'in'; + + /** + * @since 23.0.0 + */ + public const HINT_PATH_EQ_HASH = 'path_eq_hash'; // transform `path = "$path"` into `path_hash = md5("$path")`, on by default + + /** * Get the type of comparison, one of the ISearchComparison::COMPARE_* constants * * @return string * @since 12.0.0 */ - public function getType(); + public function getType(): string; /** * Get the name of the field to compare with @@ -51,13 +79,21 @@ interface ISearchComparison extends ISearchOperator { * @return string * @since 12.0.0 */ - public function getField(); + public function getField(): string; + + /** + * extra means data are not related to the main files table + * + * @return string + * @since 28.0.0 + */ + public function getExtra(): string; /** * Get the value to compare the field with * - * @return string|integer|\DateTime + * @return ParamValue * @since 12.0.0 */ - public function getValue(); + public function getValue(): string|int|bool|\DateTime|array; } diff --git a/lib/public/Files/Search/ISearchOperator.php b/lib/public/Files/Search/ISearchOperator.php index a443c2744cf..f6ae8edcbb1 100644 --- a/lib/public/Files/Search/ISearchOperator.php +++ b/lib/public/Files/Search/ISearchOperator.php @@ -1,30 +1,31 @@ <?php + /** - * @copyright Copyright (c) 2017 Robin Appelman <robin@icewind.nl> - * - * @author Robin Appelman <robin@icewind.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2017 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Search; /** * @since 12.0.0 */ interface ISearchOperator { + /** + * Get a query builder hint by name + * + * @param string $name + * @param $default + * @return mixed + * @since 23.0.0 + */ + public function getQueryHint(string $name, $default); + + /** + * Get a query builder hint + * + * @param string $name + * @param $value + * @since 23.0.0 + */ + public function setQueryHint(string $name, $value): void; } diff --git a/lib/public/Files/Search/ISearchOrder.php b/lib/public/Files/Search/ISearchOrder.php index fb0137c1bac..e6e68849443 100644 --- a/lib/public/Files/Search/ISearchOrder.php +++ b/lib/public/Files/Search/ISearchOrder.php @@ -1,34 +1,25 @@ <?php + /** - * @copyright Copyright (c) 2017 Robin Appelman <robin@icewind.nl> - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Robin Appelman <robin@icewind.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2017 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Search; +use OCP\Files\FileInfo; + /** * @since 12.0.0 */ interface ISearchOrder { + /** + * @since 12.0.0 + */ public const DIRECTION_ASCENDING = 'asc'; + + /** + * @since 12.0.0 + */ public const DIRECTION_DESCENDING = 'desc'; /** @@ -37,7 +28,7 @@ interface ISearchOrder { * @return string * @since 12.0.0 */ - public function getDirection(); + public function getDirection(): string; /** * The field to sort on @@ -45,5 +36,23 @@ interface ISearchOrder { * @return string * @since 12.0.0 */ - public function getField(); + public function getField(): string; + + /** + * extra means data are not related to the main files table + * + * @return string + * @since 28.0.0 + */ + public function getExtra(): string; + + /** + * Apply the sorting on 2 FileInfo objects + * + * @param FileInfo $a + * @param FileInfo $b + * @return int -1 if $a < $b, 0 if $a = $b, 1 if $a > $b (for ascending, reverse for descending) + * @since 22.0.0 + */ + public function sortFileInfo(FileInfo $a, FileInfo $b): int; } diff --git a/lib/public/Files/Search/ISearchQuery.php b/lib/public/Files/Search/ISearchQuery.php index 4d866f8d7b6..1b400c56e5b 100644 --- a/lib/public/Files/Search/ISearchQuery.php +++ b/lib/public/Files/Search/ISearchQuery.php @@ -1,26 +1,9 @@ <?php + /** - * @copyright Copyright (c) 2017 Robin Appelman <robin@icewind.nl> - * - * @author Robin Appelman <robin@icewind.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2017 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Search; use OCP\IUser; @@ -62,7 +45,7 @@ interface ISearchQuery { /** * The user that issued the search * - * @return IUser + * @return ?IUser * @since 12.0.0 */ public function getUser(); diff --git a/lib/public/Files/SimpleFS/ISimpleFile.php b/lib/public/Files/SimpleFS/ISimpleFile.php index 3ef005b361c..4e77299ab00 100644 --- a/lib/public/Files/SimpleFS/ISimpleFile.php +++ b/lib/public/Files/SimpleFS/ISimpleFile.php @@ -1,91 +1,76 @@ <?php + /** - * @copyright Copyright (c) 2016 Roeland Jago Douma <roeland@famdouma.nl> - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Julius Härtl <jus@bitgrid.net> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @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/>. - * + * 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; /** - * Interface ISimpleFile + * This interface allows to manage simple files. + * + * This interface must not be implemented in your application but + * instead should be used as a service and injected in your code with + * dependency injection. * * @since 11.0.0 */ interface ISimpleFile { - /** * Get the name * - * @return string * @since 11.0.0 */ - public function getName(); + public function getName(): string; /** * Get the size in bytes * - * @return int * @since 11.0.0 */ - public function getSize(); + public function getSize(): int|float; /** * Get the ETag * - * @return string * @since 11.0.0 */ - public function getETag(); + public function getETag(): string; /** * Get the last modification time * - * @return int * @since 11.0.0 */ - public function getMTime(); + public function getMTime(): int; /** * Get the content * - * @throws NotPermittedException + * @throws GenericFileException + * @throws LockedException * @throws NotFoundException - * @return string + * @throws NotPermittedException * @since 11.0.0 */ - public function getContent(); + public function getContent(): string; /** * 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); + public function putContent($data): void; /** * Delete the file @@ -93,20 +78,24 @@ interface ISimpleFile { * @throws NotPermittedException * @since 11.0.0 */ - public function delete(); + public function delete(): void; /** * Get the MimeType * - * @return string * @since 11.0.0 */ - public function getMimeType(); + public function getMimeType(): string; + + /** + * @since 24.0.0 + */ + public function getExtension(): string; /** * Open the file as stream for reading, resulting resource can be operated as stream like the result from php's own fopen * - * @return resource + * @return resource|false * @throws \OCP\Files\NotPermittedException * @since 14.0.0 */ diff --git a/lib/public/Files/SimpleFS/ISimpleFolder.php b/lib/public/Files/SimpleFS/ISimpleFolder.php index ebe8194325c..95efc676688 100644 --- a/lib/public/Files/SimpleFS/ISimpleFolder.php +++ b/lib/public/Files/SimpleFS/ISimpleFolder.php @@ -1,27 +1,9 @@ <?php + /** - * @copyright Copyright (c) 2016 Roeland Jago Douma <roeland@famdouma.nl> - * - * @author Robin Appelman <robin@icewind.nl> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2016 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\SimpleFS; use OCP\Files\NotFoundException; @@ -39,7 +21,7 @@ interface ISimpleFolder { * @return ISimpleFile[] * @since 11.0.0 */ - public function getDirectoryListing(); + public function getDirectoryListing(): array; /** * Check if a file with $name exists @@ -48,28 +30,24 @@ interface ISimpleFolder { * @return bool * @since 11.0.0 */ - public function fileExists($name); + public function fileExists(string $name): bool; /** * Get the file named $name from the folder * - * @param string $name - * @return ISimpleFile * @throws NotFoundException * @since 11.0.0 */ - public function getFile($name); + public function getFile(string $name): ISimpleFile; /** * Creates a new file with $name in the folder * - * @param string $name * @param string|resource|null $content @since 19.0.0 - * @return ISimpleFile * @throws NotPermittedException * @since 11.0.0 */ - public function newFile($name, $content = null); + public function newFile(string $name, $content = null): ISimpleFile; /** * Remove the folder and all the files in it @@ -77,13 +55,29 @@ interface ISimpleFolder { * @throws NotPermittedException * @since 11.0.0 */ - public function delete(); + public function delete(): void; /** * Get the folder name * - * @return string * @since 11.0.0 */ - public function getName(); + public function getName(): string; + + /** + * Get the folder named $name from the current folder + * + * @throws NotFoundException + * @since 25.0.0 + */ + public function getFolder(string $name): ISimpleFolder; + + /** + * Creates a new folder with $name in the current folder + * + * @param string|resource|null $content @since 19.0.0 + * @throws NotPermittedException + * @since 25.0.0 + */ + public function newFolder(string $path): ISimpleFolder; } diff --git a/lib/public/Files/SimpleFS/ISimpleRoot.php b/lib/public/Files/SimpleFS/ISimpleRoot.php index b90e8af5a7e..6be8a1d47c9 100644 --- a/lib/public/Files/SimpleFS/ISimpleRoot.php +++ b/lib/public/Files/SimpleFS/ISimpleRoot.php @@ -1,27 +1,9 @@ <?php + /** - * @copyright Copyright (c) 2016 Roeland Jago Douma <roeland@famdouma.nl> - * - * @author Morris Jobke <hey@morrisjobke.de> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2016 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\SimpleFS; use OCP\Files\NotFoundException; @@ -36,8 +18,6 @@ interface ISimpleRoot { /** * Get the folder with name $name * - * @param string $name - * @return ISimpleFolder * @throws NotFoundException * @throws \RuntimeException * @since 11.0.0 @@ -57,8 +37,6 @@ interface ISimpleRoot { /** * Create a new folder named $name * - * @param string $name - * @return ISimpleFolder * @throws NotPermittedException * @throws \RuntimeException * @since 11.0.0 diff --git a/lib/public/Files/SimpleFS/InMemoryFile.php b/lib/public/Files/SimpleFS/InMemoryFile.php index d420638737d..7849b8c879a 100644 --- a/lib/public/Files/SimpleFS/InMemoryFile.php +++ b/lib/public/Files/SimpleFS/InMemoryFile.php @@ -3,28 +3,9 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2018, Michael Weimann <mail@michael-weimann.eu> - * - * @author Michael Weimann <mail@michael-weimann.eu> - * @author Morris Jobke <hey@morrisjobke.de> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\SimpleFS; use OCP\Files\NotPermittedException; @@ -37,17 +18,13 @@ use OCP\Files\NotPermittedException; class InMemoryFile implements ISimpleFile { /** * Holds the file name. - * - * @var string */ - private $name; + private string $name; /** * Holds the file contents. - * - * @var string */ - private $contents; + private string $contents; /** * InMemoryFile constructor. @@ -65,7 +42,7 @@ class InMemoryFile implements ISimpleFile { * @inheritdoc * @since 16.0.0 */ - public function getName() { + public function getName(): string { return $this->name; } @@ -73,7 +50,7 @@ class InMemoryFile implements ISimpleFile { * @inheritdoc * @since 16.0.0 */ - public function getSize() { + public function getSize(): int|float { return strlen($this->contents); } @@ -81,7 +58,7 @@ class InMemoryFile implements ISimpleFile { * @inheritdoc * @since 16.0.0 */ - public function getETag() { + public function getETag(): string { return ''; } @@ -89,7 +66,7 @@ class InMemoryFile implements ISimpleFile { * @inheritdoc * @since 16.0.0 */ - public function getMTime() { + public function getMTime(): int { return time(); } @@ -97,7 +74,7 @@ class InMemoryFile implements ISimpleFile { * @inheritdoc * @since 16.0.0 */ - public function getContent() { + public function getContent(): string { return $this->contents; } @@ -105,7 +82,7 @@ class InMemoryFile implements ISimpleFile { * @inheritdoc * @since 16.0.0 */ - public function putContent($data) { + public function putContent($data): void { $this->contents = $data; } @@ -114,7 +91,7 @@ class InMemoryFile implements ISimpleFile { * * @since 16.0.0 */ - public function delete() { + public function delete(): void { // unimplemented for in memory files } @@ -122,12 +99,20 @@ class InMemoryFile implements ISimpleFile { * @inheritdoc * @since 16.0.0 */ - public function getMimeType() { + public function getMimeType(): string { $fileInfo = new \finfo(FILEINFO_MIME_TYPE); return $fileInfo->buffer($this->contents); } /** + * {@inheritDoc} + * @since 24.0.0 + */ + public function getExtension(): string { + return \pathinfo($this->name, PATHINFO_EXTENSION); + } + + /** * Stream reading is unsupported for in memory files. * * @throws NotPermittedException diff --git a/lib/public/Files/Storage.php b/lib/public/Files/Storage.php deleted file mode 100644 index c9e72983231..00000000000 --- a/lib/public/Files/Storage.php +++ /dev/null @@ -1,469 +0,0 @@ -<?php -/** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author J0WI <J0WI@users.noreply.github.com> - * @author Jörn Friedrich Dreyer <jfd@butonic.de> - * @author Lukas Reschke <lukas@statuscode.ch> - * @author Morris Jobke <hey@morrisjobke.de> - * @author Robin Appelman <robin@icewind.nl> - * @author Robin McCorkell <robin@mccorkell.me.uk> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * @author Thomas Müller <thomas.mueller@tmit.eu> - * @author Tigran Mkrtchyan <tigran.mkrtchyan@desy.de> - * @author Vincent Petry <vincent@nextcloud.com> - * @author Vinicius Cubas Brand <vinicius@eita.org.br> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * - */ - -/** - * Public interface of ownCloud for apps to use. - * Files/Storage interface - */ - -// use OCP namespace for all classes that are considered public. -// This means that they should be used by apps instead of the internal ownCloud 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|bool - * @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 int|bool - * @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|bool - * @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|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 $path1 - * @param string $path2 - * @return bool - * @since 6.0.0 - */ - public function rename($path1, $path2); - - /** - * see https://www.php.net/manual/en/function.copy.php - * - * @param string $path1 - * @param string $path2 - * @return bool - * @since 6.0.0 - */ - public function copy($path1, $path2); - - /** - * 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.free_space.php - * - * @param string $path - * @return int|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|bool - * @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|bool - * @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 - * - * @param string $class - * @return bool - * @since 7.0.0 - */ - 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); - - public function needsPartFile(); -} diff --git a/lib/public/Files/Storage/IChunkedFileWrite.php b/lib/public/Files/Storage/IChunkedFileWrite.php new file mode 100644 index 00000000000..0cf27814f0e --- /dev/null +++ b/lib/public/Files/Storage/IChunkedFileWrite.php @@ -0,0 +1,45 @@ +<?php + +/** + * SPDX-FileCopyrightText: 2021 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +declare(strict_types=1); + + +namespace OCP\Files\Storage; + +use OCP\Files\GenericFileException; + +/** + * @since 26.0.0 + */ +interface IChunkedFileWrite extends IStorage { + /** + * @param string $targetPath Relative target path in the storage + * @return string writeToken to be used with the other methods to uniquely identify the file write operation + * @throws GenericFileException + * @since 26.0.0 + */ + public function startChunkedWrite(string $targetPath): string; + + /** + * @param resource $data + * @throws GenericFileException + * @since 26.0.0 + */ + public function putChunkedWritePart(string $targetPath, string $writeToken, string $chunkId, $data, ?int $size = null): ?array; + + /** + * @throws GenericFileException + * @since 26.0.0 + */ + public function completeChunkedWrite(string $targetPath, string $writeToken): int; + + /** + * @throws GenericFileException + * @since 26.0.0 + */ + public function cancelChunkedWrite(string $targetPath, string $writeToken): void; +} 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 761f636b068..19951da2015 100644 --- a/lib/public/Files/Storage/IDisableEncryptionStorage.php +++ b/lib/public/Files/Storage/IDisableEncryptionStorage.php @@ -1,27 +1,9 @@ <?php + /** - * @copyright Copyright (c) 2018 Robin Appelman <robin@icewind.nl> - * - * @author Robin Appelman <robin@icewind.nl> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Storage; /** @@ -29,5 +11,5 @@ namespace OCP\Files\Storage; * * @since 16.0.0 */ -interface IDisableEncryptionStorage { +interface IDisableEncryptionStorage extends IStorage { } diff --git a/lib/public/Files/Storage/ILockingStorage.php b/lib/public/Files/Storage/ILockingStorage.php index 3fa08bce3f0..ceedf33ceab 100644 --- a/lib/public/Files/Storage/ILockingStorage.php +++ b/lib/public/Files/Storage/ILockingStorage.php @@ -1,26 +1,10 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Morris Jobke <hey@morrisjobke.de> - * @author Robin Appelman <robin@icewind.nl> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ - namespace OCP\Files\Storage; use OCP\Lock\ILockingProvider; @@ -37,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 35dc828dfdf..063ff815581 100644 --- a/lib/public/Files/Storage/INotifyStorage.php +++ b/lib/public/Files/Storage/INotifyStorage.php @@ -1,27 +1,9 @@ <?php + /** - * @copyright Copyright (c) 2016 Robin Appelman <robin@icewind.nl> - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Robin Appelman <robin@icewind.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2016 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Storage; use OCP\Files\Notify\INotifyHandler; @@ -32,18 +14,32 @@ use OCP\Files\Notify\INotifyHandler; * @since 9.1.0 */ interface INotifyStorage { + /** + * @since 9.1.0 + */ public const NOTIFY_ADDED = 1; + + /** + * @since 9.1.0 + */ public const NOTIFY_REMOVED = 2; + + /** + * @since 9.1.0 + */ public const NOTIFY_MODIFIED = 3; + + /** + * @since 9.1.0 + */ public const NOTIFY_RENAMED = 4; /** * 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/IReliableEtagStorage.php b/lib/public/Files/Storage/IReliableEtagStorage.php new file mode 100644 index 00000000000..29fbfacf831 --- /dev/null +++ b/lib/public/Files/Storage/IReliableEtagStorage.php @@ -0,0 +1,20 @@ +<?php + +declare(strict_types=1); +/** + * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +namespace OCP\Files\Storage; + +/** + * Marks a storage as providing reliable etags according to expected behavior of etags within nextcloud: + * + * - Etag are stable as long as no changes are made to the files + * - Changes inside a folder cause etag changes of the parent folders + * + * @since 24.0.0 + */ +interface IReliableEtagStorage extends IStorage { +} 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 5e70e319c40..5f6c8a0e8a0 100644 --- a/lib/public/Files/Storage/IStorage.php +++ b/lib/public/Files/Storage/IStorage.php @@ -1,37 +1,12 @@ <?php -/** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author J0WI <J0WI@users.noreply.github.com> - * @author Lukas Reschke <lukas@statuscode.ch> - * @author Robin Appelman <robin@icewind.nl> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * @author Tigran Mkrtchyan <tigran.mkrtchyan@desy.de> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * - */ /** - * Public interface of ownCloud for apps to use. - * Files/Storage interface + * 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 ownCloud classes +// This means that they should be used by apps instead of the internal Nextcloud classes namespace OCP\Files\Storage; @@ -48,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. @@ -72,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|bool + * @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 int|bool + * @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|bool + * @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|false + * @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 $path1 - * @param string $path2 * @return bool * @since 9.0.0 */ - public function rename($path1, $path2); + public function rename(string $source, string $target); /** * see https://www.php.net/manual/en/function.copy.php * - * @param string $path1 - * @param string $path2 * @return bool * @since 9.0.0 */ - public function copy($path1, $path2); + 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|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|bool + * @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|bool + * @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 @@ -362,49 +293,42 @@ interface IStorage { /** * Check if the storage is an instance of $class or is a wrapper for a storage that is an instance of $class * - * @param string $class + * @template T of IStorage + * @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 @@ -422,21 +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); /** * @return ICache * @since 9.0.0 */ - public function getCache(); + public function getCache(string $path = '', ?IStorage $storage = null); /** * @return IPropagator @@ -461,4 +392,16 @@ interface IStorage { * @since 9.0.0 */ public function getWatcher(); + + /** + * Allow setting the storage owner + * + * 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 $user Owner user id + * @return void + * @since 30.0.0 + */ + public function setOwner(?string $user): void; } diff --git a/lib/public/Files/Storage/IStorageFactory.php b/lib/public/Files/Storage/IStorageFactory.php index 7c5860f6b77..24f87d2e775 100644 --- a/lib/public/Files/Storage/IStorageFactory.php +++ b/lib/public/Files/Storage/IStorageFactory.php @@ -1,28 +1,10 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Morris Jobke <hey@morrisjobke.de> - * @author Robin Appelman <robin@icewind.nl> - * @author Vincent Petry <vincent@nextcloud.com> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ - namespace OCP\Files\Storage; use OCP\Files\Mount\IMountPoint; @@ -37,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 5f8e73e0cba..b03f46ef2bc 100644 --- a/lib/public/Files/Storage/IWriteStreamStorage.php +++ b/lib/public/Files/Storage/IWriteStreamStorage.php @@ -3,28 +3,9 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2018 Robin Appelman <robin@icewind.nl> - * - * @author Julius Härtl <jus@bitgrid.net> - * @author Robin Appelman <robin@icewind.nl> - * - * @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/>. - * + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Files\Storage; use OCP\Files\GenericFileException; @@ -38,12 +19,11 @@ 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 */ - public function writeStream(string $path, $stream, int $size = null): int; + public function writeStream(string $path, $stream, ?int $size = null): int; } diff --git a/lib/public/Files/StorageAuthException.php b/lib/public/Files/StorageAuthException.php index 24afacd72ea..d0115313a96 100644 --- a/lib/public/Files/StorageAuthException.php +++ b/lib/public/Files/StorageAuthException.php @@ -1,27 +1,10 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Jesús Macias <jmacias@solidgear.es> - * @author Lukas Reschke <lukas@statuscode.ch> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ - namespace OCP\Files; /** @@ -29,7 +12,6 @@ namespace OCP\Files; * @since 9.0.0 */ class StorageAuthException extends StorageNotAvailableException { - /** * StorageAuthException constructor. * @@ -37,8 +19,8 @@ class StorageAuthException extends StorageNotAvailableException { * @param \Exception|null $previous * @since 9.0.0 */ - public function __construct($message = '', \Exception $previous = null) { - $l = \OC::$server->getL10N('core'); + public function __construct($message = '', ?\Exception $previous = null) { + $l = \OCP\Util::getL10N('core'); parent::__construct($l->t('Storage unauthorized. %s', [$message]), self::STATUS_UNAUTHORIZED, $previous); } } diff --git a/lib/public/Files/StorageBadConfigException.php b/lib/public/Files/StorageBadConfigException.php index 2b0e362389f..c38bd840d3e 100644 --- a/lib/public/Files/StorageBadConfigException.php +++ b/lib/public/Files/StorageBadConfigException.php @@ -1,27 +1,10 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Jesús Macias <jmacias@solidgear.es> - * @author Lukas Reschke <lukas@statuscode.ch> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ - namespace OCP\Files; /** @@ -29,7 +12,6 @@ namespace OCP\Files; * @since 9.0.0 */ class StorageBadConfigException extends StorageNotAvailableException { - /** * ExtStorageBadConfigException constructor. * @@ -37,8 +19,8 @@ class StorageBadConfigException extends StorageNotAvailableException { * @param \Exception|null $previous * @since 9.0.0 */ - public function __construct($message = '', \Exception $previous = null) { - $l = \OC::$server->getL10N('core'); + public function __construct($message = '', ?\Exception $previous = null) { + $l = \OCP\Util::getL10N('core'); parent::__construct($l->t('Storage incomplete configuration. %s', [$message]), self::STATUS_INCOMPLETE_CONF, $previous); } } diff --git a/lib/public/Files/StorageConnectionException.php b/lib/public/Files/StorageConnectionException.php index 221fe661b3b..8629d8cee6e 100644 --- a/lib/public/Files/StorageConnectionException.php +++ b/lib/public/Files/StorageConnectionException.php @@ -1,27 +1,10 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Jesús Macias <jmacias@solidgear.es> - * @author Lukas Reschke <lukas@statuscode.ch> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ - namespace OCP\Files; /** @@ -29,7 +12,6 @@ namespace OCP\Files; * @since 9.0.0 */ class StorageConnectionException extends StorageNotAvailableException { - /** * StorageConnectionException constructor. * @@ -37,8 +19,8 @@ class StorageConnectionException extends StorageNotAvailableException { * @param \Exception|null $previous * @since 9.0.0 */ - public function __construct($message = '', \Exception $previous = null) { - $l = \OC::$server->getL10N('core'); + public function __construct($message = '', ?\Exception $previous = null) { + $l = \OCP\Util::getL10N('core'); parent::__construct($l->t('Storage connection error. %s', [$message]), self::STATUS_NETWORK_ERROR, $previous); } } diff --git a/lib/public/Files/StorageInvalidException.php b/lib/public/Files/StorageInvalidException.php index 3f9acdc1562..1109bf2790e 100644 --- a/lib/public/Files/StorageInvalidException.php +++ b/lib/public/Files/StorageInvalidException.php @@ -1,34 +1,12 @@ <?php -/** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Morris Jobke <hey@morrisjobke.de> - * @author Robin Appelman <robin@icewind.nl> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * - */ /** - * Public interface of ownCloud for apps to use. - * Files/AlreadyExistsException class + * 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 ownCloud classes +// This means that they should be used by apps instead of the internal Nextcloud classes namespace OCP\Files; diff --git a/lib/public/Files/StorageNotAvailableException.php b/lib/public/Files/StorageNotAvailableException.php index 11b8d76f706..208c7de3238 100644 --- a/lib/public/Files/StorageNotAvailableException.php +++ b/lib/public/Files/StorageNotAvailableException.php @@ -1,56 +1,56 @@ <?php -/** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Björn Schießle <bjoern@schiessle.org> - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Jesús Macias <jmacias@solidgear.es> - * @author Lukas Reschke <lukas@statuscode.ch> - * @author Morris Jobke <hey@morrisjobke.de> - * @author Robin Appelman <robin@icewind.nl> - * @author Robin McCorkell <robin@mccorkell.me.uk> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * @author Vincent Petry <vincent@nextcloud.com> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * - */ /** - * Public interface of ownCloud for apps to use. - * Files/AlreadyExistsException class + * 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 ownCloud classes +// This means that they should be used by apps instead of the internal Nextcloud classes namespace OCP\Files; -use OC\HintException; +use OCP\HintException; /** * Storage is temporarily not available - * @since 6.0.0 - since 8.2.1 based on HintException + * @since 6.0.0 + * @since 8.2.1 based on HintException */ class StorageNotAvailableException extends HintException { + /** + * @since 8.2.0 + */ public const STATUS_SUCCESS = 0; + + /** + * @since 8.2.0 + */ public const STATUS_ERROR = 1; + + /** + * @since 8.2.0 + */ public const STATUS_INDETERMINATE = 2; + + /** + * @since 8.2.0 + */ public const STATUS_INCOMPLETE_CONF = 3; + + /** + * @since 8.2.0 + */ public const STATUS_UNAUTHORIZED = 4; + + /** + * @since 8.2.0 + */ public const STATUS_TIMEOUT = 5; + + /** + * @since 8.2.0 + */ public const STATUS_NETWORK_ERROR = 6; /** @@ -61,8 +61,8 @@ class StorageNotAvailableException extends HintException { * @param \Exception|null $previous * @since 6.0.0 */ - public function __construct($message = '', $code = self::STATUS_ERROR, \Exception $previous = null) { - $l = \OC::$server->getL10N('core'); + public function __construct($message = '', $code = self::STATUS_ERROR, ?\Exception $previous = null) { + $l = \OCP\Util::getL10N('core'); parent::__construct($message, $l->t('Storage is temporarily not available'), $code, $previous); } diff --git a/lib/public/Files/StorageTimeoutException.php b/lib/public/Files/StorageTimeoutException.php index b473b5da96f..85201932d66 100644 --- a/lib/public/Files/StorageTimeoutException.php +++ b/lib/public/Files/StorageTimeoutException.php @@ -1,27 +1,10 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Jesús Macias <jmacias@solidgear.es> - * @author Lukas Reschke <lukas@statuscode.ch> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ - namespace OCP\Files; /** @@ -29,7 +12,6 @@ namespace OCP\Files; * @since 9.0.0 */ class StorageTimeoutException extends StorageNotAvailableException { - /** * StorageTimeoutException constructor. * @@ -37,8 +19,8 @@ class StorageTimeoutException extends StorageNotAvailableException { * @param \Exception|null $previous * @since 9.0.0 */ - public function __construct($message = '', \Exception $previous = null) { - $l = \OC::$server->getL10N('core'); + public function __construct($message = '', ?\Exception $previous = null) { + $l = \OCP\Util::getL10N('core'); parent::__construct($l->t('Storage connection timeout. %s', [$message]), self::STATUS_TIMEOUT, $previous); } } 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 7ed342e4007..0636d1dc251 100644 --- a/lib/public/Files/Template/FileCreatedFromTemplateEvent.php +++ b/lib/public/Files/Template/FileCreatedFromTemplateEvent.php @@ -1,29 +1,11 @@ <?php -/* - * @copyright Copyright (c) 2021 Julius Härtl <jus@bitgrid.net> - * - * @author Julius Härtl <jus@bitgrid.net> - * - * @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/>. - * - */ declare(strict_types=1); - +/** + * SPDX-FileCopyrightText: 2021 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ namespace OCP\Files\Template; use OCP\EventDispatcher\Event; @@ -35,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; } /** @@ -55,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 a14ea86a100..6136bc4f1c0 100644 --- a/lib/public/Files/Template/ICustomTemplateProvider.php +++ b/lib/public/Files/Template/ICustomTemplateProvider.php @@ -1,29 +1,11 @@ <?php -/* - * @copyright Copyright (c) 2021 Julius Härtl <jus@bitgrid.net> - * - * @author Julius Härtl <jus@bitgrid.net> - * - * @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/>. - * - */ declare(strict_types=1); - +/** + * SPDX-FileCopyrightText: 2021 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ namespace OCP\Files\Template; use OCP\Files\File; @@ -35,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 39a48598508..df81bc5604e 100644 --- a/lib/public/Files/Template/ITemplateManager.php +++ b/lib/public/Files/Template/ITemplateManager.php @@ -1,29 +1,11 @@ <?php -/** - * @copyright Copyright (c) 2021 Julius Härtl <jus@bitgrid.net> - * - * @author Julius Härtl <jus@bitgrid.net> - * - * @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/>. - * - */ declare(strict_types=1); - +/** + * SPDX-FileCopyrightText: 2021 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ namespace OCP\Files\Template; use OCP\Files\GenericFileException; @@ -32,7 +14,6 @@ use OCP\Files\GenericFileException; * @since 21.0.0 */ interface ITemplateManager { - /** * Register a template type support * @@ -52,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 */ @@ -81,14 +71,16 @@ interface ITemplateManager { * @param string|null $userId * @since 21.0.0 */ - public function initializeTemplateDirectory(string $path = null, string $userId = null, $copyTemplates = true): string; + public function initializeTemplateDirectory(?string $path = null, ?string $userId = null, $copyTemplates = true): string; /** * @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 new file mode 100644 index 00000000000..a9e7fa01252 --- /dev/null +++ b/lib/public/Files/Template/RegisterTemplateCreatorEvent.php @@ -0,0 +1,31 @@ +<?php + +/** + * 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 RegisterTemplateCreatorEvent extends Event { + + /** + * @since 30.0.0 + */ + public function __construct( + private ITemplateManager $templateManager, + ) { + } + + /** + * @since 30.0.0 + */ + public function getTemplateManager(): ITemplateManager { + return $this->templateManager; + } +} diff --git a/lib/public/Files/Template/Template.php b/lib/public/Files/Template/Template.php index 71c02d1f5be..7f01c2afa48 100644 --- a/lib/public/Files/Template/Template.php +++ b/lib/public/Files/Template/Template.php @@ -1,29 +1,11 @@ <?php -/* - * @copyright Copyright (c) 2021 Julius Härtl <jus@bitgrid.net> - * - * @author Julius Härtl <jus@bitgrid.net> - * - * @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/>. - * - */ declare(strict_types=1); - +/** + * SPDX-FileCopyrightText: 2021 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ namespace OCP\Files\Template; use OCP\Files\File; @@ -32,7 +14,6 @@ use OCP\Files\File; * @since 21.0.0 */ final class Template implements \JsonSerializable { - /** @var string */ private $templateType; /** @var string */ @@ -43,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 @@ -68,9 +51,40 @@ 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() { + public function jsonSerialize(): array { return [ 'templateType' => $this->templateType, 'templateId' => $this->templateId, @@ -83,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 e40fa8e91b3..809bd3d0bc2 100644 --- a/lib/public/Files/Template/TemplateFileCreator.php +++ b/lib/public/Files/Template/TemplateFileCreator.php @@ -1,28 +1,11 @@ <?php -/* - * @copyright Copyright (c) 2021 Julius Härtl <jus@bitgrid.net> - * - * @author Julius Härtl <jus@bitgrid.net> - * - * @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/>. - * - */ declare(strict_types=1); +/** + * SPDX-FileCopyrightText: 2021 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ namespace OCP\Files\Template; /** @@ -30,18 +13,28 @@ namespace OCP\Files\Template; */ final class TemplateFileCreator implements \JsonSerializable { protected $appId; + /** @var list<string> $mimetypes */ protected $mimetypes = []; protected $actionName; protected $fileExtension; + /** @var ?string $iconClass */ protected $iconClass; + /** @var ?string $iconSvgInline */ + protected $iconSvgInline; + /** @var ?float $ratio */ protected $ratio = null; protected $order = 100; + /** + * @since 27.0.0 + * @deprecated 28.0.0 + */ + protected string $actionLabel = ''; /** * @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; @@ -57,6 +50,7 @@ final class TemplateFileCreator implements \JsonSerializable { /** * @since 21.0.0 + * @deprecated 29.0.0 */ public function setIconClass(string $iconClass): TemplateFileCreator { $this->iconClass = $iconClass; @@ -64,6 +58,14 @@ final class TemplateFileCreator implements \JsonSerializable { } /** + * @since 29.0.0 + */ + public function setIconSvgInline(string $iconSvgInline): TemplateFileCreator { + $this->iconSvgInline = $iconSvgInline; + return $this; + } + + /** * @since 21.0.0 */ public function addMimetype(string $mimetype): TemplateFileCreator { @@ -103,16 +105,34 @@ final class TemplateFileCreator implements \JsonSerializable { } /** + * @since 27.0.0 + */ + public function setActionLabel(string $actionLabel): TemplateFileCreator { + $this->actionLabel = $actionLabel; + return $this; + } + + /** + * @since 27.0.0 + */ + public function getActionLabel(): string { + return $this->actionLabel; + } + + /** * @since 21.0.0 + * @return array{app: string, label: string, extension: string, iconClass: ?string, iconSvgInline: ?string, mimetypes: list<string>, ratio: ?float, actionLabel: string} */ - public function jsonSerialize() { + public function jsonSerialize(): array { return [ 'app' => $this->appId, 'label' => $this->actionName, 'extension' => $this->fileExtension, 'iconClass' => $this->iconClass, + 'iconSvgInline' => $this->iconSvgInline, 'mimetypes' => $this->mimetypes, - 'ratio' => $this->ratio + 'ratio' => $this->ratio, + 'actionLabel' => $this->actionLabel, ]; } } diff --git a/lib/public/Files/UnseekableException.php b/lib/public/Files/UnseekableException.php index 13ef6330207..7152b0e4210 100644 --- a/lib/public/Files/UnseekableException.php +++ b/lib/public/Files/UnseekableException.php @@ -1,34 +1,12 @@ <?php -/** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Piotr Filiciak <piotr@filiciak.pl> - * @author Roeland Jago Douma <roeland@famdouma.nl> - * - * @license AGPL-3.0 - * - * This code is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License, version 3, - * as published by the Free Software Foundation. - * - * 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, version 3, - * along with this program. If not, see <http://www.gnu.org/licenses/> - * - */ /** - * Public interface of ownCloud for apps to use. - * Files/UnseekableException class + * 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 ownCloud classes +// This means that they should be used by apps instead of the internal Nextcloud classes namespace OCP\Files; |