Overview

J4L BarCodes 1D for PHP is a software package that allows you to create bar codes of virtually any type (“symbology” or system) used nowadays for a variety of uses.

Some of its main features are:

• You have control over many relevant parameters in order to customize the resulting bar code image to your particular needs :
  • You can specify the width and height of the bars, the relation between different bars (narrow / wide bars) and the “quite zone” (margins).
  • You can specify the background color, the color of the bars and the text color.
  • You can use any True Type font for the printed text, and specify its size, and put it at the bottom (default) or on the top 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).
  • The program can calculate checksum characters if you don’t provide them.
• Developed using object oriented programming 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.
• FreeType Library, if you want to use True Type fonts. Also bundled in recent PHP distributions.
• 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.

Program Files

In this software package you will find the following files an directories:

• Program files (“inc” directory): Graphics.php, BarCode.inc, EAN_UPC.php, EAN.php, SET25.php and one file for each supported bar code type with the form BCTYPE_class.php
• Demonstration / examples ("www" directory) : demo.php, multisample.php, sample.php
• UserGuide.html (this file)

File Dependencies

You will always need the following files :

• Graphics.php
• BarCode.php
• BCTYPE_class.php, where BCTYPE stands for the specific barcode type you wan to use.

Additionally you will need the following files for certain bar code types:

• EAN.php and EAN_UPC.php for EAN8 & EAN13 bar code types.
• EAN_UPC.php for UPCA & UPCE bar code types
• SET25.php for MAT25, IND25 & INTERLEAVED25
• BAR39_class.php for BAR39EXT
• CODE93_class.php for CODE93EXT

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 access 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 <app.dir>/www/demo.php 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/J4L-BarCodes-1D-PHP/inc" );

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

Basic Operation

Generating your first bar code.

You can see an example of the minimum coding effort to get up un running by using the provided sample code sample.php. This script generates a CODE128 bar code.

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

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

ini_set("include_path", "/home/myusername/J4L-BarCodes-1D-PHP/inc" );

We charge the class file of the barcode type that we wish to use:

require("CODE128_class.php");

J4L BarCodes 1D 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 CODE128;

Note: to use a different bar code type just replace “CODE128” in the above PHP sentences by the actual bar code type you wish to use. The class names you should use are : CODE39, CODE39EXT, CODE11, CODABAR, CODE93, CODE93EXT, CODE128, EAN13, EAN8, INTERLEAVED25, IND25, MAT25, MSI, POSTNET, UPCA or UPCE.

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 “narrow bar” width to 2 pixels and its height to 60.

$bc->setX( 2 );
$bc->setbarHeight( 60 );

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

$bc->paint( '123456789012' );

If you want the image to be stored into a file or you want to create several images at a time, see the multisample.php script and the output to file section below.

User functions overview

All functions useful for normal operation of the software are listed below, grouped by section. Each section explains the use of the related functions, click on the section title to go to a section.

setX()
setN()
setBarHeight()
setCheckCharacter()

EAN / UPC Supplement:
setSuppSeparation()
setSuppHeight()

UPCE: setSystem()

CODABAR :
setStartChar()
setStopChar()

CODE39 : setI()

POSTNET:
setHeightTallBar()
setHeightShortBar()

setQuiteZone() 
setTopMargin() 
setLeftMargin() 
setBGColor() 
setBarColor() 
setTextFont() 
setFontSize()  
setRotation() 
setImageType()

setFilePath()
paint()

Generic Parameters

setX( int )

Sets the width in pixels of  a “narrow” bar (smallest type of bar to represent a byte).  Most barcode types use a “narrow” bar to represent a bit value, for instance “0”, and a “wide” bar to represent the other one, for instance “1”.

• Default : 1 pixel
• Example: $bc->setX( 2 );

setN( float )

Sets the size relation between a “narrow” and a “wide” bar. This is a multiplication of N. The final “wide bar” size will be obtained as X * N.

• Default : 2  ( wide bar is double than narrow bar )
• Example: $bc->setN( 2.5 );

setBarHeight( int )

Height of bars in pixels.

• Default : 50 pixels
• Example: $bc->setBarHeight( 80 );

setCheckCharacter( boolean )

Determines if the check character will be automatically calculated and added to the the bar code.  Otherwise the program assumes that it will be eventually provided by your application.

• Default : TRUE (J4L BarCodes 1D will add check character)
• Example: $bc->setCheckCharacter( $askYN == “Y” );

Symbology specific parameters

EAN / UPC Supplement

• You can add a supplement to EAN & UPC barcodes. You can specify it in three manners :
• Appending it to the code parameter, using a dash as separator. Example: 12345678-90 (90 would be the supplement).
• Calling the EAN/UPC specific method paintWithSupp().
   Example : $bc->paintWithSupp( ‘12345678', ‘90')
