repo_zf1Php7/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>