Documentation

Horde_Share_Kolab extends Horde_Share_Base
in package

Horde_Share_Kolab:: provides the Kolab backend for the horde share driver.

Copyright 2004-2017 Horde LLC (http://www.horde.org/)

See the enclosed file LICENSE for license information (LGPL). If you did not receive this file, see http://www.horde.org/licenses/lgpl21.

Tags
category

Horde

author

Stuart Binge omicron@mighty.co.za

author

Gunnar Wrobel wrobel@pardus.de

license

http://www.horde.org/licenses/lgpl21 LGPL 2.1

Table of Contents

VERSION  = 1
$_app  : string
The application we're managing shares for.
$_cache  : array<string|int, mixed>
A cache of all shares that have been retrieved, so we don't hit the backend again and again for them.
$_callbacks  : array<string|int, mixed>
Configured callbacks. We currently support: <pre> add - Called immediately before a new share is added. Receives the share object as a parameter.
$_groups  : Horde_Group_Base
The Horde_Group driver
$_listcache  : array<string|int, mixed>
Cache used for listShares().
$_logger  : Horde_Log_Logger
Logger
$_permsObject  : Horde_Perms_Base
The Horde_Perms object
$_root  : mixed
The root of the Share tree.
$_shareCallback  : callable
A callback that is passed to the share objects for setting the objects' Horde_Share object.
$_shareMap  : array<string|int, mixed>
Id-name-map of already cached share objects.
$_shareObject  : string
The Horde_Share_Object subclass to instantiate objects as
$_sortList  : array<string|int, mixed>
A list of objects that we're currently sorting, for reference during the sorting algorithm.
$_user  : string
The current user
$_id_map  : array<string|int, mixed>
A map of IDs to folder names.
$_storage  : Horde_Kolab_Storage
The Kolab storage handler
$_type  : string
The folder type in the storage backend.
__construct()  : mixed
Constructor.
addCallback()  : mixed
Add a callback to the collection
addShare()  : mixed
Adds a share to the shares system.
constructFolderName()  : string
Construct the Kolab storage folder name based on the share name and owner attributes.
constructId()  : string
Construct the ID from the owner name and the folder subpath.
countShares()  : int
Returns the count of all shares that $userid has access to.
deleteAcl()  : null
Delete Kolab specific access rights for a share.
exists()  : bool
Checks if a share name exists in the system.
expireListCache()  : mixed
Expire the current list cache. This would be needed anytime a share is either added, deleted, had a change in owner, parent, or perms.
fromHash()  : Horde_Share_Object
Adds a share created from a hash.
getAcl()  : An
Retrieve the Kolab specific access rights for a share.
getApp()  : string
Returns the application we're managing shares for.
getFolderNameElements()  : array<string|int, mixed>
Retrieve namespace information for a folder name.
getList()  : Horde_Kolab_Storage_List
Return the Kolab storage folder list handler.
getListCache()  : array<string|int, mixed>
Returns the share's list cache.
getPermissions()  : mixed
Finds out what rights the given user has to this object.
getPermsObject()  : Horde_Perms_Base
Getter for Horde_Perms object
getShare()  : Horde_Share_Object
Returns a Horde_Share_Object object corresponding to the given share name, with the details retrieved appropriately.
getShareById()  : Horde_Share_Object
Returns a Horde_Share_Object object corresponding to the given unique ID, with the details retrieved appropriately.
getShares()  : array<string|int, mixed>
Returns an array of Horde_Share_Object objects corresponding to the given set of unique IDs, with the details retrieved appropriately.
getStorage()  : Horde_Kolab_Storage
Return the Kolab storage backend associated with this driver.
getType()  : string
Return the type of folder this share driver will access in the Kolab storage backend (depends on the application calling the share driver).
idExists()  : bool
Check that a share id exists in the system.
initShareObject()  : mixed
(Re)connects the share object to this share driver.
listAllShares()  : array<string|int, mixed>
Lists *all* shares for the current app/share, regardless of permissions.
listShares()  : array<string|int, mixed>
Returns an array of all shares that $userid has access to.
listSystemShares()  : array<string|int, mixed>
Returns an array of all system shares.
newShare()  : Horde_Share_Object
Returns a new share object.
removeShare()  : mixed
Removes a share from the shares system permanently.
renameShare()  : mixed
Renames a share in the shares system.
resetCache()  : mixed
Resets the internal caches.
runCallback()  : mixed
Give public access to call the share callbacks. Needed to run the callbacks from the Horde_Share_Object objects.
save()  : null
Save share data to the storage backend.
setAcl()  : null
Set the Kolab specific access rights for a share.
setListCache()  : mixed
Set the list cache.
setLogger()  : mixed
Set a logger object.
setShareCallback()  : mixed
setShareClass()  : mixed
Set the class type to use for creating share objects.
setStorage()  : null
Set the Kolab storage backend.
toDriverCharset()  : mixed
Convert TO the storage driver's charset. Individual share objects should implement this method if needed.
_addShare()  : mixed
Adds a share to the shares system.
_exists()  : bool
Checks if a share exists in the system.
_getShare()  : Horde_Share_Object
Returns a Horde_Share_Object_Kolab object corresponding to the given share name, with the details retrieved appropriately.
_getShareById()  : Horde_Share_Object_sql
Returns a Horde_Share_Object_sql object corresponding to the given unique ID, with the details retrieved appropriately.
_getShares()  : array<string|int, mixed>
Returns an array of Horde_Share_Object_kolab objects corresponding to the requested folders.
_idExists()  : bool
Check that a share id exists in the system.
_listAllShares()  : array<string|int, mixed>
Lists *all* shares for the current app/share, regardless of permissions.
_listShares()  : array<string|int, mixed>
Returns an array of all shares that $userid has access to.
_newShare()  : Horde_Share_Object_kolab
Returns a new share object.
_removeShare()  : mixed
Removes a share from the shares system permanently.
_renameShare()  : mixed
Renames a share in the shares system.
_sortShares()  : mixed
Utility function to be used with uasort() for sorting arrays of Horde_Share objects.
_createObject()  : Horde_Share_Object
Returns a Horde_Share_Object_Kolab object corresponding to the given share name, with the details retrieved appropriately.
_idDecode()  : string
Decode a share ID.
_idDeconstruct()  : array<string|int, mixed>
Deconstruct the ID elements from the ID string
_idEncode()  : string
Encode a share ID.

Constants

VERSION

public mixed VERSION = 1

Properties

$_app

The application we're managing shares for.

protected string $_app

$_cache

A cache of all shares that have been retrieved, so we don't hit the backend again and again for them.

protected array<string|int, mixed> $_cache = array()

$_callbacks

Configured callbacks. We currently support: <pre> add - Called immediately before a new share is added. Receives the share object as a parameter.

protected array<string|int, mixed> $_callbacks

modify - Called immediately before a share object's changes are saved to storage. Receives the share object as a parameter. remove - Called immediately before a share is removed from storage. Receives the share object as a parameter. list - Called immediately after a list of shares is received from storage. Passed the userid, share list, and any parameters passed to the listShare call. Should return the (possibly modified) share list. @see listShares() for more info.

$_groups

The Horde_Group driver

protected Horde_Group_Base $_groups

$_listcache

Cache used for listShares().

protected array<string|int, mixed> $_listcache = array()

$_logger

Logger

protected Horde_Log_Logger $_logger

$_permsObject

The Horde_Perms object

protected Horde_Perms_Base $_permsObject

$_root

The root of the Share tree.

protected mixed $_root = \null

$_shareCallback

A callback that is passed to the share objects for setting the objects' Horde_Share object.

protected callable $_shareCallback

$_shareMap

Id-name-map of already cached share objects.

protected array<string|int, mixed> $_shareMap = array()

$_shareObject

The Horde_Share_Object subclass to instantiate objects as

protected string $_shareObject

$_sortList

A list of objects that we're currently sorting, for reference during the sorting algorithm.

protected array<string|int, mixed> $_sortList

$_user

The current user

protected string $_user

$_id_map

A map of IDs to folder names.

private array<string|int, mixed> $_id_map = array()

$_storage

The Kolab storage handler

private Horde_Kolab_Storage $_storage

$_type

The folder type in the storage backend.

private string $_type

Methods

__construct()

Constructor.

public __construct(string $app, string $user, Horde_Perms_Base $perms, Horde_Group_Base $groups) : mixed
Parameters
$app : string

The application that the shares belong to

$user : string

The current user

$perms : Horde_Perms_Base

The permissions object

$groups : Horde_Group_Base

The Horde_Group driver.

Return values
mixed —

addCallback()

Add a callback to the collection

public addCallback(string $type, array<string|int, mixed> $callback) : mixed
Parameters
$type : string
$callback : array<string|int, mixed>
Return values
mixed —

addShare()

Adds a share to the shares system.

public addShare(Horde_Share_Object $share) : mixed

The share must first be created with newShare(), and have any initial details added to it, before this function is called.

Parameters
$share : Horde_Share_Object

The new share object.

Tags
throws
Horde_Share_Exception
Return values
mixed —

constructFolderName()

Construct the Kolab storage folder name based on the share name and owner attributes.

public constructFolderName(string $owner, string $subpath[, string $prefix = null ]) : string
Parameters
$owner : string

The owner of the share.

$subpath : string

The folder subpath.

$prefix : string = null

The namespace prefix.

Return values
string —

The folder name for the Kolab backend.

constructId()

Construct the ID from the owner name and the folder subpath.

public constructId(string $owner, string $name[, string $prefix = null ]) : string
Parameters
$owner : string

The share owner.

$name : string

The name of the folder without the namespace prefix.

$prefix : string = null

The namespace prefix.

Return values
string —

The encoded ID.

countShares()

Returns the count of all shares that $userid has access to.

public countShares(string $userid[, int $perm = Horde_Perms::SHOW ][, mixed $attributes = null ][, mixed $parent = null ][, bool $allLevels = true ]) : int
Parameters
$userid : string

The userid of the user to check access for.

$perm : int = Horde_Perms::SHOW

The level of permissions required.

$attributes : mixed = null

Restrict the shares counted to those matching $attributes. An array of attribute/values pairs or a share owner username.

$parent : mixed = null

The share to start searching from (Horde_Share_Object, share_id, or null)

$allLevels : bool = true

Return all levels, or just the direct children of $parent?

Tags
throws
Horde_Share_Exception
Return values
int —

Number of shares the user has access to.

deleteAcl()

Delete Kolab specific access rights for a share.

public deleteAcl(string $id, string $user) : null
Parameters
$id : string

The share ID.

$user : string

The user to delete the ACL for

Return values
null —

exists()

Checks if a share name exists in the system.

public exists(string $share) : bool
Parameters
$share : string

The share name to check.

Return values
bool —

True if the share exists.

expireListCache()

Expire the current list cache. This would be needed anytime a share is either added, deleted, had a change in owner, parent, or perms.

public expireListCache() : mixed
Return values
mixed —

fromHash()

Adds a share created from a hash.

public fromHash(array<string|int, mixed> $hash) : Horde_Share_Object
Parameters
$hash : array<string|int, mixed>

A hash like exported from Horde_Share_Object#toHash().

Tags
since

Horde_Share 2.2.0

Return values
Horde_Share_Object —

A new share object.

getAcl()

Retrieve the Kolab specific access rights for a share.

public getAcl(string $id) : An
Parameters
$id : string

The share ID.

Return values
An —

array of rights.

getApp()

Returns the application we're managing shares for.

public getApp() : string
Return values
string —

The application this share belongs to.

getFolderNameElements()

Retrieve namespace information for a folder name.

public getFolderNameElements(string $folder) : array<string|int, mixed>
Parameters
$folder : string

The folder name.

Return values
array<string|int, mixed> —

A list of namespace prefix, the delimiter and the folder subpath.

getList()

Return the Kolab storage folder list handler.

public getList() : Horde_Kolab_Storage_List
Return values
Horde_Kolab_Storage_List —

The folder list handler.

getListCache()

Returns the share's list cache.

public getListCache() : array<string|int, mixed>
Return values
array<string|int, mixed> —

getPermissions()

Finds out what rights the given user has to this object.

public getPermissions(mixed $share[, string $user = null ]) : mixed
Parameters
$share : mixed

The share that should be checked for the users permissions.

$user : string = null

The user to check for.

Tags
see
Horde_Perms::getPermissions
Return values
mixed —

A bitmask of permissions, a permission value, or an array of permission values the user has, depending on the permission type and whether the permission value is ambiguous. False if there is no such permsission.

getPermsObject()

Getter for Horde_Perms object

public getPermsObject() : Horde_Perms_Base
Return values
Horde_Perms_Base —

getShare()

Returns a Horde_Share_Object object corresponding to the given share name, with the details retrieved appropriately.

public getShare(string $name) : Horde_Share_Object
Parameters
$name : string

The name of the share to retrieve.

Return values
Horde_Share_Object —

The requested share.

getShareById()

Returns a Horde_Share_Object object corresponding to the given unique ID, with the details retrieved appropriately.

public getShareById(string $cid) : Horde_Share_Object
Parameters
$cid : string

The id of the share to retrieve.

Return values
Horde_Share_Object —

The requested share.

getShares()

Returns an array of Horde_Share_Object objects corresponding to the given set of unique IDs, with the details retrieved appropriately.

public getShares(array<string|int, mixed> $cids) : array<string|int, mixed>
Parameters
$cids : array<string|int, mixed>

The array of ids to retrieve.

Return values
array<string|int, mixed> —

The requested shares.

getStorage()

Return the Kolab storage backend associated with this driver.

public getStorage() : Horde_Kolab_Storage
Return values
Horde_Kolab_Storage —

The Kolab storage driver.

getType()

Return the type of folder this share driver will access in the Kolab storage backend (depends on the application calling the share driver).

public getType() : string
Return values
string —

idExists()

Check that a share id exists in the system.

public idExists(int $id) : bool
Parameters
$id : int

The share id

Return values
bool —

True if the share exists.

listAllShares()

Lists *all* shares for the current app/share, regardless of permissions.

public listAllShares() : array<string|int, mixed>

This is for admin functionality and scripting tools, and shouldn't be called from user-level code!

Return values
array<string|int, mixed> —

All shares for the current app/share.

listShares()

Returns an array of all shares that $userid has access to.

public listShares(string $userid[, array<string|int, mixed> $params = array() ]) : array<string|int, mixed>
Parameters
$userid : string

The userid of the user to check access for. An empty value for the userid will only return shares with guest access.

$params : array<string|int, mixed> = array()

Additional parameters for the search.

 'perm'        Require this level of permissions. Horde_Perms constant.
 'attributes'  Restrict shares to these attributes. A hash or username.
 'from'        Offset. Start at this share
 'count'       Limit.  Only return this many.
 'sort_by'     Sort by attribute.
 'direction'   Sort by direction.
Return values
array<string|int, mixed> —

The shares the user has access to.

listSystemShares()

Returns an array of all system shares.

public listSystemShares() : array<string|int, mixed>
Return values
array<string|int, mixed> —

All system shares.

newShare()

Returns a new share object.

public newShare(string $owner[, string $share_name = '' ][, string $name_attribute = '' ]) : Horde_Share_Object
Parameters
$owner : string

The share owner name.

$share_name : string = ''

The share's name.

$name_attribute : string = ''

The name displayed to the user.

Tags
throws
Horde_Share_Exception
Return values
Horde_Share_Object —

A new share object.

resetCache()

Resets the internal caches.

public resetCache() : mixed
Return values
mixed —

runCallback()

Give public access to call the share callbacks. Needed to run the callbacks from the Horde_Share_Object objects.

public runCallback(string $type, array<string|int, mixed> $params) : mixed
Parameters
$type : string

The callback to run

$params : array<string|int, mixed>

The parameters to pass to the callback.

Return values
mixed —

save()

Save share data to the storage backend.

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

The share id.

$old_id : string

The old share id.

$data : array<string|int, mixed>

The share data.

Return values
null —

setAcl()

Set the Kolab specific access rights for a share.

public setAcl(string $id, string $user, string $acl) : null
Parameters
$id : string

The share ID.

$user : string

The user to set the ACL for.

$acl : string

The ACL.

Return values
null —

setListCache()

Set the list cache.

public setListCache(array<string|int, mixed> $cache) : mixed
Parameters
$cache : array<string|int, mixed>
Return values
mixed —

setLogger()

Set a logger object.

public setLogger(Horde_Log_Logger $logger) : mixed
Parameters
$logger : Horde_Log_Logger
Tags
inject
Return values
mixed —

setShareCallback()

public setShareCallback(mixed $callback) : mixed
Parameters
$callback : mixed
Return values
mixed —

setShareClass()

Set the class type to use for creating share objects.

public setShareClass(mixed $classname) : mixed
Parameters
$classname : mixed
Return values
mixed —

setStorage()

Set the Kolab storage backend.

public setStorage(Horde_Kolab_Storage $storage) : null
Parameters
$storage : Horde_Kolab_Storage

The Kolab storage handler.

Return values
null —

toDriverCharset()

Convert TO the storage driver's charset. Individual share objects should implement this method if needed.

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

Data to be converted.

Return values
mixed —

_addShare()

Adds a share to the shares system.

protected _addShare(Horde_Share_Object $share) : mixed

The share must first be created with Horde_Share::newShare(), and have any initial details added to it, before this function is called.

Parameters
$share : Horde_Share_Object

The new share object.

Return values
mixed —

_exists()

Checks if a share exists in the system.

protected _exists(string $share) : bool
Parameters
$share : string

The share to check.

Tags
throws
Horde_Share_Exception
Return values
bool —

True if the share exists.

_getShare()

Returns a Horde_Share_Object_Kolab object corresponding to the given share name, with the details retrieved appropriately.

protected _getShare(string $name) : Horde_Share_Object
Parameters
$name : string

The name of the share to retrieve.

Tags
throws
Horde_Exception_NotFound
throws
Horde_Share_Exception
Return values
Horde_Share_Object —

The requested share.

_getShareById()

Returns a Horde_Share_Object_sql object corresponding to the given unique ID, with the details retrieved appropriately.

protected _getShareById(int $id) : Horde_Share_Object_sql
Parameters
$id : int

The id of the share to retrieve.

Tags
throws

Horde_Share_Exception, Horde_Exception_NotFound

Return values
Horde_Share_Object_sql —

The requested share.

_getShares()

Returns an array of Horde_Share_Object_kolab objects corresponding to the requested folders.

protected _getShares(string $ids) : array<string|int, mixed>
Parameters
$ids : string

The ids of the shares to fetch.

Return values
array<string|int, mixed> —

An array of Horde_Share_Object_kolab objects.

_idExists()

Check that a share id exists in the system.

protected _idExists(int $id) : bool
Parameters
$id : int

The share id

Return values
bool —

True if the share exists.

_listAllShares()

Lists *all* shares for the current app/share, regardless of permissions.

protected _listAllShares() : array<string|int, mixed>

For the Kolab backend this cannot work in the same way as for the SQL based backend. Permissions are always handled by the backend automatically (IMAP ACLs) and cannot be disabled.

listAllShares() is apparently used during command line scipts where it represents administrator access. This is possible on Kolab by using the "manager" user. In that case a standard listShares() authenticated as "manager" should be sufficient.

Return values
array<string|int, mixed> —

All shares for the current app/share.

_listShares()

Returns an array of all shares that $userid has access to.

protected _listShares(string $userid[, array<string|int, mixed> $params = array() ]) : array<string|int, mixed>
Parameters
$userid : string

The userid of the user to check access for.

$params : array<string|int, mixed> = array()

See listShares().

Return values
array<string|int, mixed> —

The shares the user has access to.

_newShare()

Returns a new share object.

protected _newShare(string $name) : Horde_Share_Object_kolab
Parameters
$name : string

The share's name.

Return values
Horde_Share_Object_kolab —

A new share object.

_removeShare()

Removes a share from the shares system permanently.

protected _removeShare(Horde_Share_Object $share) : mixed
Parameters
$share : Horde_Share_Object

The share to remove.

Return values
mixed —

_sortShares()

Utility function to be used with uasort() for sorting arrays of Horde_Share objects.

protected _sortShares(mixed $a, mixed $b) : mixed

Example: uasort($list, array('Horde_Share', '_sortShares'));

Parameters
$a : mixed
$b : mixed
Return values
mixed —

_createObject()

Returns a Horde_Share_Object_Kolab object corresponding to the given share name, with the details retrieved appropriately.

private _createObject(string $id[, array<string|int, mixed> $data = array() ]) : Horde_Share_Object
Parameters
$id : string

The id of the share to retrieve.

$data : array<string|int, mixed> = array()

The share data.

Return values
Horde_Share_Object —

The requested share.

_idDecode()

Decode a share ID.

private _idDecode(string $id) : string
Parameters
$id : string

The ID to be decoded.

Return values
string —

The decoded ID.

_idDeconstruct()

Deconstruct the ID elements from the ID string

private _idDeconstruct(string $id) : array<string|int, mixed>
Parameters
$id : string

The ID to be deconstructed.

Return values
array<string|int, mixed> —

A tuple of (owner, folder subpath).

_idEncode()

Encode a share ID.

private _idEncode(string $id) : string
Parameters
$id : string

The ID to be encoded.

Tags
todo:

In Horde3 share IDs were not properly escaped everywhere and it made sense to escape them here just in case they are placed in a URL. Needs checking in Horde4.

Return values
string —

The encoded ID.

Search results