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


Classes:
Net_LDAP2
Net_LDAP2_Entry
Net_LDAP2_Error
Net_LDAP2_Filter
Net_LDAP2_LDIF
Net_LDAP2_RootDSE
Net_LDAP2_Schema
Net_LDAP2_Search
Net_LDAP2_Util
Files:
add_entry.php
connecting.php
Entry.php
fetch_entry.php
Filter.php
LDAP2.php
LDIF.php
modify_entry.php
modify_entry2.php
RootDSE.php
Schema.php
SchemaCache.interface.php
schema_cache.php
Search.php
search_entries.php
SimpleFileSchemaCache.php
Util.php

Class: Net_LDAP2

Source Location: /Net_LDAP2-2.2.0/Net/LDAP2.php

Class Overview

PEAR
   |
   --Net_LDAP2

Net_LDAP2 - manipulate LDAP servers the right way!


Author(s):

Copyright:

  • 2003-2007 Tarjej Huse, Jan Wagner, Del Elson, Benedikt Hallinger

Variables

Methods

Inherited Variables

Inherited Methods

Class Details

[line 57]
Net_LDAP2 - manipulate LDAP servers the right way!


[ Top ]

Class Variables

$_config = array('host'            => 'localhost',
                               'port'            => 389,
                               'version'         => 3,
                               'starttls'        => false,
                               'binddn'          => '',
                               'bindpw'          => '',
                               'basedn'          => '',
                               'options'         => array(),'filter'=>'(objectClass=*)','scope'=>'sub','auto_reconnect'=>false,'min_backoff'=>1,'current_backoff'=>1,'max_backoff'=>32)

[line 88]

Class configuration array

host = the ldap host to connect to (may be an array of several hosts to try) port = the server port version = ldap version (defaults to v 3) starttls = when set, ldap_start_tls() is run after connecting. bindpw = no explanation needed binddn = the DN to bind as. basedn = ldap base options = hash of ldap options to set (opt => val) filter = default search filter scope = default search scope

Newly added in 2.0.0RC4, for auto-reconnect: auto_reconnect = if set to true then the class will automatically attempt to reconnect to the LDAP server in certain failure conditionswhen attempting a search, or other LDAP operation. Defaults to false. Note that if you set this to true, calls to search() may block indefinitely if there is a catastrophic server failure. min_backoff = minimum reconnection delay period (in seconds). current_backoff = initial reconnection delay period (in seconds). max_backoff = maximum reconnection delay period (in seconds).

  • Access: protected

Type:   array


[ Top ]

$_down_host_list = array()

[line 117]

List of hosts that are known to be down.
  • Access: protected

Type:   array


[ Top ]

$_host_list = array()

[line 109]

List of hosts we try to establish a connection to
  • Access: protected

Type:   array


[ Top ]

$_link =  false

[line 125]

LDAP resource link.
  • Access: protected

Type:   resource


[ Top ]

$_rootDSE_cache = array()

[line 167]

Cache for rootDSE objects

Hash with requested rootDSE attr names as key and rootDSE object as value

Since the RootDSE object itself may request a rootDSE object, rootDse() caches successful requests. Internally, Net_LDAP2 needs several lookups to this object, so caching increases performance significally.

  • Access: protected

Type:   array


[ Top ]

$_schema =  null

[line 135]

Net_LDAP2_Schema object

This gets set and returned by schema()

  • Access: protected

Type:   object Net_LDAP2_Schema


[ Top ]

$_schemaAttrs = array()

[line 152]

Cache for attribute encoding checks
  • Var: Hash with attribute names as key and boolean value to determine whether they should be utf8 encoded or not.
  • Access: protected

Type:   array


[ Top ]

$_schema_cache =  null

[line 143]

Schema cacher function callback

Type:   string


[ Top ]


Method Detail

__construct (Constructor)   [line 230]

void __construct( [array $config = array()])

Net_LDAP2 constructor

Sets the config array

Please note that the usual way of getting Net_LDAP2 to work is to call something like: 

  1. $ldap = Net_LDAP2::connect($ldap_config);
    2.


