LdapRecord Core

https://ldaprecord.com/docs/core/v3
Admin
LdapRecord is a PHP ActiveRecord implementation that provides full LDAP integration for creating,...
Tokens:158,114
Snippets:1,508
Trust Score:7.3
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### whereStartsWith - Add a 'starts with' clause

Source: https://ldaprecord.com/docs/core/v3/searching-api

Adds a 'starts with' clause to the query, searching for objects where the attribute starts with the given value. The example returns "(cn=John*)".

```php
$query = $connection->query();

// Returns "(cn=John*)"
$query->whereStartsWith('cn', 'John')->getUnescapedQuery();

```

--------------------------------

### Install LdapRecord via Composer

Source: https://ldaprecord.com/docs/core/v3/installation

Run this command in the root directory of your project after installing Composer to install LdapRecord.

```bash
composer require directorytree/ldaprecord
```

--------------------------------

### orWhereNotStartsWith - Add 'or where not starts with' clause

Source: https://ldaprecord.com/docs/core/v3/searching-api

Adds an 'or where not starts with' clause. Examples show single and combined filters.

```php
// Returns "(!(cn=John*))"
$connection->query()
    ->orWhereNotStartsWith('cn', 'John')
    ->getUnescapedQuery();

// Returns "(|(!(cn=Suzy*))(!(cn=John*)))"
$connection->query()
    ->whereNotStartsWith('cn', 'Suzy')
    ->orWhereNotStartsWith('cn', 'John')
    ->getUnescapedQuery();

```

--------------------------------

### orWhereStartsWith - Add 'or where starts with' clause

Source: https://ldaprecord.com/docs/core/v3/searching-api

Adds an 'or where starts with' clause to the query. The example shows the resulting unescaped query for a single clause and for a combined whereStartsWith and orWhereStartsWith.

```php
// Returns "(cn=John*)"
$connection->query()
    ->orWhereStartsWith('cn', 'John')
    ->getUnescapedQuery();

// Returns "(|(cn=Suzy*)(cn=John*))"
$connection->query()
    ->whereStartsWith('cn', 'Suzy')
    ->orWhereStartsWith('cn', 'John')
    ->getUnescapedQuery();

```

--------------------------------

### Linux/macOS ldap.conf CA certificate example

Source: https://ldaprecord.com/docs/core/v3/configuration

Linux/macOS example of referencing the CA certificate and enforcing strict verification in ldap.conf.

```text
TLS_CACERT /etc/ssl/certs/ca.pem
TLS_REQCERT hard
```

--------------------------------

### first: Get first query result

Source: https://ldaprecord.com/docs/core/v3/searching-api

Gets the first resulting entry of a query from the directory. Returns the first entry or null if none.

```php
$query = $connection->query();

$entry = $query->whereStartsWith('cn', 'Steve')->first();
```

--------------------------------

### Windows ldap.conf CA certificate example

Source: https://ldaprecord.com/docs/core/v3/configuration

Windows example of referencing the CA certificate and enforcing strict verification in ldap.conf.

```text
TLS_CACERT C:\OpenLDAP\sysconf\ca.pem
TLS_REQCERT hard
```

--------------------------------

### Add expectation to LdapFake with expect method

Source: https://ldaprecord.com/docs/core/v3/testing-api

Shows how to add an LdapExpectation to an LdapFake instance using the expect method. The example uses DirectoryFake::setup() to get the LDAP connection.

```php
DirectoryFake::setup()
    ->getLdapConnection() // LdapRecord\Testing\LdapFake
    ->expect(LdapFake::operation('...'))
```

--------------------------------

### Retrieve search results with get()

Source: https://ldaprecord.com/docs/core/v3/searching

Call get() to execute the search and return results as an array.

```php
$results = $query->select(['cn', 'samaccountname'])->get();
```

--------------------------------

### Determine the connection in a model event

Source: https://ldaprecord.com/docs/core/v3/events

Shows how to get the LDAP connection host from a model event. The example listens to the Creating event and retrieves the host from the model's connection.

```php
use LdapRecord\Container;
use LdapRecord\Models\Events\Creating;

$dispatcher = Container::getDispatcher();

$dispatcher->listen(Creating::class, function ($event) {
    $connection = $event->model->getConnection();

    $host = $connection->getHost();

    echo $host; // Displays 'ldap://192.168.1.1:386'
});
```

--------------------------------

### get

Source: https://ldaprecord.com/docs/core/v3/searching-api

Gets the resulting entries of a query.

```APIDOC
## `get`

### Description
Gets the resulting entries of a query from the directory. Use `paginate` for more than 1000 entries.

### Method
`get`

### Parameters
None.

### Returns
Returns an array of entries.

### Example
```php
$query = $connection->query();
$entries = $query->where('company', '=', 'Acme')->get();
```
```

--------------------------------

### Get immediate groups with groups()->get()

