Defective Code Logo

Total Downloads Latest Stable Version Latest Stable Version

English | العربية | বাংলা | Bosanski | Deutsch | Español | Français | हिन्दी | Italiano | 日本語 | 한국어 | मराठी | Português | Русский | Kiswahili | தமிழ் | తెలుగు | Türkçe | اردو | Tiếng Việt | 中文

Обновление

Если вы обновляете с предыдущей версии, пожалуйста, ознакомьтесь с Руководством по обновлению для получения информации о критических изменениях и этапах миграции.

Введение

MJML — это язык разметки, специально разработанный для упрощения процесса кодирования адаптивных электронных писем. Его семантический синтаксис обеспечивает удобство и простоту, тогда как обширная библиотека стандартных компонентов ускоряет разработку и снижает сложность вашей кодовой базы электронных писем. Открытый движок MJML генерирует высококачественный, адаптивный HTML, соответствующий лучшим практикам. Если вы испытывали раздражение, работая с Outlook, этот пакет создан именно для вас.

Наша реализация MJML служит оберткой для официального API MJML. Она позволяет удобно компилировать MJML в HTML непосредственно в PHP, без необходимости в NodeJS. Этот пакет идеально подходит для приложений на PHP, которые хотят включить MJML без хлопот, связанных с установкой NodeJS и CLI MJML.

Пример

// Без Laravel
(new MJML)->render(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Привет, мир</mj-text></mj-column></mj-section></mj-body></mjml>'
);
 
// Минифицированный HTML
(new MJML)->minify()->render(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Привет, мир</mj-text></mj-column></mj-section></mj-body></mjml>'
);
 
// С Laravel
MJML::render(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Привет, мир</mj-text></mj-column></mj-section></mj-body></mjml>'
);
 
// С Laravel и минифицированным HTML
MJML::minify()->render(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Привет, мир</mj-text></mj-column></mj-section></mj-body></mjml>'
);

Установка

  1. Сначала добавьте следующее в ваш файл composer.json, чтобы указать нашему пакету загрузить правильные бинарные файлы для вашей операционной системы при установке нашего пакета. Бинарные файлы будут загружены после выполнения команды install, update, или dump-autoload.

    {
        "post-autoload-dump": ["DefectiveCode\\MJML\\PullBinary::all"]
    }

    Бинарный файл MJML будет получен из нашего CDN и сохранен в папке "bin" этого пакета во время установки или обновления composer. Убедитесь, что необходимые бинарные файлы загружены как для вашей локальной, так и для производственной среды.

    По умолчанию, all загрузит все поддерживаемые бинарные файлы. Мы рекомендуем ограничиться операционными системами и архитектурами, которые вам нужны, чтобы сэкономить на пропускной способности и времени установки. Ниже представлены доступные бинарные файлы.

    Операционная система Архитектура Команда Composer Post Update
    Все Все DefectiveCode\MJML\PullBinary::all
    Darwin (MacOS) arm64 DefectiveCode\MJML\PullBinary::darwin-arm64
    Darwin (MacOS) x64 DefectiveCode\MJML\PullBinary::darwin-x64
    Linux (glibc) arm64 DefectiveCode\MJML\PullBinary::linux-arm64
    Linux (glibc) x64 DefectiveCode\MJML\PullBinary::linux-x64
    Linux (musl) arm64 DefectiveCode\MJML\PullBinary::linux-arm64-musl
    Linux (musl) x64 DefectiveCode\MJML\PullBinary::linux-x64-musl

  2. Далее установите PHP пакет, выполнив следующую команду composer:

    composer require defectivecode/mjml

  3. Вот и все! Если вы используете Laravel, наш пакет автоматически установится с помощью функции обнаружения пакетов Laravel.

Использование (Без Laravel)

См. использование с Laravel ниже, если вы используете Laravel.

Рендеринг MJML

Чтобы отрендерить MJML, просто передайте вашу MJML строку в метод render:

use DefectiveCode\MJML;
 
$html = (new MJML)->render(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Привет, мир</mj-text></mj-column></mj-section></mj-body></mjml>'
);

Валидация MJML

