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>Hello World</mj-text></mj-column></mj-section></mj-body></mjml>'
);
 
// Минифицированный HTML
(new MJML)->minify()->render(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Hello World</mj-text></mj-column></mj-section></mj-body></mjml>'
);
 
// С Laravel
MJML::render(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Hello World</mj-text></mj-column></mj-section></mj-body></mjml>'
);
 
// С Laravel и минифицированным HTML
MJML::minify()->render(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Hello World</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 ниже, если вы используете Laravel.

Отображение MJML

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

use DefectiveCode\MJML;
 
$html = (new MJML)->render(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Hello World</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>Hello World</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>Hello World</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>Hello World</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>Hello World</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 внутри, но этот пакет поддерживает оберточный уровень улучшения, чтобы пользовательские PHP beautifyOptions продолжали работать. Параметры по умолчанию:

Хотя 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 по умолчанию. Вы можете добавить параметры juice, используя следующие методы:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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