Source: https://ldaprecord.com/docs/core/v3/active-directory/groups

Retrieves the immediate parent groups of a given group by calling the `groups` relationship and then `get()`.

```php
$group = Group::find('cn=Accounting,dc=local,dc=com');

$groups = $group->groups()->get();

```

--------------------------------

### DirectoryFake::setup()

Source: https://ldaprecord.com/docs/core/v3/testing-api

Swaps a LdapRecord\Connection in the LdapRecord\Container with an LdapRecord\Testing\ConnectionFake. Returns the ConnectionFake instance.

```php
use LdapRecord\Testing\DirectoryFake;

DirectoryFake::setup(); // LdapRecord\Testing\ConnectionFake

```

--------------------------------

### getGuidKey - Get GUID attribute key

Source: https://ldaprecord.com/docs/core/v3/model-api

Returns the attribute key that contains the object's GUID. The example shows the default key.

```php
// Returns: 'objectguid'
$model->getGuidKey();
```

--------------------------------

### Guid::getValue

Source: https://ldaprecord.com/docs/core/v3/helpers

Gets the string representation of the GUID. This method is called on a Guid instance.

```APIDOC
## Guid::getValue

### Description
Gets the string representation of the GUID.

### Method
getValue

### Parameters
- **guid** (string) - Required - The GUID string.

### Returns
- **string** - The string representation of the GUID.

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

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

```

--------------------------------

### newInstance: Create new model instance

Source: https://ldaprecord.com/docs/core/v3/model-api

Creates a new model instance. The example finds an existing model and then creates a new instance from it.

```php
$model = Model::findByAnr('sbauman');

$new = $model->newInstance();
```

--------------------------------

### Guid::getBinary

Source: https://ldaprecord.com/docs/core/v3/helpers

Gets the binary representation of the GUID string. This method is called on a Guid instance.

```APIDOC
## Guid::getBinary

### Description
Gets the binary representation of the GUID string.

### Method
getBinary

### Parameters
- **guid** (string) - Required - The GUID string to convert.

### Returns
- **string** - The binary representation of the GUID.

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

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

```

--------------------------------

### Example of windows-int timestamp

Source: https://ldaprecord.com/docs/core/v3/model-mutators

Example of an 18-digit Active Directory timestamp (Windows NT time format) used by the 'windows-int' mutator type.

```text
132131246410000000

```

--------------------------------

### Swap default connection with a fake

Source: https://ldaprecord.com/docs/core/v3/testing

Uses DirectoryFake::setup to replace the default LDAP connection with a mockable fake instance.

```php
use LdapRecord\Testing\DirectoryFake;

class LdapTest extends TestCase
{
    public function test()
    {
        // Swap default connection with a fake...
        $fake = DirectoryFake::setup();
        
        // Returns instanceof \LdapRecord\Testing\ConnectionFake
        // \LdapRecord\Container::getDefaultConnection();
        
        // ...
    }
}
```

--------------------------------

### Guid::getHex

Source: https://ldaprecord.com/docs/core/v3/helpers

Gets the hexadecimal representation of the GUID string. This method is called on a Guid instance.

```APIDOC
## Guid::getHex

### Description
Gets the hexadecimal representation of the GUID string.

### Method
getHex

### Parameters
- **guid** (string) - Required - The GUID string to convert.

### Returns
- **string** - The hexadecimal representation of the GUID.

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

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

```

--------------------------------

### Guid::getEncodedHex

Source: https://ldaprecord.com/docs/core/v3/helpers

Gets the encoded hexadecimal representation of the GUID string. This method is called on a Guid instance.

```APIDOC
## Guid::getEncodedHex

### Description
Gets the encoded hexadecimal representation of the GUID string.

### Method
getEncodedHex

### Parameters
- **guid** (string) - Required - The GUID string to convert.

### Returns
- **string** - The encoded hexadecimal representation of the GUID.

### Example
php
$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();

```

--------------------------------

### whereStartsWith()

Source: https://ldaprecord.com/docs/core/v3/searching

Adds a 'starts with' clause to the query.

```APIDOC
## whereStartsWith()

### Description
Adds a 'starts with' clause to the query.

### Method
whereStartsWith

### Parameters
- **field** (string) - Required - The LDAP attribute to filter on.
- **value** (string) - Required - The prefix to match.

### Example
```php
$results = $query->whereStartsWith('cn', 'John')->get();
```
```

--------------------------------

### Guid::getValue - Get string representation

Source: https://ldaprecord.com/docs/core/v3/helpers

Returns the string representation of the GUID.

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

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

--------------------------------

### Retrieve LdapFake instance via DirectoryFake::setup()->getLdapConnection()

Source: https://ldaprecord.com/docs/core/v3/testing

Call DirectoryFake::setup()->getLdapConnection() to obtain the LdapFake instance for adding expectations.

