Developer API

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.

// 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 {

	public $name = 'My Service';

	public $id = 'myService';

	public function send(Postmaster_TransportModel $model)
	{
		$response = new TransportResponse($model);

		try
		{
			$client = new Client();
			
			$request = $client->post($this->settings->url, array(), $this->settings->postVars);

			$request->send();

		}
		catch(\Exception $e)
		{
			$response->addError($e->getMessage());
			$response->setSuccess(false);
		}

		return $response;
	}

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

	public function getSettingsModelClassName()
	{
		return '\Craft\MyPlugin_MyServiceModel';
	}
}