Horde_Ldap_Entry
in package
Horde_Ldap_Entry represents an LDAP entry.
Copyright 2003-2007 Tarjej Huse, Jan Wagner, Benedikt Hallinger Copyright 2009-2017 Horde LLC (http://www.horde.org/)
Tags
Table of Contents
- $_attributes : array<string|int, mixed>
- Attributes.
- $_changes : array<string|int, mixed>
- Map with changes to the entry.
- $_delete : bool
- Shall the entry be deleted?
- $_dn : string
- Distinguished name of the entry.
- $_entry : resource
- Entry resource identifier.
- $_ldap : Horde_Ldap
- Horde_Ldap object.
- $_link : resource
- LDAP resource identifier.
- $_map : array<string|int, mixed>
- Map of attribute names.
- $_new : bool
- Is this a new entry?
- $_newdn : string
- New distinguished name.
- $_original : array<string|int, mixed>
- Original attributes before any modification.
- add() : mixed
- Adds new attributes or a new values to existing attributes.
- attributes() : array<string|int, mixed>
- Returns an array of attributes names.
- createConnected() : Horde_Ldap_Entry
- Creates an entry object out of an LDAP entry resource.
- createExisting() : Horde_Ldap_Entry
- Creates an entry object that is considered to exist already.
- createFresh() : Horde_Ldap_Entry
- Creates a fresh entry that may be added to the directory later.
- currentDN() : string
- Returns always the original DN.
- delete() : mixed
- Deletes an attribute, a value or the whole entry.
- dn() : string
- Returns or sets the distinguished name of the entry.
- exists() : bool
- Returns whether an attribute exists or not.
- getChanges() : array<string|int, mixed>
- 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|array<string|int, mixed>
- Returns the value of a specific attribute.
- getValues() : array<string|int, mixed>
- Returns the values of all attributes in a hash.
- isNew() : bool
- Returns whether the entry is considered new (not present in the server).
- markAsNew() : mixed
- Marks the entry as new or existing.
- pregMatch() : bool
- Applies a regular expression onto a single- or multi-valued attribute (like preg_match()).
- replace() : mixed
- Replaces attributes or their values.
- setLDAP() : mixed
- Sets a reference to the LDAP object of this entry.
- update() : mixed
- Updates the entry on the directory server.
- willBeDeleted() : bool
- Is this entry going to be deleted once update() is called?
- willBeMoved() : bool
- Is this entry going to be moved once update() is called?
- __construct() : mixed
- Constructor.
- _getAttrName() : string
- Returns the right attribute name.
- _loadAttributes() : mixed
- Sets the internal attributes array.
Properties
$_attributes
Attributes.
protected
array<string|int, mixed>
$_attributes
= array()
$_changes
Map with changes to the entry.
protected
array<string|int, mixed>
$_changes
= array('add' => array(), 'delete' => array(), 'replace' => array())
$_delete
Shall the entry be deleted?
protected
bool
$_delete
= \false
$_dn
Distinguished name of the entry.
protected
string
$_dn
$_entry
Entry resource identifier.
protected
resource
$_entry
$_ldap
Horde_Ldap object.
protected
Horde_Ldap
$_ldap
This object will be used for updating and schema checking.
$_link
LDAP resource identifier.
protected
resource
$_link
$_map
Map of attribute names.
protected
array<string|int, mixed>
$_map
= array()
$_new
Is this a new entry?
protected
bool
$_new
= \true
$_newdn
New distinguished name.
protected
string
$_newdn
$_original
Original attributes before any modification.
protected
array<string|int, mixed>
$_original
= array()
Methods
add()
Adds new attributes or a new values to existing attributes.
public
add([array<string|int, mixed> $attr = array() ]) : mixed
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, and will only return the values you added, NOT all values present on the server. To avoid this, just refetch the entry after calling or select the attribute.
Parameters
- $attr : array<string|int, mixed> = array()
-
Attributes to add.
Return values
mixed —attributes()
Returns an array of attributes names.
public
attributes() : array<string|int, mixed>
Return values
array<string|int, mixed> —Array of attribute names.
createConnected()
Creates an entry object out of an LDAP entry resource.
public
static createConnected(Horde_Ldap $ldap, resource $entry) : Horde_Ldap_Entry
Use this method, if you want to initialize an entry object that is already present in some directory and that you have read manually.
Parameters
- $ldap : Horde_Ldap
-
Horde_Ldap object.
- $entry : resource
-
PHP LDAP entry resource.
Tags
Return values
Horde_Ldap_Entry —createExisting()
Creates an entry object that is considered to exist already.
public
static createExisting(string $dn[, array<string|int, mixed> $attrs = array() ]) : Horde_Ldap_Entry
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');
Parameters
- $dn : string
-
DN of the entry.
- $attrs : array<string|int, mixed> = array()
-
Attributes of the entry.
Tags
Return values
Horde_Ldap_Entry —createFresh()
Creates a fresh entry that may be added to the directory later.
public
static createFresh(string $dn[, array<string|int, mixed> $attrs = array() ]) : Horde_Ldap_Entry
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');
Parameters
- $dn : string
-
DN of the entry.
- $attrs : array<string|int, mixed> = array()
-
Attributes of the entry.
Tags
Return values
Horde_Ldap_Entry —currentDN()
Returns always the original DN.
public
currentDN() : string
If an entry will be moved but was not called, will return the new DN. This method however, returns always the current active DN.
Return values
string —The current DN
delete()
Deletes an attribute, a value or the whole entry.
public
delete([string|array<string|int, mixed> $attr = null ]) : mixed
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 is called.
You must select the attribute (at $ldap->search() for example) to be able to delete values of it, Otherwise will silently fail and remove nothing.
Parameters
- $attr : string|array<string|int, mixed> = null
-
Attributes to delete.
Return values
mixed —dn()
Returns or sets the distinguished name of the entry.
public
dn([string $dn = null ]) : string
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 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 to retrieve the DN that is currently active.
Parameters
- $dn : string = null
-
New distinguished name.
Tags
Return values
string —Distinguished name.
exists()
Returns whether an attribute exists or not.
public
exists(string $attr) : bool
Parameters
- $attr : string
-
Attribute name.
Return values
bool —True if the attribute exists.
getChanges()
Returns the attribute changes to be carried out once update() is called.
public
getChanges() : array<string|int, mixed>
Return values
array<string|int, mixed> —The due changes.
getLDAP()
Returns a reference to the LDAP-Object of this entry.
public
getLDAP() : Horde_Ldap
Tags
Return values
Horde_Ldap —Reference to the Horde_Ldap object (the connection).
getValue()
Returns the value of a specific attribute.
public
getValue(string $attr[, string $option = null ]) : string|array<string|int, mixed>
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.
Parameters
- $attr : string
-
Attribute name.
- $option : string = null
-
Option.
Tags
Return values
string|array<string|int, mixed> —Attribute value(s).
getValues()
Returns the values of all attributes in a hash.
public
getValues() : array<string|int, mixed>
The returned hash has the form
array('attributename' => 'single value',
'attributename' => array('value1', value2', value3'))
Tags
Return values
array<string|int, mixed> —Hash of all attributes with their values.
isNew()
Returns whether the entry is considered new (not present in the server).
public
isNew() : bool
This method doesn't tell you if the entry is really not present on the server. Use to see if an entry is already there.
Return values
bool —True if this is considered a new entry.
markAsNew()
Marks the entry as new or existing.
public
markAsNew([bool $mark = true ]) : mixed
If an entry is marked as new, it will be added to the directory when calling .
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 .
Parameters
- $mark : bool = true
-
Whether to mark the entry as new.
Return values
mixed —pregMatch()
Applies a regular expression onto a single- or multi-valued attribute (like preg_match()).
public
pregMatch(string $regex, string $attr_name[, array<string|int, mixed> &$matches = array() ]) : bool
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();
}
Parameters
- $regex : string
-
The regular expression.
- $attr_name : string
-
The attribute to search in.
- $matches : array<string|int, mixed> = array()
-
Array to store matches in.
Tags
Return values
bool —True if we had a match in one of the values.
replace()
Replaces attributes or their values.
public
replace([array<string|int, mixed> $attr = array() ][, bool $force = false ]) : mixed
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 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.
Parameters
- $attr : array<string|int, mixed> = array()
-
Attributes to replace.
- $force : bool = false
-
Force replacing mode in case we can't read the attribute value but are allowed to replace it.
Return values
mixed —setLDAP()
Sets a reference to the LDAP object of this entry.
public
setLDAP(Horde_Ldap $ldap) : mixed
After setting a Horde_Ldap object, calling update() will use that object for updating directory contents. Use this to dynamicly switch directories.
Parameters
- $ldap : Horde_Ldap
-
Horde_Ldap object that this entry should be connected to.
Tags
Return values
mixed —update()
Updates the entry on the directory server.
public
update() : mixed
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.
Tags
Return values
mixed —willBeDeleted()
Is this entry going to be deleted once update() is called?
public
willBeDeleted() : bool
Return values
bool —True if this entry is going to be deleted.
willBeMoved()
Is this entry going to be moved once update() is called?
public
willBeMoved() : bool
Return values
bool —True if this entry is going to be move.
__construct()
Constructor.
protected
__construct(Horde_Ldap|resource|array<string|int, mixed> $ldap[, string|resource $entry = null ]) : mixed
Sets up the distinguished name and the entries attributes.
Parameters
- $ldap : Horde_Ldap|resource|array<string|int, mixed>
-
Horde_Ldap object, LDAP connection resource or array of attributes.
- $entry : string|resource = null
-
Either a DN or a LDAP entry resource.
Return values
mixed —_getAttrName()
Returns the right attribute name.
protected
_getAttrName(string $attr) : string
Parameters
- $attr : string
-
Name of attribute.
Return values
string —The right name of the attribute
_loadAttributes()
Sets the internal attributes array.
protected
_loadAttributes([array<string|int, mixed> $attributes = null ]) : mixed
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.
Parameters
- $attributes : array<string|int, mixed> = null
-
Attributes to set for this entry.