Helpers

LdapRecord provides some helper classes and utility functions you may find useful in your application.

Distinguished Names

use LdapRecord\Models\Attributes\DistinguishedName;

The DistinguishedName utility class allows you to parse Distinguished Name's, and perform various operations.

All comparison based operations are case insensitive.

make

Make a new Distinguished Name instance:

$dn = DistinguishedName::make('cn=John Doe,dc=local,dc=com');

build

Make a new Distinguished Name Builder instance:

// Pre-populate a builder:
$builder = DistinguishedName::build('cn=John Doe,dc=local,dc=com');

// Start from scratch:
$builder = DistinguishedName::build();

of

Alias of the build method:

// Pre-populate a builder:
$builder = DistinguishedName::of('cn=John Doe,dc=local,dc=com');

// Start from scratch:
$builder = DistinguishedName::of();

isValid

Determine if the given string is a valid Distinguished Name:

// true
DistinguishedName::isValid('cn=John Doe,dc=local,dc=com');

// true
DistinguishedName::isValid('cn=John');

// false
DistinguishedName::isValid('String containing rdn cn=John');

// false
DistinguishedName::isValid(null);

// false
DistinguishedName::isValid('');

get

Get the full value of the Distinguished Name:

$dn = DistinguishedName::make('cn=John Doe,dc=local,dc=com');

// "cn=John Doe,dc=local,dc=com"
$dn->get();

set

Set the value of the Distinguished Name:

$dn = DistinguishedName::make('cn=other,dc=local,dc=com');

$dn->set('cn=John Doe,dc=local,dc=com');

// "cn=John Doe,dc=local,dc=com"
$dn->get();

explode

Explode a Distinguished Name string:

$dn = DistinguishedName::explode('cn=john doe,dc=local,dc=com');

// [
//   "cn=john doe",
//   "dc=local",
//   "dc=com",
// ]
var_dump($dn);

explodeRdn

Explode a Relative Distinguished Name string:

[$attribute, $value] = DistinguishedName::explodeRdn('cn=john doe');

// "cn"
echo $attribute;

// "john doe"
echo $value;

makeRdn

Make a Relative Distinguished Name string:

$rdn = DistinguishedName::makeRdn(['cn', 'john doe']);

// "cn=john doe"
echo $rdn;

unescape

$unescaped = DistinguishedName::unescape('\6a\6f\68\6e\2c\64\6f\65');

// "doe, john"
echo $unescaped;

name

Get the Relative Distinguished Name's value:

$dn = DistinguishedName::make('cn=John Doe,dc=local,dc=com');

// "John Doe"
$dn->name();

head

Get the Relative Distinguished Name's attribute:

$dn = DistinguishedName::make('cn=John Doe,dc=local,dc=com');

// "cn"
$dn->head();

relative

Get the Relative Distinguished Name:

$dn = DistinguishedName::make('cn=John Doe,dc=local,dc=com');

// "cn=John Doe"
$dn->relative();

parent

Get the parent Distinguished Name:

$dn = DistinguishedName::make('cn=John Doe,dc=local,dc=com');

// "dc=local,dc=com"
$dn->parent();

values

Get the values of each DN component:

$dn = DistinguishedName::make('cn=John Doe,dc=local,dc=com');

// array:3 [
//  0 => "John Doe"
//  1 => "local"
//  2 => "com"
// ]
$dn->values();

components

Get the Relative Distinguished Name's of each DN component:

$dn = DistinguishedName::make('cn=John Doe,dc=local,dc=com');

// array:3 [
//  0 => "cn=John Doe"
//  1 => "dc=local"
//  2 => "dc=com"
// ]
$dn->components();

assoc

Get an associative array of the Distinguished Name component's, grouping them using their attribute name:

$dn = DistinguishedName::make('cn=John Doe,dc=local,dc=com');

