Home Page QRCode symbol generator for PHP
Home
Help
J4L QRCode for PHP
Overview
Demonstration
User Guide
Pricing & Ordering

Other barcodes for PHP
Barcode Suites
AztecCode
Barcodes 1D
DataMatrix
GS1 Databar (RSS)
MaxiCode
PDF417
QRCode

For other languages
.NET
ActiveX
AJAX/Javascript
C++
Delphi
Java
PHP
Realbasic
Ruby

Reader/Scanner
J4L Vision
User Guide

Overview

J4L QRCode for PHP is a software package that allows you to create QRCode symbols as images that you can use in a web site.

QR Code is a matrix symbology which includes a finder pattern located at three corners of the symbol used to locate the symbol and figure out its size and orientation.

The main features of QRCode symbols are:

  • There are 40 sizes of QR Code symbols (called Version 1, Version 2 till Version 40). Version 1 measures 21 modules * 21 modules, Version 2 measures 25 modules * 25 modules and so on. Version 40 measures 177 modules * 177 modules.
  • The following data can be encoded:
    • Numeric data (digits 0-9).
    • Alphanumeric characters , digits 0 - 9; upper case letters A -Z and nine other characters: space, $ % * + - . / :
    • Byte data (bytes 0-255)
    • Kanji characters ( hexadecimal values 8140 -9FFC and E040 - EBBF )
  • Symbol size is 21 * 21 modules to 177 * 177 modules (Versions 1 to 40, increasing in steps of 4 modules per side).
  • The maximum number of characters encoded in one symbol (without structured append) is:
    • Numeric data: 7089 characters
    • Alphanumeric data: 4296 characters
    • Byte data: 2953 characters
    • Kanji data: 1817 characters
  • Supports 4 error correction levels:
    • L ( 7% of the symbol codewords).
    • M ( 15% of the symbol codewords).
    • Q ( 25% of the symbol codewords).
    • H ( 30% of the symbol codewords).
  • Structured append (optional) This allows files of data to be represented logically in up to 16 QR Code symbols.
  • Extended Channel Interpretation (optional): enables data using character sets other than the default set (e.g. Arabic, Cyrillic, Greek).
  • FNC1 indicators: FNC1 mode is used for messages containing data formatted either in accordance with the UCC/EAN Application Identifiers standard or in accordance with a specific industry standard previously agreed with AIM International.

J4L-QRCode supports:

  • QRCode mode 2 symbols (not mode 1).
  • All versions 1-40. Automatic selection of the version is also supported.
  • Numeric, alphanumeric and byte modes (*). Automatic selection of the most appropriate mode is also supported.
  • Structured Append.
  • Extended Channel Interpretation (only one per symbol, no nesting supported).
  • All 4 error correction levels.
  • FNC1 indicators.

(*) Kanji mode is not supported yet. Please contact us if you need to encode Kanji characters.

Some of its features are:

  • You have control over many relevant parameters in order to customize the symbol 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 modules.
    • 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 programming techniques, you can easily modify the source code to adapt it to your specific application needs if you ever need to (of course you can also count on us to do it).

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 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 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/J4L-QRCodephp_application/inc" );

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

Basic Operation

Generating your first QRCode symbol.

You can see an example of the minimum coding effort to get up and 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 J4L QRCode program files, as we already did for the demo.php file:

ini_set("include_path", "/home/myusername/J4L-QRCodephp_application/inc" );

We charge the class file of J4L QRCode for PHP:

require("QRCode_class.php");

J4L QRCode 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 QRCode();

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 them the program will use its default values. In this example we set the QRCode error correction to level "Q".

$bc->setErrorCorrectionLevel('Q');

To show the symbol, we call the paint() function. It receives as parameter the character string containing the data to be encoded.

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

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.

Generic Image Parameters

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

QRCode parameters

setModuleSize()
setEncoding()
setVersion() setAutoConfigurate() setErrorCorrectionLevel() setECI() setFNC1Mode() setProcessTilde()
setStructuredAppendCounter() setStructuredAppendIndex()

Creating the symbol image

setFilePath()
paint()

Error Management

setErrorShowMode()
setErrorLogMode()
getErrorCode()
getErrorMsg()

Generic Image Parameters

