Developer API

Overview

Developers can take complete control of Postmaster and harness the power of its underlying API's. The following are the API's current available to developers.

1. ParcelType API
2. Service API

Registering Classes

Postmaster allows developers to extend the core classes within their own plugins. When Postmaster is updated, your classes will never be overwritten. Before you can use your new classes in Postmaster you must register them so they will be recognized in the control panel. Once you register your classes, they will be available for immediate use. It's best practice to register your classes in the MyFooPlugin::init() method after the postmaster.onInit callback has been triggered.

public function init()
{
	craft()->on('postmaster.init', function(Event $event)
	{
		// Register multiple services at once
		craft()->postmaster->registerServices(array(
		    'Craft\FooService',
		    'Craft\YourService',
		));

		// One service at a time
		craft()->postmaster->registerService('Craft\FooService');

		// Register multiple parcel types at once
		craft()->postmaster->registerParcelTypes(array(
		    'Craft\FooParcelType',
		    'Craft\YourParcelType',
		));

		// One parcel type at a time
		craft()->postmaster->registerParcelType('Craft\FooParcelType');
	});
}

ParcelType API

ParcelTypes allow you to create different types of parcels that do different things beyond the default. These parcels can fire at anytime and can perform any arbitrary code you need. The great thing about creating your own ParcelType compared to rolling your own solution is that that you inherent all the services provided by Postmaster. For instances, you can can create your own interface, settings, and event binding logic, then pass all that to whatever service the user chooses. It's extremely fast to create custom notifications using ParcelTypes.

<?php
namespace Craft;

use Craft\Plugins\Postmaster\Components\BaseParcelType;

class MyParcelType extends BaseParcelType {
	
	// The name of your service and how it will appear in the app
	public $name = 'My Parcel Type';

	// A unique camelCased string used programmatically in the app
	public $id = 'myParcelType';

	// Do something at the start
	public function init()
	{
		// Set some stuff since we can't use "$this" in callback in PHP 5.3, super lame
		// $settings is an instance of the model you set in the `getSettingsModelClassName()`
		$settings = $this->settings;

		// $parcel is a `Postmaster_ParcelModel` object
		$parcel = $this->parcel;

		// Bind the event, this is any event (or events) you want
		$this->craft()->on('some.event', function(Event $event) use ($settings, $parcel)
        {
        	// Note, if the $settings var is an object that implements ParseInterface,
        	// it is then parseable. Otherwise, implement your own parsing logic.

         	// Super simple, just create a Postmaster_TransportModel and give
         	// it a service, some settings, and some data for later use (by a service maybe).
            $obj = new Postmaster_TransportModel(array(
                'service' => $parcel->service,
                'settings' => $settings->parse($data),
                'data' => array()
            ));

            // Send Postmaster_TransportModel to the parcel and let the API's
            // do the wrest... 
           	$parcel->send($obj);
        }
	}

	// Get your input fields html (appears in the Parcel tab)
	public function getInputHtml(Array $data = array())
	{
		return $this->craft()->templates->render('myplugin/myParcelType/fields', $data);	
	}

	// Gets your settings html (appears in the Settings tab)
	public function getSettingsInputHtml(Array $data = array())
	{
		return $this->craft()->templates->render('myplugin/myParcelType/settings', $data);	
	}

	// Gets the models of settings the correlates to your input fields
	public function getSettingsModelClassName()
	{
		return '\Craft\MyParcelTypeSettingsModel.php';
	}
}

Service API

Services are the classes that actually facilitate the sending of requests. The Services API allows developers to perform arbitrary logic to send a message with any service.

<?php
namespace Craft;

use Craft\Postmaster_TransportModel;
use Craft\Plugins\Postmaster\Components\BaseService;
use Craft\Plugins\Postmaster\Responses\TransportResponse;
use \Guzzle\Http\Client;

class MyService extends BaseService {

	// Your service's name
	public $name = 'My Service';

	// Your service's camelCased unique id
	public $id = 'myService';

	// Send the Postmaster_TransportModel
	public function send(Postmaster_TransportModel $model)
	{
		// Create a new TransportResponse object
		$response = new TransportResponse($model);

		// Try to perform the send request and catch the errors if it fails			
		try
		{
			// Create a new Guzzle Http client
			$client = new Client();
			
			// Create a new post request with t
			$request = $client->post('some url', array(), array('somePostVar' => 'some data'));

			// Send the request
			$request->send();

		}
		catch(\Exception $e)
		{
			// Add the exception error to the TransportResponse object
			$response->addError($e->getMessage());
			// Set the response success property to false to note it failed
			$response->setSuccess(false);
		}

		// You must always return the TransportResponse object
		return $response;
	}

	// Get the settings input html
	public function getInputHtml(Array $data = array())
	{
		return $this->craft()->templates->render('myplugin/myservice/settings', $data);
	}

	// Get the settings model class name
	public function getSettingsModelClassName()
	{
		return '\Craft\MyPlugin_MyServiceSettingsModel';
	}
}