Documentation

Horde_Share_Sql extends Horde_Share_Base
in package

Base class for all Horde_Share drivers.

Table of Contents

SQL_FLAG_GROUPS  = 2
SQL_FLAG_USERS  = 1
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.
$_clobFields  : array<string|int, mixed>
Local cache of text/clob fields
$_db  : Horde_Db_Adapter
Handle for the current database connection.
$_groups  : Horde_Group_Base
The Horde_Group driver
$_listcache  : array<string|int, mixed>
Cache used for listShares().
$_logger  : Horde_Log_Logger
Logger
$_nonClobFields  : array<string|int, mixed>
Local cache of non-text/clob fields
$_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.
$_table  : string
Main share table for the current scope.
$_user  : string
The current user
$_driverConversions  : array<string|int, mixed>
__construct()  : mixed
Constructor.
addCallback()  : mixed
Add a callback to the collection
addShare()  : mixed
Adds a share to the shares system.
countOwners()  : int
Count the number of users who have shares with the given permissions for the current user.
countShares()  : int
Returns the count of all shares that $userid has access to.
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.
getApp()  : string
Returns the application we're managing shares for.
getListCache()  : array<string|int, mixed>
Returns the share's list cache.
getParent()  : Horde_Share_Object
Returns a share's direct parent object.
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.
getShareCriteria()  : string
Returns an array of criteria for querying shares.
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_Db_Adapter
getTable()  : string
Get storage table
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.
listOwners()  : array<string|int, mixed>
Return a list of users who have shares with the given permissions for the current user.
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.
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()  : mixed
setTable()  : mixed
Set the SQL table name to use for the current scope's share storage.
toDriverCharset()  : mixed
Utility function to convert TO the SQL server's charset.
_addShare()  : mixed
Adds a share to the shares system.
_buildPermsFromRow()  : int
Builds a permission bit mask from the "perm" column.
_convertClobs()  : mixed
Convert clob data to string.
_createObject()  : mixed
_exists()  : bool
Checks if a share exists in the system.
_fetchClobFields()  : mixed
Fetch data for all clob fields of each share passed in $shares.
_fromDriverCharset()  : mixed
Utility function to convert from the SQL server's charset.
_getClobFields()  : array<string|int, mixed>
Return a list of fields in the table that ARE text/clob fields.
_getDistinctClause()  : string
Return a DISTINCT clause containing all non-clob field names.
_getNonClobFields()  : array<string|int, mixed>
Return a list of fields in the table that are NOT text/clob fields.
_getShare()  : Horde_Share_Object
Returns a Horde_Share_Object_sql 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.
_getShareGroups()  : mixed
Get groups permissions
_getSharePerms()  : mixed
_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.
_getShareUsers()  : mixed
Get users permissions
_getUserAndGroupCriteria()  : array<string|int, mixed>
Returns criteria statement fragments for querying shares.
_hasGroups()  : mixed
Finds out if the share has user set
_hasUsers()  : mixed
Finds out if the share has user set
_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.
_loadPermissions()  : mixed
Helper function to load the permissions data into the share data
_newShare()  : Horde_Share_Object
Returns a new share object.
_removeShare()  : bool
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.
_toDriverKeys()  : array<string|int, mixed>
Convert an array keyed on client keys to an array keyed on the driver keys.

Constants

SQL_FLAG_GROUPS

public mixed SQL_FLAG_GROUPS = 2

SQL_FLAG_USERS

public mixed SQL_FLAG_USERS = 1

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.

$_clobFields

Local cache of text/clob fields

protected array<string|int, mixed> $_clobFields

$_db

Handle for the current database connection.

protected Horde_Db_Adapter $_db

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

$_nonClobFields

Local cache of non-text/clob fields

protected array<string|int, mixed> $_nonClobFields

$_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 = 'Horde_Share_Object_Sql'

$_sortList

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

protected array<string|int, mixed> $_sortList

$_table

Main share table for the current scope.

protected string $_table

$_user

The current user

protected string $_user

$_driverConversions

private array<string|int, mixed> $_driverConversions = ['utf8mb4' => 'UTF-8', 'utf8mb3' => 'UTF-8', 'utf8' => 'UTF-8']

Methods

__construct()

Constructor.

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

The application that the shares belong to.

$user : mixed

The current user.

$perms : Horde_Perms_Base

The permissions object.

$groups : Horde_Group_Base

The Horde_Group driver.

Tags
see
Horde_Share_Base::__construct()
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

countOwners()

Count the number of users who have shares with the given permissions for the current user.

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

The level of permissions required.

$parent : mixed = null

