Come creare un QR Code con icona incorporata in PHP

Categoria: PHP • Grafica • Tutorial   | Livello: Intermedio

I QR Code sono ormai onnipresenti: li troviamo sui menu dei ristoranti, sulle confezioni dei prodotti, nei biglietti da visita digitali. Ma un QR Code con il logo aziendale al centro non solo è esteticamente più accattivante, ma rafforza anche il riconoscimento del brand. In questo articolo vedremo come generarlo in PHP con poche righe di codice.

La buona notizia è che i QR Code hanno una ridondanza incorporata (error correction), il che significa che anche sovrapponendo un’icona al centro — che “oscura” una parte del codice — il QR rimane perfettamente leggibile, a patto di non esagerare con le dimensioni dell’icona.

1. Prerequisiti e librerie

Avremo bisogno di:

• PHP 7.4 o superiore (consigliato PHP 8.x)
• Composer per la gestione delle dipendenze
• La libreria endroid/qr-code (la più diffusa e mantenuta attivamente)
• L’estensione GD di PHP abilitata (per manipolare le immagini)

Per installare la libreria via Composer, esegui nel terminale:

composer require endroid/qr-code

Se preferisci non usare Composer puoi lavorare con la libreria PHP QR Code (phpqrcode) in forma standalone, ma endroid/qr-code è decisamente più moderna e flessibile.

2. Generare il QR Code di base

Prima di aggiungere l’icona, generiamo un QR Code semplice. Crea un file generate_qr.php:

<?php

