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
    Все Все 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, смотрите использование ниже.

Рендеринг MJML

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

use DefectiveCode\MJML\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\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\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 теги. Это соответствует более безопасному умолчанию MJML 5. Вы можете включить включения, вызвав ignoreIncludes(false).

При включении включений используйте filePath(string $path) в качестве основной директории и includePath(string|array|null $path), чтобы разрешить дополнительные директории включений.

Украшение

Наш пакет будет улучшать HTML, используя js-beautify. MJML 5.2 также использует js-beautify внутри, но этот пакет сохраняет украшение на уровне обертки, чтобы пользовательские beautifyOptions PHP продолжали работать. Параметры по умолчанию:

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

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

Минификация

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

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

Почему минификация на основе PHP? MJML 5 больше не использует старый уязвимый пакет html-minifier. Этот пакет все еще сохраняет минификацию в PHP для поддержания поведения вывода, введенного в версии 2.x. Если вам нужны нативные параметры минификации htmlnano/cssnano от MJML 5, откройте проблему с требуемой формой опции.

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

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

Путь к файлу

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

MJML 5 рассматривает filePath как базу песочницы для включений. Если включения включены, пути за пределами filePath запрещены, если они не разрешены явно с помощью includePath(string|array|null $path).

Juice

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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