```php
use LdapRecord\Testing\DirectoryFake;

DirectoryFake::setup()->getLdapConnection(); // \LdapRecord\Testing\LdapFake

```

--------------------------------

### Guid::getBinary - Get binary representation

Source: https://ldaprecord.com/docs/core/v3/helpers

Returns the binary representation of the GUID string.

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

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

--------------------------------

### Guid::getHex - Get hexadecimal representation

Source: https://ldaprecord.com/docs/core/v3/helpers

Returns the hexadecimal representation of the GUID string.

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

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

--------------------------------

### select

Source: https://ldaprecord.com/docs/core/v3/searching-api

Sets the attributes to return from the directory.

```APIDOC
## `select`

### Description
Set the attributes to return from the directory. By selecting only the attributes you need, you can effectively reduce memory usage on large query result sets.

### Method
select

### Parameters
- **attributes** (array) - Required - An array of attribute names to return.

### Request Example
```php
$query = $connection->query();

// Only return the 'cn' and 'sn' attributes in result
$query->select(['cn', 'sn'])->get();
```

### Response
No explicit response documented.
```

--------------------------------

### hasGetMutator: Check for get mutator

Source: https://ldaprecord.com/docs/core/v3/model-api

Checks if the model has a 'get' mutator for the given attribute. The example defines a get mutator for 'cn' and then verifies it exists.

```php
class Entry extends Model
{
    public function getCnAttribute(array $values): mixed
    {
        // ...
    }
}

$model = new Entry();

// Returns: true
$model->hasGetMutator('cn');
```

--------------------------------

### Create a new LdapRecord Connection

Source: https://ldaprecord.com/docs/core/v3/connections

Instantiate a Connection with hosts, username, and password configuration. This is the first step before connecting to the LDAP server.

```php
use LdapRecord\Connection;

$connection = new Connection([
     'hosts'    => ['192.168.1.1'],
     'username' => 'cn=user,dc=local,dc=com',
     'password' => 'secret',
]);
```

--------------------------------

### Guid::getEncodedHex - Get encoded hexadecimal representation

Source: https://ldaprecord.com/docs/core/v3/helpers

Returns the encoded hexadecimal representation of the GUID string.

```php
$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();
```

--------------------------------

### DirectoryFake::setup

Source: https://ldaprecord.com/docs/core/v3/testing-api

Swaps a real LDAP connection with a fake connection for testing.

```APIDOC
## DirectoryFake::setup

### Description
Swaps a `LdapRecord\Connection` in the `LdapRecord\Container` with an `LdapRecord\Testing\ConnectionFake`.

### Method
`setup`

### Parameters
None

### Return Value
`LdapRecord\Testing\ConnectionFake`

### Example
```php
use LdapRecord\Testing\DirectoryFake;

DirectoryFake::setup(); // LdapRecord\Testing\ConnectionFake
```
```

--------------------------------

### getObjectGuid - Get raw binary object GUID

Source: https://ldaprecord.com/docs/core/v3/model-api

Returns the raw binary object GUID. For Active Directory, the raw binary GUID is returned; for other LDAP directories, the raw string GUID is returned.

```php
$rawBinary = $model->getObjectGuid();
```

--------------------------------

### ConnectionFake::make()

Source: https://ldaprecord.com/docs/core/v3/testing-api

Creates a new ConnectionFake instance with the given configuration array.

```php
use LdapRecord\Testing\ConnectionFake;

$config = ['...'];

$fake = ConnectionFake::make($config);

```

--------------------------------

### getGrammar

Source: https://ldaprecord.com/docs/core/v3/searching-api

Gets the query grammar instance.

```APIDOC
## `getGrammar`

### Description
Gets the underlying query grammar instance.

### Method
`getGrammar`

### Parameters
None.

### Returns
Returns an instance of `LdapRecord\Query\Grammar`.

### Example
```php
$query = $connection->query();
$grammar = $query->getGrammar();
```
```

--------------------------------

### Basic retrieval methods

Source: https://ldaprecord.com/docs/core/v3/models

Shows how to retrieve a single model using first(), find(), findBy(), findByAnr(), and findByGuid(). Use these methods when you expect the model to exist.

```php
// Retrieve the first model of a global LDAP search...
$user = User::first();

// Retrieve a model by its distinguished name...
$user = User::find('cn=John Doe,dc=local,dc=com');

// Retrieve the first model that matches the attribute...
$user = User::findBy('cn', 'John Doe');

// Retrieve the first model that matches an array of ANR attributes...
$user = User::findByAnr('John Doe');

// Retrieve a model by its object guid...
$user = User::findByGuid('bf9679e7-0de6-11d0-a285-00aa003049e2');
```

--------------------------------

### getAnrAttributes: Get ANR attributes

Source: https://ldaprecord.com/docs/core/v3/model-api

