Added Net_LDAP2 to extlib, and add a skeleton LDAP plugin

1 files changed, 1055 insertions, 0 deletions

diff --git a/extlib/Net/LDAP2/Entry.php b/extlib/Net/LDAP2/Entry.php
new file mode 100644
index 000000000..66de96678
--- /dev/null
+++ b/extlib/Net/LDAP2/Entry.php
@@ -0,0 +1,1055 @@
+<?php
+/* vim: set expandtab tabstop=4 shiftwidth=4: */
+/**
+* File containing the Net_LDAP2_Entry interface class.
+*
+* PHP version 5
+*
+* @category  Net
+* @package   Net_LDAP2
+* @author    Jan Wagner <wagner@netsols.de>
+* @author    Tarjej Huse <tarjei@bergfald.no>
+* @author    Benedikt Hallinger <beni@php.net>
+* @copyright 2009 Tarjej Huse, Jan Wagner, Benedikt Hallinger
+* @license   http://www.gnu.org/licenses/lgpl-3.0.txt LGPLv3
+* @version   SVN: $Id: Entry.php 286787 2009-08-04 06:03:12Z beni $
+* @link      http://pear.php.net/package/Net_LDAP2/
+*/
+
+/**
+* Includes
+*/
+require_once 'PEAR.php';
+require_once 'Util.php';
+
+/**
+* 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.
+*
+* @category Net
+* @package  Net_LDAP2
+* @author   Jan Wagner <wagner@netsols.de>
+* @author   Tarjej Huse <tarjei@bergfald.no>
+* @author   Benedikt Hallinger <beni@php.net>
+* @license  http://www.gnu.org/copyleft/lesser.html LGPL
+* @link     http://pear.php.net/package/Net_LDAP2/
+*/
+class Net_LDAP2_Entry extends PEAR
+{
+    /**
+    * Entry ressource identifier
+    *
+    * @access protected
+    * @var ressource
+    */
+    protected $_entry = null;
+
+    /**
+    * LDAP ressource identifier
+    *
+    * @access protected
+    * @var ressource
+    */
+    protected $_link = null;
+
+    /**
+    * Net_LDAP2 object
+    *
+    * This object will be used for updating and schema checking
+    *
+    * @access protected
+    * @var object Net_LDAP2
+    */
+    protected $_ldap = null;
+
+    /**
+    * Distinguished name of the entry
+    *
+    * @access protected
+    * @var string
+    */
+    protected $_dn = null;
+
+    /**
+    * Attributes
+    *
+    * @access protected
+    * @var array
+    */
+    protected $_attributes = array();
+
+    /**
+    * Original attributes before any modification
+    *
+    * @access protected
+    * @var array
+    */
+    protected $_original = array();
+
+
+    /**
+    * Map of attribute names
+    *
+    * @access protected
+    * @var array
+    */
+    protected $_map = array();
+
+
+    /**
+    * Is this a new entry?
+    *
+    * @access protected
+    * @var boolean
+    */
+    protected $_new = true;
+
+    /**
+    * New distinguished name
+    *
+    * @access protected
+    * @var string
+    */
+    protected $_newdn = null;
+
+    /**
+    * Shall the entry be deleted?
+    *
+    * @access protected
+    * @var boolean
+    */
+    protected $_delete = false;
+
+    /**
+    * Map with changes to the entry
+    *
+    * @access protected
+    * @var array
+    */
+    protected $_changes = array("add"     => array(),
+                                "delete"  => array(),
+                                "replace" => array()
+                               );
+    /**
+    * Internal Constructor
+    *
+    * Constructor of the entry. Sets up the distinguished name and the entries
+    * attributes.
+    * You should not call this method manually! Use {@link Net_LDAP2_Entry::createFresh()}
+    * or {@link Net_LDAP2_Entry::createConnected()} instead!
+    *
+    * @param Net_LDAP2|ressource|array &$ldap Net_LDAP2 object, ldap-link ressource or array of attributes
+    * @param string|ressource          $entry Either a DN or a LDAP-Entry ressource
+    *
+    * @access protected
+    * @return none
+    */
+    protected function __construct(&$ldap, $entry = null)
+    {
+        $this->PEAR('Net_LDAP2_Error');
+
+        // set up entry resource or DN
+        if (is_resource($entry)) {
+            $this->_entry = &$entry;
+        } else {
+            $this->_dn = $entry;
+        }
+
+        // set up LDAP link
+        if ($ldap instanceof Net_LDAP2) {
+            $this->_ldap = &$ldap;
+            $this->_link = $ldap->getLink();
+        } elseif (is_resource($ldap)) {
+            $this->_link = $ldap;
+        } elseif (is_array($ldap)) {
+            // Special case: here $ldap is an array of attributes,
+            // this means, we have no link. This is a "virtual" entry.
+            // We just set up the attributes so one can work with the object
+            // as expected, but an update() fails unless setLDAP() is called.
+            $this->setAttributes($ldap);
+        }
+
+        // if this is an entry existing in the directory,
+        // then set up as old and fetch attrs
+        if (is_resource($this->_entry) && is_resource($this->_link)) {
+            $this->_new = false;
+            $this->_dn  = @ldap_get_dn($this->_link, $this->_entry);
+            $this->setAttributes();  // fetch attributes from server
+        }
+    }
+
+    /**
+    * 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:
+    * <code>
+    * $attrs = array( 'attribute1' => array('value1', 'value2'),
+    *                 'attribute2' => 'single value'
+    *          );
+    * </code>
+    *
+    * @param string $dn    DN of the Entry
+    * @param array  $attrs Attributes of the entry
+    *
+    * @static
+    * @return Net_LDAP2_Entry|Net_LDAP2_Error
+    */
+    public static function createFresh($dn, $attrs = array())
+    {
+        if (!is_array($attrs)) {
+            return PEAR::raiseError("Unable to create fresh entry: Parameter \$attrs needs to be an array!");
+        }
+
+        $entry = new Net_LDAP2_Entry($attrs, $dn);
+        return $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 {@link createExisting()}.
+    *
+    * The method should be called statically: $entry = Net_LDAP2_Entry::createConnected();
+    *
+    * @param Net_LDAP2 $ldap  Net_LDA2 object
+    * @param resource  $entry PHP LDAP entry resource
+    *
+    * @static
+    * @return Net_LDAP2_Entry|Net_LDAP2_Error
+    */
+    public static function createConnected($ldap, $entry)
+    {
+        if (!$ldap instanceof Net_LDAP2) {
+            return PEAR::raiseError("Unable to create connected entry: Parameter \$ldap needs to be a Net_LDAP2 object!");
+        }
+        if (!is_resource($entry)) {
+            return PEAR::raiseError("Unable to create connected entry: Parameter \$entry needs to be a ldap entry resource!");
+        }
+
+        $entry = new Net_LDAP2_Entry($ldap, $entry);
+        return $entry;
+    }
+
+    /**
+    * 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:
+    * <code>
+    * $attrs = array( 'attribute1' => array('value1', 'value2'),
+    *                 'attribute2' => 'single value'
+    *          );
+    * </code>
+    *
+    * @param string $dn    DN of the Entry
+    * @param array  $attrs Attributes of the entry
+    *
+    * @static
+    * @return Net_LDAP2_Entry|Net_LDAP2_Error
+    */
+    public static function createExisting($dn, $attrs = array())
+    {
+        if (!is_array($attrs)) {
+            return PEAR::raiseError("Unable to create entry object: Parameter \$attrs needs to be an array!");
+        }
+
+        $entry = Net_LDAP2_Entry::createFresh($dn, $attrs);
+        if ($entry instanceof Net_LDAP2_Error) {
+            return $entry;
+        } else {
+            $entry->markAsNew(false);
+            return $entry;
+        }
+    }
+
+    /**
+    * 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 {@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.
+    *
+    * Please note that special characters (eg german umlauts) should be encoded using utf8_encode().
+    * You may use {@link Net_LDAP2_Util::canonical_dn()} for properly encoding of the DN.
+    *
+    * @param string $dn New distinguished name
+    *
+    * @access public
+    * @return string|true Distinguished name (or true if a new DN was provided)
+    */
+    public function dn($dn = null)
+    {
+        if (false == is_null($dn)) {
+            if (is_null($this->_dn)) {
+                $this->_dn = $dn;
+            } else {
+                $this->_newdn = $dn;
+            }
+            return true;
+        }
+        return (isset($this->_newdn) ? $this->_newdn : $this->currentDN());
+    }
+
+    /**
+    * Renames or moves the entry
+    *
+    * This is just a convinience alias to {@link dn()}
+    * to make your code more meaningful.
+    *
+    * @param string $newdn The new DN
+    *
+    * @return true
+    */
+    public function move($newdn)
+    {
+        return $this->dn($newdn);
+    }
+
+    /**
+    * 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.
+    *
+    * @param array $attributes Attributes to set for this entry
+    *
+    * @access protected
+    * @return void
+    */
+    protected function setAttributes($attributes = null)
+    {
+        /*
+        * fetch attributes from the server
+        */
+        if (is_null($attributes) && is_resource($this->_entry) && is_resource($this->_link)) {
+            // fetch schema
+            if ($this->_ldap instanceof Net_LDAP2) {
+                $schema =& $this->_ldap->schema();
+            }
+            // fetch attributes
+            $attributes = array();
+            do {
+                if (empty($attr)) {
+                    $ber  = null;
+                    $attr = @ldap_first_attribute($this->_link, $this->_entry, $ber);
+                } else {
+                    $attr = @ldap_next_attribute($this->_link, $this->_entry, $ber);
+                }
+                if ($attr) {
+                    $func = 'ldap_get_values'; // standard function to fetch value
+
+                    // Try to get binary values as binary data
+                    if ($schema instanceof Net_LDAP2_Schema) {
+                        if ($schema->isBinary($attr)) {
+                             $func = 'ldap_get_values_len';
+                        }
+                    }
+                    // fetch attribute value (needs error checking?)
+                    $attributes[$attr] = $func($this->_link, $this->_entry, $attr);
+                }
+            } while ($attr);
+        }
+
+        /*
+        * set attribute data directly, if passed
+        */
+        if (is_array($attributes) && count($attributes) > 0) {
+            if (isset($attributes["count"]) && is_numeric($attributes["count"])) {
+                unset($attributes["count"]);
+            }
+            foreach ($attributes as $k => $v) {
+                // attribute names should not be numeric
+                if (is_numeric($k)) {
+                    continue;
+                }
+                // map generic attribute name to real one
+                $this->_map[strtolower($k)] = $k;
+                // attribute values should be in an array
+                if (false == is_array($v)) {
+                    $v = array($v);
+                }
+                // remove the value count (comes from ldap server)
+                if (isset($v["count"])) {
+                    unset($v["count"]);
+                }
+                $this->_attributes[$k] = $v;
+            }
+        }
+
+        // save a copy for later use
+        $this->_original = $this->_attributes;
+    }
+
+    /**
+    * Get the values of all attributes in a hash
+    *
+    * The returned hash has the form
+    * <code>array('attributename' => 'single value',
+    *       'attributename' => array('value1', value2', value3'))</code>
+    *
+    * @access public
+    * @return array Hash of all attributes with their values
+    */
+    public function getValues()
+    {
+        $attrs = array();
+        foreach ($this->_attributes as $attr => $value) {
+            $attrs[$attr] = $this->getValue($attr);
+        }
+        return $attrs;
+    }
+
+    /**
+    * 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 including the value count 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 (without value count)
+    *
+    * @param string $attr   Attribute name
+    * @param string $option Option
+    *
+    * @access public
+    * @return string|array|PEAR_Error string, array or PEAR_Error
+    */
+    public function getValue($attr, $option = null)
+    {
+        $attr = $this->getAttrName($attr);
+
+        if (false == array_key_exists($attr, $this->_attributes)) {
+            return PEAR::raiseError("Unknown attribute ($attr) requested");
+        }
+
+        $value = $this->_attributes[$attr];
+
+        if ($option == "single" || (count($value) == 1 && $option != 'all')) {
+            $value = array_shift($value);
+        }
+
+        return $value;
+    }
+
+    /**
+    * Alias function of getValue for perl-ldap interface
+    *
+    * @see getValue()
+    * @return string|array|PEAR_Error
+    */
+    public function get_value()
+    {
+        $args = func_get_args();
+        return call_user_func_array(array( &$this, 'getValue' ), $args);
+    }
+
+    /**
+    * Returns an array of attributes names
+    *
+    * @access public
+    * @return array Array of attribute names
+    */
+    public function attributes()
+    {
+        return array_keys($this->_attributes);
+    }
+
+    /**
+    * Returns whether an attribute exists or not
+    *
+    * @param string $attr Attribute name
+    *
+    * @access public
+    * @return boolean
+    */
+    public function exists($attr)
+    {
+        $attr = $this->getAttrName($attr);
+        return array_key_exists($attr, $this->_attributes);
+    }
+
+    /**
+    * 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, {@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.
+    *
+    * @param array $attr Attributes to add
+    *
+    * @access public
+    * @return true|Net_LDAP2_Error
+    */
+    public function add($attr = array())
+    {
+        if (false == is_array($attr)) {
+            return PEAR::raiseError("Parameter must be an array");
+        }
+        foreach ($attr as $k => $v) {
+            $k = $this->getAttrName($k);
+            if (false == is_array($v)) {
+                // Do not add empty values
+                if ($v == null) {
+                    continue;
+                } else {
+                    $v = array($v);
+                }
+            }
+            // add new values to existing attribute or add new attribute
+            if ($this->exists($k)) {
+                $this->_attributes[$k] = array_unique(array_merge($this->_attributes[$k], $v));
+            } else {
+                $this->_map[strtolower($k)] = $k;
+                $this->_attributes[$k]      = $v;
+            }
+            // save changes for update()
+            if (empty($this->_changes["add"][$k])) {
+                $this->_changes["add"][$k] = array();
+            }
+            $this->_changes["add"][$k] = array_unique(array_merge($this->_changes["add"][$k], $v));
+        }
+        $return = true;
+        return $return;
+    }
+
+    /**
+    * 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 {@link 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 {@link update()} will silently fail
+    * and remove nothing.
+    *
+    * @param string|array $attr Attributes to delete (NULL or missing to delete whole entry)
+    *
+    * @access public
+    * @return true
+    */
+    public function delete($attr = null)
+    {
+        if (is_null($attr)) {
+            $this->_delete = true;
+            return true;
+        }
+        if (is_string($attr)) {
+            $attr = array($attr);
+        }
+        // Make the assumption that attribute names cannot be numeric,
+        // therefore this has to be a simple list of attribute names to delete
+        if (is_numeric(key($attr))) {
+            foreach ($attr as $name) {
+                if (is_array($name)) {
+                    // someone mixed modes (list mode but specific values given!)
+                    $del_attr_name = array_search($name, $attr);
+                    $this->delete(array($del_attr_name => $name));
+                } else {
+                    // mark for update() if this attr was not marked before
+                    $name = $this->getAttrName($name);
+                    if ($this->exists($name)) {
+                        $this->_changes["delete"][$name] = null;
+                        unset($this->_attributes[$name]);
+                    }
+                }
+            }
+        } else {
+            // Here we have a hash with "attributename" => "value to delete"
+            foreach ($attr as $name => $values) {
+                if (is_int($name)) {
+                    // someone mixed modes and gave us just an attribute name
+                    $this->delete($values);
+                } else {
+                    // mark for update() if this attr was not marked before;
+                    // this time it must consider the selected values also
+                    $name = $this->getAttrName($name);
+                    if ($this->exists($name)) {
+                        if (false == is_array($values)) {
+                            $values = array($values);
+                        }
+                        // save values to be deleted
+                        if (empty($this->_changes["delete"][$name])) {
+                            $this->_changes["delete"][$name] = array();
+                        }
+                        $this->_changes["delete"][$name] =
+                            array_unique(array_merge($this->_changes["delete"][$name], $values));
+                        foreach ($values as $value) {
+                            // find the key for the value that should be deleted
+                            $key = array_search($value, $this->_attributes[$name]);
+                            if (false !== $key) {
+                                // delete the value
+                                unset($this->_attributes[$name][$key]);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        $return = true;
+        return $return;
+    }
+
+    /**
+    * 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 {@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.
+    *
+    * @param array $attr  Attributes to replace
+    * @param bool  $force Force replacing mode in case we can't read the attr value but are allowed to replace it
+    *
+    * @access public
+    * @return true|Net_LDAP2_Error
+    */
+    public function replace($attr = array(), $force = false)
+    {
+        if (false == is_array($attr)) {
+            return PEAR::raiseError("Parameter must be an array");
+        }
+        foreach ($attr as $k => $v) {
+            $k = $this->getAttrName($k);
+            if (false == is_array($v)) {
+                // delete attributes with empty values; treat ints as string
+                if (is_int($v)) {
+                    $v = "$v";
+                }
+                if ($v == null) {
+                    $this->delete($k);
+                    continue;
+                } else {
+                    $v = array($v);
+                }
+            }
+            // existing attributes will get replaced
+            if ($this->exists($k) || $force) {
+                $this->_changes["replace"][$k] = $v;
+                $this->_attributes[$k]         = $v;
+            } else {
+                // new ones just get added
+                $this->add(array($k => $v));
+            }
+        }
+        $return = true;
+        return $return;
+    }
+
+    /**
+    * 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.
+    *
+    * @param 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
+    *
+    * @access public
+    * @return true|Net_LDAP2_Error
+    * @todo Entry rename with a DN containing special characters needs testing!
+    */
+    public function update($ldap = null)
+    {
+        if ($ldap) {
+            $msg = $this->setLDAP($ldap);
+            if (Net_LDAP2::isError($msg)) {
+                return PEAR::raiseError('You passed an invalid $ldap variable to update()');
+            }
+        }
+
+        // ensure we have a valid LDAP object
+        $ldap =& $this->getLDAP();
+        if (!$ldap instanceof Net_LDAP2) {
+            return PEAR::raiseError("The entries LDAP object is not valid");
+        }
+
+        // Get and check link
+        $link = $ldap->getLink();
+        if (!is_resource($link)) {
+            return PEAR::raiseError("Could not update entry: internal LDAP link is invalid");
+        }
+
+        /*
+        * Delete the entry
+        */
+        if (true === $this->_delete) {
+            return $ldap->delete($this);
+        }
+
+        /*
+        * New entry
+        */
+        if (true === $this->_new) {
+            $msg = $ldap->add($this);
+            if (Net_LDAP2::isError($msg)) {
+                return $msg;
+            }
+            $this->_new                = false;
+            $this->_changes['add']     = array();
+            $this->_changes['delete']  = array();
+            $this->_changes['replace'] = array();
+            $this->_original           = $this->_attributes;
+
+            $return = true;
+            return $return;
+        }
+
+        /*
+        * Rename/move entry
+        */
+        if (false == is_null($this->_newdn)) {
+            if ($ldap->getLDAPVersion() !== 3) {
+                return PEAR::raiseError("Renaming/Moving an entry is only supported in LDAPv3");
+            }
+            // make dn relative to parent (needed for ldap rename)
+            $parent = Net_LDAP2_Util::ldap_explode_dn($this->_newdn, array('casefolding' => 'none', 'reverse' => false, 'onlyvalues' => false));
+            if (Net_LDAP2::isError($parent)) {
+                return $parent;
+            }
+            $child = array_shift($parent);
+            // maybe the dn consist of a multivalued RDN, we must build the dn in this case
+            // because the $child-RDN is an array!
+            if (is_array($child)) {
+                $child = Net_LDAP2_Util::canonical_dn($child);
+            }
+            $parent = Net_LDAP2_Util::canonical_dn($parent);
+
+            // rename/move
+            if (false == @ldap_rename($link, $this->_dn, $child, $parent, true)) {
+                return PEAR::raiseError("Entry not renamed: " .
+                                        @ldap_error($link), @ldap_errno($link));
+            }
+            // reflect changes to local copy
+            $this->_dn    = $this->_newdn;
+            $this->_newdn = null;
+        }
+
+        /*
+        * Carry out modifications to the entry
+        */
+        // ADD
+        foreach ($this->_changes["add"] as $attr => $value) {
+            // if attribute exists, add new values
+            if ($this->exists($attr)) {
+                if (false === @ldap_mod_add($link, $this->dn(), array($attr => $value))) {
+                    return PEAR::raiseError("Could not add new values to attribute $attr: " .
+                                            @ldap_error($link), @ldap_errno($link));
+                }
+            } else {
+                // new attribute
+                if (false === @ldap_modify($link, $this->dn(), array($attr => $value))) {
+                    return PEAR::raiseError("Could not add new attribute $attr: " .
+                                            @ldap_error($link), @ldap_errno($link));
+                }
+            }
+            // all went well here, I guess
+            unset($this->_changes["add"][$attr]);
+        }
+
+        // DELETE
+        foreach ($this->_changes["delete"] as $attr => $value) {
+            // In LDAPv3 you need to specify the old values for deleting
+            if (is_null($value) && $ldap->getLDAPVersion() === 3) {
+                $value = $this->_original[$attr];
+            }
+            if (false === @ldap_mod_del($link, $this->dn(), array($attr => $value))) {
+                return PEAR::raiseError("Could not delete attribute $attr: " .
+                                        @ldap_error($link), @ldap_errno($link));
+            }
+            unset($this->_changes["delete"][$attr]);
+        }
+
+        // REPLACE
+        foreach ($this->_changes["replace"] as $attr => $value) {
+            if (false === @ldap_modify($link, $this->dn(), array($attr => $value))) {
+                return PEAR::raiseError("Could not replace attribute $attr values: " .
+                                        @ldap_error($link), @ldap_errno($link));
+            }
+            unset($this->_changes["replace"][$attr]);
+        }
+
+        // all went well, so _original (server) becomes _attributes (local copy)
+        $this->_original = $this->_attributes;
+
+        $return = true;
+        return $return;
+    }
+
+    /**
+    * Returns the right attribute name
+    *
+    * @param string $attr Name of attribute
+    *
+    * @access protected
+    * @return string The right name of the attribute
+    */
+    protected function getAttrName($attr)
+    {
+        $name = strtolower($attr);
+        if (array_key_exists($name, $this->_map)) {
+            $attr = $this->_map[$name];
+        }
+        return $attr;
+    }
+
+    /**
+    * Returns a reference to the LDAP-Object of this entry
+    *
+    * @access public
+    * @return Net_LDAP2|Net_LDAP2_Error   Reference to the Net_LDAP2 Object (the connection) or Net_LDAP2_Error
+    */
+    public function &getLDAP()
+    {
+        if (!$this->_ldap instanceof Net_LDAP2) {
+            $err = new PEAR_Error('LDAP is not a valid Net_LDAP2 object');
+            return $err;
+        } else {
+            return $this->_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.
+    *
+    * @param Net_LDAP2 &$ldap Net_LDAP2 object that this entry should be connected to
+    *
+    * @access public
+    * @return true|Net_LDAP2_Error
+    */
+    public function setLDAP(&$ldap)
+    {
+        if (!$ldap instanceof Net_LDAP2) {
+            return PEAR::raiseError("LDAP is not a valid Net_LDAP2 object");
+        } else {
+            $this->_ldap =& $ldap;
+            return true;
+        }
+    }
+
+    /**
+    * Marks the entry as new/existing.
+    *
+    * 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()}.
+    *
+    * @param boolean $mark Value to set, defaults to "true"
+    *
+    * @return void
+    */
+    public function markAsNew($mark = true)
+    {
+        $this->_new = ($mark)? true : false;
+    }
+
+    /**
+    * 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):
+    * <code>
+    * $matches = array(
+    *         0 => array (usual preg_match() returnarray),
+    *         1 => array (usual preg_match() returnarray)
+    *     )
+    * </code>
+    * Please note, that $matches will be initialized to an empty array inside.
+    *
+    * Usage example:
+    * <code>
+    * $result = $entry->preg_match('/089(\d+)/', 'telephoneNumber', &$matches);
+    * if ( $result === true ){
+    *     echo "First match: ".$matches[0][1];   // Match of value 1, content of first bracket
+    * } else {
+    *     if ( Net_LDAP2::isError($result) ) {
+    *         echo "Error: ".$result->getMessage();
+    *     } else {
+    *         echo "No match found.";
+    *     }
+    * }
+    * </code>
+    *
+    * 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.
+    *
+    * @param string $regex     The regular expression
+    * @param string $attr_name The attribute to search in
+    * @param array  $matches   (optional, PASS BY REFERENCE!) Array to store matches in
+    *
+    * @return boolean|Net_LDAP2_Error  TRUE, if we had a match in one of the values, otherwise false. Net_LDAP2_Error in case something went wrong
+    */
+    public function pregMatch($regex, $attr_name, $matches = array())
+    {
+        $matches = array();
+
+        // fetch attribute values
+        $attr = $this->getValue($attr_name, 'all');
+        if (Net_LDAP2::isError($attr)) {
+            return $attr;
+        } else {
+            unset($attr['count']);
+        }
+
+        // perform preg_match() on all values
+        $match = false;
+        foreach ($attr as $thisvalue) {
+            $matches_int = array();
+            if (preg_match($regex, $thisvalue, $matches_int)) {
+                $match = true;
+                array_push($matches, $matches_int); // store matches in reference
+            }
+        }
+        return $match;
+    }
+
+    /**
+    * Alias of {@link pregMatch()} for compatibility to Net_LDAP 1
+    *
+    * @see pregMatch()
+    * @return boolean|Net_LDAP2_Error
+    */
+    public function preg_match()
+    {
+        $args = func_get_args();
+        return call_user_func_array(array( &$this, 'pregMatch' ), $args);
+    }
+
+    /**
+    * 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 {@link Net_LDAP2::dnExists()} to see if an entry is already there.
+    *
+    * @return boolean
+    */
+    public function isNew()
+    {
+        return $this->_new;
+    }
+
+
+    /**
+    * Is this entry going to be deleted once update() is called?
+    *
+    * @return boolean
+    */
+    public function willBeDeleted()
+    {
+        return $this->_delete;
+    }
+
+    /**
+    * Is this entry going to be moved once update() is called?
+    *
+    * @return boolean
+    */
+    public function willBeMoved()
+    {
+        return ($this->dn() !== $this->currentDN());
+    }
+
+    /**
+    * Returns always the original DN
+    *
+    * 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.
+    *
+    * @return string
+    */
+    public function currentDN()
+    {
+        return $this->_dn;
+    }
+
+    /**
+    * Returns the attribute changes to be carried out once update() is called
+    *
+    * @return array
+    */
+    public function getChanges()
+    {
+        return $this->_changes;
+    }
+}
+?>