Nextcloud PHP API (master)

Folder extends Node

Interface Node

Tags
since
6.0.0

Table of Contents

BLACKLIST_FILES_REGEX  = '\\.(part|filepart)$'
MIMETYPE_FOLDER  = 'httpd/unix-directory'
SPACE_NOT_COMPUTED  = -1
SPACE_UNKNOWN  = -2
SPACE_UNLIMITED  = -3
TYPE_FILE  = 'file'
TYPE_FOLDER  = 'dir'
changeLock()  : mixed
Check the type of an existing lock.
copy()  : Node
Copy the file or folder to a new location
delete()  : void
Delete the file or folder
get()  : Node
Get the node at $path
getById()  : array<string|int, Node>
get a file or folder inside the folder by it's internal id
getChecksum()  : string
Get the stored checksum(s) for this file
getCreationTime()  : int
Get the creation date as unix timestamp
getDirectoryListing()  : array<string|int, Node>
get the content of this directory
getEtag()  : string
Get the Etag of the file or folder
getExtension()  : string
Get the extension of the file
getFreeSpace()  : int
Get the amount of free space inside the folder
getFullPath()  : string
Get the full path of an item in the folder within owncloud's filesystem
getId()  : int|null
Get the file id of the file or folder
getInternalPath()  : string
Get the path relative to the storage
getMimePart()  : string
Get the first part of the mimetype of the file or folder i.e. 'image'
getMimetype()  : string
Get the full mimetype of the file or folder i.e. 'image/png'
getMountPoint()  : IMountPoint
Get the mountpoint the file belongs to
getMTime()  : int
Get the modified date of the file or folder as unix timestamp
getMtime()  : int
Get the last modified date as timestamp for the file or folder
getName()  : string
Get the name of the file or folder
getNonExistingName()  : string
Add a suffix to the name in case the file exists
getOwner()  : IUser|null
Get the owner of the file
getParent()  : Folder
Get the parent folder of the file or folder
getPath()  : string
Get the absolute path
getPermissions()  : int
Get the permissions of the file or folder as bitmasked combination of the following constants \OCP\Constants::PERMISSION_CREATE \OCP\Constants::PERMISSION_READ \OCP\Constants::PERMISSION_UPDATE \OCP\Constants::PERMISSION_DELETE \OCP\Constants::PERMISSION_SHARE \OCP\Constants::PERMISSION_ALL
getRecent()  : array<string|int, Node>
getRelativePath()  : string|null
Get the path of an item in the folder relative to the folder
getSize()  : int|float
Get the size in bytes for the file or folder
getStorage()  : IStorage
Get the storage the file or folder is storage on
getType()  : string
Check whether this is a file or a folder
getUploadTime()  : int
Get the upload date as unix timestamp
isCreatable()  : bool
Check if new files or folders can be created within the folder
isDeletable()  : bool
Check if a file or folder can be deleted
isEncrypted()  : bool
Check whether the file is encrypted
isMounted()  : bool
Check if a file or folder is mounted
isReadable()  : bool
Check if the file or folder is readable
isShareable()  : bool
Check if a file or folder can be shared
isShared()  : bool
Check if a file or folder is shared
isSubNode()  : bool
check if a node is a (grand-)child of the folder
isUpdateable()  : bool
Check if a file is writable
lock()  : mixed
Acquire a lock on this file or folder.
move()  : Node
Move the file or folder to a new location
newFile()  : File
Create a new file
newFolder()  : Folder
Create a new folder
nodeExists()  : bool
Check if a file or folder exists in the folder
search()  : array<string|int, Node>
search for files with the name matching $query
searchByMime()  : array<string|int, Node>
search for files by mimetype $mimetype can either be a full mimetype (image/png) or a wildcard mimetype (image)
searchBySystemTag()  : array<string|int, Node>
search for files by system tag
searchByTag()  : array<string|int, Node>
search for files by tag
stat()  : array<string|int, mixed>
Get metadata of the file or folder The returned array contains the following values: - mtime - size
touch()  : void
Change the modified date of the file or folder If $mtime is omitted the current time will be used
unlock()  : mixed
Release an existing lock.

