PHP Class Horde_Ldap_Entry, horde

Author: Jan Wagner ([email protected])

Author: Tarjej Huse ([email protected])

Author: Benedikt Hallinger ([email protected])

Author: Ben Klang ([email protected])

Author: Jan Schneider ([email protected])

Show file Open project: horde/horde Class Usage Examples

Protected Properties

Property	Type	Description
$_attributes	array	Attributes.
$_changes	array	Map with changes to the entry.
$_delete	boolean	Shall the entry be deleted?
$_dn	string	Distinguished name of the entry.
$_entry	resource	Entry resource identifier.
$_ldap	Horde_Ldap	This object will be used for updating and schema checking.
$_link	resource	LDAP resource identifier.
$_map	array	Map of attribute names.
$_new	boolean	Is this a new entry?
$_newdn	string	New distinguished name.
$_original	array	Original attributes before any modification.

Public Methods

Method	Description
add ( array $attr = [] )	Adds new attributes or a new values to existing attributes.
attributes ( ) : array	Returns an array of attributes names.
createConnected ( Horde_Ldap $ldap, resource $entry ) : Horde_Ldap_Entry	Creates an entry object out of an LDAP entry resource.
createExisting ( string $dn, array $attrs = [] ) : Horde_Ldap_Entry	Creates an entry object that is considered to exist already.
createFresh ( string $dn, array $attrs = [] ) : Horde_Ldap_Entry	Creates a fresh entry that may be added to the directory later.
currentDN ( ) : string	Returns always the original DN.
delete ( string \| array $attr = null )	Deletes an attribute, a value or the whole entry.
dn ( string $dn = null ) : string	Returns or sets the distinguished name of the entry.
exists ( string $attr ) : boolean	Returns whether an attribute exists or not.
getChanges ( ) : array	Returns the attribute changes to be carried out once update() is called.
getLDAP ( ) : Horde_Ldap	Returns a reference to the LDAP-Object of this entry.
getValue ( string $attr, string $option = null ) : string \| array	Returns the value of a specific attribute.
getValues ( ) : array	Returns the values of all attributes in a hash.
isNew ( ) : boolean	Returns whether the entry is considered new (not present in the server).
markAsNew ( boolean $mark = true )	Marks the entry as new or existing.
pregMatch ( string $regex, string $attr_name, array &$matches = [] ) : boolean	Applies a regular expression onto a single- or multi-valued attribute (like preg_match()).
replace ( array $attr = [], boolean $force = false )	Replaces attributes or their values.
setLDAP ( Horde_Ldap $ldap )	Sets a reference to the LDAP object of this entry.
update ( )	Updates the entry on the directory server.
willBeDeleted ( ) : boolean	Is this entry going to be deleted once update() is called?
willBeMoved ( ) : boolean	Is this entry going to be moved once update() is called?

Protected Methods

Method	Description
__construct ( Horde_Ldap \| resource \| array $ldap, string \| resource $entry = null )	Constructor.
_getAttrName ( string $attr ) : string	Returns the right attribute name.
_loadAttributes ( array $attributes = null )	Sets the internal attributes array.

Method Details

__construct() protected method

Sets up the distinguished name and the entries attributes. Use {@link Horde_Ldap_Entry::createFresh()} or {@link Horde_Ldap_Entry::createConnected()} to create Horde_Ldap_Entry objects.

protected __construct ( Horde_Ldap \| resource \| array $ldap, string \| resource $entry = null )
$ldap	Horde_Ldap \| resource \| array	Horde_Ldap object, LDAP connection resource or array of attributes.
$entry	string \| resource	Either a DN or a LDAP entry resource.

_getAttrName() protected method

Returns the right attribute name.

protected _getAttrName ( string $attr ) : string
$attr	string	Name of attribute.
return	string	The right name of the attribute

_loadAttributes() protected method

This method fetches the values for the attributes from the server. The attribute syntax will be checked so binary attributes will be returned as binary values. Attributes may be passed directly via the $attributes parameter to setup this entry manually. This overrides attribute fetching from the server.

protected _loadAttributes ( array $attributes = null )
$attributes	array	Attributes to set for this entry.

add() public method

The paramter has to be an array of the form:


array('attributename' => 'single value',
      'attributename' => array('value1', 'value2'))

