README

LDAP Distinguished Name parsing and manipulation library for PHP.

Table of contents

• Features
• Requirements
• Installation
• How to use
  • Parsing DNs and accessing their components
    • Create a DN object from a string
    • Back to string representation
    • Access RDNs by index
    • Iterate RDNs
    • Access attributes
    • Multivalued RDNs
    • Special characters
    • Filter by attribute name
    • Get the parent DN
  • Manipulating DNs
    • Remove a fragment of a DN
  • Constructing DNs
  • Exceptions

Features

• access individual RDNs by index
• iterate RDNs
• filter by attribute name
• support for escaping special characters
• access attribute values
• remove fragments of a DN
• construct DNs
• case-insensitive but case-preserving (lookups are case-insensitive but attribute names’ and values’ case is preserved)
• 100% test coverage

Requirements

• PHP 7.1

Installation

$ composer require paweldecowski/ldap-dn

How to use

Parsing DNs and accessing their components

Create a DN object from a string

$dn = LdapDn\Dn::fromString('cn=john.doe,ou=it,ou=leadership,dc=example,dc=org');

Back to string representation

Dn class as well as classes representing its components (Rdn, Attribute) implement the __toString method. It means that in string context, they automatically become strings:

$dn = LdapDn\Dn::fromString('cn=john.doe,ou=it,ou=leadership,dc=example,dc=org');

echo $dn; // 'cn=john.doe,ou=it,ou=leadership,dc=example,dc=org'
echo $dn[0]; // 'dc=org'
echo $dn->filter('ou'); // 'ou=it,ou=leadership'

Access RDNs by index

Note that Rdns in a Dn object are reversed in relation to the DN string (if read from left to right). In a Dn with n Rdns, the right-most Rdn is at index 0 and the left-most Rdn is at index n-1. This is because it’s more natural and common to have the root object at index 0.

$dn = LdapDn\Dn::fromString('cn=john.doe,ou=it,ou=leadership,dc=example,dc=org');

echo $dn[0]; // 'dc=org'
echo $dn[4]; // 'cn=john.doe'

Iterate RDNs

$dn = LdapDn\Dn::fromString('cn=john.doe,ou=it,ou=leadership,dc=example,dc=org');

foreach ($dn as $rdn) {
    echo $rdn, "\n";
}

outputs:

dc=org
dc=example
ou=leadership
ou=it
cn=john.doe

Access attributes

$dn = LdapDn\Dn::fromString('cn=john.doe,ou=it,ou=leadership,dc=example,dc=org');

echo $dn[0]['dc']->getValue(); // 'org'
echo $dn[4]['cn']->getValue(); // 'john.doe'

If there’s only one instance of a certain attribute, you can get its value directly from the Dn object:

$dn = LdapDn\Dn::fromString('cn=john.doe,ou=it,ou=leadership,dc=example,dc=org');

echo $dn->getValue('cn'); // 'john.doe'

If mulitiple attributes with the specified name are found, a MultipleAttributesReturnedException is thrown.

Multivalued RDNs

Rdns are allowed to have multiple attributes, separated by the + character. You can access them using array dereferencing syntax.

$dn = LdapDn\Dn::fromString('cn=john.doe+uid=123,ou=it,ou=leadership,dc=example,dc=org');

echo $dn[4]; // 'cn=john.doe+uid=123'
echo $dn[4]['cn']; // 'cn=john.doe'
echo $dn[4]['cn']->getValue(); // 'john.doe'
echo $dn[4]['uid']; // 'uid=123'
echo $dn[4]['uid']->getValue(); // '123' 

You can also iterate attributes if you don’t know their names.

$dn = LdapDn\Dn::fromString('cn=john.doe+uid=123,ou=it,ou=leadership,dc=example,dc=org');

foreach ($dn[4] as $attribute) {
    echo $attribute->getName(), ' is ', $attribute->getValue(), "\n";
}

outputs:

cn is john.doe
uid is 123

Special characters

$dn = LdapDn\Dn::fromString('cn=doe\, john,ou=it,ou=leadership,dc=example,dc=org');

echo $dn[4]; // 'cn=doe\, john'
echo $dn[4]['cn']->getValue(); // 'doe, john'

Filter by attribute name

$dn = LdapDn\Dn::fromString('cn=john.doe,ou=it,ou=leadership,dc=example,dc=org');

echo $dn->filter('ou'); // 'ou=it,ou=leadership'

Note that even though the result of filter() is a Dn object, it may not be a valid Distinguished Name (for example if you remove the root RDN). This library doesn’t have the knowledge of your LDAP structure, so it can’t ensure validity.

Get the parent DN

$dn = LdapDn\Dn::fromString('cn=john.doe,ou=it,ou=leadership,dc=example,dc=org');

echo $dn->getParent(); // 'ou=it,ou=leadership,dc=example,dc=org'
echo $dn->getParent()->getParent(); // 'ou=leadership,dc=example,dc=org'

Manipulating DNs

Dn, Rdn and Attribute are immutable so all manipulation functions return a new object.

Remove a fragment of a DN

Sometimes you may want to remove a fragment of a DN, for example its base DN.

$dn = LdapDn\Dn::fromString('cn=john.doe,ou=it,ou=leadership,dc=example,dc=org');
$fragmentToRemove = LdapDn\Dn::fromString('dc=example,dc=org');

echo $dn->withRemoved($fragmentToRemove); // 'cn=john.doe,ou=it,ou=leadership'

Constructing DNs

While the main purpose of the library is parsing DNs, you can also construct them.

use LdapDn\Dn;
use LdapDn\Rdn;
use LdapDn\Attribute;

$dn = new Dn([
    new Rdn([new Attribute('dc', 'org')]),
    new Rdn([new Attribute('dc', 'example')]),
    new Rdn([new Attribute('ou', 'leadership')]),
    new Rdn([new Attribute('ou', 'it')]),
    new Rdn([new Attribute('cn', 'doe, john'), new Attribute('uid', '123')]),
]);

echo $dn; // 'cn=doe\, john+uid=123,ou=it,ou=leadership,dc=example,dc=org'

Most RDNs contain a single attribute, so you can construct them with a shorthand syntax.

use LdapDn\Dn;
use LdapDn\Rdn;
use LdapDn\Attribute;

$dn = new Dn([
    Rdn::withNameAndValue('dc', 'org'),
    Rdn::withNameAndValue('dc', 'example'),
    Rdn::withNameAndValue('ou', 'leadership'),
    Rdn::withNameAndValue('ou', 'it'),
    new Rdn([new Attribute('cn', 'doe, john'), new Attribute('uid', '123')]),
]);

echo $dn; // 'cn=doe\, john+uid=123,ou=it,ou=leadership,dc=example,dc=org'

Exceptions

AttributeNotFoundException

Thrown if an attribute is not found in an Dn.

DnNotFoundException

Thrown if an Dn cannot be found in another Dn

InvalidAttributeStringException

Thrown if a string representing an attribute is malformed.

MultipleAttributesReturned exception

Thrown when multiple Attributes are returned when exactly 1 was expected.

NotImplementedException

Thrown when an unimplemented method is called.