BCard - Documentation technique

QRCodeService
in package

Génère, régénère, sert au téléchargement et supprime les QR codes des cartes de visite.

Le service s'appuie sur la bibliothèque endroid/qr-code (writers PNG, JPEG et SVG, encodage UTF-8, libellé optionnel en police NotoSans) et écrit les images produites dans le répertoire désigné par le paramètre de conteneur qrcode_directory, créé à la volée si nécessaire. Chaque fichier reçoit un nom rendu unique par uniqid(), ce qui impose de supprimer explicitement l'ancien fichier lors d'une régénération. Les méthodes de génération capturent leurs exceptions, les journalisent via error_log() et retournent null plutôt que de propager l'erreur.

Table of Contents

Properties

$parameterBag  : ParameterBagInterface

Methods

__construct()  : mixed
deleteQRCode()  : bool
Supprime un QR code du système de fichiers
downloadQRCode()  : BinaryFileResponse|null
Télécharge un QR code dans le format spécifié
generateQRCode()  : string|null
Génère un QR code pour une carte de visite avec options personnalisables
generateQRCodeByHash()  : string|null
Génère un QR code basé sur le hash public
regenerateQRCode()  : string|null
Régénère un QR code existant
regenerateQRCodeByHash()  : string|null
Régénère un QR code existant basé sur le hash public
createSlug()  : string
Crée un slug URL-friendly à partir d'une chaîne de caractères

Properties

Methods

__construct()

public __construct(ParameterBagInterface $parameterBag) : mixed
Parameters
$parameterBag : ParameterBagInterface

Accès aux paramètres du conteneur, notamment qrcode_directory où sont stockées les images générées.

deleteQRCode()

Supprime un QR code du système de fichiers

public deleteQRCode(string|null $qrCodePath) : bool

Tolérante par conception : un chemin null ou un fichier déjà absent est traité comme un succès. Effet de bord : suppression physique du fichier dans qrcode_directory. Aucune mise à jour de l'entité correspondante n'est effectuée.

Parameters
$qrCodePath : string|null

Nom du fichier à supprimer, ou null pour ne rien faire.

Return values
bool —

true si le fichier a été supprimé, était absent ou si aucun chemin n'était fourni ; false si unlink() a échoué.

downloadQRCode()

Télécharge un QR code dans le format spécifié

public downloadQRCode(string $qrCodePath[, string $format = 'png' ]) : BinaryFileResponse|null

Construit une réponse binaire en pièce jointe pointant sur le fichier stocké dans qrcode_directory, nommée qrcode.{format} côté client. Le paramètre $format n'agit que sur le nom proposé au téléchargement : aucune conversion d'image n'est réalisée, le contenu servi reste celui du fichier existant.

Parameters
$qrCodePath : string

Nom du fichier de QR code, relatif à qrcode_directory.

$format : string = 'png'

Extension utilisée dans le nom du fichier téléchargé.

Return values
BinaryFileResponse|null —

Réponse de téléchargement, ou null si le fichier est introuvable sur le disque.

generateQRCode()

Génère un QR code pour une carte de visite avec options personnalisables

public generateQRCode(string $baseUrl, int $cardId, string $firstName, string $lastName[, string $companyName = '' ][, string $position = '' ][, array<string, mixed> $options = [] ]) : string|null

L'URL encodée est construite selon les données disponibles : si l'entreprise et le poste produisent tous deux un slug non vide et que l'option simple_format est activée, le format {baseUrl}/card/{entreprise}/{id}/{poste} est utilisé ; à défaut de slugs exploitables, un repli {baseUrl}/{id}/{prénom}/{nom} est appliqué avec les noms encodés par urlencode(). Attention : lorsque les deux slugs sont présents mais que simple_format est absent ou faux, aucune branche n'affecte $url, la génération échoue alors et la méthode retourne null.

Les options sont fusionnées avec les valeurs par défaut size 300, margin 10, format png, labelText « SCAN ME » et labelFontSize 20 ; un labelText vide supprime le libellé. Effets de bord : création éventuelle du répertoire qrcode_directory (mode 0755, récursif) et écriture du fichier image.

Parameters
$baseUrl : string

Base d'URL utilisée pour composer le lien encodé.

$cardId : int

Identifiant de la carte, repris dans l'URL et le nom de fichier.

$firstName : string

Prénom, utilisé uniquement par le format de repli.

$lastName : string

Nom, utilisé uniquement par le format de repli.

$companyName : string = ''

Raison sociale, transformée en slug pour le format simplifié.

$position : string = ''

Intitulé de poste, transformé en slug pour le format simplifié.

$options : array<string, mixed> = []

Options de rendu : simple_format, size, margin, format (png, jpg/jpeg, svg), labelText, labelFontSize.

Return values
string|null —