// array:2 [
//  "cn" => array:1 [
//    0 => "John Doe"
//  ]
//  "dc" => array:2 [
//    0 => "local"
//    1 => "com"
//  ]
// ]
$dn->assoc();

multi

Split the Relative Distinguished Name's of each DN component into an associative array:

$dn = DistinguishedName::make('cn=John Doe,dc=local,dc=com');

// array: 3 [
//   0 => ['cn', 'John'],
//   1 => ['ou', 'local'],
//   2 => ['dc', 'local'],
// ]
$dn->multi();

isEmpty

Determine if the Distinguished Name has any values:

// false
DistinguishedName::make('cn=John Doe,dc=local,dc=com')->isEmpty();

// false
DistinguishedName::make('cn=John Doe')->isEmpty();

// true
DistinguishedName::make(null)->isEmpty();

// true
DistinguishedName::make('')->isEmpty();

isParentOf

Determine if the Distinguished Name is a direct parent of the given child:

$dn = DistinguishedName::make('ou=users,dc=local,dc=com');

// false
$dn->isParentOf(
  DistinguishedName::make('ou=accounting,dc=local,dc=com')
);

// true
$dn->isParentOf(
  DistinguishedName::make('ou=office,ou=users,dc=local,dc=com')
);

isChildOf

Determine if the Distinguished Name is a direct child of the given parent:

$dn = DistinguishedName::make('cn=John Doe,dc=local,dc=com');

// false
$dn->isChildOf(
  DistinguishedName::make('ou=users,dc=local,dc=com')
);

// true
$dn->isChildOf(
  DistinguishedName::make('dc=local,dc=com')
);

isAncestorOf

Determine if the Distinguished Name is an ancestor of the given descendant/child:

$dn = DistinguishedName::make('ou=users,dc=local,dc=com');

// false
$dn->isAncestorOf(
  DistinguishedName::make('dc=local,dc=com')
);

// true
$dn->isAncestorOf(
  DistinguishedName::make('ou=accounting,ou=users,dc=local,dc=com')
);

// true
$dn->isAncestorOf(
  DistinguishedName::make('ou=other,ou=accounting,ou=users,dc=local,dc=com')
);

isDescendantOf

Determine if the Distinguished Name is an descendant of the given ancestor/parent:

$dn = DistinguishedName::make('cn=John Doe,ou=accounting,ou=users,dc=local,dc=com')

// false
$dn->isDescendantOf(
  DistinguishedName::make('ou=admin,dc=local,dc=com')
);

// true
$dn->isDescendantOf(
  DistinguishedName::make('ou=users,dc=local,dc=com')
);

// true
$dn->isDescendantOf(
  DistinguishedName::make('ou=accounting,ou=users,dc=local,dc=com')
);

Distinguished Name Building

The Distinguished Name Builder allows you to build and transform Distinguished Names.

use LdapRecord\Models\Attributes\DistinguishedNameBuilder;
  • All transformation methods can be chained.
  • Values given to the prepend and append are escaped.
  • Missing method calls are forwarded to a DistinguishedName instance.

components

Get all of the components of the DN.

$dn = DistinguishedName::build('cn=john doe,ou=users,dc=local,dc=com');

// array:4 [
//   0 => array:2 [
//     0 => "cn"
//     1 => "john doe"
//   ]
//   1 => array:2 [
//     0 => "ou"
//     1 => "users"
//   ]
//   2 => array:2 [
//     0 => "dc"
//     1 => "local"
//   ]
//   3 => array:2 [
//     0 => "dc"
//     1 => "com"
//   ]
// ]
$dn->components();

Get the components of a particular type:

$dn = DistinguishedName::build('cn=john doe,ou=users,dc=local,dc=com');

// array:2 [
//   0 => array:2 [
//     0 => "dc"
//     1 => "local"
//   ]
//   1 => array:2 [
//     0 => "dc"
//     1 => "com"
//   ]
// ]
$dn->components('dc');