Constants

BLACKLIST_FILES_REGEX

public mixed BLACKLIST_FILES_REGEX = '\\.(part|filepart)$'
Tags
const

\OCP\Files\FileInfo::BLACKLIST_FILES_REGEX Return regular expression to test filenames against (blacklisting)

since
12.0.0

MIMETYPE_FOLDER

public mixed MIMETYPE_FOLDER = 'httpd/unix-directory'
Tags
since
9.1.0

SPACE_NOT_COMPUTED

public mixed SPACE_NOT_COMPUTED = -1
Tags
const

\OCP\Files\FileInfo::SPACE_NOT_COMPUTED Return value for a not computed space value

since
8.0.0

SPACE_UNKNOWN

public mixed SPACE_UNKNOWN = -2
Tags
const

\OCP\Files\FileInfo::SPACE_UNKNOWN Return value for unknown space value

since
8.0.0

SPACE_UNLIMITED

public mixed SPACE_UNLIMITED = -3
Tags
const

\OCP\Files\FileInfo::SPACE_UNLIMITED Return value for unlimited space

since
8.0.0

TYPE_FILE

public mixed TYPE_FILE = 'file'
Tags
since
7.0.0

TYPE_FOLDER

public mixed TYPE_FOLDER = 'dir'
Tags
since
7.0.0

Methods

changeLock()

Check the type of an existing lock.

public changeLock(int $targetType) : mixed

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.

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.

Parameters
$targetType : int

\OCP\Lock\ILockingProvider::LOCK_SHARED or \OCP\Lock\ILockingProvider::LOCK_EXCLUSIVE

Tags
throws
LockedException
since
9.1.0
Return values
mixed

copy()

Copy the file or folder to a new location

public copy(string $targetPath) : Node
Parameters
$targetPath : string

the absolute target path

Tags
since
6.0.0
Return values
Node

get()

Get the node at $path

public get(string $path) : Node
Parameters
$path : string

relative path of the file or folder

Tags
throws
NotFoundException
since
6.0.0
Return values
Node

getById()

get a file or folder inside the folder by it's internal id

public getById(int $id) : array<string|int, Node>

This method could return multiple entries. For example once the file/folder is shared or mounted (files_external) to the user multiple times.

Parameters
$id : int
Tags
since
6.0.0
Return values
array<string|int, Node>

getChecksum()

Get the stored checksum(s) for this file

public getChecksum() : string

Checksums are stored in the format TYPE:CHECKSUM, here may be multiple checksums separated by a single space e.g. MD5:d3b07384d113edec49eaa6238ad5ff00 SHA1:f1d2d2f924e986ac86fdf7b36c94bcdf32beec15

Tags
since
9.0.0
Return values
string

getCreationTime()

Get the creation date as unix timestamp

public getCreationTime() : int

If the creation time is not known, 0 will be returned

creation time is not set automatically by the server and is generally only available for files uploaded by the sync clients

Tags
since
18.0.0
Return values
int

getDirectoryListing()

get the content of this directory

public getDirectoryListing() : array<string|int, Node>
Tags
throws
NotFoundException
since
6.0.0
Return values
array<string|int, Node>

getEtag()

Get the Etag of the file or folder

public getEtag() : string
Tags
since
7.0.0
Return values
string

getExtension()

Get the extension of the file

public getExtension() : string
Tags
since
15.0.0
Return values
string

getFreeSpace()

Get the amount of free space inside the folder

public getFreeSpace() : int
Tags
since
6.0.0
Return values
int

getFullPath()

Get the full path of an item in the folder within owncloud's filesystem

public getFullPath(string $path) : string
Parameters
$path : string

relative path of an item in the folder

Tags
throws
NotPermittedException
since
6.0.0
Return values
string

getId()

Get the file id of the file or folder

