Developed with love by KnpLabs Hire us for your project!
22

KnpMailjetBundle

by KnpLabs

Symfony2 bundle for handling Mailjet API

KnpMailjetBundle

KnpMailjetBundle is a Symfony2 Bundle, mainly aimed at processing Mailjet Event Tracking API,
but also provides service initialization for mailjet-api-php library.

Build Status
SensioLabsInsight
Scrutinizer Quality Score
Latest Stable Version
Composer Downloads

Usage

RESTful API as a service

Add api/secret keys in config.yml and it's up!

# app/config.yml
knp_mailjet:
    api_key:    %mailjet_api_key%
    secret_key: %mailjet_secret_key%

Now you can access RESTful API via DIC by calling knp_mailjet.api service:

<?php

$client = $this->container->get('knp_mailjet.api');
$userInfo = $client->get(RequestApi::USER_INFOS);

var_dump($userInfo);

//(
//    [username] => KnpLabs
//    [email] => hello@Knplabs.com
//    ...
//)

Event Tracking Listener

KnpMailjetBundle handles Event Tracking API via EventListener service.

Configuring Mailjet

First, you need to provide Mailjet with a specific endpoint URL where all event callbacks will be sent.
To do this, go to Event Tracking admin panel:

KnpMailjetBundle provides a helper command that you can use to quickly dump current endpoint URL:

$ php app/console mailjet:event-endpoint example.com
http://example.com/mailjet-event-api-endpoint

Configuring Event Listener

To actually handle events, you need to create your own Event Listener class by implementing provided interface Knp\Bundle\MailjetBundle\Event\Listener\EventListenerInterface:

<?php

namespace Acme\DemoBundle\Listener;

use Knp\Bundle\MailjetBundle\Event\Listener\EventListenerInterface;

use Knp\Bundle\MailjetBundle\Event\Adapter\BlockedEvent;
use Knp\Bundle\MailjetBundle\Event\Adapter\BounceEvent;
// ...

class EventListener implements EventListenerInterface
{
    public function onOpenEvent(OpenEvent $event)
    {
        // handle open events here
    }

    public function onSpamEvent(SpamEvent $event)
    {
        // handle close events here
    }

    // ...
}

Now you need to configure it in DIC, but be sure to specify the tags you want to listen to:

    acme.demo.mailjet_listener:
        class:  Acme\DemoBundle\Listener\EventListener
        tags:
            - { name: kernel.event_listener, event:  knp_mailjet.open,    method: onOpenEvent }
            - { name: kernel.event_listener, event:  knp_mailjet.blocked, method: onBlockedEvent }
            - { name: kernel.event_listener, event:  knp_mailjet.bounce,  method: onBounceEvent }
            - { name: kernel.event_listener, event:  knp_mailjet.click,   method: onClickEvent }
            - { name: kernel.event_listener, event:  knp_mailjet.spam,    method: onSpamEvent }
            - { name: kernel.event_listener, event:  knp_mailjet.typofix, method: onTypofixEvent }
            - { name: kernel.event_listener, event:  knp_mailjet.unsub,   method: onUnsubEvent }
        arguments: []

And that's it, your endpoint is ready for Event Tracking API consumption!

If you don't know where to start with Event Listener implementation, take a look at the
demo listener and its configuration, which simply logs the events.

Securing Endpoint URL

It's a good idea to secure your endpoint URL with a special token that only you and Mailjet servers will know.
That way you will avoid people abusing it should they discover.

With KnpMailjetBundle it's really easy - just specify your desired token in config.yml:

# app/config.yml
knp_mailjet:
    event_endpoint_token: 123token

And now if you run the helper command you will see the secured URL:

$ php app/console mailjet:event-endpoint example.com
http://example.com/mailjet-event-api-endpoint/123token

Don't forget to update Mailjet admin panel with your new endpoint URL!

Installation

The first step to use KnpMailjetBundle is to download Composer:

$ curl -s http://getcomposer.org/installer | php

Now add KnpMailjetBundle with Composer:

$ php composer.phar require knplabs/knp-mailjet-bundle:1.*

And that's it! Composer will automatically handle the rest.

Alternatively, you can manually add the dependency to composer.json file...

{
    "require": {
        "knplabs/knp-mailjet-bundle": "1.*"
    }
}

... and then install our dependencies using:
bash
$ php composer.phar install

After that, you need to update your app/AppKernel.php file:

<?php
// app/AppKernel.php

use Symfony\Component\HttpKernel\Kernel;

class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = array(
            // ...
            new Knp\Bundle\MailjetBundle\KnpMailjetBundle(),
        );
    }
}

For Event Tracking API you also need to import routing:

# app/routing.yml

_knp_mailjet:
    resource: "@KnpMailjetBundle/Resources/config/routing.yml"

And that's it!

Requirements

  • PHP >= 5.3.8
  • knplabs/mailjet-api-php

Contributing

See CONTRIBUTING.md file.

Running the Tests

To run unit tests, you'll need a set of dev dependencies you can install using Composer:

php composer.phar install --dev

Once installed, just launch the following command:

./bin/phpspec

Credits

Sponsored by

KnpLabs Team

License

KnpMailjetBundle is released under the MIT License. See the bundled LICENSE file for
details.

The MIT License

Copyright (c) 2013 KnpLabs

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.
knp_mailjet:

# Mailjet API key
api_key: ~

# Mailjet API token
secret_key: ~

# Route name of the event API endpoint
event_endpoint_route: knp_mailjet_event_endpoint

# Security token to validate endpoint request with
event_endpoint_token: ~
  • use stable release example in readme
    By Inoryy, 4 years ago
  • add sl-insight widget
    By Inoryy, 4 years ago
  • add packagist widget
    By Inoryy, 4 years ago
  • add travis-ci widget
    By Inoryy, 4 years ago
  • add scrutinizer-ci widget
    By Inoryy, 4 years ago
  • add a note to readme on running unit tests
    By Inoryy, 4 years ago
  • add travis CI integration
    By Inoryy, 4 years ago
  • use non-dev mailjet-api library version
    By Inoryy, 4 years ago
  • fix cs
    By Inoryy, 4 years ago
  • add spec to check endpoint uri generation with token
    By Inoryy, 4 years ago
  • add command spec
    By Inoryy, 4 years ago
  • add controller callback validation specs
    By Inoryy, 4 years ago
  • add successful callback spec
    By Inoryy, 4 years ago
  • add event factory spec
    By Inoryy, 4 years ago
  • Merge branch 'master' of github.com:KnpLabs/KnpMailjetBundle
    By Inoryy, 4 years ago
  • fix packagist name typo
    By docteurklein, 4 years ago
  • add basic phpspec tests
    By Inoryy, 4 years ago
  • add basic deps + phpspec for testing
    By Inoryy, 4 years ago
  • link to proper mailjet-api-php lib version, add branch alias
    By Inoryy, 4 years ago
  • remove unnecessary method
    By Inoryy, 4 years ago
  • fix Adapter method override
    By Inoryy, 4 years ago
  • fix service definition - apparently you can't inherit tags in Symfony2
    By Inoryy, 4 years ago
  • make example event listener less strict
    By Inoryy, 4 years ago
  • can't rely on content type to validate incoming content, Mailjet doesn't set it to json
    By Inoryy, 4 years ago
  • Update README.md
    By Inoryy, 4 years ago
  • Update README.md
    By Inoryy, 4 years ago
  • add readme and contributing
    By Inoryy, 4 years ago
  • specify which Event class is returned on getEvent() of event adapters
    By Inoryy, 4 years ago
  • get rid of event listener class config, add (commented out) example implementation config instead; make initial config abstract
    By Inoryy, 4 years ago
  • specify proper target dir for Composer
    By Inoryy, 4 years ago