• Calling to the setSuplement() prior to the paint() call.
  Example : $bc->setSupplement(‘90'); $bc->paint(‘12345678');
• The supplement digits can also be automatically extracted from the code (each barcode type takes them from different positions). To use this –let's call it automatic mode-, you must call the setSupp2Flag() or setSupp5Flag() methods, prior to the paint() call.
  Example : $bc->setSupp2Flag(TRUE); $bc->paint(‘12345678');
  (will print “34” as supplement for EAN8 )
• Note that if you “manually” specify the supplement digits in any of the three forms explained at the first paragraph above, the “automatic mode” will be overridden for this specific paint() call.

setSuppSeparation( int )

Sets the separation in pixels between the supplement and the barcode. Default is 5.

setSuppHeight( float )

Sets the supplement height. This is a multiplicator of the bar code height. Default is 0.8 (80%).

UPCE : setSystem( int )

Sets the UPCE system (character set. It may be either 0 or 1 (default).

CODABAR :    setStartChar( string ); / setStopChar( string )

Set CODABAR start/stop characters. They may be either “A”, “B”, “C” or “D”.

• Defaut: “A” & “B”
• Example: $bc->setStartChar( “C” );

CODE39: setI( int )

Space between 2 characters. Multiplicator of X. Default 1.

POSTNET : setHeightTallBar( int ) / setHeightShortBar( int )

They set the height in pixels of the tall & short bar POSTNET uses. If you don't call to setHeightTallBar() the generic value set by setBarHeight() –or its default- will be used.

If you don't call to setHeightShortBar(), a default value of half of the tall bar will be used.

Image 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.

• Default : 10 pixels
• Example: $bc->setTopMargin( 20 );

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.

• Default : 10 pixels
• Example: $bc->setLeftMargin( 20 );

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.php Just add them to the $stdColors array definition )
2. The color’s RGB values in a comma-separated string.

Default : WHITE

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

setBarColor( string )

Sets the color of the bars. Same format that setBGColor();

• Default: BLACK

setFontColor( string )

Sets the color of the text below the bars. Same format that setBGColor();

• Default: BLACK

setTextFont( string )

Sets the Font in which the code text below the bars intended for human reading of the code. You can specify in two ways :

• Use any of the five PHP default fonts. Use DEFAULT-1, DEFAULT-2, DEFAULT-3, DEFAULT-4 or DEFAULT-5 values for this.
• Use a True Type font that you have in your system. Then you should specify the font’s file name. To find the file, the program follows the following rules :
• If you don’t put a file extension, it will add “.TTF”
• If you don’t specify the absolute path to the file, it will first look in the current directory for the font file.
• If not found it will look in the fonts directory. This directory is set in the Graphics.inc file, as the TTFPATH constant. You may want to change the default one ("./fonts").
• If the font file is not found, nothing will be done, the previously defined or default font will be used.

• Default : DEFAULT-3
• Examples:
  $bc->setTextFont( “DEFAULT-5” );
  $bc->setTextFont( “ARIAL” );
  $bc->setTextFont( “ARIAL.TTF” );
  $bc->setTextFont( “/home/me/myfonts/arial.ttf” );

Note: you can get some TTF fonts at http://sourceforge.net/projects/corefonts/

setFontSize( integer )

Sets the text font size. Only works for True Type fonts, not for PHP default fonts.

• Default: 10
• Example: $bc->setFontSize( 14 );

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 )

Note : Default PHP fonts only allow 90 degrees rotation. To allow 180 or 270 use a True Type font ( see setTextFont() ).

• Default: 0
• Example: $bc->setRotation( 270 );

setImageType( string [, int ] )

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 some GD versions so maybe it's not available in your system.
• WBMP: note that this is a wireless format so it won’t show on most browsers.

Examples:

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

Creating the symbol image

Related functions

setFilePath( string )

Sets the file path where the image files will be created. After calling to this function, subsequent calls to paint() will create a file instead of sending the image to the browser.

• Default: None (output direct to browser)
• Example: $bc->setFilePath( “./images” )

paint( string )

Creates and eventually outputs the symbol image.

Parameter : data string to be encoded.

Returns :
- The file name in which the image has been stored (if output is sent to a file).
- An empty string if the image was sent to the browser.

Output to browser

By default, if you don't call to setFilePath(), the paint() function 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 file system where the generated files will be stored. Please end it with a slash (“/”). If you want to use the current directory use “./” as path (in Windows systems you can use regular slash as PHP converts it to the backslash ). 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 that you wish as a second optional parameter to the paint() method, or, if you omit it the program will create one.

Multiple file generation

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