repo_zf1/documentation/manual/en/module_specs/Zend_Ldap-API-Ldap-Attribute.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect3 id="zend.ldap.api.reference.zend-ldap-attribute">
    <title>Zend_Ldap_Attribute</title>

    <para>
        <classname>Zend_Ldap_Attribute</classname> is a helper class providing only static
        methods to manipulate arrays suitable to the structure used in
        <classname>Zend_Ldap</classname> data modification methods and to the data format required by
        the <acronym>LDAP</acronym> server. <acronym>PHP</acronym> data types are converted the following way:
    </para>

    <variablelist>
        <varlistentry>
            <term><code>string</code></term>
            <listitem><para>No conversion will be done.</para></listitem>
        </varlistentry>

        <varlistentry>
            <term><code>integer</code> and <code>float</code></term>
            <listitem><para>The value will be converted to a string.</para></listitem>
        </varlistentry>

        <varlistentry>
            <term><code>boolean</code></term>
            <listitem><para><constant>TRUE</constant> will be converted to <emphasis>'<constant>TRUE</constant>'</emphasis> and
            <constant>FALSE</constant> to <emphasis>'<constant>FALSE</constant>'</emphasis></para></listitem>
        </varlistentry>

        <varlistentry>
            <term><code>object</code> and <code>array</code></term>
            <listitem><para>The value will be converted to a string by using
            <methodname>serialize()</methodname>.</para></listitem>
        </varlistentry>

        <varlistentry>
            <term><code>resource</code></term>
            <listitem><para>If a <code>stream</code> resource is given, the data will be
            fetched by calling <methodname>stream_get_contents()</methodname>.</para></listitem>
        </varlistentry>

        <varlistentry>
            <term>others</term>
            <listitem><para>All other data types (namely non-stream resources) will be
            ommitted.</para></listitem>
        </varlistentry>

    </variablelist>

    <para>On reading attribute values the following conversion will take place:</para>

    <variablelist>
        <varlistentry>
            <term><emphasis>'<constant>TRUE</constant>'</emphasis></term>
            <listitem><para>Converted to <constant>TRUE</constant>.</para></listitem>
        </varlistentry>

        <varlistentry>
            <term><emphasis>'<constant>FALSE</constant>'</emphasis></term>
            <listitem><para>Converted to <constant>FALSE</constant>.</para></listitem>
        </varlistentry>

        <varlistentry>
            <term>others</term>
            <listitem><para>All other strings won't be automatically converted and are passed
            as they are.</para></listitem>
        </varlistentry>

    </variablelist>

    <table id="zend.ldap.api.reference.zend-ldap-attribute.table">
        <title>Zend_Ldap_Attribute API</title>

        <tgroup cols="2">
            <thead>
                <row>
                    <entry>Method</entry>
                    <entry>Description</entry>
                </row>
            </thead>
            <tbody>
                <row>
                    <entry>
                        <emphasis><code>void setAttribute(array &amp;$data, string
                        $attribName, mixed $value, boolean $append)</code>
                        </emphasis>
                    </entry>
                    <entry>
                        Sets the attribute <varname>$attribName</varname> in
                        <varname>$data</varname> to the value <varname>$value</varname>. If
                        <varname>$append</varname> is <constant>TRUE</constant> (<constant>FALSE</constant> by
                        default) <varname>$value</varname> will be appended to the attribute.
                        <varname>$value</varname> can be a scalar value or an array of scalar
                        values. Conversion will take place.
                    </entry>
                </row>
                <row>
                    <entry>
                        <emphasis><code>array|mixed getAttribute(array $data,
                        string $attribName, integer|null $index)</code> </emphasis>
                    </entry>
                    <entry>
                        Returns the attribute <varname>$attribName</varname> from
                        <varname>$data</varname>. If <varname>$index</varname> is <constant>NULL</constant>
                        (default) an array will be returned containing all the values for
                        the given attribute. An empty array will be returned if the
                        attribute does not exist in the given array. If an integer index is
                        specified the corresponding value at the given index will be
                        returned. If the index is out of bounds, <constant>NULL</constant> will be
                        returned. Conversion will take place.
                    </entry>
                </row>
                <row>
                    <entry>
                        <emphasis><code>boolean attributeHasValue(array &amp;$data,
                        string $attribName, mixed|array $value)</code> </emphasis>
                    </entry>
                    <entry>
                        Checks if the attribute <varname>$attribName</varname> in
                        <varname>$data</varname> has the value(s) given in <varname>$value</varname>.
                        The method returns <constant>TRUE</constant> only if all values in
                        <varname>$value</varname> are present in the attribute. Comparison is
                        done strictly (respecting the data type).
                    </entry>
                </row>
                <row>
                    <entry>
                        <emphasis><code>void removeDuplicatesFromAttribute(array
                        &amp;$data, string $attribName)</code> </emphasis>
                    </entry>
                    <entry>
                        Removes all duplicates from the attribute
                        <varname>$attribName</varname> in <varname>$data</varname>.
                    </entry>
                </row>
                <row>
                    <entry>
                        <emphasis><code>void removeFromAttribute(array &amp;$data,
                        string $attribName, mixed|array $value)</code> </emphasis>
                    </entry>
                    <entry>
                        Removes the value(s) given in <varname>$value</varname> from
                        the attribute <varname>$attribName</varname> in
                        <varname>$data</varname>.
                    </entry>
                </row>
                <row>
                    <entry>
                        <emphasis><code>string|null convertToLdapValue(mixed
                        $value)</code> </emphasis>
                    </entry>
                    <entry>
                        Converts a <acronym>PHP</acronym> data type into its <acronym>LDAP</acronym> representation. See
                        introduction for details.
                    </entry>
                </row>
                <row>
                    <entry>
                        <emphasis><code>mixed convertFromLdapValue(string
                        $value)</code> </emphasis>
                    </entry>
                    <entry>
                        Converts an <acronym>LDAP</acronym> value into its <acronym>PHP</acronym> data type. See
                        introduction for details.
                    </entry>
                </row>
                <row>
                    <entry>
                        <emphasis><code>string|null
                        convertToLdapDateTimeValue(integer $value, boolean $utc)</code>
                        </emphasis>
                    </entry>
                    <entry>
                        Converts a timestamp into its <acronym>LDAP</acronym> date/time representation.
                        If <varname>$utc</varname> is <constant>TRUE</constant> (<constant>FALSE</constant> by
                        default) the resulting <acronym>LDAP</acronym> date/time string will be in <acronym>UTC</acronym>,
                        otherwise a local date/time string will be returned.
                    </entry>
                </row>
                <row>
                    <entry>
                        <emphasis><code>integer|null
                        convertFromLdapDateTimeValue(string $value)</code>
                        </emphasis>
                    </entry>
                    <entry>
                        Converts <acronym>LDAP</acronym> date/time representation into a timestamp. The
                        method returns <constant>NULL</constant> if <varname>$value</varname> can not be
                        converted back into a <acronym>PHP</acronym> timestamp.
                    </entry>
                </row>
                <row>
                    <entry>
                        <emphasis><code>void setPassword(array &amp;$data, string
                        $password, string $hashType, string $attribName)</code>
                        </emphasis>
                    </entry>
                    <entry>
                        Sets a <acronym>LDAP</acronym> password for the attribute
                        <varname>$attribName</varname> in <varname>$data</varname>.
                        <varname>$attribName</varname> defaults to <code>'userPassword'</code>
                        which is the standard password attribute. The password hash can be
                        specified with <varname>$hashType</varname>. The default value here is
                        <constant>Zend_Ldap_Attribute::PASSWORD_HASH_MD5</constant> with
                        <constant>Zend_Ldap_Attribute::PASSWORD_HASH_SHA</constant> as the other
                        possibilty.
                    </entry>
                </row>
                <row>
                    <entry>
                        <emphasis><code>string createPassword(string $password,
                        string $hashType)</code> </emphasis>
                    </entry>
                    <entry>
                        Creates a <acronym>LDAP</acronym> password. The password hash can be specified
                        with <varname>$hashType</varname>. The default value here is
                        <constant>Zend_Ldap_Attribute::PASSWORD_HASH_MD5</constant> with
                        <constant>Zend_Ldap_Attribute::PASSWORD_HASH_SHA</constant> as the other
                        possibilty.
                    </entry>
                </row>
                <row>
                    <entry>
                        <emphasis><code>void setDateTimeAttribute(array &amp;$data,
                        string $attribName, integer|array $value, boolean $utc, boolean
                        $append)</code> </emphasis>
                    </entry>
                    <entry>
                        Sets the attribute <varname>$attribName</varname> in
                        <varname>$data</varname> to the date/time value <varname>$value</varname>. If
                        <varname>$append</varname> is <constant>TRUE</constant> (<constant>FALSE</constant> by
                        default) <varname>$value</varname> will be appended to the attribute.
                        <varname>$value</varname> can be an integer value or an array of
                        integers. Date-time-conversion according to
                        <methodname>Zend_Ldap_Attribute::convertToLdapDateTimeValue()</methodname> will
                        take place.
                    </entry>
                </row>
                <row>
                    <entry>
                        <emphasis><code>array|integer getDateTimeAttribute(array
                        $data, string $attribName, integer|null $index)</code>
                        </emphasis>
                    </entry>
                    <entry>
                        Returns the date/time attribute <varname>$attribName</varname>
                        from <varname>$data</varname>. If <varname>$index</varname> is
                        <constant>NULL</constant> (default) an array will be returned containing
                        all the date/time values for the given attribute. An empty array
                        will be returned if the attribute does not exist in the given
                        array. If an integer index is specified the corresponding date/time
                        value at the given index will be returned. If the index is out of
                        bounds, <constant>NULL</constant> will be returned. Date-time-conversion
                        according to
                        <methodname>Zend_Ldap_Attribute::convertFromLdapDateTimeValue()</methodname>
                        will take place.
                    </entry>
                </row>
            </tbody>
        </tgroup>
    </table>
</sect3>