5.0-beta

[codemasher]

It's here! The main public API is finished so far. What's left is some cleanup dan documenting. Feel free to leave feedback in the linked discussion thread. Thanks!

---

This discussion was created from the release 5.0-beta.

[codemasher]

Release notes (draft)

New Features

• QR Code reader based on a PHP port of the ZXing library
  • MIT and Apache 2.0 dual licensing to accommodate the ZXing related files, see: NOTICE
• Proper mixed mode support (several data mode segments can appear in the same QR symbol)
  • Simplified Chinese (Hanzi/GB2312) support according to GBT18284-2000
  • ECI mode support
  • Structured append mode (not yet...)
• Full "reversed reflectance" support (inverted matrix colors)
• Encapsulated Postscript (EPS) output
• An all new documentation at https://php-qrcode.readthedocs.io/ in favor over the wiki
• A truckload of new examples

Changes

• [breaking] The default output has been changed from PNG (GdImage) to SVG. No image processing extension (ext-gd or ext-imagick) required anymore!
• [breaking] The default output format of the built-in output classes is now a base64 data URI (if applicable) so that it can be directly embedded as src into an <img> tag. This can be disabled by setting QROptions::$outputBase64 to false.
• [breaking] The values of the QRMatrix::M_* constants and therefore the keys of the QROptions::$moduleValues array have changed. QRMatrix::M_*_DARK constants have been introduced for convenience. The module values are now a bitmask, the dark value is now calculated (QRMatrix::M_* | QRMatrix::IS_DARK) instead of (QRMatrix::M_* << 8).
• [breaking] The output class QRMarkup has been changed to abstract, inheritors are now QRMarkupHTML and QRMarkupSVG (QRMarkupXML anyone?).
• The module value validation method QROutputInterface::moduleValueIsValid() is now public static, so that you can now check input values before invoking the options, e.g. QRMarkupSVG::moduleValueIsValid('#aabbcc'). Please note that in case of HTML and SVG it will only check for the basic syntax, it will not validate values.
• The GD output class now also supports BMP and WEBP output. The formerly GD exclusive options QROptions::$jpegQuality and QROptions::$pngCompression have been deprecated in favor of the more generic QROptions::$quality.

API

The full API documentation can be found under https://chillerlan.github.io/php-qrcode/

class names are relative from the namespace chillerlan\QRCode, only public facing items are listed

Changed/Moved

without deprecation

v4.3.x (old)	v5.x (new)
\QRCode::getMatrix(string $data)	\QRCode::getMatrix()
\QROptions::$imagickBG (array)	\QROptions::$bgColor (mixed)
\QROptions::$imageTransparencyBG (array)	\QROptions::$transparencyColor (mixed)
\Helpers\BitBuffer::class	\Common\BitBuffer::class
\Helpers\Polynomial::class	\Common\GF256::class
\Data\MaskPatternTester::class	methods moved to \Common\MaskPattern
\Data\QRMatrix::__construct(int $version, int $eclevel)	\Data\QRMatrix::__construct(Version $version, EccLevel $eccLevel)
\Data\QRMatrix::init(int $maskPattern, bool $test = null)	\Data\QRMatrix::initFunctionalPatterns()
\Data\QRMatrix::setFormatInfo(int $maskPattern, bool $test = null)	\Data\QRMatrix::setFormatInfo(MaskPattern $maskPattern = null)
\Data\QRMatrix::setQuietZone(int $size = null)	\Data\QRMatrix::setQuietZone(int $quietZoneSize)
\Data\QRMatrix::setVersionNumber(bool $test = null)	\Data\QRMatrix::setVersionNumber()
\Data\QRMatrix::mapData(array $data, int $maskPattern)	\Data\QRMatrix::writeCodewords(BitBuffer $bitBuffer)

deprecated

The following items are deprecated as of v5 and will be removed in v6.

