In order to use the QR barcodes the library module "QR/qrencoder.inc.php" must first be included in the script.

The following script shows how to create the simplest possible QR code (in PNG format) representing the data string "The first QR code" encoded using all default values. The resulting QR Code is shown in Figure 27.6

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

<?php // content="text/plain; charset=utf-8"
require_once('jpgraph/QR/qrencoder.inc.php');
 
// Data to be encoded
$data = '01234567';
 
// Create a new instance of the encoder and let the library
// decide a suitable QR version and error level
$e=new QREncoder();
 
// Use the image backend (this is also the default)
$b=QRCodeBackendFactory::Create($e);
 
// .. send the barcode back to the browser for the data
$b->Stroke($data);
?>

Figure 27.6. The first very basic QR code (qrexample00.php)

(As can be seen this follows the same principles as the creation of Datamatrix symbols)

The principle is the same for all type of data QR code creations. First an instance of the chosen encoder is instantiated. In this case using all default parameters by creating an instance of class QREncoder. We then create a suitable backend that handles the output of the barcode. By default the output will be an image encoded in the PNG image format.

The final step is to send back the generated image to the browser with a call to the method Backend::Stroke() with the data to be encoded as its first argument.

The example above does not have any error handling. If there is some error in the process an exception will be thrown in the same way as in other places in the library. The default exception will display a standard library image error box. An example of this is shown in Figure 27.7

Figure 27.7. QR Error message

If some additional processing is necessary and to just display a text based re-formatted error message we could change the above code to catch this exception as the following example shows.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

<?php // content="text/plain; charset=utf-8"
require_once('jpgraph/QR/qrencoder.inc.php');
 
// Data to be encoded
$data = '01234567';
 
// Create a new instance of the encoder and let the library
// decide a suitable QR version and error level
$encoder = new QREncoder(1);
 
// Use the image backend (this is also the default)
$backend = QRCodeBackendFactory::Create($encoder);
 
try {
    //     . send the QR Code back to the browser
    $backend->Stroke($data);
} catch (Exception $e) {
    $errstr = $e->GetMessage();
    echo 'QR Code error: '.$e->GetMessage()."\n";
    exit(1);
}
 
?>

Figure 27.8. Adding basic exception handling (qrexample0.php)

As a final initial example the next script uses the backend method Backend::SetModuleWidth($aWidth) to increase the size of one module. Since a module in QR code refers to the smallest square used adjusting the module width will also adjust the height of the overall QR code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

<?php // content="text/plain; charset=utf-8"
require_once('jpgraph/QR/qrencoder.inc.php');
 
// Data to be encoded
$data = '01234567';
 
// Create a new instance of the encoder and let the library
// decide a suitable QR version and error level
$encoder = new QREncoder();
 
// Use the image backend
$backend = QRCodeBackendFactory::Create($encoder, BACKEND_IMAGE);
 
// Set the module size (quite big)
$backend->SetModuleWidth(5);
 
// .. send the barcode back to the browser for the data
$backend->Stroke($data);
?>

Figure 27.9. Adjusting the module width for the QR code (qrexample01.php)

As in other parts of the library the QR module throws an exception when an error occurs. As shown in the previous section an error image is the default if no explicit try {} catch {} statement is added to the script.

The script below shows how to catch the error, do some possible clean up and then explicitly create and send back the error image.

1
2
3
4
5
6
7
8
9
10

<?php
...
try {
    $backend->Stroke($data);
} catch( Exception $e ) {
    doCleanup();
    $errobj = new QRErrObjectImg();
    $errobj->Raise($e->getMessage());    
}
?>

another variant of this would be to re-throw the exception after the cleanup has been performed as the following example shows

1
2
3
4
5
6
7
8
9

<?php
...
try {
    $backend->Stroke($data);
} catch( Exception $e ) {
    doCleanup();
    throw $e;
}
?>

It is also possible to get hold of the internal error code that corresponds to each error message by calling the PHP standard exception method Exception::getCode() as the following example shows

1
2
3
4
5
6
7
8
9
10

<?php
...
try {
    $backend->Stroke($data);
} catch (Exception $e) {
    $errstr = $e->GetMessage();
    $errcode = $e->GetCode();
    echo "QR error ($errcode). Message: $errstr\n";
}
?>

Table 27.4 lists the public errors that can be thrown by the QR code module (the table deliberately excludes internal error messages)

A QR encoder is created as an instance of class QREncoder. The constructor have the following signature

The following examples creates a basic encoder which will automatically select the smallest possible size to fit the data given

1

$encoder = new QREncoder();

The following example will create an instance of an encoder with size 22 and error correction level 'Q'

1

$encoder = new QREncoder(22, QRCapacity::ErrQ);

The absolute simplest way of encoding data is simply to create a simple string representing the data to be encoded and then pass that string as the first argument to the Stroke() method in the backend. The encoder will then analyze the input data and choose the most efficient space saving encoding schema for this data.

