Net_LDAP2
[ class tree: Net_LDAP2 ] [ index: Net_LDAP2 ] [ all elements ]

Class: Net_LDAP2_Entry

Source Location: /Net_LDAP2-2.1.0/Net/LDAP2/Entry.php

Class Overview

PEAR
   |
   --Net_LDAP2_Entry

Object representation of a directory entry


Author(s):

Variables

Methods


Inherited Variables

Inherited Methods


Class Details

[line 39]
Object representation of a directory entry

This class represents a directory entry. You can add, delete, replace attributes and their values, rename the entry, delete the entry.



[ Top ]


Class Variables

$_attributes = array()

[line 81]

Attributes
  • Access: protected

Type:   array


[ Top ]

$_changes = array("add"     => array(),"delete"=>array(),"replace"=>array())

[line 131]

Map with changes to the entry
  • Access: protected

Type:   array


[ Top ]

$_delete =  false

[line 123]

Shall the entry be deleted?
  • Access: protected

Type:   boolean


[ Top ]

$_dn =  null

[line 73]

Distinguished name of the entry
  • Access: protected

Type:   string


[ Top ]

$_entry =  null

[line 47]

Entry ressource identifier
  • Access: protected

Type:   ressource


[ Top ]

$_ldap =  null

[line 65]

Net_LDAP2 object

This object will be used for updating and schema checking

  • Access: protected

Type:   object Net_LDAP2


[ Top ]

$_link =  null

[line 55]

LDAP ressource identifier
  • Access: protected

Type:   ressource


[ Top ]

$_map = array()

[line 98]

Map of attribute names
  • Access: protected

Type:   array


[ Top ]

$_new =  true

[line 107]

Is this a new entry?
  • Access: protected

Type:   boolean


[ Top ]

$_newdn =  null

[line 115]

New distinguished name
  • Access: protected

Type:   string


[ Top ]

$_original = array()

[line 89]

Original attributes before any modification
  • Access: protected

Type:   array


[ Top ]



Method Detail

__construct (Constructor)   [line 149]

none __construct( Net_LDAP2|ressource|array &$ldap, [string|ressource $entry = null])

Internal Constructor

Constructor of the entry. Sets up the distinguished name and the entries attributes. You should not call this method manually! Use Net_LDAP2_Entry::createFresh() or Net_LDAP2_Entry::createConnected() instead!

  • Access: protected

Parameters:

Net_LDAP2|ressource|array   &$ldap     Net_LDAP2 object, ldap-link ressource or array of attributes
string|ressource   $entry     Either a DN or a LDAP-Entry ressource

[ Top ]

add   [line 556]

true|Net_LDAP2_Error add( [array $attr = array()])

Adds a new attribute or a new value to an existing attribute

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, else 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.

Note, that you can add values of attributes that you haven't selected, but if you do so, getValue() and getValues() will only return the values you added, _NOT_ all values present on the server. To avoid this, just refetch the entry after calling update() or select the attribute.

  • Access: public

Parameters:

array   $attr     Attributes to add

[ Top ]

attributes   [line 517]

array attributes( )

Returns an array of attributes names
  • Return: Array of attribute names
  • Access: public

[ Top ]

createConnected   [line 233]

Net_LDAP2_Entry|Net_LDAP2_Error createConnected( Net_LDAP2 $ldap, resource $entry)

Creates a Net_LDAP2_Entry object out of an ldap entry resource

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

Please note, that if you want to create an entry object that represents some already existing entry, you should use createExisting().

The method should be called statically: $entry = Net_LDAP2_Entry::createConnected();

  • Access: public

Parameters:

Net_LDAP2   $ldap     Net_LDA2 object
resource   $entry     PHP LDAP entry resource

[ Top ]

createExisting   [line 276]

Net_LDAP2_Entry|Net_LDAP2_Error createExisting( string $dn, [array $attrs = array()])

Creates an Net_LDAP2_Entry object that is considered already existing

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 Net_LDAP2->getEntry()!

Please note that 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.

This method is equal to calling createFresh() and after that markAsNew(FALSE).