Parameters:

array   $config   —  Configuration array

[ Top ]

_Net_LDAP2 (Destructor)   [line 699]

void _Net_LDAP2( )

Destructor
  • Access: public

[ Top ]

add   [line 715]

Net_LDAP2_Error|true add( Net_LDAP2_Entry $entry)

Add a new entryobject to a directory.

Use add to add a new Net_LDAP2_Entry object to the directory. This also links the entry to the connection used for the add, if it was a fresh entry (Net_LDAP2_Entry::createFresh())

  • Return: Net_LDAP2_Error object or true
  • Access: public

Parameters:

Net_LDAP2_Entry   $entry   —  Net_LDAP2_Entry

[ Top ]

bind   [line 315]

Net_LDAP2_Error|true bind( [string $dn = null], [string $password = null])

Bind or rebind to the ldap-server

This function binds with the given dn and password to the server. In case no connection has been made yet, it will be started and startTLS issued if appropiate.

The internal bind configuration is not being updated, so if you call bind() without parameters, you can rebind with the credentials provided at first connecting to the server.

  • Return: Net_LDAP2_Error object or true
  • Access: public

Parameters:

string   $dn   —  Distinguished name for binding
string   $password   —  Password for binding

[ Top ]

checkLDAPExtension   [line 1630]

Net_LDAP2_Error|true checkLDAPExtension( )

Checks if phps ldap-extension is loaded

If it is not loaded, it tries to load it manually using PHPs dl(). It knows both windows-dll and *nix-so.

  • Access: public

[ Top ]

connect   [line 195]

Net_LDAP2_Error|Net_LDAP2 connect( [array $config = array()])

Configure Net_LDAP2, connect and bind

Use this method as starting point of using Net_LDAP2 to establish a connection to your LDAP server.

Static function that returns either an error object or the new Net_LDAP2 object. Something like a factory. Takes a config array with the needed parameters.

  • Return: Net_LDAP2_Error or Net_LDAP2 object
  • Access: public

Parameters:

array   $config   —  Configuration array

[ Top ]

copy   [line 1382]

Net_LDAP2_Error|Net_LDAP2_Entry copy( Net_LDAP2_Entry $entry, string $newdn)

Copy an entry to a new location

The entry will be immediately copied. Please note that only attributes you have selected will be copied.

  • Return: Error Message or reference to the copied entry
  • Access: public

Parameters:

Net_LDAP2_Entry   $entry   —  Entry object
string   $newdn   —  New FQF-DN of the entry

[ Top ]

delete   [line 782]

Net_LDAP2_Error|true delete( string|Net_LDAP2_Entry $dn, [boolean $recursive = false])

Delete an entry from the directory

The object may either be a string representing the dn or a Net_LDAP2_Entry object. When the boolean paramter recursive is set, all subentries of the entry will be deleted as well.

  • Return: Net_LDAP2_Error object or true
  • Access: public

Parameters:

string|Net_LDAP2_Entry   $dn   —  DN-string or Net_LDAP2_Entry
boolean   $recursive   —  Should we delete all children recursive as well?

[ Top ]

disconnect   [line 689]

void disconnect( )

Alias for done()

[ Top ]

dnExists   [line 1247]

boolean|Net_LDAP2_Error dnExists( string|Net_LDAP2_Entry $dn)

Tells if a DN does exist in the directory
  • Access: public

Parameters:

string|Net_LDAP2_Entry   $dn   —  The DN of the object to test

[ Top ]

done   [line 678]

void done( )

Close LDAP connection.

Closes the connection. Use this when the session is over.

  • Access: public

[ Top ]

errorMessage   [line 1411]

string errorMessage( int $errorcode)

Returns the string for an ldap errorcode.

Made to be able to make better errorhandling Function based on DB::errorMessage() Tip: The best description of the errorcodes is found here: http://www.directory-info.com/LDAP2/LDAPErrorCodes.html

  • Return: The errorstring for the error.
  • Access: public

Parameters:

