From 7889c487c82c0848ef1d1cc91d22f3fe0e6e7755 Mon Sep 17 00:00:00 2001 From: Fabio Cagliero Date: Thu, 7 Mar 2024 14:48:46 +0100 Subject: [PATCH] v1.0.0 - Support for Laravel 9 - 11 and PHP 8.1 - 8.3 - Use `spatie/mjml-php` package - Add tests with Pest --- .editorconfig | 18 +++++++ .github/workflows/run-tests.yml | 54 ++++++++++++++++++++ .gitignore | 4 ++ CHANGELOG.md | 14 ++++++ LICENSE | 21 ++++++++ README.md | 68 +++++++++++++++++++++++++ composer.json | 58 ++++++++++++++++++++++ package.json | 5 ++ phpunit.xml | 17 +++++++ src/Mailable.php | 88 +++++++++++++++++++++++++++++++++ tests/Feature/MailableTest.php | 43 ++++++++++++++++ tests/Pest.php | 47 ++++++++++++++++++ tests/TestCase.php | 10 ++++ 13 files changed, 447 insertions(+) create mode 100644 .editorconfig create mode 100644 .github/workflows/run-tests.yml create mode 100644 .gitignore create mode 100644 CHANGELOG.md create mode 100644 LICENSE create mode 100644 README.md create mode 100644 composer.json create mode 100644 package.json create mode 100644 phpunit.xml create mode 100644 src/Mailable.php create mode 100644 tests/Feature/MailableTest.php create mode 100644 tests/Pest.php create mode 100644 tests/TestCase.php diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..8f0de65 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,18 @@ +root = true + +[*] +charset = utf-8 +end_of_line = lf +indent_size = 4 +indent_style = space +insert_final_newline = true +trim_trailing_whitespace = true + +[*.md] +trim_trailing_whitespace = false + +[*.{yml,yaml}] +indent_size = 2 + +[docker-compose.yml] +indent_size = 4 diff --git a/.github/workflows/run-tests.yml b/.github/workflows/run-tests.yml new file mode 100644 index 0000000..743b8e2 --- /dev/null +++ b/.github/workflows/run-tests.yml @@ -0,0 +1,54 @@ +name: Run Tests + +on: [push, pull_request] + +jobs: + test: + runs-on: ${{ matrix.os }} + strategy: + fail-fast: true + matrix: + os: [ubuntu-latest] + php: [8.1, 8.2, 8.3] + laravel: [9.*, 10.*, 11.*] + stability: [prefer-lowest, prefer-stable] + include: + - laravel: 9.* + testbench: ^7.40 + pest: ^1.0 + - laravel: 10.* + testbench: ^8.21 + pest: ^2.0 + - laravel: 11.* + testbench: ^9.0 + pest: ^2.0 + exclude: + - php: 8.1 + laravel: 11.* + + name: P${{ matrix.php }} - L${{ matrix.laravel }} - ${{ matrix.stability }} - ${{ matrix.os }} + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup PHP + uses: shivammathur/setup-php@v2 + with: + php-version: ${{ matrix.php }} + extensions: dom, curl, libxml, mbstring, zip, pcntl, pdo, sqlite, pdo_sqlite, bcmath, soap, intl, gd, exif, iconv, imagick, fileinfo + coverage: none + + - name: Setup problem matchers + run: | + echo "::add-matcher::${{ runner.tool_cache }}/php.json" + echo "::add-matcher::${{ runner.tool_cache }}/phpunit.json" + + - name: Install dependencies + run: | + composer require "laravel/framework:${{ matrix.laravel }}" "orchestra/testbench:${{ matrix.testbench }}" "pestphp/pest:${{ matrix.pest }}" --no-interaction --no-update + composer update --${{ matrix.stability }} --prefer-dist --no-interaction + npm install + + - name: Execute tests + run: vendor/bin/pest diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..21cdf54 --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +/node_modules +/vendor +composer.lock +pnpm-lock.yaml diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..9b2ab96 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,14 @@ +# Changelog + +All notable changes to `webnuvola/laravel-mjml` will be documented in this file. + +## v1.0.0 - 2024-03-07 + +- Support for Laravel 9 - 11 and PHP 8.1 - 8.3 +- Use `spatie/mjml-php` package +- Add tests with Pest + +## Upgrading from v0.4.0 to v1.0.0 +Version v1.0.0 is compatible with Mailables defined with version v0.4.0. + +This package uses [`spatie/mjml-php`](https://github.com/spatie/mjml-php) under the hood. In your project, or on your server, you must have the JavaScript package [`mjml`](https://github.com/mjmlio/mjml) installed. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..39f6fdf --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2024 Webnuvola + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..350a7f1 --- /dev/null +++ b/README.md @@ -0,0 +1,68 @@ +# Laravel MJML +[![Latest Version on Packagist](https://img.shields.io/packagist/v/webnuvola/laravel-mjml.svg?style=flat-square)](https://packagist.org/packages/webnuvola/laravel-mjml) +[![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/webnuvola/laravel-mjml/run-tests.yml?branch=main)](https://github.com/webnuvola/laravel-mjml/actions/workflows/run-tests.yml?query=branch%3Amain) +[![Total Downloads](https://img.shields.io/packagist/dt/webnuvola/laravel-mjml.svg?style=flat-square)](https://packagist.org/packages/webnuvola/laravel-mjml) + +Effortlessly craft responsive email templates using MJML within Laravel Mailables. + +To use this package, follow these steps after generating a new Mailable. +Instead of extending `Illuminate\Mail\Mailable`, extend `Webnuvola\Laravel\Mjml\Mailable`. +In the Mailable class, define the `build` method. +You can now use the `mjml` method for defining a view or `mjmlContent` to directly pass the MJML template. + +Here's an example: + +```php +use Webnuvola\Laravel\Mjml\Mailable; + +class TestMail extends Mailable +{ + /** + * Build the message. + */ + public function build(): void + { + return $this->mjml('emails.orders.shipped', [ + 'order' => $order, + ]); + } +} +``` + +## Installation + +You can install the package via composer: + +```bash +composer require webnuvola/laravel-mjml +``` + +In your project, or on your server, you must have the JavaScript package [`mjml`](https://github.com/mjmlio/mjml) installed. + +```bash +npm install mjml +``` + +Make sure you have installed Node 16 or higher. +This package uses [`spatie/mjml-php`](https://github.com/spatie/mjml-php) under the hood. + + +## Testing + +```bash +composer test +``` + +## Changelog + +Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. + +## Credits + +- [Fabio Cagliero](https://github.com/fab120) + +Inspired by [asahasrabuddhe/laravel-mjml](https://github.com/asahasrabuddhe/laravel-mjml) package. + +## License + +The MIT License (MIT). Please see [License File](LICENSE) for more information. diff --git a/composer.json b/composer.json new file mode 100644 index 0000000..5a5a023 --- /dev/null +++ b/composer.json @@ -0,0 +1,58 @@ +{ + "name": "webnuvola/laravel-mjml", + "description": "Effortlessly craft responsive email templates using MJML within Laravel Mailables", + "keywords": [ + "email", + "laravel", + "mail", + "mailables", + "mjml" + ], + "license": "MIT", + "authors": [ + { + "name": "Fabio Cagliero", + "email": "fabio@webnuvola.com" + } + ], + "require": { + "php": "^8.1", + "html2text/html2text": "^4.3", + "laravel/framework": "^9.0||^10.0||^11.0", + "spatie/mjml-php": "^1.1" + }, + "require-dev": { + "orchestra/testbench": "^7.0||^8.0||^9.0", + "pestphp/pest": "^2.34" + }, + "autoload": { + "psr-4": { + "Webnuvola\\Laravel\\Mjml\\": "src/" + } + }, + "autoload-dev": { + "psr-4": { + "Webnuvola\\Laravel\\Mjml\\Tests\\": "tests/" + } + }, + "scripts": { + "test": "pest" + }, + "extra": { + "laravel": { + "providers": [ + "Webnuvola\\Laravel\\Mjml\\ServiceProvider" + ] + } + }, + "config": { + "optimize-autoloader": true, + "preferred-install": "dist", + "sort-packages": true, + "allow-plugins": { + "pestphp/pest-plugin": true + } + }, + "minimum-stability": "dev", + "prefer-stable": true +} diff --git a/package.json b/package.json new file mode 100644 index 0000000..339c1ca --- /dev/null +++ b/package.json @@ -0,0 +1,5 @@ +{ + "dependencies": { + "mjml": "^4.15.3" + } +} diff --git a/phpunit.xml b/phpunit.xml new file mode 100644 index 0000000..0c12bb9 --- /dev/null +++ b/phpunit.xml @@ -0,0 +1,17 @@ + + + + + ./tests + + + + + ./src + + + diff --git a/src/Mailable.php b/src/Mailable.php new file mode 100644 index 0000000..826b992 --- /dev/null +++ b/src/Mailable.php @@ -0,0 +1,88 @@ +mjml = $view; + $this->viewData = array_merge($this->buildViewData(), $data); + + return $this; + } + + /** + * Set the MJML content for the message. + */ + public function mjmlContent(string $mjmlContent): static + { + $this->mjmlContent = $mjmlContent; + + return $this; + } + + /** + * Build the view for the message. + * + * @return array|string + * + * @throws \ReflectionException + */ + protected function buildView() + { + if (isset($this->mjml) || isset($this->mjmlContent)) { + return $this->buildMjmlView(); + } + + return parent::buildView(); + } + + /** + * Build the MJML view for the message. + */ + protected function buildMjmlView(): array + { + if (isset($this->mjml)) { + $this->mjmlContent = View::make($this->mjml, $this->buildViewData()); + } + + $html = Mjml::new()->toHtml($this->mjmlContent); + + return [ + 'html' => new HtmlString($html), + 'text' => new HtmlString( + html_entity_decode( + preg_replace("/[\r\n]{2,}/", "\n\n", (new Html2Text($html, ['width' => 0]))->getText()), + ENT_QUOTES, + 'UTF-8', + ), + ), + ]; + } +} diff --git a/tests/Feature/MailableTest.php b/tests/Feature/MailableTest.php new file mode 100644 index 0000000..35ae0fb --- /dev/null +++ b/tests/Feature/MailableTest.php @@ -0,0 +1,43 @@ +mjmlContent( + << + + + + +

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

