\Horde_Share_Sql

Base class for all Horde_Share drivers.

Copyright 2002-2017 Horde LLC (http://www.horde.org/) Copyright 2002-2007 Infoteck Internet webmaster@infoteck.qc.ca

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

Summary

Methods
Properties
Constants
__construct()
setLogger()
initShareObject()
setShareCallback()
getApp()
getShare()
getShareById()
getShares()
listAllShares()
listShares()
listSystemShares()
countShares()
newShare()
addShare()
fromHash()
renameShare()
removeShare()
exists()
idExists()
getPermissions()
setShareClass()
getPermsObject()
toDriverCharset()
addCallback()
getListCache()
setListCache()
resetCache()
runCallback()
expireListCache()
setTable()
getTable()
setStorage()
getStorage()
listOwners()
countOwners()
getParent()
getShareCriteria()
No public properties found
SQL_FLAG_USERS
SQL_FLAG_GROUPS
VERSION
_getShare()
_getShareById()
_getShares()
_listAllShares()
_listShares()
_newShare()
_addShare()
_renameShare()
_removeShare()
_exists()
_idExists()
_sortShares()
_getClobFields()
_getNonClobFields()
_getDistinctClause()
_hasUsers()
_hasGroups()
_getShareUsers()
_getShareGroups()
_createObject()
_convertClobs()
_loadPermissions()
_getSharePerms()
_fetchClobFields()
_getUserAndGroupCriteria()
_buildPermsFromRow()
_fromDriverCharset()
_toDriverKeys()
$_app
$_root
$_cache
$_shareMap
$_listcache
$_sortList
$_shareObject
$_permsObject
$_user
$_groups
$_shareCallback
$_logger
$_callbacks
$_db
$_table
$_clobFields
$_nonClobFields
N/A
No private methods found
No private properties found
N/A

Constants

SQL_FLAG_USERS

SQL_FLAG_USERS

SQL_FLAG_GROUPS

SQL_FLAG_GROUPS

VERSION

VERSION

Properties

$_app

$_app : string

The application we're managing shares for.

Type

string

$_root

$_root : mixed

The root of the Share tree.

Type

mixed

$_cache

$_cache : array

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

Type

array

$_shareMap

$_shareMap : array

Id-name-map of already cached share objects.

Type

array

$_listcache

$_listcache : array

Cache used for listShares().

Type

array

$_sortList

$_sortList : array

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

Type

array

$_shareObject

$_shareObject : string

The Horde_Share_Object subclass to instantiate objects as

Type

string

$_permsObject

$_permsObject : \Horde_Perms_Base

The Horde_Perms object

Type

\Horde_Perms_Base

$_user

$_user : string

The current user

Type

string

$_groups

$_groups : \Horde_Group_Base

The Horde_Group driver

Type

\Horde_Group_Base

$_shareCallback

$_shareCallback : callback

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

Type

callback

$_logger

$_logger : \Horde_Log_Logger

Logger

Type

\Horde_Log_Logger

$_callbacks

$_callbacks : array

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

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.

Type

array

$_db

$_db : \Horde_Db_Adapter

Handle for the current database connection.

Type

\Horde_Db_Adapter

$_table

$_table : string

Main share table for the current scope.

Type

string

$_clobFields

$_clobFields : array

Local cache of text/clob fields

Type

array

$_nonClobFields

$_nonClobFields : array

Local cache of non-text/clob fields

Type

array

Methods

__construct()

__construct(string  $app, string  $user, \Horde_Perms_Base  $perms, \Horde_Group_Base  $groups) 

Constructor.

Parameters

string $app

The application that the shares belong to.

string $user

The current user.

\Horde_Perms_Base $perms

The permissions object.

\Horde_Group_Base $groups

The Horde_Group driver.

setLogger()

setLogger(\Horde_Log_Logger  $logger) 

Set a logger object.

Parameters

\Horde_Log_Logger $logger

initShareObject()

initShareObject(\Horde_Share_Object  $object) 

(Re)connects the share object to this share driver.

Parameters

\Horde_Share_Object $object

setShareCallback()

setShareCallback(  $callback) 

Parameters

$callback

getApp()

getApp() : string

Returns the application we're managing shares for.

Returns

string —

The application this share belongs to.

getShare()

getShare(string  $name) : \Horde_Share_Object

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

Parameters

string $name

The name of the share to retrieve.

Returns

\Horde_Share_Object

The requested share.

getShareById()

getShareById(string  $cid) : \Horde_Share_Object

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

Parameters

string $cid

The id of the share to retrieve.

Returns

\Horde_Share_Object

The requested share.

getShares()

getShares(array  $cids) : array

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

Parameters

array $cids

The array of ids to retrieve.

Returns

array —

The requested shares.

listAllShares()

listAllShares() : array

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

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

Throws

\Horde_Share_Exception

Returns

array —

All shares for the current app/share.

listShares()

listShares(string  $userid, array  $params = array()) : array

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

Parameters

string $userid

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

array $params

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?

Throws

\Horde_Share_Exception

Returns

array —

The shares the user has access to.

listSystemShares()

listSystemShares() : array

Returns an array of all system shares.

Throws

\Horde_Share_Exception

Returns

array —

All system shares.

countShares()

countShares(string  $userid, integer  $perm = \Horde_Perms::SHOW, mixed  $attributes = null, mixed  $parent = null, boolean  $allLevels = true) : integer

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

Parameters

string $userid

The userid of the user to check access for.

integer $perm

The level of permissions required.

mixed $attributes

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

mixed $parent

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

boolean $allLevels

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

Throws

\Horde_Share_Exception

Returns

integer —

Number of shares the user has access to.

newShare()

newShare(string  $owner, string  $share_name = '', string  $name_attribute = '') : \Horde_Share_Object

Returns a new share object.

Parameters

string $owner

The share owner name.

string $share_name

The share's name.

string $name_attribute

The name displayed to the user.

Throws

\Horde_Share_Exception

Returns

\Horde_Share_Object

A new share object.

addShare()

addShare(\Horde_Share_Object  $share) 

Adds a share to the shares system.

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

Parameters

\Horde_Share_Object $share

The new share object.

Throws

\Horde_Share_Exception

fromHash()

fromHash(array  $hash) : \Horde_Share_Object

Adds a share created from a hash.

Parameters

array $hash

A hash like exported from Horde_Share_Object#toHash().

Returns

\Horde_Share_Object

A new share object.

renameShare()

renameShare(\Horde_Share_Object  $share, string  $name) 

Renames a share in the shares system.

Parameters

\Horde_Share_Object $share

The share to rename.

string $name

The share's new name.

Throws

\Horde_Share_Exception

removeShare()

removeShare(\Horde_Share_Object  $share) 

Removes a share from the shares system permanently.

Parameters

\Horde_Share_Object $share

The share to remove.

Throws

\Horde_Share_Exception

exists()

exists(string  $share) : boolean

Checks if a share name exists in the system.

Parameters

string $share

The share name to check.

Returns

boolean —

True if the share exists.

idExists()

idExists(integer  $id) : boolean

Check that a share id exists in the system.

Parameters

integer $id

The share id

Returns

boolean —

True if the share exists.

getPermissions()

getPermissions(mixed  $share, string  $user = null) : mixed

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

Parameters

mixed $share

The share that should be checked for the users permissions.

string $user

The user to check for.

Returns

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.

setShareClass()

setShareClass(  $classname) 

Set the class type to use for creating share objects.

Parameters

$classname

getPermsObject()

getPermsObject() : \Horde_Perms_Base

Getter for Horde_Perms object

Returns

\Horde_Perms_Base

toDriverCharset()

toDriverCharset(array  $data) 

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

Parameters

array $data

Data to be converted.

addCallback()

addCallback(string  $type, array  $callback) 

Add a callback to the collection

Parameters

string $type
array $callback

getListCache()

getListCache() : array

Returns the share's list cache.

Returns

array

setListCache()

setListCache(array  $cache) 

Set the list cache.

Parameters

array $cache

resetCache()

resetCache() 

Resets the internal caches.

runCallback()

runCallback(string  $type, array  $params) : mixed

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

Parameters

string $type

The callback to run

array $params

The parameters to pass to the callback.

Returns

mixed

expireListCache()

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.

setTable()

setTable(  $table) 

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

Parameters

$table

getTable()

getTable() : string

Get storage table

Returns

string

setStorage()

setStorage(\Horde_Db_Adapter  $db) 

Parameters

\Horde_Db_Adapter $db

getStorage()

getStorage() : \Horde_Db_Adapter

Returns

\Horde_Db_Adapter

listOwners()

listOwners(integer  $perm = \Horde_Perms::SHOW, mixed  $parent = null, boolean  $allLevels = true, integer  $from, integer  $count) : array

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

Parameters

integer $perm

The level of permissions required.

mixed $parent

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

boolean $allLevels

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

integer $from

The user to start listing at.

integer $count

The number of users to return.

Throws

\Horde_Share_Exception

Returns

array —

List of users.

countOwners()

countOwners(integer  $perm = \Horde_Perms::SHOW, mixed  $parent = null, boolean  $allLevels = true) : integer

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

Parameters

integer $perm

The level of permissions required.

mixed $parent

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

boolean $allLevels

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

Throws

\Horde_Share_Exception

Returns

integer —

Number of users.

getParent()

getParent(\Horde_Share_Object  $child) : \Horde_Share_Object

Returns a share's direct parent object.

Parameters

\Horde_Share_Object $child

The share to get parent for.

Returns

\Horde_Share_Object

The parent share, if it exists.

getShareCriteria()

getShareCriteria(string  $userid, integer  $perm = \Horde_Perms::SHOW, mixed  $attributes = null, mixed  $parent = null, boolean  $allLevels = true) : string

Returns an array of criteria for querying shares.

Parameters

string $userid

The userid of the user to check access for.

integer $perm

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

mixed $attributes

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

mixed $parent

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

boolean $allLevels

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

Throws

\Horde_Share_Exception

Returns

string —

The criteria string for fetching this user's shares.

_getShare()

_getShare(string  $name) : \Horde_Share_Object

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

Parameters

string $name

The name of the share to retrieve.

Throws

\Horde_Exception_NotFound
\Horde_Share_Exception

Returns

\Horde_Share_Object

The requested share.

_getShareById()

_getShareById(integer  $id) : \Horde_Share_Object_sql

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

Parameters

integer $id

The id of the share to retrieve.

Throws

\Horde_Share_Exception,

Horde_Exception_NotFound

Returns

\Horde_Share_Object_sql —

The requested share.

_getShares()

_getShares(array  $ids) : array

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

Parameters

array $ids

The array of ids to retrieve.

Throws

\Horde_Share_Exception

Returns

array —

The requested shares.

_listAllShares()

_listAllShares() : array

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

Throws

\Horde_Share_Exception

Returns

array —

All shares for the current app/share.

_listShares()

_listShares(string  $userid, array  $params = array()) : array

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

Parameters

string $userid

The userid of the user to check access for.

array $params

See listShares().

Returns

array —

The shares the user has access to.

_newShare()

_newShare(string  $name) : \Horde_Share_Object

Returns a new share object.

Parameters

string $name

The share's name.

Throws

\InvalidArgumentException

Returns

\Horde_Share_Object

A new share object

_addShare()

_addShare(\Horde_Share_Object  $share) 

Adds a share to the shares system.

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

\Horde_Share_Object $share

The new share object.

_renameShare()

_renameShare(\Horde_Share_Object  $share, string  $name) 

Renames a share in the shares system.

Parameters

\Horde_Share_Object $share

The share to rename.

string $name

The share's new name.

Throws

\Horde_Share_Exception

_removeShare()

_removeShare(\Horde_Share_Object  $share) : boolean

Removes a share from the shares system permanently.

Parameters

\Horde_Share_Object $share

The share to remove.

Throws

\Horde_Share_Exception

Returns

boolean

_exists()

_exists(string  $share) : boolean

Checks if a share exists in the system.

Parameters

string $share

The share to check.

Throws

\Horde_Share_Exception

Returns

boolean —

True if the share exists.

_idExists()

_idExists(integer  $id) : boolean

Check that a share id exists in the system.

Parameters

integer $id

The share id

Returns

boolean —

True if the share exists.

_sortShares()

_sortShares(  $a,   $b) 

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

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

Parameters

$a
$b

_getClobFields()

_getClobFields() : array

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

Returns

array —

An array of clob field names.

_getNonClobFields()

_getNonClobFields() : array

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

Returns

array —

An array of non-clob field names.

_getDistinctClause()

_getDistinctClause() : string

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

Returns

string —

The DISTINCT clause.

_hasUsers()

_hasUsers(  $share) 

Finds out if the share has user set

Parameters

$share

_hasGroups()

_hasGroups(  $share) 

Finds out if the share has user set

Parameters

$share

_getShareUsers()

_getShareUsers(array  $share) 

Get users permissions

Parameters

array $share

Share data array

Throws

\Horde_Share_Exception

_getShareGroups()

_getShareGroups(array  $share) 

Get groups permissions

Parameters

array $share

Share data array

Throws

\Horde_Share_Exception

_createObject()

_createObject(array  $data = array()) 

Parameters

array $data

_convertClobs()

_convertClobs(  $data) 

Convert clob data to string.

Parameters

$data

_loadPermissions()

_loadPermissions(array  $data) 

Helper function to load the permissions data into the share data

Parameters

array $data

Array of share attributes

_getSharePerms()

_getSharePerms(  $data) 

Parameters

$data

_fetchClobFields()

_fetchClobFields(  $shares) 

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

Parameters

$shares

_getUserAndGroupCriteria()

_getUserAndGroupCriteria(string  $userid, integer  $perm = \Horde_Perms::SHOW) : array

Returns criteria statement fragments for querying shares.

Parameters

string $userid

The userid of the user to check access for.

integer $perm

The level of permissions required.

Returns

array —

An array with query and where string fragments.

_buildPermsFromRow()

_buildPermsFromRow(array  $row) : integer

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

Parameters

array $row

A data row including permission columns.

Returns

integer —

A permission mask.

_fromDriverCharset()

_fromDriverCharset(  $data) 

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

Parameters

$data

_toDriverKeys()

_toDriverKeys(array  $data) : array

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

Parameters

array $data

The client code keyed array.

Returns

array —

The driver keyed array.