Nextcloud PHP API (stable18)

ITags

Class for easily tagging objects by their id

A tag can be e.g. 'Family', 'Work', 'Chore', 'Special Occation' or anything else that is either parsed from a vobject or that the user chooses to add. Tag names are not case-sensitive, but will be saved with the case they are entered in. If a user already has a tag 'family' for a type, and tries to add a tag named 'Family' it will be silently ignored.

Tags
since
6.0.0

Table of Contents

add()  : int|false
Add a new tag.
addMultiple()  : bool
Add a list of new tags.
addToFavorites()  : bool
Add an object to favorites
delete()  : bool
Delete tags from the database
getFavorites()  : array|false
Get favorites for an object type
getIdsForTag()  : array|false
Get a list of items tagged with $tag.
getTag()  : array|false
Returns an array mapping a given tag's properties to its values: ['id' => 0, 'name' = 'Tag', 'owner' = 'User', 'type' => 'tagtype']
getTags()  : array
Get the tags for a specific user.
getTagsForObjects()  : array|bool
Get a list of tags for the given item ids.
hasTag()  : bool
Checks whether a tag is already saved.
isEmpty()  : bool
Check if any tags are saved for this type and user.
purgeObjects()  : bool
Delete tag/object relations from the db
removeFromFavorites()  : bool
Remove an object from favorites
rename()  : bool
Rename tag.
tagAs()  : bool
Creates a tag/object relation.
unTag()  : bool
Delete single tag/object relation from the db
userHasTag()  : bool
Checks whether a tag is saved for the given user, disregarding the ones shared with him or her.

Methods

add()

Add a new tag.

public add(string $name) : int|false
Parameters
$name : string

A string with a name of the tag

Tags
since
6.0.0
Return values
int|false

the id of the added tag or false if it already exists.

addMultiple()

Add a list of new tags.

public addMultiple(string[] $names[, bool $sync = false ][, int|null $id = null ]) : bool
Parameters
$names : string[]

A string with a name or an array of strings containing the name(s) of the to add.

$sync : bool = false

When true, save the tags

$id : int|null = null

int Optional object id to add to this|these tag(s)

Tags
since
6.0.0
Return values
bool

Returns false on error.

addToFavorites()

Add an object to favorites

public addToFavorites(int $objid) : bool
Parameters
$objid : int

The id of the object

Tags
since
6.0.0
Return values
bool

delete()

Delete tags from the database

public delete(string[]|int[] $names) : bool
Parameters
$names : string[]|int[]

An array of tags (names or IDs) to delete

Tags
since
6.0.0
Return values
bool

Returns false on error

getFavorites()

Get favorites for an object type

public getFavorites() : array|false
Tags
since
6.0.0
Return values
array|false

An array of object ids.

getIdsForTag()

Get a list of items tagged with $tag.

public getIdsForTag(string|int $tag) : array|false

Throws an exception if the tag could not be found.

Parameters
$tag : string|int

Tag id or name.

Tags
since
6.0.0
Return values
array|false

An array of object ids or false on error.

getTag()

Returns an array mapping a given tag's properties to its values: ['id' => 0, 'name' = 'Tag', 'owner' = 'User', 'type' => 'tagtype']

public getTag(string $id) : array|false
Parameters
$id : string

The ID of the tag that is going to be mapped

Tags
since
8.0.0
Return values
array|false

getTags()

Get the tags for a specific user.

public getTags() : array

This returns an array with id/name maps: [ ['id' => 0, 'name' = 'First tag'], ['id' => 1, 'name' = 'Second tag'], ]

Tags
since
6.0.0
Return values
array

getTagsForObjects()

Get a list of tags for the given item ids.

public getTagsForObjects(array $objIds) : array|bool

This returns an array with object id / tag names: [ 1 => array('First tag', 'Second tag'), 2 => array('Second tag'), 3 => array('Second tag', 'Third tag'), ]

Parameters
$objIds : array

item ids

Tags
since
8.0.0
Return values
array|bool

with object id as key and an array of tag names as value or false if an error occurred

hasTag()

Checks whether a tag is already saved.

public hasTag(string $name) : bool
Parameters
$name : string

The name to check for.

Tags
since
6.0.0
Return values
bool

isEmpty()

Check if any tags are saved for this type and user.

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

purgeObjects()

Delete tag/object relations from the db

public purgeObjects(array $ids) : bool
Parameters
$ids : array

The ids of the objects

Tags
since
6.0.0
Return values
bool

Returns false on error.

removeFromFavorites()

Remove an object from favorites

public removeFromFavorites(int $objid) : bool
Parameters
$objid : int

The id of the object

Tags
since
6.0.0
Return values
bool

rename()

Rename tag.

public rename(string|int $from, string $to) : bool
Parameters
$from : string|int

The name or ID of the existing tag

$to : string

The new name of the tag.

Tags
since
6.0.0
Return values
bool

tagAs()

Creates a tag/object relation.

public tagAs(int $objid, string $tag) : bool
Parameters
$objid : int

The id of the object

$tag : string

The id or name of the tag

Tags
since
6.0.0
Return values
bool

Returns false on database error.

unTag()

Delete single tag/object relation from the db

public unTag(int $objid, string $tag) : bool
Parameters
$objid : int

The id of the object

$tag : string

The id or name of the tag

Tags
since
6.0.0
Return values
bool

userHasTag()

Checks whether a tag is saved for the given user, disregarding the ones shared with him or her.

public userHasTag(string $name, string $user) : bool
Parameters
$name : string

The tag name to check for.

$user : string

The user whose tags are to be checked.

Tags
since
8.0.0
Return values
bool

Search results