Overview

RDataMatrix for PHP is a software package that allows you to create DataMatrix symbols.

Data Matrix is a two-dimensional (2D) matrix symbology which is made up of square modules arranged within a perimeter finder pattern. It can encode up to 3116 characters from the entire 256 byte ASCII character set. The symbol consists of data regions which contain square modules set out in a regular array. Large ECC 200 symbols contain several regions. Each data region is delimited by a finder pattern, and this is surrounded on all four sides by a quiet zone border (margin).

ECC 200 symbols have an even number of rows and an even number of columns. Most of the symbols are square with sizes from 10 x 10 to 144 x 144. Some symbols however are rectangular with sizes from 8 x 18 to 16 x 48. All ECC 200 symbols can be recognized by the upper right corner module being light (binary 0).

ECC200 is the newest version of data matrix and supports advanced encoding error checking and correction algorithms (reed-solomon). This algorithms allow the recognition of barcodes that are up to 60% damaged.

The barcode supports two optional mechanisms:

* The "Extended Channel Interpretation" (ECI) mechanism enables characters from other character sets (e.g. Arabic, Cyrillic ..) and other data interpretations or industry-specific requirements to be represented.
* The "Structured append" allows files of data to be represented as a secuence of up to 16 Data Matrix symbols. The original data or file can be reconstructed regardless of the order of the symbols.

RDataMatrix supports:

• All sizes and formats (from 10x10 till 144x144)
• Ascii, text , C40 and Base256 (for binary data) encoding.
• The "Extended Channel Interpretation and Structured append
  

Some of its main features are:

• You have control over many relevant paramenters in order to customize the resulting bar code image to your particular needs :
• You can specify the module size and the quite zone.
• You can specify the background color, and the color of the bars.
• You can rotate the image 90,180 or 270 degrees.
• The resulting image can be sent directly to the browser or to a file, in several formats (PNG, JPEG, GIF, WBMP).
• Developed using object oriented programing techniques, you can easily modify the source code to adapt your application needs or to add a new bar code type. (Of course you can count on us to do it, in most cases that will be more cost-effective for you).

Requirements

• A working PHP4 or PHP5 system
• GD library. It’s usually bundled into PHP.
• Support for specific image formats such as GIF or JPEG if you want to use them. Default is PNG. In recent PHP versions you will likely have at least PNG and JPEG.

Installation

Create a working directory for the application. It should be OUTSIDE the web server tree (this is, the web server should not access it). We will call it "the application directory".

Uncompress the provided distribution file into the application directory.

Create another working directory INSIDE the web server tree, and configure your web server to process PHP files in it. This is, make sure you can acces this directory using an appropriate URL from your browser, make sure that files with .php extension are parsed through the PHP interpreter, etc. We will call it "the web directory".

Copy the demo.php file from the application directory to the web directory.

Edit the demo.php in the web directory and update the include_path setting to the "inc" subdirectory of the application directory. The sentence is at the beginning of the script. Example :

ini_set("include_path", "/home/myusername/RDataMatrixphp_application/inc" );

Call demo.php using the appropriate URL in your browser and verify it works properly.

Basic Operation

Generating your first DataMatrix symbol.

You can see an example of the mininum coding effort to get up un running by using the provided sample code sample.php.

We reproduce and comment it here to show how it works.

First we set the include_path so PHP will find RDataMatrix program files, as we already did for the demo.php file:

ini_set("include_path", "/home/myusername/RDataMatrixphp_application/inc" );

We charge the class file of RDataMatrix for PHP:

require( "DataMatrix_class.inc" );

RDataMatrix for PHP uses PHP OOP capabilities in a Java-like style, so prior of executing
any function we must create a barcode object of the proper type. We use the
$bc variable for this.

$bc = new DataMatrix(); 

We are ready to obtain our barcode graphic. However we will usually wish to specify some parameters. All these settings are optional and if you don’t call the setting functions the program will use its default values. In this example we set the module size to 3 x 3 pixels.

$bc->setModuleSize(3);

To show the barcode, we call the paint() function. It receives as parameter the character string containing the code to be shown.

$bc->paint( "string to be encoded" );

Parameter Setting

Although all settings are optional you will usually need to set at least some of the program parameter’s in order to adjust it to your particular needs.

Important: To set any parameter you should use the provided setParameter() functions. You shouldn’t directly set any instance variable as it may lead to unexpected results and incompatibility of your code with future versions of the program  :

$bc->setParam( 2 ); // OK 
$bc->Param = 2; // DON’T DO THIS !!

You can set the following parameters :

Generic Parameters

setQuiteZone( int ) Sets the margin in pixels of the four sides around the graphic. You can also use setTopMargin() & setLeftMargin() instead.

setTopMargin( int ) Sets the vertical margin or empty space between the image’s border and the start of the bars. The bottom margin is se to the same size.

setLeftMargin( int ) Sets the horizontal margin or empty space between the image’s border and the start of the bars. The right margin is set to the same size.

setBGColor( string ) Sets the image’s background color.  It can have two formats :

1. A descriptive name among the predefined ones. They are: WHITE, RED, GREEN, BLUE, YELLOW, CYAN, ORANGE, GRAY, BLACK.
   ( Note: you may add your own colors editing the source code of Graphics.inc. Just add them to the $stdColors array definition )
2. The color’s RGB values in a comma-separated string.
   

Examples:

$bc->setBGColor( “YELLOW” );
$bc->setBGColor( “255,128,255” ); // rose

setBarColor( string ) Sets the color of the bars. Same format than setBGColor()

setRotation( integer ) Sets the rotation of the barcode. Acceptable values are :

