README

This modules purpose is to ease out the management of various external services that your application may depend upon. Each service is governed by a single easily reachable class that does all the required loading of PHP or Javascript,

Setting up:

Presently there are 2 types of services:

Javascript Services - they require javascript files to load. To be able to use those you must place those helpers in appropriate places

<html>
<head>
	<title>Site</title>
	...
	<!-- This needs to be inside your head tag -->
	<?php echo Service::all_heads(); ?>
</head>
<body>
	...
	<!-- This needs to be at the very end of the body, just before the closing body tag -->
	<?php echo Service::all_bodies(); ?>
</body>
</html>

PHP Services - they handle their own affairs.

Each service has its own configuration, you can see the default configuration in the services-manager.php file

Usage:

Some services have helper methods to be used throughout your code. The general principle is that those methods will fail silently if the service is disabled for some reason or another.

For example this will render an addthis toolbox with sharing options for the current url, but if the service is disabled, it will return an empty string, thus your site should not be affected by disabling of the services and continue operation:

<?php echo Service::factory('addthis')->toolbox() ?>

In order to insure that for your service specific code will not execute if the service is disabled, you can use the initialized method:

<?php if (Service::factory('addthis')->initialized()): ?>
	<!-- Your custom addthis code goes here -->
<?php endif; ?>

You can also disable each service based on a role from jam_auth. Just use the 'disabled-for-role' => '{somerole}' config parameter, or allow it only for certain roles with 'enabled-for-role' => '{somerole}'.

There are some builtin services that are available:

Addthis

Configuraitons:

enabled : (bool)
disabled-for-role : (string)
enabled-for-role : (string)
api-key : (string) your api key for addthis
load-user-email : (bool) if you set this to TRUE will load the current user email and you can use :user-email to access it in the addthis-config
addthis-config : (array) this will be use to set the javascript variable addthis_config, used by addthis.

Helpers:

toolbox($url = NULL, $attributes = NULL) : Generate a div addthis toolbox, url defaults to inital requests' url

Exceptionalio

Configuraitons:

enabled : (bool)
disabled-for-role : (string)
enabled-for-role : (string)
api-key : (string) your api key for exceptionalio
use-auth : (bool) Get the current user id and email and set it as custom parameters for the exception

Helpers:

log(Exception $exception) : Send the exception to exceptionalio

Googleanalytics

Configuraitons:

enabled : (bool)
disabled-for-role : (string)
enabled-for-role : (string)
api-key : (string) your api key for google analytics
header : (bool) Set it to FALSE to place the GA code at the bottom of the page

Kissinsights

Configuraitons:

enabled : (bool)
disabled-for-role : (string)
enabled-for-role : (string)
notifications-for-role : (string) this is used to replace kissmetrics events with HTML5 notifications so that you can clearly see which events get triggered and when, without going to kissmetrics service at all
api-file : (string) the file for kissinsights - they don't have api keys yet, but the filename is unique

Kissmetrics

Configuraitons:

enabled : (bool)
disabled-for-role : (string)
enabled-for-role : (string)
api-key : (string) your api key for kissmetrics
use-auth : (bool) Idintify the user with the email in the php api, using the currently logged user
php-api : (bool) Enabled the php-api. If its set to FALSE all the php methods will silently fail and the KM class will not be loaded at all.
more : (string) Custom javascript to be placed after kissmetrics has been included, placed just after the script tags

Helpers:

record($event) : Record an event with the PHP API
identify($identification) : Identify the user with the PHP API
set($properties) : Set properties to the current user with the PHP API
queue($event, $event2 ...) : Add the events to the Javascript API queue. If this is a normal page rendering it will place them just after the kissmetrics javascript include code, but if its ajax request will render a script tag directly with the events specified
is_async() : Find out if its an asynchronous request (ajax)

Example using the queue helper method. This will either add those to the queue and render it in the header, or render them directly here with a script tag:

<?php echo Service::factory('kissmetrics')->queue(
  array('trackClick', '.add-to-favourites', 'clicked on add to favourites in company profile'),
  array('trackClick', '.remove-from-favourites', 'clicked on remove from favourites in company profile')
) ?>

Mailchimp

Configuraitons:

enabled : (bool)
disabled-for-role : (string)
enabled-for-role : (string)
api-key : (string) your api key for mailchimp
lists : (array) Key value pairs for list alias => list id. If those are set you will be able to use list aliases instead of actual list ids, so for example listSubscribe('newsletter') will result in listSubscribe('')

Helpers:

This service uses Mailchimp api Version 1.3 and all methods are proxied to the API itself. so you can call any of the API methods directly with the service object. All methods starting with list, will try to use the ids specified in the configuration. Example:

<?php Service::factory('mailchimp')->lists->subscribe('newsletter', 'me@example.com'); ?>

License

Under BSD-3-Clause license, read LICENSE file.

openbuildings / services-manager

Maintainers

Details

README

Setting up:

Usage:

Addthis

Exceptionalio

Googleanalytics

Kissinsights

Kissmetrics

Mailchimp

License