Чтобы валидировать MJML, просто передайте вашу MJML строку в метод isValid:

use DefectiveCode\MJML;
 
$isValid = (new MJML)->isValid(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Привет, мир</mj-text></mj-column></mj-section></mj-body></mjml>'
);

Использование (С Laravel)

Рендеринг MJML

Чтобы отрендерить MJML, просто передайте вашу MJML строку в метод render фасада MJML:

use DefectiveCode\MJML\Facades\MJML;
 
$html = MJML::render(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Привет, мир</mj-text></mj-column></mj-section></mj-body></mjml>'
);

Валидация MJML

Чтобы валидировать MJML, просто передайте вашу MJML строку в метод isValid фасада MJML:

use DefectiveCode\MJML\Facades\MJML;
 
$isValid = MJML::isValid(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Привет, мир</mj-text></mj-column></mj-section></mj-body></mjml>'
);

Конфигурация

Вы можете опубликовать файл конфигурации с помощью следующей команды:

php artisan vendor:publish --provider="DefectiveCode\MJML\MJMLServiceProvider"

Это создаст файл конфигурации mjml.php в вашей папке config. Все параметры, перечисленные в файле конфигурации, передаются объекту config, когда вы используете фасад MJML.

Конфигурация

Все параметры конфигурации могут быть заданы, вызывая следующие методы напрямую на объекте MJML.

use DefectiveCode\MJML;
 
$html = (new MJML)
    ->setMinify(true)
    ->setBeautify(false)
    ->render(
        '<mjml><mj-body><mj-section><mj-column><mj-text>Привет, мир</mj-text></mj-column></mj-section></mj-body></mjml>'
    );

Наш пакет следует той же конфигурации, что и официальный пакет MJML, за исключением следующих пунктов:

Шрифты

Наш пакет использует следующие шрифты по умолчанию:

Вы можете изменить шрифты, используя следующие методы:

Комментарии

Комментарии сохраняются по умолчанию. Если вы хотите удалить комментарии, вы можете использовать метод removeComments().

Вы также можете вернуть removeComments(), вызвав метод keepComments().

Игнорировать включения

По умолчанию наш пакет будет включать любые теги mj-include. Вы можете откорректировать это поведение, вызвав метод ignoreIncludes(bool $ignore).

Приведение к стандарту

Наш пакет приведет HTML к стандарту, используя js-beautify с следующими умолчальными параметрами:

Хотя js-beautify использует snake_case для предоставления параметров, вы должны использовать camelCase при работе с нашим пакетом. Мы сделали этот выбор, чтобы сохранить единство нашего пакета с остальными параметрами конфигурации. Наш пакет автоматически преобразует параметры из camelCase в snake_case.

Вы можете переопределить любые из этих параметров, предоставив действительную конфигурацию js-beautify, используя следующие методы:

Минификация

Наш пакет будет минифицировать HTML-вывод, когда эта функция будет включена. Минификация выполняет следующие шаги:

Вы можете включить или отключить минификацию, вызвав метод minify(bool $minify).

Почему минификация на основе PHP? Официальный пакет MJML использует html-minifier для минификации, который имеет известную уязвимость ReDoS (CVE-2022-37620), для которой нет доступного исправления, так как пакет не поддерживается. Чтобы избежать упаковки уязвимых зависимостей, мы перенесли минификацию на PHP с использованием легковесной, безопасной реализации.

Уровень валидации

Наш пакет будет валидировать MJML, используя уровень валидации soft по умолчанию. Вы можете изменить это, используя метод validationLevel(ValidationLevel $validationLevel). Ниже приведены доступные уровни валидации:

Путь к файлу

Наш пакет по умолчанию будет использовать директорию .. Вы можете изменить это, вызвав метод filePath(string $path).

Juice

Мы не предоставляем никаких опций juice по умолчанию. Вы можете добавить опции juice, используя следующие методы:

Руководство по поддержке

Спасибо, что выбрали наш пакет с открытым исходным кодом! Пожалуйста, уделите немного времени, чтобы ознакомиться с этими рекомендациями по поддержке. Они помогут вам максимально эффективно использовать наш проект.

Поддержка, основанная на сообществе

