Nextcloud PHP API (stable18)

ICache

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:

  • Scanner: scans the storage and updates the cache where needed
  • Watcher: checks for changes made to the filesystem outside of the ownCloud instance and rescans files and folder when a change is detected
  • Updater: listens to changes made to the filesystem inside of the ownCloud instance and updates the cache where needed
  • ChangePropagator: updates the mtime and etags of parent folders whenever a change to the cache is made to the cache by the updater
Tags
since
9.0.0

Table of Contents

COMPLETE  = 3
NOT_FOUND  = 0
PARTIAL  = 1
SHALLOW  = 2
get()  : ICacheEntry|false
get the stored metadata of a file or folder
getFolderContents()  : \OCP\Files\Cache\ICacheEntry[]
get the metadata of all files stored in $folder
getFolderContentsById()  : \OCP\Files\Cache\ICacheEntry[]
get the metadata of all files stored in $folder
getId()  : int
get the file id for a file
getIncomplete()  : string|bool
find a folder in the cache which has not been fully scanned
getNumericStorageId()  : int
Get the numeric storage id for this cache's storage
getParentId()  : int
get the id of the parent folder of a file
getPathById()  : string|null
get the path of a file on this storage by it's file id
getStatus()  : int
Get the scan status of a file
inCache()  : bool
check if a file is available in the cache
insert()  : int
insert meta data for a new file or folder
move()  : mixed
Move a file or folder in the cache
moveFromCache()  : mixed
Move a file or folder in the cache
normalize()  : string
normalize the given path for usage in the cache
put()  : int
store meta data for a file or folder This will automatically call either insert or update depending on if the file exists
remove()  : mixed
remove a file or folder from the cache
search()  : \OCP\Files\Cache\ICacheEntry[]
search for files matching $pattern, files are matched if their filename matches the search pattern
searchByMime()  : \OCP\Files\Cache\ICacheEntry[]
search for files by mimetype
searchQuery()  : \OCP\Files\Cache\ICacheEntry[]
Search for files with a flexible query
update()  : mixed
update the metadata of an existing file or folder in the cache

Constants

COMPLETE

public mixed COMPLETE = 3

NOT_FOUND

public mixed NOT_FOUND = ""

PARTIAL

public mixed PARTIAL = 1

SHALLOW

public mixed SHALLOW = 2

Methods

get()

get the stored metadata of a file or folder

public get(mixed $file) : ICacheEntry|false
Parameters
$file : mixed
Tags
since
9.0.0
Return values
ICacheEntry|false

the cache entry or false if the file is not found in the cache

getFolderContents()

get the metadata of all files stored in $folder

public getFolderContents(string $folder) : \OCP\Files\Cache\ICacheEntry[]

Only returns files one level deep, no recursion

Parameters
$folder : string
Tags
since
9.0.0
Return values
\OCP\Files\Cache\ICacheEntry[]

getFolderContentsById()

get the metadata of all files stored in $folder

public getFolderContentsById(int $fileId) : \OCP\Files\Cache\ICacheEntry[]

Only returns files one level deep, no recursion

Parameters
$fileId : int

the file id of the folder

Tags
since
9.0.0
Return values
\OCP\Files\Cache\ICacheEntry[]

getId()

get the file id for a file

public getId(string $file) : int

A file id is a numeric id for a file or folder that's unique within an owncloud instance which stays the same for the lifetime of a file

File ids are easiest way for apps to store references to a file since unlike paths they are not affected by renames or sharing

Parameters
$file : string
Tags
since
9.0.0
Return values
int

getIncomplete()

find a folder in the cache which has not been fully scanned

public getIncomplete() : string|bool

If multiple incomplete folders are in the cache, the one with the highest id will be returned, 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

Tags
since
9.0.0
Return values
string|bool

the path of the folder or false when no folder matched

getNumericStorageId()

Get the numeric storage id for this cache's storage

public getNumericStorageId() : int
Tags
since
9.0.0
Return values
int

getParentId()

