diff options
Diffstat (limited to 'lib/public/Files')
141 files changed, 2475 insertions, 2899 deletions
diff --git a/lib/public/Files/AlreadyExistsException.php b/lib/public/Files/AlreadyExistsException.php index 4e4e2cc505d..1935243a79c 100644 --- a/lib/public/Files/AlreadyExistsException.php +++ b/lib/public/Files/AlreadyExistsException.php @@ -1,29 +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/> - * + * 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 4b2daf6bfc0..b2f01b2e470 100644 --- a/lib/public/Files/Cache/AbstractCacheEvent.php +++ b/lib/public/Files/Cache/AbstractCacheEvent.php @@ -3,27 +3,8 @@ 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; diff --git a/lib/public/Files/Cache/CacheEntryInsertedEvent.php b/lib/public/Files/Cache/CacheEntryInsertedEvent.php index c3aa5f0a598..c3afe0f034f 100644 --- a/lib/public/Files/Cache/CacheEntryInsertedEvent.php +++ b/lib/public/Files/Cache/CacheEntryInsertedEvent.php @@ -3,25 +3,8 @@ 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 f4009fde81c..d0f8c47b430 100644 --- a/lib/public/Files/Cache/CacheEntryRemovedEvent.php +++ b/lib/public/Files/Cache/CacheEntryRemovedEvent.php @@ -3,25 +3,8 @@ 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 91f4d17cc6a..91dcf5340aa 100644 --- a/lib/public/Files/Cache/CacheEntryUpdatedEvent.php +++ b/lib/public/Files/Cache/CacheEntryUpdatedEvent.php @@ -3,25 +3,8 @@ 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 3c2210c964e..18a64cfb36b 100644 --- a/lib/public/Files/Cache/CacheInsertEvent.php +++ b/lib/public/Files/Cache/CacheInsertEvent.php @@ -3,25 +3,8 @@ 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 5903d18f965..7c2a290bd1d 100644 --- a/lib/public/Files/Cache/CacheUpdateEvent.php +++ b/lib/public/Files/Cache/CacheUpdateEvent.php @@ -3,25 +3,8 @@ 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 e27f4207f1e..cd610b15545 100644 --- a/lib/public/Files/Cache/ICache.php +++ b/lib/public/Files/Cache/ICache.php @@ -1,24 +1,9 @@ <?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; @@ -28,7 +13,7 @@ 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 Nextcloud instance and rescans files and folder when a change is detected @@ -38,9 +23,24 @@ use OCP\Files\Search\ISearchQuery; * @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; /** @@ -219,7 +219,7 @@ interface ICache { * search for files by mimetype * * @param string $mimetype either a full mimetype to search ('text/plain') or only the first part of a mimetype ('image') - * where it will search for all mimetypes in the group ('image/*') + * where it will search for all mimetypes in the group ('image/*') * @return ICacheEntry[] an array of cache entries where the mimetype matches the search * @since 9.0.0 * @deprecated 9.0.0 due to lack of pagination, not all backends might implement this @@ -231,7 +231,7 @@ interface ICache { * * @param ISearchQuery $query * @return ICacheEntry[] - * @throw \InvalidArgumentException if the cache is unable to perform the query + * @throws \InvalidArgumentException if the cache is unable to perform the query * @since 12.0.0 */ public function searchQuery(ISearchQuery $query); @@ -243,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(); diff --git a/lib/public/Files/Cache/ICacheEntry.php b/lib/public/Files/Cache/ICacheEntry.php index 17eecf89ddb..28e673071fd 100644 --- a/lib/public/Files/Cache/ICacheEntry.php +++ b/lib/public/Files/Cache/ICacheEntry.php @@ -1,24 +1,9 @@ <?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; @@ -28,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'; /** @@ -123,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 @@ -162,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 87d9a3a3fe4..a5659efd4a6 100644 --- a/lib/public/Files/Cache/ICacheEvent.php +++ b/lib/public/Files/Cache/ICacheEvent.php @@ -3,26 +3,8 @@ 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; 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 0ff72cd849f..703cba59599 100644 --- a/lib/public/Files/Cache/IPropagator.php +++ b/lib/public/Files/Cache/IPropagator.php @@ -1,23 +1,9 @@ <?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; diff --git a/lib/public/Files/Cache/IScanner.php b/lib/public/Files/Cache/IScanner.php index 8a45bfa6de7..9b3c283b436 100644 --- a/lib/public/Files/Cache/IScanner.php +++ b/lib/public/Files/Cache/IScanner.php @@ -1,24 +1,9 @@ <?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; @@ -28,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; /** diff --git a/lib/public/Files/Cache/IUpdater.php b/lib/public/Files/Cache/IUpdater.php index 5a776d4be7e..2bc702114b4 100644 --- a/lib/public/Files/Cache/IUpdater.php +++ b/lib/public/Files/Cache/IUpdater.php @@ -1,23 +1,9 @@ <?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; @@ -53,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 @@ -72,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 f70024247d5..62b90f672c6 100644 --- a/lib/public/Files/Cache/IWatcher.php +++ b/lib/public/Files/Cache/IWatcher.php @@ -1,24 +1,9 @@ <?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; @@ -28,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 /** @@ -80,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 e6aa2ec38c8..a9b30d8ba6d 100644 --- a/lib/public/Files/Config/ICachedMountFileInfo.php +++ b/lib/public/Files/Config/ICachedMountFileInfo.php @@ -1,24 +1,8 @@ <?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; diff --git a/lib/public/Files/Config/ICachedMountInfo.php b/lib/public/Files/Config/ICachedMountInfo.php index dafd2423fdc..cb9c0205d3d 100644 --- a/lib/public/Files/Config/ICachedMountInfo.php +++ b/lib/public/Files/Config/ICachedMountInfo.php @@ -1,24 +1,9 @@ <?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; @@ -84,4 +69,12 @@ interface ICachedMountInfo { * @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 00bcd1dbc9f..b193e9ba22e 100644 --- a/lib/public/Files/Config/IHomeMountProvider.php +++ b/lib/public/Files/Config/IHomeMountProvider.php @@ -1,23 +1,9 @@ <?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; diff --git a/lib/public/Files/Config/IMountProvider.php b/lib/public/Files/Config/IMountProvider.php index 6ac7c1acd5a..b59813a866d 100644 --- a/lib/public/Files/Config/IMountProvider.php +++ b/lib/public/Files/Config/IMountProvider.php @@ -1,24 +1,9 @@ <?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; diff --git a/lib/public/Files/Config/IMountProviderCollection.php b/lib/public/Files/Config/IMountProviderCollection.php index 2d42246b863..db5188372c1 100644 --- a/lib/public/Files/Config/IMountProviderCollection.php +++ b/lib/public/Files/Config/IMountProviderCollection.php @@ -1,24 +1,9 @@ <?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; diff --git a/lib/public/Files/Config/IRootMountProvider.php b/lib/public/Files/Config/IRootMountProvider.php index bb6147ac691..e2a32fc346a 100644 --- a/lib/public/Files/Config/IRootMountProvider.php +++ b/lib/public/Files/Config/IRootMountProvider.php @@ -3,25 +3,8 @@ 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; diff --git a/lib/public/Files/Config/IUserMountCache.php b/lib/public/Files/Config/IUserMountCache.php index 4411200c7ae..a5b68ded66d 100644 --- a/lib/public/Files/Config/IUserMountCache.php +++ b/lib/public/Files/Config/IUserMountCache.php @@ -1,26 +1,9 @@ <?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 szaimen <szaimen@e.mail.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\Config; @@ -42,7 +25,7 @@ interface IUserMountCache { * @param array|null $mountProviderClasses * @since 9.0.0 */ - public function registerMounts(IUser $user, array $mounts, array $mountProviderClasses = null); + public function registerMounts(IUser $user, array $mounts, ?array $mountProviderClasses = null); /** * Get all cached mounts for a user 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 99708f9afd8..1630ce63ea2 100644 --- a/lib/public/Files/EmptyFileNameException.php +++ b/lib/public/Files/EmptyFileNameException.php @@ -1,24 +1,8 @@ <?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 04322dd0146..f703d3cf414 100644 --- a/lib/public/Files/EntityTooLargeException.php +++ b/lib/public/Files/EntityTooLargeException.php @@ -1,29 +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/> - * + * 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 10aabc4a143..70c9d23c156 100644 --- a/lib/public/Files/Events/BeforeFileScannedEvent.php +++ b/lib/public/Files/Events/BeforeFileScannedEvent.php @@ -3,25 +3,8 @@ 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; @@ -31,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 add86ab719c..cd72c79e8d8 100644 --- a/lib/public/Files/Events/BeforeFolderScannedEvent.php +++ b/lib/public/Files/Events/BeforeFolderScannedEvent.php @@ -3,25 +3,8 @@ 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; @@ -31,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 28376fc10b9..7b3877bb05d 100644 --- a/lib/public/Files/Events/FileCacheUpdated.php +++ b/lib/public/Files/Events/FileCacheUpdated.php @@ -3,25 +3,8 @@ 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; @@ -32,7 +15,6 @@ use OCP\Files\Storage\IStorage; * @since 18.0.0 */ class FileCacheUpdated extends Event { - /** @var IStorage */ private $storage; @@ -45,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 3d6b3020b94..9ede4e2425f 100644 --- a/lib/public/Files/Events/FileScannedEvent.php +++ b/lib/public/Files/Events/FileScannedEvent.php @@ -3,25 +3,8 @@ 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; @@ -31,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 82c408daaba..5e14bbfb6a8 100644 --- a/lib/public/Files/Events/FolderScannedEvent.php +++ b/lib/public/Files/Events/FolderScannedEvent.php @@ -3,25 +3,8 @@ 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; @@ -31,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 index 6508e168d4c..a29281ddcec 100644 --- a/lib/public/Files/Events/InvalidateMountCacheEvent.php +++ b/lib/public/Files/Events/InvalidateMountCacheEvent.php @@ -2,23 +2,8 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2022 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: 2022 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Files\Events; diff --git a/lib/public/Files/Events/Node/AbstractNodeEvent.php b/lib/public/Files/Events/Node/AbstractNodeEvent.php index 6478d527eee..7afb71277f6 100644 --- a/lib/public/Files/Events/Node/AbstractNodeEvent.php +++ b/lib/public/Files/Events/Node/AbstractNodeEvent.php @@ -3,44 +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, + ) { } /** @@ -49,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 dd2174f0884..8fa8795d1df 100644 --- a/lib/public/Files/Events/Node/AbstractNodesEvent.php +++ b/lib/public/Files/Events/Node/AbstractNodesEvent.php @@ -3,47 +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, + ) { } /** @@ -59,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 07c14838b97..c7c014cfd64 100644 --- a/lib/public/Files/Events/Node/BeforeNodeCopiedEvent.php +++ b/lib/public/Files/Events/Node/BeforeNodeCopiedEvent.php @@ -3,25 +3,8 @@ 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 e213956a05f..3f42687576d 100644 --- a/lib/public/Files/Events/Node/BeforeNodeCreatedEvent.php +++ b/lib/public/Files/Events/Node/BeforeNodeCreatedEvent.php @@ -3,25 +3,8 @@ 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 316a30fadd8..83d9402dbeb 100644 --- a/lib/public/Files/Events/Node/BeforeNodeDeletedEvent.php +++ b/lib/public/Files/Events/Node/BeforeNodeDeletedEvent.php @@ -3,30 +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 14d0ee7ad8b..ae688fccb30 100644 --- a/lib/public/Files/Events/Node/BeforeNodeReadEvent.php +++ b/lib/public/Files/Events/Node/BeforeNodeReadEvent.php @@ -3,25 +3,8 @@ 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 efbef03e383..54714b8f7e2 100644 --- a/lib/public/Files/Events/Node/BeforeNodeRenamedEvent.php +++ b/lib/public/Files/Events/Node/BeforeNodeRenamedEvent.php @@ -3,30 +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 2b9e3df566b..ed2e561e947 100644 --- a/lib/public/Files/Events/Node/BeforeNodeTouchedEvent.php +++ b/lib/public/Files/Events/Node/BeforeNodeTouchedEvent.php @@ -3,25 +3,8 @@ 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 a9c1f00c0ff..61d3afb9cd6 100644 --- a/lib/public/Files/Events/Node/BeforeNodeWrittenEvent.php +++ b/lib/public/Files/Events/Node/BeforeNodeWrittenEvent.php @@ -3,25 +3,8 @@ 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 index 3e7780c827e..2076b739b51 100644 --- a/lib/public/Files/Events/Node/FilesystemTornDownEvent.php +++ b/lib/public/Files/Events/Node/FilesystemTornDownEvent.php @@ -2,23 +2,8 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2022 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: 2022 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/NodeCopiedEvent.php b/lib/public/Files/Events/Node/NodeCopiedEvent.php index ba0f495fd92..8913f34835e 100644 --- a/lib/public/Files/Events/Node/NodeCopiedEvent.php +++ b/lib/public/Files/Events/Node/NodeCopiedEvent.php @@ -3,25 +3,8 @@ 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 3b19503ac74..ffcbc9a9f10 100644 --- a/lib/public/Files/Events/Node/NodeCreatedEvent.php +++ b/lib/public/Files/Events/Node/NodeCreatedEvent.php @@ -3,25 +3,8 @@ 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 b04cf336aa7..58689e2c3d9 100644 --- a/lib/public/Files/Events/Node/NodeDeletedEvent.php +++ b/lib/public/Files/Events/Node/NodeDeletedEvent.php @@ -3,25 +3,8 @@ 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 9194a679e3b..f126d191d7f 100644 --- a/lib/public/Files/Events/Node/NodeRenamedEvent.php +++ b/lib/public/Files/Events/Node/NodeRenamedEvent.php @@ -3,25 +3,8 @@ 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 236bce9a764..88037311b4a 100644 --- a/lib/public/Files/Events/Node/NodeTouchedEvent.php +++ b/lib/public/Files/Events/Node/NodeTouchedEvent.php @@ -3,25 +3,8 @@ 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 a4862cd8042..b6bb949167c 100644 --- a/lib/public/Files/Events/Node/NodeWrittenEvent.php +++ b/lib/public/Files/Events/Node/NodeWrittenEvent.php @@ -3,25 +3,8 @@ 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 8699131d4d4..4ea20a3f3c1 100644 --- a/lib/public/Files/Events/NodeAddedToCache.php +++ b/lib/public/Files/Events/NodeAddedToCache.php @@ -3,25 +3,8 @@ 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; @@ -32,7 +15,6 @@ use OCP\Files\Storage\IStorage; * @since 18.0.0 */ class NodeAddedToCache extends Event { - /** @var IStorage */ private $storage; @@ -45,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 7c85e5e4586..01c8c21f71d 100644 --- a/lib/public/Files/Events/NodeRemovedFromCache.php +++ b/lib/public/Files/Events/NodeRemovedFromCache.php @@ -3,25 +3,8 @@ 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; @@ -32,7 +15,6 @@ use OCP\Files\Storage\IStorage; * @since 18.0.0 */ class NodeRemovedFromCache extends Event { - /** @var IStorage */ private $storage; @@ -45,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 cdb868241b6..d0aceeaba37 100644 --- a/lib/public/Files/File.php +++ b/lib/public/Files/File.php @@ -1,29 +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/> - * + * 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; @@ -40,6 +23,7 @@ interface File extends Node { * * @return string * @throws NotPermittedException + * @throws GenericFileException * @throws LockedException * @since 6.0.0 */ @@ -68,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 92c191b63e0..f9957f580e8 100644 --- a/lib/public/Files/FileInfo.php +++ b/lib/public/Files/FileInfo.php @@ -1,30 +1,9 @@ <?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; @@ -84,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); @@ -154,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 @@ -250,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 @@ -296,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 f188eca5193..ae1022cca50 100644 --- a/lib/public/Files/FileNameTooLongException.php +++ b/lib/public/Files/FileNameTooLongException.php @@ -1,28 +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/> - * + * 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 912c5472fac..a35d2d78bc9 100644 --- a/lib/public/Files/Folder.php +++ b/lib/public/Files/Folder.php @@ -1,30 +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/> - * + * 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; @@ -78,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); @@ -142,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 @@ -154,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 @@ -186,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 4b148dde93b..514ef8623d3 100644 --- a/lib/public/Files/ForbiddenException.php +++ b/lib/public/Files/ForbiddenException.php @@ -1,28 +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; @@ -32,7 +16,6 @@ namespace OCP\Files; * @since 9.0.0 */ class ForbiddenException extends \Exception { - /** @var bool */ private $retry; @@ -42,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; } @@ -52,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 3ee36339c9e..66a3b5e5ac4 100644 --- a/lib/public/Files/GenericFileException.php +++ b/lib/public/Files/GenericFileException.php @@ -1,24 +1,8 @@ <?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 6217f4a263c..4d0c4da6a8a 100644 --- a/lib/public/Files/IAppData.php +++ b/lib/public/Files/IAppData.php @@ -1,25 +1,8 @@ <?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; 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 7eb3ffc4a24..6f2ca82ef72 100644 --- a/lib/public/Files/IHomeStorage.php +++ b/lib/public/Files/IHomeStorage.php @@ -1,32 +1,17 @@ <?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/> - * + * 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 @@ -34,4 +19,11 @@ use OCP\Files\Storage\IStorage; * @since 7.0.0 */ 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 6017360cab0..1e87cf932ce 100644 --- a/lib/public/Files/IMimeTypeDetector.php +++ b/lib/public/Files/IMimeTypeDetector.php @@ -1,27 +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; @@ -29,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 @@ -42,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 @@ -50,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 @@ -59,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 @@ -68,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 @@ -83,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 faed18ed7d9..77c59fb2c0a 100644 --- a/lib/public/Files/IMimeTypeLoader.php +++ b/lib/public/Files/IMimeTypeLoader.php @@ -1,23 +1,9 @@ <?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; @@ -28,7 +14,6 @@ namespace OCP\Files; * Interface to load mimetypes **/ interface IMimeTypeLoader { - /** * Get a mimetype from its ID * @@ -36,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 @@ -45,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 @@ -54,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 7d007cb690c..fb8532f8c81 100644 --- a/lib/public/Files/IRootFolder.php +++ b/lib/public/Files/IRootFolder.php @@ -1,31 +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 @@ -33,7 +19,6 @@ use OC\User\NoUserException; * @since 8.0.0 */ interface IRootFolder extends Folder, Emitter { - /** * Returns a view to user's files folder * @@ -56,4 +41,50 @@ interface IRootFolder extends Folder, Emitter { * @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 b54269e12eb..f34a5778bcf 100644 --- a/lib/public/Files/InvalidCharacterInPathException.php +++ b/lib/public/Files/InvalidCharacterInPathException.php @@ -1,28 +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/> - * + * 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 7eee0d46780..bf5d1306751 100644 --- a/lib/public/Files/InvalidContentException.php +++ b/lib/public/Files/InvalidContentException.php @@ -1,29 +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/> - * + * 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 613d12bd5b5..b9640209cbf 100644 --- a/lib/public/Files/InvalidDirectoryException.php +++ b/lib/public/Files/InvalidDirectoryException.php @@ -1,24 +1,8 @@ <?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 98e886d6fa0..1c944f26844 100644 --- a/lib/public/Files/InvalidPathException.php +++ b/lib/public/Files/InvalidPathException.php @@ -1,29 +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/> - * + * 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 index 03737a178c6..4adb45b7b18 100644 --- a/lib/public/Files/Lock/ILock.php +++ b/lib/public/Files/Lock/ILock.php @@ -3,25 +3,8 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2022 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/>. - * + * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Files\Lock; @@ -30,7 +13,6 @@ namespace OCP\Files\Lock; * @since 24.0.0 */ interface ILock { - /** * User owned manual lock * diff --git a/lib/public/Files/Lock/ILockManager.php b/lib/public/Files/Lock/ILockManager.php index cad66380e93..d19116a9b3d 100644 --- a/lib/public/Files/Lock/ILockManager.php +++ b/lib/public/Files/Lock/ILockManager.php @@ -3,25 +3,8 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2022 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/>. - * + * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Files\Lock; @@ -39,14 +22,21 @@ use OCP\PreConditionNotMetException; * @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 */ diff --git a/lib/public/Files/Lock/ILockProvider.php b/lib/public/Files/Lock/ILockProvider.php index 50326c427e4..be0306e3188 100644 --- a/lib/public/Files/Lock/ILockProvider.php +++ b/lib/public/Files/Lock/ILockProvider.php @@ -3,25 +3,8 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2022 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/>. - * + * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Files\Lock; @@ -32,7 +15,6 @@ use OCP\PreConditionNotMetException; * @since 24.0.0 */ interface ILockProvider { - /** * @throws PreConditionNotMetException * @throws NoLockProviderException diff --git a/lib/public/Files/Lock/LockContext.php b/lib/public/Files/Lock/LockContext.php index 1466cb41ae1..5e61d3e2ec5 100644 --- a/lib/public/Files/Lock/LockContext.php +++ b/lib/public/Files/Lock/LockContext.php @@ -3,25 +3,8 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2022 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/>. - * + * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Files\Lock; @@ -50,7 +33,7 @@ final class LockContext { public function __construct( Node $node, int $type, - string $owner + string $owner, ) { $this->node = $node; $this->type = $type; diff --git a/lib/public/Files/Lock/NoLockProviderException.php b/lib/public/Files/Lock/NoLockProviderException.php index ab727348e87..460cdc76e6e 100644 --- a/lib/public/Files/Lock/NoLockProviderException.php +++ b/lib/public/Files/Lock/NoLockProviderException.php @@ -3,25 +3,8 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2022 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/>. - * + * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Files\Lock; diff --git a/lib/public/Files/Lock/OwnerLockedException.php b/lib/public/Files/Lock/OwnerLockedException.php index fc4530cb29e..ff51ebfc401 100644 --- a/lib/public/Files/Lock/OwnerLockedException.php +++ b/lib/public/Files/Lock/OwnerLockedException.php @@ -3,25 +3,8 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2022 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/>. - * + * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Files\Lock; diff --git a/lib/public/Files/LockNotAcquiredException.php b/lib/public/Files/LockNotAcquiredException.php index 4a26878cedf..93d861c248f 100644 --- a/lib/public/Files/LockNotAcquiredException.php +++ b/lib/public/Files/LockNotAcquiredException.php @@ -1,30 +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/> - * + * 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; @@ -42,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 aa760f53e96..43a771c07ce 100644 --- a/lib/public/Files/Mount/IMountManager.php +++ b/lib/public/Files/Mount/IMountManager.php @@ -1,31 +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 * @@ -33,7 +17,6 @@ namespace OCP\Files\Mount; * @since 8.2.0 */ interface IMountManager { - /** * Add a new mount * @@ -107,4 +90,14 @@ interface IMountManager { * @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 66144bc4360..8989a885fda 100644 --- a/lib/public/Files/Mount/IMountPoint.php +++ b/lib/public/Files/Mount/IMountPoint.php @@ -1,25 +1,9 @@ <?php + /** - * @copyright Copyright (c) 2016, ownCloud, Inc. - * - * @author Morris Jobke <hey@morrisjobke.de> - * @author Robin Appelman <robin@icewind.nl> - * @author szaimen <szaimen@e.mail.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\Mount; @@ -28,7 +12,6 @@ namespace OCP\Files\Mount; * @since 8.0.0 */ interface IMountPoint { - /** * get complete path to the mount point * @@ -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(); 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 b892d8e0a73..edef0a6157f 100644 --- a/lib/public/Files/Node.php +++ b/lib/public/Files/Node.php @@ -1,37 +1,17 @@ <?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/> - * + * 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\Lock\LockedException; use OCP\Files\Storage\IStorage; +use OCP\Lock\LockedException; /** * Interface Node @@ -145,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 @@ -263,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 bf5816448e9..f2a0b60a916 100644 --- a/lib/public/Files/NotEnoughSpaceException.php +++ b/lib/public/Files/NotEnoughSpaceException.php @@ -1,29 +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/> - * + * 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 0caf52d42a5..28edb082e81 100644 --- a/lib/public/Files/NotFoundException.php +++ b/lib/public/Files/NotFoundException.php @@ -1,29 +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/> - * + * 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 e69a9bf4f92..3b5cf637cb8 100644 --- a/lib/public/Files/NotPermittedException.php +++ b/lib/public/Files/NotPermittedException.php @@ -1,29 +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/> - * + * 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 2a4f806be46..c7c758eec11 100644 --- a/lib/public/Files/Notify/IChange.php +++ b/lib/public/Files/Notify/IChange.php @@ -1,25 +1,8 @@ <?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; @@ -29,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 dd819982f9e..09b3dbca919 100644 --- a/lib/public/Files/Notify/INotifyHandler.php +++ b/lib/public/Files/Notify/INotifyHandler.php @@ -1,24 +1,8 @@ <?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 e45880b69f4..b1bfae5fc00 100644 --- a/lib/public/Files/Notify/IRenameChange.php +++ b/lib/public/Files/Notify/IRenameChange.php @@ -1,24 +1,8 @@ <?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 924141a3d4b..35099ef8ba8 100644 --- a/lib/public/Files/ObjectStore/IObjectStore.php +++ b/lib/public/Files/ObjectStore/IObjectStore.php @@ -1,26 +1,9 @@ <?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; @@ -32,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 @@ -55,7 +37,7 @@ interface IObjectStore { * @throws \Exception when something goes wrong, message will be logged * @since 7.0.0 */ - public function writeObject($urn, $stream, string $mimetype = null); + 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 fd4a26808fb..68af12fd440 100644 --- a/lib/public/Files/ReservedWordException.php +++ b/lib/public/Files/ReservedWordException.php @@ -1,28 +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/> - * + * 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 4b3bbfd21fc..fa7ef4d1bb3 100644 --- a/lib/public/Files/Search/ISearchBinaryOperator.php +++ b/lib/public/Files/Search/ISearchBinaryOperator.php @@ -1,25 +1,8 @@ <?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; @@ -27,8 +10,19 @@ 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 8ebaeced304..ab298fa0a57 100644 --- a/lib/public/Files/Search/ISearchComparison.php +++ b/lib/public/Files/Search/ISearchComparison.php @@ -1,40 +1,66 @@ <?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 /** @@ -43,7 +69,7 @@ interface ISearchComparison extends ISearchOperator { * @return string * @since 12.0.0 */ - public function getType(); + public function getType(): string; /** * Get the name of the field to compare with @@ -53,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 1799b97c1ca..f6ae8edcbb1 100644 --- a/lib/public/Files/Search/ISearchOperator.php +++ b/lib/public/Files/Search/ISearchOperator.php @@ -1,24 +1,8 @@ <?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; diff --git a/lib/public/Files/Search/ISearchOrder.php b/lib/public/Files/Search/ISearchOrder.php index 3b9e6e6713a..e6e68849443 100644 --- a/lib/public/Files/Search/ISearchOrder.php +++ b/lib/public/Files/Search/ISearchOrder.php @@ -1,25 +1,8 @@ <?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; @@ -29,7 +12,14 @@ 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'; /** @@ -38,7 +28,7 @@ interface ISearchOrder { * @return string * @since 12.0.0 */ - public function getDirection(); + public function getDirection(): string; /** * The field to sort on @@ -46,7 +36,15 @@ 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 diff --git a/lib/public/Files/Search/ISearchQuery.php b/lib/public/Files/Search/ISearchQuery.php index 91c6f642566..1b400c56e5b 100644 --- a/lib/public/Files/Search/ISearchQuery.php +++ b/lib/public/Files/Search/ISearchQuery.php @@ -1,24 +1,8 @@ <?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; diff --git a/lib/public/Files/SimpleFS/ISimpleFile.php b/lib/public/Files/SimpleFS/ISimpleFile.php index 8f1921cb7cb..4e77299ab00 100644 --- a/lib/public/Files/SimpleFS/ISimpleFile.php +++ b/lib/public/Files/SimpleFS/ISimpleFile.php @@ -1,31 +1,15 @@ <?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; /** * This interface allows to manage simple files. @@ -37,58 +21,56 @@ use OCP\Files\NotPermittedException; * @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 @@ -96,15 +78,14 @@ 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 @@ -114,7 +95,7 @@ interface ISimpleFile { /** * 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 0159c41760b..95efc676688 100644 --- a/lib/public/Files/SimpleFS/ISimpleFolder.php +++ b/lib/public/Files/SimpleFS/ISimpleFolder.php @@ -1,25 +1,8 @@ <?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; @@ -38,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 @@ -47,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 @@ -76,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 fd590b66b31..6be8a1d47c9 100644 --- a/lib/public/Files/SimpleFS/ISimpleRoot.php +++ b/lib/public/Files/SimpleFS/ISimpleRoot.php @@ -1,25 +1,8 @@ <?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; @@ -35,8 +18,6 @@ interface ISimpleRoot { /** * Get the folder with name $name * - * @param string $name - * @return ISimpleFolder * @throws NotFoundException * @throws \RuntimeException * @since 11.0.0 @@ -56,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 590cb43e1d6..7849b8c879a 100644 --- a/lib/public/Files/SimpleFS/InMemoryFile.php +++ b/lib/public/Files/SimpleFS/InMemoryFile.php @@ -3,26 +3,8 @@ 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; @@ -36,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. @@ -64,7 +42,7 @@ class InMemoryFile implements ISimpleFile { * @inheritdoc * @since 16.0.0 */ - public function getName() { + public function getName(): string { return $this->name; } @@ -72,7 +50,7 @@ class InMemoryFile implements ISimpleFile { * @inheritdoc * @since 16.0.0 */ - public function getSize() { + public function getSize(): int|float { return strlen($this->contents); } @@ -80,7 +58,7 @@ class InMemoryFile implements ISimpleFile { * @inheritdoc * @since 16.0.0 */ - public function getETag() { + public function getETag(): string { return ''; } @@ -88,7 +66,7 @@ class InMemoryFile implements ISimpleFile { * @inheritdoc * @since 16.0.0 */ - public function getMTime() { + public function getMTime(): int { return time(); } @@ -96,7 +74,7 @@ class InMemoryFile implements ISimpleFile { * @inheritdoc * @since 16.0.0 */ - public function getContent() { + public function getContent(): string { return $this->contents; } @@ -104,7 +82,7 @@ class InMemoryFile implements ISimpleFile { * @inheritdoc * @since 16.0.0 */ - public function putContent($data) { + public function putContent($data): void { $this->contents = $data; } @@ -113,7 +91,7 @@ class InMemoryFile implements ISimpleFile { * * @since 16.0.0 */ - public function delete() { + public function delete(): void { // unimplemented for in memory files } @@ -121,7 +99,7 @@ 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); } diff --git a/lib/public/Files/Storage.php b/lib/public/Files/Storage.php deleted file mode 100644 index 0a1a504b137..00000000000 --- a/lib/public/Files/Storage.php +++ /dev/null @@ -1,466 +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/> - * - */ -// 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 - * - * @template T of IStorage - * @param string $class - * @psalm-param class-string<T> $class - * @return bool - * @since 7.0.0 - * @psalm-assert-if-true T $this - */ - public function instanceOfStorage($class); - - /** - * A custom storage implementation can return an url for direct download of a give file. - * - * For now the returned array can hold the parameter url - in future more attributes might follow. - * - * @param string $path - * @return array|bool - * @since 8.0.0 - */ - public function getDirectDownload($path); - - /** - * @param string $path the path of the target folder - * @param string $fileName the name of the file itself - * @return void - * @throws InvalidPathException - * @since 8.1.0 - */ - public function verifyPath($path, $fileName); - - /** - * @param IStorage $sourceStorage - * @param string $sourceInternalPath - * @param string $targetInternalPath - * @return bool - * @since 8.1.0 - */ - public function copyFromStorage(IStorage $sourceStorage, $sourceInternalPath, $targetInternalPath); - - /** - * @param IStorage $sourceStorage - * @param string $sourceInternalPath - * @param string $targetInternalPath - * @return bool - * @since 8.1.0 - */ - public function moveFromStorage(IStorage $sourceStorage, $sourceInternalPath, $targetInternalPath); - - /** - * @param string $path The path of the file to acquire the lock for - * @param int $type \OCP\Lock\ILockingProvider::LOCK_SHARED or \OCP\Lock\ILockingProvider::LOCK_EXCLUSIVE - * @param \OCP\Lock\ILockingProvider $provider - * @throws \OCP\Lock\LockedException - * @since 8.1.0 - */ - public function acquireLock($path, $type, ILockingProvider $provider); - - /** - * @param string $path The path of the file to acquire the lock for - * @param int $type \OCP\Lock\ILockingProvider::LOCK_SHARED or \OCP\Lock\ILockingProvider::LOCK_EXCLUSIVE - * @param \OCP\Lock\ILockingProvider $provider - * @throws \OCP\Lock\LockedException - * @since 8.1.0 - */ - public function releaseLock($path, $type, ILockingProvider $provider); - - /** - * @param string $path The path of the file to change the lock for - * @param int $type \OCP\Lock\ILockingProvider::LOCK_SHARED or \OCP\Lock\ILockingProvider::LOCK_EXCLUSIVE - * @param \OCP\Lock\ILockingProvider $provider - * @throws \OCP\Lock\LockedException - * @since 8.1.0 - */ - public function changeLock($path, $type, ILockingProvider $provider); - - /** - * Test a storage for availability - * - * @since 8.2.0 - * @return bool - */ - public function test(); - - /** - * @since 8.2.0 - * @return array [ available, last_checked ] - */ - public function getAvailability(); - - /** - * @since 8.2.0 - * @param bool $isAvailable - */ - public function setAvailability($isAvailable); - - 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 7b70aa3e47f..19951da2015 100644 --- a/lib/public/Files/Storage/IDisableEncryptionStorage.php +++ b/lib/public/Files/Storage/IDisableEncryptionStorage.php @@ -1,25 +1,8 @@ <?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; diff --git a/lib/public/Files/Storage/ILockingStorage.php b/lib/public/Files/Storage/ILockingStorage.php index 401a8de30bf..ceedf33ceab 100644 --- a/lib/public/Files/Storage/ILockingStorage.php +++ b/lib/public/Files/Storage/ILockingStorage.php @@ -1,24 +1,9 @@ <?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; @@ -36,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 18bcf3c6adc..063ff815581 100644 --- a/lib/public/Files/Storage/INotifyStorage.php +++ b/lib/public/Files/Storage/INotifyStorage.php @@ -1,25 +1,8 @@ <?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; @@ -31,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 index e074a48b403..29fbfacf831 100644 --- a/lib/public/Files/Storage/IReliableEtagStorage.php +++ b/lib/public/Files/Storage/IReliableEtagStorage.php @@ -2,23 +2,8 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2022 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: 2022 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Files\Storage; 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 f42eb81bfec..5f6c8a0e8a0 100644 --- a/lib/public/Files/Storage/IStorage.php +++ b/lib/public/Files/Storage/IStorage.php @@ -1,28 +1,9 @@ <?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/> - * + * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-FileCopyrightText: 2016 ownCloud, Inc. + * SPDX-License-Identifier: AGPL-3.0-only */ // use OCP namespace for all classes that are considered public. // This means that they should be used by apps instead of the internal Nextcloud classes @@ -42,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. @@ -66,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 @@ -357,51 +294,41 @@ interface IStorage { * Check if the storage is an instance of $class or is a wrapper for a storage that is an instance of $class * * @template T of IStorage - * @param string $class * @psalm-param class-string<T> $class * @return bool * @since 9.0.0 * @psalm-assert-if-true T $this */ - public function instanceOfStorage($class); + public function instanceOfStorage(string $class); /** * A custom storage implementation can return an url for direct download of a give file. * * For now the returned array can hold the parameter url - in future more attributes might follow. * - * @param string $path - * @return array|bool + * @return array|false * @since 9.0.0 */ - public function getDirectDownload($path); + public function getDirectDownload(string $path); /** - * @param string $path the path of the target folder - * @param string $fileName the name of the file itself * @return void * @throws InvalidPathException * @since 9.0.0 */ - public function verifyPath($path, $fileName); + public function verifyPath(string $path, string $fileName); /** - * @param IStorage $sourceStorage - * @param string $sourceInternalPath - * @param string $targetInternalPath * @return bool * @since 9.0.0 */ - public function copyFromStorage(IStorage $sourceStorage, $sourceInternalPath, $targetInternalPath); + public function copyFromStorage(IStorage $sourceStorage, string $sourceInternalPath, string $targetInternalPath); /** - * @param IStorage $sourceStorage - * @param string $sourceInternalPath - * @param string $targetInternalPath * @return bool * @since 9.0.0 */ - public function moveFromStorage(IStorage $sourceStorage, $sourceInternalPath, $targetInternalPath); + public function moveFromStorage(IStorage $sourceStorage, string $sourceInternalPath, string $targetInternalPath); /** * Test a storage for availability @@ -419,23 +346,28 @@ interface IStorage { /** * @since 9.0.0 - * @param bool $isAvailable + * @return void + */ + public function setAvailability(bool $isAvailable); + + /** + * @since 12.0.0 + * @since 31.0.0 moved from Storage to IStorage + * @return bool */ - public function setAvailability($isAvailable); + public function needsPartFile(); /** - * @param string $path path for which to retrieve the owner + * @return string|false * @since 9.0.0 */ - public function getOwner($path); + public function getOwner(string $path); /** - * @param string $path - * @param IStorage|null $storage * @return ICache * @since 9.0.0 */ - public function getCache($path = '', $storage = null); + public function getCache(string $path = '', ?IStorage $storage = null); /** * @return IPropagator @@ -460,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 846e4114497..24f87d2e775 100644 --- a/lib/public/Files/Storage/IStorageFactory.php +++ b/lib/public/Files/Storage/IStorageFactory.php @@ -1,26 +1,9 @@ <?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; @@ -36,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 f9122cd4b2c..b03f46ef2bc 100644 --- a/lib/public/Files/Storage/IWriteStreamStorage.php +++ b/lib/public/Files/Storage/IWriteStreamStorage.php @@ -3,26 +3,8 @@ 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; @@ -37,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 696792c8d43..d0115313a96 100644 --- a/lib/public/Files/StorageAuthException.php +++ b/lib/public/Files/StorageAuthException.php @@ -1,25 +1,9 @@ <?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; @@ -28,7 +12,6 @@ namespace OCP\Files; * @since 9.0.0 */ class StorageAuthException extends StorageNotAvailableException { - /** * StorageAuthException constructor. * @@ -36,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 e05b9217799..c38bd840d3e 100644 --- a/lib/public/Files/StorageBadConfigException.php +++ b/lib/public/Files/StorageBadConfigException.php @@ -1,25 +1,9 @@ <?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; @@ -28,7 +12,6 @@ namespace OCP\Files; * @since 9.0.0 */ class StorageBadConfigException extends StorageNotAvailableException { - /** * ExtStorageBadConfigException constructor. * @@ -36,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 d9a69e53edd..8629d8cee6e 100644 --- a/lib/public/Files/StorageConnectionException.php +++ b/lib/public/Files/StorageConnectionException.php @@ -1,25 +1,9 @@ <?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; @@ -28,7 +12,6 @@ namespace OCP\Files; * @since 9.0.0 */ class StorageConnectionException extends StorageNotAvailableException { - /** * StorageConnectionException constructor. * @@ -36,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 c59a703eee0..1109bf2790e 100644 --- a/lib/public/Files/StorageInvalidException.php +++ b/lib/public/Files/StorageInvalidException.php @@ -1,28 +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/> - * + * 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 f600ef80808..208c7de3238 100644 --- a/lib/public/Files/StorageNotAvailableException.php +++ b/lib/public/Files/StorageNotAvailableException.php @@ -1,34 +1,12 @@ <?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/> - * + * 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; @@ -36,15 +14,43 @@ 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; /** @@ -55,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 256f7e710a1..85201932d66 100644 --- a/lib/public/Files/StorageTimeoutException.php +++ b/lib/public/Files/StorageTimeoutException.php @@ -1,25 +1,9 @@ <?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; @@ -28,7 +12,6 @@ namespace OCP\Files; * @since 9.0.0 */ class StorageTimeoutException extends StorageNotAvailableException { - /** * StorageTimeoutException constructor. * @@ -36,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 bb913f6f16a..0636d1dc251 100644 --- a/lib/public/Files/Template/FileCreatedFromTemplateEvent.php +++ b/lib/public/Files/Template/FileCreatedFromTemplateEvent.php @@ -3,25 +3,8 @@ declare(strict_types=1); /** - * @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/>. - * + * SPDX-FileCopyrightText: 2021 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Files\Template; @@ -34,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; } /** @@ -54,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 81448a111de..6136bc4f1c0 100644 --- a/lib/public/Files/Template/ICustomTemplateProvider.php +++ b/lib/public/Files/Template/ICustomTemplateProvider.php @@ -3,25 +3,8 @@ declare(strict_types=1); /** - * @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/>. - * + * SPDX-FileCopyrightText: 2021 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Files\Template; @@ -34,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 a874ec6491a..df81bc5604e 100644 --- a/lib/public/Files/Template/ITemplateManager.php +++ b/lib/public/Files/Template/ITemplateManager.php @@ -3,26 +3,8 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2021 Julius Härtl <jus@bitgrid.net> - * - * @author John Molakvoæ <skjnldsv@protonmail.com> - * @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/>. - * + * SPDX-FileCopyrightText: 2021 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Files\Template; @@ -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 d71ef3b3655..7f01c2afa48 100644 --- a/lib/public/Files/Template/Template.php +++ b/lib/public/Files/Template/Template.php @@ -3,25 +3,8 @@ declare(strict_types=1); /** - * @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/>. - * + * SPDX-FileCopyrightText: 2021 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Files\Template; @@ -31,7 +14,6 @@ use OCP\Files\File; * @since 21.0.0 */ final class Template implements \JsonSerializable { - /** @var string */ private $templateType; /** @var string */ @@ -42,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 @@ -67,6 +51,37 @@ final class Template implements \JsonSerializable { } /** + * @param list<Field> $fields + * @since 30.0.0 + */ + public function setFields(array $fields): void { + $this->fields = $fields; + } + + /** + * @return array{ + * templateType: string, + * templateId: string, + * basename: string, + * etag: string, + * fileid: int, + * filename: string, + * lastmod: int, + * mime: string, + * size: int|float, + * type: string, + * hasPreview: bool, + * previewUrl: ?string, + * fields: list<array{ + * index: string, + * type: string, + * alias: ?string, + * tag: ?string, + * id: ?int, + * content?: string, + * checked?: bool, + * }>, + * } * @since 21.0.0 */ public function jsonSerialize(): array { @@ -82,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 26edf585869..809bd3d0bc2 100644 --- a/lib/public/Files/Template/TemplateFileCreator.php +++ b/lib/public/Files/Template/TemplateFileCreator.php @@ -3,26 +3,8 @@ declare(strict_types=1); /** - * @copyright Copyright (c) 2021 Julius Härtl <jus@bitgrid.net> - * - * @author John Molakvoæ <skjnldsv@protonmail.com> - * @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/>. - * + * SPDX-FileCopyrightText: 2021 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Files\Template; @@ -31,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; @@ -58,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; @@ -65,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 { @@ -104,7 +105,23 @@ 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(): array { return [ @@ -112,8 +129,10 @@ final class TemplateFileCreator implements \JsonSerializable { '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 1fb7cdc4787..7152b0e4210 100644 --- a/lib/public/Files/UnseekableException.php +++ b/lib/public/Files/UnseekableException.php @@ -1,28 +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/> - * + * 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; |