require ‘vendor/autoload.php’;
use Endroid\QrCode\QrCode;
use Endroid\QrCode\Writer\PngWriter;
$qrCode = QrCode::create(‘https://www.tuosito.it’)

    ->setSize(400)

    ->setMargin(20)

    ->setErrorCorrectionLevel(‘H’); // Alta ridondanza

$writer = new PngWriter();
$result = $writer->write($qrCode);
$result->saveToFile(‘qrcode.png’);
echo “QR Code generato: qrcode.png”;

Nota importante: Imposta sempre l’error correction level a ‘H’ (High) quando vuoi inserire un’icona. Questo livello garantisce che il QR Code rimanga leggibile anche se fino al 30% della sua superficie viene coperta.

3. Aggiungere l’icona con GD

Ora arriva la parte interessante. Una volta generato il QR Code come PNG, usiamo le funzioni GD di PHP per sovrapporre un’icona al centro. Il processo segue questi passi:

1. Caricare il QR Code come risorsa immagine GD
2. Caricare l’icona (PNG con trasparenza consigliato)
3. Calcolare le coordinate del centro del QR
4. Ridimensionare l’icona (max 25-30% del QR)
5. Copiare l’icona sul QR Code con imagecopyresampled()
6. Salvare il risultato finale

Ecco il codice completo:

<?php

require ‘vendor/autoload.php’;
use Endroid\QrCode\QrCode;
use Endroid\QrCode\Writer\PngWriter;
function generaQrConIcona(
string $url,

    string $iconaPath,

    string $output = ‘qr_con_logo.png’,

    int $dimensioneQr = 400,

    float $percentualeIcona = 0.25

): void {

    // 1. Genera il QR Code base

    $qrCode = QrCode::create($url)

        ->setSize($dimensioneQr)

        ->setMargin(20)

        ->setErrorCorrectionLevel(‘H’);

    $writer = new PngWriter();

    $qrPngData = $writer->write($qrCode)->getString();

    // 2. Carica le immagini come risorse GD

    $qrImg = imagecreatefromstring($qrPngData);

    $icona  = imagecreatefrompng($iconaPath);

    // 3. Calcola dimensioni

    $qrW = imagesx($qrImg);

    $qrH = imagesy($qrImg);

    $iconaW = imagesx($icona);

    $iconaH = imagesy($icona);

    // Dimensione target icona (max 25% del QR)

    $targetW = (int)($qrW * $percentualeIcona);

    $targetH = (int)($iconaH * ($targetW / $iconaW));

    // Coordinate per centrare

    $x = (int)(($qrW – $targetW) / 2);

    $y = (int)(($qrH – $targetH) / 2);

    // 4. Sovrapponi icona sul QR Code

    imagecopyresampled(

        $qrImg, $icona,

        $x, $y, 0, 0,

        $targetW, $targetH,

        $iconaW, $iconaH

    );

    // 5. Salva e libera memoria

    imagepng($qrImg, $output);

    imagedestroy($qrImg);

    imagedestroy($icona);

}

// Utilizzo

generaQrConIcona(

    ‘https://www.tuosito.it’,

    ‘logo.png’,

    ‘output/qr_logo.png’,

    400,    // dimensione QR in pixel

    0.25    // icona occupa il 25%

);

4. Aggiungere uno sfondo bianco all’icona

Se la tua icona ha uno sfondo trasparente (PNG con canale alpha), potresti voler aggiungere un cerchio o un rettangolo bianco attorno ad essa per migliorare il contrasto col QR Code e renderla più leggibile. Aggiungi queste righe prima di imagecopyresampled():

// Crea sfondo bianco arrotondato

$padding = 10;

$bianco = imagecolorallocate($qrImg, 255, 255, 255);

imagefilledrectangle(

    $qrImg,

    $x – $padding,

    $y – $padding,

    $x + $targetW + $padding,

    $y + $targetH + $padding,

    $bianco

);

Per uno sfondo circolare, puoi usare imagefilledellipse() con le stesse coordinate calcolate. L’effetto finale è un cerchio bianco che “isola” visivamente l’icona dal pattern del QR.

5. Usare la libreria Logo integrata (metodo alternativo)

La libreria endroid/qr-code offre anche un supporto nativo per i logo tramite la classe Logo, che semplifica ulteriormente il processo:

use Endroid\QrCode\Logo\Logo;

$logo = Logo::create(‘logo.png’)

    ->setResizeToWidth(80)    // larghezza in pixel

    ->setPunchoutBackground(true); // sfondo bianco auto

$result = $writer->write($qrCode, null, $logo);

$result->saveToFile(‘qr_logo_nativo.png’);

setPunchoutBackground(true) aggiunge automaticamente uno sfondo bianco attorno al logo, garantendo la massima leggibilità senza dover scrivere codice GD manuale. È il metodo consigliato se stai già usando endroid/qr-code.

6. Consigli pratici e best practice

• Dimensione icona: non superare il 30% della superficie totale del QR. Con error correction ‘H’, puoi coprire fino al 30%, ma stare sotto il 25% è più sicuro.
• Formato icona: usa PNG con trasparenza. JPEG con sfondo bianco funziona ma risulta meno pulito.
• Testa sempre il QR generato con più app diverse (Google Lens, app fotocamera nativa, app dedicate) prima di usarlo in produzione.
• Risoluzione: per la stampa, usa almeno 1000×1000 pixel. Per il web, 400×400 px è sufficiente.
• Colori: evita QR Code con colori chiari su sfondo chiaro. Il contrasto tra moduli e sfondo deve essere elevato.
• Cache: se generi QR dinamici a runtime, considera di salvare il risultato su disco e servirlo come file statico per evitare rigenerazioni inutili.

7. Esposizione via HTTP

Se vuoi restituire il QR direttamente al browser invece di salvarlo su file, usa questo approccio:

header(‘Content-Type: image/png’);

header(‘Cache-Control: max-age=86400’); // cache 24h

imagepng($qrImg); // output diretto

imagedestroy($qrImg);

In questo modo potrai incorporare il QR direttamente in una pagina HTML con un semplice tag <img src=”genera_qr.php?url=https://…”> passando l’URL come parametro GET.

Conclusioni

Generare QR Code con logo incorporato in PHP è sorprendentemente semplice grazie alla libreria endroid/qr-code e alle funzioni GD native. Il risultato è un codice leggibile e brandizzato che può essere integrato in qualsiasi flusso applicativo: landing page, fatture PDF, app mobile, campagne di marketing.

Ricorda sempre di testare il QR finale prima della distribuzione: la leggibilità è la priorità assoluta, e un codice esteticamente bello ma non funzionante è inutile.

Al prossimo articolo!