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>
        Therefor <classname>Zend_Validate_Barcode</classname> supports multiple barcode standards
        and can be extended with proprietary barcode implementations very easily. Actually the
        following barcode standards are supported:
    </para>

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

            <para>
                This barcode has a variable length. It supports digits, alphabetical characters
                and 6 special characters. 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>EAN8</emphasis>: EAN is the shortcut for "European Article Number".
            </para>

            <para>
                These barcodes must have a length of 8 characters. It supports only digits and
                the last digit is always a checksum. This standard is used worldwide but has avery
                limited range. It can be found on small atricles where a longer barcode could not
                be printed on.
            </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 USA and common on the market. It has been superseeded 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>GTIN12</emphasis>: GTIN is the shortcut for "Global Trade Item Number".
            </para>

            <para>
                This barcode uses the same standard as Ean12 and is it's successor. It's commonly
                used within 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 it's successor. It's 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 it's successor. It is used
                worldwide and common on the market.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>INTERLEAVED25</emphasis>: Often called Interleaved two of five.
            </para>

            <para>
                This barcode 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. This standard is used worldwide and common on
                the market.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>ITF14</emphasis>: ITF is the shortcut for "Interleaved Two of Five".
            </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>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 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 USA.
            </para>
        </listitem>
    </itemizedlist>

    <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 it's 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. These barcode types do per default 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('adapter' => 'EAN13', 'checksum' => true);
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 these 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.selfwritten">
        <title>Self written adapters</title>

        <para>
            Of course it's possible to write barcode validators yourself. This could be
            necessary as many barcode types are properitary. To write your own barcode
            validator you need some informations.
        </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>
            Additionally your own barcode validator must extend
            <classname>BarcodeAdapter</classname>.
        </para>

        <para>
            Now let's concat all options together and write a own barcode validator. Let's expect
            that our barcode must be even, it can have all digits and additionally the chars
            'ABCDE', and it has a checksum.
        </para>

        <programlisting language="php"><![CDATA[
class My_Barcode_MyBar extends Zend_Validate_Barcode_BarcodeAdapter
{
    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:
-->