Gets an array of ANR attributes defined on the model. Example shows the default list.

```php
$attributes = $model->getAnrAttributes();

// Displays:
// [
//    'cn',
//    'sn',
//    'uid',
//    'name',
//    'mail',
//    'givenname',
//    'displayname'
// ]
var_dump($attributes);

```

--------------------------------

### Use LdapRecord to Connect and Perform Basic Operations

Source: https://ldaprecord.com/docs/core/v3/quickstart

Create a connection, add it to the container, and perform basic operations like retrieving entries, accessing attributes, and saving changes.

```php
use LdapRecord\Container;
use LdapRecord\Connection;
use LdapRecord\Models\Entry;

// Create a new connection:
$connection = new Connection([
    'hosts' => ['192.168.1.1'],
    'port' => 389,
    'base_dn' => 'dc=local,dc=com',
    'username' => 'cn=user,dc=local,dc=com',
    'password' => 'secret',
]);

// Add the connection into the container:
Container::addConnection($connection);

// Get all entries:
$entries = Entry::get();

// Get a single entry:
$entry = Entry::find('cn=John Doe,dc=local,dc=com');

// Getting attributes:
foreach ($entry->memberof as $group) {
    echo $group;
}

// Modifying attributes:
$entry->company = 'My Company';

// Saving changes:
$entry->save();

```

--------------------------------

### getConvertedGuid

Source: https://ldaprecord.com/docs/core/v3/model-api

Get the model's string GUID.

```APIDOC
## getConvertedGuid

### Description
Get the model's string GUID.

### Method
N/A (SDK method)

### Endpoint
N/A (SDK method)

### Parameters
None

### Request Example
```php
$guid = $model->getConvertedGuid();
```

### Response
#### Success Response
- Returns the string GUID.

#### Response Example
```php
// Example: bf9679e7-0de6-11d0-a285-00aa003049e2
$guid = $model->getConvertedGuid();
```
```

--------------------------------

### with

Source: https://ldaprecord.com/docs/core/v3/testing-api

Sets the arguments to expect when the method is called.

```APIDOC
## `with`

### Description
Sets the arguments to expect when the method is called.

### Method
`with`

### Parameters
- **arguments** (mixed) - Required - The arguments to expect.

### Example
```php
(new LdapExpectation('read'))->with('cn=john,dc=local,dc=com', '(objectclass=*)', ['objectclass', 'cn']);
```
```

--------------------------------

### whereNotStartsWith - Add a 'where doesn't start with' clause

Source: https://ldaprecord.com/docs/core/v3/searching-api

Adds a 'where doesn't start with' clause to the query, searching for objects where the attribute does not start with the given value. The example returns "(!(cn=John*))".

```php
$query = $connection->query();

// Returns "(!(cn=John*))"
$query->whereNotStartsWith('cn', 'John')->getUnescapedQuery();

```

--------------------------------

### getGuidKey

Source: https://ldaprecord.com/docs/core/v3/model-api

Get the attribute key that contains the object's GUID.

```APIDOC
## getGuidKey

### Description
Get the attribute key that contains the object's GUID.

### Method
N/A (SDK method)

### Endpoint
N/A (SDK method)

### Parameters
None

### Request Example
```php
$model->getGuidKey();
```

### Response
#### Success Response
- Returns the attribute key string.

#### Response Example
```php
// Returns: 'objectguid'
$model->getGuidKey();
```
```

--------------------------------

### Long Chain Example - Chaining multiple transformations

Source: https://ldaprecord.com/docs/core/v3/helpers

Demonstrates chaining multiple transformation methods on a DistinguishedNameBuilder instance.

```php
$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;

```

--------------------------------

### getDateFormat - Get date serialization format

Source: https://ldaprecord.com/docs/core/v3/model-api

Returns the format that dates are serialized to. The example shows the default format.

```php
// Returns: 'Y-m-d\TH:i:sO'
$model->getDateFormat();
```

--------------------------------

### Configure LdapRecord Connection with all options

Source: https://ldaprecord.com/docs/core/v3/configuration

Creates an LdapRecord Connection with mandatory and optional LDAP configuration options. Mandatory keys are hosts, base_dn, username, and password; optional keys include port, protocol, use_ssl, use_tls, use_sasl, version, timeout, and follow_referrals. Custom LDAP options and SASL bind options are also supported.

```php
use LdapRecord\Connection;

$connection = new Connection([
    // Mandatory Configuration Options
    'hosts'            => ['192.168.1.1'],
    'base_dn'          => 'dc=local,dc=com',
    'username'         => 'cn=admin,dc=local,dc=com',
    'password'         => 'password',

    // Optional Configuration Options
    'port'             => 389,
    'protocol'         => 'ldap://',
    'use_ssl'          => false,
    'use_tls'          => false,
    'use_sasl'         => false,
    'version'          => 3,
    'timeout'          => 5,
    'follow_referrals' => false,

    // Custom LDAP Options
    'options' => [
        // See: http://php.net/ldap_set_option
        LDAP_OPT_X_TLS_REQUIRE_CERT => LDAP_OPT_X_TLS_HARD
    ],
    
    // See: https://www.php.net/manual/en/function.ldap-sasl-bind.php
    'sasl_options' => [
        'mech' => null,
        'realm' => null,
        'authc_id' => null,
        'authz_id' => null,
        'props' => null,
    ],
]);
```