int   $errorcode   —  Error code

[ Top ]

getEntry   [line 1286]

Net_LDAP2_Entry|Net_LDAP2_Error getEntry( string $dn, [array $attr = array()])

Get a specific entry based on the DN
  • Return: Reference to a Net_LDAP2_Entry object or Net_LDAP2_Error object
  • Todo: Maybe check against the shema should be done to be sure the attribute type exists
  • Access: public

Parameters:

string   $dn   —  DN of the entry that should be fetched
array   $attr   —  Array of Attributes to select. If ommitted, all attributes are fetched.

[ Top ]

getLDAPVersion   [line 1186]

int getLDAPVersion( )

Get the LDAP_PROTOCOL_VERSION that is used on the connection.

A lot of ldap functionality is defined by what protocol version the ldap server speaks. This might be 2 or 3.

  • Access: public

[ Top ]

getLink   [line 1749]

resource getLink( )

Get the LDAP link resource. It will loop attempting to re-establish the connection if the connection attempt fails and auto_reconnect has been turned on (see the _config array documentation).
  • Return: LDAP link
  • Access: public

[ Top ]

getOption   [line 1154]

Net_LDAP2_Error|string getOption( string $option)

Get an LDAP option value
  • Return: Net_LDAP2_Error or option value
  • Access: public

Parameters:

string   $option   —  Option to get

[ Top ]

getVersion   [line 175]

string getVersion( )

Returns the Net_LDAP2 Release version, may be called statically
  • Return: Net_LDAP2 version
  • Access: public

[ Top ]

modify   [line 887]

Net_LDAP2_Error|true modify( string|Net_LDAP2_Entry $entry, [array $parms = array()])

Modify an ldapentry directly on the server

This one takes the DN or a Net_LDAP2_Entry object and an array of actions. This array should be something like this:

array('add' => array('attribute1' => array('val1', 'val2'), 'attribute2' => array('val1')), 'delete' => array('attribute1'), 'replace' => array('attribute1' => array('val1')), 'changes' => array('add' => ..., 'replace' => ..., 'delete' => array('attribute1', 'attribute2' => array('val1')))

The changes array is there so the order of operations can be influenced (the operations are done in order of appearance). The order of execution is as following:

  1. adds from 'add' array
  2. deletes from 'delete' array
  3. replaces from 'replace' array
  4. changes (add, replace, delete) in order of appearance
All subarrays (add, replace, delete, changes) may be given at the same time.

The function calls the corresponding functions of an Net_LDAP2_Entry object. A detailed description of array structures can be found there.

Unlike the modification methods provided by the Net_LDAP2_Entry object, this method will instantly carry out an update() after each operation, thus modifying "directly" on the server.

  • Return: Net_LDAP2_Error object or true
  • Access: public

Parameters:

string|Net_LDAP2_Entry   $entry   —  DN-string or Net_LDAP2_Entry
array   $parms   —  Array of changes

[ Top ]

move   [line 1325]

Net_LDAP2_Error|true move( string|Net_LDAP2_Entry $entry, string $newdn, [Net_LDAP2 $target_ldap = null])

Rename or move an entry

This method will instantly carry out an update() after the move, so the entry is moved instantly. You can pass an optional Net_LDAP2 object. In this case, a cross directory move will be performed which deletes the entry in the source (THIS) directory and adds it in the directory $target_ldap. A cross directory move will switch the Entrys internal LDAP reference so updates to the entry will go to the new directory.

Note that if you want to do a cross directory move, you need to pass an Net_LDAP2_Entry object, otherwise the attributes will be empty.

  • Access: public

Parameters:

string|Net_LDAP2_Entry   $entry   —  Entry DN or Entry object
string   $newdn   —  New location
Net_LDAP2   $target_ldap   —  (optional) Target directory for cross server move; should be passed via reference

[ Top ]

performConnect   [line 377]

Net_LDAP2_Error|true performConnect( )

Connect to the ldap-server

This function connects to the LDAP server specified in the configuration, binds and set up the LDAP protocol as needed.

  • Return: Net_LDAP2_Error object or true
  • Access: protected

[ Top ]

performReconnect   [line 557]

Net_LDAP2_Error|true performReconnect( )

Reconnect to the ldap-server.

In case the connection to the LDAP service has dropped out for some reason, this function will reconnect, and re-bind if a bind has been attempted in the past. It is probably most useful when the server list provided to the new() or connect() function is an array rather than a single host name, because in that case it will be able to connect to a failover or secondary server in case the primary server goes down.

This doesn't return anything, it just tries to re-establish the current connection. It will sleep for the current backoff period (seconds) before attempting the connect, and if the connection fails it will double the backoff period, but not try again. If you want to ensure a reconnection during a transient period of server downtime then you need to call this function in a loop.

  • Return: Net_LDAP2_Error object or true
  • Access: protected

[ Top ]

registerSchemaCache   [line 1609]

true|Net_LDAP2_Error registerSchemaCache( Net_LDAP2_SchemaCache|null $cache)

Enable/disable persistent schema caching

Sometimes it might be useful to allow your scripts to cache the schema information on disk, so the schema is not fetched every time the script runs which could make your scripts run faster.

This method allows you to register a custom object that implements your schema cache. Please see the SchemaCache interface (SchemaCache.interface.php) for informations on how to implement this. To unregister the cache, pass null as $cache parameter.

For ease of use, Net_LDAP2 provides a simple file based cache which is used in the example below. You may use this, for example, to store the schema in a linux tmpfs which results in the schema beeing cached inside the RAM which allows nearly instant access. 

  1.     // Create the simple file cache object that comes along with Net_LDAP2
    2. 

  2.     $mySchemaCache_cfg = array(
    3. 

  3.       'path'    =>  '/tmp/Net_LDAP2_Schema.cache',
    4. 

  4.       'max_age' =>  86400   // max age is 24 hours (in seconds)
    5. 

  5.     );
    6. 

  6.     $mySchemaCache = new Net_LDAP2_SimpleFileSchemaCache($mySchemaCache_cfg);
    7. 

  7.     $ldap = new Net_LDAP2::connect(...);
    8. 

  8.     $ldap->registerSchemaCache($mySchemaCache); // enable caching
    9. 

  9.     // now each call to $ldap->schema() will get the schema from disk!
    10.

  • Access: public

Parameters:

Net_LDAP2_SchemaCache|null   $cache   —  Object implementing the Net_LDAP2_SchemaCache interface

[ Top ]

rootDse   [line 1494]

Net_LDAP2_Error|Net_LDAP2_RootDSE rootDse( [array $attrs = null])

Gets a rootDSE object

This either fetches a fresh rootDSE object or returns it from the internal cache for performance reasons, if possible.

  • Return: Net_LDAP2_Error or Net_LDAP2_RootDSE object
  • Access: public

Parameters:

array   $attrs   —  Array of attributes to search for

[ Top ]

root_dse   [line 1523]

Net_LDAP2_Error|Net_LDAP2_RootDSE root_dse( )

Alias function of rootDse() for perl-ldap interface

[ Top ]

schema   [line 1537]

Net_LDAP2_Schema|Net_LDAP2_Error schema( [string $dn = null])

Get a schema object
  • Return: Net_LDAP2_Schema or Net_LDAP2_Error object
  • Access: public

Parameters:

string   $dn   —  (optional) Subschema entry dn

[ Top ]

search   [line 1025]

Net_LDAP2_Search|Net_LDAP2_Error search( [string|Net_LDAP2_Entry $base = null], [string|Net_LDAP2_Filter $filter = null], [array $params = array()])

Run a ldap search query

Search is used to query the ldap-database. $base and $filter may be ommitted. The one from config will then be used. $base is either a DN-string or an Net_LDAP2_Entry object in which case its DN willb e used.

Params may contain:

scope: The scope which will be used for searching base - Just one entry sub - The whole tree one - Immediately below $base sizelimit: Limit the number of entries returned (default: 0 = unlimited), timelimit: Limit the time spent for searching (default: 0 = unlimited), attrsonly: If true, the search will only return the attribute names, attributes: Array of attribute names, which the entry should contain. It is good practice to limit this to just the ones you need. [NOT IMPLEMENTED] deref: By default aliases are dereferenced to locate the base object for the search, but not when searching subordinates of the base object. This may be changed by specifying one of the following values:

never - Do not dereference aliases in searching or in locating the base object of the search. search - Dereference aliases in subordinates of the base object in searching, but not in locating the base object of the search. find always

Please note, that you cannot override server side limitations to sizelimit and timelimit: You can always only lower a given limit.

  • Return: Net_LDAP2_Search object or Net_LDAP2_Error object
  • Todo: implement search controls (sorting etc)
  • Access: public

Parameters:

string|Net_LDAP2_Entry   $base   —  LDAP searchbase
string|Net_LDAP2_Filter   $filter   —  LDAP search filter or a Net_LDAP2_Filter object
array   $params   —  Array of options

[ Top ]

setConfig   [line 244]

void setConfig( array $config)

Sets the internal configuration array
  • Access: protected

Parameters:

array   $config   —  Configuration array

[ Top ]

setLDAPVersion   [line 1205]

Net_LDAP2_Error|true setLDAPVersion( [int $version = 0], [boolean $force = false])

Set the LDAP_PROTOCOL_VERSION that is used on the connection.
  • Return: Net_LDAP2_Error object or true
  • Todo: Checking via the rootDSE takes much time - why? fetching and instanciation is quick!
  • Access: public

Parameters:

int   $version   —  LDAP-version that should be used
boolean   $force   —  If set to true, the check against the rootDSE will be skipped

[ Top ]

setOption   [line 1122]

Net_LDAP2_Error|true setOption( string $option, mixed $value)

Set an LDAP option
  • Return: Net_LDAP2_Error object or true
  • Access: public

Parameters:

string   $option   —  Option to set
mixed   $value   —  Value to set Option to

[ Top ]

startTLS   [line 613]

Net_LDAP2_Error|true startTLS( )

Starts an encrypted session
  • Return: Net_LDAP2_Error object or true
  • Access: public

[ Top ]

start_tls   [line 665]

void start_tls( )

alias function of startTLS() for perl-ldap interface

[ Top ]

utf8   [line 1687]

array|Net_LDAP2_Error utf8( array $attributes, array $function)

Encodes or decodes UTF-8/ISO-8859-1 attribute values if needed by schema
  • Return: Array of attributes with function applied to values or Error
  • Access: protected

Parameters:

array   $attributes   —  Array of attributes
array   $function   —  Function to apply to attribute values

[ Top ]

utf8Decode   [line 1673]

array|Net_LDAP2_Error utf8Decode( array $attributes)

Decodes the given attribute values from UTF-8 to ISO-8859-1 if needed by schema

$attributes is expected to be an array with keys describing the attribute names and the values as the value of this attribute: 

  1. $attributes = array('cn' => 'foo', 'attr2' => array('mv1', 'mv2'));
    2.


Parameters:

array   $attributes   —  Array of attributes

[ Top ]

utf8Encode   [line 1655]

array|Net_LDAP2_Error utf8Encode( array $attributes)

Encodes given attributes from ISO-8859-1 to UTF-8 if needed by schema

This function takes attributes in an array and then checks against the schema if they need UTF8 encoding. If that is so, they will be encoded. An encoded array will be returned and can be used for adding or modifying.

$attributes is expected to be an array with keys describing the attribute names and the values as the value of this attribute: 

  1. $attributes = array('cn' => 'foo', 'attr2' => array('mv1', 'mv2'));
    2.

  • Return: Array of UTF8 encoded attributes or Error
  • Access: public

Parameters:

array   $attributes   —  Array of attributes

[ Top ]
Documentation generated on Mon, 11 Mar 2019 16:03:54 -0400 by phpDocumentor 1.4.4. PEAR Logo Copyright © PHP Group 2004.