From 227d1b2697eba85e72fd84b4c6a1c0a49d820657 Mon Sep 17 00:00:00 2001 From: Chris Torstenson Date: Tue, 23 Feb 2016 16:20:33 -0800 Subject: [PATCH] Formatting fixes and syntax highlighting --- README.md | 186 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 98 insertions(+), 88 deletions(-) diff --git a/README.md b/README.md index 6672382..271ac88 100644 --- a/README.md +++ b/README.md @@ -4,27 +4,31 @@ 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 ===== @@ -32,145 +36,151 @@ 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: - '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: - 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: - 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: - getNode('cn=my,ou=node,dc=example,dc=com'); +```php +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: - 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 =====