--------------------------------

### Associate multiple users to a group

Source: https://ldaprecord.com/docs/core/v3/model-relationships

Shows how to batch associate multiple users to a group using associate() and then save() the group.

```php
$group = Group::find('cn=Accounting,dc=local,dc=com');

$users = User::in('ou=Office,dc=local,dc=com')->get();

$group->members()->associate($users);

$group->save();
```

--------------------------------

### getObjectGuid

Source: https://ldaprecord.com/docs/core/v3/model-api

Get the raw binary object GUID. Returns raw binary for Active Directory, raw string for other LDAP directories.

```APIDOC
## getObjectGuid

### Description
Get the raw binary object GUID. Returns raw binary for Active Directory, raw string for other LDAP directories.

### Method
N/A (SDK method)

### Endpoint
N/A (SDK method)

### Parameters
None

### Request Example
```php
$rawBinary = $model->getObjectGuid();
```

### Response
#### Success Response
- Returns the raw binary or string GUID.

#### Response Example
```php
$rawBinary = $model->getObjectGuid();
```
```

--------------------------------

### Mock bind attempt with actingAs

Source: https://ldaprecord.com/docs/core/v3/testing

Use DirectoryFake::setup()->actingAs() to permit a bind attempt for a specific distinguished name, allowing any password.

```php
DirectoryFake::setup()->actingAs('cn=admin,dc=local,dc=com');
```

```php
\LdapRecord\Container::addConnection(
    $connection = new \LdapRecord\Connection(['...'])
);

// Successful.
$connection->bind('cn=admin,dc=local,dc=com', 'secret');
```

--------------------------------

### getHidden - Get hidden attributes

Source: https://ldaprecord.com/docs/core/v3/model-api

Returns the hidden attributes for the model. The example shows adding a hidden attribute and retrieving the list.

```php
$model->addHidden('cn');

// Returns: ['cn']
$model->getHidden();
```

--------------------------------

### newInstance - Create new query instance

Source: https://ldaprecord.com/docs/core/v3/searching-api

Creates a new query instance. Can inherit the base DN from the previous instance or use a new base DN.

```php
$query = $connection->query();

// Create and inherit the base DN from the previous instance:
$newQuery = $query->newInstace();

// Use a new base DN:
$newQuery = $query->newInstace('ou=Users,dc=local,dc=com');
```

--------------------------------

### getGlobalScopes - Get global scopes

Source: https://ldaprecord.com/docs/core/v3/model-api

Returns the global scopes set on the model. The example shows adding a global scope and then retrieving it.

```php
Model::addGlobalScope('my-scope', function () {
    // ...
});

// Returns: ['my-scope' => \Closure]
$scopes = $model->getGlobalScopes();
```

--------------------------------

### getDn - Get Distinguished Name

Source: https://ldaprecord.com/docs/core/v3/model-api

Returns the model's Distinguished Name. The example shows the output for a model with a specific DN.

```php
// Displays: 'cn=John Doe,dc=local,dc=com'
echo $model->getDn();
```

--------------------------------

### Create and enable an Active Directory user with LdapRecord

Source: https://ldaprecord.com/docs/core/v3/active-directory/users

Creates an Active Directory user with required attributes (cn, unicodePwd, samaccountname, userPrincipalName), saves it, refreshes attributes, then enables the account by setting userAccountControl to 512. Wrap saving in a try/catch to handle domain password policy failures.

```php
<?php

use LdapRecord\Models\ActiveDirectory\User;

$user = (new User)->inside('ou=Users,dc=local,dc=com');

$user->cn = 'John Doe';
$user->unicodePwd = 'SecretPassword';
$user->samaccountname = 'jdoe';
$user->userPrincipalName = 'jdoe@acme.org';

$user->save();

// Sync the created users attributes.
$user->refresh();

// Enable the user.
$user->userAccountControl = 512;

try {
    $user->save();
} catch (\LdapRecord\LdapRecordException $e) {
    // Failed saving user.
}

```

--------------------------------

### getDates - Get attributes mutated to dates

Source: https://ldaprecord.com/docs/core/v3/model-api

Returns an array of attributes that should be mutated to dates. The example shows the default date attributes.

```php
$dates = $model->getDates();

// Displays:
// [
//    'createtimestamp' => 'ldap',
//    'modifytimestamp' => 'ldap',
// ]
var_dump($dates);
```

