tiesa/ldap

LDAP made easy & practical to use in PHP

dev-master / 1.0.x-dev 2013-02-04 07:37 UTC

This package is not auto-updated.

Last update: 2024-03-10 00:51:53 UTC


README

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": {
        "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');

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.

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

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

// 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()));
    }
}

SCOPE_ALL will let you search through the whole subtree including the base node with the distinguished name you gave for the search. Other options are:

  • SCOPE_BASE: Will only search for the one node which matches the given distinguished name
  • SCOPE_ONE: Will search for nodes just below the one that matches the given distinguished name

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.3.3 with ldap extension
  • Composer

License

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