• 0 normal
• 90 ( vertical, bars drawn from bottom to top )
• 180 ( inverted )
• 270 ( vertical, bars drawn from top to bottom )

setImageType( string [, integer] ):

Sets the image type in which the graphic will be generated. Second parameter is the quality (%). It’s optional and should be used only for JPEG.

There are four possible image formats in which the barcode can be generated:

• PNG: default and recommended format
• JPEG: note that image size will be much higher. You can reduce it reducing image quality ( second optional parameter in setImageType() ).
• GIF: note that it was removed from GD version 1.6, so it’s likely that you won’t have it available in recent PHP versions
• WBMP: note that this is a wireless format so it won’t show on most browsers

Examples:

$bc->setImageType( “GIF” );
$bc->setImageType( “JPEG”, 50 );

setFilePath( string )

Sets the file path where the image files will be created. After calling to this function, subseqüent calls to paint() will create a file instead of sending the image to the browser. By default the output will go to the browser. See  “Image Ouput” paragraph below for more details.

DataMatrix specific parameters

setModuleSize( int ) Sets the module width & heigth in pixels.

setTilde( boolean ) Specifies whether the tilde will be used as a flag to include special characters.

setEncoding( string ) Sets the encoding algorithm to be used. Possible values are: "C40", "TEXT", "BAS256", "ASCII", "AUTO". Default is "AUTO" and means that the program will automatically determine the most suitable enconding algorithm depending on the data to be encoded.

setFormat( int or string ) Sets the DataMatrix format. Possible values are :

• For square symbols (e.g. 10 x 10 ): 10,12,16,18,20,22,24,26,32,36,40,44,48,52,64,72,80,88,96,104,120,132,144
• For non square symbols : "8x18", "8x32", "12x26", "12x36", "16x36", "16x48"

By Default the program will automatically determine the most suitable format depending on the data to be encoded.

Image Output

The image that the program generates can be ouput in two ways: to the browser or to a file.

Output to browser

This is the default mode. In the last sentence of the sricpt we call to the paint() method so it will directly output the image to the browser (after appropriate HTTP headers of course). Note that you will usually need an HTML page with a form in it that will set the appropriate parameters. In the example we provide this is done by demo.php. In this mode you will usually generate only one image at a time.

Output to file

Activation

Barcode images can be stored into files. To do so you must first call setFilePath() in order to specify a base directory in your filesystem where the generated files will be stored. Please end it with a slash (“/”). If you want to use the current directory use “./” as path (You can use regular slash as PHP converts it to the backslash in Windows systems) . Note that this call is mandatory as it also works as an indicator that you want the output to a file.

File names

You have two options for the file name the generated image will have:

You can pass the file name you wish as a second optional parameter to the paint() method or you can do nothing so a default filename will be used ( code plug image type extension, e.g. ‘12345678.png’ )

Multiple file generation

When you send the output to a file, you can easily create many barcode images in one program. Just call to the paint() method as many times as you wish.

Formats

RDataMatrix supports all data matrix formats. The following table contains the size , the capacity and the correction error features of each format:

Encoding Algorithms

The data represented in the symbol is can be compressed using one or several of the following algorithms:

* ASCII: it is used to encode data that mainly contains ascii characters (0-127). It encodes one alphanumeric or two numeric characters per byte.
* C40: it is used to encode data that mainly contains numeric and upper case characters. C40 encodes three alphanumeric data characters into two bytes.
* TEXT: it is used to encode data that mainly contains numeric and lowercase characters. TEXT encodes three alphanumeric data characters into two bytes.
* BASE256: it is used to encode 8 bit values.

All encoding system can be used to encode any data, but for example, encoding binary data with C40 generates much more overhead (longer symbol) than with BASE256.

Special Characters

RDataMatrix uses the character ~ to recognize some special characters in the input data. The following possibilities are available:

* ~X is used to represent character values from 0 to 26. Replace the X like in the following example ~@ = means character ascii 0, ~A= means character 1, ~B=means character 2, ~C=means character 3 ...
* ~1: represents the character FNC1. When FNC1 appears in the first position (or in the fifth position of the first symbol of a Structured Append), it will indicate that the data conforms to the UCC/EAN Application Identifier standard format.
* ~2: It is used to represent Structured Append. Structured Append is used to link information from several symbols in a secuence. The ~2 must be followed by 3 additional bytes. The first 4 bits of thie first byte identify the position of the particular symbol in the secuence . The last 4 bits identify the total number of symbols in the secuence. The second and third byte are used as a file identifier are can have a value between 1 and 254 (up to 254*254=64516 identifiers). See Data Matrix Specification for more information about this (ISO 16022).
* ~3: This character are only allowed in the first position of the symbol. It indicates that the data contains commands for the barcode reader.
* ~4: not allowed.
* ~5 and ~6: These characters are only allowed in the first position of the symbol. If ~5 is used the header [)> ascii30 ascii05 ascii29 will be transmitted by the barcode reader before the data in the symbol and the trailer ascii30 ascii04 will be transmitted after the data. If a ~6 is used , the header [)> ascii30 ascii05 ascii29 will be transmittedby the reader before the data and the trailer ascii30 ascii04 will be transmitted afterwards.
* ~7NNNNNN specifies the Extended Channel to be used, where NNNNNN is a value between and 000000 - 999999. For example: ~7000010 means Extended Channel 10 . Extended channel is used for using other character sets other than ascii. See Data Matrix Specification for more information about this (ISO 16022).
* ~dNNN represents the ascii character encoded by the 3 digits NNN. For exmaple, ~d065 represents the character 'A'.

References

You can find more information about data matrix at:

• BarCode 1
• AIM International, Inc.
• ISO 16022