--------------------------------

### newInstance

Source: https://ldaprecord.com/docs/core/v3/searching-api

Creates a new query instance, optionally with a new base DN.

```APIDOC
## `newInstance`

### Description
Create a new query instance.

### Method
`newInstance(string $baseDn = null)`

### Parameters
- **$baseDn** (string) - Optional - The base DN for the new instance. If not provided, inherits from the previous instance.

### Return Value
- **Builder** - A new query builder instance.

### Example
```php
$query = $connection->query();

// Create and inherit the base DN from the previous instance:
$newQuery = $query->newInstace();

// Use a new base DN:
$newQuery = $query->newInstace('ou=Users,dc=local,dc=com');
```
```

--------------------------------

### getName - Get name of model

Source: https://ldaprecord.com/docs/core/v3/model-api

Returns the name of the model, typically the CN value. The example shows setting a DN and retrieving the name.

```php
$model->setDn('cn=John Doe,dc=local,dc=com');

// Returns: 'John Doe'
$name = $model->getName();
```

--------------------------------

### Logged Output for LdapRecord\Auth\Events\Binding

Source: https://ldaprecord.com/docs/core/v3/logging

Example log output for the LdapRecord\Auth\Events\Binding event, showing the LDAP server URI, operation class, and username.

```text
LDAP (ldap://192.168.1.1:389) - Operation: LdapRecord\Auth\Events\Binding - Username: CN=Steve Bauman,OU=Users,DC=local,DC=com

```

--------------------------------

### Register a listener with a closure

Source: https://ldaprecord.com/docs/core/v3/events

Retrieve the event dispatcher and call listen() with the event class and a closure. The closure receives the event object, exposing properties like connection, username, and password.

```php
use LdapRecord\Container;
use LdapRecord\Auth\Events\Binding;

$dispatcher = Container::getDispatcher();

$dispatcher->listen(Binding::class, function (Binding $event) {
    $event->connection; // LdapRecord\Connections\Ldap instance
    $event->username; // 'jdoe@acme.org'
    $event->password; // 'super-secret'
});
```

--------------------------------

### getModifications - Get batch modifications

Source: https://ldaprecord.com/docs/core/v3/model-api

Returns the model's batch modifications to be processed. The example shows changing an attribute and then retrieving the modifications array.

```php
$model->cn = 'Changed';

// Returns:
// [
//      [
//      'attrib' => 'cn',
//      'modtype' => 1,
//      'values' => ['Changed'],
//     ]
// ]
$mods = $model->getModifications();
```

--------------------------------

### Swap a named connection with a fake

Source: https://ldaprecord.com/docs/core/v3/testing

Uses DirectoryFake::setup with a connection name to mock a specific non-default LDAP connection.

```php
use LdapRecord\Testing\DirectoryFake;

public function test()
{
    $fake = DirectoryFake::setup('alpha');
    
    // Returns instanceof \LdapRecord\Testing\ConnectionFake
    // \LdapRecord\Container::getConnection('alpha');
}
```

--------------------------------

### getFirstAttribute - Get first value of attribute

Source: https://ldaprecord.com/docs/core/v3/model-api

Returns the first value of a multi-valued attribute. The example shows setting an array and retrieving the first element.

```php
$model->proxyaddresses = ['first', 'second'];

// Returns: 'first'
$value = $model->getFirstAttribute('proxyaddresses');
```

--------------------------------

### Authenticate with attempt()

Source: https://ldaprecord.com/docs/core/v3/connections

Use auth()->attempt() to validate a username and password. After the attempt, the configured user is rebound to the server.

```php
$user = 'cn=user,dc=local,dc=com';
$password = 'secret';

if ($connection->auth()->attempt($user, $password))
{
    echo "Username and password are correct!";
}
```

--------------------------------

### getDirty - Get changed attributes

Source: https://ldaprecord.com/docs/core/v3/model-api

Returns the attributes that have been changed on the model. The example shows iterating over the dirty attributes and displaying the attribute name and values.

```php
$model->cn = 'Changed';

foreach ($model->getDirty() as $attribute => $values) {
    // Displays: 'cn'
    echo $attribute;

    // Displays: ['Changed']
    var_dump($values);
}
```

--------------------------------

### Logged Output for LdapRecord\Auth\Events\Attempting

Source: https://ldaprecord.com/docs/core/v3/logging

Example log output for the LdapRecord\Auth\Events\Attempting event, showing the LDAP server URI, operation class, and username.

```text
LDAP (ldap://192.168.1.1:389) - Operation: LdapRecord\Auth\Events\Attempting - Username: CN=Steve Bauman,OU=Users,DC=local,DC=com

```

--------------------------------

### getCreatableDn - Get creatable DN

Source: https://ldaprecord.com/docs/core/v3/model-api

