diff options
Diffstat (limited to 'lib/public/Files/Storage/IStorage.php')
| -rw-r--r-- | lib/public/Files/Storage/IStorage.php | 218 |
1 files changed, 81 insertions, 137 deletions
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; } |