shawnmccool / minimal-php-postmark-sdk
A minimal PHP Postmark SDK that enables you to send single and batched email through the PostmarkApp.com service.
Requires
- php: ^8
- ext-curl: *
Requires (Dev)
- phpunit/phpunit: 9.5.x-dev
README
A minimal PHP Postmark SDK that enables you to send single and batched email through the PostmarkApp.com service.
Design
To maintain reliability, some objects are used for data (such as email and metadata) so that they can ensure that either the data conforms to specification or the developer is made aware of it as quickly as possible.
Install
$ composer require shawnmccool/minimal-php-postmark-sdk
Creating Mailings
The Mailing class represents a single instance that will be sent to a single recipient.
Simple Mail
To, from, subject, and body.
<?php use MinimalPhpPostmarkSdk\{Mailing, Email}; new Mailing( 'from name', Email::fromString('from@email.com'), Email::fromString('to@email.com'), 'subject line', 'email body' );
Tags and Metadata
Configure message tags and metadata for link each mailing to entities, events, etc.
<?php use MinimalPhpPostmarkSdk\{Mailing, Email}; new Mailing( 'from name', Email::fromString('from@email.com'), Email::fromString('to@email.com'), 'subject line', 'email body', [], 'holiday-sales-campaign', [ 'user_id' => 1, 'description' => 'this information may be maximum 80 characters' ] );
File Attachments
Multiple files can be attached.
<?php use MinimalPhpPostmarkSdk\{Mailing, Email, Attachment}; new Mailing( 'from name', Email::fromString('from@email.com'), Email::fromString('to@email.com'), 'subject line', 'email body', [ new Attachment( 'filename.pdf', 'application/pdf', file_get_contents('local.pdf') ) ] );
Postmark Templates
Instead of specifying a subject line and html body you can use the Postmark template feature. Build the template in the Postmark user interface and specify either its id or alias in the mailing.
<?php use MinimalPhpPostmarkSdk\{Mailing, Email}; new Mailing( 'from name', Email::fromString('from@email.com'), Email::fromString('to@email.com'), null, null, [], '', [], 'postmark template alias' );
or
<?php use MinimalPhpPostmarkSdk\{Mailing, Email}; new Mailing( 'from name', Email::fromString('from@email.com'), Email::fromString('to@email.com'), null, null, [], '', [], '', 'template id' );
Postmark templates allow for variables. Create a template model to fill those variables.
<?php use MinimalPhpPostmarkSdk\{Mailing, Email}; new Mailing( 'from name', Email::fromString('from@email.com'), Email::fromString('to@email.com'), null, null, [], '', [], '', 'template id', [ 'customer_name' => 'Roger', 'product_name' => 'A really fun gift.' ] );
Named Parameters
There's a number of options when creating a mailing. It could be possible to make a more rich and complex object model to reduce the need for optional constructor arguments. But in the name of simplicity and the fact that the class is feature complete we're going to leave it how it is.
If you don't like the empty arguments you can create a wrapper class, or you might prefer to use named parameters.
<?php use MinimalPhpPostmarkSdk\{Mailing, Email}; new Mailing( fromName: 'from name', fromEmail: Email::fromString('from@email.com'), toEmail: Email::fromString('to@email.com'), templateId: 'template id', templateModel: [ 'customer_name' => 'Roger', 'product_name' => 'A really fun gift.' ] );
Sending Mailings
The Postmark API
You'll need a server token from postmark.
The PostmarkApi
class handles interactions with the Postmark API.
<?php use MinimalPhpPostmarkSdk\PostmarkApi; $postmark = new PostmarkApi('server token');
Single Mailing
Sending a single mail is different from sending a batch. The response is an instance of SuccessResponse
or ErrorResponse
.
use MinimalPhpPostmarkSdk\{ErrorResponse,PostmarkApi,Mailing,Email,SuccessResponse}; $mailing = new Mailing( 'from name', Email::fromString('from@email.com'), Email::fromString('to@email.com'), null, null, [], '', [], '', 'template id' ); $response = (new PostmarkApi('server token'))->single($mailing); echo match (get_class($response)) { SuccessResponse::class => "Successfully sent message {$response->messageId()}.", ErrorResponse::class => "Could not send message. {$response->errorMessage()}", };
Batch Mailing
A batched mailing is an array of mailings that will be sent to the Postmark api in chunks. This prevents new connections to the api being made for each and every mailing. By default the batch mailing will send chunks of 500 mailings at once; but this can be configured.
use MinimalPhpPostmarkSdk\{PostmarkApi,Mailing,Email}; $mailings = [ new Mailing( 'from name', Email::fromString('from@email.com'), Email::fromString('to@email.com'), null, null, [], '', [], '', 'template id' ), new Mailing( 'from name', Email::fromString('from@email.com'), Email::fromString('to@email.com'), null, null, [], '', [], '', 'template id' ) ]; # to send a batch with default settings (new PostmarkApi('server token'))->batch($mailings); # manually specify chunk size {how many mailings to send in one call) (new PostmarkApi('server token'))->batch($mailings, 100);
Development
Development can be done on any machine running at least PHP 8.0. Set up the machine yourself or use the virtual-machine provided.
Running the Tests
The idea here is to test everything that doesn't have side effects against the Postmark API.
$ bin/phpunit
The Virtual Machine
The virtual machine may help if you don't have PHP 8.0 on your computer or if you want to avoid some kind of versioning collision etc. This will create an emulated server inside your computer that is configured for development of this package.
For the most part this should not be necessary.
Install modern versions of the following on your computer.
Run the following in the repository's directory.
$ git submodule update --init virtual-machine $ vagrant up
The virtual machine will initialize. Afterwards enter the virtual machine and run the tests to validate the setup.
$ vagrant ssh Welcome to Ubuntu 18.04 LTS (GNU/Linux 4.15.0-20-generic x86_64) * Documentation: https://help.ubuntu.com * Management: https://landscape.canonical.com * Support: https://ubuntu.com/advantage Last login: Sat Dec 26 16:29:42 2020 from 10.0.2.2 minimal-php-postmark-sdk :: /vagrant $ bin/phpunit