LeanQR : générer des QR Codes en PHP simplement, sans dépendances inutiles
Les QR Codes sont aujourd’hui omniprésents. On les retrouve sur des affiches, des factures, des cartes de visite, des billets, des documents administratifs, des interfaces web ou encore dans des systèmes de paiement. Ils permettent de transmettre rapidement une URL, une adresse email, un identifiant ou un court texte à un smartphone, simplement en pointant l’appareil photo vers une image.
En PHP, il existe déjà plusieurs bibliothèques très complètes capables de générer des QR Codes. Elles proposent souvent de nombreuses options : choix du niveau de correction d’erreur, personnalisation graphique, couleurs, logos, formes de modules, différents formats d’image, intégrations avec des frameworks, validation avancée, SVG, WebP, etc.
Ces fonctionnalités peuvent être très utiles dans certains projets.
Mais elles peuvent aussi représenter beaucoup plus que ce dont une application a réellement besoin.
C’est précisément de ce constat qu’est né LeanQR.
LeanQR est une petite bibliothèque PHP dédiée à la génération de QR Codes, conçue autour d’un objectif simple :
aller à l’essentiel.
Le projet ne cherche pas à concurrencer les bibliothèques les plus riches du marché en multipliant les fonctionnalités. Il cherche au contraire à proposer une solution légère, lisible, facile à intégrer et adaptée aux besoins les plus courants.
Son rôle est volontairement limité : recevoir une donnée, générer un QR Code valide et produire une image PNG directement exploitable.
Pourquoi créer LeanQR ?
LeanQR est né d’un besoin concret.
Dans plusieurs projets PHP, la génération d’un QR Code repose souvent sur une bibliothèque tierce importante alors que l’utilisation réelle se limite parfois à quelques opérations très simples :
- encoder une URL ;
- encoder une adresse email ;
- encoder un court texte ;
- afficher le QR Code dans une page HTML ;
- l’enregistrer dans un fichier PNG ;
- l’intégrer dans un PDF ;
- éventuellement afficher un petit label sous l’image.
Dans ce contexte, utiliser une bibliothèque très complète peut sembler disproportionné.
L’idée de LeanQR est donc de conserver uniquement le cœur fonctionnel nécessaire à ces usages.
Le projet suit une philosophie volontairement minimaliste :
- une API courte ;
- peu de classes ;
- pas de framework ;
- aucune dépendance externe pour l’algorithme QR ;
- sortie PNG ;
- fonctionnement avec PHP et GD ;
- installation possible avec Composer ;
- comportement prévisible ;
- code suffisamment compact pour pouvoir être compris et maintenu facilement.
Le nom LeanQR résume cette approche.
Le terme Lean évoque quelque chose de léger, épuré et débarrassé de ce qui n’est pas indispensable.
LeanQR n’essaie donc pas de tout faire.
Il essaie de faire peu de choses, mais de les faire simplement.
Une bibliothèque PHP compacte
L’architecture de LeanQR reste volontairement réduite.
Le cœur du projet repose sur quelques composants spécialisés :
LeanQR/
├── src/
│ ├── QrCode.php
│ ├── Encoder.php
│ └── PngRenderer.php
├── tests/
├── examples/
├── composer.json
├── README.md
└── LICENSE
La classe QrCode constitue l’interface principale destinée au développeur.
L’encodage du QR Code est pris en charge en interne par Encoder.
Enfin, PngRenderer transforme la matrice obtenue en image PNG à l’aide de l’extension GD de PHP.
Cette séparation permet de garder une API publique extrêmement simple tout en isolant la partie plus technique de l’algorithme QR.
Installation avec Composer
LeanQR est conçu pour être utilisé comme n’importe quelle bibliothèque PHP moderne.
Une fois le package publié sur Packagist, l’installation se fait simplement avec :
composer require crainios/leanqr
Composer installe alors le package et configure automatiquement son autoloading PSR-4.
Dans une application utilisant déjà Composer, il suffit ensuite de charger l’autoloader habituel :
require_once __DIR__.'/vendor/autoload.php';
Puis d’importer la classe :
use CrainiosLeanQrQrCode;LeanQR peut alors être utilisé immédiatement.
Générer un premier QR Code
Le cas le plus simple consiste à générer un QR Code puis à l’enregistrer dans un fichier.
use CrainiosLeanQrQrCode;
$qrcode = new QrCode();
$qrcode->save(
'https://example.com',
'qrcode.png'
);Le fichier qrcode.png contient alors le QR Code correspondant à l’adresse :
https://example.com
Il peut ensuite être affiché dans une page HTML :
La philosophie de LeanQR apparaît immédiatement : il n’est pas nécessaire de créer un writer, un objet de configuration, un objet couleur ou une structure complexe.
La classe reçoit simplement la donnée à encoder et produit le QR Code.
Ajouter un label
LeanQR permet également d’ajouter un texte facultatif sous le QR Code.
Par exemple :
$qrcode->save(
'https://example.com',
'qrcode.png',
'Visitez notre site'
);Le PNG généré contient alors le QR Code accompagné du texte :
Visitez notre site
Le label peut être utile pour préciser la fonction du QR Code :
Scannez-moi
ou :
Accéder au site
ou encore :
Voir le document
Il reste toutefois facultatif.
Si aucun label n’est fourni, LeanQR génère simplement un QR Code carré.
Générer le PNG directement en mémoire
L’une des fonctionnalités les plus pratiques de LeanQR est la méthode render().
Au lieu d’enregistrer immédiatement le QR Code dans un fichier, elle retourne directement les données binaires PNG.
$qrcode = new QrCode();
$png = $qrcode->render(
'https://example.com'
);La variable $png contient alors l’image complète.
Cette méthode permet de nombreuses utilisations sans création de fichier intermédiaire.
Afficher directement le QR Code dans une page HTML
Pour afficher une image générée à la volée dans une page HTML, on peut convertir le PNG en Base64.
$qrcode = new QrCode();
$png = $qrcode->render(
'https://example.com',
'Example'
);
$src = 'data:image/png;base64,'.base64_encode($png);Puis :
Il n’est donc pas nécessaire d’écrire l’image sur le disque.
Le QR Code est généré en mémoire puis directement intégré dans la page.
Cette méthode est particulièrement intéressante pour les applications dynamiques.
Utiliser une adresse email
LeanQR peut également être utilisé avec une adresse email.
$qrcode->save(
'contact@example.com',
'email.png',
'Contact'
);Une adresse email peut ainsi être encodée de manière adaptée pour être reconnue par les smartphones.
Une fois scanné, le QR Code peut permettre à l’utilisateur d’ouvrir rapidement son application de messagerie.
Encoder un simple texte
Un QR Code n’est pas limité aux URL.
LeanQR peut également encoder un court texte :
$qrcode->save(
'Bienvenue sur notre site',
'message.png'
);Cela permet par exemple d’utiliser LeanQR pour :
- transmettre une référence ;
- afficher un identifiant ;
- encoder une information courte ;
- fournir un numéro de dossier ;
- partager un texte avec un smartphone.
Régler la taille du QR Code
LeanQR utilise un système de scale.
Le QR Code est constitué d’une grille de petits carrés appelés modules.
Le scale définit le nombre de pixels utilisés pour dessiner chaque module.
Par exemple :
$qrcode = (new QrCode())
->setScale(10);
Une valeur plus élevée produit une image plus grande.
$qrcode->setScale(5);
produit un QR Code plus compact.
$qrcode->setScale(15);produit une image sensiblement plus grande.
Cette approche permet de conserver une image nette, puisque chaque module est dessiné directement sous forme de pixels pleins.
Régler la marge
La zone blanche située autour d’un QR Code est appelée quiet zone.
Elle est importante car elle permet aux scanners d’identifier correctement la limite du QR Code.
LeanQR permet de la régler avec :
$qrcode->setMargin(4);
La marge est exprimée en modules.
Une configuration typique peut donc être :
$qrcode = (new QrCode())
->setScale(10)
->setMargin(4);
Puis :
$png = $qrcode->render(
'https://example.com'
);Intégration dans un PDF
L’un des objectifs initiaux de LeanQR est de pouvoir générer des QR Codes destinés à être intégrés dans des documents PDF.
La méthode render() est particulièrement adaptée à cet usage puisqu’elle retourne directement le contenu PNG.
Selon la bibliothèque PDF utilisée, l’image peut être intégrée directement en mémoire ou en passant temporairement par un fichier.
Avec certaines bibliothèques anciennes, comme tFPDF, l’API Image() attend obligatoirement un nom de fichier.
Dans ce cas, on peut créer un fichier temporaire :
$qrcode = (new QrCode())
->setScale(10)
->setMargin(4);
$png = $qrcode->render(
'https://example.com'
);
$tmpQr = tempnam(
sys_get_temp_dir(),
'leanqr_'
);
file_put_contents(
$tmpQr,
$png
);
$pdf->Image(
$tmpQr,
98,
214,
35,
35,
'PNG'
);
unlink($tmpQr);Le fichier n’existe alors que quelques instants.
Il est créé dans le répertoire temporaire du système, utilisé par la bibliothèque PDF puis immédiatement supprimé.
Ajouter un texte sous le QR Code dans un PDF
Lorsqu’un QR Code est destiné à un PDF, il peut être préférable de générer le QR Code sans label puis d’utiliser directement le moteur de texte du PDF.
Par exemple :
$qrcode = (new QrCode())
->setScale(10)
->setMargin(4);
$png = $qrcode->render(
$url
);
Puis après insertion de l’image :
$pdf->SetFont('Arial', '', 8);
$pdf->SetTextColor(255, 0, 0);
$pdf->SetXY(83, 250);
$pdf->Cell(
65,
5,
'Scannez-moi pour payer par CB',
0,
0,
'C'
);
$pdf->SetTextColor(0, 0, 0);Cette méthode présente plusieurs avantages.
Le QR Code reste parfaitement carré, tandis que le label utilise les capacités typographiques natives du PDF.
Le texte reste donc vectoriel, parfaitement net et facilement personnalisable.
Une implémentation QR autonome
Même si l’API de LeanQR est très simple, la génération d’un véritable QR Code ne consiste pas uniquement à dessiner des carrés noirs et blancs.
LeanQR effectue en interne plusieurs opérations nécessaires à la construction d’un QR Code valide :
- analyse des données ;
- encodage en mode Byte ;
- génération des codewords ;
- calcul de la correction Reed-Solomon ;
- construction de la matrice ;
- insertion des motifs de positionnement ;
- insertion des motifs de synchronisation ;
- placement des données ;
- application des masques ;
- calcul du masque optimal ;
- génération des informations de format ;
- production de la matrice finale.
L’utilisateur n’a toutefois pas besoin d’interagir avec ces mécanismes.
Ils restent volontairement cachés derrière une API minimale.
C’est un des principes fondamentaux de LeanQR :
la complexité nécessaire doit rester à l’intérieur de la bibliothèque.
QR Code Model 2
LeanQR génère des QR Codes basés sur le format standard QR Code Model 2.
Il s’agit du type de QR Code aujourd’hui utilisé dans l’immense majorité des applications.
La bibliothèque est volontairement centrée sur un sous-ensemble pratique du standard afin de conserver une implémentation compacte.
LeanQR privilégie les besoins habituels des applications web :
- URL ;
- email ;
- texte court ;
- chaînes UTF-8 ;
- QR Codes destinés à être affichés ou imprimés.
Cette limitation volontaire fait partie de la philosophie du projet.
PNG comme format principal
LeanQR produit actuellement des images PNG.
Ce choix est volontaire.
Le PNG présente plusieurs avantages :
- il est supporté par tous les navigateurs ;
- il est directement exploitable dans une balise
;
- il peut être intégré dans la plupart des bibliothèques PDF ;
- il ne provoque aucune perte de qualité ;
- il est parfaitement adapté à une image composée de zones noires et blanches ;
- il est pris en charge nativement par GD.
LeanQR ne cherche donc pas à multiplier les formats de sortie.
SVG, WebP, EPS ou autres formats peuvent être intéressants dans certains projets, mais ne sont pas indispensables à l’objectif principal de la bibliothèque.
Dépendances réduites
LeanQR ne dépend pas d’une autre bibliothèque de génération QR.
Le package nécessite simplement PHP ainsi que l’extension GD pour produire l’image PNG.
Cette approche présente plusieurs avantages.
Il y a moins de packages à installer.
Il y a moins de dépendances transitives.
Les mises à jour sont plus faciles à suivre.
Le fonctionnement général reste compréhensible.
Et surtout, le projet conserve une empreinte réduite.
Cette caractéristique est particulièrement intéressante pour les applications PHP traditionnelles, les CMS propriétaires ou les projets dans lesquels on souhaite limiter le nombre de bibliothèques externes.
Une API volontairement limitée
LeanQR ne cherche pas à proposer des dizaines de paramètres.
L’utilisation habituelle reste proche de ceci :
$qrcode = (new QrCode())
->setScale(10)
->setMargin(4);
$qrcode->save(
'https://example.com',
'qrcode.png',
'Example'
);Ou :
$png = $qrcode->render(
'https://example.com'
);C’est volontaire.
Une bibliothèque légère perdrait une grande partie de son intérêt si elle finissait par accumuler des dizaines d’options rarement utilisées.
Ce que LeanQR ne cherche pas à faire
LeanQR assume également clairement ses limites.
Le projet n’a pas pour objectif de devenir un studio graphique de QR Codes.
Il ne cherche pas à proposer toutes les possibilités de personnalisation disponibles dans certaines bibliothèques spécialisées.
LeanQR privilégie :
donnée → QR Code → PNG
plutôt que :
donnée
→ configuration avancée
→ logo
→ formes personnalisées
→ couleurs
→ dégradés
→ effets graphiques
→ nombreux formats
→ multiples renderers
→ QR Code
Cette différence de philosophie est essentielle.
LeanQR n’est pas destiné à remplacer toutes les bibliothèques QR existantes.
Il constitue une alternative lorsque les besoins sont simples.
Pourquoi ne pas intégrer de logo ?
Certaines bibliothèques permettent d’insérer une image ou un logo au centre du QR Code.
LeanQR ne propose volontairement pas cette fonctionnalité dans son cœur initial.
Un logo masque nécessairement une partie des modules du QR Code et dépend donc fortement du niveau de correction d’erreur.
Cela complexifie également le rendu et introduit davantage de paramètres.
Pour une bibliothèque qui vise principalement la fiabilité et la simplicité, un QR Code noir sur fond blanc reste la solution la plus robuste.
Le projet peut naturellement évoluer avec le temps, mais chaque nouvelle fonctionnalité doit rester compatible avec sa philosophie initiale.
LeanQR et les applications PHP existantes
LeanQR est particulièrement adapté aux projets PHP existants qui utilisent déjà Composer.
Il peut facilement être intégré à :
- un CMS ;
- une application métier ;
- une interface d’administration ;
- un générateur de factures ;
- un système de paiement ;
- un gestionnaire documentaire ;
- une application associative ;
- un extranet ;
- un générateur de tickets ;
- un système d’identification.
Il n’impose aucun framework.
Il peut donc être utilisé aussi bien avec du PHP classique qu’au sein d’une architecture plus importante.
Exemple dans une application existante
Une intégration peut se limiter à quelques lignes :
use CrainiosLeanQrQrCode;
$qrcode = (new QrCode())
->setScale(8)
->setMargin(4);
$png = $qrcode->render(
$url,
$label ?: null
);
$src = 'data:image/png;base64,'.base64_encode($png);Puis :
Il n’est pas nécessaire de modifier l’architecture générale du projet.
LeanQR se comporte simplement comme un composant supplémentaire.
Un projet open source
LeanQR est destiné à être publié sur GitHub et distribué via Composer.
Le projet utilise une licence permissive afin de faciliter sa réutilisation dans différents types d’applications.
Le dépôt GitHub permet également de suivre son évolution, consulter le code source, proposer des améliorations ou signaler d’éventuels problèmes.
L’objectif est de conserver un projet suffisamment petit pour que son fonctionnement puisse être examiné facilement.
Cette transparence est également un avantage pour les développeurs qui souhaitent comprendre réellement ce qu’ils intègrent dans leurs applications.
Une première version volontairement stable et sobre
La version 1.0.0 de LeanQR marque une première API stable.
Le choix d’une version 1.0 signifie que les fonctionnalités principales sont considérées comme suffisamment abouties pour une utilisation normale.
Cela ne signifie pas que LeanQR ne pourra plus évoluer.
Mais les évolutions futures devront conserver deux principes :
simplicité et compatibilité.
Une fonctionnalité ne devrait être ajoutée que si elle apporte une réelle valeur sans transformer LeanQR en bibliothèque généraliste complexe.
Une alternative, pas un remplacement universel
LeanQR n’a pas vocation à remplacer systématiquement des solutions comme Endroid QR Code ou d’autres bibliothèques plus complètes.
Ces projets restent parfaitement adaptés lorsqu’une application a besoin de fonctionnalités avancées.
LeanQR répond simplement à une autre problématique.
Lorsqu’un projet a uniquement besoin de générer quelques QR Codes propres et standards, importer une bibliothèque extrêmement complète peut ne pas être nécessaire.
LeanQR occupe donc volontairement cet espace :
le QR Code utile, sans le superflu.
En résumé
LeanQR est une bibliothèque PHP légère destinée à générer rapidement des QR Codes standards.
Elle permet notamment :
- d’encoder une URL ;
- d’encoder une adresse email ;
- d’encoder un court texte ;
- d’ajouter un label facultatif ;
- de générer une image PNG ;
- de récupérer directement cette image en mémoire ;
- de l’afficher dans une page HTML ;
- de l’intégrer dans un document PDF ;
- de régler simplement l’échelle et la marge ;
- de l’installer avec Composer.
Son utilisation tient généralement en quelques lignes :
use CrainiosLeanQrQrCode;
$qrcode = (new QrCode())
->setScale(10)
->setMargin(4);
$qrcode->save(
'https://example.com',
'qrcode.png',
'Example'
);Ou, pour une génération en mémoire :
$png = $qrcode->render(
'https://example.com'
);LeanQR suit ainsi une idée simple : lorsqu’un besoin est simple, son outil peut l’être également.
Pas de framework.
Pas de configuration interminable.
Pas de fonctionnalités ajoutées uniquement pour allonger la liste des possibilités.
Seulement ce qui est nécessaire pour générer un QR Code proprement en PHP.
LeanQR : lightweight QR Code generation for PHP.