The QR standard allows 3 different compaction schema that can be used to minimize the number of codewords used for a particular data string. This also means that a particular data string may have several different valid barcodes that visually looks different.

The supported compaction modes in the library are:

When the automatic encoding is chosen this will create an optimum encoding (from a size perspective) of the supplied data. This includes shifting encoding method in the middle of the data one or several time depending on the structure of the data.

It is also possible to manually control the exact encodation of the input data. This is done by supplying one or more data tuples where the first entry in the tuple is the compaction schema and the second the data. To encode the data manually the following structure must then be followed:

$data = array( array( <encoding_mode1> , <data1> ),
               array( <encoding_mode2> , <data2> ),
                         ...
               array( <encoding_modeN> , <dataN> ));

The encoding mode is specified as one of three symbolic constants

and the data is specified as a regular text string. Each section of data must therefore have the compaction mode specified.

In order to use a specific encodation schema one has to create an array as input instead of the normal string input. For example, to specify an input where the encodation should be alphanumeric encoding of the digits '0123456789' one would have to create the array

1
2
3
4
5

<?php
$data = array( array( QREncoder::MODE_ALPHANUM,'0123456789') );
...
$backend->Stroke($data)
?>

It is also possible to use different encodings for different parts of the data in a similar way as the following example shows

1
2
3
4
5
6
7
8

<?php
$data = array( array(QREncoder::MODE_ALPHANUM,'0123456789'),
               array(QREncoder::MODE_BYTE,'ABCDEFGH') 
             );
...
...
$backend->Stroke($data)
?>

Normally the method Backend::Stroke($aData) is sued to create a QR code from the datastring given. This string can of course come from a database, user input or from a file. The library provides a utility method

which makes it easy to get data directly from a file. Otherwise it behaves exactly the same as the normal Backend::Stroke().

In order to create the actual output one or more backends must be created. The QR Code supports the following backends:

The following code snippet shows two ways of creating a barcode image backend.

1
2
3
4
5

<?php
$encoder = new QREncoder();
$backend = QRCodeBackendFactory::Create($encoder);
...
?>

1
2
3
4
5

<?php
$encoder = new QREncoder();
$backend = QRCodeBackendFactory::Create($encoder,BACKEND_IMAGE);
...
?>

The following code shows a complete script to generate a postscript output

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

<?php // content="text/plain; charset=utf-8"
// Include the library
require_once('jpgraph/QR/qrencoder.inc.php');
 
// Example 11 : Generate postscript output
 
$data         = 'ABCDEFGH01234567'; // Data to be encoded
$version      = -1;  // -1 = Let the library decide version (same as default)
$corrlevel    = QRCapacity::ErrH; // Error correction level H (Highest possible)
$modulewidth  = 3;
 
// Create a new instance of the encoder using the specified
// QR version and error correction
$encoder = new QREncoder($version,$corrlevel);
 
// Use the image backend
$backend = QRCodeBackendFactory::Create($encoder, BACKEND_PS);
 
// Set the module size
$backend->SetModuleWidth($modulewidth);
 
// Store the barcode in the specifed file
$ps_str = $backend->Stroke($data);
 
echo '<pre>'.$ps_str.'</pre>';
?>

Figure 27.11. QR Code - Example Postscript Output

The following methods are available to adjust the final look and feel of the barcode

For the image backend it is possible to adjust the image encoding format with the following method

For postscript backend it is possible to select whether the postscript should be generated as encapsulated postscript. This is controlled by the method

The following (complete) script can be used as a starting point for creation of more advanced barcode scripts

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

<?php // content="text/plain; charset=utf-8"
require_once('jpgraph/QR/qrencoder.inc.php');
 
// Data to be encoded
$data         = 'ABCDEFGH01234567';
 
// QR Code specification
$version      = -1;                  // -1 = Let the library decide version (same as default)
$corrlevel    = QRCapacity::ErrM;   // Medium erro correction
$modulewidth  = 2;                    // Module width
$back         = BACKEND_IMAGE;        // Default backend
$quiet          = 4;                     // Same as default value
 
// Create encoder and backend
$encoder = new QREncoder($version, $corrlevel);
$backend = QRCodeBackendFactory::Create($encoder, $back);
 
// Set the module size
$backend->SetModuleWidth($modulewidth);
 
// Set Quiet zone (this should rarely need changing from the default)
$backend->SetQuietZone($quiet);
 
if( $back == BACKEND_IMAGE ) {
 
    $backend->Stroke($data);
}
else {
    $str = $backend->Stroke($data);
    echo '<pre>'.$str.'</pre>';
}
?>

Figure 27.12. A QR code template (qr_template.php)

As an example the library includes a WEB-based demo barcode creation application. This application can be used to easily create barcode through it's WEB interface. It is available at 'qr/demoapp/index.html'

This application is primarily included as a demo on the features available in the library and not as a finalized product.

Figure 27.13 shows a screen shot of the application interface.

Figure 27.13. QR Code WEB-based demo application