setQuiteZone( int ) Sets the margin in pixels of the four sides around the graphic. You can also use setTopMargin() & setLeftMargin() instead. The QRCode specification requires a quite zone of 4 modules, which is the default value if you don't call this function.

setTopMargin( int ) Sets the vertical margin or empty space between the image’s border and the start of the bars. The bottom margin is set 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 square modules & fixed patterns. Same format than setBGColor()

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

  • 0 normal
  • 90 ( vertical, rotated counterclockwise)
  • 180 ( inverted )
  • 270 ( vertical, rotated clockwise)

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 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 );

QRCode parameters

Module size

setModuleSize( int ) Sets the number of pixels which make a module (square) in the barcode (default is 4).

setEncoding( string ): "ALPHA", "NUMERIC", "BYTE", "AUTO" (default).

  • AUTO: Automatic selection of the encoding method (recommended).
  • ALPHA: encode alphanumeric characters only (uppercase letters plus 9 additional characters).
  • NUMERIC: encode digits only.
  • BYTE: use this mode to encode binary data.

setVersion( int ): Sets the QRCode version to use. Values from 1 to 40, where 1 is the smallest one and 40 the bigger. Data capacity of each version is listed in the annex A. Default is 1. See also setAutoConfigurate() below.

setAutoConfigurate( boolean ): set to true (default) to allow automatic selection of a larger version if the data to encode does not fit in the version defined by setVersion().

setErrorCorrectionLevel( char ): The following values are possible :

Error Correction Level Recovery Capacity % (approx.)
'L' (default) 7
'M' 15
'Q' 25
'H' 30

setECI( int ): Sets the Extended Channel Interpretation (ECI) code. valid values are 1 to 99999999. The appropriate ECI header will be added. Nested ECI's are not supported.

setFNC1Mode( int, string ): FNC1 mode is used for messages containing data formatted either in accordance with the UCC/EAN Application Identifiers standard or in accordance with a specific industry standard previously agreed with AIM International. Possible values for the first parameter :

  • NULL : disable FNC1 (default).
  • 1 : FNC1 in first position. This Mode Indicator identifies symbols encoding data formatted according to the UCC/EAN Application Identifiers standard.
  • 2 : FNC1 in second position. This Mode Indicator identifies symbols formatted in accordance with specific industry or application specifications previously agreed with AIM International. In this case you must pass a second parameter with the value for the Application Indicator.

setProcessTilde( boolean ): Enables / disables tilde processing used for encoding special characters. By default is enabled.

When enabled it works as follows:

  • ~~: will be replaced with ~
  • ~dxxx: will be replaced by the character whose ascii code is xxx. For example ~d065 will be replaced with A.

setStructuredAppendCounter( int ): When the symbol is part of an Structured Append set, this is the total number of symbols in the set. Valid values : 2 to 16. If this is not set, or set to 1, the symbol is assumed to be standalone (no structured append used).

setStructuredAppendIndex( int ): When the symbol is part of an Structured Append set, this is the number of this symbol in the set. Valid values : 1 to 16.

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.

paint( string ) Creates and eventually outputs the symbol image.

Parameter : data string to be encoded.

Returns :
- NULL if some error condition is found that prevents the image to be created. See Error Management.
- 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.

Error Management

When trying to create the symbol (paint() function) a number of issues may arise. They have been classified in three categories, similar to those of PHP : errors, warnings and notices. Errors are serious problems that prevent the image from being created, warnings indicate non fatal problems -the image can be created anyway- but they should corrected as they may lead to problems when decoding. Finally notices are used to inform of minor issues which are usually irrelevant.

Notes:

  • Unless otherwise specified by the context, we will refer generically as "errors" for the three conditions: errors, warnings or notices.
  • Errors are triggered mainly by paint(). In general, functions that set parameters will ignore wrong parameters and will use defaults instead.

There are three ways errors/warnings/notices can be managed :

  • they can be processed by your PHP script
  • they can be shown to the user
  • they can be logged

The three options are independent and either of them can be used or not used/disabled.

Processing errors in the calling script

string getErrorCode()
string getErrorMsg()

These functions return an error code and description of the last error occurred. The first character of the error code indicates the type of error: "E" for errors, "W" for warnings and "N" for notices.

If no error has been detected, both functions will return NULL.

Example :