prepend

Prepend an RDN onto the DN.

$dn = DistinguishedName::build('dc=com');

// Use an attribute and value:
$dn->prepend('dc', 'local');

// Use an RDN:
$dn->prepend('cn=john');

// "cn=john,dc=local,dc=com"
$dn->get();

append

Append an RDN onto the DN.

$dn = DistinguishedName::build('cn=john');

// Use an attribute and value:
$dn->append('dc', 'local');

// Use an RDN:
$dn->append('dc=com');

// "cn=john,dc=local,dc=com"
$dn->get();

pop

Pop an RDN off of the end of the DN.

// "cn=john,dc=local"
DistinguishedName::build('cn=john,dc=local,dc=com')
  ->pop()
  ->get();

// "cn=john"
DistinguishedName::build('cn=john,dc=local,dc=com')
  ->pop(2)
  ->get();

// "cn=john"
DistinguishedName::build('cn=john,dc=local,dc=com')
  ->pop(2, $removed)
  ->get();

// array:2 [
//   0 => "dc=local"
//   1 => "dc=com"
// ]
var_dump($removed);

shift

Shift an RDN off of the beginning of the DN.

// "dc=local,dc=com"
DistinguishedName::build('cn=john,dc=local,dc=com')
  ->shift()
  ->get();

// "dc=com"
DistinguishedName::build('cn=john,dc=local,dc=com')
  ->shift(2)
  ->get();

// "dc=com"
DistinguishedName::build('cn=john,dc=local,dc=com')
  ->shift(2, $removed)
  ->get();

// array:2 [
//   0 => "cn=john"
//   1 => "dc=local"
// ]
var_dump($removed);

reverse

Whether to output the DN in reverse.

// "dc=com,dc=local,cn=john"
DistinguishedName::build('cn=john,dc=local,dc=com')
  ->reverse()
  ->get();

Long Chain Example

$dn = DistinguishedName::of('cn=John Doe,dc=local,dc=com')
    ->shift(1, $removed)
    ->prepend('ou', 'users')
    ->prepend($removed)
    ->pop(1, $removed)
    ->append('dc', 'org')
    ->append($removed)
    ->get();

// "cn=John Doe,ou=users,dc=local,dc=org,dc=com"
echo $dn;

Passwords

use LdapRecord\Models\Attributes\Password;

The Password helper allows you to create hashed passwords, as well as encode them for transmission to your LDAP server.

You do not need to use any of these utilities when connecting to an Active Directory server. Password encoding is done for you with the included User model.

encode

Make an encoded password for transmission over LDAP.

// "\x00s\x00e\x00c\x00r\x00e\x00t\x00"\x00"
Password::encode('secret');

smd5

Make a salted md5 password.

// "{SMD5}i3f4A6FAN0MDFaaZU23fu8FcHw4="
Password::smd5('secret');

// "{SMD5}mc0uWpXVVe5747A4pKhGJXNhbHQ="
Password::smd5('secret', 'salt');

ssha

Make a salted SHA password.

// "{SSHA}L8EHaF8fyBVlTrvHbdE5/7MnCN1sR4az"
Password::ssha('secret');

// "{SSHA}gVK8WC9YyFT1gMsQHTGCgT3sSv5zYWx0"
Password::ssha('secret', 'salt');

ssha256

Make a salted SSHA256 password.

// "{SSHA256}f30+bbvnM24awEIG2iLZ12TcsjFT7e+OP3/fFmmqMZNdQRP/"
Password::ssha256('secret');

// "{SSHA256}+E+iFJ27Yu1ODPH1UNKUmzOmUT06dwfghQJRHHnMsO5zYWx0"
Password::ssha256('secret', 'salt');

ssha384

Make a salted SSHA384 password.

// "{SSHA384}x57dAvYd0LnqXDLxgmCqgrR585r2Ej4Lyxm+SQqY2fr1yzgIGz/t48MlKwEy+96jeShdcg=="
Password::ssha384('secret');