v4.3.x (deprecated)	v5.x (new)
\QRCode::VERSION_AUTO	\Common\Version::AUTO
\QRCode::MASK_PATTERN_AUTO	\Common\MaskPattern::AUTO
\QRCode::ECC_L	\Common\EccLevel::L
\QRCode::ECC_M	\Common\EccLevel::M
\QRCode::ECC_Q	\Common\EccLevel::Q
\QRCode::ECC_H	\Common\EccLevel::H
\QRCode::OUTPUT_MARKUP_HTML	\Output\QROutputInterface::MARKUP_HTML
\QRCode::OUTPUT_MARKUP_SVG	\Output\QROutputInterface::MARKUP_SVG
\QRCode::OUTPUT_IMAGE_PNG	\Output\QROutputInterface::GDIMAGE_PNG
\QRCode::OUTPUT_IMAGE_JPG	\Output\QROutputInterface::GDIMAGE_JPG
\QRCode::OUTPUT_IMAGE_GIF	\Output\QROutputInterface::GDIMAGE_GIF
\QRCode::OUTPUT_STRING_JSON	\Output\QROutputInterface::STRING_JSON
\QRCode::OUTPUT_STRING_TEXT	\Output\QROutputInterface::STRING_TEXT
\QRCode::OUTPUT_IMAGICK	\Output\QROutputInterface::IMAGICK
\QRCode::OUTPUT_FPDF	\Output\QROutputInterface::FPDF
\QRCode::OUTPUT_EPS	\Output\QROutputInterface::EPS
\QRCode::OUTPUT_CUSTOM	\Output\QROutputInterface::CUSTOM
\QRCode::OUTPUT_MODES	\Output\QROutputInterface::MODES
\QRCode::getMatrix()	\QRCode::getQRMatrix()
\QRCode::isNumber()	\Data\Number::validateString()
\QRCode::isAlphaNum()	\Data\AlphaNum::validateString()
\QRCode::isKanji()	\Data\Kanji::validateString()
\QRCode::isByte()	\Data\Byte::validateString()
\QROptions::$imageBase64	\QROptions::$outputBase64
\QROptions::$pngCompression	\QROptions::$quality
\QROptions::$jpegQuality	\QROptions::$quality
\Data\QRMatrix::eccLevel()	\Data\QRMatrix::getEccLevel()
\Data\QRMatrix::maskPattern()	\Data\QRMatrix::getMaskPattern()
\Data\QRMatrix::matrix(bool $boolean = null)	\Data\QRMatrix::getMatrix(bool $boolean = null)
\Data\QRMatrix::size()	\Data\QRMatrix::getSize()
\Data\QRMatrix::version()	\Data\QRMatrix::getVersion()
\Output\QRImage::class	\Output\QRGdImage::class

Added