The parent share to start looking in. (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 users.

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.

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.

getApp()

Returns the application we're managing shares for.

public getApp() : string
Return values
string

The application this share belongs to.

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.

getShareCriteria()

Returns an array of criteria for querying shares.

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

The userid of the user to check access for.

$perm : int = Horde_Perms::SHOW

The level of permissions required. Set to null to skip permission filtering.

$attributes : mixed = null

Restrict the shares returned to those who have these attribute values.

$parent : mixed = null

The share to start searching in. (A Horde_Share_Object, share_id or null)

$allLevels : bool = true

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

Tags
TODO

Make this method protected, like all the other drivers.

throws
Horde_Share_Exception
Return values
string

The criteria string for fetching this user's shares.

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()

public getStorage() : Horde_Db_Adapter
Return values
Horde_Db_Adapter

getTable()

Get storage table

public getTable() : 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!

Tags
throws
Horde_Share_Exception
Return values
array<string|int, mixed>

All shares for the current app/share.

listOwners()

Return a list of users who have shares with the given permissions for the current user.

public listOwners([int $perm = Horde_Perms::SHOW ][, mixed $parent = null ][, bool $allLevels = true ], int $from, int $count) : array<string|int, mixed>
Parameters
$perm : int = Horde_Perms::SHOW

The level of permissions required.

$parent : mixed = null

The parent share to start looking in. (Horde_Share_Object, share_id, or null)

$allLevels : bool = true

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

$from : int

The user to start listing at.

$count : int

The number of users to return.

Tags
throws
Horde_Share_Exception
Return values
array<string|int, mixed>

List of users.

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.
 'attribtues'    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.
 'parent'        Start at this share in the hierarchy. Either share_id or
                 Horde_Share_Object
 'all_levels'    List all levels or just the direct children of parent?
Tags
throws
Horde_Share_Exception
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>
Tags
throws
Horde_Share_Exception
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

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()

public setStorage(Horde_Db_Adapter $db) : mixed
Parameters
$db : Horde_Db_Adapter
Return values
mixed

setTable()

Set the SQL table name to use for the current scope's share storage.

public setTable(mixed $table) : mixed
Parameters
$table : mixed
Return values
mixed

toDriverCharset()

Utility function to convert TO the SQL server's charset.

public toDriverCharset(mixed $data) : mixed
Parameters
$data : mixed

Data to be converted.

Tags
see

Horde_Share#toDriverCharset

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_sql::_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

_buildPermsFromRow()

Builds a permission bit mask from the "perm" column.

protected _buildPermsFromRow(array<string|int, mixed> $row) : int
Parameters
$row : array<string|int, mixed>

A data row including permission columns.

Return values
int

A permission mask.

_convertClobs()

Convert clob data to string.

protected _convertClobs(array<string|int, mixed> &$data) : mixed
Parameters
$data : array<string|int, mixed>

An array of share data.

Return values
mixed

_createObject()

protected _createObject([array<string|int, mixed> $data = array() ]) : mixed
Parameters
$data : array<string|int, mixed> = array()
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.

_fetchClobFields()

Fetch data for all clob fields of each share passed in $shares.

protected _fetchClobFields(array<string|int, mixed> &$shares) : mixed
Parameters
$shares : array<string|int, mixed>

List of share data to populate with clob data.

Return values
mixed

_fromDriverCharset()

Utility function to convert from the SQL server's charset.

protected _fromDriverCharset(mixed $data) : mixed
Parameters
$data : mixed
Return values
mixed

_getClobFields()

Return a list of fields in the table that ARE text/clob fields.

protected _getClobFields() : array<string|int, mixed>
Return values
array<string|int, mixed>

An array of clob field names.

_getDistinctClause()

Return a DISTINCT clause containing all non-clob field names.

protected _getDistinctClause() : string
Return values
string

The DISTINCT clause.

_getNonClobFields()

Return a list of fields in the table that are NOT text/clob fields.

protected _getNonClobFields() : array<string|int, mixed>
Return values
array<string|int, mixed>

An array of non-clob field names.

_getShare()

Returns a Horde_Share_Object_sql 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.

_getShareGroups()

Get groups permissions

protected _getShareGroups(array<string|int, mixed> &$share) : mixed
Parameters
$share : array<string|int, mixed>

Share data array

Tags
throws
Horde_Share_Exception
Return values
mixed

_getSharePerms()

protected _getSharePerms(mixed &$data) : mixed
Parameters
$data : mixed
Return values
mixed

_getShares()

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

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

The array of ids to retrieve.

Tags
throws
Horde_Share_Exception
Return values
array<string|int, mixed>

The requested shares.

_getShareUsers()

Get users permissions

protected _getShareUsers(array<string|int, mixed> &$share) : mixed
Parameters
$share : array<string|int, mixed>

Share data array

Tags
throws
Horde_Share_Exception
Return values
mixed

_getUserAndGroupCriteria()

Returns criteria statement fragments for querying shares.

protected _getUserAndGroupCriteria(string $userid[, int $perm = Horde_Perms::SHOW ]) : array<string|int, mixed>
Parameters
$userid : string

The userid of the user to check access for.

$perm : int = Horde_Perms::SHOW

The level of permissions required.

Return values
array<string|int, mixed>

An array with query and where string fragments.

_hasGroups()

Finds out if the share has user set

protected _hasGroups(mixed $share) : mixed
Parameters
$share : mixed
Return values
mixed

_hasUsers()

Finds out if the share has user set

protected _hasUsers(mixed $share) : mixed
Parameters
$share : mixed
Return values
mixed

_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>
Tags
throws
Horde_Share_Exception
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.

_loadPermissions()

Helper function to load the permissions data into the share data

protected _loadPermissions(array<string|int, mixed> &$data) : mixed
Parameters
$data : array<string|int, mixed>

Array of share attributes

Return values
mixed

_newShare()

Returns a new share object.

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

The share's name.

Tags
throws
InvalidArgumentException
Return values
Horde_Share_Object

A new share object

_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

_toDriverKeys()

Convert an array keyed on client keys to an array keyed on the driver keys.

protected _toDriverKeys(array<string|int, mixed> $data) : array<string|int, mixed>
Parameters
$data : array<string|int, mixed>

The client code keyed array.

Return values
array<string|int, mixed>

The driver keyed array.

Search results