plexcel_set_attrdefs

Printer Friendly Format

Synopsis

bool plexcel_set_attrdefs(resource $px, array $attrdefs)

Description

The plexcel_set_attrdefs function sets attribute definitions that allow Plexcel functions to accept and return attribute values that are more convenient for the programmer.

Note: Currently attribute definitions do not work with the PLEXCEL_SUPPLEMENTAL flag used with plexcel_get_account.

Attribute definitions for more than 200 attributes commonly found in AD are preloaded which means that it may not be necessary to use this function at all. However, all other attributes, such as those from less commonly used objects or from schema customizations, will be represented within scripts as multivalued and binary (the default behavior is just like the raw LDAP API). In this case, it may be convenient for the programmer to add their own attribute definitions with this function.

The $px parameter is the Plexcel context resource for which attribute definitions will be set. Attribute definitions are limited in scope to the specified Plexcel context and will not affect attribute definitions of other contexts.

The $attrdefs parameter is an array of attribute definitions. An attribute definition is an array containing the elements type, flags and conv described below.

The type element

The type element instructs Plexcel as to how to represent the attribute at the script level. The following table describes the possible type values.

Value	Description
`PLEXCEL_TYPE_STRING`	An attribute of this type will be represented within scripts as a string. The value will automatically be converted from UTF-8 to the default locale encoding Apache runs under (e.g. `ISO-8859-1@euro`).
`PLEXCEL_TYPE_BOOLEAN`	An attribute of this type will be represented within scripts as a boolean. For PHP this means `1` or `0` or the identifiers `TRUE` or `FALSE`. For example, setting a boolean attribute to the string 'FALSE' would probably not produce the desired behavior.
`PLEXCEL_TYPE_BINARY`	An attribute of this type is not modified from it's directory representation.
`PLEXCEL_TYPE_TIME`	An attribute of this type will be represented as a standard LDAP UTC time string like `20070307033755.0Z`.
`PLEXCEL_TYPE_INT32`	An attribute of this type will be represented as a simple integer.
`PLEXCEL_TYPE_INT64`	An attribute of this type will be represented within PHP as a double value.

The flags element

The flags element should be set to PLEXCEL_SINGLE_VALUED if the attribute is single valued or 0 if it is multivalued. If the PLEXCEL_SINGLE_VALUED flag is set, Plexcel functions that return objects will represent the attribute as a simple array value indexed by name (e.g. $obj['name']). Otherwise, like the raw LDAP API, single valued attributes will be represented as a 0 indexed array value within an array indexed by name (e.g. $obj['name'][0]). When manipulating large numbers of attributes, this small change can make your significantly simpler and more efficient.

The conv element

The conv element indicates to Plexcel that certain attributes should be automatically converted between a script-level representation and the directory representation. The conv element values are always in the form PLEXCEL_CONV_<script representation>_X_<directory representation> as shown in the below table of possible conv values.

Value	Description
`PLEXCEL_CONV_BASE64_X_BINARY`	This `conv` value automatically converts between a base 64 encoding within scripts and binary within the directory. For example, an `objectGUID` attribute would be represented within scripts as the string `t7xt74WBqUW6iS1gKsr11A==. This conversion helps prevent scripts from emitting garbage data at the user or into data files.`
`PLEXCEL_CONV_SIDSTR_X_BINARY`	This `conv` value automatically converts between a SID string like `S-1-5-21-4133389617-793951518-2001521813-1341` and it's binary representation in the directory. This conversion is useful for SID binding and advanced utilities that work with SIDs.
`PLEXCEL_CONV_TIME1970M_X_TIMEUTC`	This `conv` value automatically converts between milliseconds since 1970 and a UTC time string like `20060719203335.0Z`. This conversion is ideal for producing human readable dates and performing date logic. See the example below.
`PLEXCEL_CONV_TIME1970M_X_TIME1601`	This `conv` value automatically converts between milliseconds since 1970 and nanoseconds since 1601 dates commonly used by AD. This conversion is also ideal for producing human readable dates and performing date logic.
`PLEXCEL_CONV_INT32_X_STRING`	This `conv` value automatically converts between an integer and a string.
`PLEXCEL_CONV_STRING_X_BINARY`	This `conv` value automatically converts between strings and binary.

Returns

The plexcel_set_attrdefs function returns TRUE if the attribute definitions were successfully added to the Plexcel context resource. Otherwise, FALSE is returned in which case plexcel_status should be consulted.

Example

The following PHP fragment illustrates how to set an attribute definition with the PLEXCEL_CONV_TIME1970M_X_TIMEUTC automatic type conversion and then print a human readable time using PHP's date function.

$attrdefs = array(
        'currentTime' => array(
            'type' => PLEXCEL_TYPE_TIME,
            'flags' => PLEXCEL_SINGLE_VALUED,
            'conv' => PLEXCEL_CONV_TIME1970M_X_TIMEUTC));

        if (plexcel_set_attrdefs($px, $attrdefs) == FALSE)
      
    die('<pre>' . plexcel_status($px) . '</pre>');

// call plexcel_search_objects to get currentTime from RootDSE

// This prints a date string like Mar 16, 2007 5:58:51 PM

echo 'currentTime:' . date('M j, Y g:i:s A', $rootdse['currentTime'] / 1000.0);

Pretty-printing the currentTime with help from a plexcel_set_attrdefs conversion.