repo_zf1/documentation/manual/en/module_specs/Zend_Validate-Barcode.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect2 id="zend.validate.set.barcode">
    <title>Barcode</title>

    <para>
        <classname>Zend_Validate_Barcode</classname> allows you to check if a given value can be
        represented as barcode.
    </para>

    <para>
        <classname>Zend_Validate_Barcode</classname> supports multiple barcode standards and can be
        extended with proprietary barcode implementations very easily. The following barcode
        standards are supported:
    </para>

    <itemizedlist>
        <listitem>
            <para>
                <emphasis>CODE25</emphasis>: Often called "two of five" or "Code25 Industrial".
            </para>

            <para>
                This barcode has no length limitation. It supports only digits, and the last digit
                can be an optional checksum which is calculated with modulo 10. This standard is
                very old and nowadays not often used. Common usecases are within the industry.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>CODE25INTERLEAVED</emphasis>: Often called "Code 2 of 5 Interleaved".
            </para>

            <para>
                This standard is a variant of CODE25. It has no length limitation, but it must
                contain an even amount of characters. It supports only digits, and the last digit
                can be an optional checksum which is calculated with modulo 10. It is used worldwide
                and common on the market.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>CODE39</emphasis>: CODE39 is one of the oldest available codes.
            </para>

            <para>
                This barcode has a variable length. It supports digits, upper cased alphabetical
                characters and 7 special characters like whitespace, point and dollar sign. It can
                have an optional checksum which is calculated with modulo 43. This standard is used
                worldwide and common within the industry.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>CODE39EXT</emphasis>: CODE39EXT is an extension of CODE39.
            </para>

            <para>
                This barcode has the same properties as CODE39. Additionally it allows the usage of
                all 128 ASCII characters. This standard is used worldwide and common within the
                industry.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>CODE93</emphasis>: CODE93 is the successor of CODE39.
            </para>

            <para>
                This barcode has a variable length. It supports digits, alphabetical characters
                and 7 special characters. It has an optional checksum which is calculated with
                modulo 47 and contains 2 characters. This standard produces a denser code than
                CODE39 and is more secure.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>CODE93EXT</emphasis>: CODE93EXT is an extension of CODE93.
            </para>

            <para>
                This barcode has the same properties as CODE93. Additionally it allows the usage of
                all 128 ASCII characters. This standard is used worldwide and common within the
                industry.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>EAN2</emphasis>: EAN is the shortcut for "European Article Number".
            </para>

            <para>
                These barcode must have 2 characters. It supports only digits and does not have a
                checksum. This standard is mainly used as addition to EAN13 (ISBN) when printed on
                books.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>EAN5</emphasis>: EAN is the shortcut for "European Article Number".
            </para>

            <para>
                These barcode must have 5 characters. It supports only digits and does not have a
                checksum. This standard is mainly used as addition to EAN13 (ISBN) when printed on
                books.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>EAN8</emphasis>: EAN is the shortcut for "European Article Number".
            </para>

            <para>
                These barcode can have 7 or 8 characters. It supports only digits. When it has a
                length of 8 characters it includes a checksum. This standard is used worldwide but
                has a very limited range. It can be found on small articles where a longer barcode
                could not be printed.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>EAN12</emphasis>: EAN is the shortcut for "European Article Number".
            </para>

            <para>
                This barcode must have a length of 12 characters. It supports only digits, and the
                last digit is always a checksum which is calculated with modulo 10. This standard is
                used within the USA and common on the market. It has been superceded by EAN13.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>EAN13</emphasis>: EAN is the shortcut for "European Article Number".
            </para>

            <para>
                This barcode must have a length of 13 characters. It supports only digits, and the
                last digit is always a checksum which is calculated with modulo 10. This standard is
                used worldwide and common on the market.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>EAN14</emphasis>: EAN is the shortcut for "European Article Number".
            </para>

            <para>
                This barcode must have a length of 14 characters. It supports only digits, and the
                last digit is always a checksum which is calculated with modulo 10. This standard is
                used worldwide and common on the market. It is the successor for EAN13.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>EAN18</emphasis>: EAN is the shortcut for "European Article Number".
            </para>

            <para>
                This barcode must have a length of 18 characters. It support only digits. The last
                digit is always a checksum digit which is calculated with modulo 10. This code is
                often used for the identification of shipping containers.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>GTIN12</emphasis>: GTIN is the shortcut for "Global Trade Item Number".
            </para>

            <para>
                This barcode uses the same standard as EAN12 and is its successor. It's commonly
                used within the USA.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>GTIN13</emphasis>: GTIN is the shortcut for "Global Trade Item Number".
            </para>

            <para>
                This barcode uses the same standard as EAN13 and is its successor. It is used
                worldwide by industry.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>GTIN14</emphasis>: GTIN is the shortcut for "Global Trade Item Number".
            </para>

            <para>
                This barcode uses the same standard as EAN14 and is its successor. It is used
                worldwide and common on the market.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>IDENTCODE</emphasis>: Identcode is used by Deutsche Post and DHL. It's an
                specialized implementation of Code25.
            </para>

            <para>
                This barcode must have a length of 12 characters. It supports only digits, and the
                last digit is always a checksum which is calculated with modulo 10. This standard is
                mainly used by the companies DP and DHL.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>INTELLIGENTMAIL</emphasis>: Intelligent Mail is a postal barcode.
            </para>

            <para>
                This barcode can have a length of 20, 25, 29 or 31 characters. It supports only
                digits, and contains no checksum. This standard is the successor of
                <acronym>PLANET</acronym> and <acronym>POSTNET</acronym>. It is mainly used by the
                United States Postal Services.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>ISSN</emphasis>: <acronym>ISSN</acronym> is the abbreviation for
                International Standard Serial Number.
            </para>

            <para>
                This barcode can have a length of 8 or 13 characters. It supports only digits,
                and the last digit must be a checksum digit which is calculated with modulo 11.
                It is used worldwide for printed publications.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>ITF14</emphasis>: ITF14 is the GS1 implementation of an Interleaved Two
                of Five bar code.
            </para>

            <para>
                This barcode is a special variant of Interleaved 2 of 5. It must have a length of
                14 characters and is based on GTIN14. It supports only digits, and the last digit
                must be a checksum digit which is calculated with modulo 10. It is used worldwide
                and common within the market.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>LEITCODE</emphasis>: Leitcode is used by Deutsche Post and DHL. It's an
                specialized implementation of Code25.
            </para>

            <para>
                This barcode must have a length of 14 characters. It supports only digits, and the
                last digit is always a checksum which is calculated with modulo 10. This standard is
                mainly used by the companies DP and DHL.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>PLANET</emphasis>: Planet is the abbreviation for Postal Alpha Numeric
                Encoding Technique.
            </para>

            <para>
                This barcode can have a length of 12 or 14 characters. It supports only digits, and
                the last digit is always a checksum. This standard is mainly used by the United
                States Postal Services.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>POSTNET</emphasis>: Postnet is used by the US Postal Service.
            </para>

            <para>
                This barcode can have a length of 6, 7, 10 or 12 characters. It supports only
                digits, and the last digit is always a checksum. This standard is mainly used
                by the United States Postal Services.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>ROYALMAIL</emphasis>: Royalmail is used by Royal Mail.
            </para>

            <para>
                This barcode has no defined length. It supports digits, uppercased letters, and the
                last digit is always a checksum. This standard is mainly used by Royal Mail for
                their Cleanmail Service. It is also called <acronym>RM4SCC</acronym>.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>SSCC</emphasis>: SSCC is the shortcut for "Serial Shipping Container
                Code".
            </para>

            <para>
                This barcode is a variant of EAN barcode. It must have a length of 18 characters and
                supports only digits. The last digit must be a checksum digit which is calculated
                with modulo 10. It is commonly used by the transport industry.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>UPCA</emphasis>: UPC is the shortcut for "Univeral Product Code".
            </para>

            <para>
                This barcode preceeded EAN13. It must have a length of 12 characters and supports
                only digits. The last digit must be a checksum digit which is calculated with
                modulo 10. It is commonly used within the USA.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>UPCE</emphasis>: UPCE is the short variant from UPCA.
            </para>

            <para>
                This barcode is a smaller variant of UPCA. It can have a length of 6, 7 or 8
                characters and supports only digits. When the barcode is 8 chars long it includes
                a checksum which is calculated with modulo 10. It is commonly used with small
                products where a UPCA barcode would not fit.
            </para>
        </listitem>
    </itemizedlist>

    <sect3 id="zend.validate.set.barcode.options">
        <title>Supported options for Zend_Validate_Barcode</title>

        <para>
            The following options are supported for <classname>Zend_Validate_Barcode</classname>:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis><property>adapter</property></emphasis>: Sets the barcode adapter
                    which will be used. Supported are all above noted adapters. When using a self
                    defined adapter, then you have to set the complete classname.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>checksum</property></emphasis>: <constant>TRUE</constant>
                    when the barcode should contain a checksum. The default value depends on the
                    used adapter. Note that some adapters don't allow to set this option.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>options</property></emphasis>: Defines optional options for
                    a self written adapters.
                </para>
            </listitem>
        </itemizedlist>
    </sect3>

    <sect3 id="zend.validate.set.barcode.basic">
        <title>Basic usage</title>

        <para>
            To validate if a given string is a barcode you just need to know its type. See the
            following example for an EAN13 barcode:
        </para>

        <programlisting language="php"><![CDATA[
$valid = new Zend_Validate_Barcode('EAN13');
if ($valid->isValid($input)) {
    // input appears to be valid
} else {
    // input is invalid
}
]]></programlisting>
    </sect3>

    <sect3 id="zend.validate.set.barcode.checksum">
        <title>Optional checksum</title>

        <para>
            Some barcodes can be provided with an optional checksum. These barcodes would be valid
            even without checksum. Still, when you provide a checksum, then you should also validate
            it. By default, these barcode types perform no checksum validation. By using the
            <property>checksum</property> option you can define if the checksum will be validated or
            ignored.
        </para>

        <programlisting language="php"><![CDATA[
$valid = new Zend_Validate_Barcode(array(
    'adapter'  => 'EAN13',
    'checksum' => false,
));
if ($valid->isValid($input)) {
    // input appears to be valid
} else {
    // input is invalid
}
]]></programlisting>

        <note>
            <title>Reduced security by disabling checksum validation</title>

            <para>
                 By switching off checksum validation you will also reduce the security of the used
                 barcodes. Additionally you should note that you can also turn off the checksum
                 validation for those barcode types which must contain a checksum value. Barcodes
                 which would not be valid could then be returned as valid even if they are not.
            </para>
        </note>
    </sect3>

    <sect3 id="zend.validate.set.barcode.custom">
        <title>Writing custom adapters</title>

        <para>
            You may write custom barcode validators for usage with
            <classname>Zend_Validate_Barcode</classname>; this is often necessary when dealing with
            proprietary barcode types. To write your own barcode validator, you need the following
            information.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>Length</emphasis>: The length your barcode must have. It can have one
                    of the following values:
                </para>

                <itemizedlist>
                    <listitem>
                        <para>
                            <emphasis>Integer</emphasis>: A value greater 0, which means that the
                            barcode must have this length.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <emphasis>-1</emphasis>: There is no limitation for the length of this
                            barcode.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <emphasis>"even"</emphasis>: The length of this barcode must have a
                            even amount of digits.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <emphasis>"odd"</emphasis>: The length of this barcode must have a
                            odd amount of digits.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <emphasis>array</emphasis>: An array of integer values. The length of
                            this barcode must have one of the set array values.
                        </para>
                    </listitem>
                </itemizedlist>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Characters</emphasis>: A string which contains all allowed characters
                    for this barcode. Also the integer value 128 is allowed, which means the first
                    128 characters of the ASCII table.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Checksum</emphasis>: A string which will be used as callback for a
                    method which does the checksum validation.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Your custom barcode validator must extend
            <classname>Zend_Validate_Barcode_AdapterAbstract</classname> or implement
            <interface>Zend_Validate_Barcode_AdapterInterface</interface>.
        </para>

        <para>
            As an example, let's create a validator that expects an even number of characters that
            include all digits and the letters 'ABCDE', and which requires a checksum.
        </para>

        <programlisting language="php"><![CDATA[
class My_Barcode_MyBar extends Zend_Validate_Barcode_AdapterAbstract
{
    protected $_length     = 'even';
    protected $_characters = '0123456789ABCDE';
    protected $_checksum   = '_mod66';

    protected function _mod66($barcode)
    {
        // do some validations and return a boolean
    }
}

$valid = new Zend_Validate_Barcode('My_Barcode_MyBar');
if ($valid->isValid($input)) {
    // input appears to be valid
} else {
    // input is invalid
}
]]></programlisting>
    </sect3>
</sect2>
<!--
vim:se ts=4 sw=4 et:
-->