+

Link

+ + + + + + EOF, + ); + } +} + +it('can build email with inline content', function () { + $mailable = new MjmlTestMail(); + + $mailable + ->assertSeeInOrderInHtml( + [ + '

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

', + '

Link

', + ], + false, + ) + ->assertSeeInOrderInText([ + 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.', + 'Link [https://www.example.com/]', + ]); +}); diff --git a/tests/Pest.php b/tests/Pest.php new file mode 100644 index 0000000..bf0ce30 --- /dev/null +++ b/tests/Pest.php @@ -0,0 +1,47 @@ +in('Feature'); + +/* +|-------------------------------------------------------------------------- +| Expectations +|-------------------------------------------------------------------------- +| +| When you're writing tests, you often need to check that values meet certain conditions. The +| "expect()" function gives you access to a set of "expectations" methods that you can use +| to assert different things. Of course, you may extend the Expectation API at any time. +| +*/ + +expect()->extend('toBeOne', function () { + return $this->toBe(1); +}); + +/* +|-------------------------------------------------------------------------- +| Functions +|-------------------------------------------------------------------------- +| +| While Pest is very powerful out-of-the-box, you may have some testing code specific to your +| project that you don't want to repeat in every file. Here you can also expose helpers as +| global functions to help you to reduce the number of lines of code in your test files. +| +*/ + +function something() +{ + // .. +} diff --git a/tests/TestCase.php b/tests/TestCase.php new file mode 100644 index 0000000..c184fce --- /dev/null +++ b/tests/TestCase.php @@ -0,0 +1,10 @@ +