Наш проект с открытым исходным кодом поддерживается нашим замечательным сообществом. Если у вас есть вопросы или требуется помощь, StackOverflow и другие онлайн-ресурсы — ваши лучшие помощники.

Ошибки и приоритизация функций

Реальность управления проектом с открытым исходным кодом заключается в том, что мы не можем сразу же решить каждую сообщенную ошибку или запрос на новую функцию. Мы приоритизируем проблемы в следующем порядке:

1. Ошибки, влияющие на наши платные продукты

Ошибки, которые затрагивают наши платные продукты, всегда будут нашим приоритетом. В некоторых случаях мы можем рассматривать только те ошибки, которые влияют на нас напрямую.

2. Запросы на внесение изменений от сообщества

Если вы выявили ошибку и у вас есть решение, пожалуйста, отправьте запрос на внесение изменений. После вопросов, касающихся наших продуктов, мы придаем следующий высокий приоритет этим исправлениям, инициированным сообществом. После проверки и одобрения мы объединим ваше решение и отметим ваш вклад.

3. Финансовая поддержка

Для вопросов за пределами упомянутых категорий вы можете выбрать финансирование их решения. Каждая открытая проблема связана с формой заказа, через которую вы можете внести финансовый вклад. Мы приоритизируем эти вопросы на основе суммы финансирования.

Вклад сообщества

Проекты с открытым исходным кодом процветают, когда их сообщество активно. Даже если вы не исправляете ошибки, подумайте о том, чтобы внести вклад через улучшение кода, обновление документации, создание учебных пособий или помощь другим в каналах сообщества. Мы настоятельно призываем всех, как сообщество, поддерживать работу с открытым исходным кодом.

Повторим, что DefectiveCode будет приоритизировать ошибки в зависимости от того, как они влияют на наши платные продукты, запросы на внесение изменений от сообщества и финансовую поддержку, полученную за проблемы.

Лицензия - MIT Лицензия

Авторские права © Defective Code, LLC. Все права защищены

Настоящим предоставляется разрешение, безвозмездно, любому лицу, получающему копию этого программного обеспечения и сопутствующих документационных файлов (далее «Программное обеспечение»), пользоваться Программным обеспечением без ограничений, включая, но не ограничиваясь правами использовать, копировать, изменять, сливать, публиковать, распространять, предоставлять сублицензии и/или продавать копии Программного обеспечения, а также разрешать лицам, которым предоставляется Программное обеспечение, делать это, при соблюдении следующих условий:

Указанные выше авторские права и данное разрешение должны быть включены во все копии или значительные части Программного обеспечения.

ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ ПРЕДОСТАВЛЯЕТСЯ «КАК ЕСТЬ», БЕЗ ГАРАНТИЙ ЛЮБОГО ВИДА, ЯВНЫХ ИЛИ ИМПЛИЦИТНЫХ, ВКЛЮЧАЯ, НО НЕ ОГРАНИЧИВАЯСЬ, ГАРАНТИЯМИ ТОРГОВОЙ ПРИГОДНОСТИ, ПРИГОДНОСТИ ДЛЯ ОПРЕДЕЛЁННЫХ ЦЕЛЕЙ И НАРУШЕНИЯ ПРАВ. В НИКАКОМ СЛУЧАЕ АВТОРЫ ИЛИ ДЕРЖАТЕЛИ АВТОРСКИХ ПРАВ НЕ НЕСУТ ОТВЕТСТВЕННОСТЬ ЗА ЛЮБЫЕ ИСКИ, УЩЕРБ ИЛИ ДРУГИЕ ОБЯЗАТЕЛЬСТВА, НИ В КАКОМ УКАЗАНИИ, ДОГОВОРЕ, ДЕЛИКТЕ ИЛИ ИНОМ, ВЫТЕКАЮЩИЕ ИЗ, ИЛИ В СВЯЗИ С ПРОГРАММНЫМ ОБЕСПЕЧЕНИЕМ ИЛИ ИСПОЛЬЗОВАНИЕМ ИЛИ ДРУГИМИ СДЕЛКАМИ С ПРОГРАММНЫМ ОБЕСПЕЧЕНИЕМ.