ldap_control_paged_result — Funktion · PHP-Referenz

Signatur

ldap_control_paged_result(LDAP\Connection $ldap, int $pagesize, bool $iscritical = false, string $cookie = ''): bool

Beschreibung

ldap_control_paged_result() aktiviert die serverseitige Paginierung von LDAP-Suchergebnissen gemäß RFC 2696. Anstatt alle Einträge auf einmal abzurufen, können große Verzeichnisabfragen in überschaubare Seiten unterteilt werden. Dies ist besonders wichtig, wenn LDAP-Server serverseitige Limits für die maximale Trefferzahl (z. B. 1000 Einträge) erzwingen.

Die Funktion muss vor dem eigentlichen ldap_search()-Aufruf aufgerufen werden, um die Paginierungssteuerung für die Verbindung zu setzen. Nach dem Abrufen einer Seite wird über ldap_control_paged_result_response() ein Cookie ermittelt, das beim nächsten Aufruf von ldap_control_paged_result() übergeben werden muss, um die nächste Seite anzufordern. Das Ende der Ergebnisse ist erreicht, wenn das Cookie leer ist.

Der Parameter $iscritical gibt an, ob der Server die Anfrage ablehnen soll, wenn er die Paginierungssteuerung nicht unterstützt. Wird er auf true gesetzt und der Server unterstützt RFC 2696 nicht, schlägt die Suche fehl, anstatt ungepaginierte Ergebnisse zurückzugeben.

Hinweis: Diese Funktion ist seit PHP 7.4 als veraltet (deprecated) markiert und wurde in PHP 8.0 entfernt. Als Ersatz sollte der controls-Parameter von ldap_search() zusammen mit LDAP_CONTROL_PAGEDRESULTS verwendet werden.

Parameter

Name	Typ	Default	Beschreibung
$ldap Pflicht	LDAP\Connection		Eine gültige LDAP-Verbindungsressource, wie sie von `ldap_connect()` zurückgegeben wird.
$pagesize Pflicht	int		Die maximale Anzahl von Einträgen, die pro Seite zurückgegeben werden sollen.
$iscritical	bool	false	Gibt an, ob die Paginierungssteuerung als kritisch eingestuft wird. Wenn `true`, lehnt der Server die Anfrage ab, falls er Paginierung nicht unterstützt.
$cookie	string		Das vom Server zurückgegebene Cookie aus dem vorherigen `ldap_control_paged_result_response()`-Aufruf. Beim ersten Aufruf leer lassen oder einen leeren String übergeben.

Rückgabewert

Typ

bool

Beschreibung

Gibt true bei Erfolg zurück, false bei einem Fehler (z. B. ungültige Verbindung oder nicht unterstützte Steuerung bei gesetztem $iscritical).

Beispiele

Alle Benutzer seitenweise aus dem LDAP abrufen (PHP 5.4–7.3)

<?php
$ds = ldap_connect('ldap://ldap.example.com');
ldap_set_option($ds, LDAP_OPT_PROTOCOL_VERSION, 3);
ldap_bind($ds, 'cn=admin,dc=example,dc=com', 'geheimespasswort');

$baseDn  = 'ou=users,dc=example,dc=com';
$filter  = '(objectClass=inetOrgPerson)';
$pageSize = 100;
$cookie  = '';

do {
    // Paginierungssteuerung setzen
    ldap_control_paged_result($ds, $pageSize, true, $cookie);

    $result = ldap_search($ds, $baseDn, $filter, ['cn', 'mail']);

    if (!$result) {
        echo 'Suche fehlgeschlagen: ' . ldap_error($ds);
        break;
    }

    $entries = ldap_get_entries($ds, $result);
    echo 'Einträge auf dieser Seite: ' . $entries['count'] . PHP_EOL;

    for ($i = 0; $i < $entries['count']; $i++) {
        echo $entries[$i]['cn'][0] . ' <' . ($entries[$i]['mail'][0] ?? 'keine Mail') . '>' . PHP_EOL;
    }

    // Cookie für die nächste Seite abrufen
    ldap_control_paged_result_response($ds, $result, $cookie);

} while (!empty($cookie));

ldap_unbind($ds);

Einträge auf dieser Seite: 100 Max Mustermann <max.mustermann@example.com> ... Einträge auf dieser Seite: 42 ...

Moderner Ersatz mit ldap_search()-Controls (PHP 8.0+)

<?php
// Ab PHP 8.0: ldap_control_paged_result() ist entfernt.
// Stattdessen: controls-Parameter von ldap_search() nutzen.

$ds = ldap_connect('ldap://ldap.example.com');
ldap_set_option($ds, LDAP_OPT_PROTOCOL_VERSION, 3);
ldap_bind($ds, 'cn=admin,dc=example,dc=com', 'geheimespasswort');

$baseDn   = 'ou=users,dc=example,dc=com';
$filter   = '(objectClass=inetOrgPerson)';
$pageSize = 100;
$cookie   = '';

do {
    $controls = [
        [
            'oid'        => LDAP_CONTROL_PAGEDRESULTS,
            'isCritical' => true,
            'value'      => [
                'size'   => $pageSize,
                'cookie' => $cookie,
            ],
        ],
    ];

    $result = ldap_search($ds, $baseDn, $filter, ['cn', 'mail'], 0, 0, 0, LDAP_DEREF_NEVER, $controls);

    $entries = ldap_get_entries($ds, $result);
    echo 'Einträge auf dieser Seite: ' . $entries['count'] . PHP_EOL;

    // Antwort-Controls auslesen
    ldap_parse_result($ds, $result, $errcode, $matcheddn, $errmsg, $referrals, $serverctrls);
    $cookie = $serverctrls[LDAP_CONTROL_PAGEDRESULTS]['value']['cookie'] ?? '';

} while (!empty($cookie));

ldap_unbind($ds);

Einträge auf dieser Seite: 100 ...

// Wichtig · Fallstricke

Deprecation: ldap_control_paged_result() ist seit PHP 7.4.0 als veraltet markiert und wurde in PHP 8.0.0 vollständig entfernt. Neuer Code sollte stets den controls-Parameter von ldap_search() in Verbindung mit der Konstante LDAP_CONTROL_PAGEDRESULTS verwenden.

Die Paginierungssteuerung ist global für die LDAP-Verbindung. Das bedeutet, dass bei gleichzeitiger Verwendung mehrerer Verbindungen oder Threads Konflikte auftreten können. Es sollte stets eine dedizierte Verbindung pro Paginierungsvorgang verwendet werden.

Nicht alle LDAP-Server unterstützen RFC 2696. Active Directory und OpenLDAP unterstützen es in der Regel, ältere oder einfachere LDAP-Implementierungen jedoch möglicherweise nicht. Wenn $iscritical auf true gesetzt ist und der Server keine Paginierung unterstützt, schlägt die gesamte Suche fehl.

Siehe auch

ldap_control_paged_result_response ldap_search ldap_connect ldap_get_entries ldap_parse_result