// "{SSHA384}BPdC1qPVnOtOWlZBhlNvMSsThLk7gG0moXRB2Ulg+UGkFToChXZ4jNzGfK5Uh3Otc2FsdA=="
Password::ssha384('secret', 'salt');

ssha512

Make a salted SSHA512 password.

// "{SSHA512}udY8kkohMXfh4YKmrMWbXk1CWf2xpzarDAOLTPBezod5JSwbgMvgCAjeJiYvmfrsfyHlVqc/4nmfaH7Hlvumo/cB2Jg="
Password::ssha512('secret');

// "{SSHA512}E491yrR9AdCoE7rbOPYS3EZgSuZpVE65AD9xko08s6floNesY/Zpe9zMVvLix4S2FiQSJ99RIkNvhHomNO9uL3NhbHQ="
Password::ssha512('secret', 'salt');

sha

Make a non-salted SHA password.

// "{SHA}5en6G6MezRroT3XKqkdPOmY/BfQ="
Password::sha('secret');

sha256

Make a non-salted SHA256 password.

// "{SHA256}K7gNU3sdo+OL0wNhqoVWhr3g6s1xYv72ol/pe/Unols="
Password::sha256('secret');

sha384

Make a non-salted SHA384 password.

// "{SHA384}WKd1ukESvjAFrkQHznV9iP2nHUBJe7gCbsrFTU4//HIyzo3jq1rLMK45dg/ufFPt"
Password::sha384('secret');

sha512

Make a non-salted SHA512 password.

// "SHA512}vSsar3708Jvp9Szi2NWZZ02Bqp1qRCFpbcTZPdBhnWgs5WtNZKnvCXdhztmeD2cmW192CF5bDufKRpayrW/isg=="
Password::sha512('secret');

md5

Make a non-salted md5 password.

// "{MD5}Xr4ilOzQ4PCOq3aQ0qbuaQ=="
Password::md5('secret');

md5Crypt

Crypt password with an MD5 salt.

// "{CRYPT}$1$hYstY89O$EHfOOWhp4qJ0.lDJ2owwb."
Password::md5Crypt('secret');

// "{CRYPT}saHW9GdxihkGQ"
Password::md5Crypt('secret', 'salt');

sha256Crypt

Crypt password with a SHA256 salt.

// "{CRYPT}$5$aRmWk3iiWxTdJ$iTy8QAfarSnilA3nM6SSH67qB2VpZiRbxXkA4FddfdD"
Password::sha256Crypt('secret');

// "{CRYPT}saHW9GdxihkGQ"
Password::sha256Crypt('secret', 'salt');

sha512Crypt

Crypt a password with a SHA512 salt.

// "{CRYPT}$6$GcGAYPV4NIvbC$odXh0cW4xldt2YUTqCaxjwFvRjiLA4CyDsQYaY1zLEfB4XXzsq6MFru9TAMbzR8hs0nJjmi5fFHrAB9hmaFF.."
Password::sha512Crypt('secret');

// "{CRYPT}saHW9GdxihkGQ"
Password::sha512Crypt('secret', 'salt');

GUID

A utility class for parsing and validating Object GUIDs.

use LdapRecord\Models\Attributes\Guid;

isValid

Determine if a given string is a valid GUID:

// Returns "true"
Guid::isValid('59e5e143-a50e-41a9-bf2b-badee699a577');
Guid::isValid('8be90b30-0bbb-4638-b468-7aaeb32c74f9');
Guid::isValid('17bab266-05ac-4e30-9fad-1c7093e4dd83');

// Returns "false"
Guid::isValid('Invalid GUID');
Guid::isValid('17bab266-05ac-4e30-9fad');
Guid::isValid('');

getHex

Get the hexadecimal representation of the GUID string:

$guid = '270db4d0-249d-46a7-9cc5-eb695d9af9ac';

