emogrifier
V7.3.0: Add support for PHP 8.4 and CSS custom properties
N. e•mog•ri•fi•er [ē-'mä-grƏ-,fī-Ər] - utilitas untuk mengubah sepenuhnya sifat atau tampilan email HTML, khususnya. dengan cara yang sangat fantastis atau aneh
Emogrifier mengubah gaya CSS menjadi atribut gaya sebaris dalam kode HTML Anda. Hal ini memastikan tampilan yang tepat pada pembaca email dan perangkat seluler yang tidak memiliki dukungan stylesheet.
Utilitas ini dikembangkan sebagai bagian dari Interval untuk menangani masalah yang ditimbulkan oleh klien email tertentu (yaitu Outlook 2007 dan GoogleMail) dalam hal cara mereka menangani gaya yang terkandung dalam email HTML. Seperti yang sudah diketahui oleh banyak pengembang dan desainer web, klien email tertentu terkenal karena kurangnya dukungan CSS. Meskipun upaya sedang dilakukan untuk mengembangkan standar email umum, penerapannya masih jauh dari kenyataan.
Masalah utama dengan klien email yang tidak kooperatif adalah sebagian besar cenderung hanya menganggap CSS sebaris, membuang semua elemen <style> dan link ke stylesheet di elemen <link> . Emogrifier memecahkan masalah ini dengan mengubah gaya CSS menjadi atribut gaya sebaris dalam kode HTML Anda.
Emogrifier secara otomatis mentransogrifikasi HTML Anda dengan menguraikan CSS Anda dan memasukkan definisi CSS Anda ke dalam tag dalam HTML Anda berdasarkan pemilih CSS Anda.
Untuk menginstal emogrifier, tambahkan pelago/emogrifier ke bagian require di composer.json proyek Anda, atau Anda dapat menggunakan composer seperti di bawah ini:
composer require pelago/emogrifierLihat https://getcomposer.org/ untuk informasi dan dokumentasi lebih lanjut.
Cara paling dasar untuk menggunakan kelas CssInliner adalah membuat instance dengan HTML asli, menyejajarkan CSS eksternal, lalu mendapatkan kembali HTML yang dihasilkan:
use Pelago Emogrifier CssInliner ;
…
$ visualHtml = CssInliner:: fromHtml ( $ html )-> inlineCss ( $ css )-> render (); Jika tidak ada file CSS eksternal dan semua CSS terletak di dalam elemen <style> di HTML, Anda dapat menghilangkan parameter $css :
$ visualHtml = CssInliner:: fromHtml ( $ html )-> inlineCss ()-> render (); Jika Anda hanya ingin mendapatkan kembali konten elemen <body> dan bukan seluruh dokumen HTML, Anda dapat menggunakan metode renderBodyContent sebagai gantinya:
$ bodyContent = $ visualHtml = CssInliner:: fromHtml ( $ html )-> inlineCss ()
-> renderBodyContent ();Jika Anda ingin mengubah proses inlining dengan salah satu opsi yang tersedia, Anda perlu memanggil metode yang sesuai sebelum melakukan inlining CSS. Kodenya kemudian akan terlihat seperti ini:
$ visualHtml = CssInliner:: fromHtml ( $ html )-> disableStyleBlocksParsing ()
-> inlineCss ( $ css )-> render (); Ada juga beberapa kelas pemrosesan HTML lain yang tersedia (semuanya merupakan subkelas dari AbstractHtmlProcessor ) yang dapat Anda gunakan untuk mengubah HTML lebih lanjut setelah memasukkan CSS. (Untuk detail lebih lanjut mengenai kelas-kelas tersebut, silakan lihat bagian di bawah ini.) CssInliner dan semua kelas pemrosesan HTML dapat berbagi instance DOMDocument yang sama untuk dikerjakan:
use Pelago Emogrifier CssInliner ;
use Pelago Emogrifier HtmlProcessor CssToAttributeConverter ;
use Pelago Emogrifier HtmlProcessor HtmlPruner ;
…
$ cssInliner = CssInliner:: fromHtml ( $ html )-> inlineCss ( $ css );
$ domDocument = $ cssInliner -> getDomDocument ();
HtmlPruner:: fromDomDocument ( $ domDocument )-> removeElementsWithDisplayNone ()
-> removeRedundantClassesAfterCssInlined ( $ cssInliner );
$ finalHtml = CssToAttributeConverter:: fromDomDocument ( $ domDocument )
-> convertCssToVisualAttributes ()-> render (); Kelas HtmlNormalizer menormalkan HTML yang diberikan dengan cara berikut:
Kelas dapat digunakan seperti ini:
use Pelago Emogrifier HtmlProcessor HtmlNormalizer ;
…
$ cleanHtml = HtmlNormalizer:: fromHtml ( $ rawHtml )-> render (); CssToAttributeConverter mengonversi beberapa nilai atribut gaya menjadi atribut visual HTML. Hal ini memungkinkan untuk mendapatkan setidaknya sedikit gaya visual untuk klien email yang tidak mendukung CSS dengan baik. Misalnya, style="width: 100px" akan dikonversi menjadi width="100" .
Kelas dapat digunakan seperti ini:
use Pelago Emogrifier HtmlProcessor CssToAttributeConverter ;
…
$ visualHtml = CssToAttributeConverter:: fromHtml ( $ rawHtml )
-> convertCssToVisualAttributes ()-> render (); Anda juga dapat membuat CssToAttributeConverter berfungsi pada DOMDocument :
$ visualHtml = CssToAttributeConverter:: fromDomDocument ( $ domDocument )
-> convertCssToVisualAttributes ()-> render (); Kelas CssVariableEvaluator dapat digunakan untuk menerapkan nilai variabel CSS yang ditentukan dalam atribut gaya sebaris ke properti gaya sebaris yang menggunakannya.
Misalnya, CSS berikut mendefinisikan dan menggunakan properti khusus:
: root {
--text-color : green;
}
p {
color : var ( --text-color );
} Setelah CssInliner menggariskan CSS tersebut pada HTML (yang dibuat) <html><body><p></p></body></html> , akan terlihat seperti ini:
< html style =" --text-color: green; " >
< body >
< p style =" color: var(--text-color); " >
< p >
</ body >
</ html > Metode CssVariableEvaluator evaluateVariables akan menerapkan nilai --text-color sehingga atribut style paragraf menjadi color: green; .
Ini dapat digunakan seperti ini:
use Pelago Emogrifier HtmlProcessor CssVariableEvaluator ;
…
$ evaluatedHtml = CssVariableEvaluator:: fromHtml ( $ html )
-> evaluateVariables ()-> render (); Anda juga dapat membuat CssVariableEvaluator berfungsi pada DOMDocument :
$ evaluatedHtml = CssVariableEvaluator:: fromDomDocument ( $ domDocument )
-> evaluateVariables ()-> render (); Kelas HtmlPruner dapat mengurangi ukuran HTML dengan menghapus elemen dengan deklarasi gaya display: none , dan/atau menghapus kelas dari atribut class yang tidak diperlukan.
Ini dapat digunakan seperti ini:
use Pelago Emogrifier HtmlProcessor HtmlPruner ;
…
$ prunedHtml = HtmlPruner:: fromHtml ( $ html )-> removeElementsWithDisplayNone ()
-> removeRedundantClasses ( $ classesToKeep )-> render (); Metode removeRedundantClasses menerima daftar nama kelas yang diizinkan yang harus dipertahankan. Jika ini adalah langkah pasca-pemrosesan setelah memasukkan CSS, Anda juga dapat menggunakan removeRedundantClassesAfterCssInlined , dengan meneruskan instance CssInliner yang telah memasukkan CSS ke dalamnya (dan membuat HtmlPruner berfungsi di DOMDocument ). Ini akan menggunakan informasi dari CssInliner untuk menentukan kelas mana yang masih diperlukan (yaitu kelas yang digunakan dalam aturan uninlinable yang telah disalin ke elemen <style> ):
$ prunedHtml = HtmlPruner:: fromDomDocument ( $ cssInliner -> getDomDocument ())
-> removeElementsWithDisplayNone ()
-> removeRedundantClassesAfterCssInlined ( $ cssInliner )-> render (); Metode removeElementsWithDisplayNone tidak akan menghapus elemen apa pun yang memiliki kelas -emogrifier-keep . Jadi jika, misalnya, ada elemen yang secara default memiliki display: none tetapi diungkapkan oleh aturan @media , atau yang dimaksudkan sebagai preheader, Anda dapat menambahkan kelas tersebut ke elemen tersebut. Paragraf dalam cuplikan HTML ini tidak akan dihapus meskipun memiliki display: none (yang mungkin telah diterapkan oleh CssInliner::inlineCss() dari aturan CSS .preheader { display: none; } ):
< p class =" preheader -emogrifier-keep " style =" display: none; " >
Hello World!
</ p > Metode removeRedundantClassesAfterCssInlined (atau removeRedundantClasses ), jika dipanggil setelah removeElementsWithDisplayNone , akan menghapus kelas -emogrifier-keep .
Ada beberapa opsi yang dapat Anda atur pada instance CssInliner sebelum memanggil metode inlineCss :
->disableStyleBlocksParsing() - Secara default, CssInliner akan mengambil semua blok <style> di HTML dan akan menerapkan gaya CSS sebagai atribut "gaya" sebaris ke HTML. Blok <style> kemudian akan dihapus dari HTML. Jika Anda ingin menonaktifkan fungsi ini sehingga CssInliner meninggalkan blok <style> ini di HTML dan tidak menguraikannya, Anda harus menggunakan opsi ini. Jika Anda menggunakan opsi ini, konten blok <style> tidak akan diterapkan sebagai gaya sebaris dan CSS apa pun yang Anda ingin CssInliner gunakan harus diteruskan seperti yang dijelaskan di bagian Penggunaan di atas.->disableInlineStyleAttributesParsing() - Secara default, CssInliner mempertahankan semua atribut "style" pada tag di HTML yang Anda berikan padanya. Namun jika Anda ingin membuang semua gaya inline yang ada di HTML sebelum CSS diterapkan, Anda harus menggunakan opsi ini.->addAllowedMediaType(string $mediaName) - Secara default, CssInliner hanya akan menyimpan tipe media all , screen dan print . Jika Anda ingin menyimpan beberapa lainnya, Anda dapat menggunakan metode ini untuk mendefinisikannya.->removeAllowedMediaType(string $mediaName) - Anda dapat menggunakan metode ini untuk menghapus jenis media yang disimpan oleh Emogrifier.->addExcludedSelector(string $selector) - Menjaga elemen agar tidak terpengaruh oleh inlining CSS. Perhatikan bahwa hanya elemen yang cocok dengan pemilih yang disediakan yang akan dikecualikan dari sebaris CSS, belum tentu turunannya. Jika Anda ingin mengecualikan seluruh subpohon, Anda harus menyediakan pemilih yang akan cocok dengan semua elemen dalam subpohon, misalnya dengan menggunakan pemilih universal: $ cssInliner -> addExcludedSelector ( ' .message-preview ' );
$ cssInliner -> addExcludedSelector ( ' .message-preview * ' );->addExcludedCssSelector(string $selector) - Bertentangan dengan addExcludedSelector , yang mengecualikan node HTML, metode ini mengecualikan penyeleksi CSS agar tidak dimasukkan. Misalnya, ini berguna jika Anda tidak ingin aturan penyetelan ulang CSS Anda disisipkan pada setiap node HTML (misalnya * { margin: 0; padding: 0; font-size: 100% } ). Perhatikan bahwa penyeleksi ini harus sama persis dengan penyeleksi yang ingin Anda kecualikan. Artinya mengecualikan .example tidak akan mengecualikan p .example . $ cssInliner -> addExcludedCssSelector ( ' * ' );
$ cssInliner -> addExcludedCssSelector ( ' form ' );->removeExcludedCssSelector(string $selector) - Menghapus penyeleksi yang dikecualikan yang ditambahkan sebelumnya, jika ada. $ cssInliner -> removeExcludedCssSelector ( ' form ' );Emogrifier yang dihapus ke kelas CssInliner Kode lama menggunakan Emogrifier :
$ emogrifier = new Emogrifier ( $ html );
$ html = $ emogrifier -> emogrify (); Kode baru menggunakan CssInliner :
$ html = CssInliner:: fromHtml ( $ html )-> inlineCss ()-> render (); NB: Dalam contoh ini, kode lama menghapus elemen dengan display: none; sedangkan kode baru tidak, karena perilaku default kelas lama dan kelas baru berbeda dalam hal ini.
Kode lama menggunakan Emogrifier :
$ emogrifier = new Emogrifier ( $ html , $ css );
$ emogrifier -> enableCssToHtmlMapping ();
$ html = $ emogrifier -> emogrify (); Kode baru menggunakan CssInliner dan keluarga:
$ domDocument = CssInliner:: fromHtml ( $ html )-> inlineCss ( $ css )-> getDomDocument ();
HtmlPruner:: fromDomDocument ( $ domDocument )-> removeElementsWithDisplayNone ();
$ html = CssToAttributeConverter:: fromDomDocument ( $ domDocument )
-> convertCssToVisualAttributes ()-> render ();Emogrifier saat ini mendukung penyeleksi CSS berikut:
~ (satu kata dalam daftar kata yang dipisahkan spasi)| (baik nilai yang sama persis atau awalan yang diikuti dengan tanda hubung)^ (pencocokan awalan)$ (akhiran cocok)* (kecocokan substring)p:first-of-type tetapi tidak *:first-of-type )Penyeleksi berikut belum diterapkan:
<style> dalam HTML – termasuk (namun tidak terbatas pada) hal berikut: Aturan yang melibatkan penyeleksi berikut tidak dapat diterapkan sebagai gaya sebaris. Namun, mereka akan dipertahankan dan disalin ke elemen <style> di HTML:
:hover )::after ) @media yang berlaku. Kueri media bisa sangat berguna dalam desain email responsif. Lihat dukungan kueri media. Namun, agar efektif, Anda mungkin perlu menambahkan !important ke beberapa deklarasi di dalamnya sehingga deklarasi tersebut akan menggantikan gaya CSS yang telah disisipkan. Misalnya, dengan CSS berikut, deklarasi font-size dalam aturan @media tidak akan mengesampingkan ukuran font untuk elemen p dari aturan sebelumnya setelah itu disisipkan sebagai <p style="font-size: 16px;"> dalam HTML, tanpa direktif !important (walaupun !important tidak diperlukan jika CSS tidak disisipkan): p {
font-size : 16 px ;
}
@media ( max-width : 640 px ) {
p {
font-size : 14 px !important ;
}
}@media tidak dapat diterapkan ke nilai properti CSS yang telah disisipkan dan dievaluasi. Namun, aturan @media yang menggunakan properti khusus (dengan var() ) masih bisa mendapatkan nilainya (dari definisi sebaris atau aturan @media ) di klien email yang mendukung properti khusus.::after ) atau kelas semu dinamis (seperti :hover ) – hal ini tidak mungkin. Namun, aturan tersebut akan dipertahankan dan disalin ke elemen <style> , seperti untuk aturan @media , dengan peringatan yang sama berlaku.<style> dari HTML Anda, namun tidak akan mengambil file CSS yang direferensikan dalam elemen <link> atau aturan @import (meskipun akan membiarkannya tetap utuh untuk klien email yang mendukungnya).Silakan lihat API dan kebijakan penghentian kami.
Kontribusi dalam bentuk laporan bug, permintaan fitur, atau permintaan penarikan sangat kami harapkan. Silakan lihat pedoman kontribusi kami untuk mempelajari lebih lanjut tentang cara berkontribusi ke Emogrifier.
branch-alias agar mengarah ke rilis setelah rilis mendatang.
