README

This is a fork of the original tiesa/ldap package. Credits to the original author Cyril Cottet for creating this great package!

This fork fixes some minor issues and adds LDAP paged result support. Please note that because of the paging support this package requires a higher PHP version (>= 5.4.22) than the original package. This package uses the same namespace as the original package and can be used as an easy replacement of the original package.

Install

Installing the component in your project is as simple as installing Composer if not already done so yet.

Then, under your project root folder, create a new file called composer.json and paste the following into it:

{
    "require": {
        "81square/tiesa-ldap": "dev-master"
    }
}

To select the component names & versions, you shall refer to information found at Packagist

Then you are ready to download all the vendor libraries and generate the autoloading configuration file:

$ php composer.phar install

From there, loading Ldap component classes as well as any other package supported in your composer.json configuration is as easy as adding the following code at the top of your script:

require_once '/path/to/project/vendor/autoload.php';

Usage

Connecting & Binding

A typical sequence for connecting to a LDAP involves not only establishing the connection to the server but also binding a user. This is done as follows:

<?php

use Toyota\Component\Ldap\Core\Manager;
use Toyota\Component\Ldap\Platform\Native\Driver;

$params = array(
    'hostname'      => 'ldap.example.com',
    'base_dn'       => 'dc=example,dc=com'
);
$manager = new Manager($params, new Driver());

$manager->connect();

// Anonymous binding
$manager->bind();

// Ready for searching & persisting information

Most of the times, you will have to use a privileged user to bind to the LDAP in order to perform persistence operations:

$manager->bind('cn=user,dc=example,dc=com', 'myTopSecretPassword');

If you are connecting to an Active Directory domain, you can also bind like this:

$manager->bind('user@example.com', 'myTopSecretPassword');

Connection Parameters

We have seen a minimal set of parameters in the connection & binding introduction. However, there are lots of configuration possibilities available:

hostname: FQDN for the LDAP server
port: Port to connect to on the LDAP server (default to 389 for regular and 636 for SSL connection)
security: One of SSL or TLS. When security is not set, the connection will be a plain one
bind_dn: Default distinguished name to use for binding (in that case, $manager->bind() will not be anonymous anymore)
bind_password: Default password to use for binding
options: LDAP options to enable by default for the connection (Refer to Toyota\Component\Ldap\API\ConnectionInterface)

Error Handling

All Ldap error codes and messages which are usually quite inconvenient to track (and are easily forgotten about) are handled with convenient exceptions for all LDAP operations.

NOTE: Just like the php ldap_connect function, the Manager's connect method will not actually connect. The actual connection is made during bind(). If your DC is unreachable or you provided the wrong connection configuration, you will get an exception on bind() and not on connect().

Hence, for instance, you can write the following:

<?php
// ... namespace imports and $params configuration
$manager = new Manager($params, new Driver());

try {
    $manager->connect();
} catch (ConnectionException $e) {
    // Do something about it
}

try {
    $manager->bind();
} catch (BindingException $e) {
    // Do something about it
}

// ...

All exceptions available are found in Toyota\Component\Ldap\Exception namespace

Search the LDAP

The most basic search as well as the most complex ones are all handled through a unique API. This is the end of the ldap_read or ldap_list or ldap_search dilemma:

<?php
// ... $manager connection & binding

// Whether to search through all subtree depth (Default = true)
$inDepth = true;

// Search
$results = $manager->search('ou=comp,dc=example,dc=com', '(objectclass=*)', $inDepth);

// A search result instance is retrieved which provides iteration capability for a convenient use
foreach ($results as $node) {
    echo $node->getDn();
    foreach ($node->getAttributes() as $attribute) {
        echo sprintf('%s => %s', $attribute->getName(), implode(',', $attribute->getValues()));
    }
}

Also for more convenience, the component offers a direct method to retrieve one node when you know its distinguished name:

<?php
$node = $manager->getNode('cn=my,ou=node,dc=example,dc=com');

Persist information to the LDAP

Forget about all the ldap_mod_add, ldap_mod_del, ldap_mod_replace, ldap_add and ldap_delete. The only things you'll need to remember about now are save() and delete(). The component will track all changes you make on a LDAP entry and will automagically issue the right function calls for just performing those changes in your directory:

<?php

$node = $manager->getNode('cn=node,ou=to,ou=update,dc=example,dc=com');
$node->get('username')->set('test_user');
$node->get('objectClass')->add('inetOrgPerson');
$node->get('sn')->set('Doe');
$node->removeAttribute('whatever');

$manager->save($node);

// Update done

$node = new Node()
$node->setDn('ou=create',dc=example,dc=com');
$node->get('objectClass', true)->add(array('top', 'organizationalUnit'));
// The true param creates the attribute on the fly
$node->get('ou', true)->set('create');

$manager->save($node);

// New Ldap entry saved

$manager->delete($node);

// Now it's gone

Resources

To run the test suite, clone the project in your working environment from github Package your own version of autoload.php and phpunit.xml starting from the distributed versions You are ready to go:

$ php composer.phar install --dev
$ vendor/bin/phpunit

About

Requirements

PHP >= 5.4.22 with ldap extension
Composer

License

TIESA Ldap Component is licensed under the MIT License - see the LICENSE file for details

81square / tiesa-ldap

Maintainers

Details