public getId() : int|null
Tags
since
7.0.0
Return values
int|null

getInternalPath()

Get the path relative to the storage

public getInternalPath() : string
Tags
since
7.0.0
Return values
string

getMimePart()

Get the first part of the mimetype of the file or folder i.e. 'image'

public getMimePart() : string
Tags
since
7.0.0
Return values
string

getMimetype()

Get the full mimetype of the file or folder i.e. 'image/png'

public getMimetype() : string
Tags
since
7.0.0
Return values
string

getMtime()

Get the last modified date as timestamp for the file or folder

public getMtime() : int
Tags
since
7.0.0
Return values
int

getName()

Get the name of the file or folder

public getName() : string
Tags
since
7.0.0
Return values
string

getNonExistingName()

Add a suffix to the name in case the file exists

public getNonExistingName(string $name) : string
Parameters
$name : string
Tags
throws
NotPermittedException
since
8.1.0
Return values
string

getOwner()

Get the owner of the file

public getOwner() : IUser|null
Tags
since
9.0.0
Return values
IUser|null

getParent()

Get the parent folder of the file or folder

public getParent() : Folder
Tags
since
6.0.0
Return values
Folder

getPath()

Get the absolute path

public getPath() : string
Tags
since
7.0.0
Return values
string

getPermissions()

Get the permissions of the file or folder as bitmasked combination of the following constants \OCP\Constants::PERMISSION_CREATE \OCP\Constants::PERMISSION_READ \OCP\Constants::PERMISSION_UPDATE \OCP\Constants::PERMISSION_DELETE \OCP\Constants::PERMISSION_SHARE \OCP\Constants::PERMISSION_ALL

public getPermissions() : int
Tags
since
7.0.0
  • namespace of constants has changed in 8.0.0
Return values
int

getRecent()

public getRecent(int $limit, int $offset) : array<string|int, Node>
Parameters
$limit : int
$offset : int
Tags
since
9.1.0
Return values
array<string|int, Node>

getRelativePath()

Get the path of an item in the folder relative to the folder

public getRelativePath(string $path) : string|null
Parameters
$path : string

absolute path of an item in the folder

Tags
throws
NotFoundException
since
6.0.0
Return values
string|null

getSize()

Get the size in bytes for the file or folder

public getSize([bool $includeMounts = true ]) : int|float
Parameters
$includeMounts : bool = true

whether or not to include the size of any sub mounts, since 16.0.0

Tags
since
7.0.0
Return values
int|float

getStorage()

Get the storage the file or folder is storage on

public getStorage() : IStorage
Tags
since
7.0.0
Return values
IStorage

getType()

Check whether this is a file or a folder

public getType() : string
Tags
since
7.0.0
Return values
string

\OCP\Files\FileInfo::TYPE_FILE|\OCP\Files\FileInfo::TYPE_FOLDER

getUploadTime()

Get the upload date as unix timestamp

public getUploadTime() : int

If the upload time is not known, 0 will be returned

Upload time will be set automatically by the server for files uploaded over DAV files created by Nextcloud apps generally do not have an the upload time set

Tags
since
18.0.0
Return values
int

isCreatable()

Check if new files or folders can be created within the folder

public isCreatable() : bool
Tags
since
6.0.0
Return values
bool

isDeletable()

Check if a file or folder can be deleted

public isDeletable() : bool
Tags
since
7.0.0
Return values
bool

isEncrypted()

Check whether the file is encrypted

public isEncrypted() : bool
Tags
since
7.0.0
Return values
bool

isMounted()

Check if a file or folder is mounted

public isMounted() : bool
Tags
since
7.0.0
Return values
bool

isReadable()

Check if the file or folder is readable

public isReadable() : bool
Tags
since
7.0.0
Return values
bool

isShareable()

Check if a file or folder can be shared

public isShareable() : bool
Tags
since
7.0.0
Return values
bool

isShared()

Check if a file or folder is shared