$bc-> paint( $data );
$status = $bc->getErrorCode();

if ( $status === NULL  OR $status[0] == 'N' ) 
    ok_process();
else
    if ( $status == 'E_OVERFLOW' )
      procedure_to_reduce_size();
    else
      other_error_found();

show the errors to the user

setErrorShowMode( string types, string mode [, string predefined_text [, string image_file ] ] )

sets how errors will (or won't) be shown to the user.

Parameters :

  • types: Defines which types of errors will be affected by the setting. Must be a string containing 1 to 3 characters, of the following allowed : EWN.
  • mode: Defines which show mode to use. Three allowed values : "IMG","TXT" and "NO".
  • predefined_text: for IMG and TXT modes, sets a fixed text that will be used instead of the error description. Can be omitted or set to NULL so in both cases the specific error description will be used.
  • image_file: for the IMG mode, it should be the relative path to an image file

There are three modes for showing errors :

  • 'IMG' (image): default and recommended mode: shows the error inside the resulting image.
  • 'TXT' (text): shows the error as plain text. Note that, unless you output the image to a file, the image won't show as it will be replaced by the error text. In such case note that, if you are calling the script from an img tag you will get a broken image or some error message from the browser.
  • 'NO': error showing disabled. This may be fine for notices and warnings but note that for errors you should process the error from your script, because otherwise your browser will show a broken image or generic error.

Defaults are : show image for errors and warnings and ignore notices. This is equivalent to :

$bc->setErrorShowMode( 'EW', 'IMG' );
$bc->setErrorShowMode( 'N', 'NO' ); 

Examples :

show all error types as text :

$bc->setErrorShowMode( 'EWN', 'TXT' );

disable showing warnings :

$bc->setErrorShowMode( 'W', 'NO' ); 

show a generic message using an ad hoc image :

$bc->setErrorShowMode( 'EW', 'IMG, 'SOME ERROR WAS FOUND', 'imgs/error.png' );

error logging

setErrorLogMode( string types, string mode [, string $file ] )

Parameters :

  • types: Defines which types of errors will be affected by the setting. Must be a string containing 1 to 3 characters, of the following allowed : EWN.
  • mode: Defines which log mode to use. Three allowed values : "PHP","FILE" and "NO".
  • file : log file for mode 'FILE'

Explanation of modes :

  • 'PHP': uses PHP error logging (calls trigger_error() ). This is the default for all error types.
    • Errors are logged as E_USER_WARNING, while warnings and notices are logged as E_USER_NOTICE. This is done this way in order to avoid E_USER_ERROR as it would abort the script execution.
    • Note that if you have PHP error logging off, no logging will be done.
    • If you have display_errors on, it will be disabled to avoid broken images. Use the error showing options if you want to see the error messages in the browser.
  • 'FILE': logs errors to a file, which path is provided as a second parameter.
  • 'NO': disables logging.

Example: log all errors to a file :

$bc->setLOgMode( 'EWN', 'FILE', 'logs/QRCode_errors.txt' );

Error codes currently used

 E_NO_DATA No data to encode was supplied
E_SIZE_LIMIT

Reached the maximum data size available with current settings, but still there is data remaining to be encoded. Possible corrective actions :

  • Use the automatic encoding mode or a mode more efficient for the kind data that you wish to encode.
  • Enable auto-configure or select a higher version
  • Reduce error correction level
  • Reduce data size
W_INVALID_PARAMETER Some of the parameters set has a non-allowed value.

 

Annex A

Table  Data capacity for QRCode versions

Version Error
Correction
Level

Numeric

Alphanumeric

Byte

Kanji

1

L
M
Q
H

41
34
27
17

25
20
16
10

17
14
11
7

10
8
7
4

2

L
M
Q
H

77
63
48
34

47
38
29
20

32
26
20
14

20
16
12
8

3

L
M
Q
H

127
101
77
58

77
61
47
35

53
42
32
24

32
26
20
15

4

L
M
Q
H

187
149
111
82

114
90
67
50

78
62
46
34

48
38
28
21

5

L
M
Q
H

255
202
144
106

154
122
87
64

106
84
60
44

65
52
37
27

6

L
M
Q
H

322
255
178
139

195
154
108
84

134
106
74
58

82
65
45
36

7

L
M
Q
H

370
293
207
154

224
178
125
93

154
122
86
64

95
75
53
39

8

L
M
Q
H

461
365
259
202

279
221
157
122

192
152
108
84

118
93
66
52

9

L
M
Q
H

552
432
312
235

335
262
189
143

230
180
130
98

141
111
80
60

10

L
M
Q
H

652
513
364
288

395
311
221
174

271
213
151
119

167
131
93
74

11

L
M
Q
H

772
604
427
331

468
366
259
200

321
251
177
137

198
155
109
85

12

L
M
Q
H

883
691
489
374

535
419
296
227

367
287
203
155

226
177
125
96

13

L
M
Q
H

1022
796
580
427

619
483
352
259

425
331
241
177

262
204
149
109

14

L
M
Q
H

1101
871
621
468

667
528
376
283

458
362
258
194

282
223
159
120

15

L
M
Q
H

1250
991
703
530

758
600
426
321

520
412
292
220

320
254
180
136

16

L
M
Q
H

1408
1082
775
602

854
656
470
365

586
450
322
250

361
277
198
154

17

L
M
Q
H

1548
1212
876
674

938
734
531
408

644
504
364
280

397
310
224
173

18

L
M
Q
H

1725
1346
948
746

1046
816
574
452

718
560
394
310

442
345
243
191

19

L
M
Q
H

1903
1500
1063
813

1153
909
644
493

792
624
442
338

488
384
272
208

20

L
M
Q
H

2061
1600
1159
919

1249
970
702
557

858
666
482
382

528
410
297
235

21

L
M
Q
H

2232
1708
1224
969

1352
1035
742
587

929
711
509
403

572
438
314
248

22

L
M
Q
H

2409
1872
1358
1056

1460
1134
823
640

1003
779
565
439

618
480
348
270

23

L
M
Q
H

2620
2059
1468
1108

1588
1248
890
672

1091
857
611
461

672
528
376
284

24

L
M
Q
H

2812
2188
1588
1228

1704
1326
963
744

1171
911
661
511

721
561
407
315

25

L
M
Q
H

3057
2395
1718
1286

1853
1451
1041
779

1273
997
715
535

784
614
440
330

26

L
M
Q
H

3283
2544
1804
1425

1990
1542
1094
864

1367
1059
751
593

842
652
462
365

27

L
M
Q
H

3517
2701
1933
1501

2132
1637
1172
910

1465
1125
805
625

902
692
496
385

28

L
M
Q
H

3669
2857
2085
1581

2223
1732
1263
958

1528
1190
868
658

940
732
534
405

29

L
M
Q
H

3909
3035
2181
1677

2369
1839
1322
1016

1628
1264
908
698

1002
778
559
430

30

L
M
Q
H

4158
3289
2358
1782

2520
1994
1429
1080

1732
1370
982
742

1066
843
604
457

31

L
M
Q
H

4417
3486
2473
1897

2677
2113
1499
1150

1840
1452
1030
790

1132
894
634
486

32

L
M
Q
H

4686
3693
2670
2022

2840
2238
1618
1226

1952
1538
1112
842

1201
947
684
518

33

L
M
Q
H

4965
3909
2805
2157

3009
2369
1700
1307

2068
1628
1168
898

1273
1002
719
553

34

L
M
Q
H

5253
4134
2949
2301

3183
2506
1787
1394

2188
1722
1228
958

1347
1060
756
590

35

L
M
Q
H

5529
4343
3081
2361

3351
2632
1867
1431

2303
1809
1283
983

1417
1113
790
605

36

L
M
Q
H

5836
4588
3244
2524

3537
2780
1966
1530

2431
1911
1351
1051

1496
1176
832
647

37

L
M
Q
H

6153
4775
3417
2625

3729
2894
2071
1591

2563
1989
1423
1093

1577
1224
876
673

38

L
M
Q
H

6479
5039
3599
2735

3927
3054
2181
1658

2699
2099
1499
1139

1661
1292
923
701

39

L
M
Q
H

6743
5313
3791
2927

4087
3220
2298
1774

2809
2213
1579
1219

1729
1362
972
750

40

L
M
Q
H

7089
5596
3993
3057

4296
3391
2420
1852

2953
2331
1663
1273

1817
1435
1024
784