Guides de migration

Les recipes et guides apparaissent ici au fur et à mesure de leur publication par les dépôts en amont. Cette page est un index de routage pour le contenu rédigé dans les dépôts source (nextpdf, nextpdf-Laravel, nextpdf-Symfony, et les autres packages de l'écosystème). Pour la documentation disponible aujourd'hui, consulte Insider_ (35 articles, les 17 langues) ou Choisir une intégration.

Guides de migration

NextPDF est un moteur PDF 2.0 pour PHP. Si tu génères déjà des PDF avec une autre bibliothèque, un guide de migration mappe l’API de cette bibliothèque vers NextPDF et documente les différences de comportement que tu rencontreras. Cette page est l’index inter-dépôts : elle indique depuis quelle bibliothèque chaque guide te fait migrer, quel dépôt en est propriétaire, et le modèle commun à tous les guides.

Comme cette page est un index, elle n’affirme rien sur le comportement d’un guide en particulier. Chaque guide appartient à son propre dépôt. L’agrégateur l’intègre à ce site, et tant qu’un guide n’est pas publié, le lien ci-dessous pointe vers un espace réservé. Toute affirmation sur le comportement se trouve dans le guide lui-même, étayée par un test dans le dépôt ou par une clause ISO 32000-2 / CSS WG épinglée — pas ici.

Le seul modèle de migration

Chaque guide de migration NextPDF partage le même modèle honnête, et tu dois lire chaque guide en le gardant à l’esprit :

• Compatible avec, et non strictement identique. NextPDF et la bibliothèque que tu quittes sont des implémentations indépendantes. Après migration, le document reste fonctionnellement équivalent dans l’intention, mais il n’est pas identique au pixel ou à l’octet près. Aucun des guides ne revendique un remplacement direct ni une compatibilité à 100 %.
• La couverture est un nombre mesuré, pas une affirmation. Lorsqu’un guide annonce un chiffre de couverture (par exemple l’adaptateur TCPDF), ce chiffre est une métrique de complétude fonctionnelle tirée d’une matrice présente dans le dépôt, au sens de la clause 43 de la norme ISO/IEC 25023 — un nombre mesuré de méthodes couvertes, pas une garantie globale.
• Chaque guide énonce ouvertement ses différences de comportement. Chaque guide comporte un tableau explicite des différences et une section « non pris en charge / pas d’équivalent direct ». Une différence est une propriété documentée du moteur, pas un défaut.
• Un changement de moteur de rendu impose une nouvelle revue. Migrer, c’est un changement de code plus une nouvelle référence de sortie. Chaque guide décrit comment tester la migration ; la validation visuelle se fait document par document et relève de la responsabilité de l’intégrateur.

Les formes de migration

Les guides se répartissent en deux formes. La forme t’indique l’ampleur des changements de code.

• Les migrations par réécriture d’API n’ont aucun shim (couche de compatibilité) : chaque site d’appel est réécrit à l’aide du mappage de verbes et du mappage d’options du guide. Les migrations depuis les bibliothèques HTML-vers-PDF (dompdf, mpdf) relèvent de cette forme — elles ciblent directement le pipeline Html de NextPDF.
• Les migrations « drop-in-then-migrate » livrent un adaptateur quasi compatible au niveau du code source, si bien que la première étape est un remplacement de dépendance minimal. À partir de là, tu migres progressivement les sites d’appel vers l’API moderne, puis tu retires l’adaptateur. La migration TCPDF relève de cette forme, via l’adaptateur nextpdf/compat-legacy.

Référence des guides et de leurs dépôts propriétaires

Chaque guide ci-dessous vit dans le docs/public/ du dépôt propriétaire, et l’agrégateur l’intègre à ce site. Le dépôt propriétaire fait autorité pour les affirmations de comportement de ce guide ; cet index ne consigne que le routage.

Depuis	Guide	Forme	Dépôt propriétaire	Page
Dompdf	Dompdf → pipeline Html de NextPDF	Réécriture d’API	nextpdf (cœur)	Guide Dompdf dompdf (prévu en amont)
mPDF	mPDF → cœur NextPDF	Réécriture d’API	nextpdf (cœur)	Guide mPDF mpdf (prévu en amont)
TCPDF 6.x	TCPDF → NextPDF via l’adaptateur compat-legacy	Drop-in-then-migrate	nextpdf-compat-tcpdf (dépôt), package nextpdf/compat-legacy	Guide TCPDF tcpdf-compat (prévu en amont)

Les guides dompdf et mpdf se trouvent dans le dépôt du cœur parce qu’ils ciblent les API du moteur principal, et les examples/ du cœur les étayent. Le guide tcpdf-compat vit dans le dépôt compat-tcpdf parce que le package nextpdf/compat-legacy est propriétaire de la surface comportementale TCPDF et des tests d’adaptateur qui étayent le guide. Cet index vit nativement dans les docs parce qu’il couvre plusieurs dépôts, et il ne fait aucune affirmation sur leur comportement.

À quoi sert chaque guide

• Dompdf → NextPDF (dompdf (prévu en amont)) — pour les bases de code qui utilisent dompdf/dompdf côté serveur. Il mappe loadHtml/render/output et les clés Options sur le pipeline Html de NextPDF, et rattache les attentes en matière de fonctionnalités CSS à la matrice de prise en charge CSS « Verified-only ». Il n’y a pas de shim de classe Dompdf ; chaque site d’appel est réécrit.
• mPDF → NextPDF (mpdf (prévu en amont)) — pour les bases de code qui utilisent mpdf/mpdf. Il mappe WriteHTML/Output/AddPage et le tableau de configuration du constructeur sur l’API du cœur, avec un écart de gestion des polices : NextPDF résout les polices via un seul répertoire de polices plus une correspondance CSS, et crée toujours des sous-ensembles de polices. Pas de shim de classe Mpdf.
• TCPDF → NextPDF (compat-legacy) (tcpdf-compat (prévu en amont)) — pour les bases de code TCPDF 6.x qui veulent minimiser le changement initial. Installe l’adaptateur, audite ta surface réelle en mode strict par rapport à la matrice de couverture présente dans le dépôt, migre les sites d’appel hors de l’adaptateur, puis ajoute par-dessus une structure balisée PDF/UA-2 — une capacité que TCPDF n’a jamais eue. L’adaptateur est un échafaudage, pas la destination, et pas une garantie de remplacement direct.

Comment les liens des guides se résolvent

Chaque espace réservé [[…]] ci-dessus est une référence anticipée vers une page qui vit dans le dépôt propriétaire sous docs/public/migration/, et l’agrégateur l’intègre à ce site. Les slugs cibles suivent une seule convention :

/migration/<source>/

Le jeton <source> est le nom court de la bibliothèque depuis laquelle tu migres : l’un de dompdf, mpdf ou tcpdf-compat, comme indiqué dans le tableau de référence des guides ci-dessus. Tant qu’une page cible n’est pas agrégée, son lien est un espace réservé et ne se résout pas. Cet index ne fait aucune affirmation de comportement sur quelque guide cible que ce soit ; il ne consigne que le routage et le modèle de migration partagé.

Voir aussi

• Matrice de prise en charge CSS — l’autorité « Verified-only » à laquelle les guides dompdf et mpdf rattachent leurs attentes en matière de fonctionnalités CSS.
• Cookbook Intégrations — l’index inter-dépôts des packages d’intégration de l’écosystème (une préoccupation différente : connecter le moteur, et non migrer vers lui).