The method should be called statically: $entry = Net_LDAP2_Entry::createExisting();

The attributes parameter is as following:

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

  • Access: public

Parameters:

string   $dn     DN of the Entry
array   $attrs     Attributes of the entry

[ Top ]

createFresh   [line 206]

Net_LDAP2_Entry|Net_LDAP2_Error createFresh( string $dn, [array $attrs = array()])

Creates a fresh entry that may be added to the directory later on

Use this method, if you want to initialize a fresh entry.

The method should be called statically: $entry = Net_LDAP2_Entry::createFresh(); 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:

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

  • Access: public

Parameters:

string   $dn     DN of the Entry
array   $attrs     Attributes of the entry

[ Top ]

currentDN   [line 1081]

string currentDN( )

Returns always the original DN

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

  • Access: public

[ Top ]

delete   [line 617]

true delete( [string|array $attr = null])

Deletes an whole attribute or a value or the whole entry

The parameter can be one of the following:

"attributename" - The attribute as a whole will be deleted array("attributename1", "attributename2) - All given attributes will be deleted array("attributename" => "value") - The value will be deleted array("attributename" => array("value1", "value2") - The given values will be deleted If $attr is null or omitted , then the whole Entry will be deleted!

These changes are local to the entry and do not affect the entry on the server until update() is called.

Please note that you must select the attribute (at $ldap->search() for example) to be able to delete values of it, Otherwise update() will silently fail and remove nothing.

  • Access: public

Parameters:

string|array   $attr     Attributes to delete (NULL or missing to delete whole entry)

[ Top ]

dn   [line 309]

string|true dn( [string $dn = null])

Get or set the distinguished name of the entry

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 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 currentDN() to retrieve the DN that is currently active.

Please note that special characters (eg german umlauts) should be encoded using utf8_encode(). You may use Net_LDAP2_Util::canonical_dn() for properly encoding of the DN.

  • Return: Distinguished name (or true if a new DN was provided)
  • Access: public

Parameters:

string   $dn     New distinguished name

[ Top ]

exists   [line 530]

boolean exists( string $attr)

Returns whether an attribute exists or not
  • Access: public

Parameters:

string   $attr     Attribute name

[ Top ]

getAttrName   [line 902]

string getAttrName( string $attr)

Returns the right attribute name
  • Return: The right name of the attribute
  • Access: protected

Parameters:

string   $attr     Name of attribute

[ Top ]

getChanges   [line 1091]

array getChanges( )

Returns the attribute changes to be carried out once update() is called
  • Access: public

[ Top ]

getLDAP   [line 917]

Net_LDAP2|Net_LDAP2_Error &getLDAP( )

Returns a reference to the LDAP-Object of this entry
  • Return: Reference to the Net_LDAP2 Object (the connection) or Net_LDAP2_Error
  • Access: public

[ Top ]

getValue   [line 460]

string|array getValue( string $attr, [string $option = null])

Get the value of a specific attribute

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 'default': 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

If the attribute is not set at this entry (no value or not defined in schema), "false" is returned when $option is 'single', an empty string if 'default', and an empty array when 'all'.

You may use Net_LDAP2_Schema->checkAttribute() to see if the attribute is defined for the objectClasses of this entry.

  • Access: public

Parameters:

string   $attr     Attribute name
string   $option     Option

[ Top ]

getValues   [line 427]

array getValues( )

Get the values of all attributes in a hash

The returned hash has the form

  1. array('attributename' => 'single value',
  2.        'attributename' => array('value1'value2', value3'))
Only attributes present at the entry will be returned.

  • Return: Hash of all attributes with their values
  • Access: public

[ Top ]

get_value   [line 505]

string|array|PEAR_Error get_value( )

Alias function of getValue for perl-ldap interface

[ Top ]

isNew   [line 1046]

boolean isNew( )

Tells if the entry is consiedered as new (not present in the server)

Please note, that this doesn't tell you if the entry is present on the server. Use Net_LDAP2::dnExists() to see if an entry is already there.

  • Access: public

[ Top ]

markAsNew   [line 961]

void markAsNew( [boolean $mark = true])

Marks the entry as new/existing.

If an Entry is marked as new, it will be added to the directory when calling 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 update().

  • Access: public

Parameters:

boolean   $mark     Value to set, defaults to "true"

[ Top ]

move   [line 332]

true move( string $newdn)

Renames or moves the entry

This is just a convinience alias to dn() to make your code more meaningful.

  • Access: public

Parameters:

string   $newdn     The new DN

[ Top ]

pregMatch   [line 1007]

boolean|Net_LDAP2_Error pregMatch( string $regex, string $attr_name, [array $matches = array()])

Applies a regular expression onto a single- or multivalued attribute (like preg_match())

This method behaves like PHPs preg_match() but with some exceptions. If you want to retrieve match information, then you MUST pass the $matches parameter via reference! otherwise you will get no matches. Since it is possible to have multi valued attributes the $matches array will have a additionally numerical dimension (one for each value):

  1.  $matches = array(
  2.          0 => array (usual preg_match(returnarray),
  3.          1 => array (usual preg_match(returnarray)
  4.      )
Please note, that $matches will be initialized to an empty array inside.

Usage example:

  1.  $result $entry->preg_match('/089(\d+)/''telephoneNumber'&$matches);
  2.  if $result === true ){
  3.      echo "First match: ".$matches[0][1];   // Match of value 1, content of first bracket
  4.  else {
  5.      if Net_LDAP2::isError($result) ) {
  6.          echo "Error: ".$result->getMessage();
  7.      else {
  8.          echo "No match found.";
  9.      }
  10.  }

Please note that it is important to test for an Net_LDAP2_Error, because objects are evaluating to true by default, thus if an error occured, and you only check using "==" then you get misleading results. Use the "identical" (===) operator to test for matches to avoid this as shown above.

  • Return: TRUE, if we had a match in one of the values, otherwise false. Net_LDAP2_Error in case something went wrong
  • Access: public

Parameters:

string   $regex     The regular expression
string   $attr_name     The attribute to search in
array   $matches     (optional, PASS BY REFERENCE!) Array to store matches in

[ Top ]

preg_match   [line 1032]

boolean|Net_LDAP2_Error preg_match( )

Alias of pregMatch() for compatibility to Net_LDAP 1

[ Top ]

replace   [line 706]

true|Net_LDAP2_Error replace( [array $attr = array()], [bool $force = false])

Replaces attributes or its values

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 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.

  • Access: public

Parameters:

array   $attr     Attributes to replace
bool   $force     Force replacing mode in case we can't read the attr value but are allowed to replace it

[ Top ]

setAttributes   [line 352]

void setAttributes( [array $attributes = null])

Sets the internal attributes array

This 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.

  • Access: protected

Parameters:

array   $attributes     Attributes to set for this entry

[ Top ]

setLDAP   [line 938]

true|Net_LDAP2_Error setLDAP( Net_LDAP2 &$ldap)

Sets a reference to the LDAP-Object of this entry

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

  • Access: public

Parameters:

Net_LDAP2   &$ldap     Net_LDAP2 object that this entry should be connected to

[ Top ]

update   [line 754]

true|Net_LDAP2_Error update( [Net_LDAP2 $ldap = null])

Update the entry on the directory server

This will evaluate all changes made so far and send them to the directory server. Please note, that 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.

  • Todo: Entry rename with a DN containing special characters needs testing!
  • Access: public

Parameters:

Net_LDAP2   $ldap     If passed, a call to setLDAP() is issued prior update, thus switching the LDAP-server. This is for perl-ldap interface compliance

[ Top ]

willBeDeleted   [line 1057]

boolean willBeDeleted( )

Is this entry going to be deleted once update() is called?
  • Access: public

[ Top ]

willBeMoved   [line 1067]

boolean willBeMoved( )

Is this entry going to be moved once update() is called?
  • Access: public

[ Top ]


Documentation generated on Mon, 09 Dec 2013 10:30:04 +0000 by phpDocumentor 1.4.3. PEAR Logo Copyright © PHP Group 2004.