v5.x (new)
\QRCode::setOptions(SettingsContainerInterface $options)
\QRCode::renderMatrix(QRMatrix $matrix, string $file = null)
\QRCode::addSegment(QRDataModeInterface $segment)
\QRCode::clearSegments()
\QRCode::addNumericSegment(string $data)
\QRCode::addAlphaNumSegment(string $data)
\QRCode::addKanjiSegment(string $data)
\QRCode::addHanziSegment(string $data)
\QRCode::addByteSegment(string $data)
\QRCode::addEciSegment(int $encoding, string $data)
\QRCode::addEciDesignator(int $encoding)
\QRCode::readFromFile(string $path)
\QRCode::readFromBlob(string $blob)
\QRCode::readFromSource(LuminanceSourceInterface $source)
\QROptions::$svgPreserveAspectRatio
\QROptions::$svgWidth
\QROptions::$svgHeight
\QROptions::$connectPaths
\QROptions::$excludeFromConnect
\QROptions::$drawCircularModules
\QROptions::$circleRadius
\QROptions::$keepAsSquare
\QROptions::$drawLightModules
\QROptions::$bgColor
\QROptions::$readerUseImagickIfAvailable
\QROptions::$readerGrayscale
\QROptions::$readerIncreaseContrast
\QROptions::$addLogoSpace
\QROptions::$logoSpaceWidth
\QROptions::$logoSpaceHeight
\QROptions::$logoSpaceStartX
\QROptions::$logoSpaceStartY
\QROptions::$textLineStart
\QROptions::$jsonAsBooleans
\Common\EccLevel::class
\Common\ECICharset::class
\Common\MaskPattern::class
\Common\Mode::class
\Common\Version::class
\Data\QRMatrix::IS_DARK
\Data\QRMatrix::M_DARKMODULE_LIGHT
\Data\QRMatrix::M_DATA_DARK
\Data\QRMatrix::M_FINDER_DARK
\Data\QRMatrix::M_FINDER_DOT_LIGHT
\Data\QRMatrix::M_ALIGNMENT_DARK
\Data\QRMatrix::M_TIMING_DARK
\Data\QRMatrix::M_FORMAT_DARK
\Data\QRMatrix::M_VERSION_DARK
\Data\QRMatrix::M_QUIETZONE_DARK
\Data\QRMatrix::M_LOGO_DARK
\Data\QRMatrix::M_SEPARATOR_DARK
\Data\QRMatrix::M_TEST_DARK
\Data\QRMatrix::checkType(int $x, int $y, int $M_TYPE)
\Data\QRMatrix::checkTypeIn(int $x, int $y, array $M_TYPES)
\Data\QRMatrix::checkNeighbours(int $x, int $y, int $M_TYPE_VALUE = null)
\Data\QRMatrix::invert()
\Data\QRMatrix::mask()
\Data\QRMatrix::rotate90()
\Data\QRMatrix::setArea(int $startX, int $startY, int $width, int $height, bool $value, int $M_TYPE)
\Decoder\Decoder::class
\Decoder\DecoderResult::class
\Decoder\GDLuminanceSource::class
\Decoder\IMagickLuminanceSource::class
\Decoder\LuminanceSourceInterface::class
\Data\Hanzi::class
\Data\ECI::class
\Data\QRData::class
\Data\QRDataModeInterface::class
\Data\QRDataModeAbstract::class
\Output\QROutputInterface::moduleValueIsValid($value)
\Output\QREps::class
\Output\QRMarkupHTML::class
\Output\QRMarkupSVG::class

Removed

v4.3.x (old)	reason
\QRCode::initDataInterface()	data mode overhaul
\QROptions::$dataModeOverride	data mode overhaul
\Data\QRDataAbstract::class	data mode overhaul
\Data\QRDataInterface::class	data mode overhaul

[phil-gregory]

Hi...noob question, got v5 going all good. However, Im finding it quite easy to cause "image cannot be displayed because it has errors" when using specific urls (characters actually) urls with ? and = and other such characters.....should I be encoding these to prevent this ? (should mention Im using qr with embedded imagick image/logo)

[codemasher]

The error message usually occurs when a header is set (like in the examples) and an exception is thrown:

php-qrcode/examples/imagickWithLogo.php

Line 119 in c8c37a4

header('Content-type: image/png');

If you outcomment that line, you'll see the original exception message aka what went wrong.

[phil-gregory]

Cool (sort of) caught the error "Uncaught chillerlan\QRCode\Data\QRCodeDataException: code length overflow. (404 > 368 bit)" does this just mean my url is too long ? If so, what is the limit & can it be varied at all ?

[codemasher]

In the example, the QR Code version is set to 5 - you can either increase that number (up to 40) or set it to Version::AUTO (which is the default value, in which case you can remove that line entirely). You can find the data capacity information over here: https://www.qrcode.com/en/about/version.html

[phil-gregory]