Nom du fichier généré (sans chemin), ou null si une exception est survenue — elle est alors journalisée via error_log() et non propagée.

generateQRCodeByHash()

Génère un QR code basé sur le hash public

public generateQRCodeByHash(string $baseUrl, string $hash[, string $companyName = '' ][, string $position = '' ][, array<string, mixed> $options = [] ]) : string|null

Variante de self::generateQRCode() qui encode le hash public de la carte plutôt que son identifiant numérique, évitant ainsi d'exposer une clé primaire. La base d'URL est normalisée (suppression de la barre oblique finale) et un éventuel segment /bcard terminal est retiré pour obtenir la racine du site utilisée par le format simplifié. Trois formes d'URL sont possibles, par ordre de priorité : {racine}/card/{entreprise}/{hash}/{poste} lorsque simple_format (activé par défaut ici) et les deux slugs sont disponibles ; {baseUrl}/{hash}/{prénom}/{nom} si au moins un des slugs de nom issus des options first_name / last_name est renseigné ; sinon {baseUrl}/{hash}.

Mêmes options de rendu et mêmes effets de bord que self::generateQRCode() : création éventuelle du répertoire et écriture du fichier image.

Parameters
$baseUrl : string

Base d'URL, dont le suffixe /bcard est retiré pour le format simplifié.

$hash : string

Hash public identifiant la carte.

$companyName : string = ''

Raison sociale, transformée en slug.

$position : string = ''

Intitulé de poste, transformé en slug.

$options : array<string, mixed> = []

Options de rendu, plus first_name et last_name employés par le format intermédiaire ; simple_format vaut true par défaut.

Return values
string|null —

Nom du fichier généré (sans chemin), ou null si une exception est survenue — elle est alors journalisée via error_log() et non propagée.

regenerateQRCode()

Régénère un QR code existant

public regenerateQRCode(string $baseUrl, int $cardId, string $firstName, string $lastName[, string|null $oldQrCodePath = null ][, array<string, mixed> $options = [] ][, string $companyName = '' ][, string $position = '' ]) : string|null

Supprime physiquement l'ancien fichier dans qrcode_directory s'il est fourni et existe, puis délègue la création du nouveau à self::generateQRCode(). La suppression a lieu avant la génération : si celle-ci échoue et retourne null, la carte se retrouve sans image de QR code.

Parameters
$baseUrl : string

Base d'URL utilisée pour composer le lien encodé.

$cardId : int

Identifiant de la carte.

$firstName : string

Prénom, utilisé par le format de repli.

$lastName : string

Nom, utilisé par le format de repli.

$oldQrCodePath : string|null = null

Nom de l'ancien fichier à supprimer, ou null pour n'en supprimer aucun.

$options : array<string, mixed> = []

Options de rendu, voir self::generateQRCode().

$companyName : string = ''

Raison sociale, transformée en slug.

$position : string = ''

Intitulé de poste, transformé en slug.

Return values
string|null —

Nom du nouveau fichier, ou null en cas d'échec de la génération.

regenerateQRCodeByHash()

Régénère un QR code existant basé sur le hash public

public regenerateQRCodeByHash(string $baseUrl, string $hash[, string|null $oldQrCodePath = null ][, array<string, mixed> $options = [] ][, string $companyName = '' ][, string $position = '' ]) : string|null

Pendant de self::regenerateQRCode() pour les cartes identifiées par leur hash public : suppression physique préalable de l'ancien fichier s'il existe, puis appel à self::generateQRCodeByHash(). Ici encore, un échec de génération laisse la carte sans image.

Parameters
$baseUrl : string

Base d'URL utilisée pour composer le lien encodé.

$hash : string

Hash public identifiant la carte.

$oldQrCodePath : string|null = null

Nom de l'ancien fichier à supprimer, ou null pour n'en supprimer aucun.

$options : array<string, mixed> = []

Options de rendu, voir self::generateQRCodeByHash().

$companyName : string = ''

Raison sociale, transformée en slug.

$position : string = ''

Intitulé de poste, transformé en slug.

Return values
string|null —

Nom du nouveau fichier, ou null en cas d'échec de la génération.

createSlug()

Crée un slug URL-friendly à partir d'une chaîne de caractères

private createSlug(string $text) : string

Passe le texte en minuscules, translittère les caractères accentués en ASCII via iconv(), remplace toute suite de caractères non alphanumériques par un tiret unique, puis élague les tirets de début et de fin. Une chaîne ne contenant aucun caractère alphanumérique produit une chaîne vide, ce qui fait basculer les méthodes de génération vers leurs formats d'URL de repli.

Parameters
$text : string

Texte source, typiquement une raison sociale ou un intitulé de poste.

Return values
string —

Slug en minuscules composé de lettres, chiffres et tirets ; potentiellement vide.


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results