public isShared() : bool
Tags
since
7.0.0
Return values
bool

isSubNode()

check if a node is a (grand-)child of the folder

public isSubNode(Node $node) : bool
Parameters
$node : Node
Tags
since
6.0.0
Return values
bool

isUpdateable()

Check if a file is writable

public isUpdateable() : bool
Tags
since
7.0.0
Return values
bool

lock()

Acquire a lock on this file or folder.

public lock(int $type) : mixed

A shared (read) lock will prevent any exclusive (write) locks from being created but any number of shared locks can be active at the same time. An exclusive lock will prevent any other lock from being created (both shared and exclusive).

A locked exception will be thrown if any conflicting lock already exists

Note that this uses mandatory locking, if you acquire an exclusive lock on a file it will block all other operations for that file, even within the same php process.

Acquiring any lock on a file will also create a shared lock on all parent folders of that file.

Note that in most cases you won't need to manually manage the locks for any files you're working with, any filesystem operation will automatically acquire the relevant locks for that operation.

Parameters
$type : int

\OCP\Lock\ILockingProvider::LOCK_SHARED or \OCP\Lock\ILockingProvider::LOCK_EXCLUSIVE

Tags
throws
LockedException
since
9.1.0
Return values
mixed

newFile()

Create a new file

public newFile(string $path[, string|resource|null $content = null ]) : File
Parameters
$path : string

relative path of the new file

$content : string|resource|null = null

content for the new file, since 19.0.0

Tags
throws
NotPermittedException
since
6.0.0
Return values
File

newFolder()

Create a new folder

public newFolder(string $path) : Folder
Parameters
$path : string

relative path of the new folder

Tags
throws
NotPermittedException
since
6.0.0
Return values
Folder

nodeExists()

Check if a file or folder exists in the folder

public nodeExists(string $path) : bool
Parameters
$path : string

relative path of the file or folder

Tags
since
6.0.0
Return values
bool

search for files with the name matching $query

public search(string|ISearchQuery $query) : array<string|int, Node>
Parameters
$query : string|ISearchQuery
Tags
since
6.0.0
Return values
array<string|int, Node>

searchByMime()

search for files by mimetype $mimetype can either be a full mimetype (image/png) or a wildcard mimetype (image)

public searchByMime(string $mimetype) : array<string|int, Node>
Parameters
$mimetype : string
Tags
since
6.0.0
Return values
array<string|int, Node>

searchBySystemTag()

search for files by system tag

public searchBySystemTag(string $tagName, string $userId, int $limit, int $offset) : array<string|int, Node>
Parameters
$tagName : string
$userId : string

user id to ensure access on returned nodes

$limit : int
$offset : int
Tags
since
28.0.0
Return values
array<string|int, Node>

searchByTag()

search for files by tag

public searchByTag(string|int $tag, string $userId) : array<string|int, Node>
Parameters
$tag : string|int

tag name or tag id

$userId : string

owner of the tags

Tags
since
8.0.0
Return values
array<string|int, Node>

stat()

Get metadata of the file or folder The returned array contains the following values: - mtime - size

public stat() : array<string|int, mixed>
Tags
since
6.0.0
Return values
array<string|int, mixed>

touch()

Change the modified date of the file or folder If $mtime is omitted the current time will be used

public touch([int $mtime = null ]) : void
Parameters
$mtime : int = null

(optional) modified date as unix timestamp

Tags
throws
InvalidPathException
throws
NotFoundException
throws
NotPermittedException
since
6.0.0
Return values
void

unlock()

Release an existing lock.

public unlock(int $type) : mixed

This will also free up the shared locks on any parent folder that were automatically acquired when locking the file.

Note that this method will not give any sort of error when trying to free a lock that doesn't exist.

Parameters
$type : int

\OCP\Lock\ILockingProvider::LOCK_SHARED or \OCP\Lock\ILockingProvider::LOCK_EXCLUSIVE

Tags
throws
LockedException
since
9.1.0
Return values
mixed

Search results