Sweet, thanks and thanks for the fast responses. One other little aside question....If Im using anon-square logo (say 2:1 aspect) is there a simple way to centre it (vertically in the image ? or can I define an aspect ratio that matches my logo in some way ?

[codemasher]

I'm not sure if there's a way to let Imagick do that automatically, but it's only a few lines of math:tm: over here:

php-qrcode/examples/imagickWithLogo.php

Lines 36 to 47 in c8c37a4

	// set new logo size, leave a border of 1 module (no proportional resize/centering)
	$size = (($this->options->logoSpaceWidth - 2) * $this->options->scale);
	// logo position: the top left corner of the logo space
	$pos = (($this->moduleCount * $this->options->scale - $size) / 2);
	// invoke logo instance
	$imLogo = new Imagick($this->options->pngLogo);
	$imLogo->resizeImage($size, $size, Imagick::FILTER_LANCZOS, 0.85, true);
	// add the logo to the qrcode
	$this->imagick->compositeImage($imLogo, Imagick::COMPOSITE_ATOP, $pos, $pos);

[phil-gregory]

Thanks again for quick response. Yes Ive seen that chunk of code but wasnt able to figure out which bit is referencing the height of logo and/or which bit is referencing the height of the "enclosure". im sure I will if I look a bit harder and thanks again.

[codemasher]

The "enclosure" is $size, the pixel width/height of the logo space. In the example it's just that one size used for simplicity. However, there's logoSpaceHeight which you can use in addition and add it as $height in the same way (and rename $size to $width) and then pass it to $imLogo->resizeImage($width, $height, ...). Good luck! :)

[codemasher]

You may want to check out this one perhaps: https://www.php.net/manual/en/imagick.adaptiveresizeimage.php

[phil-gregory]

Following up on this, I got the logo to centre up (horizontally or vertically) if its a non-square image so for anyone interested, there's a few extra lines of maths code here:

$imageprops = $imLogo->getImageGeometry();
//get your logo width & height
$width = $imageprops['width'];
$height = $imageprops['height'];
//calculate the new size that imagick will make your image to fit within the canvas, subtract that from canvas target size, halve it to get an //additional offset to use in the composite image layout

$y_offset = (($size - ($size*$height/$width))/2 > 0) ? ($size - ($size*$height/$width))/2 : 0;

$x_offset = (($size - ($size*$width/$height))/2 > 0) ? ($size - ($size*$width/$height))/2 : 0;

$imLogo->resizeImage($size, $size, Imagick::FILTER_LANCZOS, 0.85, true);

// add the logo to the qrcode
$this->imagick->compositeImage($imLogo, Imagick::COMPOSITE_ATOP, $pos+$x_offset, $pos+$y_offset);

Thanks again to codemasher for the support :)

[neekfenwick]

Love this repo, just wanted to ask that the QROptionsTrait::returnResource option be given greater visibility for those wanting to use Imagick. I've spent a few hours trying to instantiate QRImagick, or derive a class from it, or pull other tricks to try to access the protected $imagick member, and just now noticed that dump() returns $this->imagick if returnResource is true. Maybe a new examples file that starts with an existing Imagick image and overlays a qrcode onto it. I've now got this working, by taking examples/imagick.php, setting returnResource=>true and using $qrIm = (new QRCode($options))->render('foobar') and $myIm->compositeImage($qrIm, ....) but I started off in completely the wrong direction :)

[codemasher]

Hey, i'm currently in the process of rewriting the documentation and the chapter for the options sure will include this!

[launay12u]

Hey thanks for this package ! I just wanted to know if you have a release date ? I want to use your repo but I prefer to wait until the v5 release, I don't want to start coding on the v4 and have to change just after for the v5. Thanks for the response !

[codemasher]

I'm going to be completely honest with you: I don't know. I'm struggling with health issues physical and mental and I'm having a hard time to focus on anything. I was about to prepare a release in March already, but there were still things I was unhappy with and so I decided to release it as beta at least, also in hope to gather some feedback. You can start writing your code for 5.x already, there won't be any more API changes aside of the one I created a PR for and I'm not sure if I should merge it at all.

tl;dr: I'm trying my best.

[launay12u]

sorry to hear that... Health is the priority, the work you provide is already great. It's a open source project and I think everybody can understand that you are other things in your head right now. Take your time, and I hope everything will be fine. I would like to help but I'm not sure that will understand and be useful 😅

[codemasher]

Thank you for understanding!