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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect2 id="zend.validate.set.barcode">
   4     <title>Barcode</title>
   5
   6     <para>
   7         <classname>Zend_Validate_Barcode</classname> allows you to check if a given value can be
   8         represented as barcode.
   9     </para>
  10
  11     <para>
  12         <classname>Zend_Validate_Barcode</classname> supports multiple barcode standards and can be
  13         extended with proprietary barcode implementations very easily. The following barcode
  14         standards are supported:
  15     </para>
  16
  17     <itemizedlist>
  18         <listitem>
  19             <para>
  20                 <emphasis>CODE25</emphasis>: Often called "two of five" or "Code25 Industrial".
  21             </para>
  22
  23             <para>
  24                 This barcode has no length limitation. It supports only digits, and the last digit
  25                 can be an optional checksum which is calculated with modulo 10. This standard is
  26                 very old and nowadays not often used. Common usecases are within the industry.
  27             </para>
  28         </listitem>
  29
  30         <listitem>
  31             <para>
  32                 <emphasis>CODE25INTERLEAVED</emphasis>: Often called "Code 2 of 5 Interleaved".
  33             </para>
  34
  35             <para>
  36                 This standard is a variant of CODE25. It has no length limitation, but it must
  37                 contain an even amount of characters. It supports only digits, and the last digit
  38                 can be an optional checksum which is calculated with modulo 10. It is used worldwide
  39                 and common on the market.
  40             </para>
  41         </listitem>
  42
  43         <listitem>
  44             <para>
  45                 <emphasis>CODE39</emphasis>: CODE39 is one of the oldest available codes.
  46             </para>
  47
  48             <para>
  49                 This barcode has a variable length. It supports digits, upper cased alphabetical
  50                 characters and 7 special characters like whitespace, point and dollar sign. It can
  51                 have an optional checksum which is calculated with modulo 43. This standard is used
  52                 worldwide and common within the industry.
  53             </para>
  54         </listitem>
  55
  56         <listitem>
  57             <para>
  58                 <emphasis>CODE39EXT</emphasis>: CODE39EXT is an extension of CODE39.
  59             </para>
  60
  61             <para>
  62                 This barcode has the same properties as CODE39. Additionally it allows the usage of
  63                 all 128 ASCII characters. This standard is used worldwide and common within the
  64                 industry.
  65             </para>
  66         </listitem>
  67
  68         <listitem>
  69             <para>
  70                 <emphasis>CODE93</emphasis>: CODE93 is the successor of CODE39.
  71             </para>
  72
  73             <para>
  74                 This barcode has a variable length. It supports digits, alphabetical characters
  75                 and 7 special characters. It has an optional checksum which is calculated with
  76                 modulo 47 and contains 2 characters. This standard produces a denser code than
  77                 CODE39 and is more secure.
  78             </para>
  79         </listitem>
  80
  81         <listitem>
  82             <para>
  83                 <emphasis>CODE93EXT</emphasis>: CODE93EXT is an extension of CODE93.
  84             </para>
  85
  86             <para>
  87                 This barcode has the same properties as CODE93. Additionally it allows the usage of
  88                 all 128 ASCII characters. This standard is used worldwide and common within the
  89                 industry.
  90             </para>
  91         </listitem>
  92
  93         <listitem>
  94             <para>
  95                 <emphasis>EAN2</emphasis>: EAN is the shortcut for "European Article Number".
  96             </para>
  97
  98             <para>
  99                 These barcode must have 2 characters. It supports only digits and does not have a
 100                 checksum. This standard is mainly used as addition to EAN13 (ISBN) when printed on
 101                 books.
 102             </para>
 103         </listitem>
 104
 105         <listitem>
 106             <para>
 107                 <emphasis>EAN5</emphasis>: EAN is the shortcut for "European Article Number".
 108             </para>
 109
 110             <para>
 111                 These barcode must have 5 characters. It supports only digits and does not have a
 112                 checksum. This standard is mainly used as addition to EAN13 (ISBN) when printed on
 113                 books.
 114             </para>
 115         </listitem>
 116
 117         <listitem>
 118             <para>
 119                 <emphasis>EAN8</emphasis>: EAN is the shortcut for "European Article Number".
 120             </para>
 121
 122             <para>
 123                 These barcode can have 7 or 8 characters. It supports only digits. When it has a
 124                 length of 8 characters it includes a checksum. This standard is used worldwide but
 125                 has a very limited range. It can be found on small articles where a longer barcode
 126                 could not be printed.
 127             </para>
 128         </listitem>
 129
 130         <listitem>
 131             <para>
 132                 <emphasis>EAN12</emphasis>: EAN is the shortcut for "European Article Number".
 133             </para>
 134
 135             <para>
 136                 This barcode must have a length of 12 characters. It supports only digits, and the
 137                 last digit is always a checksum which is calculated with modulo 10. This standard is
 138                 used within the USA and common on the market. It has been superceded by EAN13.
 139             </para>
 140         </listitem>
 141
 142         <listitem>
 143             <para>
 144                 <emphasis>EAN13</emphasis>: EAN is the shortcut for "European Article Number".
 145             </para>
 146
 147             <para>
 148                 This barcode must have a length of 13 characters. It supports only digits, and the
 149                 last digit is always a checksum which is calculated with modulo 10. This standard is
 150                 used worldwide and common on the market.
 151             </para>
 152         </listitem>
 153
 154         <listitem>
 155             <para>
 156                 <emphasis>EAN14</emphasis>: EAN is the shortcut for "European Article Number".
 157             </para>
 158
 159             <para>
 160                 This barcode must have a length of 14 characters. It supports only digits, and the
 161                 last digit is always a checksum which is calculated with modulo 10. This standard is
 162                 used worldwide and common on the market. It is the successor for EAN13.
 163             </para>
 164         </listitem>
 165
 166         <listitem>
 167             <para>
 168                 <emphasis>EAN18</emphasis>: EAN is the shortcut for "European Article Number".
 169             </para>
 170
 171             <para>
 172                 This barcode must have a length of 18 characters. It support only digits. The last
 173                 digit is always a checksum digit which is calculated with modulo 10. This code is
 174                 often used for the identification of shipping containers.
 175             </para>
 176         </listitem>
 177
 178         <listitem>
 179             <para>
 180                 <emphasis>GTIN12</emphasis>: GTIN is the shortcut for "Global Trade Item Number".
 181             </para>
 182
 183             <para>
 184                 This barcode uses the same standard as EAN12 and is its successor. It's commonly
 185                 used within the USA.
 186             </para>
 187         </listitem>
 188
 189         <listitem>
 190             <para>
 191                 <emphasis>GTIN13</emphasis>: GTIN is the shortcut for "Global Trade Item Number".
 192             </para>
 193
 194             <para>
 195                 This barcode uses the same standard as EAN13 and is its successor. It is used
 196                 worldwide by industry.
 197             </para>
 198         </listitem>
 199
 200         <listitem>
 201             <para>
 202                 <emphasis>GTIN14</emphasis>: GTIN is the shortcut for "Global Trade Item Number".
 203             </para>
 204
 205             <para>
 206                 This barcode uses the same standard as EAN14 and is its successor. It is used
 207                 worldwide and common on the market.
 208             </para>
 209         </listitem>
 210
 211         <listitem>
 212             <para>
 213                 <emphasis>IDENTCODE</emphasis>: Identcode is used by Deutsche Post and DHL. It's an
 214                 specialized implementation of Code25.
 215             </para>
 216
 217             <para>
 218                 This barcode must have a length of 12 characters. It supports only digits, and the
 219                 last digit is always a checksum which is calculated with modulo 10. This standard is
 220                 mainly used by the companies DP and DHL.
 221             </para>
 222         </listitem>
 223
 224         <listitem>
 225             <para>
 226                 <emphasis>INTELLIGENTMAIL</emphasis>: Intelligent Mail is a postal barcode.
 227             </para>
 228
 229             <para>
 230                 This barcode can have a length of 20, 25, 29 or 31 characters. It supports only
 231                 digits, and contains no checksum. This standard is the successor of
 232                 <acronym>PLANET</acronym> and <acronym>POSTNET</acronym>. It is mainly used by the
 233                 United States Postal Services.
 234             </para>
 235         </listitem>
 236
 237         <listitem>
 238             <para>
 239                 <emphasis>ISSN</emphasis>: <acronym>ISSN</acronym> is the abbreviation for
 240                 International Standard Serial Number.
 241             </para>
 242
 243             <para>
 244                 This barcode can have a length of 8 or 13 characters. It supports only digits,
 245                 and the last digit must be a checksum digit which is calculated with modulo 11.
 246                 It is used worldwide for printed publications.
 247             </para>
 248         </listitem>
 249
 250         <listitem>
 251             <para>
 252                 <emphasis>ITF14</emphasis>: ITF14 is the GS1 implementation of an Interleaved Two
 253                 of Five bar code.
 254             </para>
 255
 256             <para>
 257                 This barcode is a special variant of Interleaved 2 of 5. It must have a length of
 258                 14 characters and is based on GTIN14. It supports only digits, and the last digit
 259                 must be a checksum digit which is calculated with modulo 10. It is used worldwide
 260                 and common within the market.
 261             </para>
 262         </listitem>
 263
 264         <listitem>
 265             <para>
 266                 <emphasis>LEITCODE</emphasis>: Leitcode is used by Deutsche Post and DHL. It's an
 267                 specialized implementation of Code25.
 268             </para>
 269
 270             <para>
 271                 This barcode must have a length of 14 characters. It supports only digits, and the
 272                 last digit is always a checksum which is calculated with modulo 10. This standard is
 273                 mainly used by the companies DP and DHL.
 274             </para>
 275         </listitem>
 276
 277         <listitem>
 278             <para>
 279                 <emphasis>PLANET</emphasis>: Planet is the abbreviation for Postal Alpha Numeric
 280                 Encoding Technique.
 281             </para>
 282
 283             <para>
 284                 This barcode can have a length of 12 or 14 characters. It supports only digits, and
 285                 the last digit is always a checksum. This standard is mainly used by the United
 286                 States Postal Services.
 287             </para>
 288         </listitem>
 289
 290         <listitem>
 291             <para>
 292                 <emphasis>POSTNET</emphasis>: Postnet is used by the US Postal Service.
 293             </para>
 294
 295             <para>
 296                 This barcode can have a length of 6, 7, 10 or 12 characters. It supports only
 297                 digits, and the last digit is always a checksum. This standard is mainly used
 298                 by the United States Postal Services.
 299             </para>
 300         </listitem>
 301
 302         <listitem>
 303             <para>
 304                 <emphasis>ROYALMAIL</emphasis>: Royalmail is used by Royal Mail.
 305             </para>
 306
 307             <para>
 308                 This barcode has no defined length. It supports digits, uppercased letters, and the
 309                 last digit is always a checksum. This standard is mainly used by Royal Mail for
 310                 their Cleanmail Service. It is also called <acronym>RM4SCC</acronym>.
 311             </para>
 312         </listitem>
 313
 314         <listitem>
 315             <para>
 316                 <emphasis>SSCC</emphasis>: SSCC is the shortcut for "Serial Shipping Container
 317                 Code".
 318             </para>
 319
 320             <para>
 321                 This barcode is a variant of EAN barcode. It must have a length of 18 characters and
 322                 supports only digits. The last digit must be a checksum digit which is calculated
 323                 with modulo 10. It is commonly used by the transport industry.
 324             </para>
 325         </listitem>
 326
 327         <listitem>
 328             <para>
 329                 <emphasis>UPCA</emphasis>: UPC is the shortcut for "Univeral Product Code".
 330             </para>
 331
 332             <para>
 333                 This barcode preceeded EAN13. It must have a length of 12 characters and supports
 334                 only digits. The last digit must be a checksum digit which is calculated with
 335                 modulo 10. It is commonly used within the USA.
 336             </para>
 337         </listitem>
 338
 339         <listitem>
 340             <para>
 341                 <emphasis>UPCE</emphasis>: UPCE is the short variant from UPCA.
 342             </para>
 343
 344             <para>
 345                 This barcode is a smaller variant of UPCA. It can have a length of 6, 7 or 8
 346                 characters and supports only digits. When the barcode is 8 chars long it includes
 347                 a checksum which is calculated with modulo 10. It is commonly used with small
 348                 products where a UPCA barcode would not fit.
 349             </para>
 350         </listitem>
 351     </itemizedlist>
 352
 353     <sect3 id="zend.validate.set.barcode.options">
 354         <title>Supported options for Zend_Validate_Barcode</title>
 355
 356         <para>
 357             The following options are supported for <classname>Zend_Validate_Barcode</classname>:
 358         </para>
 359
 360         <itemizedlist>
 361             <listitem>
 362                 <para>
 363                     <emphasis><property>adapter</property></emphasis>: Sets the barcode adapter
 364                     which will be used. Supported are all above noted adapters. When using a self
 365                     defined adapter, then you have to set the complete classname.
 366                 </para>
 367             </listitem>
 368
 369             <listitem>
 370                 <para>
 371                     <emphasis><property>checksum</property></emphasis>: <constant>TRUE</constant>
 372                     when the barcode should contain a checksum. The default value depends on the
 373                     used adapter. Note that some adapters don't allow to set this option.
 374                 </para>
 375             </listitem>
 376
 377             <listitem>
 378                 <para>
 379                     <emphasis><property>options</property></emphasis>: Defines optional options for
 380                     a self written adapters.
 381                 </para>
 382             </listitem>
 383         </itemizedlist>
 384     </sect3>
 385
 386     <sect3 id="zend.validate.set.barcode.basic">
 387         <title>Basic usage</title>
 388
 389         <para>
 390             To validate if a given string is a barcode you just need to know its type. See the
 391             following example for an EAN13 barcode:
 392         </para>
 393
 394         <programlisting language="php"><![CDATA[
 395 $valid = new Zend_Validate_Barcode('EAN13');
 396 if ($valid->isValid($input)) {
 397     // input appears to be valid
 398 } else {
 399     // input is invalid
 400 }
 401 ]]></programlisting>
 402     </sect3>
 403
 404     <sect3 id="zend.validate.set.barcode.checksum">
 405         <title>Optional checksum</title>
 406
 407         <para>
 408             Some barcodes can be provided with an optional checksum. These barcodes would be valid
 409             even without checksum. Still, when you provide a checksum, then you should also validate
 410             it. By default, these barcode types perform no checksum validation. By using the
 411             <property>checksum</property> option you can define if the checksum will be validated or
 412             ignored.
 413         </para>
 414
 415         <programlisting language="php"><![CDATA[
 416 $valid = new Zend_Validate_Barcode(array(
 417     'adapter'  => 'EAN13',
 418     'checksum' => false,
 419 ));
 420 if ($valid->isValid($input)) {
 421     // input appears to be valid
 422 } else {
 423     // input is invalid
 424 }
 425 ]]></programlisting>
 426
 427         <note>
 428             <title>Reduced security by disabling checksum validation</title>
 429
 430             <para>
 431                  By switching off checksum validation you will also reduce the security of the used
 432                  barcodes. Additionally you should note that you can also turn off the checksum
 433                  validation for those barcode types which must contain a checksum value. Barcodes
 434                  which would not be valid could then be returned as valid even if they are not.
 435             </para>
 436         </note>
 437     </sect3>
 438
 439     <sect3 id="zend.validate.set.barcode.custom">
 440         <title>Writing custom adapters</title>
 441
 442         <para>
 443             You may write custom barcode validators for usage with
 444             <classname>Zend_Validate_Barcode</classname>; this is often necessary when dealing with
 445             proprietary barcode types. To write your own barcode validator, you need the following
 446             information.
 447         </para>
 448
 449         <itemizedlist>
 450             <listitem>
 451                 <para>
 452                     <emphasis>Length</emphasis>: The length your barcode must have. It can have one
 453                     of the following values:
 454                 </para>
 455
 456                 <itemizedlist>
 457                     <listitem>
 458                         <para>
 459                             <emphasis>Integer</emphasis>: A value greater 0, which means that the
 460                             barcode must have this length.
 461                         </para>
 462                     </listitem>
 463
 464                     <listitem>
 465                         <para>
 466                             <emphasis>-1</emphasis>: There is no limitation for the length of this
 467                             barcode.
 468                         </para>
 469                     </listitem>
 470
 471                     <listitem>
 472                         <para>
 473                             <emphasis>"even"</emphasis>: The length of this barcode must have a
 474                             even amount of digits.
 475                         </para>
 476                     </listitem>
 477
 478                     <listitem>
 479                         <para>
 480                             <emphasis>"odd"</emphasis>: The length of this barcode must have a
 481                             odd amount of digits.
 482                         </para>
 483                     </listitem>
 484
 485                     <listitem>
 486                         <para>
 487                             <emphasis>array</emphasis>: An array of integer values. The length of
 488                             this barcode must have one of the set array values.
 489                         </para>
 490                     </listitem>
 491                 </itemizedlist>
 492             </listitem>
 493
 494             <listitem>
 495                 <para>
 496                     <emphasis>Characters</emphasis>: A string which contains all allowed characters
 497                     for this barcode. Also the integer value 128 is allowed, which means the first
 498                     128 characters of the ASCII table.
 499                 </para>
 500             </listitem>
 501
 502             <listitem>
 503                 <para>
 504                     <emphasis>Checksum</emphasis>: A string which will be used as callback for a
 505                     method which does the checksum validation.
 506                 </para>
 507             </listitem>
 508         </itemizedlist>
 509
 510         <para>
 511             Your custom barcode validator must extend
 512             <classname>Zend_Validate_Barcode_AdapterAbstract</classname> or implement
 513             <interface>Zend_Validate_Barcode_AdapterInterface</interface>.
 514         </para>
 515
 516         <para>
 517             As an example, let's create a validator that expects an even number of characters that
 518             include all digits and the letters 'ABCDE', and which requires a checksum.
 519         </para>
 520
 521         <programlisting language="php"><![CDATA[
 522 class My_Barcode_MyBar extends Zend_Validate_Barcode_AdapterAbstract
 523 {
 524     protected $_length     = 'even';
 525     protected $_characters = '0123456789ABCDE';
 526     protected $_checksum   = '_mod66';
 527
 528     protected function _mod66($barcode)
 529     {
 530         // do some validations and return a boolean
 531     }
 532 }
 533
 534 $valid = new Zend_Validate_Barcode('My_Barcode_MyBar');
 535 if ($valid->isValid($input)) {
 536     // input appears to be valid
 537 } else {
 538     // input is invalid
 539 }
 540 ]]></programlisting>
 541     </sect3>
 542 </sect2>
 543 <!--
 544 vim:se ts=4 sw=4 et:
 545 -->