ldap_read

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_read — Liest einen Eintrag

Beschreibung

ldap_read(
    LDAP\Connection|array $ldap,
    array|string $base,
    array|string $filter,
    array $attributes = [],
    int $attributes_only = 0,
    int $sizelimit = -1,
    int $timelimit = -1,
    int $deref = LDAP_DEREF_NEVER,
    ?array $controls = null
): LDAP\Result|array|false

Führt eine Suche nach dem angegeben filter im Verzeichnis mit dem Geltungsbereich LDAP_SCOPE_BASE durch. Somit ist es gleichwertig zum Lesen eines Eintrags aus dem Verzeichnis.

Es ist auch möglich, parallele Suchen durchzuführen. In diesem Fall muss der erste Parameter ein Array von LDAP\Connection-Instanzen sein, anstatt einer einzelnen. Wenn die Suchen nicht alle den gleichen Basis-DN und Filter verwenden sollen, kann stattdessen ein Array von Basis-DNs und/oder ein Array von Filtern als Parameter übergeben werden. Diese Arrays müssen die gleiche Größe haben wie das Array von LDAP\Connection-Instanzen, da die ersten Einträge der Arrays für eine Suche verwendet werden, die zweiten Einträge für eine andere und so weiter. Bei parallelen Suchen wird ein Array von LDAP\Result-Instanzen zurückgegeben, außer im Fall eines Fehlers, dann ist der Rückgabewert false.

Parameter-Liste

ldap

Eine LDAP\ConnectionInstanz, die von ldap_connect() zurückgegeben wurde.

base

Der Basis-DN für das Verzeichnis.

filter

Ein leerer Filter ist nicht erlaubt. Sollen alle Information zu einem Eintrag ermittelt werden, ist ein objectClass=*-Filter zu verwenden. Wenn bekannt ist, welche Eintragstypen auf dem Verzeichnis-Server verwendet werden, könnte ein entsprechender Filter, wie objectClass=inetOrgPerson verwendet werden.

attributes

Ein Array von erforderlichen Merkmalen, z. B. array("mail", "sn", "cn"). Es ist zu beachten, dass der "dn" immer zurückgegeben wird, unabhängig davon, welche Merkmalstypen angefordert wurden.

Die Verwendung dieses Parameters ist effizienter als die Standardaktion (die alle Merkmale und deren assoziierte Werte zurückgibt). Die Verwendung dieses Parameters sollte daher als gute Praxis eingestuft werden.

attributes_only

Sollte auf 1 gesetzt werden, wenn nur Merkmalstypen erwünscht sind. Wird 0 übergeben, werden sowohl Merkmalstypen als auch Merkmalswerte abgerufen, was das Standardverhalten ist.

sizelimit

Ermöglicht die Begrenzung der Anzahl der abgerufenen Einträge. Wird hier 0 übergeben, besteht keine Begrenzung.

Hinweis:
Dieser Parameter kann ein serverseitig voreingestelltes sizelimit NICHT überschreiben. Es kann allerdings kleiner gewählt werden.

Verzeichnis-Server können so konfiguriert werden, dass sie nicht mehr als eine voreingestellte Anzahl von Einträgen zurückgeben. Wenn dies der Fall ist, dann zeigt der Server an, dass nur eine teilweise Ergebnismenge zurückgegeben wurde. Das geschieht ebenfalls, wenn dieser Parameter verwendet wird, um die Zahl der abgerufenen Einträge zu begrenzen.

timelimit

Setzt die Anzahl von Sekunden, die auf die Suche verwendet wird. Die Übergabe von 0 bedeutet keine Begrenzung.

Hinweis:
Dieser Parameter kann ein serverseitig voreingestelltes timelimit NICHT überschreiben. Es kann allerdings kleiner gewählt werden.

deref

Gibt an, wie Aliase während der Suche behandelt werden sollen. Es kann einen der folgenden Werte annehmen:

LDAP_DEREF_NEVER - (standard) Aliase werden nie dereferenziert.
LDAP_DEREF_SEARCHING - Aliase sollen während der Suche dereferenziert werden, aber nicht wenn das Basis-Objekt der Suche lokalisiert wird.
LDAP_DEREF_FINDING - Aliase sollen für die Lokalisierung des Basis-Objekts dereferenziert werden, aber nicht während der Suche.
LDAP_DEREF_ALWAYS - Aliase sollen immer dereferenziert werden.

controls

Ein Array von LDAP-Steuerbefehlen, die mit der Anfrage versendet werden sollen.

Rückgabewerte

Gibt eine LDAP\Result-Instanz oder ein Array von LDAP\Result-Instanzen zurück. Bei einem Fehler wird false zurückgegeben.

Changelog

Version	Beschreibung
8.1.0	Der Parameter `ldap` erwartet nun eine LDAP\Connection-Instanz; vorher wurde eine gültige `ldap link`-Ressource erwartet.
8.1.0	Gibt nun eine LDAP\Result-Instanz zurück; vorher wurde eine Ressource zurückgegeben.
8.0.0	`controls` ist nun nullable (akzeptiert den `null`-Wert); vorher war der Standardwert `[]`.
7.3.0	Die Unterstützung für `controls` wurde hinzugefügt.

Found A Problem?

Learn How To Improve This Page • Submit a Pull Request • Report a Bug

＋add a note

User Contributed Notes 5 notes

down

cnicholl at yahoo dot com ¶

19 years ago

Clarification of the ldap_read command syntax:  

If you just want to pull certain attributes from an object and you already know it's dn, the ldap_read command can do this as illustrated below.  It will be less overhead than ldap_search.

The string base_dn which is normally used to set the top context for a recursive ldap_search is used slightly differently with this command.  It is used to specify the actual object with the full dn.  (Hopefully this saves someone else a couple hours trying this command out.)

<?php
$ds = ldap.myserver.com // your ldap server
  $dn = "cn=username,o=My Company, c=US"; //the object itself instead of the top search level as in ldap_search
  $filter="(objectclass=*)"; // this command requires some filter
  $justthese = array("ou", "sn", "givenname", "mail"); //the attributes to pull, which is much more efficient than pulling all attributes if you don't do this
      $sr=ldap_read($ds, $dn, $filter, $justthese);
          $entry = ldap_get_entries($ds, $sr);

echo $entry[0]["mail"][0] . "is the email address of the cn your requested";
echo $entry[0]["sn"][0] . "is the sn of the cn your requested";
ldap_close($ds);
?> 

This prints out the specified users mail and surname for example.

down

me at example dot com ¶

17 years ago

In the previous example the

$ds = ldap.myserver.com // your ldap server

should be 

$ds = ldap_connect( "ldap.myserver.com" ) ; // your ldap server

down

ronny at nxc dot no ¶

11 years ago

The array in the attributes parameter needs to be an indexed array with numeric keys in ascending order. Like this:

Array
(
    [0] => this
    [1] => is
    [2] => a
    [3] => test
)

If there are missing keys in the array, then no result will be returned. This will not work:

Array
(
    [0] => this
    [1] => is
    [3] => test
)

down

ehalls at gmail dot com ¶

6 years ago

For those debugging a wrapper, akin to symfony's client wrapper for these functions and since there is crap documentation on a full cycle of pulling a single record vs multiple, etc.

For this one:
YOU MUST call ldap_get_entries after this function call. 

AND PLEASE if you implement a wrapper, prime it with the initial entry else it makes no sense to execute without returning something easily visible as successful.

WHEN query->execute() and you get a collection.. make sure the entry field in the collection has at least the first entry primed.. wasted so much time because it was looking empty. 

AND this entire adapter needs to be wrapped with a less retarded usage pattern via an STL lib wrapper, mysticism( bad design) begone.
123.. not 4290234~"wds

Thanks for your time

down

-1

sbarnum at mac dot com ¶

23 years ago

This differs from ldap_search() by not recursing down to sub-entries.  if you know the dn of the item you're looking for and only want info on that entry, use ldap_read() and pass it the full dn of the item you want.



It also seems that you'd alway want something like objectclass=* for the filter, since you're only searching on one entry.

＋add a note