Returns the model's creatable Distinguished Name. The example shows how the DN changes when the 'cn' attribute is modified.

```php
$model = new Entry(['cn' => 'John Doe']);

// Returns: 'cn=John Doe,dc=local,dc=com'
$creatableDn = $model->getCreatableDn();

$model->cn = 'Jane Doe';

// Returns: 'cn=Jane Doe,dc=local,dc=com'
$creatableDn = $model->getCreatableDn();
```

--------------------------------

### getAppends - Get appended accessors

Source: https://ldaprecord.com/docs/core/v3/model-api

Returns the accessors that have been appended to the model's array form. The example shows setting an append and then dumping the result.

```php
$model->setAppends(['foo-bar']);

// Displays:
// [
//    'foo-bar',
// ]
var_dump($model->getAppends());
```

--------------------------------

### Logged Output for LdapRecord\Models\Events\Creating

Source: https://ldaprecord.com/docs/core/v3/logging

Example log output for the LdapRecord\Models\Events\Creating event, showing the operation, model class, and distinguished name.

```text
LDAP (ldap://192.168.1.1:389) - Operation: Creating - On: LdapRecord\Models\Entry - Distinguished Name: cn=John Doe,DC=local,DC=com

```

--------------------------------

### setDn - Set base Distinguished Name

Source: https://ldaprecord.com/docs/core/v3/searching-api

Sets the base Distinguished Name to perform a search upon. The example shows getting all entries below the 'Users' OU.

```php
$query = $connection->query();

// Get all entries below the 'Users' OU:
$query->setDn('ou=Users,dc=local,dc=com')->get();

```

--------------------------------

### getOriginal - Get original attributes

Source: https://ldaprecord.com/docs/core/v3/model-api

Returns the original, un-modified attributes on a model. The example shows finding a model, changing an attribute, and then retrieving the original values.

```php
$model = Model::findBy('cn', 'Steve Bauman');

$model->cn = 'Changed';

// Returns:
// [
//    'cn' => ['Steve Bauman']
//    ...
// ]
$model->getOriginal();
```

--------------------------------

### Attach using raw distinguished names

Source: https://ldaprecord.com/docs/core/v3/model-relationships

Shows how to attach a group to a user using a raw DN string or an array of DNs.

```php
$user = User::find('cn=John Doe,ou=Users,dc=local,dc=com');

$user->groups()->attach('cn=Accounting,dc=local,dc=com');

// Multiple groups:

$user->groups()->attach([
    'cn=Office,dc=local,dc=com',
    'cn=Accounting,dc=local,dc=com',
]);
```

--------------------------------

### Add an LDAP connection to the container

Source: https://ldaprecord.com/docs/core/v3/testing

Initializes an LDAP connection with configuration and adds it to the LdapRecord container.

```php
// Adding an LDAP connection somewhere in your application...

\LdapRecord\Container::addConnection(
    new \LdapRecord\Connection(['...'])
);
```

--------------------------------

### getCreatableRdn - Get creatable RDN

Source: https://ldaprecord.com/docs/core/v3/model-api

Returns the model's creatable relative Distinguished Name. The example shows how the RDN changes when the 'cn' attribute is modified.

```php
$model = new Entry(['cn' => 'John Doe']);

// Returns: 'cn=John Doe'
$creatableDn = $model->getCreatableRdn();

$model->cn = 'Jane Doe';

// Returns: 'cn=Jane Doe'
$creatableDn = $model->getCreatableRdn();
```

--------------------------------

### Associate a single user to a group

Source: https://ldaprecord.com/docs/core/v3/model-relationships

Shows how to associate a single user to a group using associate() and then save() the group.

```php
$group->members()->associate(
    User::find('cn=John Doe,dc=local,dc=com')
);

$group->save();
```

--------------------------------

### getParentDn - Get parent Distinguished Name

Source: https://ldaprecord.com/docs/core/v3/model-api

Returns the direct parent Distinguished Name of a model. The example shows retrieving the parent DN for a model and for a specific DN.

```php
$model = Model::find('cn=John Doe,dc=local,dc=com');

// Returns: 'dc=local,dc=com'
$model->getParentDn();

// Returns: 'ou=Users,dc=local,dc=com'
$model->getParentDn('cn=Steve Bauman,ou=Users,dc=local,dc=com');
```

--------------------------------

### getConnectionName - Get connection name

Source: https://ldaprecord.com/docs/core/v3/model-api

Returns the connection name set on the model. If no connection is set, null is returned. The example defines a model with a connection property and retrieves it.

```php
class Entry extends Model
{
    protected ?string $connection = 'domain-b';
}

// Returns 'domain-b'
$connectionName = (new Entry)->getConnectionName();
```

--------------------------------

### Connect to LDAP with account or anonymously

Source: https://ldaprecord.com/docs/core/v3/authentication

