headsnet/sms-bundle

Provide email and SMS sending functions

Symfony SMS Bundle

Symfony bundle to send and receive SMS messages. Currently only the Esendex SMS gateway is supported - https://www.esendex.com/. Other gateways may be added in the future., _(*1)

Greatly inspired by the excellent tomazahlin/symfony-mailer-bundle https://github.com/tomazahlin/symfony-mailer-bundle, _(*2)

Installation

Requires Symfony >= 3.3 and PHP >= 7.0, _(*3)

Install with Composer, _(*4)

composer require headsnet/sms-bundle, _(*5)

Add bundle to AppKernel.php, _(*6)

public function registerBundles()
{
    $bundles = array(
        // ...
        new Headsnet\SmsBundle\HeadsnetSmsBundle(),
    );
}

If you need to receive SMS then add the routing configuration in app/config/routing.yml, _(*7)

headsnet_sms:
  resource: '@HeadsnetSmsBundle/Resources/config/routing.yml'
  prefix:   '/sms'

Configuration

Add required configuration in app/config.yml, _(*8)

headsnet_sms:
  dispatcher:          esendex
  esendex:
    account_reference: ~
    username:          ~
    password:          ~
    vmn:               ~  # Virtual Mobile Number

To simulate SMS sending, you can use the DummyDispatcher - for example in your when running your test suite - add the following to app/config_test.yml, _(*9)

headsnet_sms:
  dispatcher: dummy

To override the recipient phone number, for example in development, add the following to app/config_dev.yml, _(*10)

headsnet_sms:
  delivery_override:   '+33123456789'

Define SMS message templates

Create a mapping service to link template path definitions to template names, _(*11)

<?php
declare(strict_types=1);

namespace AppBundle\Sms;

use Headsnet\Sms\Mapping\TemplateMappingInterface;

/**
 * Map template reference names to template paths
 */
class Mapping implements TemplateMappingInterface
{
    /**
     * @return array
     */
    public function getMappings()
    {
        return [
            'customer.confirm' => '@AppBundle/sms/customer.confirm.text.twig',
            'customer.reminder' => '@AppBundle/sms/customer.reminder.text.twig'
        ];
    }
}

Sending SMS

To send SMS, inject the SMS sender service in to your code. From here you can access the SMS message factory, or the SMS sender, _(*12)

namespace Company\App;

use Headsnet\Sms\SmsSendingInterface;

class MyService
{
    private $smsSending;

    public function __construct(SmsSendingInterface $smsSending)
    {
        $this->smsSending = $smsSending;
    }

    public function doSomething()
    {
        // How to access factory to create SMS instances
        $factory = $this->smsSending->getFactory();

        // How to access sender to send or queue the SMS
        $smsSender = $this->smsSending->getSmsSender();
    }
}

Setting up Push Notifications

If you want the EsendexEventDispatcher gateway to phone home with delivery notifications etc, you must ensure you have added the bundle's routing in your routing.yml file., _(*13)

Then, in your EsendexEventDispatcher control panel, configure the Push Notifications routes with the following URLs:, _(*14)

SMS received, _(*15)

https://app.your-domain.com/sms/esendex/message-received, _(*16)

SMS delivered, _(*17)

https://app.your-domain.com/sms/esendex/delivery-notify, _(*18)

SMS failed, _(*19)

https://app.your-domain.com/sms/esendex/delivery-error, _(*20)

Opt-out, _(*21)

https://app.your-domain.com/sms/esendex/opt-out, _(*22)

These end-points will receive the payload from EsendexEventDispatcher and dispatch one of the following events:, _(*23)

• headsnet.sms.delivered
• headsnet.sms.error
• headsnet.sms.received
• headsnet.sms.opt_out

Listeners to these events will receive a Headsnet\SmsBundle\Event\SmsEvent instance which contains the message data., _(*24)

View an example Event Subscriber for these events., _(*25)

Contributing

Pull requests and other contributions are very welcome., _(*26)