Synopsis

array plexcel_search_objects(resource $px, array $params)

Description

The plexcel_search_objects function accepts an array of search parameters $params with which it searches the directory bound through $px and returns an array of results.

The $px parameter must be a Plexcel context created with plexcel_new . The $params parameter may be NULL or an array containing zero or more of the following elements.

All $params parameters are optional. If the $params parameter is NULL or if an element was not specified, default values will be used. Default values may be overridden using the LDAP URL supplied to plexcel_new .

User Input in Filters

When using user supplied data in a filter the data must be properly escaped to prevent the user from accidentally or maliciously injecting their own filter expressions. The following PHP fragment illustrates how to properly escape externally supplied filter data (for an example that allows the user to supply a wildcard, see the plexcel/setup.php script).

$search_expr = plexcel_get_param('p_search_expr', '');
$search_expr = str_replace('*', '\\2a', $search_expr);
$search_expr = str_replace('(', '\\28', $search_expr);
$search_expr = str_replace(')', '\\29', $search_expr);
$search_expr = str_replace('\\', '\\5c', $search_expr);
$search_expr = str_replace('/', '\\2f', $search_expr);
$_params = array('scope' => 'sub',
        'filter' => "(&(objectClass=user)(cn=$search_expr))");
$saccts = plexcel_search_objects($px, $_params);
if (is_array($saccts) == FALSE) {
    ...

Use the Same Directory Server for Data Consistency

When searching for data that may have been just modified, it is important that the same directory server be queried. Otherwise, your application may not display consistent results because the directory servers will not have had time to replicate your changes.

The plexcel_preamble function is designed to remedy this problem. Provided that your HTML form correctly propagates the p_authority request parameter the returned $px and $bindstr parameters will refer to the same directory server across requests. Please review the plexcel_preamble documentation for details.

Alternatively an explicit directory server may be specified with plexcel_new .

Specifying Times in Filters

If you wish to specify a time in a search filter it will be necessary to represent the time value in it's native form and not as the value returned by Plexcel functions that have used automatic attribute conversions. In a future release functions for converting conventional dates to AD nanoseconds since 1601 values may be provided.

Returns

The plexcel_search_objects function returns an array of arrays. Each array represents an object that matches the search criteria. An empty array indicates that no objects were found. A return value of FALSE indicates that an error occurred and that the plexcel_status function should be consulted.

Note that because an empty array in PHP will evaluate to FALSE if tested with the == operator, the return value must be tested with is_array or the === operator to distinguish between an empty array which indicates that no objects where found and FALSE which indicates that an error has occurred.

Example

The following PHP fragment illustrates how to use the plexcel_search_objects function.

// find accounts with a logonCount of 0
$params = array(
    'base' => 'DC=example,DC=com',
    'scope' => 'sub',
    'filter' => '(&(objectClass=user)(logonCount=0))'
);

        $objs = plexcel_search_objects($px, $params);
      
if (is_array($objs) == FALSE) {
    die('<pre>' . plexcel_status($px) . '</pre>');
} else {
    $count = 0;
    foreach ($objs as $obj) { 
        echo $obj['distinguishedName'] . "\n"; 
        $count++;
    }
    echo "$count objects found\n";
    ...

See also

plexcel_new | plexcel_get_account