Shows two ways to connect to an LDAP directory before searching for a user: with an account (providing username and password) or anonymously (omitting credentials, if enabled). Both require a base_dn so LdapRecord knows where to start searching. Using a dedicated web application account is recommended over a personal or domain administrator account.

```php
// Connecting with an an account...
$connection = new \LdapRecord\Connection([
    'hosts' => ['127.0.0.1'],
    'base_dn' => 'dc=local,dc=com',
    'username' => 'cn=WebApi,dc=local,dc=com',
    'password' => 'super-secret',
]);

$connection->connect();

// Anonymously binding...
$connection = new \LdapRecord\Connection([
    'hosts' => ['127.0.0.1'],
    'base_dn' => 'dc=local,dc=com',
]);

$connection->connect();
```

--------------------------------

### Placeholder

Source: https://ldaprecord.com/docs/core/v3/models

Placeholder

```php
// ...
```

```php
// ...
```

--------------------------------

### Retrieve all User models with User::get()

Source: https://ldaprecord.com/docs/core/v3/models

Retrieves all User models from the directory and iterates over them, calling getFirstAttribute('cn') on each. This is the basic pattern for fetching and processing models.

```php
<?php

$users = User::get();

foreach ($users as $user) {
    $user->getFirstAttribute('cn');
}

```

--------------------------------

### getVisible: Get visible attributes for JSON encoding

Source: https://ldaprecord.com/docs/core/v3/model-api

Returns the list of attributes that are visible when encoding the model with json_encode. The example first adds 'cn' and 'sn' to the visible list, then retrieves it.

```php
$model->addVisible('cn', 'sn');

// Returns: ['cn', 'sn']
$visibleAttributes = $model->getVisible();
```

--------------------------------

### Create DistinguishedName builder with build

Source: https://ldaprecord.com/docs/core/v3/helpers

Create a DistinguishedName builder, either pre-populated with a DN string or empty.

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

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

--------------------------------

### Determine the connection in an authentication event

Source: https://ldaprecord.com/docs/core/v3/events

Shows how to get the LDAP connection host from an authentication event. The example listens to the Binding event and retrieves the host from the event's connection property.

```php
use LdapRecord\Container;
use LdapRecord\Auth\Events\Binding;

$dispatcher = Container::getDispatcher();

$dispatcher->listen(Binding::class, function ($event) {
    $connection = $event->connection;

    $host = $connection->getHost();

    echo $host; // Displays 'ldap://192.168.1.1:386'
});
```

--------------------------------

### Guid::isValid - Validate GUID strings

Source: https://ldaprecord.com/docs/core/v3/helpers

Checks if a string is a valid GUID. Returns true for valid GUIDs and false for invalid ones.

```php
// 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('');
```

--------------------------------

### Dynamic where example

Source: https://ldaprecord.com/docs/core/v3/searching

Shows converting a standard where clause to a dynamic where method (whereCn).

```php
// This query:
$result = $query->where('cn', '=', 'John Doe')->first();

// Can be converted to:
$result = $query->whereCn('John Doe')->first();
```

--------------------------------

### Guid::isValid

Source: https://ldaprecord.com/docs/core/v3/helpers

Determines if a given string is a valid GUID. Returns true for valid GUIDs and false for invalid ones.

```APIDOC
## Guid::isValid

### Description
Determines if a given string is a valid GUID.

### Method
isValid

### Parameters
- **string** (string) - Required - The string to validate as a GUID.

### Returns
- **bool** - True if the string is a valid GUID, false otherwise.

### Example
php
// 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('');

```

--------------------------------

### Listen to model events with Container::getDispatcher()

Source: https://ldaprecord.com/docs/core/v3/models

Retrieve the event dispatcher from the LdapRecord container and register a listener for the Creating event. Set up listeners before making model changes to ensure they are executed.

```php
<?php

use LdapRecord\Container;
use LdapRecord\Models\Events\Creating;

$dispatcher = Container::getDispatcher();

$dispatcher->listen(Creating::class, function ($event) {
    $model = $event->getModel();
});

```

--------------------------------

### Logged Output for LdapRecord\Auth\Events\Bound

Source: https://ldaprecord.com/docs/core/v3/logging

Example log output for the LdapRecord\Auth\Events\Bound event, showing the LDAP server URI, operation class, and username.

```text
LDAP (ldap://192.168.1.1:389) - Operation: LdapRecord\Auth\Events\Bound - Username: CN=Steve Bauman,OU=Users,DC=local,DC=com

```

--------------------------------

### Get groups recursively with groups()->recursive()->get()

Source: https://ldaprecord.com/docs/core/v3/active-directory/groups

Retrieves all parent groups in the hierarchy by calling `recursive()` before `get()` on the `groups` relationship.

```php
$group = Group::find('cn=Accounting,dc=local,dc=com');

$allGroups = $group->groups()->recursive()->get();

```
Tokens:
Raw