When the attribute already exists the values will be added, otherwise the attribute will be created. These changes are local to the entry and do not affect the entry on the server until update() is called. You can add values of attributes that you haven't originally selected, but if you do so, {@link getValue()} and {@link getValues()} will only return the values you added, *NOT* all values present on the server. To avoid this, just refetch the entry after calling {@link update()} or select the attribute.

public add ( array $attr = [] )
$attr	array	Attributes to add.

attributes() public method

Returns an array of attributes names.

public attributes ( ) : array
return	array	Array of attribute names.

createConnected() public static method

Use this method, if you want to initialize an entry object that is already present in some directory and that you have read manually.

public static createConnected ( Horde_Ldap $ldap, resource $entry ) : Horde_Ldap_Entry
$ldap	Horde_Ldap	Horde_Ldap object.
$entry	resource	PHP LDAP entry resource.
return	Horde_Ldap_Entry

createExisting() public static method

Use this method, if you want to modify an already existing entry without fetching it first. In most cases however, it is better to fetch the entry via Horde_Ldap::getEntry(). You should take care if you construct entries manually with this because you may get weird synchronisation problems. The attributes and values as well as the entry itself are considered existent which may produce errors if you try to modify an entry which doesn't really exist or if you try to overwrite some attribute with an value already present. The attributes parameter is as following:


$attrs = array('attribute1' => array('value1', 'value2'),
               'attribute2' => 'single value');

public static createExisting ( string $dn, array $attrs = [] ) : Horde_Ldap_Entry
$dn	string	DN of the entry.
$attrs	array	Attributes of the entry.
return	Horde_Ldap_Entry

createFresh() public static method

You should put a 'objectClass' attribute into the $attrs so the directory server knows which object you want to create. However, you may omit this in case you don't want to add this entry to a directory server. The attributes parameter is as following:


$attrs = array('attribute1' => array('value1', 'value2'),
               'attribute2' => 'single value');

public static createFresh ( string $dn, array $attrs = [] ) : Horde_Ldap_Entry
$dn	string	DN of the entry.
$attrs	array	Attributes of the entry.
return	Horde_Ldap_Entry

currentDN() public method

If an entry will be moved but {@link update()} was not called, {@link dn()} will return the new DN. This method however, returns always the current active DN.

public currentDN ( ) : string
return	string	The current DN

delete() public method