// "d0b40d279d24a7469cc5eb695d9af9ac"
(new Guid($guid))->getHex();

getEncodedHex

Get the encoded hexadecimal representation of the GUID string:

$guid = '270db4d0-249d-46a7-9cc5-eb695d9af9ac';

// "\d0\b4\0d\27\9d\24\a7\46\9c\c5\eb\69\5d\9a\f9\ac"
(new Guid($guid))->getEncodedHex();

getValue

Get the string representation of the GUID:

$guid = '270db4d0-249d-46a7-9cc5-eb695d9af9ac';

// "270db4d0-249d-46a7-9cc5-eb695d9af9ac"
(new Guid($guid))->getValue();

getBinary

Get the binary representation of the GUID string:

$guid = '270db4d0-249d-46a7-9cc5-eb695d9af9ac';

// "b"ð┤\r'Ø$ºF£┼Ùi]ܨ¼""
(new Guid($guid))->getBinary();

SID

A utility class for parsing and validating Object SIDs.

use LdapRecord\Models\Attributes\Sid;

isValid

Determine if a string is a valid SID:

// Returns "true"
Sid::isValid('S-1-5-21-362381101-336104434-3030082-101');
Sid::isValid('S-1-5-21-362381101-336104434');
Sid::isValid('S-1-5-21-362381101');
Sid::isValid('S-1-5-21');
Sid::isValid('S-1-5');

// Returns "false"
Sid::isValid('Invalid SID');
Sid::isValid('S-1');
Sid::isValid('');

getValue

Get the string representation value of the SID:

$sid = 'S-1-5-21-362381101-336104434-3030082-101';

// "S-1-5-21-362381101-336104434-3030082-101"
(new Sid($sid))->getValue();

getBinary

Get the binary representation value of the SID:

$sid = 'S-1-5-21-362381101-336104434-3030082-101';

// "b"\x01\x05\x00\x00\x00\x00\x00\x05\x15\x00\x00\x00-\x7F™\x15ò‹\x08\x14B<.\x00e\x00\x00\x00"
(new Sid($sid))->getBinary();

Timestamp

A utility class for transforming dates to and from LDAP timestamps.

use LdapRecord\Models\Attributes\Timestamp;

Timestamp Types

To begin, create a new Timestamp instance with the type of timestamp you are looking to convert:

$timestamp = new Timestamp(Timestamp::TYPE_LDAP);

$timestamp = new Timestamp(Timestamp::TYPE_WINDOWS);

$timestamp = new Timestamp(Timestamp::TYPE_WINDOWS_INT);

Converting to an LDAP Timestamp

Call fromDateTime() to convert a string, int, DateTime, or Carbon instance to the LDAP timestamp:

// "20230417210756Z"
$ldapTimestamp = (new Timestamp(Timestamp::TYPE_LDAP))
    ->fromDateTime(new \DateTime());

// "20230417210824.0Z"
$windowsTime = (new Timestamp(Timestamp::TYPE_WINDOWS))
    ->fromDateTime(new \DateTime());

// 133262392690000000
$windowsIntegerTime = (new Timestamp(Timestamp::TYPE_WINDOWS_INT))
    ->fromDateTime(new \DateTime());

Converting from an LDAP Timestamp

Call toDateTime() to convert an LDAP timestamp into a PHP Carbon instance:

// Carbon\Carbon
$ldapTimestampAsCarbon = (new Timestamp(Timestamp::TYPE_LDAP))
    ->toDateTime('20230417210756Z');

// Carbon\Carbon
$windowsTimeAsCarbon = (new Timestamp(Timestamp::TYPE_WINDOWS))
    ->toDateTime('20230417210824.0Z');

// Carbon\Carbon
$windowsIntegerTimeAsCarbon = (new Timestamp(Timestamp::TYPE_WINDOWS_INT))
    ->toDateTime(133262392690000000);