Nextcloud PHP API (master)

ICache
in

Metadata cache for a storage

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
  • Updater: listens to changes made to the filesystem inside of the Nextcloud instance and updates the cache where needed
  • ChangePropagator: updates the mtime and etags of parent folders whenever a change to the cache is made to the cache by the updater
Tags
since
9.0.0

Table of Contents

Constants

COMPLETE  = 3
NOT_FOUND  = 0
PARTIAL  = 1
SHALLOW  = 2

Methods

copyFromCache()  : int
Copy a file or folder in the cache
get()  : ICacheEntry|false
get the stored metadata of a file or folder
getCacheEntryFromSearchResult()  : ICacheEntry|null
Construct a cache entry from a search result row *if* the entry belongs to this storage.
getFolderContents()  : array<string|int, ICacheEntry>
get the metadata of all files stored in $folder
getFolderContentsById()  : array<string|int, ICacheEntry>
get the metadata of all files stored in $folder
getId()  : int
get the file id for a file
getIncomplete()  : string|false
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
getQueryFilterForStorage()  : ISearchOperator
Get the query expression required to filter files within this storage.
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()  : array<string|int, ICacheEntry>
search for files matching $pattern, files are matched if their filename matches the search pattern
searchByMime()  : array<string|int, ICacheEntry>
search for files by mimetype
searchQuery()  : array<string|int, 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
Tags
since
9.0.0

NOT_FOUND

public mixed NOT_FOUND = 0
Tags
since
9.0.0

PARTIAL

public mixed PARTIAL = 1
Tags
since
9.0.0

SHALLOW

public mixed SHALLOW = 2
Tags
since
9.0.0

Methods

copyFromCache()

Copy a file or folder in the cache

public copyFromCache(ICache $sourceCache, ICacheEntry $sourceEntry, string $targetPath) : int
Parameters
$sourceCache : ICache
$sourceEntry : ICacheEntry
$targetPath : string
Tags
since
22.0.0
Return values
int —

fileid of copied entry

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

getCacheEntryFromSearchResult()

Construct a cache entry from a search result row *if* the entry belongs to this storage.

public getCacheEntryFromSearchResult(ICacheEntry $rawEntry) : ICacheEntry|null

This method will be called for every item in the search results, including results from different storages. It's the responsibility of this method to return null for all results that don't belong to this storage.

Additionally some implementations might need to further process the resulting entry such as modifying the path or permissions of the result.

Parameters
$rawEntry : ICacheEntry
Tags
since
22.0.0
Return values
ICacheEntry|null

getFolderContents()

get the metadata of all files stored in $folder

public getFolderContents(string $folder) : array<string|int, ICacheEntry>

Only returns files one level deep, no recursion

Parameters
$folder : string
Tags
since
9.0.0
Return values
array<string|int, ICacheEntry>

getFolderContentsById()

get the metadata of all files stored in $folder

public getFolderContentsById(int $fileId) : array<string|int, 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
array<string|int, 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 Nextcloud instance which stays the same for the lifetime of a file

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

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|false

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|false —

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

getQueryFilterForStorage()

Get the query expression required to filter files within this storage.

public getQueryFilterForStorage() : ISearchOperator

In the most basic case this is just comparing the storage id but storage wrappers can add additional expressions to filter down things further

Tags
since
22.0.0
Return values
ISearchOperator

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<string|int, mixed> $data) : int
Parameters
$file : string
$data : array<string|int, mixed>
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

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

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<string|int, mixed> $data) : int
Parameters
$file : string
$data : array<string|int, mixed>
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

search()

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

public search(string $pattern) : array<string|int, 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
array<string|int, ICacheEntry> —

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

searchByMime()

search for files by mimetype

public searchByMime(string $mimetype) : array<string|int, 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
array<string|int, ICacheEntry> —

an array of cache entries where the mimetype matches the search

searchQuery()

Search for files with a flexible query

public searchQuery(ISearchQuery $query) : array<string|int, ICacheEntry>
Parameters
$query : ISearchQuery
Tags
throws
InvalidArgumentException

if the cache is unable to perform the query

since
12.0.0
Return values
array<string|int, ICacheEntry>

update()

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

public update(int $id, array<string|int, mixed> $data) : mixed
Parameters
$id : int

the fileid of the existing file or folder

$data : array<string|int, mixed>

[$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 

        

        
    




    

    

                                

                

                            
    

        On this page

        
    


                

                            

            

    

        

            
Search results