Skip to content

README.md

Latest commit

 

History

History
195 lines (147 loc) · 6.36 KB

README.md

File metadata and controls

195 lines (147 loc) · 6.36 KB
Raw

Utopia Messaging

Important

This repository is a read-only mirror of the utopia-php monorepo. Development happens in packages/messaging — please open issues and pull requests there.

Build Status Total Downloads Discord

Utopia Messaging library is simple and lite library for sending messages using multiple messaging adapters. This library is aiming to be as simple and easy to learn and use. This library is maintained by the Appwrite team.

Although this library is part of the Utopia Framework project it is dependency free, and can be used as standalone with any other PHP project or framework.

Getting started

Install using Composer:

composer require utopia-php/messaging

Email

<?php

use \Utopia\Messaging\Messages\Email;
use \Utopia\Messaging\Adapter\Email\SendGrid;
use \Utopia\Messaging\Adapter\Email\Mailgun;
use \Utopia\Messaging\Adapter\Email\Resend;
use \Utopia\Messaging\Adapter\Email\SES;

$message = new Email(
    to: ['team@appwrite.io'],
    subject: 'Hello World',
    content: '<h1>Hello World</h1>'
);

$messaging = new Sendgrid('YOUR_API_KEY');
$messaging->send($message);

$messaging = new Mailgun('YOUR_API_KEY', 'YOUR_DOMAIN');
$messaging->send($message);

$messaging = new Resend('YOUR_API_KEY');
$messaging->send($message);

$messaging = new SES('YOUR_ACCESS_KEY', 'YOUR_SECRET_KEY', 'YOUR_REGION');
$messaging->send($message);

SMS

<?php

use \Utopia\Messaging\Messages\SMS;
use \Utopia\Messaging\Adapter\SMS\Twilio;
use \Utopia\Messaging\Adapter\SMS\Telesign;

$message = new SMS(
    to: ['+12025550139'],
    content: 'Hello World'
);

$messaging = new Twilio('YOUR_ACCOUNT_SID', 'YOUR_AUTH_TOKEN');
$messaging->send($message);

$messaging = new Telesign('YOUR_USERNAME', 'YOUR_PASSWORD');
$messaging->send($message);

One-time codes over WhatsApp

The WhatsApp adapter sends codes through a Meta Cloud API authentication template. Meta fixes the template text, so the message content is the code itself: up to 15 letters and digits, no free text. Create the template once per language, then send with the same SMS message type.

<?php

use \Utopia\Messaging\Messages\SMS;
use \Utopia\Messaging\Adapter\SMS\WhatsApp;
use \Utopia\Messaging\Adapter\SMS\WhatsApp\App;
use \Utopia\Messaging\Adapter\SMS\WhatsApp\MetadataParameter;
use \Utopia\Messaging\Adapter\SMS\WhatsApp\OtpType;

$messaging = new WhatsApp('YOUR_ACCESS_TOKEN', 'YOUR_PHONE_NUMBER_ID', 'login_code');

// Copy-code works everywhere. One-tap and zero-tap hand the code straight to a
// named Android app and fall back to copy-code on other platforms.
$messaging->upsertTemplate(
    'YOUR_BUSINESS_ACCOUNT_ID',
    ['en_US', 'fr'],
    expirationMinutes: 10,
    otpType: OtpType::ONE_TAP,
    apps: [new App('com.example.app', 'K8a/AINcGX7')],
);

$messaging->getTemplate('YOUR_BUSINESS_ACCOUNT_ID'); // [['language' => 'en_US', 'status' => 'APPROVED', ...], ...]

$message = new SMS(
    to: ['+12025550139'],
    content: '482913'
);
$message->setMetadata([
    MetadataParameter::LANGUAGE->value => 'fr',
    MetadataParameter::TEMPLATE->value => 'recovery_code',
    MetadataParameter::CALLBACK_DATA->value => 'token-64f1c2', // echoed back in status webhooks
]);

$messaging->send($message);

Push

<?php

use \Utopia\Messaging\Messages\Push;
use \Utopia\Messaging\Adapter\Push\FCM;

$message = new Push(
    to: ['eyJhGc...ssw5c'],
    content: 'Hello World'
);

$messaging = new FCM('YOUR_SERVICE_ACCOUNT_JSON');
$messaging->send($message);

Adapters

Want to implement any of the missing adapters or have an idea for another? We would love to hear from you! Please check out our contribution guide and new adapter guide for more information.

Email

SMS

Push

System requirements

Utopia Messaging requires PHP 8.0 or later. We recommend using the latest PHP version whenever possible.

Tests

To run all unit tests, use the following Docker command:

composer test

To run static code analysis, use the following Psalm command:

composer lint

Copyright and license

The MIT License (MIT) http://www.opensource.org/licenses/mit-license.php