get the id of the parent folder of a file

public getParentId(string $file) : int
Parameters
$file : string
Tags
since
9.0.0
Return values
int

getPathById()

get the path of a file on this storage by it's file id

public getPathById(int $id) : string|null
Parameters
$id : int

the file id of the file or folder to search

Tags
since
9.0.0
Return values
string|null

the path of the file (relative to the storage) or null if a file with the given id does not exists within this cache

getStatus()

Get the scan status of a file

public getStatus(string $file) : int
  • ICache::NOT_FOUND: File is not in the cache
  • ICache::PARTIAL: File is not stored in the cache but some incomplete data is known
  • ICache::SHALLOW: The folder and it's direct children are in the cache but not all sub folders are fully scanned
  • ICache::COMPLETE: The file or folder, with all it's children) are fully scanned
Parameters
$file : string
Tags
since
9.0.0
Return values
int

ICache::NOT_FOUND, ICache::PARTIAL, ICache::SHALLOW or ICache::COMPLETE

inCache()

check if a file is available in the cache

public inCache(string $file) : bool
Parameters
$file : string
Tags
since
9.0.0
Return values
bool

insert()

insert meta data for a new file or folder

public insert(string $file, array $data) : int
Parameters
$file : string
$data : array
Tags
throws
RuntimeException
since
9.0.0
Return values
int

file id

move()

Move a file or folder in the cache

public move(string $source, string $target) : mixed
Parameters
$source : string
$target : string
Tags
since
9.0.0
Return values
mixed

moveFromCache()

Move a file or folder in the cache

public moveFromCache(ICache $sourceCache, string $sourcePath, string $targetPath) : mixed

Note that this should make sure the entries are removed from the source cache

Parameters
$sourceCache : ICache
$sourcePath : string
$targetPath : string
Tags
throws
DatabaseException
since
9.0.0
Return values
mixed

normalize()

normalize the given path for usage in the cache

public normalize(string $path) : string
Parameters
$path : string
Tags
since
9.0.0
Return values
string

put()

store meta data for a file or folder This will automatically call either insert or update depending on if the file exists

public put(string $file, array $data) : int
Parameters
$file : string
$data : array
Tags
throws
RuntimeException
since
9.0.0
Return values
int

file id

remove()

remove a file or folder from the cache

public remove(string $file) : mixed

when removing a folder from the cache all files and folders inside the folder will be removed as well

Parameters
$file : string
Tags
since
9.0.0
Return values
mixed

search for files matching $pattern, files are matched if their filename matches the search pattern

public search(string $pattern) : \OCP\Files\Cache\ICacheEntry[]
Parameters
$pattern : string

the search pattern using SQL search syntax (e.g. '%searchstring%')

Tags
since
9.0.0
deprecated
9.0.0

due to lack of pagination, not all backends might implement this

Return values
\OCP\Files\Cache\ICacheEntry[]

an array of cache entries where the name matches the search pattern

searchByMime()

search for files by mimetype

public searchByMime(string $mimetype) : \OCP\Files\Cache\ICacheEntry[]
Parameters
$mimetype : string

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/*')

Tags
since
9.0.0
deprecated
9.0.0

due to lack of pagination, not all backends might implement this

Return values
\OCP\Files\Cache\ICacheEntry[]

an array of cache entries where the mimetype matches the search

searchQuery()

Search for files with a flexible query

public searchQuery(ISearchQuery $query) : \OCP\Files\Cache\ICacheEntry[]
Parameters
$query : ISearchQuery
Tags
throws
InvalidArgumentException

if the cache is unable to perform the query

since
12.0.0
Return values
\OCP\Files\Cache\ICacheEntry[]

update()

update the metadata of an existing file or folder in the cache

public update(int $id, array $data) : mixed
Parameters
$id : int

the fileid of the existing file or folder

$data : array

[$key => $value] the metadata to update, only the fields provided in the array will be updated, non-provided values will remain unchanged

Tags
since
9.0.0
Return values
mixed

Search results