The parameter can be one of the following: - 'attributename': the attribute as a whole will be deleted. - array('attributename1', 'attributename2'): all specified attributes will be deleted. - array('attributename' => 'value'): the specified attribute value will be deleted. - array('attributename' => array('value1', 'value2'): The specified attribute values will be deleted. - null: the whole entry will be deleted. These changes are local to the entry and do not affect the entry on the server until {@link update()} is called. You must select the attribute (at $ldap->search() for example) to be able to delete values of it, Otherwise {@link update()} will silently fail and remove nothing.

public delete ( string \| array $attr = null )
$attr	string \| array	Attributes to delete.

dn() public method

If called without an argument the current (or the new DN if set) DN gets returned. If you provide an DN, this entry is moved to the new location specified if a DN existed. If the DN was not set, the DN gets initialized. Call {@link update()} to actually create the new entry in the directory. To fetch the current active DN after setting a new DN but before an update(), you can use {@link currentDN()} to retrieve the DN that is currently active.

public dn ( string $dn = null ) : string
$dn	string	New distinguished name.
return	string	Distinguished name.

exists() public method

Returns whether an attribute exists or not.

public exists ( string $attr ) : boolean
$attr	string	Attribute name.
return	boolean	True if the attribute exists.

getChanges() public method

Returns the attribute changes to be carried out once update() is called.

public getChanges ( ) : array
return	array	The due changes.

getLDAP() public method

Returns a reference to the LDAP-Object of this entry.

public getLDAP ( ) : Horde_Ldap
return	Horde_Ldap	Reference to the Horde_Ldap object (the connection).

getValue() public method

The first parameter is the name of the attribute. The second parameter influences the way the value is returned: - 'single': only the first value is returned as string. - 'all': all values are returned in an array. In all other cases an attribute value with a single value is returned as string, if it has multiple values it is returned as an array.

public getValue ( string $attr, string $option = null ) : string \| array
$attr	string	Attribute name.
$option	string	Option.
return	string \| array	Attribute value(s).

getValues() public method

The returned hash has the form


array('attributename' => 'single value',
      'attributename' => array('value1', value2', value3'))

public getValues ( ) : array
return	array	Hash of all attributes with their values.

isNew() public method

This method doesn't tell you if the entry is really not present on the server. Use {@link Horde_Ldap::exists()} to see if an entry is already there.

public isNew ( ) : boolean
return	boolean	True if this is considered a new entry.

markAsNew() public method

If an entry is marked as new, it will be added to the directory when calling {@link update()}. If the entry is marked as old ($mark = false), then the entry is assumed to be present in the directory server wich results in modification when calling {@link update()}.

public markAsNew ( boolean $mark = true )
$mark	boolean	Whether to mark the entry as new.

pregMatch() public method

This method behaves like PHP's preg_match() but with some exception. Since it is possible to have multi valued attributes the $matches array will have a additionally numerical dimension (one for each value):


$matches = array(
        0 => array (usual preg_match() returned array),
        1 => array (usual preg_match() returned array)
)

$matches will always be initialized to an empty array inside. Usage example:


try {
    if ($entry->pregMatch('/089(\d+)/', 'telephoneNumber', $matches)) {
Match of value 1, content of first bracket
        echo 'First match: ' . $matches[0][1];
    } else {
        echo 'No match found.';
    }
} catch (Horde_Ldap_Exception $e) {
    echo 'Error: ' . $e->getMessage();
}

public pregMatch ( string $regex, string $attr_name, array &$matches = [] ) : boolean
$regex	string	The regular expression.
$attr_name	string	The attribute to search in.
$matches	array	Array to store matches in.
return	boolean	True if we had a match in one of the values.

replace() public method

The parameter has to an array of the following form:


array('attributename' => 'single value',
      'attribute2name' => array('value1', 'value2'),
      'deleteme1' => null,
      'deleteme2' => '')

If the attribute does not yet exist it will be added instead (see also $force). If the attribue value is null, the attribute will de deleted. These changes are local to the entry and do not affect the entry on the server until {@link update()} is called. In some cases you are not allowed to read the attributes value (for example the ActiveDirectory attribute unicodePwd) but are allowed to replace the value. In this case replace() would assume that the attribute is not in the directory yet and tries to add it which will result in an LDAP_TYPE_OR_VALUE_EXISTS error. To force replace mode instead of add, you can set $force to true.

public replace ( array $attr = [], boolean $force = false )
$attr	array	Attributes to replace.
$force	boolean	Force replacing mode in case we can't read the attribute value but are allowed to replace it.

setLDAP() public method

After setting a Horde_Ldap object, calling update() will use that object for updating directory contents. Use this to dynamicly switch directories.

public setLDAP ( Horde_Ldap $ldap )
$ldap	Horde_Ldap	Horde_Ldap object that this entry should be connected to.

update() public method

This will evaluate all changes made so far and send them to the directory server. If you make changes to objectclasses wich have mandatory attributes set, update() will currently fail. Remove the entry from the server and readd it as new in such cases. This also will deal with problems with setting structural object classes.

public update ( )

willBeDeleted() public method

Is this entry going to be deleted once update() is called?

public willBeDeleted ( ) : boolean
return	boolean	True if this entry is going to be deleted.

willBeMoved() public method

Is this entry going to be moved once update() is called?

public willBeMoved ( ) : boolean
return	boolean	True if this entry is going to be move.

Property Details

$_attributes protected property

Attributes.

protected array $_attributes
return	array

$_changes protected property

Map with changes to the entry.

protected array $_changes
return	array

$_delete protected property

Shall the entry be deleted?

protected bool $_delete
return	boolean

$_dn protected property

Distinguished name of the entry.

protected string $_dn
return	string

$_entry protected property

Entry resource identifier.

protected resource $_entry
return	resource

$_ldap protected property

This object will be used for updating and schema checking.

protected Horde_Ldap $_ldap
return	Horde_Ldap

$_link protected property

LDAP resource identifier.

protected resource $_link
return	resource

$_map protected property

Map of attribute names.

protected array $_map
return	array

$_new protected property

Is this a new entry?

protected bool $_new
return	boolean

$_newdn protected property

New distinguished name.

protected string $_newdn
return	string

$_original protected property

Original attributes before any modification.

protected array $_original
return	array