Skip to content

Formatting fixes and syntax highlighting #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
torsday wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Formatting fixes and syntax highlighting #8

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
186 changes: 98 additions & 88 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,173 +4,183 @@ TIESA Ldap Component
Install
=======

Installing the component in your project is as simple as installing [Composer](http://getcomposer.org/download/)
if not already done so yet.
Installing the component in your project is as simple as installing [Composer](http://getcomposer.org/download/) 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:
Then, under your project root folder, create a new file called `composer.json` and paste the following into it:

{
"require": {
"tiesa/ldap": "dev-master"
}
```json
{
"require": {
"tiesa/ldap": "dev-master"
}
}
```

To select the component names & versions, you shall refer to information found at [Packagist](http://packagist.org)

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

$ php composer.phar install
```sh
$ 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:
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';
```sh
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:
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
```php
<?php

use Toyota\Component\Ldap\Core\Manager;
use Toyota\Component\Ldap\Platform\Native\Driver;
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());
$params = array(
'hostname' => 'ldap.example.com',
'base_dn' => 'dc=example,dc=com'
);
$manager = new Manager($params, new Driver());

$manager->connect();
$manager->connect();

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

// Ready for searching & persisting information
// 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');
```php
$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:
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)
- 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.
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());
```php
<?php
// ... namespace imports and $params configuration
$manager = new Manager($params, new Driver());

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

try {
$manager->bind();
} catch (BindingException $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
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:
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
```php
<?php
// ... $manager connection & binding

$results = $manager->search(Search::SCOPE_ALL, 'ou=comp,dc=example,dc=com', '(objectclass=*)');
$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
// 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()));
}
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
`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
- `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:
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');
```php
<?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:
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
```php
<?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');
$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);
$manager->save($node);

// Update done
// 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');
$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);
$manager->save($node);

// New Ldap entry saved
// New Ldap entry saved

$manager->delete($node);
$manager->delete($node);

// Now it's gone
// 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:
Package your own version of `autoload.php` and `phpunit.xml` starting from the distributed versions and you are ready to go:

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

About
=====
Expand Down