Getting Started

Minimal Setup

Installation:
```
composer require directorytree/ldaprecord-browser
```
The package auto-registers its LdapRecordBrowserServiceProvider, so no manual registration is needed.
Publish Config: Publish the default config to config/ldaprecord-browser.php:
```
php artisan vendor:publish --provider="DirectoryTree\LdapRecordBrowser\LdapRecordBrowserServiceProvider"
```
Configure your LDAP connection (e.g., host, base DN, bind DN, password) in the config file.

First Use Case: Use the LdapRecordBrowser facade to browse LDAP entries in a Livewire component:

use DirectoryTree\LdapRecordBrowser\Facades\LdapRecordBrowser;

public function browse($baseDn = null) {
    $baseDn = $baseDn ?? config('ldaprecord-browser.default_base_dn');
    return LdapRecordBrowser::browse($baseDn);
}

Implementation Patterns

Core Workflows

Livewire Integration: Extend the provided LdapRecordBrowserComponent or create a custom Livewire component to render LDAP data:

namespace App\Http\Livewire;

use DirectoryTree\LdapRecordBrowser\Facades\LdapRecordBrowser;
use Livewire\Component;

class LdapBrowser extends Component {
    public $baseDn = '';
    public $results = [];

    public function mount() {
        $this->baseDn = config('ldaprecord-browser.default_base_dn');
    }

    public function browse() {
        $this->results = LdapRecordBrowser::browse($this->baseDn);
    }

    public function render() {
        return view('livewire.ldap-browser', ['results' => $this->results]);
    }
}

Searching and Filtering: Use the search() method to query specific entries:

$users = LdapRecordBrowser::search('ou=users,dc=example,dc=com', '(objectClass=person)');

Pagination: Leverage Livewire's built-in pagination for large LDAP datasets:

public function browse() {
    $this->results = LdapRecordBrowser::paginate($this->baseDn, 10);
}

Attribute Selection: Fetch only specific attributes to optimize performance:

$attributes = ['cn', 'mail', 'telephoneNumber'];
$entries = LdapRecordBrowser::browse($this->baseDn, $attributes);

Integration Tips

Caching: Cache frequent LDAP queries using Laravel's cache system:

$cacheKey = "ldap_{$this->baseDn}";
$results = cache()->remember($cacheKey, now()->addMinutes(5), function () {
    return LdapRecordBrowser::browse($this->baseDn);
});

Error Handling: Wrap LDAP calls in try-catch blocks to handle connection issues gracefully:

try {
    $results = LdapRecordBrowser::browse($this->baseDn);
} catch (\DirectoryTree\LdapRecord\Exceptions\ConnectionException $e) {
    session()->flash('error', 'LDAP connection failed: ' . $e->getMessage());
}

Blade Views: Use Blade to render LDAP data dynamically:

@foreach($results as $entry)
    <div>
        <h3>{{ $entry->getAttribute('cn') }}</h3>
        <p>Email: {{ $entry->getAttribute('mail') }}</p>
    </div>
@endforeach

Gotchas and Tips

Pitfalls

Connection Timeouts:
- LDAP queries can time out if the server is slow or the query is complex. Use setOption() to adjust timeouts:
```
LdapRecordBrowser::setOption('timeout', 30);
```
Base DN Misconfiguration:
- Ensure the default_base_dn in the config matches your LDAP structure. Incorrect values will return no results or errors.
Livewire State Persistence:
- Livewire components may lose state if the LDAP query takes too long. Use wire:ignore or wire:key to mitigate:
```
<div wire:ignore>{{ $this->results->links() }}</div>
```
Attribute Name Variations:
- LDAP attribute names can vary by server (e.g., telephoneNumber vs. telephone). Test with your specific LDAP schema.

Debugging

Enable LDAP Logging: Add this to your config/ldaprecord-browser.php:
```
'debug' => env('LDAP_DEBUG', false),
```
Check Laravel logs for LDAP query details.
Use spatie/ray: The package includes Ray integration for debugging. Install it in composer.json:
```
"require-dev": {
    "spatie/ray": "^1.25"
}
```
Then inspect LDAP records in the Ray dashboard.

Extension Points

Custom Attributes: Extend the LdapRecordBrowser facade to add custom attribute mappings:

namespace App\Services;

use DirectoryTree\LdapRecordBrowser\Facades\LdapRecordBrowser as BaseLdapRecordBrowser;

class LdapRecordBrowser extends BaseLdapRecordBrowser {
    public function getCustomAttribute($entry, $attribute) {
        return $entry->getAttribute($attribute) ?? 'N/A';
    }
}

Override Search Logic: Create a decorator for the LdapRecordBrowser service:

namespace App\Providers;

use DirectoryTree\LdapRecordBrowser\Facades\LdapRecordBrowser;
use Illuminate\Support\ServiceProvider;

class LdapRecordBrowserServiceProvider extends ServiceProvider {
    public function boot() {
        $this->app->extend('ldaprecord-browser', function ($browser) {
            return new class($browser) {
                public function __construct($browser) {
                    $this->browser = $browser;
                }

                public function customSearch($baseDn, $filter) {
                    // Custom logic here
                    return $this->browser->search($baseDn, $filter);
                }
            };
        });
    }
}

Add Custom Views: Override the default Livewire view by publishing and modifying:
```
php artisan vendor:publish --tag=ldaprecord-browser-views
```
Then update resources/views/vendor/ldaprecord-browser/livewire.blade.php.

Configuration Quirks

Environment Variables: Use .env for sensitive LDAP credentials:

LDAP_HOST=ldap.example.com
LDAP_BASE_DN=dc=example,dc=com
LDAP_BIND_DN=cn=admin,dc=example,dc=com
LDAP_PASSWORD=yourpassword

Then reference them in config/ldaprecord-browser.php:

'connections' => [
    'default' => [
        'host' => env('LDAP_HOST'),
        'base_dn' => env('LDAP_BASE_DN'),
        'bind_dn' => env('LDAP_BIND_DN'),
        'password' => env('LDAP_PASSWORD'),
    ],
],

SSL/TLS: Enable LDAPS by adding to the config:

'use_ssl' => env('LDAP_USE_SSL', false),
'port' => env('LDAP_PORT', 636),

Performance Tips

Limit Scope: Restrict searches to specific organizational units (OUs) to reduce query load:

$ou = 'ou=users,dc=example,dc=com';
$users = LdapRecordBrowser::search($ou, '(objectClass=person)');

Batch Processing: For large datasets, use pagination or batch processing:

$page = 1;
$perPage = 50;
$results = LdapRecordBrowser::paginate($this->baseDn, $perPage, $page);

Avoid Eager Loading: LDAP queries can be resource-intensive. Load attributes on-demand:

$entry = LdapRecordBrowser::find('cn=John Doe,ou=users,dc=example,dc=com');
$email = $entry->getAttribute('mail'); // Load only when needed

Ldaprecord Browser Laravel Package