Another Mautic Guide

17/12/2017

https://developer.mautic.org/#plugin-directory-structure

Mautic Developer Documentation

1/222

17/12/2017


Introduction Welcome to the Mautic Developer Documentation. This documentation will go over how to build a Mautic Plugin that extends the features of Mautic, how to build custom themes, and and how to integrate applications outside of Mautic using its REST API.

Submitting Code to Mautic Development is open and available to any member of the Mautic community. community. All fixes and improvements are done through pull requests to the code on GitHub. This code is open source and publicly available. Read more about the PR process on the Mautic Governance page. The code should try to follow Symfony’s Coding Standards

Symfony Mautic is built on Symfony, the popular PHP framework (Mautic 1.0.x uses Symfony 2.5; Mautic 2.0.x uses Symfony 2.8). This document will go over the basics but most of their documentation applies to Mautic as well which can be used to obtain more advanced Symfony functionality. There are some structural differences between Mautic and standard Symfony. Below is a list of where you will find some of standard Symfony locations in Mautic: Symfony

Mautic

src/

app/bundles (Mautic core) or plugins/ (Mautic plugins)

web/

/

AcmeBundle/Resources/config

AcmeBundle/Config

AcmeBundle/Resources/views

AcmeBundle/Views

AcmeBundle/Resources/public

AcmeBundle/Assets

AcmeBundl AcmeBundle/Reso e/Resources/ urces/transl translation ations/dom s/domain.e ain.en_US. n_US.ini ini

AcmeBundle/ AcmeBundle/Tra Translati nslations/en ons/en_US/ _US/domai domain.ini n.ini

Most of Symfony’s standard locations, such as the Resources/views and Resources/translations directories, should still function with Mautic. However, it may be required to handle service registration, etc with native Symfony processes if not using the Mautic methods defined in this document.

Development Environment SETUP

It is assumed that the system already has composer and git installed and configured. https://developer.mautic.org/#plugin-directory-structure

2/222

17/12/2017


To setup the developer environment, simply fork and clone the source from GitHub. Then Run composer install on the source. Open your browser and complete the installation through the Mautic installer. ENVIRONMENTS

There are three environments in Mautic: prod, dev, and test. prod is used when accessing the site through index.php. dev is used when accessing the site through index_dev.php. Using Mautic in the dev environment will activate Symfony’s profiler toolbar,

has more strict error handling, will display information about exceptions, and will not cache as much (see below). Note that steps should be taken to ensure index_dev.php is not accessible to the public as it could potentially reveal sensitive information. It is restricted to localhost by default. However, there are two ways to allow access to index_dev.php from a non-localhost. The first option is to set a header from the web-server with the IP addresses assigned to MAUTIC_DEV_HOSTS . The second and easier option is to add an array to your installation’s app/config/local.php file as 'dev_hosts' = ['123.123.123.123', '124.124.124.124'], then clear the cache.

test is used mainly for PHP Unit Tests. CACHE

Symfony makes heavy use of a filesystem cache. Frequently clearing this cache will be required when developing for Mautic. By default, the cache is located in app/cache/ENV where ENV is the environment currently accessed (i.e. dev or prod). To To rebuild the cache, the ENV can just be deleted or run the the Symfony command php app/console cache:clear --env=ENV If a specific environment is not passed to the command via --env=ENV , the dev environment will be used by default. In the dev environment, translations, views, and assets are not cached. However, changes to these files will require the cache to be cleared for them to take effect in the prod environment. Changes to Mautic c onfig files, Symfony config files, etc will require the cache to be c leared regardless of environment.



The typical rule of thumb is, if Mautic is not acting as you expect after making changes, try clearing your cache.



If you get class could not be found or cannot redeclare class errors when using the cache:clear command, manually delete the

app/cache/ENV folder then run the command and/or browse to the s ite to rebuild.

Plugins Plugins are bundles that can extend the functionality of Mautic. They can be very simple or very complex and have acc ess to leverage pretty much all that Symfony offers. Just as as reminder, the basics are covered in this document. If more advanced processes are required, the Symfony book and cookbook will be valuable resources.



Mautic plugins are located in the plugins/ directory and must be namespaced with MauticPlugin.

Migrations/Deprecations The following is a list of deprecations and migrations required to support latest versions of Mautic.____ https://developer.mautic.org/#plugin-directory-structure

3/222

17/12/2017


1.2.0

1.2.0 deprecated the Mautic Addon with it’s successor, the Plugin. Mautic addons will continue to work but should be migrated to a plugin before Mautic 2.0 when support will be dropped. The migration path is as follows: 1. Move the plugin from addons/ to plugins/ 2. Replace the namespace MauticAddon with MauticPlugin 3. Replace the MauticFactory getModel() notation of addon. to plugin. 4. Replace the permission notation of addon: to plugin: 5. Change the plugin’s bundle class to extend PluginBundleBase instead of AddonBundleBase 6. In the plugin’s bundle class, use the function’s onPluginInstall() and onPluginUpdate() instead of the deprecated onInstall() and onUpdate() 7. Migrate Entity use of annotations for ORM to the static PHP function loadMetadata() 8. Migrate Entity use of annotations for the serializer (used with the REST API) to the static PHP function loadApiMetadata() 2.0.0

The big ticket item with 2.0.0 is the deprecation of MauticFactory which will be phased out during the 2.x release cycles and to be removed in 3.0. Where possible, please use direct dependency injection of services rather than relying on MauticFactory. MauticFactory. 1. MauticFactory deprecated - use dependency injection of required serv ices. Many MauticFactory helper functions have been replaced with services. 2. Models need to be registered as services using a specific nomenclature. See Models for more information. 3. The static callback function for campaign actions and decisions has been deprecated. Please see Extending Campaigns for more information on the new event based method. (Form submit actions, point triggers, and the like will follow suit with a s imilar migration throughout the lifecycle of 2.0 but for now still uses the static callback method). 4. Minimum PHP version has been increased to 5.6.19 and thus newer PHP code goodies are available for developers (traits, etc) 5. Themes have been completely revamped although the old format is still s upported for now. Please see Themes for the new format. 6. Some routes for /leads/* were removed in favor of /contacts/*. I.e. /api/leads is now /api/contacts, /s/leads is now /s/contacts, and so forth. The route names were also updated. For example, mautic_lead_action is now mautic_contact_action and so forth.

Plugin Directory Structure
The directory structure of an plugin will vary based on the features implemented. At a minimum, the following structure is required: HelloWorldBundle/ - - - Config/ - - - - - config.php - - - HelloWorldBundle.php Read more about the config file. The HelloWorldBundle.php file registers the bundle with Symfony. See the code block for the minimum required code. https://developer.mautic.org/#plugin-directory-structure

4/222

17/12/2017


A typical MVC plugin may look something like: HelloWorldBundle/ - - - Assets/ - - - - - - images/ - - - - - - - - - earth.png - - - - - - - - - mars.png - - - - - - helloworld.js - - - - - - helloworld.css - - - Config/ - - - - - - config.php - - - Controller/ - - - - - - DefaultController.php - - - Model/ - - - - - - ContactModel.php - - - - - - WorldModel.php - - - Translations// - - - - - - en_US/ - - - - - - - - - flashes.ini - - - - - - - - - messages.ini - - - Views/ - - - - - - Contact/ - - - - - - - - - form.html.php - - - - - - World/ - - - - - - - - - index.html.php - - - - - - - - - list.html.php - - - HelloWorldBundle.php - - - HelloWorldEvents.php Each of the other directories and files are explained elsewhere in the document.

Install/Upgrade
$plugin

* @param MauticFactory $factory * @param null

$metadata

*/ static public function onPluginInstall(Plugin $plugin, MauticFactory $factory, $metadata = null) {


5/222

17/12/2017

Mautic Developer Documentation if ($metadata !== null) { self::installPluginSchema($metadata, $factory); } // Do other install stuff

} /** * Called by PluginController::reloadAction when the plugin version does not match what's installed * * @param Plugin

$plugin

* @param MauticFactory $factory * @param null

$metadata

* @param Schema

$installedSchema

* * @throws \Exception */ static public function onPluginUpdate(Plugin $plugin, MauticFactory $factory, $metadata = null, Schema $installedSchema = null) { $db

= $factory->getDatabase();

$platform

= $db->getDatabasePlatform()->getName();

$queries

= array();

$fromVersion

= $plugin->getVersion();

// Simple example switch ($fromVersion) { case '1.0': switch ($platform) { case 'mysql': $queries[] = 'ALTER TABLE ' . MAUTIC_TABLE_PREFIX . 'worlds CHANGE CHANGE description description LONGTEXT DEFAULT NULL'; break; case 'postgresql': $queries[] = 'ALTER TABLE ' . MAUTIC_TABLE_PREFIX . 'worlds ALTER description ALTER TYPE TEXT'; break; } break; } if (!empty($queries)) { $db->beginTransaction(); try { foreach ($queries as $q) { $db->query($q); } $db->commit(); } catch (\Exception $e) { $db->rollback(); throw $e; } } } }

Currently, plugins are installed by uploading the plugin to the plugins folder and the c ache manually deleted ( app/cache/prod ). Then, the admin must click the Install/Upgrade Plugins button in the Plugin manager. When that happens, new plugins found will have the static method onPluginInstall() called from the plugin’s bundle file. If the plugin has already been installed, and the vers ion has changed, then onPluginUpdate() is called.

By default, onPluginInstall() will execute installPluginSchema() . This function will generate and execute schema based on found Entity classes.


6/222

17/12/2017


updatePluginSchema() is

available for use with onPluginUpdate() , however it is not called by default. The reason is that it uses Doctrine to generate schema differences and executes the queries. This is not recommended due to the r isk of Doctrine making incorrect assumptions that will lead to data loss. If updatePluginSchema() is relied upon, it is very important to test thoroughly to ensure the desired outcome. It is recommended to write a migration path for both MySQL and PostgreSQL with native queries instead. ONPLUGININSTALL()

Executed when a plugin is first installed. By default, the plugin’s database schema will be generated and installed based on the Entity class’ loadMetadata function. Argument

Type

Description

$plugin

Mautic\PluginBundle\Entity\Plugin

The plugin entity with information gleaned from the plugin’s config file.

$factory

Mautic\CoreBundle\Factory\MauticFactory

Mautic’s factory class to provide access to Mautic’s services.

$metadata

array\

null

INSTALLPLUGINSCHEMA()

Argument

Type

Description

$metadata

array\

null

$factory



ONPLUGINUPDATE()

Argument

Type

Description

$plugin

Mautic\PluginBundle\Entity\Plugin

The plugin entity with information gleaned from the plugin’s config file.

$factory



$metadata

array\

null

$installedSchema

\Doctrine\DBAL\Schema\Schema

Schema of currently installed tables

UPDATEPLUGINSCHEMA()

Argument

Type

Description

$metadata

array\

null

$installedSchema

\Doctrine\DBAL\Schema\Schema

Schema of currently installed tables

$factory



Plugin Config File Mautic leverages a simple array config file that will register routes, menu items, services and custom configuration parameters. GENERAL


7/222

17/12/2017


'name'

=> 'Hello World',

'description' => 'This is an example config file for a simple Hellow World plugin.', 'author'

=> 'Marty Mautibot',

'version'

=> '1.0.0',

The general config options will define what should be listed in the Plugin manager. The version should be “PHP-standardized” as the Plugin manager will use version_compare() to determine if the onUpdate c allback should be executed. ROUTES

If copying, do not copy

=> array(

'main' => array( 'plugin_helloworld_world' => array( 'path'

=> '/hello/{world}',

'controller' => 'HelloWorldBundle:Default:world', 'defaults'

=> array(

'world' => 'earth' ), 'requirements' => array( 'world' => 'earth|mars' ) ), 'plugin_helloworld_list' 'path'

=> array(

=> '/hello/{page}',

'controller' => 'HelloWorldBundle:Default:index' ), 'plugin_helloworld_admin' => array( 'path'

=> '/hello/admin',

'controller' => 'HelloWorldBundle:Default:admin' ), ), 'public' => array( 'plugin_helloworld_goodbye' => array( 'path'

=> '/hello/goodbye',

'controller' => 'HelloWorldBundle:Default:goodbye' ), 'plugin_helloworld_contact' => array( 'path'

=> '/hello/contact',

'controller' => 'HelloWorldBundle:Default:contact' ) ), 'api' => array( 'plugin_helloworld_api' => array( 'path'

=> '/hello',

'controller' => 'HelloWorldBundle:Api:howdy', 'method'

=> 'GET'

) ) ),

Routes define the URL paths that will be used to execute the plugin’s controller actions. See Routing for specifics on how routes work. FIREWALLS

There are three firewalls to define the routes behind. Firewall main

Description

Secure area of Mautic (/s/ will be auto prepended to the path). The user will be required to login to access this path.


8/222

17/12/2017


Firewall

Description

public

Public access without needing authentication. The URL will be appended directly to Mautic’s base URL.

api

Secure API area of Mautic (/api/ will be auto prepended to the path). OAuth authorization will be required to access the path.

Each firewall accepts an array of defined routes. Each key, the route’s name, must be unique across all bundles and firewalls. Paths must be unique across the same firewall. Order does matter as the first matching route will be used. ROUTE DEFINITIONS

Array Key

Required

Type

Description

path

REQUIRED

string

Defines the path for the URL. Placeholders can be defined using curly brackets. Parameters are passed into the controller function as arguments.

controller

REQUIRED

string

Defines the controller and function to call when the path is accessed. This should be in Symfony’s controller notation of BundleName:ControllerClass:controllerMethod. See Controllers for more information.

method

OPTIONAL

string

Restricts the route to a specific method, i.e. GET, POST, etc

defaults

OPTIONAL

array

Defines default values for path placeholders. If a default is defined, it is not required in the URL. In the code example, /hello will be the same as /hello/earth and the controller’s $world argument will default to ‘earth’ as well.

requirements

OPTIONAL

array

Defines regex matches placeholders must match in order for the route to be recognized. For example, for plugin_helloworld_world in the code example, world is restricted to earth or mars. Anything else will not be recognized by the route.

format

OPTIONAL

string

Sets the request format for the Request response, i.e. Content-Type header. The api firewall will automatically set this to json.

condition

OPTIONAL

string

Very flexible expression to set when the route should match. Refer to Symfony docs.

Note that there are some internally used placeholders that Mautic will set defaults and requirements for (if not overridden by the route) {page} will default to 1 with a requirement of \d+ {objectId} will default to 0 {id} will have a requirement of \d+ if under the api firewall



Each route’s name must be unique across all bundles and firewalls and paths must be unique with the same firewall.



Order does matter. The first route the path matches will be used.

Debugging Routes There are a few CLI commands that make help with debugging routes.

php app/console router:debug

php app/console router:debug article_show

php app/console router:match /blog/my-latest-post


9/222

17/12/2017


MENU

=> array(

'main' => array( 'priority' => 4, 'items'

=> array(

'plugin.helloworld.index' => array( 'id'

=> 'plugin_helloworld_index',

'iconClass' => 'fa-globe', 'access'

=> 'plugin:helloworld:worlds:view',

'parent'

=> 'mautic.core.channels',

'children'

=> array(

'plugin.helloworld.manage_worlds'

=> array(

'route' => 'plugin_helloworld_list' ), 'mautic.category.menu.index' => array( 'bundle' => 'plugin:helloWorld' ) ) ) ) ), 'admin' => array( 'plugin.helloworld.admin' => array( 'route'

=> 'plugin_helloworld_admin',

'iconClass' => 'fa-gears', 'access'

=> 'admin',

'checks'

=> array(

'parameters' => array( 'helloworld_api_enabled' => true ) ), 'priority'

=> 60

) ) ),

Menu defines the menu items to display in the different menus. MENU TYPES

Mautic 2.0 has four customizable menus. Menu Name

Location

main

Main menu on the left

admin

Admin menu accessible through the cogwheel in upper right hand side of Mautic

profile

Profile menu accessible through clicking the username in upper right hand side of Mautic

extra

Displays to the right of the Mautic logo in the upper left hand. Only shows if there are menu items injected.

PRIORITY

To control the placement of the menu item set, set an array with 'priority’ and 'items’ keys. Priority c an be negative to position the items lower than others or positive to position them higher. If the menu items are returned without setting priority, like the admin menu in the c ode example, priority is treated as 9999. To control the priority of individual menu items, set priority it’s definition array. PARENT


10/222

17/12/2017


To place a menu item in another bundles parent menu item, for example Channels or Components, define the parent key with the key of the menu item this item should display under. For example, to show an item under the Channels parent menu item, use 'parent' => 'mau‐ tic.core.channels', . MENU ITEM DEFINITIONS

The menu item’s name should be the language string key that will be displayed as the item’s link. Item definitions: Array Key

Required

Type

Description

route

OPTIONAL

string

The route name as defined in routes. Do not set a route to treat the item as a parent to activate a submenu.

routeParameters

OPTIONAL

array

Route placeholder values to use when generating the URL

id

OPTIONAL

string

Sets the id of the attribute. This will default to what is set as route. This is used in conjuction with returnUrl returned in a controller’s response so that the correct menu item is highlighted when ajax is used to navigate the interface.

iconClass

OPTIONAL

string

Font Awesome class to set the icon for the menu item.

access

OPTIONAL

string

Set the permission required for this item to display to the user currently logged in. Can also set 'admin’ to restrict to Administrators only.

checks

OPTIONAL

array

Restricts display of the link based on either configured parameters or the GET request. It will accept a 'parameters’ and/or 'request’ array of key => value pairs that must be true to display the menu item.

bundle

OPTIONAL

string

Required only for category integration.

parent

OPTIONAL

string

Display this item under another parent menu item.

priority

OPTIONAL

int

Set the priority for ordering this menu item with it’s siblings.

SERVICES

=> array(

'events' => array( 'plugin.helloworld.leadbundle.subscriber' => array( 'class' => 'MauticPlugin\HelloWorldBundle\EventListener\LeadSubscriber' ) ), 'forms'

=> array(

'plugin.helloworld.form' => array( 'class' => 'MauticPlugin\HelloWorldBundle\Form\Type\HelloWorldType', 'alias' => 'helloworld' ) ), 'helpers' => array( 'mautic.helper.helloworld' => array( 'class'

=> 'MauticPlugin\HelloWorldBundle\Helper\HelloWorldHelper',

'alias'

=> 'helloworld'

) ), 'other'

=> array(

'plugin.helloworld.mars.validator' => array( 'class'

=> 'MauticPlugin\HelloWorldBundle\Form\Validator\Constraints\MarsValidator',

'arguments' => 'mautic.factory', 'tag'

=> 'validator.constraint_validator',

'alias'

=> 'helloworld_mars'

)


11/222

17/12/2017

Mautic Developer Documentation )

),

Services are PHP objects stored in the service container and are used all throughout Mautic. They can be as simple or as complex as required. Read more about Symfony’s service container here. SERVICE TYPES

Mautic allows easy configuration for four types of services: Type

Description

events

Defines event subscriber classes used to listen to events dispatched throughout Mautic and auto-tagged with 'kernel.event_subscriber.’ The defined class must extend \Mautic\CoreBundle\EventListener\CommonSubscriber. Read more about subscribers here.

forms

Defines custom form types and auto-tagged with 'form.type.’

helpers

Defines custom template helpers available through the $view variable in views. These services are auto-tagged with 'templating.helper.’

models

Defines model services

other

All other custom services.

SERVICE DEFINITIONS

Each key within the service types array is the name of the service and must be unique. Use the following to define the service: Array Key class

Required

Type

Description

REQUIRED

string

Namespace to the service class (not that it does not start with a backslash)

arguments

OPTIONAL

string or array

String of a single argument to pass to the construct or an array of arguments to pass. Arguments enclosed with %% will be treated as a parameter. To pass a specific string, enclose the argument with double quotations “”. Anything else that is not a boolean or a namespaced class (string with \ in it) will be treated as the name of another registered service. Often, this will simply be mautic.factory.

alias

OPTIONAL

string

Sets the alias used by the service. For example, the key for the template helpers, $view, array or the string to retrieve a specific form type.

tag

OPTIONAL

string

Tags the service used by bundles to get a list of specific services (for example form types and event subscribers).

tags

OPTIONAL

array

Array of of tags

tagArguments

OPTIONAL

array

Array of attributes for the tag. See Symfony docs for more information.

scope

OPTIONAL

string

Defines the service scope. Deprecated.

factory

OPTIONAL

string

Preferred method for using a factory class. Factory class for managing creating the service.

factoryService

OPTIONAL

string

Factory class for managing creating the service. Deprecated; use

factoryMethod

OPTIONAL

string

Method name in the factory service called to create the service. Deprecated; use instead.

methodCalls

OPTIONAL

array

Array of methods to be called after a service is created passing in the array of arguments provided. Should be in the format of 'methodName’ => array('service_name’, ’%parameter%’)


factory instead. factory

12/222

17/12/2017


Array Key

Required

Type

Description

decoratedService

OPTIONAL

array

Decorated service

public

OPTIONAL

bool

Public/private service

lazy

OPTIONAL

bool

Lazy load service

synthetic

OPTIONAL

bool

Synthetic s ervice

synthetic

OPTIONAL

bool

Synthetic s ervice

file

OPTIONAL

string

Include file prior to loading service

configurator

OPTIONAL

array

Use a configurator to load service

CATEGORIES

array( 'plugin:helloWorld' => 'mautic.helloworld.world.categories' ),

Defines category types available or the Category manager. See Extending Categories. PARAMETERS

array( 'helloworld_api_enabled' => false ) );

The parameters array define and set default values for custom configuration parameters specific to the plugin. To obtain the values of these parameters, use the mautic.helper.core_parameters service.



Any parameter to be written to the system’s local config file should be defined here.

Translations Mautic uses INI files for translations. HelloWorldBundle/ - - - Translations/ - - - - - - en_US/ - - - - - - - - - messages.ini



All plugins should include strings for the United States English locale (en_US) as it is the default for the system.


13/222

17/12/2017


The directory structure for translations should be Translations/locale/domain.ini. DOMAINS

Language strings can be organized into domains. Each domain should be its own file in the plugin’s language locale folder(s). The plugin can use any domain it wants but Mautic makes consistent use of three domains: Domain

Description

messages

Default domain for the translator service when no domain is specified

flashes

Domain for flash messages

validators

Domain for form validation messages

INI FILES

Sample INI files

; plugins/HelloWorldBundle/Translations/en_US/messages.ini plugin.helloworld.contact_us="Contact Us" plugin.helloworld.goodbye="Goodbye and have a good day!" plugin.helloworld.greeting="Hello %name%!" plugin.helloworld.index="Hello World" plugin.helloworld.manage_worlds="Manage Worlds" plugin.helloworld.number_of_planets="{0}0 planets|{1}1 planet|]1,Inf[%planets% planets" plugin.helloworld.world="World" plugin.helloworld.worlds="%world% Description"

; plugins/HelloWorldBundle/Translations/en_US/flashes.ini plugin.helloworld.notice.thank_you="Thank you %name% for your interest! We will be in contact soon." plugin.helloworld.notice.planet_demoted="%planet% has been demoted to a dwarf planet." plugin.helloworld.error.planet_demotion_failed="%planet% could not be demoted because the scientists say so."

General guidelines for the translation keys: 1. Segment the key using a period 2. Use underscores to separate words 3. Must be unique 4. Be short yet descriptive 5. Use all lowercase letters and numbers (no punctuation in the key other than period or underscore) Guidelines for translation strings: 1. Wrap placeholders with %% 2. Use a single key for duplicate translation strings. 3. Use “ for double quotes 4. HTML is allowed USING THE TRANSLATOR

Refer to the translator service to learn how to use translations in the code. USING THE TRANSLATOR IN YOUR JAVASCRIPT

If your bundle implements custom javascript where translations are required, you can get them by the Mautic.translate(key, params) method. Create a javascript.ini in the same directory as the messages.ini as described above. Any translation strings added to that file will be available when translating in javascript.


14/222

17/12/2017


For example, if your javascript.ini file contained the following translation strings:

mautic.core.dynamicContent="Dynamic Content" mautic.core.dynamicContent.new="Dynamic Content %number%"

You can request those translation strings in your javascript by passing the key to the Mautic.translate() function.

Mautic.translate("mautic.core.dynamicContent"); // outputs "Dynamic Content"

String interpolation for messages with variables works with js translations just as you’d expect.

Mautic.translate("mautic.core.dynamicContent.new", {number: 4}); // outputs "Dynamic Content 4"

MVC Mautic uses a Model-View-Controller structure to manage user interaction on the frontend (views) with the underlying code processes (controllers and models). (Entity and Repository classes are also used to manage interaction with the database). In Symfony, and thus Mautic, the controller is the center of the MVC structure. The route requested by the user determines the controller method to call. The controller will then communicate with the model to get or manipulate data then display it to the user through the view. CONTROLLERS

getModel('helloworld.world'); // Retrieve details about the world $worldDetails = $model->getWorldDetails($world); return $this->delegateView( array( 'viewParameters' 'world'

=> array(

=> $world,

'details' => $worldDetails ), 'contentTemplate' => 'HelloWorldBundle:World:details.html.php', 'passthroughVars' => array( 'activeLink'

=> 'plugin_helloworld_world',


15/222

17/12/2017

Mautic Developer Documentation 'route'

=> $this->generateUrl('plugin_helloworld_world', array('world' => $world)),

'mauticContent' => 'helloWorldDetails' ) ) ); } /** * Contact form * * @return JsonResponse|\Symfony\Component\HttpFoundation\Response */ public function contactAction() { // Create the form object $form = $this->get('form.factory')->create('helloworld_contact'); // Handle form submission if POST if ($this->request->getMethod() == 'POST') { $flashes = array(); // isFormCancelled() checks if the cancel button was clicked if ($cancelled = $this->isFormCancelled($form)) { // isFormValid() will bind the request to the form object and validate the data if ($valid = $this->isFormValid($form)) { /** @var \MauticPlugin\HelloWorldBundle\Model\ContactModel $model */ $model = $this->getModel('helloworld.contact'); // Send the email $model->sendContactEmail($form->getData()); // Set success flash message $flashes[] = array( 'type'

=> 'notice',

'msg'

=> 'plugin.helloworld.notice.thank_you',

'msgVars' => array( '%name%' => $form['name']->getData() ) ); } } if ($cancelled || $valid) { // Redirect to /hello/world return $this->postActionRedirect( array( 'returnUrl'

=> $this->generateUrl('plugin_helloworld_world'),

'contentTemplate' => 'HelloWorldBundle:Default:world', 'flashes'

=> $flashes

) ); } // Otherwise show the form again with validation error messages } // Display the form return $this->delegateView( array( 'viewParameters'

=> array(

'form' => $form->createView() ), 'contentTemplate' => 'HelloWorldBundle:Contact:form.html.php', 'passthroughVars' => array( 'activeLink' => 'plugin_helloworld_contact', 'route'

=> $this->generateUrl('plugin_helloworld_contact')

) ) );


16/222

17/12/2017


} }

MATCHING ROUTES TO CONTROLLER METHODS

The controller method called is determined by the route defined in the config. Take this example,

plugin_helloworld_admin' => array( 'path' => '/hello/admin', 'controller' => 'HelloWorldBundle:Default:admin' ),

The controller is noted as HelloWorldBundle:Default:admin . Broken down, that will translate to: HelloWorldBundle

\MauticPlugin\HelloWorldBundle\Controller

Default

DefaultController

admin

adminAction()



Controller notation is in the format of BundleName:ControllerName:controllerMethod . To use a controller within a subfolder of

Controller, use BundleName:Subdirectory\ControllerName:controllerMethod .

Thus when a browser calls up /hello/admin , \MauticPlugin\HelloWorldBundle\Controller\DefaultController\adminAction() will be called. What about route placeholders? Symfony is super smart and will pass those into the controller’s method as arguments (the method’s arguments must be the same as the route’s placeholders to be matched up).

'plugin_helloworld_world' => array( 'path' => '/hello/{world}', 'controller' => 'HelloWorldBundle:Default:world', 'defaults' => array( 'world' => 'earth' ), 'requirements' => array( 'world' => 'earth|mars' ) ),

The matching method for that route will look be public function worldAction($world = 'earth') . Notice that because the route defines a default for name , the controller method must also set the same default. If the route looked like this instead:

'plugin_helloworld_world' => array( 'path' => '/hello/{world}', 'controller' => 'HelloWorldBundle:Default:world', 'requirements' => array( 'world' => 'earth|mars' ) ),

Then the method would need to be public function worldAction($world) . EXTENDING MAUTIC’S CONTROLLERS


17/222

17/12/2017


Mautic has several controllers that provide some helper functions. MAUTIC\COREBUNDLE\CONTROLLER\COMMONCONTROLLER

Controllers extending this will make MauticFactory available via $this->factory and Request via $this->request . It also provides the following helper methods: DELEGATEVIEW($ARGS)

Mautic is ajax driven and thus must support both http requests and ajax requests for content. delegateView is wrapper method that determines if the request is for ajax content or the full DOM then generates and returns the appropriate response. The $args argument is an array with the required elements for generating the view, ajax or http. It will accept the following parameters: Key

Required

Type

Description

contentTemplate

REQUIRED

string

Defines the view template to load. This should be in view notation of BundleName:ViewName:template.html.php. Refer to views for more information.

viewParameters

OPTIONAL

array

Array of variables with values made available to the template. Each key will be a variable available to the template.

passthroughVars

OPTIONAL

array

Array of variables returned as part of the ajax response used by Mautic and/or the plugin’s onLoad JS callback.

Due to the use of ajax, there are some elements of the passthroughVars array that Mautic will use internally to manipulate the user interface. For responses that include main content, i.e. routes a user would click to, should set at least activeLink and route . Key

Required

Type

Description

activeLink

OPTIONAL

string

The ID of the menu item that should be activated dynamically to match the ajax response

route

OPTIONAL

string

The route that should be pushed to the browser’s address bar to match the ajax response

mauticContent

OPTIONAL

string

Used to generate the Javascript method to call after the ajax content has been injected into the DOM. The same function will also be called on a page refresh/full page load if set via $view['slots'] in the template. For example, if this is set as helloWorldDetails , Mautic will check for the existence of and executes Mautic.helloWorldDetailsOnLoad() . Refer to Processing Ajax Content for more information regarding this and Asset Helper for injecting assets into the head for ajax generated content.

callback

OPTIONAL

string

A Mautic namespaced JS function that will be executed before the response is injected into the DOM. If set, Mautic will pass the response to the function and not process the content. It will be up to the callback function to handle the rest of the pr ocess.

redirect

OPTIONAL

string

The URL to force a page redirect rather than inject ajax content.

target

OPTIONAL

string

jQuery selector to inject the content into. By default, the app’s main content selector will be used.

replaceContent

OPTIONAL

string

Determines if Mautic should replace the target selector with the ajax content or set as its inner HTML. Return ‘true’ as a string to replace the selector.

DELEGATEREDIRECT($URL)

Delegates the appropriate response for redirects. If an ajax request, a json response with {redirect: $url} will be returned allowing the executing JS code to force the redirect. If an http request, then a redirect response is returned (i.e redirect header). https://developer.mautic.org/#plugin-directory-structure

18/222

17/12/2017


POSTACTIONREDIRECT($ARGS)

Similar to delegateView(), this method will delegate the appropriate response based on the request. This method can be used after performing some action, such as saving a form. It accepts the same elements in the $args array as delegateView() but also accepts the following: Key

Required

Type

returnUrl

OPTIONAL

string

The URL to redirect to. It will default to /s/dashboard if not set. This will also auto-populate passthroughVars[route] passthroughVars[route] if not set.

flashes

OPTIONAL

array

Array of flash messages to display after redirecting. See Flash Messages for more information.

bool

By default, the request is forwarded to a controller method rather than directly loading a view template. This means that contentTemplate contentTemplate should be in controller notation (BundleName:ControllerName:controllerMet (BundleName:ControllerName:controllerMethod) hod) rather than view notation (BundleName:ViewName:templat (BundleName:ViewName:template.html.php). e.html.php). Set this to false to directly load a view template rather than forwarding to another controller.

forwardController

OPTIONAL

Description

MAUTIC\COREBUNDLE\CONTROLLER\FORMCONTROLLER

This controller extends CommonController and provides helper methods for managing forms. See Forms for more information. MAUTIC\COREBUNDLE\CONTROLLER\AJAXCONTROLLER

This controller also extends CommonController and is a companion to some of the built-in Javascript helpers. See Javascript methods for more information. MODELS

mailer; $mailer->message->addTo( $this->factory $this->factory->getParameter ->getParameter('mailer_from_ ('mailer_from_email') email') ); $this->message->setFrom( array($data['e array($data['email'] mail'] => $data['name' $data['name']) ]) ); $mailer->mess $mailer->message->setSubjec age->setSubject($data['subje t($data['subject']); ct']); $mailer->mess $mailer->message->setBody($ age->setBody($data['message' data['message']); ]); $mailer->send();


19/222

17/12/2017


} }

Models are used to retrieve and process data between controllers and views. Models aren’t required for plugins but, if used, Mautic provides means to easily obtain the model objects and some commonly used methods. MODEL CLASSES

Model’s should be registered as model services. The names of these services should match the following nomenclature: mautic.UNIQUE_‐ BUNDLE_IDENTIFIER.model.MODEL_IDENTIFIER. UNIQUE_BUNDLE_IDENTIFIER can be whatever is desired but must be unique across all Mautic bundles and plugins. MODEL_IDENTIFIER just has to be unique for the given bundle. For example, the model example code could be registered as mautic.helloworld.model.contact. This allows the helper functions to retrieve model objects to find the correct model service. Custom models can extend one of two Mautic base models to leverage some helper functions: \MAUTIC\COREBUNDLE\MODEL\ABSTRACTCOMMONMODEL \MAUTIC\COREBUNDLE\MODEL\ABSTRACTCOMM ONMODEL

This is the basic model that mainly provides access to services frequently used with models. Property

Service

$this$this->fa >facto ctory ry

Mautic Mautic’s ’s fact factory ory serv service ice - depr depreca ecated ted as as of 2.0; 2.0; use use direct direct depe depende ndency ncy inject injection ion wher where e possib possible le

$this->em

Entity ma manager se service

$thi $thiss->s >sec ecur urit ity y

Maut Mautic ic’’s secu securi rity ty serv servic ice e

$this$this->di >dispa spatch tcher er

Event Event disp dispatc atcher her servic service e

$thi $thiss->t >tra rans nsla lato torr

Trans ransla lato torr serv servic ice e

\MAUTIC\COREBUNDLE\MODEL\FORMMODEL

The FormModel extends AbstractCommonModel and provides a set of helper methods for interacting with entities and repositories. To read more about these methods, refer to the Database section. GETTING MODEL OBJECTS

getModel('lead'); // shortcut for lead.lead /** @var \Mautic\LeadBundle\Model\ListModel \Mautic\LeadBundle\Model\ListModel $leadListModel */ $leadListModel = $this->getMod $this->getModel('lead.list' el('lead.list'); ); /** @var \MauticPlugi \MauticPlugin\HelloWorldBun n\HelloWorldBundle\Model\Cont dle\Model\ContactModel actModel $contactModel */ $contactModel = $this->getMode $this->getModel('helloworld. l('helloworld.contact'); contact');

If using a model in another service or model, inject the model service as a dependency. dependency. If in a controller, use the getModel() helper function. VIEWS

getRe (!$app->getRequest()->isXml quest()->isXmlHttpRequest()) HttpRequest()) {


20/222

17/12/2017


// Set tmpl for parent template $view['slots $view['slots']->set('tmpl' ']->set('tmpl', , 'Details'); // Extend index.html.php as the parent $view->exten $view->extend('HelloWorldB d('HelloWorldBundle:World:in undle:World:index.html.php'); dex.html.php'); } ?>

extend( $view->extend('MauticCoreBun 'MauticCoreBundle:Default:co dle:Default:content.html.php ntent.html.php'); '); // Get tmpl from sub-template $tmpl = $view['slots $view['slots']->get('tmpl' ']->get('tmpl', , 'Details'); // Tell Mautic to call JS onLoad method $view['slots'] $view['slots']->set('mautic ->set('mauticContent', Content', 'helloWorld'. 'helloWorld'.$tmpl); $tmpl); // Set the page and header title $header = ($tmpl == 'World') ? $view['trans $view['translator']->trans lator']->trans( ( 'plugin.helloworld.worlds', array('%world array('%world%' %' => ucfirst($wor ucfirst($world)) ld)) ) : $view['trans $view['translator']->trans lator']->trans('plugin.hello ('plugin.helloworld.manage_w world.manage_worlds'); orlds'); $view['slots'] $view['slots']->set('header ->set('headerTitle', Title', $header); ?>
rld-content"> output('_co ]->output('_content'); ntent'); ?>

Views take data given it from the controller and displays the content to the user. Templates Templates can be called from the controller or from within other templates. It was discussed in the Controller ’s delegateView() method how to render a view from a controller. Remember that delegateView delegateView uses contentTemplate contentTemplate to determine what view to render. Similar to controller notation, views are noted as HelloWorldBundle:Contact:form.html.php which will point to the file /path/to/mautic/plugins/HelloWorldBundle/Views/Contact/form.html.php.



View notation is in the format of BundleName:ViewName:template.html.php. To To use a view that has been nested in Views, use

BundleName:ViewName\Subfolder:template.html.php.

VIEW PARAMETERS

Remember the array passed via viewParameters in the Controller’s delegateView() method? Here is where the elements of that array will be made available as variables. For example, $world will be available and assigned the value of mars from the following example:

'viewParameters' => array( 'world' => 'mars' ),


21/222

17/12/2017


By default there are a couple variables available and should not be overridden by the controller

Variable

Description

$view

Contains all the helper objects available to templates along with providing methods for extending and/or rendering other templates.

$app

Gives access to request and session to views via $app->getRequest() and $app->getSession()

EXTENDING VIEWS

extend('MauticCoreBun $view->extend('MauticCoreBundle:Default:co dle:Default:content.html.php ntent.html.php'); ');

extend('MauticCoreBun $view->extend('MauticCoreBundle:Default:co dle:Default:content.html.php ntent.html.php'); ');

Because of the use of Ajax, views must also be able to return main content vs the entire document. This is done by extending Mautic’s base templates. Notice the notation is the same as what is used in controllers. To determine if the request is Ajax or not, use $app->getRequest()->isXmlHttpRequest(). Another option is to make the determination in the controller and pass it in the viewParameters array. Of course, this can also be used to extend custom templates as demonstrated in this code example.

The controller should call the sub-template.



It may help to note that extended templates are rendered inside out. So if HelloWorldBundle:World:details.html.php extends

HelloWorldBundle:World:index.html.php which extends MauticCoreBundle:Default:content.html.php, the content of details.html.php

will be rendered first and injected into index.html.php as it is rendered. HelloWorldBundle:World:template1.html.php will be rendered last.

To include the content from the sub-template in the parent template, use $view['slots']->output('_content');. See the Slots Helper for more information. RENDERING VIEWS WITHIN VIEWS

To render the content of another template from within a template, simply use echo $view->render('BundleName:ViewName:template.html.‐ php', array('parameter' => 'value')); TEMPLATE HELPERS

There are a number of template helper objects and helper view templates that are built into Mautic. SLOTS HELPER

set('name', $view['slots']->set('name', 'the content'); // Append content to slot rather than overwrite


22/222

17/12/2017


$view['slots']->append('name', ' and more content'); $view['slots']->append('existingArray', array( 'append' => 'me' ) ); // Get the slot content $content = $view['slots']->get('name', 'default value'); // Output the content; note that echo is not required $view['slots']->output('name'); // Check if a slot exists if ($view['slots']->has('name')) { // Do something }

As seen with extending views, the slots helper is used to pass content up through parent templates. Remember that extended templates are rendered inside out. So, content can be set in a sub template and accessed from the parent template but content set in a parent template, will not be available to the sub-template. ASSET HELPER

getUrl('plugins/HelloWorldBundle/assets/images/earth.png') . '" />'; // Dynamically insert script into head echo $view['assets']->includeScript('plugins/HelloWorldBundle/assets/helloworld.js'); // Dynamically insert stylesheet into head echo $view['assets']->includeStylesheet('plugins/HelloWorldBundle/assets/helloworld.css');

The asset helper, accessed via $view['assets'] , is used to load assets into the DOM including images, script and stylesheets.



$view['assets'] should always be used to ensure that assets work with Mautic installed in the web root, installed in a

subdirectory, ran under the dev environment (index_dev.php), and/or ran under the prod environment.

The asset helper also provides a way to insert scripts and stylesheets into the head for ajax loaded content using $view['assets']->inclu‐ deScript() and $view['assets']->includeStylesheet() . ROUTER HELPER

generate('plugin_helloworld_world', array('world' => 'mars')); ?>" data-toggle="ajax" />Mars

The router helper, $view['router'] , works as explained in the Router. TRANSLATION HELPER

trans('plugin.helloworld.worlds', array('%world%', 'Mars'); ?>

The translation helper, $view['translator'] , works as explained in the Translator section. DATE HELPER


23/222

17/12/2017


toFull($datetime); // Formats per short date system config setting $shortDateTime = $view['date']->toShort($datetime); // Formats per date only system config setting $date = $view['date']->toDate($datetime); // Formats per time only system config setting $time = $view['date']->toTime($datetime); // Formats as date only config setting + time only config setting $datetime = $view['date']->toFullConcat($datetime); // Formats date as Yesterday, 8:02 pm (Today or Tomorrow); otherwise 'x days ago' $text = $view['date']->toText($datetime); // Format a string that is not already in local time $fullDateTime = $view['date']->toFull($datetime, 'Y-m-d H:i:s', 'UTC');

The date helper can be used to format dates based on system and/or user settings. The first argument to the various methods can either be a date/time string or a \DateTime object. If a string, it is expected to be formatted as ‘Y-m-d H:i:s’ and already in the user ’s and/or system’s local time. If it is not, pass the format as the second argument and the timezone (string) as the third. FORM HELPER

form($form); ?>

The form helper, $view['form'] , works as explained in the Form section. VIEW HELPER TEMPLATES

@todo PROCESSING AJAX CONTENT

Mautic provides built in ways to ajaxify links, modals, and forms. AJAX LINKS

generate('plugin_helloworld_world', array('world' => 'mars')); ?>" data-toggle="ajax" />Mars

To ajaxify a link, set the attribute data-target="ajax" AJAX MODALS

generate('plugin_helloworld_world', array('world' => 'mars')); ?>" data-toggle="ajaxmodal" data-target="#MauticSharedModal" data-header="trans('plugin.helloworld.worlds', array('%world%', 'Mars')); ?>">Mars


24/222

17/12/2017


Mautic uses Bootstrap modals but Bootstrap lacks an easy way to dynamically retrieve content more than once. Thus, Mautic provides the attribute data-toggle="ajaxmodal" to help with this. data-target should be the selector of the model to inject the content into. Mautic has a modal, #MauticSharedModal on standby to be used

for this very purpose. data-header will set the modal’s header. AJAX FORMS

When using Symfony’s form services, the form will be auto-ajaxified. AJAX CONTENT CALLBACKS

Mautic.helloWorldDetailsOnLoad = function(container, response) { // Manipulate content }; Mautic.helloWorldDetailsOnUnload = function(container, response) { // Manipulate content };

Mautic provides a way to execute a javascript function after it injects ajax content into the DOM. This can be useful to activate various JS driven features such as typeaheads, charts, bind events, etc. To take advantage of this, utilize the mauticContent element in the passthroughVars array from the controller’s delegateView(). The value of this variable will determine what function should be called after the content has been injected. For example, the method Mautic.helloWorldDetailsOnLoad() will be called for the following:

'passthroughVars' => array( 'activeLink' => 'plugin_helloworld_world', 'route' => $this->generateUrl('plugin_helloworld_world', array('world' => $world)), 'mauticContent' => 'helloWorldDetails' )

When the user browses away from the page, Mautic.helloWorldDetailsOnUnload() will be called to give opportunity to destroy objects if necessary. Both the OnLoad and OnUnload methods are passed two arguments. Argument

Description

container

The selector that was used as the target of the ajax content.

response

The object from the ajax response, i.e. set in the passthroughVars from the Controller

mauticContent should also be set via $view['slots'] in the view’s main page.

$view['slots']->set('mauticContent', 'helloBundleDetails');

Doing so will ensure Mautic.helloWorldDetailsOnLoad() is also called when there is a page refresh.

Services https://developer.mautic.org/#plugin-directory-structure

25/222

17/12/2017


These are the services used commonly throughout Mautic. FACTORY SERVICE

\Mautic\Factory\MauticFactory is deprecated as of 2.0 and will be phased out through 2.x release cycles and completely removed in 3.0.

Direct dependency injection into the services should be used instead where possible. For controllers, extend either \Mautic\CoreBundle\Controller\CommonController or \Mautic\CoreBundle\Controller\FormController and it will be available via $this->factory by default. Otherwise, obtain the factory from the service container via $factory = $this->container>get('mautic.factory');

For models, it will be available via $this->factory by default. For custom services, pass ‘mautic.factory’ as an argument and MauticFactory will be passed into the __construct of the service. USER

get('mautic.helper.user')->getUser(); $firstName = $user->getFirstname(); $lastName

= $user->getLastname();

$email

= $user->getEmail();

$profile

= $user->getProfile();

$role = $user->getRole()->getName(); if ($role->isAdmin()) { // do something }

Service name: mautic.helper.user Class: Mautic\CoreBundle\Helper\UserHelper getUser() will return the entity, \Mautic\UserBundle\Entity\User that can then be used to get information about the currently logged in

user. SECURITY

get('mautic.security'); // Check if user is granted a single permission if ($security->isGranted('plugin:helloWorld:worlds:view')) { // do something } // Check if user is granted multiple permissions (must be granted to all to be true) if ($security->isGranted( array( 'plugin:helloWorld:worlds:view', 'plugin:helloWorld:worlds:create', ) ) ) { //do something } // Check if user is granted to at least one permission if ($security->isGranted( array( 'plugin:helloWorld:worlds:view', 'plugin:helloWorld:worlds:edit', ), 'MATCH_ONE'


26/222

17/12/2017


) ) { //do something } // Get an array of user permissions $permissions = $security->isGranted( array( 'plugin:helloWorld:worlds:view', 'plugin:helloWorld:worlds:edit', ), 'RETURN_ARRAY' ); if ($permissions['plugin:helloWorld:worlds:view']) { // do something } // Check to see if a user is anonymous (not logged in) if ($security->isAnonymous()) { // do something }

Service name: mautic.security Class: Mautic\CoreBundle\Security\Permissions\CorePermissions Using the service to check permissions is explained more in Using Permissions. TRANSLATOR

get('translator'); // Simple string echo $translator->trans('plugin.helloworld.goodbye'); // Simple string with placeholders echo $translator->trans('plugin.helloworld.greeting', array('%name%' => $name)); // String from a domain other than messages (will use planets.ini) echo $translator->trans('plugin.helloworld.worlds', array('%world%' => $world), 'planets'); // Plural translations $planetCount = 3; echo $translator->transChoice('plugin.helloworld.number_of_planets', $planetCount, array('%planets%' => $planetCount)); // Check to see if a translation key exists if ($translator->hasId('plugin.helloworld.goodbye')) { echo $translator->trans('plugin.helloworld.goodbye'); } else { // other logic } // Use the first key if it exists, otherwise use the second (helpful to prevent managing duplicate keys with the same string) echo $translator->transConditional('plugin.helloworld.planets.' . $planet, 'plugin.helloworld.dwarf_planets. ' . $planet);

Service name: translator Class: Mautic\CoreBundle\Translation\Translator Docs: http://symfony.com/doc/2.8/components/translation/usage.html Use the translator service to include translated strings in the code. Depending on where the translation is necessary will determine how to obtain the service. To use the template service in view templates, simply use the template helper, $view['translator'] .


27/222

17/12/2017


The translator service has the following functions to help with translating strings:

Simple translation trans($id, array $parameters = array(), $domain = null, $locale = null)

Pluralization transChoice($id, $number, array $parameters = array(), $domain = null, $locale = null)

Check to see if a key exists hasId($id, $domain = null, $locale = null)

Use the $preferred key if it exists, if not, use $alternative transConditional($preferred, $alternative, $parameters = array(), $domain = null, $locale = null) ROUTER

get('router'); // Relative URL $url = $router->generateUrl('plugin_helloworld_admin'); // URL with placeholders $url = $router->generateUrl('plugin_helloworld_world', array('%world%', 'mars')); // Absolute URL $absoluteUrl = $router->generateUrl('plugin_helloworld_admin', array(), true);

generate('plugin_helloworld_admin'); // result is /hello/admin // Generate a path in a view template $path = $view['router']->path('plugin_helloworld_admin'); // result is /hello/admin $url

= $view['router']->url('plugin_helloworld_admin'); // result is http://yoursite.com/hello/admin

Service name: router Class: Symfony\Bundle\FrameworkBundle\Routing\Router Docs: http://symfony.com/doc/2.8/book/routing.html#generating-urls For views, use the $view['router'] helper. The difference with the template helper is that url() or path() is used instead of generate‐ Url() of the router service. REQUEST

get('request_stack')->getCurrentRequest(); // $_GET $get = $request->query->all(); // $_POST $post = $request->request->all(); // $_COOKIE $cookies = $request->cookies->all(); // $_SERVER $server = $request->server->all(); // Headers


28/222

17/12/2017


$headers = $request->headers->all(); // Attributes - custom parameters $headers = $request->attributes->all(); // Check if a parameter exists if ($request->request->has('hello')) { // do something } // Retrieve value of a specific parameter setting mars as default $world = $request->query->get('world', 'mars'); // Set custom request value $request->attributes->set('hello', 'world'); // Get the value of a nested array $mars = $request->request->get('world[mars]', array(), true);

Service name: request_stack Class: Symfony\Component\HttpFoundation\RequestStack Docs: http://symfony.com/doc/2.8/book/service_container.html#book-container-request-stack There are multiple ways to obtain the request service. If the controller is extending one of Mautic’s controllers, it is already available via $this->request . Alternatively, Symfony will auto-inject the request object into the controller action method if the variable is type-hinted as Symfony\Component\HttpFoundation\Request. For services, pass the request_stack service then use $request = $requestStack->getCurrentRequest(). From within a view, use $app->getRequest() . SESSION

= $this->get('session');

$requestSession = $request->getSession(); // Shortcut to session // Get all session parameters $all = $session->all(); // Get specific parameter setting mars as default $world = $session->get('helloworld.world', 'mars'); // Check if a parameter exists if ($session->has('helloworld.world')) { // do something } // Set a session parameter $session->set('helloworld.world', 'mars'); // Remove a session parameter $session->remove('helloworld.world'); // Clear the whole session $session->clear();

Service name: session Class: Symfony\Component\HttpFoundation\Session Docs: http://symfony.com/doc/2.8/components/http_foundation/sessions.html To access the session service in a view, use $app->getSession() . DATABASE/ENTITY MANAGER


29/222

17/12/2017


= $this->getDoctrine()->getManager();

$repository = $em->getRepository('HelloWorldBundle:World'); $worlds

= $repository->getEntities();

/** @var \MauticPlugin\HelloWorldBundle\Entity\World $world */ foreach ($worlds as $world) { $world->upVisitCount(); } $repository->saveEntities($worlds);

Doctrine includes an ORM and DBAL layers. ORM/entity manager: Service name: doctrine.orm.default_entity_manager Class: Doctrine\ORM\EntityManager DBAL (direct DB driver): Service name: doctrine.dbal.connection Class: Doctrine\DBAL\Connection The entity manager can be used to interact with the bundle’s repositories and entities. See Database for more info. CONFIG PARAMETERS

get('mautic.helper.core_parameters'); $apiEnabled = $config->getParameter('helloworld_api_enabled', false);

Service name: mautic.helper.core_parameters Class: Mautic\CoreBundle\Helper\CoreParametersHelper EVENT DISPATCHER

get('event_dispatcher'); if ($dispatcher->hasListeners(HelloWorldEvents::ARMAGEDDON)) { $event = $dispatcher->dispatch(HelloWorldEvents::ARMAGEDDON, new ArmageddonEvent($world)); if ($event->shouldPanic()) { throw new \Exception("Run for the hills!"); } }

Service name: event_dispatcher Class: Symfony\Component\EventDispatcher\EventDispatcher Implements Symfony\Component\EventDispatcher\EventDispatcherInterface (When type hinting, use this class since different environments may use different classes for the dispatcher) Docs: http://symfony.com/doc/2.8/components/event_dispatcher/introduction.html#dispatch-the-event Dispatch custom events using the event_dispatcher service. PATHS HE LPER

get('mautic.helper.paths');


30/222

17/12/2017


$relativeImagesDir = $pathsHelper->getSystemPath('images'); // media/images $absoluteImageDir

= $pathsHelper->getSystemPath('images', true); // /home/user/public_html/media/images

Service name: mautic.helper.paths Class: Mautic\CoreBundle\Helper\PathsHelper This helper should be used when retrieving system paths for Mautic (images, themes, cache, etc) There is also a tmp or temporary option to store temporary files. It should be used by developers for such use case instead of the general cache location. IP LOOKUP HELPER

get('mautic.helper.ip_lookup'); $requestIp = $ipHelper->getIpAddressFromRequest(); // 1.2.3.4 /** @var \Mautic\CoreBundle\Entity\IpAddress $ipAddressEntity */ $ipAddressEntity = $ipHelper->getIpAddress(); /** @var array $details */ $details = $ipAddressEntity->getIpDetails(); echo $details['city'];

Service name: mautic.helper.ip_lookup Class: Mautic\CoreBundle\Helper\IpLookupHelper This helper can be used to retrieve the real IP for the request. PLUGIN CONFIG HELPER

get('mautic.helper.bundle'); $menu = $configHelper->getBundleConfig('HelloWorldBundle', 'menu', true);

Service name: mautic.helper.bundle Class: Mautic\CoreBundle\Helper\BundleHelper This can be used to get the configuration array of a bundle/plugin’s Config/config.php file. COOKIE HELPER

get('mautic.helper.cookie'); $cookieHelper->setCookie('name', 'value', 3600); $cookieHelper->deleteCookie('name');

Service name: mautic.helper.cookie Class: Mautic\CoreBundle\Helper\CookieHelper The cookie helper can be used to set cookies based on system settings. MAIL HELPER

get('mautic.helper.mailer')->getMailer(); // To address; can use setTo(), addCc(), setCc(), addBcc(), or setBcc() as well


31/222

17/12/2017


$mailer->addTo($toAddress, $toName); // Set a custom from; will use system settings by default $mailer->setFrom( $this->user->getEmail(), $this->user->getFirstName().' '.$this->user->getLastName() ); // Set subject $mailer->setSubject($email['subject']); // Set content $mailer->setBody($content); $mailer->parsePlainText($content); // Optional lead tracking (array) $mailer->setLead($lead); $mailer->setIdHash(); // Send the mail, pass true to dispatch through event listeners (for replacing tokens, etc) if ($mailer->send(true)) { // Optional to create a stat to allow a web view, tracking, etc $mailer->createLeadEmailStat(); } else { $errors = $mailer->getErrors(); $failedRecipients = $errors['failures']; }

get('mautic.helper.mailer')->getMailer(); $failed = array(); $mailer->enableQueue(); foreach ($emailList as $email) { try { if (!$mailer->addTo($email['email'], $email['name'])) { // Clear the errors so it doesn't stop the next send $mailer->clearErrors(); $failed[] = $email; continue; } } catch (BatchQueueMaxException $e) { // Queue full so flush (send) then try again if (!$mailer->flushQueue()) { $errors = $mailer->getErrors(); $failed = array_merge($failed, $errors['failures']); } if (!$mailer->addTo($email['email'], $email['email'], $email['name'])) { // ... } } } // Flush pending if (!$mailer->flushQueue()) { // ... }


32/222

17/12/2017


The mail helper can be used to send email, running the content through the event listeners to search/replace tokens, manipulate the content, etc. Some transports, such as Mandrill, support tokenized emails for multiple recipients. The mail helper makes it easy to leverage this feature by using it’s queue() and flushQueue() functions in place of send() . If sending a batch of emails, it is recommended to use the queue() function. Although these classes will still work with using just send() for one off emails, if sending a batch of the same email to multiple contacts, enable tokenization/batch mode with enableQueue() . If using an Email entity ( \Mautic\EmailBundle\Entity\Email), just pass the Email entity to $mailer->setEmail($email) and the subject, body, assets, etc will be extracted and automatically set. ATTACHMENTS

Attachments can be attached to emails by using the attachFile() function. You can also attach Mautic assets ( \Mautic\AssetBundle\En‐ tity\Asset ) via attachAsset() .

Refer to the class for more details on available functions. MODEL FACTORY

= 'email';

$channelId = 1; if ($modelFactory->hasModel($channel)) { $model = $modelFactory->getModel($channel); if ($entity = $model->getEntity($channelId)) { echo $entity->getName(); } }

Mautic/CoreBundle/Factory/ModelFactory can be used in services that a model dependency is unknown at the time the service is created.

This is great for scenarios where the channel and channel ID are stored in a database and the executing code needs to obtain information on the channel entity (name, etc). It has two methods: hasModel($modelNameKey) and getModel($modelNameKey) . hasModel simple checks to see if a model exists. It uses the same format as using the controller helper method getModel() . For example, to obtain the Mautic\EmailBundle\Model\EmailModel class, you could use something like the c ode example.

Database

33/222

17/12/2017


* @var int */ private $id; /** * @var string */ private $name; /** * @var string */ private $description; /** * @var Category */ private $category; /** * @var int */ private $visitCount; /** * @var int */ private $population = 0; /** * @var bool */ private $isInhabited = false; /** * @param ORM\ClassMetadata $metadata */ public static function loadMetadata (ORM\ClassMetadata $metadata) { $builder = new ClassMetadataBuilder($metadata); $builder->setTable('worlds') ->setCustomRepositoryClass('MauticPlugin\HelloWorldBundle\Entity\WorldRepository'); // Helper functions $builder->addIdColumns(); $builder->addCategory(); $builder->addNamedField('visitorCount', 'int', 'visitor_count'); $builder->addField('population', 'int'); // Native means to build a field $builder->createField('isInhabited', 'bool') ->columnName('is_inhabited') ->nullable(false); } /** * @return mixed */ public function getId() { return $this->id; } /** * @return mixed */ public function getName() { return $this->name;


34/222

17/12/2017


} /** * @param mixed $name * * @return World */ public function setName($name) { $this->name = $name; return $this; } /** * @return mixed */ public function getDescription() { return $this->description; } /** * @param mixed $description * * @return World */ public function setDescription($description) { $this->description = $description; return $this; } /** * @return Category */ public function getCategory() { return $this->category; } /** * @param mixed $category * * @return World */ public function setCategory(Category $category) { $this->category = $category; return $this; } /** * @return mixed */ public function getVisitCount() { return $this->visitCount; } /** * @param mixed $visitCount * * @return World */ public function setVisitCount($visitCount) { $this->visitCount = $visitCount;


35/222

17/12/2017

Mautic Developer Documentation return $this;

} /** * Increase the visit count by one */ public function upVisitCount() { $this->visitCount++; } /** * Get planet population */ public function getPopulation() { return $this->population; } /** * @param int $population * * @return World */ public function setPopulation($population) { $this->population = $population; return $this; } /** * @return boolean */ public function isIsInhabited() { return $this->isInhabited; } /** * @param boolean $isInhabited * * @return World */ public function setIsInhabited($isInhabited) { $this->isInhabited = $isInhabited; return $this; } }


36/222

17/12/2017

Mautic Developer Documentation $q = $this ->createQueryBuilder('w') ->leftJoin('a.category', 'c'); $args['qb'] = $q; return parent::getEntities($args);

} }

Mautic uses Doctrine, a database object relational mapper (ORM) and database abstraction layer (DBAL) library. Most of Mautic use entity and repository classes to define the schema and interact with the database. USAGE

Refer to Symfony’s and Doctrine’s documentation on the specifics of how to interact with the Database. METADATA/SCHEMA

Mautic uses Doctrine’s PHP Driver to define schema. The plugin doesn’t necessarily have to use entities but should at least define Entity classes to create it’s schema. INSTALLING/UPDATING SCHEMA

When an plugin is installed or updated, the bundle’s onInstall or onUpgrade functions are called. These functions can be used to manipulate the database schema. See Install/Upgrade. TABLE PREFIX

Mautic allows custom table prefixes. If using ORM, there is no need to include the prefix as Mautic will automatically handle it. However, if there is a need to use Doctrine’s DBAL layer directly, the contstant MAUTIC_TABLE_PREFIX can be used in conjuction with the table name. ORM ARRAYS AND DATETIME

When using ORM, Mautic will automatically convert DateTime properties to UTC and to the system/user’s profi le timezone on retrieval. However, if using DBAL, DateTime strings must be converted to UTC before persisting and to the local timezone on retrieval. See Date/Time Helper to assist with conversions. For arrays, ORM will auto serialize and unserialize. DBAL will need to manually handle this.

Roles and Permissions Mautic provides a means of defining custom permissions for roles through Permission objects. HOW PERMISSIONS WORK

Permissions are calculated based on bits assigned to an plugin’s level and permission. Bits are integers that increase by doubling the value. 1, 2, 4, 8, 16, 32, 64, 128, 512, 1024, and so forth. The bits should never be assigned numbers in between such as 3 or 5 as the permission will not be correctly calculated in such cases. For example, let’s say HelloWorldBundle needs to manage access to user ’s Worlds entity. A permission set for plugin:helloWorld:worlds might look like Permission

Bit

view

1

edit

2


37/222

17/12/2017


Permission

Bit

create

4

delete

8

full

16



plugin:helloWorld:worlds:view is

a typically notation for requesting permission in Mautic. The notation tells Mautic to check for

the `view` permission for the plugin, HelloWorldBundle, within the `worlds` level. Levels allow plugin’s to set permissions for multiple areas.

Mautic will take the summation of the bits for the permissions given to a role and store it in the database. For example, if a role is given view and edit access, the stored bit is 3. If given view and create access, the stored bit is 5. When a permission check is required, e.g. plugin:helloWorld:worlds:create , Mautic will check if bit of 4 is set in the r ole’s generated bit for plugin:helloWorld:worlds . If so, permission is granted.



The permission full is reserved to grant access to all previous permissions within the level and thus should always be the highest

bit.

USING PERMISSIONS

get('mautic.security'); // Check if user is granted a single permission if ($security->isGranted('plugin:helloWorld:worlds:view')) { // do something } // Check if user is granted multiple permissions (must be granted to all to be true) if ($security->isGranted( array( 'plugin:helloWorld:worlds:view', 'plugin:helloWorld:worlds:create', ) ) ) { //do something } // Check if user is granted to at least one permission if ($security->isGranted( array( 'plugin:helloWorld:worlds:view', 'plugin:helloWorld:worlds:edit', ), 'MATCH_ONE' ) ) { //do something } // Get an array of user permissions $permissions = $security->isGranted( array( 'plugin:helloWorld:worlds:view', 'plugin:helloWorld:worlds:edit',


38/222

17/12/2017


), 'RETURN_ARRAY' ); if ($permissions['plugin:helloWorld:worlds:view']) { // do something } // Check if user has access to view leads if ($security->isGranted('lead:leads:viewother')) { // do something }

To determine if a user has a specific permission, use Mautic’s security service which can be obtained from the mautic.security service. As suggested above, Mautic uses a special permission notation to refer to a specific permission. For core bundles, bundleName:permis‐ sionLevel:permission is used. For plugins, append plugin: , i.e. plugin:bundleName:permissionLevel:permission. plugin: tells Mautic to

look for the permission class in the plugins/ directory and MauticPlugin namespace. The permission level and permissions are set by the core bundle or plugin. For example, Mautic’s core UserBundle has users and roles levels with view , edit , create , delete and full permissions for each. To check if a user has permission to edit roles, use $mauticSecurity->isGranted('user:roles:edit'); CREATING CUSTOM PERMISSIONS

permissions = array( // Custom level 'worlds' => array( // Custom permissions 'use_telescope' => 1, 'send_probe'

=> 2,

'visit'

=> 4,

// Full will almost always be included and should be significantly higher than the // others in case new permissions need to be added later 'full'

=> 1024

) ); // Add standard category permissions $this->addStandardPermissions('categories'); }


39/222

17/12/2017


/** * Append the permission form fields to the Role form * * @param FormBuilderInterface $builder * @param array

$options

* @param array

$data

*/ public function buildForm(FormBuilderInterface &$builder, array $options, array $data) { // Add standard category form fields $this->addStandardFormFields('helloWorld', 'categories', $builder, $data); // Add custom 'worlds' level form fields $builder->add( // Form element name should be bundleName:permissionLevel 'helloWorld:worlds', // Should always be permissionlist type 'permissionlist', array( 'choices' => array( 'use_telescope' => 'plugin.helloworld.permissions.use_telescope', 'send_probe'

=> 'plugin.helloworld.permissions.send_probe',

'visit'

=> 'plugin.helloworld.permissions.visit',

'full'

=> 'mautic.core.permissions.full',

), 'label'

=> 'plugin.helloworld.permissions',

// Set existing data 'data'

=> (!empty($data['worlds']) ? $data['worlds'] : array()),

// Bundle name (used to build frontend form) 'bundle'

=> 'helloWorld',

// Permission level (used to build frontend form) 'level'

=> 'worlds'

) ); } /** * Permission set identifier; should be bundleName * * @return string */ public function getName() { return 'helloWorld'; } }

An plugin can create it’s own set of permissions by creating a Permission class. See the code example for a skeleton outline of what the class will look like. Each permission class should extend Mautic\CoreBundle\Security\Permissions\AbstractPermissions. Then, for most permission classes, three methods are needed: __construct() , buildForm() and getName() . __construct()

The construct method should do two things. It should call parent::__construct($params) or it should set $this->params = $params; . Then it should define $this->permissions . $this->permissions is an array of permission levels that are each arrays with permissions assigned to bits. For example, in the code block, a custom permission level of worlds is defined with the permissions of use_telescope ,


40/222

17/12/2017


send_probe , visit and full . To check to see if a user has permission to the level worlds and permission send_probe , $mauticSecurity>isGranted('plugin:helloWorld:worlds:send_probe') would be used.

Mautic provides a few helper methods for common permission sets: Method

Description

addStandardPermissions()

Set view, edit, create, delete, publish (with option to exclude), and full permissions.

addExtendedPermissions()

Set creator level restrictions: viewown, viewother, editown, editother, create, deleteown, deleteother, publishown (with option to exclude), publishother (with option to exc lude), and full

addManagePermission

Set single manage permission

buildForm() The buildForm method will append the permission toggles to the Role’s form (see Forms for details on form builders). Review the comments in the code sample. There are complimentary helper methods for the common permission sets: Method

Description

addStandardFormFields()

Appends the standard permission sets to the form

addExtendedFormFields()

Appends the extended, aka creator restricted, permissions to the form

addManageFormFields()

Appends the single manager element to the form

getName() This method is absolutely required and s hould match both the bundleName and the name of the file. For example, if Hello‐ WorldBundle is the bundle’s name, then this would be helloWorld with a filename of HelloWorldPermissions.php . PERMISSION ALIASES

To add a permission alias, use the getSynonym() method. Basically this method is called before each requested permission is determined giving opportunity to change the permission level or name as needed. For example, parent::getSynonym() will recognize editown as edit if editown isn’t defined in the permission class’ $this->permissions property for the requested level. MANIPULATING PERMISSIONS BEFORE SAVING

Plugin specific permissions

* @param

$allPermissions

All role permissions

* @param bool

$isSecondRound

Is round two after permissions have been updated by all permission classes

* * @return bool Return true if a second round is required; default false


41/222

17/12/2017


*/ public function analyzePermissions(array &$permissions, $allPermissions, $isSecondRound = false) { foreach ($permissions as $level => &$perms) { foreach ($perms as $perm) { $include = array(); switch ($perm) { case 'send_probe': $include = array('use_telescope'); break; case 'visit': $include = array('use_telescope', 'send_probe'); break; } if (!empty($include)) { foreach ($include as $r) { list($ignore, $r) = $this->getSynonym($level, $r); if ($this->isSupported($level, $r) && !in_array($r, $perms)) { $perms[] = $r; } } } } } // Return true if this method needs a second round after all the other bundles have adjusted permissions return false; }

Plugin’s can adjust permissions based on other selected permissions in order to prevent ‘user er ror.’ For example, if a user has permission to edit , then the user also needs permission to view whether that was selected in the Role form or not. The method analyzePermissions() can be be used for this which gives opportunity to the plugin to modify permissions based on other selections before

persisting to the database. Sometimes, it may be necessary to re-adjust based on a permission that is outside the plugin’s control. In this cas e, analyzePermissions() can return true and it will be called again after all the permissions have been analyzed by the other bundles and plugins. In this case, the argument $isSecondRound will be true. ADVANCED ISGRANTED LOGIC

If it is necessary to perform some logic other than simply comparing bits, the permission class can override the parent’s public function isGranted($userPermissions, $name, $level) and do whatever is necessary for it’s own permission levels and individual permissions. ADVANCED ISSUPPORTED LOGIC

The same can be applied for the method isSupported() which is used to determine if a bundle or plugin includes the requested permission and permission level. This can also be used to provide BC support.

Custom Config Params Mautic’s configuration is stored in app/config/local.php. Plugin’s can leverage custom config parameters to use within it’s code. Each configuration option desired should be defined and have a default set in the plugin’s config file. This prevents Symfony from throwing errors if the parameter is used during cache compilation or if accessed directly from the container without checking if it exists fi rst. Defining the parameters in the plugin’s config file will ensure that it always exists. To add config options to the Configuration page, an event subscriber, a config form type, and a specific view are required.


42/222

17/12/2017 


To translate the plugin’s tab in the configuration form, be s ure to include mautic.config.tab.helloworld_config in the plugin’s

messages.ini file. Of course replace helloworld_config with whatever is used as the formAlias when registering the form in the event subscriber (explained below).

CONFIG EVENT SUBSCRIBER

array('onConfigGenerate', 0), ConfigEvents::CONFIG_PRE_SAVE

=> array('onConfigSave', 0)

); } /** * @param ConfigBuilderEvent $event */ public function onConfigGenerate(ConfigBuilderEvent $event) { $event->addForm( array( 'formAlias'

=> 'helloworld_config',

'formTheme'

=> 'HelloWorldBundle:FormTheme\Config',

'parameters' => $event->getParametersFromConfig('HelloWorldBundle') ) ); } /** * @param ConfigEvent $event */ public function onConfigSave(ConfigEvent $event) { /** @var array $values */ $values = $event->getConfig(); // Manipulate the values if (!empty($values['helloworld_config']['custom_config_option'])) { $values['helloworld_config']['custom_config_option'] = htmlspecialchars($values['helloworld_config']['custom_config_option']); } // Set updated values $event->setConfig($values); } }


43/222

17/12/2017


The event subscriber will listen to the ConfigEvents::CONFIG_ON_GENERATE and ConfigEvents::CONFIG_PRE_SAVE events. The ConfigEvents::CONFIG_ON_GENERATE is dispatched when the configuration form is built giving the plugin an opportunity to inject it’s own tab and config options. To do this, the plugin must register it’s configuration details through the method assigned to the ConfigEvents::CONFIG_ON_GENERATE event. The \Mautic\ConfigBundle\Event\ConfigBuilderEvent object is passed into the method and expects the method to call addForm() . addForm() expects an array with the following elements:

Key

Description

formAlias

Alias of the form type class that sets the expected form elements

formTheme

View to format the configuration form elements, i.e, HelloWorldBundle:FormTheme\Config

parameters

Array of custom config elements. $event->getParametersFromConfig('HelloWorldBundle'))) can be used to glean them from the plugin’s config file.

The ConfigEvents::CONFIG_PRE_SAVE is called before the values from the form are rendered and s aved to the local.php file. This gives the plugin an opportunity to clean up or manipulate the data before it is written. Remember that the subscriber must be registered through the plugin’s config in the services[events] section. CONFIG FORM

$options

*/ public function buildForm(FormBuilderInterface $builder, array $options) { $builder->add( 'custom_config_option', 'text', array( 'label' => 'plugin.helloworld.config.custom_config_option', 'data'

=> $options['data']['custom_config_option'],

'attr'

=> array(

'tooltip' => 'plugin.helloworld.config.custom_config_option_tooltip' ) ) ); } /** * {@inheritdoc} */ public function getName() { return 'helloworld_config'; } }


44/222

17/12/2017


The form type is used to generate the form fields in the main configuration form. Refer to Forms for more information on using form types. Remember that the form type must be registered through the plugin’s config in the services[forms] section. CONFIG TEMPLATE

trans('mautic.config.tab.helloworld_config'); ?>

children as $f): ?>

row($f); ?>

Registering a formTheme as HelloWorldBundle:FormTheme\Config in the event listener told the ConfigBundle to look in the HelloWorldBundle’s Views/FormTheme/Config folder for templates. Specifically, it will look for a template named _config_{formAlias}_wid‐ get.html.php where {formAlias} is the same as formAlias set in the plugin’s ConfigEvents::CONFIG_ON_GENERATE event listener.

The template should be in a panel format to match the rest of the config UI.

Manipulating Contacts (Leads) getModel('lead'); /** @var \Mautic\LeadBundle\Entity\Lead $currentLead */ $currentLead = $leadModel->getCurrentLead(); // To obtain the tracking ID as well, pass true list($currentLead, $trackingId, $trackingIdIsNewlyGenerated) = $leadModel->getCurrentLead(true); // To obtain just the tracking ID; pass true as an argument to force regeneration of the tracking ID and cookies list($trackingId, $trackingIdIsNewlyGenerated) = $leadModel->getTrackingCookie(); // Set the currently tracked lead and generate tracking cookies $lead = new Lead(); // ... $leadModel->setCurrentLead($lead); // Set a lead for system use purposes (i.e. events that use getCurrentLead()) but without generating tracking cookies $leadModel->setSystemCurrentLead($lead);

In Mautic 1.4, Leads were renamed to Contacts. However, much of the code s till refers to contacts as leads. https://developer.mautic.org/#plugin-directory-structure

45/222

17/12/2017


Many plugins extending Mautic will be manipulating leads in one way or another. Here is a quick summary of how to obtain the current lead and/or manipulate the leads data. LEAD TRACKING

Leads are tracked by two cookies. The first cookie notes which ID the lead is tracked under Mautic as. The second is to track the lead’s activity for the current session (defaults to 30 minutes and resets during each lead interaction). mautic_session_id holds

the value of the lead’s current session ID. That value is then name of the cookie that holds the lead’s ID.

Review the sample code on how to obtain the currently tracked lead. As of Mautic 2.2.0, a cookie is also placed on any domain with mtc.js embedded (that’s allowed by Mautic’s CORS settings) as

mtc_id .

This will contain the ID of the currently tracked contact. CREATING NEW LEADS

getModel('lead'); $lead = $leadModel->getCurrentLead(); $leadId = $lead->getId(); // OR generate a completely new lead with $lead = new Lead(); $lead->setNewlyCreated(true); $leadId = null; // IP address of the request $ipAdddress = $this->get('mautic.helper.ip_lookup')->getIpAddress(); // Updated/new fields $leadFields = array( 'firstname' => 'Bob', //... ); // Optionally check for identifier fields to determine if the lead is unique $uniqueLeadFields

= $this->getModel('lead.field')->getUniqueIdentiferFields();

$uniqueLeadFieldData = array(); // Check if unique identifier fields are included $inList = array_intersect_key($leadFields, $availableLeadFields); foreach ($inList as $k => $v) { if (empty($query[$k])) { unset($inList[$k]); } if (array_key_exists($k, $uniqueLeadFields)) { $uniqueLeadFieldData[$k] = $v; } } // If there are unique identifier fields, check for existing leads based on lead data if (count($inList) && count($uniqueLeadFieldData)) { $existingLeads = $this->getDoctrine()->getManager()->getRepository('MauticLeadBundle:Lead')->getLeadsByUniqueFields( $uniqueLeadFieldData, $leadId // If a currently tracked lead, ignore this ID when searching for duplicates ); if (!empty($existingLeads)) { // Existing found so merge the two leads $lead = $leadModel->mergeLeads($lead, $existingLeads[0]); } // Get the lead's currently associated IPs $leadIpAddresses = $lead->getIpAddresses();


46/222

17/12/2017


// If the IP is not already associated, do so (the addIpAddress will automatically handle ignoring // the IP if it is set to be ignored in the Configuration) if (!$leadIpAddresses->contains($ipAddress)) { $lead->addIpAddress($ipAddress); } } // Set the lead's data $leadModel->setFieldValues($lead, $leadFields); // Save the entity $leadModel->saveEntity($lead); // Set the updated lead $leadModel->setCurrentLead($lead);

To create a new lead, use the \Mautic\LeadBundle\Entity\Lead entity. Review the code sample.

Extending Mautic EXTENDING API

=> array(

// ... 'api' => array( 'plugin_helloworld_api' => array( 'path'

=> '/hello/worlds',

'controller' => 'HelloWorldBundle:Api:worlds', 'method'

=> 'GET'

) ) ), // ... );


47/222

17/12/2017


{ if (!$this->get('mautic.security')->isGranted('plugin:helloWorld:worlds:view')) { return $this->accessDenied(); } $filter

= $this->request->query->get('filter', null);

$limit

= $this->request->query->get('limit', null);

$start

= $this->request->query->get('start', null);

/** @var \MauticPlugin\HelloWorldBundle\Model\WorldsModel $model */ $model

= $this->getModel('helloworld.worlds');

$worlds

= $model->getWorlds($filter, $limit, $start);

$worlds

= $this->view($worlds, Codes::HTTP_OK);

return $this->handleView($worlds); } }

To add custom API endpoints, simply define the routes under the API firewall in the plugin’s config file. This will place the route behind /api which will only be accessible if the requester has been authorized via OAuth. The api controller(s), should extend Mautic\ApiBundle\Controller\CommonApiController to leverage the helper methods provided and to utilize the REST views. EXTENDING BROADCASTS

Broadcasts are communications sent in bulk through a channel such as email (segment emails). Mautic 2.2.0 introduced a new event to execute the sending of these bulk c ommunications via the mautic:broadcasts:send command.

model = $model; } /** * {@inheritdoc} */ public static function getSubscribedEvents() { return [ CoreEvents::CHANNEL_BROADCAST => ['onChannelBroadcast', 0] ];


48/222

17/12/2017


}

public function onDataCleanup (ChannelBroadcastEvent $event) { if (!$event->checkContext('world')) { return; } // Get list of published broadcasts or broadcast if there is only a single ID $id

= $event->getId();

$broadcasts = $this->model->getRepository()->getPublishedBroadcasts($id); $output

= $event->getOutput();

while (($broadcast = $broadcasts->next()) !== false) { list($sentCount, $failedCount, $ignore) = $this->model->sendIntergalacticMessages($broadcast[0], null, 100, true, $output); $event->setResults($this->translator->trans('plugin.helloworld').': '.$broadcast[0]->getName(), $sentCount, $failedCount); } } }

To hook into the

mautic:broadcasts:send command,

create a listening for the

\Mautic\CoreBundle\CoreEvents::CHANNEL_BROADCAST event.

The event listener should check for the appropriate context and ID. See example code. EXTENDING CAMPAIGNS

array('onCampaignBuild', 0), HelloWorldEvents::BLASTOFF

=> array('executeCampaignAction', 0),

HelloWorldEvents::VALIDATE_VISIT

=> array('validateCampaignDecision', 0)

); } /** * Add campaign decision and actions * * @param Events\CampaignBuilderEvent $event */ public function onCampaignBuild(Events\CampaignBuilderEvent $event) { // Register custom action $event->addAction( 'helloworld.send_offworld', array( 'eventName'

=> HelloWorldEvents::BLASTOFF,

'label'

=> 'plugin.helloworld.campaign.send_offworld',

'description'

=> 'plugin.helloworld.campaign.send_offworld_descr',


49/222

17/12/2017

Mautic Developer Documentation // Set custom parameters to configure the decision 'formType'

=> 'helloworld_wor 'helloworld_worlds', lds',

// Set a custom formTheme to customize the layout of elements in formType 'formTheme'

=> 'HelloWorldBund 'HelloWorldBundle:FormTheme\S le:FormTheme\SubmitAction', ubmitAction',

// Set custom options to pass to the form type, if applicable 'formTypeOpt 'formTypeOptions' ions' => array( 'world' => 'mars' ) ) ); // Register custom decision (executes when a lead "makes a decision" i.e. executes some direct action $event->addDecision( 'helloworld.visits_mars', array( 'eventName'

=> HelloWorldEvent HelloWorldEvents::VALIDATE_VI s::VALIDATE_VISIT, SIT,

'label'

=> 'plugin.hellowo 'plugin.helloworld.campaign.v rld.campaign.visits_mars', isits_mars',

'description 'description' '

=> 'plugin.hellow 'plugin.helloworld.campaign.v orld.campaign.visits_mars_des isits_mars_descr', cr',

// Same as registering an action 'formType'

=> false,

'formTypeOpt 'formTypeOptions' ions' => array() ) ); } /** * Execute campaign action * * @param CampaignExecuti CampaignExecutionEvent onEvent $event */ public function executeCampai executeCampaignAction gnAction (CampaignExecutionEvent $event) { // Do blastoff $event->setResult(true); } /** * Validate campaign decision * * @param CampaignExecuti CampaignExecutionEvent onEvent $event */ public function validateCampa validateCampaignDecision ignDecision (CampaignExecutionEvent (CampaignExecutionEvent $event) { $valid = ($event->getE ($event->getEventDetails()ventDetails()->getId() >getId() === $event->getCon $event->getConfig()['id']); fig()['id']); $event->setResult($valid); } }

Plugins can add their own campaign actions, decisions, or conditions by listening to the \Mautic\CampaignBundle\CampaignEvents::CAMPAI‐ GN_ON_BUILD event. Read more about listeners and s ubscribers. CAMPAIGN ACTIONS

To add an action, use the $event->addAction($identifier, $parameters) method. $identifier must be something unique. The $parame‐ ters array can contain the following elements:

Key

Required

Type

Description

label

REQU REQUIIRED RED

stri string ng

The The lang langua uage ge stri string ng to use use for for the drag dragga gabl ble’ e’s s lab labe el

eventName

REQUIRED

string

The name of the event that should be dispatched to handle this action. The plugin will need to also create it’s own listener for the event.

description

OPTI OPTION ONA AL

stri string ng

The The lang langua uage ge stri string ng to use use for for the drag dragga gabl ble’ e’s s too toolt ltip ip


50/222

17/12/2017


Key

Required

Type

Description

formType

OPTI OPTION ONAL AL

stri string ng

The The ali alias as of a cus custo tom m for form m typ type e use used d to to set set confi config g opt optio ions ns for for the the deci decisi sion on

formTypeOptions

OPTI OPTION ONAL AL

arra array y

Arra Array y of opti option ons s to incl includ ude e into into the the form formT Type’ ype’s s $opt $optio ions ns argu argume ment nt

formTypeCleanMasks

OPTI OPTION ONA AL

arra array y

Arra Array y of inpu inputt mask asks to clean lean a value alues s from from form ormType

formTypeTheme

OPTIONAL

string

Theme to customize elements for formType

associatedDecisions

OPTIONAL

array

Array of keys registered as decisions that this action can attached to. Defaults to any decision.

anchorRestrictions

OPTIONAL

array

Array of anchors (the places on an event in the builder this action can be attached to). The format is eventType.anchorName. eventType.anchorName. Event types can be source, decision, action, or condition. anchorName includes top, bottom, inaction (yes/green), action (no/red) or leadsource. For example, by passing an array with deci‐ sion.inaction , this action will not be attachable to the inaction/red anchor of a decision.

callback

DEPRECATED

mixed

Deprecated as of 2.0 and support to be removed in 3.0; use eventName instead. Static callback function that will be called for the action and should contain the logic to execute the custom action

The listener for dispatched event will have the Mautic\CampaignBundle\Event\CampaignExecutionEvent injected. To note that the action was successfully executed, use $event->setResult($result) . $result can be a boolean or an array. Setting Setting false will cause the action to be retried. If an array, it will be stored in the campaign event log’s metadata array (useful for displaying information in the contact time-line). Use $event->setFailed() to note that an event failed but should not be retried. Failed events do not appear in a contact’s time-line. time-line. CAMPAIGN DECISIONS

getModel('campaign.ev $this->getModel('campaign.event'); ent'); // Can be anything and passed into action callbacks as $eventDetails $customPassthrough $customPassthrough = array(); // Some optional unique identifier for this specific trigger that is used mainly for debug logging; for example, can be a concatenation of the decision name + lead ID $uniqueTriggerId $uniqueTriggerId

= 'something_something'; 'something_something';

$campaignModel->triggerEven $campaignModel->triggerEvent('helloworld. t('helloworld.visits_mars', visits_mars', $customPassthroughToActions, $customPassthroughToActions, $uniqueTriggerId); $uniqueTriggerId);

Campaign decisions are registered exactly as a campaign action except it uses the $event->addDecision($identifier, $parameters) method. The only difference in the $parameters arguments is that the listener for the eventName is used to validate the decision rather than execute some action and it accepts a associatedActions array instead of associatedDecisions . For example, if the decision is configured to only apply to a specific ID chosen by the user (defined in the formType ), the listener could compare the decision’s $event->getEventDe‐ tails()->getId() (see example) with the event’s $event->getConfig()['id'] . If the decision should execute the actions associated with it, set $event->setResult(true); . Otherwise $event->setResult(false); and nothing will be executed or logged. For custom decisions to work, there must be a trigger executed when the lead makes the decision. Thus, where ever is appropriate in the plugin’s code logic, add something similar to what’s in the example code block. The triggerEvent() method will pull all the triggered decisions ( helloworld.visits_mars in the code example) for published campaigns the lead is in, dispatch the decisions event (if configured) for validation, then execute the associated actions if appropriate. CAMPAIGN CONDITIONS


51/222

17/12/2017


Campaign conditions are registered with addCondition() and accepts the same arguments as addDecision() . The listener also receives an instance of Mautic\CampaignBundle\Event\CampaignExecutionEvent. To To mark a condition as true or false, use $event->setResult($re‐ sult); . EXTENDING CATEGORIES

Mautic has a CategoryBundle that can be leveraged to incorporate categories into a plugin. ADDING CATEGORIES

As of Mautic 1.2.1, register categories through the plugin’s config.php file by adding the following as a key to the returned config array:

'categories' => array( 'plugin:helloWorld' => 'mautic.helloworld.world.categories' ),

The category keys need be prefixed with plugin: as it is used in determining permissions to manage categories. The helloWorld should match the permission class name. CONFIGURING CATEGORIES FOR MENU

It is now recommended to not show the category in the main Menu. To add a category menu item for the plugin, simply add the following to menu config for whichever menu the item should appear ( main or admin ):

'mautic.category.menu.index' => array( 'bundle' => 'plugin:helloWorld' )

The bundle value needs be prefixed with plugin: as it is used in determining permissions to manage categories. The helloWorld should be the bundle name of the plugin. CONFIGURING CATEGORIES FOR ROUTES

There is no need to add custom routes for categories. However, when generating a URL to the plugin’s category list, use

$categoryUrl = $router->generateUrl('mautic_category_index', array('bundle' => 'plugin:helloWorld'));

INCLUDING CATEGORY IN FORMS

To add a category select list to a form, use category as the form type and pass bundle as an option:

//add category $builder->add('category', 'category', array( 'bundle' => 'plugin:helloWorld' ));

RESTRICTING CATEGORY MANAGEMENT

To restrict access to catgories, use the following in the plugin’s Permission class. In __construct() add $this->addStandardPermissions('categories'); then in buildForm() , add $this->addStandardFormFields('hello‐ World', 'categories', $builder, $data);.

See a code example in Roles and Permissions. The two standard helper methods will add the permissions of view , edit , create , delete , publish , and full for categories. EXTENDING CONTACTS (LEADS)


52/222

17/12/2017


CONTACT TIMELINE/HISTORY

['onTimelineG ['onTimelineGenerate', enerate', 0] ]; } /** * Compile events for the lead timeline * * @param LeadTimelineEve LeadTimelineEvent nt $event */ public function onTimelineGenerate(LeadTimelineEvent onTimelineGenerate(LeadTimelineEvent $event) { // Add this event to the list of available events which generates the event type filters $eventTypeKey

= 'visited.worlds 'visited.worlds'; ';

$eventTypeNam $eventTypeName e = $this->transla $this->translator->trans('ma tor->trans('mautic.hello.wor utic.hello.world.visited_wor ld.visited_worlds'); lds'); $event->addEv $event->addEventType($event entType($eventTypeKey, TypeKey, $eventTypeName $eventTypeName); ); // Determine if this event has been filtered out if (!$event->is (!$event->isApplicable($ev Applicable($eventTypeKey)) entTypeKey)) { return; } /** @var \MauticPlugin\ \MauticPlugin\HelloWorldRepo HelloWorldRepository\Entity\ sitory\Entity\WorldRepository WorldRepository $repository */ $repository = $this->em->g $this->em->getRepository(' etRepository('HelloWorldBund HelloWorldBundle:World'); le:World'); // $event->getQueryOptions() $event->getQueryOptions() provide timeline filters, etc. // This method should use DBAL to obtain the events to be injected into the timeline based on pagination // but also should query for a total number of events and return an array of ['total' => $x, 'results' => []]. // There is a TimelineTrait to assist with this. See repository example. $stats = $repository-> $repository->getVisitedWorl getVisitedWorldStats($eventdStats($event->getLead()->ge >getLead()->getId(), tId(), $event->getQu $event->getQueryOptions()); eryOptions()); // If isEngagementCount(), this event should only inject $stats into addToCounter() to append to data to generate // the engagements graph. Not all events are engagements if they are just informational so it could be that this // line should only be used when `!$event->isEngagementCount()`. `!$event->isEngagementCount()`. Using TimelineTrait will determine the appropriate // return value based on the data included in getQueryOptions() if used in the stats method above. $event->addTo $event->addToCounter($event Counter($eventTypeKey, TypeKey, $stats); if (!$event->is (!$event->isEngagementCoun EngagementCount()) t()) { // Add the events to the event array foreach ($stats['results'] ($stats['results'] as $stat) { if ($stat['dateSent']) { $event->addEvent( [ // Event key type 'event'

=> $eventTypeKey,

// Event name/label - can be a string or an array as below to convert to a link


53/222

17/12/2017

Mautic Developer Documentation 'eventLabel'

=> [

'label' => $stat['name'], 'href'

=> $this->router->generate(

'mautic_dynamicContent_action', ['objectId' => $stat['dynamic_content_id'], 'objectAction' => 'view'] ) ], // Translated string displayed in the Event Type column 'eventType'

=> $eventTypeName,

// \DateTime object for the timestamp column 'timestamp'

=> $stat['dateSent'],

// Optional details passed through to the contentTemplate 'extra'

=> [

'stat' => $stat, 'type' => 'sent' ], // Optional template to customize the details of the event in the timeline 'contentTemplate' => 'MauticDynamicContentBundle:SubscribedEvents\Timeline:index.html.php', // Font Awesome class to display as the icon 'icon'

=> 'fa-envelope'

] ); } } } } }

TIMELINE_ON_GENERATE EVENT LISTENER

To inject events into a contact’s timeline, create an event listener that listens to the

LeadEvents::TIMELINE_ON_GENERATE event.

Using this

event, the plugin can inject unique items into the timeline and also into the engagements graph on each page. The event listener will receive a

Mautic\LeadBundle\Event\LeadTimelineEvent object.

Method

The commonly used methods are defined below:

Description

isApplicable

Determines if this event is applicable and not filtered out.

addEventType()

Required - Add this event to the list of available events.

getLead()

Get the Lead entity the event is dispatched for

getQueryOptions()

Used to get pagination, filters, etc needed to generate an appropriate query

addToCounter()

Used to add total number of events (across all pages) to the counters. This also generates the numbers for the engagements graph.

addEvent()

Required - Injects an event into the timeline. Accepts an array with the keys defined as below.

addEvent($event) Key Definitions Key|Required|Type|Description —|——–|—-|———– event|REQUIRED|string|The key for this event. Eg. world.visited eventType |REQUIRED|string|The translated string representing this event type. Eg. Worlds visited timestamp|REQUIRED|\DateTime|DateTime object when this event took place eventLabel|OPTIONAL|string/array|The translated string to display in the event name. Examples include names of items, page titles, etc. This can also be an array of [‘label’ => “, 'href’ => ”] to have the entry converted to a link. This will default to eventType if not defined. extra|OPTIONAL|array|Whatever should be passed through to the content template to generate the details view for this event contentTemplate|OPTIONAL|string|Template that should be used to generate the details view for this event. Eg. HelloBundle:SubscribedEvents\Timeline:index.html.php icon|OPTIONAL|Font Awesome class TIMELINE_ON_GENERATE REPOSITORY METHOD


54/222

17/12/2017


namespace Mautic\LeadBundle\Entity; use Mautic\CoreBundle\Entity\CommonRepository; use Mautic\LeadBundle\Entity\TimelineTrait; /** * Class WorldRepository */ class WorldRepository extends CommonRepository { use TimelineTrait; /** * @param

$leadId

* @param array $options */ public function getTimelineStats($leadId, array $options = []) { $query = $this->getEntityManager()->getConnection()->createQueryBuilder(); $query->select('w.id, w.name, w.visited_count, w.date_visited, w.visit_details') ->from(MAUTIC_TABLE_PREFIX.'world_visits', 'w') ->where($query->expr()->eq('w.lead_id', (int) $leadId)); if (isset($options['search']) && $options['search']) { $query->andWhere( $query->expr()->like('w.name', $query->expr()->literal('%' . $options['search'] . '%')) ); } return $this->getTimelineResults($query, $options, 'w.name', 'w.date_visited', ['visit_details'], ['date_visited']); } }

To assist with the generation of events, the Mautic\LeadBundle\Entity\TimelineTrait has been created. To leverage this, accept the array from $event->getQueryOptions() in the repository method. Create a DBAL QueryBuilder object ( $this>getEntityManager()->getConnection()->createQueryBuilder()) and define the basics of the array, including filtering by lead id and search filter. Then pass the QueryBuilder object to the getTimelineResults() method along with the following arguments: Key

Required

Type

$query

REQUIRED

QueryBuilder

DBAL QueryBuilder object defining basics of the query.

$options

REQUIRED

array

Array generated and passed into method by $event->getQueryOptions() in the event listener above

$eventNameColumn

REQUIRED

string

Name of the column (with table prefix) that should be used when sorting by event name

$timestampColumn

REQUIRED

string

Name of the column (with table prefix) that should be used when sorting by timestamp

$serializedColumns

OPTIONAL

array

When using DBAL, arrays are not auto unserialized by Doctrine. Define the columns here (as returned by the query results) to auto unserialize.

$dateTimeColumns

OPTIONAL

array

When using DBAL, datetime columns are not auto converted to \DateTime objects by Doctrine. Define the columns here (as returned by the query results) to auto do so.

$resultsParserCallback

OPTIONAL

callback

Callback to custom parse a result. This is optional and mainly used to handle a column result when all results are already being looped over for $serializedColumns and $dateTimeColumns.


Description

55/222

17/12/2017


EXTENDING EMAILS

=> array('onEmailBuild', 0),

EmailEvents::EMAIL_ON_SEND

=> array('onEmailGenerate', 0),

EmailEvents::EMAIL_ON_DISPLAY => array('onEmailGenerate', 0) ); } /** * Register the tokens and a custom A/B test winner * * @param EmailBuilderEvent $event */ public function onEmailBuild(EmailBuilderEvent $event) { // Add email tokens $content = $this->templating->render('HelloWorldBundle:SubscribedEvents\EmailToken:token.html.php'); $event->addTokenSection('helloworld.token', 'plugin.helloworld.header', $content); // Add AB Test Winner Criteria $event->addAbTestWinnerCriteria( 'helloworld.planetvisits', array( // Label to group by 'group'

=> 'plugin.helloworld.header',

// Label for this specific a/b test winning criteria 'label'

=> 'plugin.helloworld.emailtokens.',

// Static callback function that will be used to determine the winner 'callback' => '\MauticPlugin\HelloWorldBundle\Helper\AbTestHelper::determinePlanetVisitWinner' ) ); } /** * Search and replace tokens with content * * @param EmailSendEvent $event */ public function onEmailGenerate(EmailSendEvent $event) { // Get content $content = $event->getContent(); // Search and replace tokens $content = str_replace('{hello}', 'world!', $content);


56/222

17/12/2017

Mautic Developer Documentation // Set updated content $event->setContent($content);

} }

There are two way to extend emails: email tokens used to insert dynamic content into an email and a/b test winning criteria . Both leverage the \Mautic\EmailBundle\EmailEvents::EMAIL_ON_BUILD event. Read more about listeners and subscribers. EMAIL TOKENS

Email tokens are placeholders that are inserted into an email that can be replaced by dynamic content when the email is sent or viewed in the browser. $event->addTokenSection($uniqueId, $headerTranslationKey, $htmlContent) is used to generate the section for drag and drop tokens in

the email builder. $uniqueId must be unique. $headerTranslationKey is the translation key that will be used to create the s ection’s header. $htmlContent is the HTML that will be inserted into the builder’s token list for this token’s section. $this->templating->render() can be

used to render a specific view’s content (using view notation. There is free reign as to what the HTML will look like but the important part is that the elements representing the tokens must have the attribute data-token="{token_text}" in order for the builder to recognize them. For example, Translated Token Text CUSTOM TOKEN HANDLING

To convert the token into a link while requesting what the links text should be, use the attributes data-token='%text%' data-drop="showBuilderLinkModal" (replacing hello with the plugin’s custom token).

To request simple feedback from the user and inject it into the token, use the attributes data-token='{hello=%world%}' data-drop="show‐ BuilderFeedbackModal" . A modal will appear with a simple input box. Whatever the user inputs will r eplace %world% .

If you need more control or more customization, create and define a custom JS function within the Mautic namespace (i.e. Mautic.custom‐ Function and use the attribute data-drop="customFunction" . When a user drops the token, Mautic.customFunction() passing the

arguments event (jQuery Event), ui (jQuery UI object with draggable, helper, etc), editorId (ID of the inline CkEditor).

Mautic.customFunction = function (event, ui, editorId) { var token = mQuery(ui.draggable).data('token'); // Do something fancy then insert token Mautic.insertBuilderEditorToken(editorId, token); };

EMAIL A/B TEST WINNER CRITERIA

To add a custom an a/b test winner criteria, i.e. a test to compare specific aspects of an email to determine what made it more successful over it’s variants, use $event->addAbTestWinnerCriteria($uniqueId, $parameters) . $parameters can have the following elements:

Key

Required

Type

group

REQUIRED

string

Translation string to group criteria by in the dropdown select list

label

OPTIONAL

string

Label for this option in the drop down list


Description

57/222

17/12/2017


Key

Required

Type

Description

callback

REQUIRED

mixed

Static callback function that will be called to determine the winner when the email detail page is viewed

formType

OPTIONAL

string

The alias of a custom form type used to set config options for the decision

formTypeOptions

OPTIONAL

array

Array of options to include into the formType’s $options argument

formTypeCleanMasks

OPTIONAL

array

Array of input masks to clean a values from formType

formTypeTheme

OPTIONAL

string


The callback can accept the following variables (determined via ReflectionMethod::invokeArgs()): Variable

Type

Description

$properties

array

Array of elements saved from the configured formType; keyed by email ID in the case of multiple variants

$factory


Mautic’s factory service

$email

Mautic\EmailBundle\Entity\Email

Email entity for the displayed email

$parent

Mautic\EmailBundle\Entity\Email

Email entity for the parent of the email entity

$children

Doctrine\Common\Collections\ArrayCollection

All variants of the parent email

The callback function should return an array keyed with the following elements: Key

Type

Description

winners

array

Array of IDs of the winners (array in case of a tie)

support

mixed

Passed to the view defined by supportTemplate below in order to render visual support for the winners (such as a graph, etc)

supportTemplate

string

View notation to render content for the A/B stats modal. For example, HelloWorldBundle:SubscribedEvents\AbTest:graph.html.php

return array( 'winners' => $winners, 'support' => $support, 'supportTemplate' => 'HelloWorldBundle:SubscribedEvents\AbTest:graph.html.php' );

MONITORED INBOX INTEGRATION

namespace MauticPlugin\HelloWorldBundle\EventListener;

use Mautic\CoreBundle\EventListener\CommonSubscriber; use Mautic\EmailBundle\EmailEvents; use Mautic\EmailBundle\Event\MonitoredEmailEvent; use Mautic\EmailBundle\Event\ParseEmailEvent; use Mautic\EmailBundle\MonitoredEmail\Mailbox;

/** * Class MonitoredInboxSubscriber


58/222

17/12/2017


*/ class MonitoredInboxSubscriber extends CommonSubscriber { private $bundle = 'HelloWorldBundle'; private $monitor =

'deep_space_emails';

/** * @return array */ static public function getSubscribedEvents() { return [ EmailEvents::MONITORED_EMAIL_CONFIG => ['onConfig', 0], EmailEvents::EMAIL_PRE_FETCH

=> ['onPreFetch', 0],

EmailEvents::EMAIL_PARSE

=> ['onParse', 0],

]; } /** * Inject the IMAP folder settings into the Configuration * * @param MonitoredEmailEvent $event */ public function onConfig(MonitoredEmailEvent $event) { /** * The first argument is something unique to recognize this plugin. * The second argument should be something unique to identify this monitored inbox. * The third argument is the label for this monitored inbox. */ $event->addFolder($this->bundle, $this->monitor, 'mautic.world.monitored_deep_space_emails'); } /** * Inject search criteria for which messages to fetch from the configured folder. * * @param ParseEmailEvent $event */ public function onPreFetch(ParseEmailEvent $event) { $event->setCriteriaRequest($this->bundle, $this->monitor, Mailbox::CRITERIA_UNSEEN. " " . Mailbox::CRITERIA_FROM ." aliens@andromeda"); } /** * Parse the messages * * @param ParseEmailEvent $event */ public function onParse(ParseEmailEvent $event) { if ($event->isApplicable($this->bundle, $this->monitor)) { $messages = $event->getMessages(); /** @var \Mautic\EmailBundle\MonitoredEmail\Message $message */ foreach ($messages as $message) { // Do something } } } }

Plugins have access to hook into the

mautic:email:fetch command

to fetch email from a specific inbox/folder and process the content of

the message. Starting in 2.1.1, the plugin also has access to inject specific search criteria for the messages to be processed. To do this, the plugin needs to add an event listener for three events: 1.

EmailEvents::MONITORED_EMAIL_CONFIG This event is dispatched to inject the fields into Mautic’s Configuration to configure the IMAP inbox and folder that should be monitored.


59/222

17/12/2017

2.


EmailEvents::EMAIL_PRE_FETCH This

event is dispatched during the execution of the mautic:email:fetch command. It’s used to inject search criteria for the messages desired. 3. EmailEvents::EMAIL_PARSE This event parses the messages fetched by the command. EXTENDING FORMS

array('onFormBuilder', 0) ); } /** * Add a simple email form * * @param FormBuilderEvent $event */ public function onFormBuilder(Events\FormBuilderEvent $event) { // Register a form submit actions $event->addSubmitAction( 'helloworld.sendemail', [ // Label to group by in the dropdown 'group'


// Label to list by in the dropdown 'label'

=> 'plugin.helloworld.formaction.send_email',

'description' => 'plugin.helloworld.formaction.send_email_descr', // Form service for custom config options 'formType'

=> 'helloworld_worlds',

'formTheme'

=> 'HelloWorldBundle:FormTheme\SubmitAction',

// Callback method to be executed after the submission 'eventName'

=> HelloWorldEvents::FORM_SUBMIT_ACTION

] ); // Register a custom validation service $event->addValidator( 'helloworld.customfield', [ 'eventName' => HelloWorldEvents::FORM_VALIDATION, 'fieldType' => 'helloworld.customfield' // Optional - otherwise all fields will be sent through this listener for validation ] ); // Register a custom form field


60/222

17/12/2017

Mautic Developer Documentation $event->addFormField( 'helloworld.customfield', [ // Field label 'label'

=> 'plugin.helloworld.formfield.customfield',

// Form service for the field's configuration 'formType' => 'helloworld_worlds', // Template to use to render the formType 'template' => 'HelloWorldBundle:SubscribedEvents\FormField:customfield.html.php' ] ); } }

Forms can be extended by listening to the \Mautic\FormBundle\FormEvents::FORM_ON_BUILD event. Read more about listeners and subscribers. FORM FIELDS

To add a custom form field, use the $event->addFormField($identifier, $parameters) method. $identifier must be something unique. The $parameters array can contain the following elements: Key

Required

Type

label

REQUIRED

string

The language string for the option in the dropdown

formType

REQUIRED

string

The alias of a custom form type used to set config options

formTypeOptions

OPTIONAL

array


formTypeCleanMasks

OPTIONAL

array


formTypeTheme

OPTIONAL

string


template

REQUIRED

string

View template used to render the formType

valueFilter

OPTIONAL

mixed

Filter to use to clean the submitted value as supported by InputHelper or a callback function that accepts the arguments \Mautic\FormBundle\Entity\Field $field and $value .

valueConstraints

OPTIONAL

mixed

Callback function to use to validate the value; the function should accept the arguments \Mautic\FormBundle\Entity\Field $field and $filteredValue .

array

Array of boolean options for the form builder: addHelpMessage = true/false addShowLabel = true/false addDefaultValue = true/false addLabelAttributes = true/false addInputAttributes = true/false addIsRequired = true/false

builderOptions

OPTIONAL

Description

FORM SUBMIT ACTIONS

To add an action, use the $event->addSubmitAction($identifier, $parameters) method. $identifier must be something unique. The $parameters array can contain the following elements: Key

Required

Type

label

REQUIRED

string


description

OPTIONAL

string

The language string to use for the option’s tooltip


Description

61/222

17/12/2017


Key

Required

Type

Description

eventName

REQUIRED

string

This is the custom event name that will be dispatched to handle this action ( call‐ back has been deprecated)

formType

OPTIONAL

string

The alias of a custom form type used to set config options

formTypeOptions

OPTIONAL

array


formTypeCleanMasks

OPTIONAL

array


formTypeTheme

OPTIONAL

string


template

OPTIONAL

string


validator

DEPRECATED

mixed

Static callback function called to validate the form submission. Deprecated Register a validator using the $event->addValidator() .

callback

DEPRECATED

mixed

Static callback function called after a submission (submit action logic goes here). Deprecated - use eventName instead.

The subscriber registered to listen to the eventName will be passed an instance of Mautic\FormBundle\Events\SubmissionEvent with the details about the post. Sometimes, it is necessary to handle something after all the other submit actions have done their thing - like redirect to another page. This is done by registering a post submit callback through the subscriber that processes the action. You can either inject the Symfony\Com‐ ponent\HttpFoundation\Response at that time with $event->setPostSubmitCallbackResponse($response); or register another custom event to be dispatched after all submit actions have been processed using $event->setPostSubmitCallback($key, ['eventName' => HelloWorld::ANOTHER_CUSTOM_EVENT]);. FORM VALIDATIONS

To add a custom validation, use the $event->addValidator($identifier, $parameters) method. $identifier must be something unique. The $parameters array can contain the following elements: Key

Required

Type

Description

eventName

REQUIRED

string

The name of the custom event that will be dispatched to validate the form or specific field

fieldType

optional

string

The key to a custom form type (for example something registered by addFormField() ) to limit this listener to. Otherwise every field will be sent to listener.

The listener for the form event will receive a Mautic\FormBundle\Event\ValidationEvent object. Obtain the field with $event->getField(); do the logic then to fail a validation, execute $event->failedValidation('I said so.');. EXTENDING INTEGRATIONS


62/222

17/12/2017


/** * Returns the name of the social integration that must match the name of the file * For example, IcontactIntegration would need Icontact here * * @return string */ public function getName() { return 'Mars'; } /** * Display name for the integration which defaults to getName() unless defined here */ public function getDisplayName() { return 'Red Mars' } /** * Get the type of authentication required for this API.

Values can be none, key, oauth2 or callback

* (will call $this->authenticationTypeCallback) * * @return string */ public function getAuthenticationType() { return 'oauth2'; } /** * OAuth2 authentication URL */ public function getAuthenticationUrl() { return 'https://somesite.com/oauth/authorize'; } /** * OAuth2 access token URL */ public function getAccessTokenUrl() { return 'https://somesite.com/oauth/access_token'; } /** * Get a list of supported features for this integration * * @return array */ public function getSupportedFeatures() { return array( 'public_profile', 'public_activity' ); } }

Integrating 3rd party services in Mautic can be done by defining an Integration class for the service. For example, the MauticSocialBundle has several social media service classes defined in \Plugins\MauticSocialBundle\Integration. Each integration class handles the authorization process, integration configuration, etc. INTEGRATION CLASS

Each plugin can have multiple integrations by defining each as it’s own Integration class in the bundle’s Integration folder. The class should extend \Mautic\PluginBundle\Integration\AbstractIntegration . It defines the integration and provides a number of helper functions https://developer.mautic.org/#plugin-directory-structure

63/222

17/12/2017


including OAuth authorization/request signing functions. INTEGRATION IMAGE

Each integration is displayed on a “card” in the Manage Plugins area. To set an image for the integration, include an image in the bundle’s Assets\img. It should be 128x128px, be in a png, and have the same name as returned by getName() as lower case. For example, \Mau‐ ticPlugin\HelloWorldBundle\Integration\MarsIntegration should have an image plugins\HelloWorldBundle\Assets\img\mars.png. AUTHORIZATION

Out of the box, the AbstractIntegration class can handle standard key, OAuth1a, and OAuth2 specifications. The authorization type is defined by the getAuthenticationType() function. Each input required by the user (i.e username, password, etc) are defined by an array of keyName => label elements returned by getRequiredKeyFields() . This function is not required if using standard specs of key, OAuth1a, or OAuth2. FUNCTIONS

Some of the main functions used are described below. Review the AbstractIntegration class and the functions docblocks for more details. Keys saved by the integration are encrypted. To access the unencrypted vers ions in the Integration class, use the array $this->keys . Any of the functions defined in AbstractIntegration can be overridden per special needs of the specific Integration being implemented. Area

Function

Description

Auth

getRequiredKeyFields

Returns an array of keyName => label elements for settings required from the user, i.e. username, password, client id, client secret, key, etc. Each element will be displayed as an input in the integration’s settings.

Auth

getSecretKeys

Any keyName returned by getRequiredKeyFields that is considered secret or a password should be returned in an array by this function so that it’s properly masked in the form.

Auth & Request

getClientIdKey

Used to define the “username” for the integration. It defaults to ‘client_id’ for authentication type oauth2 and 'keyName’ for the keyName authentication type.

Auth & Request

getClientSecretKey

Used to define the “password” for the integration. By default, only oauth2 uses this and returns 'client_secret’.

Auth

getAuthLoginUrl

Defines the login URL for the oauth1a spec

Auth

getRequestToken

Used by the oauth1a spec to retrieve a request token during authorization

Auth

getRequestTokenUrl

Used by the oauth1a spec to define the request token URL

Auth

getAuthenticationUrl

Defines the login URL for the oauth2 spec

Auth

getAccessTokenUrl

Defines the access token URL for the oauth2 spec

Auth

getAuthScope

Defines the scope for the oauth2 spec

Auth

getAuthCallbackUrl

Used to define the callback URL for oauth1a or oauth2 specs. This defaults to the mautic_integration_auth_callback route.

Auth

prepareResponseForExtraction

Called by extractAuthKeys() to manipulate the data prior to check ing validating the response by checking that the keyName returned by getAuthTokenKey() is part of the response. If not, it calls getErrorsFromResponse().

Auth

getErrorsFromResponse

Called by extractAuthKeys() to extract errors from the response into a string.

Auth & Request

prepareRequest

Called by makeRequest() to manipulate or prepare parameters, settings, headers, etc before sending to the URL

Auth & Request

parseCallbackResponse

Called by makeRequest() to parse the response for the request into an array.


64/222

17/12/2017


Area

Function

Description

Auth & Request

getAuthTokenKey

Returns the keyName that’s used to sign a request. Used by oauth1a (oauth_token) and oauth2 (access_token) specs.

Request

getBearerToken

Generate a bearer token if required by the oauth2 spec

General

isConfigured

Called to determine if the integration has been correctly configured.

General

isAuthorized

Called to determine if the integration is authorized (or peforms a reauth if an oauth2 spec has refresh tokens stored)

Request

makeRequest

Can be used to make API requests. It automatically handles standard key, oauth1a and oauth2 specs.

Form

getFormSettings

Returns an array of options of what to display in integration’s configuration form. The two options used at this time is requires_callback (true to show a readonly input with the callback returned by getAuthCallbackUrl()) and requires_authorization (true to display the authorization button).

Form

getFormNotes

Returns an array of “helper notes” to display in the various areas of the form.

MAKEREQUEST()

makeRequest() can be used to automatically sign outgoing requests and/or authentication processes. Of course, any integration can inherit and override this class to suit the integrations needs. It accepts the following parameters: Name

Type

Description

$url

string

The url to make the request to

$parameters

array

An array of parameters to submit with the request. If $method is GET, these will be appended to the query string. Otherwise, they will be part of the POST body.

$method

string

The request method i.e. get, post, put, patch, delete

$settings

array

Configures the behavior of the makeRequest function. Built in optional settings are below.

SETTINGS

Key

Type

Description

auth_type

string

Overrides the authentication type for the request. If not set, getAuthenticationType() is used.

query

array

Append parameters to the query of the request URL.

content_type

string

Sets the content type header for the request.

encode_parameters

string

If set to json, parameters in the POST will be json encoded prior to making the request.

headers

array

Array of custom headers to append to the request.

ssl_verifypeer

bool

Set the CURLOPT_SSL_VERIFYPEER to true.

curl_options

array

Custom set of curl options to apply to the request.

return_raw

bool

If true, return the response rather than running it through parseCallbackResponse first.

authorize_session

bool

Used by prepareRequest() and parseCallbackResponse() to change the behavior based on whether the if the request is obtaining authorization or just making an API call.


65/222

17/12/2017


EXTENDING MAINTENANCE CLEANUP

$db

*/ public function __construct(MauticFactory $factory, Connection $db) { parent::__construct($factory); $this->db = $db; } /** * {@inheritdoc} */ public static function getSubscribedEvents() { return [ CoreEvents::MAINTENANCE_CLEANUP_DATA => ['onDataCleanup', -50] ]; } /** * @param $isDryRun * @param $date * * @return int */ public function onDataCleanup (MaintenanceEvent $event) { $qb = $this->db->createQueryBuilder() ->setParameter('date', $event->getDate()->format('Y-m-d H:i:s')); if ($event->isDryRun()) { $rows = (int) $qb->select('count(*) as records') ->from(MAUTIC_TABLE_PREFIX.'worlds', 'w') ->where( $qb->expr()->gte('w.date_added', ':date') ) ->execute() ->fetchColumn(); } else { $rows = (int) $qb->delete(MAUTIC_TABLE_PREFIX.'worlds') ->where( $qb->expr()->lte('date_added', ':date') )


66/222

17/12/2017


->execute(); } $event->setStat($this->translator->trans('mautic.maintenance.hello_world'), $rows, $qb->getSQL(), $qb->getParameters()); }

}

To hook into the mautic:maintenance:cleanup command, create a listening for the \Mautic\CoreBundle\CoreEvents::MAINTENANCE_CLEA‐ NUP_DATA event. The event listener should check if data should be deleted or a counted. Use $event->setStat($key, $affectedRows, $sql, $sqlParameters) to give feedback to the CLI command. Note that $sql and $sqlParameters are only used for debugging and shown only in the dev environment.



The plugin should check if a dry run is requested using `$event->isDryRun()` before deleting records!

EXTENDING LANDING PAGES

=> array('onPageBuild', 0),

PageEvents::PAGE_ON_DISPLAY => array('onPageDisplay', 0) ); } /** * Register the tokens and a custom A/B test winner * * @param PageBuilderEvent $event */ public function onPageBuild(PageBuilderEvent $event) { // Add page tokens $content = $this->templating->render('HelloWorldBundle:SubscribedEvents\PageToken:token.html.php'); $event->addTokenSection('helloworld.token', 'plugin.helloworld.header', $content); // Add AB Test Winner Criteria $event->addAbTestWinnerCriteria( 'helloworld.planetvisits', array( // Label to group by 'group'


// Label for this specific a/b test winning criteria 'label'

=> 'plugin.helloworld.pagetokens.',


67/222

17/12/2017

Mautic Developer Documentation // Static callback function that will be used to determine the winner 'callback' => '\MauticPlugin\HelloWorldBundle\Helper\AbTestHelper::determinePlanetVisitWinner' ) );

} /** * Search and replace tokens with content * * @param PageSendEvent $event */ public function onPageDisplay(PageSendEvent $event) { // Get content $content = $event->getContent(); // Search and replace tokens $content = str_replace('{hello}', 'world!', $content); // Set updated content $event->setContent($content); } }

There are two way to extend pages: page tokens used to insert dynamic content into a page and a/b test winning criteria . Both leverage the \Mautic\PageBundle\PageEvents::PAGE_ON_BUILD event. Read more about listeners and subscribers. PAGE TOKENS

Page tokens are handled exactly the same as Email Tokens. PAGE A/B TEST WINNER CRITERIA

Custom landing page A/B test winner criteria is handled exactly the same as page A/B test winner criteria with the only differences being that the callback function is passed Mautic\PageBundle\Entity\Page $page and Mautic\PageBundle\Entity\Page $parent instead. Of course $children is an ArrayCollection of Page entities as well. EXTENDING POINTS

Custom point actions and triggers can be added by listening to their respective on build events. Read more about listeners and subscribers. POINT ACTIONS

To add a custom point action used to give a lead x points for doing a certain action, add a listener to the \Mautic\PointBundle\PointE‐ vents::POINT_ON_BUILD event then configure the custom point action with $event->addAction($identifier, $parameters) method. $iden‐ tifier must be something unique. The $parameters array can contain the following elements: Key

Required

Type

Description

label

REQUIRED

string


formType

OPTIONAL

string

The alias of a custom form type used to set config options.

formTypeOptions

OPTIONAL

array


formTypeCleanMasks

OPTIONAL

array


formTypeTheme

OPTIONAL

string


template

OPTIONAL

string


callback

OPTIONAL

mixed

Static callback function used to validate the action. Return true to add the points to the lead.

In order for the custom point action to work, add something like the following in the code logic when the lead executes the custom action: https://developer.mautic.org/#plugin-directory-structure

68/222

17/12/2017


$this->getModel('point')->triggerAction('page.hit', $event->getHit()); POINT TRIGGERS

To add a custom point trigger used to execute a specific action once a lead hits X number of points, add a listener to the \Mautic\Point‐ Bundle\PointEvents::TRIGGER_ON_BUILD event then configure the custom point trigger with $event->addEvent($identifier, $parameters) method. $identifier must be something unique. The $parameters array can contain the following elements: Key

Required

Type

Description

label

REQUIRED

string


formType

OPTIONAL

string

The alias of a custom form type used to set config options.

formTypeOptions

OPTIONAL

array


formTypeCleanMasks

OPTIONAL

array


formTypeTheme

OPTIONAL

string


template

OPTIONAL

string


callback

OPTIONAL

mixed

Static callback function used to execute the custom action.

EXTENDING REPORTS

=> array('onReportBuilder', 0),

ReportEvents::REPORT_ON_GENERATE

=> array('onReportGenerate', 0),

ReportEvents::REPORT_ON_GRAPH_GENERATE => array('onReportGraphGenerate', 0) ); } /** * Add available tables, columns, and graphs to the report builder lookup * * @param ReportBuilderEvent $event * * @return void */ public function onReportBuilder (ReportBuilderEvent $event)


69/222

17/12/2017


{ // Use checkContext() to determine if the report being requested is this report if ($event->checkContext(array('worlds'))) { // Define the columns that are available to the report. $prefix

= 'w.';

$columns = array( $prefix . 'visit_count' => array( 'label' => 'mautic.hellobundle.report.visit_count', 'type'

=> 'int'

), $prefix . 'world' => array( 'label' => 'mautic.hellobundle.report.world', 'type'

=> 'text'

), ); // Several helper functions are available to append common columns such as categories, publish state fields, lead, etc.

Refer to the Report‐

BuilderEvent class for more details. $columns = $filters = array_merge($columns, $event->getStandardColumns($prefix), $event->getCategoryColumns()); // Optional to override and update filters, i.e. change it to a select list for the UI $filters[$prefix.'world']['type'] = 'select'; $filters[$prefix.'world']['list'] = array( 'earth' => 'Earth', 'mars'

=> 'Mars'

); // Add the table to the list $event->addTable('worlds', array( 'display_name' => 'mautic.helloworld.worlds', 'columns'

=> $columns,

'filters'

=> $filters // Defaults to columns if not set

) ); // Register available graphs; can use line, pie, or table $event->addGraph('worlds', 'line', 'mautic.hellobundle.graph.line.visits'); } } /** * Initialize the QueryBuilder object used to generate the report's data. * This should use Doctrine's DBAL layer, not the ORM so be sure to use * the real schema column names (not the ORM property names) and the * MAUTIC_TABLE_PREFIX constant. * * @param ReportGeneratorEvent $event * * @return void */ public function onReportGenerate (ReportGeneratorEvent $event) { $context = $event->getContext(); if ($context == 'worlds') { $qb = $event->getQueryBuilder(); $qb->from(MAUTIC_TABLE_PREFIX . 'worlds', 'w'); $event->addCategoryLeftJoin($qb, 'w'); $event->setQueryBuilder($qb); } } /** * Generate the graphs * * @param ReportGraphEvent $event * * @return void


70/222

17/12/2017


*/ public function onReportGraphGenerate (ReportGraphEvent $event) { if (!$event->checkContext('worlds')) { return; } $graphs

= $event->getRequestedGraphs();

$qb

= $event->getQueryBuilder();

foreach ($graphs as $graph) { $queryBuilder = clone $qb; $options

= $event->getOptions($graph);

/** @var ChartQuery $chartQuery */ $chartQuery

= clone $options['chartQuery'];

$chartQuery->applyDateFilters($queryBuilder, 'date_added', 'v'); switch ($graph) { case 'mautic.hellobundle.graph.line.visits': $chart = new LineChart(null, $options['dateFrom'], $options['dateTo']); $chartQuery->modifyTimeDataQuery($queryBuilder, 'date_added', 'v'); $visits = $chartQuery->loadAndBuildTimeData($queryBuilder); $chart->setDataset($options['translator']->trans('mautic.hellobundle.graph.line.visits'), $visits); $data

= $chart->render();

$data['name'] = $graph; $data['iconClass'] = 'fa-tachometer'; $event->setGraph($graph, $data); break; } } } }

Adding and rendering custom reports are done by listening to the \Mautic\ReportBundle\ReportEvents::REPORT_ON_BUILD , ReportEvents::REPORT_ON_GENERATE and ReportEvents::REPORT_ON_GRAPH_GENERATE events. DEFINING THE REPORT

Defining the report is done through the ReportEvents::REPORT_ON_BUILD event. This is where the plugin will define the context of the report, available columns for table data, available filters for the table data (defaults to columns) and available graphs. See the code example’s on‐ ReportBuilder for details. COLUMN DEFINITION

Each column array can include the following properties: Key

Required

Type

Description

label

REQUIRED

string

The language string for the column

type

REQUIRED

string

Column type

alias

OPTIONAL

string

An alias for the returned value. Useful in conjuction with formula

formula

OPTIONAL

string

SQL formula instead of a column. e.g. SUBSTRING_INDEX(e.type, \'.\', 1)

link

OPTIONAL

string

Route name to convert the value into a hyperlink. Used usually with an ID of an Entity. The route must accept objectAction and objectId parameters.

FILTER DEFINITION

Filter definitions are optional as Mautic will default to the column list. But sometimes it’s useful to replace filter values with a select list. Filter definitions can accept the same properties as columns but can also accept the following: https://developer.mautic.org/#plugin-directory-structure

71/222

17/12/2017

Key


Required

Type

Description

list

OPTIONAL

array

Used when type is select for a filter. Provides the dropdown options for a select input. Format should be value => label

operators

OPTIONAL

array

Custom list of operators to allow for this filter. See Mautic\ReportBundle\Builder\MauticReport‐ Builder::OPERATORS for a examples.

GENERATE THE QUERYBUILDER

The ReportEvents::REPORT_ON_GENERATE event is dispatched when a report is to be generated and displayed. In this function, the plugin should define the QueryBuilder object used to generate the table data. Use $event->checkContext() to determine if the report requested is the subscribers report.

Note that the ReportEvents::REPORT_ON_GENERATE event should use Doctrine’s DBAL layer QueryBuilder obtained via $qb =



$event->getQueryBuilder(); .

There are a number of helper functions to append joins for commonly used relationships such as category, leads, ip address, etc. Refer to the ReportGeneratorEvent class for more details. GRAPHS

Graphs are generated using ReportEvents::REPORT_ON_GRAPH_GENERATE event. The listener should check the context then generate and set the graph data. There are several classes to assist with generating classes. See EXTENDING WEBHOOKS

Webhooks allow for Mautic to send data to external services via an endpoint url. Webhooks work by using event listeners for two main purposes: 1. An event listener to add webhook types to the webhook user interface. 2. An event listener to whichever action you want to trigger a webhook payload to be queued. ADDITIONAL STEPS

Additional steps that you must take in your own bundle are: 1. Create your own event dispatching for your bundle’s custom event and payload 2. Register your custom event listeners in your bundle’s configuration file as a service. 3. Refer to receiving webhooks section to receive payloads in your application. WEBHOOK TYPE LISTENER



Use the WebhookEvents::WebhookBuilderEvent to add a webhook type to the webhook interface.

use Mautic\WebhookBundle\WebhookEvents; use Mautic\WebhookBundle\Event\WebhookBuilderEvent; use Mautic\CoreBundle\EventListener\CommonSubscriber; use Mautic\YourBundle\YourBundleEvents;

/** * Class WebhookSubscriber * * @package Mautic\YourBundle\EventListener */


72/222

17/12/2017


class WebhookSubscriber extends CommonSubscriber { /** * @return array */ static public function getSubscribedEvents() { return array( WebhookEvents::WEBHOOK_ON_BUILD => array('onWebhookBuild', 0) ); } /** * Add event triggers and actions * * @param WebhookBuilderEvent $event */ public function onWebhookBuild(WebhookBuilderEvent $event) { // add checkbox to the webhook form for new leads $type

= array(

'label'

=> 'mautic.bundlename.webhook.event.type.new',

'description' => 'mautic.bundlename.webhook.event.type.new_desc', // note: we don't currently use a description, but may in the future so we have supported it here ); // add it to the list $event->addEvent(YourBundle::ACTION_TO_TRIGGER, $type); // Note: you may create multiple arrays and call the $event->addEvent method multiple times // in this function to add several types all at once. } } ?>

Add an event listener for the

WebhookEvents::WEBHOOK_ON_BUILD event,

call the addEvent method and pass it an argument for your payload

event constant, and an array of a label and a description to be added to the Webhook user interface. YourBundle::ACTION_TO_TRIGGER is

a constant that should be an event registered in your bundle. We use the constant to save the type in

the database and query for later. You will use the sam e constant later, so its import ant to be consistent. PAYLOAD EVENT LISTENER



Add an event listener which extends the

WebhookSubscriberBase class.

This event should be dispatched in your bundle when you

wish to create a payload.


73/222

17/12/2017


use Mautic\CoreBundle\Factory\MauticFactory; use Doctrine\ORM\NoResultException; use Mautic\CoreBundle\EventListener\CommonSubscriber; use Mautic\LeadBundle\Event\PointsChangeEvent; use Mautic\ApiBundle\Serializer\Exclusion\PublishDetailsExclusionStrategy; /** * Class LeadSubscriber * * @package Mautic\Webhook\EventListener */ class LeadSubscriber extends WebhookSubscriberBase { /** * @return array */ static public function getSubscribedEvents () { return array( // note this is the same constant we would have used in the addEvent() listener! LeadEvents::LEAD_POST_SAVE => array('onLeadNewUpdate', 0) ) } /* * Generic method to execute when a lead does something */ public function onLeadNewUpdate(LeadEvent $event) { // serializer groups are defined and optionally used in your bundle's entity. // Use these format your payload in JSON formats. $serializerGroups = array("leadDetails", "userList", "publishDetails", "ipAddress"); // the beginning part of building our webhook payload of a lead entity $entity = $event->getLead(); // our payload goes into an array $payload = array( 'lead'

=> $entity,

); // we want to only trigger a payload if the lead is new if ($event->isNew()) { // again please note the use of the constant here - this should be consistent with the constant we register to the webhook form $webhookEvents = $this->getEventWebooksByType(LeadEvents::LEAD_POST_SAVE); // The webhook model is made available because we've extended the WebhookSubscriberBase class. $this->webhookModel->QueueWebhooks($webhookEvents, $payload, $serializerGroups);

} } }

The next step is to add an event listener for the action you want to actually use for creating payloads. This could be anything you want, your bundle will have to have an event type and use the event dispatcher to execute the event. Here is an example listener to c reate a lead payload whenever a new lead is added to Mautic. You can add the listener to any bundle. Be sure to register it in your bundle’s config.php file.



The event constant that you return in the getSubscriberEvents() method should match the event type from the previous listener.

This is used in a database query, so it must match exactly for the payload to be included in the hook POST to the endpoint URL.


74/222

17/12/2017


You can refer to the model for more documentation on the

QueueWebhooks method.

In short you want to pass the event entities that this

payload is being queued against The payload, which is an array, and finally the serializer groups for formatting the JSON. This should complete the set up, registering and executing custom webhook events and payloads. RECEIVING WEBHOOK PAYLOADS

A sample new lead post payload



Click the

JSON tab

to see a sample lead JSON payload.

Webhooks enable Mautic to send data for leads, points, and email opens to outside applications. It does this by taking an outside application’s endpoint url, and sending an HTTP post request to that location. In that post we include the relevant data the the event that has been fired. To listen to the webhook posts, developers should create a publicly accessible endpoint location in their application. That endpoint should be available to receive a POST request from Mautic. The contents of the payload will vary based on the events that the user wishes to include in the payload. An excellent way of testing to see the data that will be included is using Requestb.in. Requestb.in allows users to view the full contents of the hook payload. Developers can refer to a post to the bin to see the contents and craft the way their application receives that input accordingly. EXTENDING UI INJECTING BUTTONS

use Mautic\CoreBundle\CoreEvents; use Mautic\CoreBundle\Event\CustomButtonEvent; use Mautic\CoreBundle\EventListener\CommonSubscriber; use Mautic\CoreBundle\Templating\Helper\ButtonHelper; use Mautic\LeadBundle\Entity\Lead; class ButtonSubscriber extends CommonSubscriber { public static function getSubscribedEvents() { return [ CoreEvents::VIEW_INJECT_CUSTOM_BUTTONS => ['injectViewButtons', 0] ]; } /** * @param CustomButtonEvent $event */ public function injectViewButtons(CustomButtonEvent $event) { // Injects a button into the toolbar area for any page with a high priority (displays closer to first) $event->addButton( [ 'attr' 'class'

=> [ => 'btn btn-default btn-sm btn-nospin',

'data-toggle' => 'ajaxmodal', 'data-target' => '#MauticSharedModal', 'href'

=> $this->router->generate('mautic_world_action', ['objectAction' => 'doSomething']),

'data-header' => 'Extra Button', ], 'tooltip'

=> $this->translator->trans('mautic.world.dosomething.btn.tooltip'),


75/222

17/12/2017

Mautic Developer Documentation 'iconClass' => 'fa fa-star', 'priority'

=> 255,

], ButtonHelper::LOCATION_TOOLBAR_ACTIONS ); // if ($lead = $event->getItem()) { if ($lead instanceof Lead) { $sendEmailButton = [ 'attr'

=> [

'data-toggle' => 'ajaxmodal', 'data-target' => '#MauticSharedModal', 'data-header' => $this->translator->trans( 'mautic.world.dosomething.header', ['%email%' => $event->getItem()->getEmail()] ), 'href'

=> $this->router->generate(

'mautic_world_action', ['objectId' => $event->getItem()->getId(), 'objectAction' => 'doSomething'] ), ], 'btnText'

=> 'Extra Button',

'iconClass' => 'fa fa-star', 'primary'

=> true,

'priority'

=> 255,

]; // Inject a button into the page actions for the specified route (in this case /s/contacts/view/{contactId}) $event ->addButton( $sendEmailButton, // Location of where to inject the button; this can be an array of multiple locations ButtonHelper::LOCATION_PAGE_ACTIONS, ['mautic_contact_action', ['objectAction' => 'view']] ) // Inject a button into the list actions for each contact on the /s/contacts page ->addButton( $sendEmailButton, ButtonHelper::LOCATION_LIST_ACTIONS, 'mautic_contact_index' ); } } } }

As of Mautic 2.3.0, support for plugins to inject buttons throughout Mautic’s UI has been added by listening to the

CoreEvents::VIEW_IN‐

JECT_CUSTOM_BUTTONS event.

There are five places in Mautic’s UI that buttons can be injected into: Location

Description

\Mautic\CoreBundle\Templating\Helper\ButtonHelper::LOCATION_LIST_ACTIONS

Drop down actions per each item in list views.

\Mautic\CoreBundle\Templating\Helper\ButtonHelper::LOCATION_TOOLBAR_ACTIONS

Top right above list view tables to the right of the table filter. Preferably buttons with icons only.

\Mautic\CoreBundle\Templating\Helper\ButtonHelper::LOCATION_PAGE_ACTIONS

Main page buttons to the right of the page title (New, Edit, etc). Primary buttons will be displayed as buttons while the rest will be displayed in a drop down.


76/222

17/12/2017


Location

Description

\Mautic\CoreBundle\Templating\Helper\ButtonHelper::LOCATION_NAVBAR

Top of the page to the left of the account/profile menu. Buttons with text and/or icons.

\Mautic\CoreBundle\Templating\Helper\ButtonHelper::LOCATION_BULK_ACTIONS

Buttons inside the bulk dropdown (around the checkall checkbox of lists).

Buttons use a priority system to determine order. The higher the priority, the closer to first the button is displayed. The lower the priority, the closer to last. For a button dropdown, setting a button as primary will display the button in the button group rather than the dropdown. BUTTON ARRAY FORMAT

The array defining the button can include the following keys: Key

Type

Description

attr

array

Array of attributes to be appended to the button (data attributes, href, etc)

btnText

string

Text to display for the button

iconClass

string

Font Awesome class to use as the icon within the button

tooltip

string

Text to display as a tooltip

primary

boolean

For button dropdown formats, this will display the button in the group rather than in the dropdown

priority

int

Determines the order of buttons. Higher the priority, closer to the first the button will be placed. Buttons with the same priority wil be ordered alphabetically.

If a button is to display a confirmation modal, the key confirm can be used. A confirm array can have the following keys: Key

Type

Description

message

string

Translated message to display in the confirmation window

confirmText

string

Text to display as the confirm button

confirmAction

string

HREF of the button

cancelText

string

Text to display as the cancel button

cancelCallback

string

Mautic namespaced Javascript method to be executed when the cancel button is clicked

confirmCallback

string

Mautic namespaced Javascript method to be executed when the confirm button is clicked

precheck

string

Mautic namespaced Javascript method to be executed prior to displaying the confirmation modal

btnClass

string

Class for the button

iconClass

string

Font Awesome class to use as the icon

btnTextAttr

string

string of attributes to append to the button’s inner text

attr

array

Array of attributes to append to the button’s outer tag

tooltip

string

Translated string to display as a tooltip

tag

string

Tag to use as the button. Defaults to an a tag.


77/222

17/12/2017


Key

Type

Description

wrapOpeningTag

string

Tag/html to wrap button in. Defaults to nothing.

wrapClosingTag

string

Tag/thml to close wrapOpeningTag. Defaults to nothing.

On the same nested level as the confirm key can include primary and/or priority . DEFINING BUTTON LOCATIONS

dropdown-toggle" data-toggle="dropdown" aria-expanded="false">' ."\n"; $dropdownOpenHtml .= '
'."\n"; echo $view['buttons']->reset($app->getRequest(), 'custom_location')->renderButtons($dropdownOpenHtml, '
');

A plugin can define it’s own locations that other plugins can leverage by using the template buttons helper. There are three types of button groups supported: Type

Description

\Mautic\CoreBundle\Templating\Helper\ButtonHelper::TYPE_BUTTON_DROPDOWN

Primary buttons are displayed in a button group while others in a dropdown menu.

\Mautic\CoreBundle\Templating\Helper\ButtonHelper::TYPE_DROPDOWN

Buttons displayed in a dropdown menu.

\Mautic\CoreBundle\Templating\Helper\ButtonHelper::TYPE_GROUP

A group of buttons side by side.

Dropdowns require the wrapping HTML to be passed to the renderButtons method.

Miscellaneous FLASH MESSAGES

addFlash( 'mautic.translation.key', array('%placeholder%' => 'some text'), 'notice', // Notification type 'flashes', // Translation domain $addNotification // Add a notification entry );

translator->trans(, array( '%placeholder%' => 'some text' ), 'flashes'


78/222

17/12/2017


); $this->session->getFlashBag()->add('notice', $translatedString);

To create an alert, aka flash message, you can use the flas h bag in the session. If your controller extends one of Mautic’s common controllers, you c an simply use the helper function addFlash() . From a model, or any service, you can use the session to obtain the flash bag. $flashBag = $this->get('session')->getFlashBag(); NOTIFICATIONS

addNotification($message, $type, $isRead, $header, $iconClass, new \DateTime());

addNotification($message, $type, $isRead, $header, $iconClass, $datetime );

Mautic also has a notification center. By default, addFlash() will also add a notification to the center. But, a message can be manually added as well. Controllers can use the helper function while models and other services can obtain the NotificationModel. HELPERS

Mautic has many helper classes available. A few of the most commonly used ones are highlighted below. INPUT HELPER

The input helper can be used to ensure clean strings from user input.

DATE/TIME HELPER

The date/time helper can be used to convert between UTC and the local timezone.

= new \Mautic\CoreBundle\Helper\DateTimeHelper('2015-07-20 21:39:00', 'Y-m-d H:i:m', 'local');

$utcString = $dtHelper->toUtcString(); // refer to the class for other functions


79/222

17/12/2017


CHARTQUERY AND GRAPHS

There are several classes available to assist with generating chart data.

em->getConnection(), $dateFrom, $dateTo); $q

= $query->prepareTimeDataQuery('lead_points_change_log', 'date_added', $filter);

$data

= $query->loadAndBuildTimeData($q);

$chart->setDataset($this->translator->trans('mautic.point.changes'), $data); $data

= $chart->render();

CHARTQUERY

ChartQuery is a helper class to get the chart data from the database. Instantiate it with the Doctrine connection object, date from and date to. Those dates must be instances of the DateTime class. ChartQuery will automatically guess the time unit (hours, days, weeks, months or years) based on the items between the date range. However, if you want to receive the data from a specific time unit, pass it as the fourth parameter (H, d, W, m, Y). ChartQuery also fills in the missing items (if any) which is required to display the data properly in the line chart generated by the ChartJS. LINECHART

LineChart is used in Mautic to display a date/time related data where the time is on the horizontal axis and the values are in the vertical axis. ChartJS’ line charts can display multiple datasets in one chart. Instantiate the LineChart with a unit (null for unit guessing), from date, to date (the same as for the ChartQuery) and a date format (null for automatically generated date format). All the params you need to instantiate the LineChart are used to generate the labels of the horizontal axis. To add the dataset to the LineChart object, use the setDataset($label, $data) method where the label is string and data is an array generated by the ChartQuery. The color of each dataset will be generated automatically. Call the render() method to get the data prepared for ChartJS. PIECHART

A PieChart can be instantiated simply by new PieChart() . To add a dataset, use again the setDataset($label, $value) method where the label is a string and value is integer. Call the render() method to get the data prepared for ChartJS. BARCHART

BarChart is used to display different variants of the same value where the variants are in the horizontal axis and the value is in vertical axis. To create a bar chart, use new BarChart($labels) where labels is an array of all the variants. Each variant can have multiple datasets. To add a dataset, use the setDataset($label, $data, $order) method where the label is string, data is array of values for each variant. Order can be used to move the dataset before already created dataset. Call the render() method to get the data prepared for ChartJS.

render('MauticCoreBundle:Helper:chart.html.php', array('chartData' => $data, 'chartType' => 'line', 'chartHeight' => 300)); ?>

FRONTEND

At the frontend, simply use the prepared chart template, pass in the chart data, the chart type (line/bar/pie) and the chart height. The width is responsive. COMMANDS


80/222

17/12/2017


Support for new CLI commands can be added using Symfony’s console component. MODERATED COMMANDS

$input

* @param OutputInterface $output * * @return int */ protected function execute(InputInterface $input, OutputInterface $output) { // Validate if the command is already has an instance running // A third argument can be passed here if this command is running something unique such as an ID if (!$this->checkRunStatus($input, $output)) { return 0; } // Execute some stuff // Complete this execution $this->completeRun(); return 0; } }

Mautic provide an method for moderating commands meaning it will only allow one instance to run at a time. To utilize this method, extend the

Mautic\CoreBundle\Command\ModeratedCommand class.

FORMS

Mautic leverages Symfony’s Form component and form classes. Refer to Symfony’s documentation for more information. FORM TYPES

As stated in Symfony’s documentation referenced above, form type classes are the best way to go. Mautic makes it easy to register form type services through the bundle’s config file. Refer to the Services section. DATA S ANITIZATION


81/222

17/12/2017


addEventSubscriber( new CleanFormSubscriber( [ 'content'

=> 'html',

'customHtml' => 'html' ] ) ); // ... } // ...

Form data is not automatically sanitized. Mautic provides a form event s ubscriber to handle this. In your form type class, register the The array provided to

Mautic\CoreBundle\Form\EventListener\CleanFormSubscriber event

CleanFormSubscriber should

the data. Any un-specified form field will use the

subscriber.

contain the names of the form fields as keys and the values the masks to use to sanitize

clean mask

by default.

MANIPULATING FORMS

A form event listener must be used if a form needs to be manipulated based on submitted data such as changing defined fields, adjust constraints, or changing select choices based on submitted values. Refer to Symfony’s documentation on this. VALIDATING DATA

Review Symfony’s form validation documentation for a general overview. There are two common means of validating form data. USING ENTITY STATIC CALLBACK

addPropertyConstraint( 'name', new NotBlank( array( 'message' => 'mautic.core.name.required' ) ) ); $metadata->addPropertyConstraint(


82/222

17/12/2017


'population', new NotBlank( array( 'message' => 'mautic.core.value.required', 'groups'

=> array('VisitedWorld')

) ) ); } /** * @param Form $form * * @return array */ public static function determineValidationGroups (Form $form) { $data

= $form->getData();

$groups = array('AllWorlds'); if (!$data->getId() || ($data->getId() && $data->getVisitCount() > 0)) { $groups[] = 'VisitedWorld'; } return $groups; } // ...

If the underlying data of a form is an Entity object, a static method loadValidatorMetadata can be defined in the Entity class. This will automatically be called when Symfony is processing form data. A form can also use validation_groups to change the order of data to be validated or only validate if certain criteria is true. For example, only validate a password confirmation field if the first password field passes validation. When registering a validation group in the form type class, one can use static callback that can be used to determine what validation group(s) should be used.

setDefaults(array( 'data_class'

=> 'MauticPlugin\HelloWorld\Entity\World',

'validation_groups' => array( 'MauticPlugin\HelloWorld\Entity\World', 'determineValidationGroups', ) )); } // ...

USING CONSTRAINTS

A form type service can also register constraints when defining the form fields.


83/222

17/12/2017


use Symfony\Component\Validator\Constraints\NotBlank; // ... public function buildForm(FormBuilderInterface $builder, array $options) { $builder->add( 'name', 'text', array( 'label'

=> 'mautic.core.name',

'label_attr'

=> array('class' => 'control-label'),

'attr'

=> array(

'class'

=> 'form-control'

), 'constraints' => array( new NotBlank( array( 'message' => 'mautic.core.value.required' ) ) ) ) ); } // ...

EVENTS

=> array('onLeadPostSave', 0),

LeadEvents::LEAD_POST_DELETE

=> array('onLeadDelete', 0)

); } public function onLeadPostSave(LeadEvent $event) { $lead = $event->getLead(); // do something } public function onLeadDelete(LeadEvent $event) { $lead = $event->getLead();


84/222

17/12/2017

Mautic Developer Documentation $deletedId = $lead->deletedId; // do something

} }

Mautic leverages Symfony’s EventDispatcher to execute and communicate various actions through Mautic. Plugin’s can hook into these to extend the functionality of Mautic. Refer to Extending Mautic for some of the ways to do this. SUBSCRIBERS

The easiest way to listen to various events is to use an event subscriber. Read more about subscribers in Symfony’s documentation. Plugin event subscribers can extend \Mautic\CoreBundle\EventListener\CommonSubscriber which gives access to commonly used dependencies and also allows registering the subsc riber service through the bundles’s config file. But, it does not have to and instead See Services for more information on registering event services. AVAILABLE EVENTS

There are many events available throughout Mautic. Depending on the desired functionality, look at the core bundle’s *Event.php file in the root of the bundle. For example, Lead related events are defined and described in app\bundles\LeadBundle\LeadEvents.php. These final classes provide the names of the events to listen to. Always use the event constants to ensure future changes to event names will not break the plugin. CUSTOM EVENTS

A plugin can create and dispatch it’s own events. Custom events require three things:

1) Class defining the available events for the plugin using a final class with constants

*/

protected $world;


85/222

17/12/2017


/** @var bool

*/

protected $falseAlarm = false; public function __construct(World $world) { $this->world = $world; } public function shouldPanic() { return ('earth' == $this->world->getName()); } public function setIsFalseAlarm() { $this->falseAlarm = true; } public function getIsFalseAlarm() { return $this->falseAlarm; } }

2) The Event class that is received by the listeners. This class should extend Symfony\Component\EventDispatcher\Event. It will be created when the event is dispatched and should have any information listeners need to act on it.

get('event_dispatcher'); if ($dispatcher->hasListeners(HelloWorldEvents::ARMAGEDDON)) { $event = $dispatcher->dispatch(HelloWorldEvents::ARMAGEDDON, new ArmageddonEvent($world)); if ($event->shouldPanic()) { throw new \Exception("Run for the hills!"); } }

3) The code that dispatches the event where appropriate using the event_dispatcher service. IMPLEMENTING TRANSLATION SUPPORT TO ENTITIES

Mautic has some helper methods with adding support for translated content to an entity. \MAUTIC\COREBUNDLE\ENTITY\TRANSLATIONINTERFACE

This Entity interface ensures that everything is needed in order for Mautic to handle translations correctly for an entity. \MAUTIC\COREBUNDLE\ENTITY\TRANSLATIONENTITYTRAIT

This trait provides properties needed to define an Entity’s language and relationships to other items. In the Entity’s loadMetadata() method, be sure to call $this->addTranslationMetadata(). \MAUTIC\COREBUNDLE\TRANSLATIONMODELTRAIT

This trait provides the method getTranslatedEntity() that will determine the entity to use as the translation based on the $lead and/or the HTTP_ACCEPT_LANGUAGE header. It also has a postTranslationEntitySave() that should be called at the end of the Entity’s saveEntity()

method. \MAUTIC\COREBUNDLE\DOCTRINE\TRANSLATIONMIGRATIONTRAIT

To ease the generation of schema to match the Entity, use this trait then execute $this->addTranslationSchema(). TRANSLATED ENTITY FORM

Add a locale and translatedParent form fields like the code example. https://developer.mautic.org/#plugin-directory-structure

86/222

17/12/2017


em, 'HelloWorldBundle:World'); $builder->add( $builder->create( 'translationParent', 'world_list', array( 'label'

=> 'mautic.core.form.translation_parent',

'label_attr'

=> array('class' => 'control-label'),

'attr'

=> array(

'class'

=> 'form-control',

'tooltip' => 'mautic.core.form.translation_parent.help' ), 'required'

=> false,

'multiple'

=> false,

'empty_value' => 'mautic.core.form.translation_parent.empty', 'top_level'

=> 'translation',

'ignore_ids'

=> array((int) $options['data']->getId())

) )->addModelTransformer($transformer) ); $builder->add( 'language', 'locale', array( 'label'

=> 'mautic.core.language',

'label_attr' => array('class' => 'control-label'), 'attr' 'class'

=> array( => 'form-control',

'tooltip' => 'mautic.page.form.language.help', ), 'required'

=> false,

'empty_data' => 'en' ) );

IMPLEMENTING VARIANT (A/B TEST) SUPPORT TO ENTITIES

Mautic has some helper methods with adding support for creating variants of a given entity. This becomes particularly useful for A/B testing. \MAUTIC\COREBUNDLE\ENTITY\VARIANTINTERFACE

This Entity interface ensures that everything is needed in order for Mautic to handle the variants correctly for an entity. \MAUTIC\COREBUNDLE\ENTITY\VARIANTENTITYTRAIT

This trait provides properties needed to define an Entity’s relationship to other items. In the Entity’s loadMetadata() method, be sure to call $this->addVariantMetadata() . \MAUTIC\COREBUNDLE\VARIANTMODELTRAIT

This trait provides the methods preVariantSaveEntity() , postVariantSaveEntity() and convertVariant() . preVariantSaveEntity() should be executed prior to saveEntity then postVariantSaveEntity() . See example.

= $this->preVariantSaveEntity($entity, ['setVariantHits'], $variantStartDate);

parent::saveEntity($entity, $unlock);


87/222

17/12/2017


$this->postVariantSaveEntity($entity, $resetVariants, $entity->getRelatedEntityIds(), $variantStartDate);

\MAUTIC\COREBUNDLE\DOCTRINE\VARIANTMIGRATIONTRAIT

To ease the generation of schema to match the Entity, use this trait then execute $this->addVariantSchema() . TRANSLATED ENTITY FORM

Add variantParent field’s like the code example. In the example, the variantParent value is set in the controller due to a Add A/B Test button is clicked. The specific use for the plugin may require a select list rather than a hidden field. Change this to meet the code’s needs.

em, 'HelloWorldBundle:World'); $builder->add( $builder->create( 'variantParent', 'hidden' )->addModelTransformer($transformer) );

Themes Custom themes for public facing areas of Mautic can be generated but require a bit of Twig experience. The themes use the same templating formats as Symfony’s twig templates.

Theme Directory Structure Each theme directory must have at least a config.json file and a html directory with the public facing template’s for the feature’s it supports. All themes should have a html/message.html.twig file. See below for a typical directory structure: themes/blank/ - - - config.json - - - thumbnail.png - - - html/ - - - - - - base.html.twig - - - - - - email.html.twig - - - - - - form.html.twig - - - - - - message.html.twig - - - - - - page.html.twig

Theme zip package If you want to make your theme installable via the Theme Manager, make a zip package from it. The zip package name must be the same as the final folder name of the theme in the /themes folder. The contents of the zip folder must contain the theme files directly, not in a https://developer.mautic.org/#plugin-directory-structure

88/222

17/12/2017


subfolder. You can download an existing theme via the Theme Manager to see an example ZIP file.

Theme Config File The config file defines the name of the theme and the features it supports. The config file should return an array with the following keys: Key

Type

Description

name

string

Name of the theme

author

string

Name of the theme author

authorUrl

string

URL to the author’s website

features

array

Array of features the theme supports. Options currently are email, form, and/or page

Theme Thumbnail The thumbnail should be a screenshot of the theme with demo content. The width x height should be 575 x 600 px. This thumbnail will be available for Mautic users for quick theme preview in the Email edit form, Landing Page edit form and the Theme Manager.



Mautic will be look for thumbnail.png for default but if you want a specific image for your [email, page, form] template you can add a

thumbnail_feature.png.

Example Feature

thumbnail name

email

thumbnail_email.png

form

thumbnail_form.png

page

thumbnail_page.png

Slots SLOT DEFINITION

The slot can be defined by a single HTML attribute data-slot="{slot type here}" . For example, the text slot can be defined even with the demo content. When the theme is opened in the builder, the div with attribute data-slot="text" will make the text inside the div editable within the inline Froala editor. Example: https://developer.mautic.org/#plugin-directory-structure

89/222

17/12/2017


@JaneDoe has invited you to join Awesome inc!

The slot types currently built: IMAGE

Inserts a single image into the div. User can click on it and edit it with options which provides Froala editor (link, change image source, alt text, …) BUTTON

Inserts a HTML button. User can define text, URL as well as padding, size and position. TEXT

Inserts a new text slot which y ou can edit with a HTML editor, so you can insert even media like images and videos in it. SEPARATOR

Inserts a horizontal line to separate content. SLOT CONTAINERS

As stated before, users can drag & drop the new slots into the theme. So as a theme developer, you have to define where the user can drop the slots. You can do it again with a single HTML attribute

data-slot-container="1"

.

Example:


This way the builder will let users drop the new slots into this container. In the example above there is already one predefined slot which user can move to another container, remove or edit. This functionality will provide you with lots of creative freedom for designing and developing your own unique email and landing pages. Have a unique design? Share it with the community! We would love to see how you’re using Mautic to engage your audience.

Sections Sections are full width parts of the theme which can let user to change the background color in the section wrapper (full monitor width) and in the section content itself. Since Mautic 2.7.0 it’s possible to move the sec tions up or down, delete the sections and even create a new ones with layout of 1,2 or 3 columns. SECTION

The section holds the content. It should be centered and should have fixed width. This fixed width should be consistent with all other sections. Section also wraps the content. The section can be any block HTML element with attribute

data-section="1"

.

Example:


90/222

17/12/2017

Mautic Developer Documentation @JaneDoe has invited you to join Awesome inc!

SECTION WRAPPER

Section wrapper must have 100% width of the browser window. You thus have to split your theme into several “rows” if you want to enable the users to change the background of each section. The section wrapper can be any block HTML element with attribute data-sectionwrapper .

Example:


Theme HTML Files Notice that in the directory structure above, there is a base.html.twig file. This is not necessary but used in the example to define the base HTML document which each some of the following files extend. EMAIL.HTML.TWIG

{# themes/HelloBundle/html/email.html.twig #} {subject}

Hello there!

We haven't heard from you for a while...

{unsubscribe_text} | {webview_text}


91/222

17/12/2017


This file defines the document for building an email template. Of course this file should follow html based email etiquette. Throughout the document should be output for the slots defined as data attributes. FORM.HTML.TWIG

{# themes/thellotheme/html/form.html.twig #} {% extends ":"~template~":base.html.twig" %} {% block content %} {% if message is defined %}

{{ message|raw }}

{% endif %}
{% if header is defined %}
{{ header }}
{% endif %} {{ content|raw }}
{% endblock %}

This file generates the html document for a form when viewed via it’s public URL. This does not style the fields of a form. That will be described below. Each form.html.twig file should output a message , header , and content variables. CUSTOMIZING THE FORM

To provide custom form field templates or to manipulate the form body, create the following directory structure: themes/HelloWorld/ - - - html/ - - - - - - MauticFormBundle - - - - - - - - - Builder <– for customizing the form structure itself - - - - - - - - - Field <– for customizing form field types Copy from app/bundles/FormBundle/Views/Builder/form.html.php in the theme’s Builder directory or one or more of the fields templates in app/bundles/FormBundle/Views/Field/*.html.php into the theme’s Field directory. Then customize to the desired layout. Note that these

must be PHP templates. STYLING THE EMBEDDED FORMS

The embedded forms can be styled by the themes/{your theme name}/html/MauticFormBundle/Builder/style.html.twig file. The best way is to copy the content of the default form styles and modify them to your needs. MESSAGE.HTML.TWIG

{# themes/hellotheme/html/message.html.twig #} {% extends ":"~template~":base.html.twig" %} {% block content %}

{{ message|raw }}
{% if content is defined %}
{{ content|raw }}
{% endif %}


92/222

17/12/2017


{% endblock %}

This file is a simple message file mainly used as the landing page for when a lead unsubscr ibes or resubscribes to the system’s emails. But may be used by other areas so should be included in all themes. It requires echo'ing two variables: message and content . message houses the string message such as “You have been unsubscribed…” content will either be empty or house the HTML of a form that’s been associated with the email as an “unsubscribe form.” PAGE.HTML.TWIG

{# themes/hellotheme/html/message.html.twig #} {% extends ":"~template~":base.html.twig" %} {% block content %} {% if page is defined %} {pagetitle} <meta name="description" content="{pagemetadescription}"> {% endif %} {{ outputHeadDeclarations() }} {{ outputScripts('bodyOpen') }} {% block content %}{% endblock %} {{ outputScripts('bodyClose') }} {% endblock %}

page.html.twig is exactly the same as email.html.twig except that it’ll be used for landing pages instead. Thus, it can be more robust with the HTML document.

REST API Mautic provides a REST API to manipulate leads and/or obtain information for various entities of Mautic.



All Mautic API endpoints require an OAuth1a signtature or OAuth2 access token.

Error Handling If an OAuth error is encountered, it’ll be a JSON encoded array similar to:

{ "error": "invalid_grant", "error_description": "The access token provided has expired." }

If a system error encountered, it’ll be a JSON encoded array similar to: https://developer.mautic.org/#plugin-directory-structure

93/222

17/12/2017


{ "error": { "message": "You do not have access to the requested area/action.", "code": 403 } }

Mautic version check In case your API service wants to support several Mautic versions with different features, you might need to check the version of Mautic you communicate with. Since Mautic 2.4.0 the version number is added to all API response headers. The header name is Mautic-Version . With Mautic PHP API library you can get the Mautic version like this:

// Make any API request: $api = $this->getContext('contacts'); $response = $api->getList('', 0, 1); // Get the version number from the response header: $version = $api->getMauticVersion();

$version will be in a semantic versioning format: [major].[minor].[patch] . For example: 2.4.0 . If you’ll try it on the latest GitHub

version, the version will have -dev at the end. Like 2.5.1-dev .

Authorization Mautic uses OAuth or Basic Authentication (as of Mautic 2.3.0) for API authorization. It supports both OAuth 1a and OAuth 2; however, as of 1.1.2, the administrator of the Mautic instance must choose one or the other. Of course OAuth 2 is only recommended for servers secured behind SSL. Basic authentication must be enabled in Configuration -> API Settings. The Mautic administrator should enable the API in the Configuration -> API Settings. This will add the “API Credentials” to the admin menu. A client/consumer ID and secret should then be generated which will be used in the following processes. All authorization requests should be made to the specific Mautic instances URL, i.e. https://your-mautic.com .



The OAuth processes can be a pain. If possible, it’s best to use an OAuth library for the language being used. If PHP, it is

recommended that Mautic’s PHP library be used.

OAUTH 1A

newAuth() will accept an array of OAuth settings $settings = array( 'baseUrl'

=> 'https://your-mautic.com',

'version'

=> 'OAuth1a',

'clientKey'

=> '5ad6fa7asfs8fa7sdfa6sfas5fas6asdf8',

'clientSecret' => 'adf8asf7sf54asf3as4f5sf6asfasf97dd', 'callback'

=> 'https://your-callback.com'

);


94/222

17/12/2017


// Initiate the auth object $initAuth = new ApiAuth(); $auth

= $initAuth->newAuth($settings);

// Initiate process for obtaining an access token; this will redirect the user to the authorize endpoint and/or set the tokens when the user is redirected back after granting authorization if ($auth->validateAccessToken()) { if ($auth->accessTokenUpdated()) { $accessTokenData = $auth->getAccessTokenData(); //store access token data however you want } }

The OAuth 1a method is recommended for servers that are not behind https. Note that OAuth 1a access tokens do not expire. OAuth 1a can be a complicated method due to the need to generate a signature for the request. If anything is off with the signature, the request will not be validated. AUTHORIZATION

STEP ONE - OBTAIN A REQUEST TOKEN

The first step is to obtain a request token that will be used when directing the user to the authorization page. Make a POST to the request token endpoint /oauth/v1/request_token :

POST /oauth/v1/request_token Authorization: OAuth oauth_callback="https%3A%2F%2Fyour-callback-uri.com", oauth_consumer_key="CONSUMER_KEY", oauth_nonce="UNIQUE_STRING", oauth_signature="GENERATED_REQUEST_SIGNATURE", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1318467427", oauth_version="1.0"

(note that the header has been wrapped for legibility) Review Generating the Authorization Header on the specifics of generating the OAuth header. The response will be a query string:

oauth_token=REQUEST_TOKEN&oauth_token_secret=REQUEST_TOKEN_SECRET&oauth_expires_in=3600

Parse the string and use the parameters in the next step as indicated.



These must be preserved in some kind of persistent storage as they will be used when obtaining the ac cess token.

Note that the refresh token is only good for the number of seconds specified in oauth_expires_in . STEP TWO - AUTHORIZATION

Now redirect the user to the authorization endpoint oauth/v1/authorize with the request token as part of the URL’s query. If the callback is something different than what is configured in Mautic, url encode it and include in the query as oauth_callback .

/oauth/v1/authorize?oauth_token=REQUEST_TOKEN&oauth_callback=https%3A%2F%2Fyour-callback-uri.com


95/222

17/12/2017


The user will login and Mautic will r edirect back to the either the consumer ’s configured callback or to the oauth_callback included in the query. The callback will include oauth_token and oauth_verifier in the URL’s query. Compare the oauth_token in the query with that obtained in step two to ensure they are the same and prevent cross-site request forgery. oauth_verifier will

need to be part of the header generated in step three.

STEP THREE - OBTAIN AN ACCESS TOKEN

Generate the Authorization header and make a POST to the access token endpoint /oauth/v1/access_token . When generating the header, the oauth_token_secret returned in step two should be used as the TOKEN_SECRET in the composite key. oauth_verifier from

step two should be part of the Authorization header generated.

POST /oauth/v1/access_token Authorization: OAuth oauth_callback="https%3A%2F%2Fyour-callback-uri.com", oauth_consumer_key="CONSUMER_KEY", oauth_nonce="UNIQUE_STRING", oauth_signature="GENERATED_REQUEST_SIGNATURE", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1318467427", oauth_verifier="OAUTH_VERIFIER_FROM_STEP_TWO" oauth_version="1.0"

(note that the header has been wrapped for legibility) The response should include a query string with the access token:

oauth_token=ACCESS_TOKEN&oauth_token_secret=ACCESS_TOKEN_SECRET



Mautic’s OAuth 1a access tokens do not expire but the user can deauthorize them. If the access token is invalid, a `401` response

will be returned.

The oauth_token can be included in the authorize header and the oauth_token_secret should be used as the TOKEN_SECRET in the composite key when signing API requests. GENERATING THE AUTHORIZATION HEADER

The OAuth header may include the following parameters: Key

Description

oauth_callback

Optional, URL encoded callback to redirect the user to after authorization. If the callback URL is set in Mautic, this must match.

oauth_consumer_key

The consumer key obtained from Mautic’s API Credentials

oauth_nonce

Uniquely generated string that should be used only once

oauth_signature

Signature generated from all applicable data for the request

oauth_signature_method

Method for creating the signature. Currently, only HMAC-SHA1 is supported.


96/222

17/12/2017


Key

Description

oauth_timestamp

Current unix timestamp

oauth_token

The access token

oauth_verifier

Returned after authorization and used when requesting an access token

oauth_version

Should always be 1.0



When making a GET or POST request with parameters, all parameters should be included in the header as well.

STEP ONE - BUILD THE BASE STRING

The base string is used to generate the oauth_signature. The structure of the base string is as follows:

METHOD&URL_ENCODED_URI&NORMALIZED_PARAMETERS

METHOD should be the request method and should always be capitalized. URL_ENCODED_URI should be the base URI the request is made to. It should not include any query parameters (query parameters should be

part of NORMALIZED_PARAMETERS ). NORMALIZED_PARAMETERS should be a url encoded, alphabetically sorted query string of the above oauth parameters (except oauth_signa‐ ture ) plus the parameters of the request (query/post body).

Each key and each value of the parameters must be url encoded individually as well.



PHP should use rawurlencode() instead of urlencode() .

Then each url encoded key/value pair should be concatenated into a single string with an ampersand (&) as the glue character. For example, let’s say a request includes a query of title=Mr&firstname=Joe&lastname=Smith. The process would look s omething like the following (replacing urlencode() with whatever function is appropriate for the language being used). Of course realistically, natural sort and loop functions would be used.

urlencode( urlencode(firstname)=urlencode(Joe) &urlencode(lastname)=urlencode(smith) &urlencode(oauth_callback)=urlencode(https%3A%2F%2Fyour-callback-uri.com) &urlencode(oauth_consumer_key)=urlencode(kdjafs7fsdf86ads7a98a87df6ad9fsf98ad7f) &urlencode(oauth_nonce)=urlencode(ak877asdf6adf68asd9fas) &urlencode(oauth_signature_method)=urlencode(HMAC-SHA1) &urlencode(oauth_timestamp)=urlencode(1437604736) &urlencode(oauth_version)=urlencode(1.0) &urlencode(title)=urlencode(Mr) )



Multidimensional arrays should use foo=baz&foo=bar rather than foo[bar]=baz&foo[baz]=bar when generating the normalized

parameters string.


97/222

17/12/2017 


Notice that oauth_callback , if included, is DOUBLE url encoded.

Put all together, a base string might look like:

GET&http%3A%2F%2Fyour-mautic.com%2Fapi&firstname%3DJoe%26lastName%3DSmith%26oauth_callback%3Dhttps%253A%252F%252Fyour-call‐ back-uri.com%26oauth_consumer_key%3Dkdjafs7fsdf86ads7a98a87df6ad9fsf98ad7f%26oauth_nonce%3Dak877asdf6adf68asd9fas%26oauth_‐ signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1437604736%26oauth_version%3D1.0%26title%3DMr

STEP TWO - BUILD THE COMPOSITE KEY

The composite key is used to encrypt the base string. It is composed of the consumer secret and the token secret if available (post authorization) combined with an ampersand (&).

CLIENT_SECRET&TOKEN_SECRET

If the token secret is not available, i.e. during the request token process, then an ampersand (&) should still be used.

CLIENT_SECRET&

 TOKEN_SECRET Sources

For /oauth/v1/request_token , TOKEN_SECRET is empty. For /oauth/v1/access_token , TOKEN_SECRET will be the oauth_token_secret returned by the request to /oauth/v1/request_token For all other API endpoints, TOKEN_SECRET will be the oauth_token_secret returned by the request to /oauth/v1/access_token

STEP THREE - GENERATE THE SIGNATURE

Now, using the base string and the composite key, the signature can be generated using the appropriate HMAC function available to the language used. The signature generated should then be base64 encoded prior to being us ed in the Authorization header.

base64_encode( hmac_sha1(BASE_STRING, COMPOSITE_KEY) )

The resulting string should then be used included in the header as oauth_signature . SIGNING THE API REQUEST

To sign the API request, generate the Authorization header using the obtained access token.

POST /api/leads/new Authorization: OAuth oauth_callback="https%3A%2F%2Fyour-callback-uri.com", oauth_consumer_key="CONSUMER_KEY", oauth_nonce="UNIQUE_STRING", oauth_signature="GENERATED_REQUEST_SIGNATURE", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1318467427", oauth_token="ACCESS_TOKEN" oauth_version="1.0" https://developer.mautic.org/#plugin-directory-structure

98/222

17/12/2017


title=Mr&firstname=Joe&lastname=Smith

(note that the header has been wrapped for legibility) OAUTH 2

newAuth() will accept an array of OAuth settings $settings = array( 'baseUrl'

=> 'https://your-mautic.com',

'version'

=> 'OAuth2',

'clientKey'

=> '5ad6fa7asfs8fa7sdfa6sfas5fas6asdf8',

'clientSecret' => 'adf8asf7sf54asf3as4f5sf6asfasf97dd', 'callback'

=> 'https://your-callback.com'

); // Initiate the auth object $initAuth = new ApiAuth(); $auth


// Initiate process for obtaining an access token; this will redirect the user to the authorize endpoint and/or set the tokens when the user is redirected back after granting authorization if ($auth->validateAccessToken()) { if ($auth->accessTokenUpdated()) { $accessTokenData = $auth->getAccessTokenData(); //store access token data however you want } }

AUTHORIZATION

STEP ONE - OBTAIN AUTHORIZATION CODE



Mautic supports only the authorization_code and r efresh_token grant types.

Redirect the user to the authorize endpoint oauth/v2/authorize :

GET /oauth/v2/authorize? client_id=CLIENT_ID &grant_type=authorization_code &redirect_uri=https%3A%2F%2Fyour-redirect-uri.com%2Fcallback &response_type=code &state=UNIQUE_STATE_STRING

(note that the query has been wrapped for legibility)



The state is optional but recommended to prevent CSRF attacks. It should be a uniquely generated string and stored locally in

session, cookie, etc. to be compared with the returned value.



Note that the redirect_uri should be URL encoded.


99/222

17/12/2017 


As of 1.1.2, Mautic does not leverage OAuth2 scopes.

The user will be prompted to login. Once they do, Mautic will redirect back to the URL specified in redirect_uri with a code appended to the query. It may look something like: https://your-redirect-uri.com?code=UNIQUE_CODE_STRING&state=UNIQUE_STATE_STRING The state returned should be compared against the original to ensure nothing has been tampered with. STEP TWO - REPLACE WITH AN ACCESS TOKEN

Obtain the value of the code from Step One then immediately POST it back to the access token endpoint oauth/v2/token with:

POST /oauth/v2/token client_id=CLIENT_ID &client_secret=CLIENT_SECRET &grant_type=authorization_code &redirect_uri=https%3A%2F%2Fyour-redirect-uri.com%2Fcallback &code=UNIQUE_CODE_STRING

(note that the post body has been wrapped for legibility) The response returned should be a JSON encoded string:

{ access_token: "ACCESS_TOKEN", expires_in: 3600, token_type: "bearer", scope: "", refresh_token: "REFRESH_TOKEN" }

This data should be stored in a secure location and used to authenticate API requests. REFRESH TOKENS

The response’s expires_in is the number of seconds the access token is good for and may differ based on what is configured in Mautic. The code handling the authorization process should generate an expiration timestamp based on that value. For example . If the access token has expired, the refresh_token should be used to obtain a new access

token. The refresh token is by default good for 14 days in which the user will need to reauthorize the application with Mautic. However, the refresh token’s expiration time is configurable through Mautic’s Configuration.



The application should monitor for a 400 Bad Response response when requesting a new access token and redirect the user back

through the authorization process.

To obtain a new access token, a POST should be made to the access token’s endpoint oauth/v2/token using the refresh_token grant type.

POST /oauth/v2/token client_id=CLIENT_ID &client_secret=CLIENT_SECRET &grant_type=refresh_token https://developer.mautic.org/#plugin-directory-structure

100/222

17/12/2017


&refresh_token=REFRESH_TOKEN &redirect_uri=https%3A%2F%2Fyour-redirect-uri.com%2Fcallback

(note that the post body has been wrapped for legibility) The response returned should be a JSON encoded string:

{ access_token: "NEW_ACCESS_TOKEN", expires_in: 3600, token_type: "bearer", scope: "", refresh_token: "REFRESH_TOKEN" }

AUTHENTICATING THE API REQUEST

Authenticating the API request with OAuth2 is easy. Choose one of the following methods that is appropriate for the application’s needs. AUTHORIZATION HEADER

By using an authorization header, any request method can be authenticated. However, note that this method requires that the server Mautic is installed on passes headers to PHP or has access to the apache_re‐ quest_headers() function. apache_request_headers() is not available to PHP running under fcgi.

Authorization: Bearer ACCESS_TOKEN

METHOD SPECIFIC

The access token can also be appended to the query or included in the body of a POST.

GET https://your-mautic.com/api/leads?access_token=ACCESS_TOKEN

POST https://your-mautic.com/api/leads/new firstname=John&lastname=Smith&access_token=ACCESS_TOKEN

BASIC AUTHENTICATION

As of Mautic 2.3.0, support for basic authentication can be enabled through Mautic’s Configuration -> API Settings. As with OAuth2, it is only recommended to use basic authentication over HTTPS. To authorize a request for basic authentication, set an Authorization header. 1. Combine the username and password of a Mautic user with a colon : . For example, user:password . 2. Base64 encode the string from above. dXNlcjpwYXNzd29yZA== . 3. Add an Authorization header to each API request as Authorization: Basic dXNlcjpwYXNzd29yZA==

Libraries PHP LIBRARY

Mautic provides a PHP library on Github. It is recommended that it be used in PHP projects. Other languages will need to use custom means and/or a 3rd party library to handle the OAuth/request processes. https://developer.mautic.org/#plugin-directory-structure

101/222

17/12/2017


INSTALL VIA COMPOSER

To install using composer, simply run composer require mautic/api-library . INSTALL MANUALLY

Download the package from Github. Extract then include the following code in your project (of course change the file path if needed):

require_once __DIR__ . '/lib/Mautic/MauticApi.php';



Refer to the README in the Github repository for further instructions on how to use the library or review the code examples

included throughout this section.

Endpoints 

All responses are JSON encoded.



Base API Endpoint:

https://your-mautic.com/api

Assets Use this endpoint to obtain details on Mautic’s assets.


$apiUrl

= "https://your-mautic.com";

$api

= new MauticApi();

$assetApi = $api->newApi("assets", $auth, $apiUrl);

GET ASSET

get($id);

Get an individual asset by ID. HTTP REQUEST

GET /assets/ID


102/222

17/12/2017


RESPONSE

Expected Response Code: 200

See JSON code example. Asset Properties Name

Type

Description

id

int

ID of the asset

title

string

Title/name of the asset

description

string/null

Description of the asset

alias

string

Used to generate the URL for the asset

language

string

Locale of the asset

isPublished

bool

Published state

publishUp

datetime/null

Date/time when the asset should be published

publishDown

datetime/null

Date/time the asset should be un published

dateAdded

datetime

Date/time asset was created

createdBy

int

ID of the user that created the asset

createdByUser

string

Name of the user that created the asset

dateModified

datetime/null

Date/time asset was last modified

modifiedBy

int

ID of the user that last modified the asset

modifiedByUser

string

Name of the user that last modified the asset

downloadCount

int

Total number of downloads

uniqueDownloadCount

int

Unique number of downloads

revision

int

Revision version

category

string/null

Name of the category

extension

string

Extension of the asset

mime

string

Mime type of the asset

size

int

Filesize of the asset in bytes

downloadUrl

string

Public download URL for the asset

LIST ASSETS

getList($searchFilter, $start, $limit, $orderBy, $orderByDir, $publishedOnly, $minimal);

HTTP REQUEST


103/222

17/12/2017


GET /assets

Query Parameters Name

Description

search

String or search command to filter entities by.

start

Starting row for the entities returned. Defaults to 0.

limit

Limit number of entities to return. Defaults to the system configuration for pagination (30).

orderBy

Column to sort by. Can use any column listed in the response.

orderByDir

Sort direction: asc or desc.

publishedOnly

Only return currently published entities.

minimal

Return only array of entities without additional lists in it.

RESPONSE


See JSON code example. Properties Same as Get Asset. CREATE ASSET

getContext('files'); $apiContextFiles->setFolder('assets'); $fileRequest = array( 'file' => dirname(__DIR__).'/'.'mauticlogo.png' ); $response = $apiContextFiles->create($fileRequest); $data = array( 'title' => 'Mautic Logo sent as a API request', 'storageLocation' => 'local', 'file' => $response['file']['name'] ); $asset = $assetApi->create($data);

/** * Remote asset example */ $data = array( 'title' => 'PDF sent as a API request', 'storageLocation' => 'remote', 'file' => 'https://www.mautic.org/media/logos/logo/Mautic_Logo_DB.pdf' ); $asset = $assetApi->create($data);


104/222

17/12/2017


Create a new asset. There are 2 options: local or remote asset. HTTP REQUEST

POST /assets/new

Post Parameters Name

Description

title

string

storageLocation

string

file

string

RESPONSE


Properties Same as Get Asset. EDIT ASSET

= 1;

$data = array( 'type' => 'general', ); // Create new a asset of ID 1 is not found? $createIfNotFound = true; $asset = $assetApi->edit($id, $data, $createIfNotFound);

Edit a new asset. Asset that this supports PUT or PATCH depending on the desired behavior. PUT creates a asset if the given ID does not exist and clears all the asset information, adds the information from the request. PATCH fails if the asset with the given ID does not exist and updates the asset field values with the values form the request. HTTP REQUEST

To edit a asset and return a 404 if the asset is not found: PATCH /assets/ID/edit

To edit a asset and create a new one if the asset is not found: PUT /assets/ID/edit


Description

title

string

storageLocation

string

file

string


105/222

17/12/2017


RESPONSE

If PUT , the expected response code is 200 if the asset was edited or 201 if created. If PATCH , the expected response code is 200 . Properties

Same as Get Asset. DELETE ASSET

delete($id);

Delete a asset. In case of local storage location, the local file will be deleted as well. HTTP REQUEST

DELETE /assets/ID/delete RESPONSE


Properties

Same as Get Asset.

Campaigns Use this endpoint to obtain details on Mautic’s campaigns.

= new ApiAuth();

$auth


$apiUrl


$api

= new MauticApi();

$campaignApi = $api->newApi("campaigns", $auth, $apiUrl);

GET CAMPAIGN

get($id);

Get an individual campaign by ID. HTTP REQUEST

GET /campaigns/ID RESPONSE


106/222

17/12/2017



See JSON code example. Campaign Properties Name

Type

Description

id

int

ID of the campaign

name

string

Name of the campaign

description

string/null

Description of the campaign

alias

string

Used to generate the URL for the campaign

isPublished

bool

Published state

publishUp

datetime/null

Date/time when the campaign should be published

publishDown

datetime/null

Date/time the campaign should be un published

dateAdded

datetime

Date/time campaign was created

createdBy

int

ID of the user that created the campaign

createdByUser

string

Name of the user that created the campaign

dateModified

datetime/null

Date/time campaign was last modified

modifiedBy

int

ID of the user that last modified the campaign

modifiedByUser

string

Name of the user that last modified the campaign

events

array

Array of Event entities for the campaign. See below.

Event Properties Name

Type

Description

id

int

ID of the event

name

string

Name of the event

description

string

Optional description for the event

type

string

Type of event

eventType

string

“action” or “decision”

order

int

Order in relation to the other events (used for levels)

properties

object

Configured properties for the event

triggerMode

string

“immediate”, “interval” or “date”

triggerDate

datetime/null

Date/time of when the event should trigger if triggerMode is “date”

triggerInterval

int/null

Interval for when the event should trigger


107/222

17/12/2017


Name

Type

Description

triggerIntervalUnit

string

Interval unit for when the event should trigger. Options are i = minutes, h = hours, d = days, m = months, y = years

children

array

Array of this event’s children ,

parent

object/null

This event’s parent

decisionPath

string/null

If the event is connected into an action, this will be “no” for the non-decision path or “yes” for the actively followed path.

LIST CAMPAIGNS


HTTP REQUEST

GET /campaigns


Description

search


start


limit


orderBy


orderByDir


published


minimal


RESPONSE


See JSON code example. Properties Same as Get Campaign. LIST CAMPAIGN CONTACTS

This endpoint is basically an alias for the stats endpoint with ‘campaign_leads’ table and campaign_id specified. Other parameters are the same as in the stats endpoint.

getContacts($campaignId, $start, $limit, $order, $where);


108/222

17/12/2017


HTTP REQUEST

GET /campaigns/ID/contacts

Query Parameters RESPONSE


See JSON code example. CREATE CAMPAIGN

=> 'Campaign A',

'description' => 'This is my first campaign created via API.', 'isPublished' => 1 ); $campaign = $campaignApi->create($data);

Create a new campaign. To see more advanced example with campaing events and so on, see the unit tests. HTTP REQUEST

POST /campaigns/new


Description

name

Campaign name is the only required field

alias

string

description

A description of the campaign.

isPublished

A value of 0 or 1

RESPONSE


Properties Same as Get Campaign. EDIT CAMPAIGN

= 1;

$data = array( 'name'

=> 'New campaign name',

'isPublished' => 0 ); // Create new a campaign of ID 1 is not found? $createIfNotFound = true; $campaign = $campaignApi->edit($id, $data, $createIfNotFound);


109/222

17/12/2017


Edit a new campaign. Note that this supports PUT or PATCH depending on the desired behavior. PUT creates a campaign if the given ID does not exist and c lears all the campaign information, adds the information from the request. PATCH fails if the campaign with the given ID does not exist and updates the campaign field values with the values form the request. HTTP REQUEST

To edit a campaign and return a 404 if the campaign is not found: PATCH /campaigns/ID/edit

To edit a campaign and create a new one if the campaign is not found: PUT /campaigns/ID/edit


Description

name

Campaign name is the only required field

alias

Name alias generated automatically if not set

description

A description of the campaign.

isPublished

A value of 0 or 1

RESPONSE

If PUT , the expected response code is 200 if the campaign was edited or 201 if created. If PATCH , the expected response code is 200 . Properties Same as Get Campaign. DELETE CAMPAIGN

delete($id);

Delete a campaign. HTTP REQUEST

DELETE /campaigns/ID/delete RESPONSE


Properties Same as Get Campaign. ADD CONTACT TO A CAMPAIGN

addContact($campaignId, $contactId); if (!isset($response['success'])) {


110/222

17/12/2017


// handle error }

Manually add a contact to a specific campaign. HTTP REQUEST

POST /campaigns/CAMPAIGN_ID/contact/CONTACT_ID/add RESPONSE


See JSON code example. REMOVE CONTACT FROM A CAMPAIGN

removeContact($contactId, $listId); if (!isset($response['success'])) { // handle error }

Manually remove a contact from a specific campaign. HTTP REQUEST

POST /campaigns/CAMPAIGN_ID/contact/CONTACT_ID/remove RESPONSE


See JSON code example.

Categories Use this endpoint to obtain details on Mautic’s categories or to manipulate category memberships.

= new ApiAuth();

$auth


$apiUrl


$api

= new MauticApi();

$categoryApi = $api->newApi("categories", $auth, $apiUrl);

GET CATEGORY

get($id);


111/222

17/12/2017


Get an individual category by ID. HTTP REQUEST

GET /categories/ID RESPONSE


See JSON code example. Category Properties Name

Type

Description

id

int

ID of the category

isPublished

boolean

Whether the category is published

dateAdded

datetime

Date/time category was created

createdBy

int

ID of the user that created the category

createdByUser

string

Name of the user that created the category

dateModified

datetime/null

Date/time category was last modified

modifiedBy

int

ID of the user that last modified the category

modifiedByUser

string

Name of the user that last modified the category

title

string

The category title

alias

string

The category alias

description

string

The category description

color

string

The category color

bundle

string

The bundle where the category will be available

LIST CONTACT CATEGORIES


Returns a list of contact categories available to the user. This list is not filterable. HTTP REQUEST

GET /categories RESPONSE


See JSON code example. Category Properties


112/222

17/12/2017


Name

Type

Description

id

int

ID of the category

isPublished

boolean

Whether the category is published

dateAdded

datetime

Date/time category was created

createdBy

int

ID of the user that created the category

createdByUser

string

Name of the user that created the category

dateModified

datetime/null

Date/time category was last modified

modifiedBy

int

ID of the user that last modified the category

modifiedByUser

string

Name of the user that last modified the category

title

string

The category title

alias

string

The category alias

description

string

The category description

color

string

The category color

bundle

string

The bundle where the category will be available

CREATE CATEGORY

'test', 'categoryemail' => '[email protected]', 'categorycity' => 'Raleigh', ); $category = $categoryApi->create($data);

Create a new category. HTTP REQUEST

POST /categories/new


Description

title

string

bundle

string

RESPONSE


Properties

Same as Get Category.


113/222

17/12/2017


EDIT CATEGORY

= 1;

$data = array( 'title' => 'test', 'bundle' => 'asset' ); // Create new a category of ID 1 is not found? $createIfNotFound = true; $category = $categoryApi->edit($id, $data, $createIfNotFound);

Edit a new category. Note that this supports PUT or PATCH depending on the desired behavior. PUT creates a category if the given ID does not exist and clears all the category information, adds the information from the request. PATCH fails if the category with the given ID does not exist and updates the category field values with the values form the request. HTTP REQUEST

To edit a category and return a 404 if the category is not found: PATCH /categories/ID/edit

To edit a category and create a new one if the category is not found: PUT /categories/ID/edit


Description

title

string

bundle

string

RESPONSE

If PUT , the expected response code is 200 if the category was edited or 201 if created. If PATCH , the expected response code is 200 . Properties Same as Get Category. DELETE CATEGORY

delete($id);

Delete a category. HTTP REQUEST

DELETE /categories/ID/delete RESPONSE



114/222

17/12/2017


Properties Same as Get Category.

Companies Use this endpoint to obtain details on Mautic’s companies or to manipulate contact-company memberships.

= new ApiAuth();

$auth


$apiUrl


$api

= new MauticApi();

$companyApi = $api->newApi("companies", $auth, $apiUrl);

GET COMPANY

get($id);

Get an individual company by ID. HTTP REQUEST

GET /companies/ID RESPONSE


See JSON code example. Company Properties Name

Type

Description

id

int

ID of the company

isPublished

boolean

Whether the company is published

dateAdded

datetime

Date/time company was created

createdBy

int

ID of the user that created the company

createdByUser

string

Name of the user that created the company

dateModified

datetime/null

Date/time company was last modified

modifiedBy

int

ID of the user that last modified the company

modifiedByUser

string

Name of the user that last modified the company


115/222

17/12/2017


Name fields

Type array

Description Custom fields for the company

LIST CONTACT COMPANIES


Returns a list of contact companies available to the user. This list is not filterable. HTTP REQUEST

GET /companies RESPONSE


See JSON code example. Company Properties Name

Type

Description

id

int

ID of the company

isPublished

boolean

Whether the company is published

dateAdded

datetime

Date/time company was created

createdBy

int

ID of the user that created the company

createdByUser

string

Name of the user that created the company

dateModified

datetime/null

Date/time company was last modified

modifiedBy

int

ID of the user that last modified the company

modifiedByUser

string

Name of the user that last modified the company

fields

array

Custom fields for the company

CREATE COMPANY

'test', 'companyemail' => '[email protected]', 'companycity' => 'Raleigh', ); $company = $companyApi->create($data);

Create a new company. HTTP REQUEST

POST /companies/new


116/222

17/12/2017



Description

companyname

Company name is the only required field. Other company fields can be sent with a value

isPublished

A value of 0 or 1

RESPONSE


Properties Same as Get Company. EDIT COMPANY

= 1;

$data = array( 'companyname' => 'test', 'companyemail' => '[email protected]', 'companycity' => 'Raleigh', ); // Create new a company of ID 1 is not found? $createIfNotFound = true; $company = $companyApi->edit($id, $data, $createIfNotFound);

Edit a new company. Note that this supports PUT or PATCH depending on the desired behavior. PUT creates a company if the given ID does not exist and clears all the company information, adds the information from the request. PATCH fails if the company with the given ID does not exist and updates the company field values with the values form the request. HTTP REQUEST

To edit a company and return a 404 if the company is not found: PATCH /companies/ID/edit

To edit a company and create a new one if the company is not found: PUT /companies/ID/edit


Description

companyname

Company name is the only required field. Other company fields can be sent with a value

isPublished

A value of 0 or 1

RESPONSE

If PUT , the expected response code is 200 if the company was edited or 201 if created. If PATCH , the expected response code is 200 . Properties


117/222

17/12/2017


Same as Get Company. DELETE COMPANY

delete($id);

Delete a company. HTTP REQUEST

DELETE /companies/ID/delete RESPONSE


Properties

Same as Get Company. ADD CONTACT TO A COMPANY

addContact($companyId, $contactId); if (!isset($response['success'])) { // handle error }

Manually add a contact to a specific company. HTTP REQUEST

POST /companies/COMPANY_ID/contact/CONTACT_ID/add RESPONSE


See JSON code example. REMOVE CONTACT FROM A COMPANY

removeContact($contactId, $companyId); if (empty($response['success'])) { // handle error }

Manually remove a contact to a specific company. HTTP REQUEST

POST /companies/COMPANY_ID/contact/CONTACT_ID/remove RESPONSE


See JSON code example. https://developer.mautic.org/#plugin-directory-structure

118/222

17/12/2017


Contacts Use this endpoint to manipulate and obtain details on Mautic’s contacts.

= new ApiAuth();

$auth


$apiUrl


$api

= new MauticApi();

$contactApi = $api->newApi("contacts", $auth, $apiUrl);

GET CONTACT

get($id);

Get an individual contact by ID. HTTP REQUEST

GET /contacts/ID RESPONSE


See JSON code example. ** Contact Properties ** Name

Type

Description

id

int

ID of the contact

dateAdded

datetime

Date/time contact was created

createdBy

int

ID of the user that created the contact

createdByUser

string

Name of the user that created the contact

dateModified

datetime/null

Date/time contact was last modified

modifiedBy

int

ID of the user that last modified the contact

modifiedByUser

string

Name of the user that last modified the contact

owner

object

User object that owns the contact.

points

int

Contact’s current number of points

lastActive

datetime/null

Date/time for when the contact was last recorded as active

dateIdentified

datetime/null

Date/time when the contact identified themselves


119/222

17/12/2017


Name

Type

Description

color

string

Hex value given to contact from Point Trigger definitions based on the number of points the contact has been awarded

ipAddresses

array

Array of of IPs cu currently as associated wi with th this co contact

fields

array

Array of all contact fields with data grouped by field group. See JSON code example for format. This array includes an “all” key that includes an single level array of fieldAlias => contactValue pairs.

LIST CONTACTS

getList($searc $contactApi->getList($searchFilter, hFilter, $start, $limit, $orderBy, $orderByDir, $publishedOnly, $minimal);

Get a list of contacts. HTTP REQUEST

GET /contacts

** Query Parameters ** Name

Description

search


start

Starting ro row fo for tth he en entities re returned. De Defaults to to 0. 0.

limit imit

Lim Limit num number ber of of ent entit itiies to ret retur urn. n. Def Default aults s to to the the syst system em confi configu gura rati tion on for pagi pagina nattion ion (3 (30). 0).

orde orderB rBy y

Colu Colum mn to to sor sortt by by. Can Can use any any col colum umn n lilisted sted in the the res respo pons nse. e.

orderBy rByDir

Sort di direction: as asc or or d de esc.

publis pub lished hedOnl Only y

Only Only return return curren currently tly publ publish ished ed entit entities ies..

mini inimal mal

Ret Return urn onl only y arr array ay of entit ntitie ies s wit witho hout ut addi addittiona ionall lis lists ts in it. it.

RESPONSE


See JSON code example. ** Properties ** Same as Get Contact. CREATE CONTACT

'Jim', 'lastname'

=> 'Contact',

'email'

=> '[email protected]', '[email protected]',

'ipAddress' => $_SERVER['REMOTE_ADDR'] $_SERVER['REMOTE_ADDR'] ); $contact = $contactApi->create($data); $contactApi->create($data);


120/222

17/12/2017


Create a new contact. HTTP REQUEST

POST /contacts/new

** Post Parameters ** Name

Description

*

Any Any con conta tact ct field field alia alias s can can be post posted ed as a par param amet eter er.. For For exam exampl ple, e, first firstna name me,, las lastn tnam ame, e, emai email, l, etc. etc.

ipAddr ipAddress ess

IP addr address ess to to associ associate ate with with the the contac contactt

lastActive

Date/time in UTC; preferablly in the format of Y-m-d H:m:i but if that format fails, the string will be sent through PHP’s strtotime then formatted

owne ownerr

ID of of a Mau Mauttic user user to assi assign gn this his con conta tact ct to

RESPONSE


** Properties ** Same as Get Contact. EDIT CONTACT

= 1;

$data = array( 'email'

=> '[email protected] '[email protected]', m',

'ipAddress' => $_SERVER['REMOTE_ADDR'] $_SERVER['REMOTE_ADDR'] ); // Create new a contact of ID 1 is not found? $createIfNotFound $createIfNotFound = true; $contact = $contactApi->edit($id, $contactApi->edit($id, $data, $createIfNotFound); $createIfNotFound);

Edit a new contact. Note that this supports PUT or PATCH PATCH depending on the desired behavior. ** PUT ** creates a contact if the given ID does not exist and clears all the contact information, adds the information from the request. PATCH fails PATCH fails if the contact with the given ID does not exist and updates the contact field values with the values form the request. HTTP REQUEST

To edit a contact and return a 404 if the contact is not found: PATCH /contacts/ID/edit

To edit a contact and create a new one if the contact is not found: PUT /contacts/ID/edit

** Post Parameters ** Name *

Description Any Any con conta tact ct field field alia alias s can can be post posted ed as a par param amet eter er.. For For exam exampl ple, e, first firstna name me,, las lastn tnam ame, e, emai email, l, etc. etc.


121/222

17/12/2017


Name

Description

ipAddr ipAddress ess

IP addr address ess to to associ associate ate with with the the contac contactt

lastActive

Date/time in UTC; preferably in the format of Y-m-d H:m:i but if that format fails, the string will be s ent through PHP’s strtotime then formatted

owne ownerr

ID of of a Mau Mauttic user user to assi assign gn this his con conta tact ct to

RESPONSE

If PUT , the expected response code is 200 if the contact was edited or 201 if created. If PATCH , the expected response code is 200 . ** Properties ** Same as Get Contact. DELETE CONTACT

delete($id); $contactApi->delete($id);

Delete a contact. HTTP REQUEST

DELETE /contacts/ID/delete RESPONSE


** Properties ** Same as Get Contact. ADD DO NOT CONTACT

'Score via api', 'actionName' => 'Adding', ); $contactApi->addDnc($contact $contactApi->addDnc($contactId, Id, $channel, $reason, $channelId, $comments);

Add a contact to DNC list HTTP REQUEST

To add Do Not Contact entry to a contact: PATCH /contacts/ID/dnc/add/CHANNEL

** Data Parameters (optional) ** Name

chan channe nell

Description

Chan Channe nell of DNC DNC.. For For exam exampl ple e ‘ema ‘email il’, ’, 'sm 'sms’ s’… … Defa Defaul ultt is ema email il..


122/222

17/12/2017


Name

Description

reason

Int value of the reason. Use Contacts constants: Contacts::UNSUBSCRIBED, Contacts::UNSUBSCRIBED, Contacts::BOUNCED, Contacts::MANUAL. Default is Manual

channe channelId lId

ID of the entity entity which which was was the reas reason on for for unsubs unsubscri cripti ption on

commen comments ts

A text text descri describin bing g detai details ls of of DNC DNC entry entry

RESPONSE

Same as Get Contact. REMOVE FROM DO NOT CONTACT

addDnc($contact $contactApi->addDnc($contactId, Id, $channel);

Remove a contact from DNC list HTTP REQUEST

To remove Do Not Contact entry from a contact: PATCH /contacts/ID/dnc/remove/CHANNEL


Description

channel channel

Channel Channel of DNC. For example example 'email’ 'email’,, 'sms’… 'sms’… Default Default is email. email.

RESPONSE

Same as Get Contact. ADD POINTS

'Score via api', 'actionName' => 'Adding', ); $contactApi->addPoints($cont $contactApi->addPoints($contactId, actId, $pointDelta, $data);

Add contact points HTTP REQUEST

To add points to a c ontact and return a 404 if the lead is not found: POST /contacts/ID/points/plus/POINTS


Description

even eventtNam Name

Nam Name of of the the even eventt

acti action onNa Name me

Name Name of the the acti action on


123/222

17/12/2017


RESPONSE

Expected Response Code: 200 json { "success": true } SUBTRACT POINTS

'Score via api', 'actionname' => 'Subtracting', ); $contactApi->subtractPoints($contactId, $pointDelta, $data);

Subtract contact points HTTP REQUEST

To subtract points from a contact and return a 404 if the contact is not found: POST /contacts/ID/points/minus/POINTS


Description

eventname

Name of the event

actionname

Name of the action

RESPONSE

Expected Response Code: 200 json { "success": true } LIST AVAILABLE OWNERS

getOwners();

Get a list of owners that can be used to assign contacts to when creating/editing. HTTP REQUEST

GET /contacts/list/owners RESPONSE


** Owner Properties ** Name

Type

Description

id

int

ID of the Mautic user

firstName

string

First name of the Mautic user

lastName

string

Last name of the Mautic user

LIST AVAILABLE FIELDS


124/222

17/12/2017


getFieldList();

Get a list of available contact fields including custom ones. HTTP REQUEST

GET /contacts/list/fields RESPONSE


** Field Properties ** Name

Type

Description

id

int

ID of the field

label

string

Field label

alias

string

Field alias used as the column name in the database

type

string

Type of field. I.e. text, lookup, etc

group

string

Group the field belongs to

order

int

Field order

LIST CONTACT NOTES

getContactNotes($id, $searchFilter, $start, $limit, $orderBy, $orderByDir, $publishedOnly, $minimal);

Get a list of notes for a specific contact. HTTP REQUEST

GET /contacts/ID/notes


Description

search


start


limit


orderBy


orderByDir


RESPONSE

Expected response code: 200

** Note Properties ** https://developer.mautic.org/#plugin-directory-structure

125/222

17/12/2017


Name

Type

Description

id

int

ID of the note

text

string

Body of the note

type

string

Type of note. Options are “general”, “email”, “call”, “meeting”

dateTime

datetime

Date/time string of when the note was created.

GET SEGMENT MEMBERSHIPS

getContactSegments($id);

Get a list of contact segments the contact is a member of. HTTP REQUEST

GET /contacts/ID/segments RESPONSE


** List Properties ** Name

Type

Description

id

int

ID of the list

name

string

Name of the list

alias

string

Alias of the list used with search commands.

dateAdded

datetime

Date/time string for when the contact was added to the list

manuallyAdded

bool

True if the contact was manually added to the list versus being added by a filter

manuallyRemoved

bool

True if the contact was manually removed from the list even though the list’s filter is a match

CHANGE LIST MEMBERSHIPS

See Segements. GET CAMPAIGN MEMBERSHIPS

getContactCampaigns($id);

Get a list of campaigns the contact is a member of. HTTP REQUEST

GET /contacts/ID/campaigns RESPONSE



126/222

17/12/2017



Type

Description

id

int

ID of the campaign

name

string

Name of the campaign

dateAdded

datetime

Date/time string for when the contact was added to the campaign

manuallyAdded

bool

True if the contact was manually added to the campaign versus being added by a contact list

manuallyRemoved

bool

True if the contact was manually removed from the campaign when the contact’s list is assigned to the campaign

listMembership

array

Array of contact list IDs this contact belongs to that is also associated with this campaign

CHANGE CAMPAIGN MEMBERSHIPS

See Campaigns. GET CONTACT’S EVENTS

getEvents($id, $search, $includeEvents, $excludeEvents, $orderBy, $orderByDir, $page);

Warining: Deprecated. Use getActivityForContact instead. ** Query Parameters ** Name

Description

id

Contact ID

filters[search]

String or search command to filter events by.

filters[includeEvents][]

Array of event types to include.

filters[excludeEvents][]

Array of event types to exclude.

orderBy


orderByDir


page

What page number to load

Get a list of contact events the contact created. HTTP REQUEST

GET /contacts/ID/events

Warining: Deprecated. Use GET /contacts/ID/activity instead. RESPONSE


** List Properties **


127/222

17/12/2017


Name

Type

Description

events

array

List of events

event

string

ID of the event type

icon

string

Icon class from FontAwesome

eventType

string

Human name of the event

eventPriority

string

Priority of the event

timestamp

timestamp

Date and time when the event was created

featured

bool

Flag whether the event is featured

filters

array

Filters used in the query

order

array

Ordering used in the query

types

array

Array of available event types

total

int

Total number of events in the request

page

int

Current page number

limit

int

Limit of events per page

maxPages

int

How many pages of events are there

GET ACTIVITY EVENTS FOR SPECIFIC CONTACT

getActivityForContact($id, $search, $includeEvents, $excludeEvents, $orderBy, $orderByDir, $page, $dateFrom, $dateTo);


Description

id

Contact ID

filters[search]






filters[dateFrom]

Date from filter. Must be type of

filters[dateTo]

Date to filter. Must be type of

orderBy


orderByDir


page


\DateTime for

\DateTime for

the PHP API libary and in format

the PHP API libary and in format

Y-m-d H:i:s for

Y-m-d H:i:s for

HTTP param

HTTP param

Get a list of contact events the contact had created. HTTP REQUEST


128/222

17/12/2017


GET /contacts/ID/activity RESPONSE



Type

Description

events

array

List of events

event

string


icon

string


eventType

string


eventPriority

string


timestamp

timestamp


featured

bool


filters

array


order

array


types

array


total

int


page

int

Current page number

limit

int


maxPages

int


GET ACTIVITY EVENTS FOR ALL CONTACTS

getActivity($search, $includeEvents, $excludeEvents, $orderBy, $orderByDir, $page, $dateFrom, $dateTo);


Description

filters[search]






filters[dateFrom]

Date from filter. Must be type of \DateTime for the PHP API libary and in format Y-m-d H:i:s for HTTP param

filters[dateTo]

Date to filter. Must be type of \DateTime for the PHP API libary and in format Y-m-d H:i:s for HTTP param

orderBy


orderByDir



129/222

17/12/2017


Name

Description

page


HTTP REQUEST

GET /contacts/events RESPONSE



Type

Description

events

array

List of events

event

string


icon

string


eventType

string


eventPriority

string


contactId

ID of the contact who created the event

timestamp

timestamp


featured

bool


filters

array


order

array


types

array


total

int


page

int

Current page number

limit

int


maxPages

int


GET CONTACT’S COMPANIES

getContactCompanies($contactId); ```json { "total":1, "companies":[ { "company_id":"420", "date_associated":"2016-12-27 15:03:43", "is_primary":"0", "companyname":"test", "companyemail":"[email protected]", "companycity":"Raleigh",


130/222

17/12/2017


"score":"0", "date_added":"2016-12-27 15:03:42" } ]

}

Get a list of contact’s companies the contact belongs to. HTTP REQUEST

GET /contacts/ID/companies RESPONSE


List Properties Name

Type

Description

company_id

int

Company ID

date_associated

datetime

Date and time when the contact was associated to the company

date_added

datetime

Date and time when the company was created

is_primary

bool

Flag whether the company association is primary (current)

companyname

string

Name of the company

companyemail

string

Email of the company

companycity

string

City of the company

score

int

Score of the company

GET CONTACT’S DEVICES

getContactDevices($contactId); ```json { "total":1, "devices":[ { "id":60, "lead":[], "clientInfo":[], "device":"desktop", "deviceOsName":"Ubuntu", "deviceOsShortName":"UBT", "deviceOsPlatform":"x64" } ] }

Get a list of contact’s devices the contact has used. HTTP REQUEST

GET /contacts/ID/devices RESPONSE


131/222

17/12/2017



List Properties Name

Type

Description

id

int

Device ID

clientInfo

array

Array with various information about the client (browser)

device

string

Device type; desktop, mobile..

deviceOsName

string

Full device OS name

deviceOsShortName

string

Short device OS name

deviceOsPlatform

string

OS p latform

Data - Dashboard widget data Use this endpoint to obtain details on Mautic’s dashboard statistical data.

= new ApiAuth();

$auth


$apiUrl


$api

= new MauticApi();

$contactApi = $api->newApi("data", $auth, $apiUrl);

GET LIST OF AVAILABLE WIDGET TYPES

getList();

HTTP REQUEST

GET /data Expected Response Code: 200 GET AN INDIVIDUAL WIDGET DATA BY TYPE.

get($type, $options);

HTTP REQUEST

GET /data/{type}?dateFrom={YYYY-mm-dd}&dateTo={YYYY-mm-dd}&timeUnit={m}

Returns response which can be directly visualized byt the chartJS library. RESPONSE


132/222

17/12/2017


Expected Response Code: 200 HTTP REQUEST

GET /data/{type}?dateFrom={YYYY-mm-dd}&dateTo={YYYY-mm-dd}&timeUnit={m}&dataFormat={raw}

Returns raw format which can be more easily processed. RESPONSE


Available data URL query params Name|Type|Example|Description —-|—-|———– timezone|string|America/New_York|PHP timezone dateFrom|string|2016-28-03|Date from in the YYYY-mm-dd HH:ii:ss format dateTo|string|2016-28-04|Date to in the YYYY-mm-dd HH:ii:ss format timeUnit|string|m|Date/Time unit. Available options: Y, m, W, d, H limit|int|10|Limit of the table widget items filter|array|[lead_id => 23]|filters which should be applied to the SQL query

Dynamic Content Use this endpoint to obtain details on Mautic’s web dynamic content.

= new ApiAuth();

$auth


$apiUrl


$api

= new MauticApi();

$dynamicContentApi = $api->newApi("dynamicContents", $auth, $apiUrl);

GET DYNAMIC CONTENT

get($id);

Get an individual dynamicContent by ID. HTTP REQUEST

GET /dynamiccontents/ID RESPONSE


See JSON code example. Dynamic Content Properties Name id

Type int

Description ID of the dynamic content


133/222

17/12/2017


Name

Type

Description

name

string

Name of the dynamic content

description

string/null

Description of the dynamic content

isPublished

bool

Published state

publishUp

datetime/null

Date/time when the dynamic content should be published

publishDown

datetime/null

Date/time the dynamic content should be un published

dateAdded

datetime

Date/time dynamic content was created

createdBy

int

ID of the user that created the dynamic content

createdByUser

string

Name of the user that created the dynamic content

dateModified

datetime/null

Date/time dynamic content was last modified

modifiedBy

int

ID of the user that last modified the dynamic content

modifiedByUser

string

Name of the user that last modified the dynamic content

variantChildren

array

Array of Dynamic Content entities for variants of this landing dynamic content

variantParent

object

The parent/main dynamic content if this is a variant (A/B test)

sentCount

int

Count of how many times the dynamic content was sent

LIST DYNAMIC CONTENTS


HTTP REQUEST

GET /dynamiccontents


Description

search


start


limit


orderBy


orderByDir


publishedOnly


minimal


RESPONSE


134/222

17/12/2017



See JSON code example. Properties

Same as Get Dynamic Content. CREATE DYNAMIC CONTENT

=> 'Dynamic Content A',

'isPublished' => 1 ); $dynamicContent = $dynamicContentApi->create($data);

Create a new dynamicContent. HTTP REQUEST

POST /dynamiccontents/new


Type

Description

id

int

ID of the dynamic content

name

string


description

string/null


isPublished

bool

Published state

publishUp

datetime/null


publishDown

datetime/null


dateAdded

datetime


createdBy

int


createdByUser

string


dateModified

datetime/null


modifiedBy

int


modifiedByUser

string


variantChildren

array


variantParent

object


sentCount

int


RESPONSE



135/222

17/12/2017


Properties Same as Get Dynamic Content. EDIT DYNAMIC CONTENT

= 1;


=> 'New dynamicContent name',

'isPublished' => 0 ); // Create new a dynamicContent of ID 1 is not found? $createIfNotFound = true; $dynamicContent = $dynamicContentApi->edit($id, $data, $createIfNotFound);

Edit a new dynamicContent. Note that this supports PUT or PATCH depending on the desired behavior. PUT creates a dynamicContent if the given ID does not exist and clears all the dynamic content information, adds the information from the request. PATCH fails if the dynamic content with the given ID does not exist and updates the dynamic content field values with the values form the request. HTTP REQUEST

To edit a dynamicContent and return a 404 if the dynamic content is not found: PATCH /dynamiccontents/ID/edit

To edit a dynamicContent and create a new one if the dynamic content is not found: PUT /dynamiccontents/ID/edit


Type

Description

id

int

ID of the dynamic content

name

string


description

string/null


isPublished

bool

Published state

publishUp

datetime/null


publishDown

datetime/null


dateAdded

datetime


createdBy

int


createdByUser

string


dateModified

datetime/null


modifiedBy

int


modifiedByUser

string



136/222

17/12/2017


Name

Type

Description

variantChildren

array


variantParent

object


sentCount

int


RESPONSE

If PUT , the expected response code is 200 if the dynamic content was edited or 201 if created. If PATCH , the expected response code is 200 . Properties

Same as Get Dynamic Content. DELETE DYNAMIC CONTENT

delete($id);

Delete a dynamicContent. HTTP REQUEST

DELETE /dynamiccontents/ID/delete RESPONSE


Properties

Same as Get Dynamic Content.

Emails Use this endpoint to obtain details, create, update or delete Mautic’s emails.


$apiUrl


$api

= new MauticApi();

$emailApi = $api->newApi("emails", $auth, $apiUrl);

GET EMAIL

get($id);


137/222

17/12/2017


Get an individual email by ID. HTTP REQUEST

GET /emails/ID RESPONSE


See JSON code example. Email Properties Name

Type

Description

id

int

ID of the email

name

string

Internal name of the email

subject

stringl

Subject of the email

fromAddress

string

The from email address if it’s different than the one in the Mautic configuration

fromName

string

The from name if it’s different than the one in the Mautic configuration

replyToAddress

string

The reply to email address if it’s different than the one in the Mautic configuration

bccAddress

string

The BCC email address if it’s different than the one in the Mautic configuration

isPublished

bool

Published state

publishUp

datetime/null

Date/time when the email should be published

publishDown

datetime/null

Date/time the email should be un published

dateAdded

datetime

Date/time email was created

createdBy

int

ID of the user that created the email

createdByUser

string

Name of the user that created the email

dateModified

datetime/null

Date/time email was last modified

modifiedBy

int

ID of the user that last modified the email

modifiedByUser

string

Name of the user that last modified the email

language

string

Language locale of the email

readCount

int

Total email read count

sentCount

int

Total email sent count

revision

int

Email revision

customHtml

string

The HTML content of the email

plainText

string

The plain text content of the email

template

string

The name of the template used as the base for the email


138/222

17/12/2017


Name

Type

Description

emailType

string

If itit is is a segment (f (former lilist) em email or or te template em email. Po Possible va values ar are ‘l‘list’ an and 't'template’

trans ransla lattionC ionChi hilldren dren

arra array y

Arra rray of Page age enti entiti ties es for for tran transl slat atio ions ns of this his landi anding ng page page

translationParent

object

The parent/main page if this is a translation

variantSentCount

i nt

Sent count since variantStartDate

variantReadCount

i nt

Read co count si since va variantStartDate

variantChildren

array

Array of of Em Email en entities fo for va variants of of th this la landing em email

variantParent

object

The parent/main email if this is a variant (A/B test)

variantSettings

array

The properties of the A/B test

vari varian antS tSta tart rtDa Date te

date dateti time me/n /nul ulll

The The date date/t /tim ime e the the A/B A/B test test bega began n

category

object/null

Category information

unsubscribeForm

i nt

Id of the form displayed in the unsubscribe page

dynamicContent

object

Dynamic content configuration

lists

array

Array of segment IDs which should be added to the segment email

LIST EMAILS

getList($searchF $emailApi->getList($searchFilter, ilter, $start, $limit, $orderBy, $orderByDir, $publishedOnly, $minimal);

HTTP REQUEST

GET /emails


Description

search


start

Starting ro row fo for tth he en entities re returned. De Defaults to to 0. 0.

limit imit

Lim Limit num number ber of of ent entit itiies to ret retur urn. n. Def Default aults s to to the the syst system em confi configu gura rati tion on for pagi pagina nattion ion (3 (30). 0).

orde orderB rBy y

Colu Colum mn to to sor sortt by by. Can Can use any any col colum umn n lilisted sted in the the res respo pons nse. e.

orderBy rByDir

Sort di direction: as asc or or d de esc.

publis pub lished hedOnl Only y

Only Only return return curren currently tly publ publish ished ed entit entities ies..

mini inimal mal

Ret Return urn onl only y arr array ay of entit ntitie ies s wit witho hout ut addi addittiona ionall lis lists ts in it. it.

RESPONSE



139/222

17/12/2017



Same as Get Email. CREATE EMAIL

=> 'Email A',

'description' => 'This is my first email created via API.', 'isPublished' => 1 ); $email = $emailApi->create($data); $emailApi->create($data);

Create a new email. HTTP REQUEST

POST /emails/new


Type

Description

id

i nt

ID of the email

name

string


subject

stringl


fromAddress

string

The from email address ifif it’s di different than th the one in in th the Mautic configuration

fromName

string


repl replyT yToA oAdd ddre ress ss

stri string ng

The The repl reply y to emai emaill addr addres ess s if it’ it’s dif differen erentt than han the one one in the Mau Mautic tic confi config gurat uratio ion n

bccAddress

string


isPublished

bool

Published state

publishUp

datetime/null


publishDown

datetime/null

Date/time th the em email sh should be be un un pu publishe shed

language

string


readCount

i nt


sentCount

i nt


revision

i nt

Email revision

customHtml

string


plainText

string


template

string


emailType

string

If itit is is a segment (f (former lilist) em email or or te template em email. Po Possible va values ar are 'l'list’ an and 't'template’


140/222

17/12/2017


Name

Type

Description


arra array y


translationParent

object


variantSentCount

i nt


variantReadCount

i nt


variantChildren

array


variantParent

object


variantSettings

array





category

object/null


unsubscribeForm

i nt


dynamicContent

object


lists

array


RESPONSE


Properties Same as Get Email. EDIT EMAIL

= 1;

$data = array( 'title'

=> 'New email title',

'isPublished' => 0 ); // Create new a email of ID 1 is not found? $createIfNotFound $createIfNotFound = true; $email = $emailApi->edit($id, $emailApi->edit($id, $data, $createIfNotFound); $createIfNotFound);

Edit a new email. Note that this supports PUT or PATCH PATCH depending on the desired behavior. PUT creates PUT creates a email if the given ID does not exist and clears all the email information, adds the information from the request. PATCH fails PATCH fails if the email with the given ID does not exist and updates the email field values with the values form the request. HTTP REQUEST

To edit a email and return a 404 if the email is not found: PATCH /emails/ID/edit

To edit a email and create a new one if the email is not found: PUT /emails/ID/edit


141/222

17/12/2017



Type

Description

id

i nt

ID of the email

name

string


subject

stringl


fromAddress

string

The from email address ifif it’s di different than th the one in in th the Mautic configuration

fromName

string


repl replyT yToA oAdd ddre ress ss

stri string ng

The The repl reply y to emai emaill addr addres ess s if it’ it’s dif differen erentt than han the one one in the Mau Mautic tic confi config gurat uratio ion n

bccAddress

string


isPublished

bool

Published state

publishUp

datetime/null


publishDown

datetime/null

Date/time th the em email sh should be be un un pu publishe shed

language

string


readCount

i nt


sentCount

i nt


revision

i nt

Email revision

customHtml

string


plainText

string


template

string


emailType

string

If itit is is a segment (f (former lilist) em email or or te template em email. Po Possible va values ar are 'l'list’ an and 't'template’


arra array y


translationParent

object


variantSentCount

i nt


variantReadCount

i nt


variantChildren

array


variantParent

object


variantSettings

array





category

object/null


unsubscribeForm

i nt


dynamicContent

object



142/222

17/12/2017


Name

Type

lists

array

Description


RESPONSE

If PUT , the expected response code is 200 if the email was edited or 201 if created. If PATCH , the expected response code is 200 . Properties

Same as Get Email. DELETE EMAIL

delete($id);

Delete a email. HTTP REQUEST

DELETE /emails/ID/delete RESPONSE


Properties

Same as Get Email. SEND EMAIL TO CONTACT

sendToContact($emailId, $contactId);

Send a predefined email to existing contact. HTTP REQUEST

POST /emails/ID/contact/CONTACT_ID/send


Type

Description

tokens

array

Array of tokens in email

RESPONSE


Properties json { "success": 1 } SEND EMAIL TO SEGMENT

send($id);


143/222

17/12/2017


Send a segment email to linked segment(s). HTTP REQUEST

POST /emails/ID/send RESPONSE


Properties json { "success": 1, "sentCount": 1, "failedCount": 0 }

Fields Use this endpoint to work with Mautic’s contact/company fields.


$apiUrl


$api

= new MauticApi();

$assetApi = $api->newApi("assets", $auth, $apiUrl); // Get contact field context: $fieldApi = $api->newApi("contactFields", $auth, $apiUrl); // Or use 'companyFields' for company fields: $fieldApi = $api->newApi("companyFields", $auth, $apiUrl);

GET FIELD

get($id);

Get an individual field by ID. HTTP REQUEST

GET /fields/contact/ID or GET /fields/company/ID RESPONSE


See JSON code example. Field Properties Name

id

Type

int

Description

ID of the field


144/222

17/12/2017


Name

Type

Description

isPublished

bool

Published state

publishUp

datetime/null

Date/time when the field should be published

publishDown

datetime/null

Date/time the field should be un published

dateAdded

datetime

Date/time field was created

createdBy

int

ID of the user that created the field

createdByUser

string

Name of the user that created the field

dateModified

datetime/null

Date/time field was last modified

modifiedBy

int

ID of the user that last modified the field

modifiedByUser

string

Name of the user that last modified the field

label

string

Name of the field

alias

string

Unique alias of the field used in the form field name attributes

description

string/null

Description of the field

type

string

Field type

group

string

Groupd of the fields where the field belongs

order

int

Order number of the field

object

string

Which object use the field. Contact (lead) or Company.

defaultValue

string

Default value of the field.

isRequired

boolean

True if the field is required.

isPubliclyUpdatable

boolean

True if the field value can be changed from public requests. The tracking pixel query for example.

isUniqueIdentifier

boolean

True if the field is unique identifier and so the contacts should merge if the value of this field is the same.

properties

array

Field options if the field type needs some.

LIST CONTACT FIELDS



Description

search


start


limit



145/222

17/12/2017


Name

Description

orderBy


orderByDir


publishedOnly


minimal


HTTP REQUEST

GET /fields/contact or GET /fields/company RESPONSE


See JSON code example. Field Properties Name

Type

Description

id

int

ID of the field

isPublished

bool

Published state

publishUp

datetime/null

Date/time when the field should be published

publishDown

datetime/null

Date/time the field should be un published

dateAdded

datetime

Date/time field was created

createdBy

int

ID of the user that created the field

createdByUser

string

Name of the user that created the field

dateModified

datetime/null

Date/time field was last modified

modifiedBy

int

ID of the user that last modified the field

modifiedByUser

string

Name of the user that last modified the field

label

string

Name of the field

alias

string

Unique alias of the field used in the form field name attributes

description

string/null

Description of the field

type

string

Field type

group

string

Groupd of the fields where the field belongs

order

int

Order number of the field

object

string

Which object use the field. Contact (lead) or Company.

defaultValue

string

Default value of the field.

isRequired

boolean

True if the field is required.


146/222

17/12/2017


Name

Type

Description

isPubliclyUpdatable

boolean

True if the field value can be changed from public requests. The tracking pixel query for example.

isUniqueIdentifier

boolean

True if the field is unique identifier and so the contacts should merge if the value of this field is the same.

properties

array

Field options if the field type needs some.

CREATE FIELD

'API test field', 'type' => 'text', ); $field = $fieldApi->create($data);

Create a new field. HTTP REQUEST

POST /fields/contact/new or POST /fields/company/new


Description

label

string

alias

string

description

string/null

type

string

group

string

order

int

object

string

defaultValue

string

isRequired

boolean

isPubliclyUpdatable

boolean

isUniqueIdentifier

boolean

properties

array

RESPONSE


Properties

Same as Get Field.


147/222

17/12/2017


EDIT FIELD

= 1;

$data = array( 'label' => 'API test field', 'type' => 'text', ); // Create new a field of ID 1 is not found? $createIfNotFound = true; $field = $fieldApi->edit($id, $data, $createIfNotFound);

Edit a new field. Field that this supports PUT or PATCH depending on the desired behavior. PUT creates a field if the given ID does not exist and clears all the field infieldation, adds the infieldation from the request. PATCH fails if the field with the given ID does not exist and updates the field field values with the values field the request. HTTP REQUEST

To edit a field and return a 404 if the field is not found: PATCH /fields/contact/ID/edit or PATCH /fields/company/ID/edit

To edit a field and create a new one if the field is not found: PUT /fields/contact/ID/edit or PUT /fields/company/ID/edit


Description

label

string

alias

string

description

string/null

type

string

group

string

order

int

object

string

defaultValue

string

isRequired

boolean

isPubliclyUpdatable

boolean

isUniqueIdentifier

boolean

properties

array

RESPONSE

If PUT , the expected response code is 200 if the field was edited or 201 if created. If PATCH , the expected response code is 200 . https://developer.mautic.org/#plugin-directory-structure

148/222

17/12/2017


Properties

Same as Get Field. DELETE FIELD

delete($id);

Delete a field. HTTP REQUEST

DELETE /fields/contact/ID/delete or DELETE /fields/company/ID/delete RESPONSE


Properties

Same as Get Field.

Files This endpoint is useful for working with fi les of images and assets. Note: Assets doesn’t have nor support subdirectories.


$apiUrl


$api

= new MauticApi();

$filesApi = $api->newApi("files", $auth, $apiUrl);

GET LIST OF FILES

getList(); // Get list of some sub-directory (flags in this case) of media/images: $filesApi->setFolder('images/flags'); $files = $filesApi->getList(); // Get list of root media/files directory where the asset files are stored: $files = $filesApi->setFolder('assets'); $files = $filesApi->getList();

HTTP REQUEST

GET /files/images to

get root images directory GET /files/images?subdir=flags to get images/flags directory GET /files/assets to get

root assets directory https://developer.mautic.org/#plugin-directory-structure

149/222

17/12/2017


RESPONSE


See JSON code example. Response Properties Name

Type

Description

files

array

List of requested files and directories

CREATE FILE

dirname(__DIR__).'/'.'mauticlogo.png' // Must be a path to an existing file ); // Create a file in root media/images directory: $response = $fileApi->create($data); // Create a file in some sub-directory (flags in this case) of media/images: $filesApi->setFolder('images/flags'); $response = $fileApi->create($data); // Create a file in media/files directory where the asset files are stored: $files = $filesApi->setFolder('assets'); $response = $fileApi->create($data);

Creates a file. The file is sent via regular POST files array like a browser sends it during file upload. HTTP REQUEST

POST /files/DIR/new RESPONSE

Expected Response Code: 200 json { "file":{ "link":"http:\/\/yourmautic\/media\/images\/2b912b934dd2a4da49a226d0bf68bfea.png", "name":"2b912b934dd2a4da49a226d0bf68bfea.png" } }

Response Properties Name

Type

Description

link

string

Appears only for files in image directory, not for assets

name

string

File name of newly created file

DELETE FILE

delete($fileName); // Delete a file from some sub-directory (flags in this case) of media/images: $filesApi->setFolder('images/flags'); $response = $fileApi->delete($fileName); // Delete a file from media/files directory where the asset files are stored: $files = $filesApi->setFolder('assets'); $response = $fileApi->delete($fileName);


150/222

17/12/2017


Delete a file. HTTP REQUEST

DELETE /files/DIR/FILE/delete RESPONSE

Expected Response Code: 200 json { "success": true }

Forms Use this endpoint to obtain details on Mautic’s forms.


$apiUrl


$api

= new MauticApi();

$formApi

= $api->newApi("forms", $auth, $apiUrl);

GET FORM

get($id);

Get an individual form by ID. HTTP REQUEST

GET /forms/ID RESPONSE


See JSON code example. Form Properties Name

Type

Description

id

int

ID of the form

name

string

Name of the form

description

string/null

Description of the form

alias

string

Used to generate the URL for the form

isPublished

bool

Published state

publishUp

datetime/null

Date/time when the form should be published


151/222

17/12/2017


Name

Type

Description

publishDown

datetime/null

Date/time the form should be un published

dateAdded

datetime

Date/time form was created

createdBy

int

ID of the user that created the form

createdByUser

string

Name of the user that created the form

dateModified

datetime/null

Date/time form was last modified

modifiedBy

int

ID of the user that last modified the form

modifiedByUser

string

Name of the user that last modified the form

cachedHtml

string

Cached HTML for the form

template

string/null

Name of the template used to generate the HTML

fields

array

Array of Field entities for the form. See below.

actions

array

Array of Action entities for the form. See below.

Field Properties Name

Type

Description

id

int

ID of the field

label

string

Label of the field

showLabel

bool

Display the label of the field

alias

string

Alias of the field (used as the database column)

type

string

Field type

defaultValue

string

Default value

isRequired

bool

Field is required

validationMessage

string

Validation message if required field is left empty

helpMessage

string

Help message for the field

order

int

Order of the field

properties

array

Configured properties for the field

labelAttributes

string/null

Custom HTML attributes for the label

inputAttributes

Custom HTML attributes for the input

containerAttributes

Custom HTML attributes for the container

Action Properties Name

Type

Description


152/222

17/12/2017


Name

Type

Description

id

int

ID of the action

type

string

Action type

name

string

Name of the action

description

string/null

Description of the action

order

int

Action order

properties

array

Configured properties for the action

LIST FORMS


HTTP REQUEST

GET /forms


Description

search


start


limit


orderBy


orderByDir


publishedOnly


minimal


RESPONSE


See JSON code example. Properties Same as Get Form. CREATE FORM

'test', 'formType' => 'standalone', 'description' => 'API test', 'fields' => array(


153/222

17/12/2017

Mautic Developer Documentation array( 'label' => 'field name', 'type' => 'text' )

), 'actions' => array( array( 'name' => 'action name', 'description' => 'action desc', 'type' => 'lead.pointschange', 'properties' => array( 'operator' => 'plus', 'points' => 2 ) ) ) ); $form = $formApi->create($data);

Create a new form. HTTP REQUEST

POST /forms/new

Post Parameters

Same as Get Form. Form fields and actions can be created/edited via the forms/actions arrays in the form array. RESPONSE


Properties

Same as Get Form. EDIT FORM

= 1;

$data = array( 'name' => 'test', 'formType' => 'standalone', 'description' => 'API test', 'fields' => array( array( 'label' => 'field name', 'type' => 'text' ) ), 'actions' => array( array( 'name' => 'action name', 'description' => 'action desc', 'type' => 'lead.pointschange', 'properties' => array( 'operator' => 'plus', 'points' => 2 ) ) ) ); // Create new a form of ID 1 is not found? $createIfNotFound = true;


154/222

17/12/2017


$form = $formApi->edit($id, $data, $createIfNotFound);

Edit a new form. Note that this supports PUT or PATCH depending on the desired behavior. PUT creates a form if the given ID does not exist and c lears all the form information, adds the information from the request. Form fields and actions will be also deleted if not pres ent in the request. PATCH fails if the form with the given ID does not exist and updates the form field values with the values form the request. HTTP REQUEST

To edit a form and return a 404 if the form is not found: PATCH /forms/ID/edit

To edit a form and create a new one if the form is not found: PUT /forms/ID/edit

Post Parameters Same as Get Form. Form fields and actions can be created/edited via the forms/actions arrays in the form array. RESPONSE

If PUT , the expected response code is 200 if the form was edited or 201 if created. If PATCH , the expected response code is 200 . Properties Same as Get Form. DELETE FORM

delete($id);

Delete a form. HTTP REQUEST

DELETE /forms/ID/delete RESPONSE


Properties Same as Get Form. DELETE FORM FIELDS

The following examples will show how to delete fi elds with ID 56 and 59.

deleteFields($formId, array(56, 59));

Delete a form fields. HTTP REQUEST


155/222

17/12/2017


DELETE /forms/ID/fields/delete?fields[]=56&fields[]=59 RESPONSE


Properties Same as Get Form. DELETE FORM ACTIONS

The following examples will show how to delete ac tions with ID 56 and 59.

deleteActions($formId, array(56, 59));

Delete a form actions. HTTP REQUEST

DELETE /forms/ID/actions/delete?actions[]=56&actions[]=59 RESPONSE


Properties Same as Get Form. LIST FORM SUBMISSIONS

getSubmissions($formId, $searchFilter, $start, $limit, $orderBy, $orderByDir, $publishedOnly, $minimal);

HTTP REQUEST

GET /forms/FORM_ID/submissions


Description

formId

ID of the form you want to get submissions for

search


start


limit


orderBy


orderByDir


publishedOnly


minimal


RESPONSE


156/222

17/12/2017



See JSON code example. Properties Name

Type

Description

id

int

ID of the submission

ipAddress

array

Associative array containing IP address of the client who made the submission

form

array

Simplified associative array of the form containing id, name, alias and category

lead

array

Associative array of the lead containing the core values as well as custom fields

dateSubmitted

string

Date time string holding the UTC date and time when the submission was made

referer

string

HTTP referer info

results

array

Associative array of the form fields as the keys and submission values

LIST FORM SUBMISSIONS FOR A CONTACT

getSubmissionsForContact($formId, $contactId, $searchFilter, $start, $limit, $orderBy, $orderByDir, $publishedOnly, $minimal);

HTTP REQUEST

GET /forms/FORM_ID/submissions/contact/CONTACT_ID

Response and properties same as Get Form Submissions. Parameters too except the ContactId was added. GET FORM SUBMISSION

getSubmission($formId, $submissionId);

Get an individual form submission by ID. HTTP REQUEST

GET /forms/FORM_ID/submissions/SUBMISSION_ID RESPONSE


See JSON code example. Form Properties

Same as Get Form Submissions.

Marketing Messages https://developer.mautic.org/#plugin-directory-structure

157/222

17/12/2017


Use this endpoint to obtain details, create, update or delete Mautic’s messages.


$apiUrl


$api

= new MauticApi();

$messageApi = $api->newApi("messages", $auth, $apiUrl);

GET MARKETING MESSAGE

get($id);

Get an individual marketing message by ID. HTTP REQUEST

GET /messages/ID RESPONSE


See JSON code example. Marketing Message Properties Name

Type

Description

id

int

ID of the message

name

string

Internal name of the message

isPublished

bool

Published state

publishUp

datetime/null

Date/time when the message should be published

publishDown

datetime/null

Date/time the message should be un published

dateAdded

datetime

Date/time message was created

createdBy

int

ID of the user that created the message

createdByUser

string

Name of the user that created the message

dateModified

datetime/null

Date/time message was last modified

modifiedBy

int

ID of the user that last modified the message

modifiedByUser

string

Name of the user that last modified the message

channels

array

Array of channels configured for the marketing message

LIST MARKETING MESSAGES


158/222

17/12/2017



HTTP REQUEST

GET /messages


Description

search


start


limit


orderBy


orderByDir


publishedOnly


minimal


RESPONSE


See JSON code example. Properties Same as Get Marketing Message. CREATE MARKETING MESSAGE

=> 'Marketing Message A',

'description' => 'This is my first message created via API.', 'isPublished' => 1, 'channels' => array( 'email' => array( 'channel' => 'email', 'channelId' => 44, 'isEnabled' => true, ), 'sms' => array( 'channel' => 'sms', 'channelId' => 1, 'isEnabled' => true, ), 'notification' => array( 'channel' => 'notification', 'channelId' => 75, 'isEnabled' => false, ) ) );


159/222

17/12/2017


$message = $messageApi->create($data);

Create a new message. HTTP REQUEST

POST /messages/new


Type

Description

id

int

ID of the message

name

string


isPublished

bool

Published state

publishUp

datetime/null


publishDown

datetime/null


channels

array

Array of channels

RESPONSE


Properties Same as Get Marketing Message. EDIT MARKETING MESSAGE

= 1;


=> 'New message title',

'isPublished' => 0 ); // Create new a message of ID 1 is not found? $createIfNotFound = true; $message = $messageApi->edit($id, $data, $createIfNotFound);

Edit a new message. Note that this supports PUT or PATCH depending on the desired behavior. PUT creates a message if the given ID does not exist and clears all the message information, adds the information from the request. PATCH fails if the message with the given ID does not exist and updates the message field values with the values form the request. HTTP REQUEST

To edit a message and return a 404 if the message is not found: PATCH /messages/ID/edit

To edit a message and create a new one if the message is not found: PUT /messages/ID/edit


160/222

17/12/2017



Type

Description

id

int

ID of the message

name

string


isPublished

bool

Published state

publishUp

datetime/null


publishDown

datetime/null


channels

array

Array of channels

RESPONSE

If PUT , the expected response code is 200 if the message was edited or 201 if created. If PATCH , the expected response code is 200 . Properties

Same as Get Marketing Message. DELETE MARKETING MESSAGE

delete($id);

Delete a message. HTTP REQUEST

DELETE /messages/ID/delete RESPONSE


Properties

Same as Get Marketing Message.

Notes Use this endpoint to obtain details on Mautic’s contact notes.


$apiUrl



161/222

17/12/2017


$api

= new MauticApi();

$noteApi

= $api->newApi("notes", $auth, $apiUrl);

GET NOTE

get($id);

Get an individual note by ID. HTTP REQUEST

GET /notes/ID RESPONSE


See JSON code example. Note Properties Name

Type

Description

id

int

ID of the note

lead

array

data of the contact

text

string

Note text

type

string

Note type

datetime

datetime

Date and time related to the note.

LIST CONTACT NOTES


HTTP REQUEST

GET /notes RESPONSE


See JSON code example. Note Properties Name

Type

Description

id

int

ID of the note

lead

array

data of the contact

text

string

Note text


162/222

17/12/2017


Name

Type

Description

type

string

Note type

datetime

datetime

Date and time related to the note.

CREATE NOTE

'Note A', 'type' => 'general', ); $note = $noteApi->create($data);

Create a new note. HTTP REQUEST

POST /notes/new


Description

text

string

type

string

datetime

datetime

RESPONSE


Properties Same as Get Note. EDIT NOTE

= 1;

$data = array( 'text' => 'Note B', 'type' => 'general', ); // Create new a note of ID 1 is not found? $createIfNotFound = true; $note = $noteApi->edit($id, $data, $createIfNotFound);

Edit a new note. Note that this supports PUT or PATCH depending on the desired behavior. PUT creates a note if the given ID does not exist and clears all the note information, adds the information from the request. PATCH fails if the note with the given ID does not exist and updates the note field values with the values form the request. HTTP REQUEST


163/222

17/12/2017


To edit a note and return a 404 if the note is not found: PATCH /notes/ID/edit

To edit a note and create a new one if the note is not found: PUT /notes/ID/edit


Description

text

string

type

string

datetime

datetime

RESPONSE

If PUT , the expected response code is 200 if the note was edited or 201 if created. If PATCH , the expected response code is 200 . Properties

Same as Get Note. DELETE NOTE

delete($id);

Delete a note. HTTP REQUEST

DELETE /notes/ID/delete RESPONSE


Properties

Same as Get Note.

Notifications Use this endpoint to obtain details on Mautic’s notifications.

= new ApiAuth();

$auth



164/222

17/12/2017


$apiUrl


$api

= new MauticApi();

$notificationApi = $api->newApi("notifications", $auth, $apiUrl);

GET NOTIFICATION

get($id);

Get an individual notification by ID. HTTP REQUEST

GET /notifications/ID RESPONSE


See JSON code example. Notification Properties Name

Type

Description

id

int

ID of the notification

name

string

Title of the notification

heading

string

Heading of the notification

message

string

Message of the notification

url

string

URL to go to when the notification is clicked

isPublished

bool

Published state

publishUp

datetime/null

Date/time when the notification should be published

publishDown

datetime/null

Date/time the notification should be un published

dateAdded

datetime

Date/time notification was created

createdBy

int

ID of the user that created the notification

createdByUser

string

Name of the user that created the notification

dateModified

datetime/null

Date/time notification was last modified

modifiedBy

int

ID of the user that last modified the notification

modifiedByUser

string

Name of the user that last modified the notification

language

string

Language locale of the notification

readCount

int

Total notification read count

sentCount

int

Unique notification sent count

category

null/object

Category


165/222

17/12/2017


LIST NOTIFICATIONS


HTTP REQUEST

GET /notifications


Description

search


start


limit


orderBy


orderByDir


publishedOnly


minimal


RESPONSE


See JSON code example. Properties Same as Get Notification. CREATE NOTIFICATION

=> 'Notification A',

'heading' => 'Hello World!' 'message' => 'This is my first notification created via API.', ); $notification = $notificationApi->create($data);

Create a new notification. HTTP REQUEST

POST /notifications/new

Post Parameters Name id

Type int

Description ID of the notification


166/222

17/12/2017


Name

Type

Description

name

string


heading

string


message

string


url

string


isPublished

bool

Published state

publishUp

datetime/null


publishDown

datetime/null


language

string


RESPONSE


Properties Same as Get Notification. EDIT NOTIFICATION

= 1;


=> 'Notification A',

'heading' => 'Hello World!' 'message' => 'This is my first notification created via API.', ); // Create new a notification of ID 1 is not found? $createIfNotFound = true; $notification = $notificationApi->edit($id, $data, $createIfNotFound);

Edit a new notification. Note that this supports PUT or PATCH depending on the desired behavior. PUT creates a notification if the given ID does not exist and clears all the notification information, adds the information from the request. PATCH fails if the notification with the given ID does not exist and updates the notification field values with the values form the request. HTTP REQUEST

To edit a notification and return a 404 if the notification is not found: PATCH /notifications/ID/edit

To edit a notification and create a new one if the notification is not found: PUT /notifications/ID/edit


Type int

Description ID of the notification


167/222

17/12/2017


Name

Type

Description

name

string


heading

string


message

string


url

string


isPublished

bool

Published state

publishUp

datetime/null


publishDown

datetime/null


language

string


RESPONSE

If PUT , the expected response code is 200 if the notification was edited or 201 if created. If PATCH , the expected response code is 200 . Properties

Same as Get Notification. DELETE NOTIFICATION

delete($id);

Delete a notification. HTTP REQUEST

DELETE /notifications/ID/delete RESPONSE


Properties

Same as Get Notification.

Pages Use this endpoint to obtain details on Mautic’s landing pages.



168/222

17/12/2017 $apiUrl

Mautic Developer Documentation = "https://your-mautic.com";

$api

= new MauticApi();

$pageApi

= $api->newApi("pages", $auth, $apiUrl);

GET PAGE

get($id);

Get an individual page by ID. HTTP REQUEST

GET /pages/ID RESPONSE


See JSON code example. Page Properties Name

Type

Description

id

int

ID of the page

title

string

Title of the page

description

string/null

Description of the page

alias

string

Used to generate the URL for the page

isPublished

bool

Published state

publishUp

datetime/null

Date/time when the page should be published

publishDown

datetime/null

Date/time the page should be un published

dateAdded

datetime

Date/time page was created

createdBy

int

ID of the user that created the page

createdByUser

string

Name of the user that created the page

dateModified

datetime/null

Date/time page was last modified

modifiedBy

int

ID of the user that last modified the page

modifiedByUser

string

Name of the user that last modified the page

language

string

Language locale of the page

hits

int

Total page hit count

uniqueHits

int

Unique page hit count

revision

int

Page revision

metaDescription

Meta description for the page’s


169/222

17/12/2017


Name

Type

Description

redirectType

int

If unpublished, redirect with 301 or 302

redirectUrl

string

If unpublished, the URL to redirect to if redirectType is set

translationChildren

array

Array of Page entities for translations of this landing page

translationParent

object


variantHits

Hit count since variantStartDate

variantChildren

array

Array of Page entities for variants of this landing page

variantParent

object

The parent/main page if this is a variant (A/B test)

variantSettings

array


variantStartDate

datetime/null

The date/time the A/B test began

LIST PAGES


HTTP REQUEST

GET /pages


Description

search


start


limit


orderBy


orderByDir


publishedOnly


minimal


RESPONSE


See JSON code example. Properties Same as Get Page. CREATE PAGE


170/222

17/12/2017


=> 'Page A',

'description' => 'This is my first page created via API.', 'isPublished' => 1 ); $page = $pageApi->create($data);

Create a new page. HTTP REQUEST

POST /pages/new


Description

title

Page title is the only required field

alias

string

description

A description of the page.

isPublished

A value of 0 or 1

language

string

metaDescription


redirectType

int

redirectUrl

string

RESPONSE


Properties Same as Get Page. EDIT PAGE

= 1;

$data = array( 'title'

=> 'New page title',

'isPublished' => 0 ); // Create new a page of ID 1 is not found? $createIfNotFound = true; $page = $pageApi->edit($id, $data, $createIfNotFound);

Edit a new page. Note that this supports PUT or PATCH depending on the desired behavior. PUT creates a page if the given ID does not exist and clears all the page information, adds the information from the request. PATCH fails if the page with the given ID does not exist and updates the page field values with the values form the request. https://developer.mautic.org/#plugin-directory-structure

171/222

17/12/2017


HTTP REQUEST

To edit a page and return a 404 if the page is not found: PATCH /pages/ID/edit

To edit a page and create a new one if the page is not found: PUT /pages/ID/edit


Description

title

Page title is the only required field

alias


description

A description of the page.

isPublished

A value of 0 or 1

language

string

metaDescription


redirectType

int

redirectUrl

string

RESPONSE

If PUT , the expected response code is 200 if the page was edited or 201 if created. If PATCH , the expected response code is 200 . Properties

Same as Get Page. DELETE PAGE

delete($id);

Delete a page. HTTP REQUEST

DELETE /pages/ID/delete RESPONSE


Properties

Same as Get Page.


172/222

17/12/2017


Point Actions Use this endpoint to obtain details on Mautic’s point actions.


$apiUrl


$api

= new MauticApi();

$pointApi = $api->newApi("points", $auth, $apiUrl);

GET POINT ACTION

get($id);

Get an individual point action by ID. HTTP REQUEST

GET /points/ID RESPONSE


See JSON code example. Point Action Properties Name

Type

Description

id

int

ID of the point

name

string

Name of the point

description

string/null

Description of the point

category

string

Category name

type

string

Point action type

isPublished

bool

Published state

publishUp

datetime/null

Date/time when the point should be published

publishDown

datetime/null

Date/time the point should be un published

dateAdded

datetime

Date/time point was created

createdBy

int

ID of the user that created the point

createdByUser

string

Name of the user that created the point


173/222

17/12/2017


Name

Type

Description

dateModified

datetime/null

Date/time point was last modified

modifiedBy

int

ID of the user that last modified the point

modifiedByUser

string

Name of the user that last modified the point

delta

int

The number of points to give the lead when executing this action

properties

array

Configured properties for this point action

LIST POINT ACTIONS


HTTP REQUEST

GET /points


Description

search


start


limit


orderBy


orderByDir


publishedOnly


minimal


RESPONSE


See JSON code example. Properties Same as Get Point Action. CREATE POINT ACTION

'test', 'delta' => 5, 'type' => 'page.hit', 'description' => 'created as a API test' );


174/222

17/12/2017


$point = $pointApi->create($data);

Create a new point action. HTTP REQUEST

POST /points/new

Post Parameters Same as Get Point Action. Point Action fields and actions can be created/edited via the point actions/actions arrays in the point action array. RESPONSE


Properties Same as Get Point Action. EDIT POINT ACTION

= 1;

$data = array( 'name' => 'test', 'delta' => 5, 'type' => 'page.hit', 'description' => 'created as a API test' ); // Create new a point action of ID 1 is not found? $createIfNotFound = true; $point = $pointApi->edit($id, $data, $createIfNotFound);

Edit a new point action. Note that this supports PUT or PATCH depending on the desired behavior. PUT creates a point action if the given ID does not exist and clears all the point action inpoint actionation, adds the inpoint actionation from the request. Point Action fields and actions will be also deleted if not present in the r equest. PATCH fails if the point action with the given ID does not exist and updates the point action field values with the values point action the request. HTTP REQUEST

To edit a point action and return a 404 if the point action is not found: PATCH /points/ID/edit

To edit a point action and c reate a new one if the point action is not found: PUT /points/ID/edit

Post Parameters Same as Get Point Action. Point Action fields and actions can be created/edited via the point actions/actions arrays in the point action array. RESPONSE

If PUT , the expected response code is 200 if the point action was edited or 201 if created. If PATCH , the expected response code is 200 . Properties https://developer.mautic.org/#plugin-directory-structure

175/222

17/12/2017


Same as Get Point Action. DELETE POINT ACTION

delete($id);

Delete a point action. HTTP REQUEST

DELETE /points/ID/delete RESPONSE


Properties

Same as Get Point Action. GET POINT ACTION TYPES

getPointActionTypes();

Get array of available Point Action Types HTTP REQUEST

GET /points/actions/types RESPONSE



Point Triggers Use this endpoint to obtain details on Mautic’s point triggers.

= new ApiAuth();

$auth


$apiUrl


$api

= new MauticApi();

$triggerApi = $api->newApi("pointTriggers", $auth, $apiUrl);

GET POINT TRIGGER


176/222

17/12/2017


//... $trigger = $triggerApi->get($id);

Get an individual point trigger by ID. HTTP REQUEST

GET /points/triggers/ID RESPONSE


See JSON code example. Point Trigger Properties Name

Type

Description

id

int

ID of the point

name

string

Name of the point

description

string/null

Description of the point

category

string

Category name

isPublished

bool

Published state

publishUp

datetime/null

Date/time when the point should be published

publishDown

datetime/null

Date/time the point should be un published

dateAdded

datetime

Date/time point was created

createdBy

int

ID of the user that created the point

createdByUser

string

Name of the user that created the point

dateModified

datetime/null

Date/time point was last modified

modifiedBy

int

ID of the user that last modified the point

modifiedByUser

string

Name of the user that last modified the point

points

int

The minimum number of points before the trigger events are executed

color

string

Color hex to highlight the lead with. This value does NOT include the pound sign (#)

events

array

Array of TriggerEvent entities for this trigger. See below.

Trigger Event Properties Name

Type

Description

id

int

ID of the event

type

string

Event type

name

string

Name of the event

description

string

Description of the event


177/222

17/12/2017


Name

Type

Description

order

int

Event order

properties

array

Configured properties for the event

LIST POINT TRIGGERS


HTTP REQUEST

GET /points/triggers


Description

search


start


limit


orderBy


orderByDir


publishedOnly


minimal


RESPONSE


See JSON code example. Properties Same as Get Point Trigger. CREATE POINT TRIGGER

'test', 'description' => 'created as a API test', 'points' => 5, 'color' => '4e5d9d', 'trigger_existing_leads' => false, 'events' => array( array( 'name' => 'tag test event', 'description' => 'created as a API test', 'type' => 'lead.changetags', 'order' => 1, 'properties' => array( 'add_tags' => array('tag-a'),


178/222

17/12/2017

Mautic Developer Documentation 'remove_tags' => array() ) ), array( 'name' => 'send email test event', 'description' => 'created as a API test', 'type' => 'email.send', 'order' => 2, 'properties' => array( 'email' => 1 ) )

) ); $trigger = $triggerApi->create($data);

Create a new point trigger. HTTP REQUEST

POST /points/triggers/new

Post Parameters

Same as Get Point Trigger. Point Trigger events can be created/edited via the point trigger event arrays placed in the point trigger array. RESPONSE


Properties

Same as Get Point Trigger. EDIT POINT TRIGGER

= 1;

$data = array( 'name' => 'test', 'description' => 'created as a API test', 'points' => 5, 'color' => '4e5d9d', 'trigger_existing_leads' => false, 'events' => array( array( 'name' => 'tag test event', 'description' => 'created as a API test', 'type' => 'lead.changetags', 'order' => 1, 'properties' => array( 'add_tags' => array('tag-a'), 'remove_tags' => array() ) ), array( 'name' => 'send email test event', 'description' => 'created as a API test', 'type' => 'email.send', 'order' => 2, 'properties' => array( 'email' => 1 ) ) ) );


179/222

17/12/2017


// Create new a point trigger of ID 1 is not found? $createIfNotFound = true; $trigger = $triggerApi->edit($id, $data, $createIfNotFound);

Edit a new point trigger. Note that this supports PUT or PATCH depending on the desired behavior. PUT creates a point trigger if the given ID does not exist and clears all the point trigger information, adds the information from the request. Point Trigger events will be also deleted if not present in the request. PATCH fails if the point trigger with the given ID does not exist and updates the point trigger field values with the values point trigger the request. HTTP REQUEST

To edit a point trigger and r eturn a 404 if the point trigger is not found: PATCH /points/triggers/ID/edit

To edit a point trigger and c reate a new one if the point trigger is not found: PUT /points/triggers/ID/edit

Post Parameters Same as Get Point Trigger. Point Trigger events can be created/edited via the point triggers event arrays placed in the point trigger array. RESPONSE

If PUT , the expected response code is 200 if the point trigger was edited or 201 if created. If PATCH , the expected response code is 200 . Properties Same as Get Point Trigger. DELETE POINT TRIGGER

delete($id);

Delete a point trigger. HTTP REQUEST

DELETE /points/triggers/ID/delete RESPONSE


Properties Same as Get Point Trigger. DELETE POINT TRIGGER EVENTS

The following examples will show how to delete ev ents with ID 56 and 59.

deleteFields($triggerId, array(56, 59));


180/222

17/12/2017


Delete a point trigger events. HTTP REQUEST

DELETE /points/triggers/ID/events/delete?events[]=56&events[]=59 RESPONSE


Properties

Same as Get Point Trigger. GET POINT TRIGGER EVENT TYPES

getEventTypes();

Get array of available Point Trigger Event Types HTTP REQUEST

GET /points/triggers/events/types RESPONSE


Roles Use this endpoint to obtain details on Mautic’s roles (administrators).


$apiUrl


$api

= new MauticApi();

$roleApi

= $api->newApi("roles", $auth, $apiUrl);

GET ROLE

get($id);

Get an individual role by ID. HTTP REQUEST

GET /roles/ID RESPONSE


181/222

17/12/2017



See JSON code example. Role Properties Name

Type

Description

id

int

ID of the contact

dateAdded

datetime


createdBy

int

ID of the role that created the contact

createdByRole

string

Name of the role that created the contact

dateModified

datetime/null


modifiedBy

int

ID of the role that last modified the contact

modifiedByRole

string

Name of the role that last modified the contact

name

string

Name of the role

description

string

Description of the role

isAdmin

boolean

Whether the role has full access or only some

rawPermissions

array

List of roles

LIST CONTACT ROLES


HTTP REQUEST

GET /roles RESPONSE


See JSON code example. Role Properties Name

Type

Description

id

int

ID of the contact

dateAdded

datetime


createdBy

int

ID of the role that created the contact

createdByRole

string

Name of the role that created the contact

dateModified

datetime/null


modifiedBy

int

ID of the role that last modified the contact


182/222

17/12/2017


Name

Type

Description

modifiedByRole

string

Name of the role that last modified the contact

name

string

Name of the role

description

string

Description of the role

isAdmin

boolean

Whether the role has full access or only some

rawPermissions

array

List of roles

CREATE ROLE

'API test role', 'description' => 'created via AIP', 'rawPermissions' => array ( 'email:emails' => array ( 'viewown', 'viewother', ), ) ); $role = $roleApi->create($data);

Create a new role. HTTP REQUEST

POST /roles/new


Description

name

string

description

string

isAdmin

boolean

rawPermissions

array

RESPONSE


Properties

Same as Get Role. EDIT ROLE

= 1;

$data = array( 'name' => 'API test role',


183/222

17/12/2017


'description' => 'created via AIP', 'rawPermissions' => array ( 'email:emails' => array ( 'editown', 'editother', ), ) ); // Create new a role of ID 1 is not found? $createIfNotFound = true; $role = $roleApi->edit($id, $data, $createIfNotFound);

Edit a new role. Role that this supports PUT or PATCH depending on the desired behavior. PUT creates a role if the given ID does not exist and clears all the role information, adds the information from the request. PATCH fails if the role with the given ID does not exist and updates the role field values with the values form the request. HTTP REQUEST

To edit a role and return a 404 if the role is not found: PATCH /roles/ID/edit

To edit a role and create a new one if the role is not found: PUT /roles/ID/edit


Description

name

string

description

string

isAdmin

boolean

rawPermissions

array

RESPONSE

If

PUT ,

the expected response code is

If

PATCH ,

200 if


the role was edited or

201 if

created.

200 .

Properties Same as Get Role. DELETE ROLE

delete($id);

Delete a role. HTTP REQUEST

DELETE /roles/ID/delete


184/222

17/12/2017


RESPONSE


Properties Same as Get Role.

Segments Use this endpoint to obtain details on Mautic’s contact segments or to manipulate contact memberships.

= new ApiAuth();

$auth


$apiUrl


$api

= new MauticApi();

$segmentApi = $api->newApi("segments", $auth, $apiUrl);

GET SEGMENT

get($id);

Get an individual segment by ID. HTTP REQUEST

GET /segments/ID RESPONSE


See JSON code example. Segment Properties Name

Type

Description

id

int

ID of the segment

isPublished

boolean

Whether the segment is published

dateAdded

datetime

Date/time segment was created

createdBy

int

ID of the user that created the segment

createdByUser

string

Name of the user that created the segment

dateModified

datetime/null

Date/time segment was last modified

modifiedBy

int

ID of the user that last modified the segment


185/222

17/12/2017


Name

Type

Description

modifiedByUser

string

Name of the user that last modified the segment

name

string

Segment name

alias

string

Segment alias

description

string

Segment description

filters

array

Smart filters for the segment. See filter properties bellow

isGlobal

boolean

Whether the segment is global. 0 means only the author will see it.

Segment Filter Properties Name

Type

Description

glue

string

How to glue the filters to others. Possible values: and , or

field

string

Alias of the contact or company field to based the filter on

object

string

Object which have the field. Possible values: ‘lead’ (for contacts), company

type

string

Type of the field. Possible values: 'boolean’, date (format Y-m-d ), datetime (format Y-m-d H:i:s ), email , coun‐ try , locale , lookup , number , tel , region , select , multiselect , text , textarea , time , timezone , url

operator

string

Operator used for matching the values. Possible values: ’=’, != , empty , !empty , like , !like , regexp , !regexp , startsWith , endsWith , contains

LIST CONTACT SEGMENTS


Returns a list of contact segments available to the user. This list is not filterable. HTTP REQUEST

GET /segments RESPONSE


See JSON code example. Segment Properties Name

Type

Description

total

int

Count of all segments

id

int

ID of the segment

isPublished

boolean

Whether the segment is published

dateAdded

datetime

Date/time segment was created


186/222

17/12/2017


Name

Type

Description

createdBy

int

ID of the user that created the segment

createdByUser

string

Name of the user that created the segment

dateModified

datetime/null

Date/time segment was last modified

modifiedBy

int

ID of the user that last modified the segment

modifiedByUser

string

Name of the user that last modified the segment

name

string

Segment name

alias

string

Segment alias

description

string

Segment description

filters

array

Smart filters for the segment. See filter properties bellow

isGlobal

boolean

Whether the segment is global. 0 means only the author will see it.


Type

Description

glue

string


field

string


object

string

Object which have the field. Possible values: 'lead’ (for contacts), company

type

string


operator

string


CREATE SEGMENT

=> 'Segment A',

'alias'

=> 'segment-a',

'description' => 'This is my first segment created via API.', 'isPublished' => 1, 'filters' => array( array( 'glue' => 'and', 'field' => 'email', 'object' => 'lead', 'type' => 'email', 'filter' => '*@gmail.com', 'operator' => 'like', ), ), ); $segment = $segmentApi->create($data);

Create a new segment. https://developer.mautic.org/#plugin-directory-structure

187/222

17/12/2017


HTTP REQUEST

POST /segments/new


Description

name

Segment name is the only required field

alias


description

A description of the segment.

isPublished

A value of 0 or 1

isGlobal

boolean

filters

array


Type

Description

glue

string


field

string


object

string


type

string


operator

string


RESPONSE


Properties Same as Get Segment. EDIT SEGMENT

= 1;


=> 'New segment name',

'isPublished' => 0 ); // Create new a segment of ID 1 is not found? $createIfNotFound = true; $segment = $segmentApi->edit($id, $data, $createIfNotFound);

Edit a new segment. Note that this supports PUT or PATCH depending on the desired behavior.


188/222

17/12/2017


PUT creates a segment if the given ID does not exist and clears all the segment information, adds the information from the request. PATCH fails if the segment with the given ID does not exist and updates the segment field values with the values form the request. HTTP REQUEST

To edit a segment and return a 404 if the segment is not found: PATCH /segments/ID/edit

To edit a segment and create a new one if the segment is not found: PUT /segments/ID/edit


Description

name

Segment name is the only required field

alias


description

A description of the segment.

isPublished

A value of 0 or 1

isGlobal

boolean

filters

array


Type

Description

glue

string


field

string


object

string


type

string


operator

string


RESPONSE

If PUT , the expected response code is 200 if the segment was edited or 201 if created. If PATCH , the expected response code is 200 . Properties Same as Get Segment. DELETE SEGMENT

delete($id);

Delete a segment. https://developer.mautic.org/#plugin-directory-structure

189/222

17/12/2017


HTTP REQUEST

DELETE /segments/ID/delete RESPONSE


Properties

Same as Get Segment. ADD CONTACT TO A SEGMENT

addContact($segmentId, $contactId); if (!isset($response['success'])) { // handle error }

Manually add a contact to a specific segment. HTTP REQUEST

POST /segments/SEGMENT_ID/contact/CONTACT_ID/add RESPONSE


See JSON code example. REMOVE CONTACT FROM A SEGMENT

removeContact($segmentId, $contactId); if (!isset($response['success'])) { // handle error }

Manually remove a contact to a specific segment. HTTP REQUEST

POST /segments/SEGMENT_ID/contact/CONTACT_ID/remove RESPONSE



Text messages Use this endpoint to obtain details on Mautic’s Text Messages (SMSes).


190/222

17/12/2017



$apiUrl


$api

= new MauticApi();

$smsApi

= $api->newApi("smses", $auth, $apiUrl);

GET TEXT MESSAGE

get($id);

Get an individual sms by ID. HTTP REQUEST

GET /smses/ID RESPONSE


See JSON code example. Text message Properties Name

Type

Description

id

int

ID of the sms

name

string

Title of the sms

message

string

Message of the sms

isPublished

bool

Published state

publishUp

datetime/null

Date/time when the sms should be published

publishDown

datetime/null

Date/time the sms should be un published

dateAdded

datetime

Date/time sms was created

createdBy

int

ID of the user that created the sms

createdByUser

string

Name of the user that created the sms

dateModified

datetime/null

Date/time sms was last modified

modifiedBy

int

ID of the user that last modified the sms

modifiedByUser

string

Name of the user that last modified the sms

language

string

Language locale of the sms

sentCount

int

How many times the SMS was sent


191/222

17/12/2017


LIST TEXT MESSAGES


HTTP REQUEST

GET /smses


Description

search


start


limit


orderBy


orderByDir


publishedOnly


minimal


RESPONSE


See JSON code example. Properties Same as Get Text message. CREATE TEXT MESSAGE

=> 'Text message A',

'message' => 'This is my first sms created via API.', 'isPublished' => 1 ); $sms = $smsApi->create($data);

Create a new sms. HTTP REQUEST

POST /smses/new


Type int

Description ID of the sms


192/222

17/12/2017


Name

Type

Description

name

string

Title of the sms

message

string

Message of the sms

isPublished

bool

Published state

publishUp

datetime/null


publishDown

datetime/null


dateAdded

datetime

Date/time sms was created

createdBy

int

ID of the user that created the sms

createdByUser

string

Name of the user that created the sms

dateModified

datetime/null

Date/time sms was last modified

modifiedBy

int

ID of the user that last modified the sms

modifiedByUser

string

Name of the user that last modified the sms

language

string


sentCount

int

How many times the SMS was sent

RESPONSE


Properties Same as Get Text message. EDIT TEXT MESSAGE

= 1;


=> 'New sms name',

'isPublished' => 0 ); // Create new a sms of ID 1 is not found? $createIfNotFound = true; $sms = $smsApi->edit($id, $data, $createIfNotFound);

Edit a new sms. Note that this supports PUT or PATCH depending on the desired behavior. PUT creates a sms if the given ID does not exist and clears all the sms information, adds the information from the request. PATCH fails if the sms with the given ID does not exist and updates the sms field values with the values form the request. HTTP REQUEST

To edit a sms and return a 404 if the sms is not found: PATCH /smses/ID/edit

To edit a sms and create a new one if the sms is not found: https://developer.mautic.org/#plugin-directory-structure

193/222

17/12/2017


PUT /smses/ID/edit


Type

Description

id

int

ID of the sms

name

string

Title of the sms

message

string

Message of the sms

isPublished

bool

Published state

publishUp

datetime/null


publishDown

datetime/null


language

string


RESPONSE

If PUT , the expected response code is 200 if the sms was edited or 201 if created. If PATCH , the expected response code is 200 . Properties

Same as Get Text message. DELETE TEXT MESSAGE

delete($id);

Delete a sms. HTTP REQUEST

DELETE /smses/ID/delete RESPONSE


Properties

Same as Get Text message.

Stages Use this endpoint to obtain details on Mautic’s contact stages.


194/222

17/12/2017


$initAuth = new ApiAuth(); $auth


$apiUrl


$api

= new MauticApi();

$stageApi = $api->newApi("stages", $auth, $apiUrl);

GET STAGE

get($id);

Get an individual stage by ID. HTTP REQUEST

GET /stages/ID RESPONSE


See JSON code example. Stage Properties Name

Type

Description

id

int

ID of the stage

isPublished

boolean

Whether the stage is published

dateAdded

datetime

Date/time stage was created

createdBy

int

ID of the user that created the stage

createdByUser

string

Name of the user that created the stage

dateModified

datetime/null

Date/time stage was last modified

modifiedBy

int

ID of the user that last modified the stage

modifiedByUser

string

Name of the user that last modified the stage

name

string

Stage name

category

int

Stage category ID

description

string

Stage description

weight

int

Stage’s weight

publishUp

datetime

Date/time stage should be published

publishDown

datetime

Date/time stage should be unpublished

LIST CONTACT STAGES



195/222

17/12/2017


HTTP REQUEST

GET /stages RESPONSE


See JSON code example. Stage Properties Name

Type

Description

total

int

Count of all stages

id

int

ID of the stage

isPublished

boolean

Whether the stage is published

dateAdded

datetime

Date/time stage was created

createdBy

int

ID of the user that created the stage

createdByUser

string

Name of the user that created the stage

dateModified

datetime/null

Date/time stage was last modified

modifiedBy

int

ID of the user that last modified the stage

modifiedByUser

string

Name of the user that last modified the stage

name

string

Stage name

category

int

Stage category ID

description

string

Stage description

weight

int

Stage’s weight

publishUp

datetime

Date/time stage should be published

publishDown

datetime

Date/time stage should be unpublished

CREATE STAGE

=> 'Stage A',

'weight'

=> 5,

'description' => 'This is my first stage created via API.', 'isPublished' => 1 ); $stage = $stageApi->create($data);

Create a new stage. HTTP REQUEST

POST /stages/new


196/222

17/12/2017



Description

name

Stage name is the only required field

weight

int

description

A description of the stage.

isPublished

A value of 0 or 1

RESPONSE


Properties Same as Get Stage. EDIT STAGE

= 1;


=> 'New stage name',

'isPublished' => 0 ); // Create new a stage of ID 1 is not found? $createIfNotFound = true; $stage = $stageApi->edit($id, $data, $createIfNotFound);

Edit a new stage. Note that this supports PUT or PATCH depending on the desired behavior. PUT creates a stage if the given ID does not exist and clears all the stage information, adds the information from the request. PATCH fails if the stage with the given ID does not exist and updates the stage field values with the values form the request. HTTP REQUEST

To edit a stage and return a 404 if the stage is not found: PATCH /stages/ID/edit

To edit a stage and create a new one if the stage is not found: PUT /stages/ID/edit


Description

name

Stage name is the only required field

alias


description

A description of the stage.

isPublished

A value of 0 or 1

weight

int


197/222

17/12/2017


RESPONSE

If PUT , the expected response code is 200 if the stage was edited or 201 if created. If PATCH , the expected response code is 200 . Properties

Same as Get Stage. DELETE STAGE

delete($id);

Delete a stage. HTTP REQUEST

DELETE /stages/ID/delete RESPONSE


Properties

Same as Get Stage. ADD CONTACT TO A STAGE

addContact($contactId, $stageId); if (!isset($response['success'])) { // handle error }

Manually add a contact to a specific stage. HTTP REQUEST

POST /stages/STAGE_ID/contact/CONTACT_ID/add RESPONSE


See JSON code example. REMOVE CONTACT FROM A STAGE

removeContact($contactId, $stageId); if (!isset($response['success'])) { // handle error }

Manually remove a contact from a specific stage. HTTP REQUEST


198/222

17/12/2017


POST /stages/STAGE_ID/contact/CONTACT_ID/remove RESPONSE



Stats This endpoint is useful for downloading a full statistical table.


$apiUrl


$api

= new MauticApi();

$statsApi = $api->newApi("stats", $auth, $apiUrl);

GET AVAILABLE STAT TABLES

get();

HTTP REQUEST

GET /stats RESPONSE


See JSON code example. Stats Properties Name

Type

Description

availableTables

array

List of available tables which can be used in this endpoint

stats

array

An empty array of stats, because no table was defined

GET STATS FROM A TABLE

'id', 'dir' => 'asc'


199/222

17/12/2017


) ); $where = array( array( 'col' => 'id', 'expr' => 'gt', 'val' => 3, ) ); $stats = $statsApi->get($table, $start, $limit, $order, $where);

HTTP REQUEST

GET /stats/TABLE

Request Properties Name

Type

Description

start

int

Which row to start on

limit

int

How many rows to return

order

array

An array of arrays which contain ordering (example above)

where

array

An array of arrays which contain where conditions (example above). As the expr param can be used most of the methods from DBAL Doctrine where methods.

If using cURL, a query parameter may look something like where%5B0%5D%5Bcol%5D=id&where%5B0%5D%5Bexpr%5D=eq&where%5B0%5D%5Bval%5D=3 which is the equivalent to the following:

array( array( 'col' => 'id', 'expr' => 'eq', 'val' => 3, ) );

RESPONSE


See JSON code example. Stats Properties Different for every table. It simply returns rows or requested table.

Themes This endpoint is useful for working with Mautic themes.


200/222

17/12/2017


$initAuth = new ApiAuth(); $auth


$apiUrl


$api

= new MauticApi();

$themesApi = $api->newApi("themes", $auth, $apiUrl);

GET THEME

Returns directly the zip file in the response with the application/zip header on success or a JSON response body with error messages on fail. The PHP API library will save the zip fi le to the system temporary directory and provides you with the path.

get($themeName);

HTTP REQUEST

GET /themes/THEME_NAME RESPONSE

Expected Response Code: 200 SET TEMPORARY FILE PATH

Changes the default temporary directory where the zip file is created. The directory is created if it does not exist.

setTemporaryFilePath("/absolute/path/to/a/different/temp/dir"); $response = $themesApi->get($themeName);

GET LIST OF THEMES

Lists all installed themes with the detailes stored in their config.json files.

getList();

HTTP REQUEST

GET /themes RESPONSE


See JSON code example. Response Properties Name

Type

Description

themes

array

List of installed themes and their configs

CREATE THEME

Creates a new theme or updates an existing one (based on the file name) from provided zip file.

dirname(__DIR__).'/'.'mytheme.zip' // Must be a path to an existing file );


201/222

17/12/2017


$response = $themeApi->create($data);

The file is sent via regular POST files array like a browser sends it during file upload. HTTP REQUEST

POST /themes/new RESPONSE

Expected Response Code: 200 json { "success": true } DELETE FILE

delete($themeName);

Delete a theme. The stock themes cannot be deleted HTTP REQUEST

DELETE /themes/THEME_NAME/delete RESPONSE

Expected Response Code: 200 json { "success": true }

Tweets Use this endpoint to obtain details on Mautic’s tweets. Implemented in Mautic 2.8.0.

= new ApiAuth();

$auth


$apiUrl


$api

= new MauticApi();

$tweetApi = $api->newApi("tweets", $auth, $apiUrl);

GET TWEET

get($id);

Get an individual tweet by ID. HTTP REQUEST

GET /tweets/ID RESPONSE

Expected Response Code: 200 https://developer.mautic.org/#plugin-directory-structure

202/222

17/12/2017


See JSON code example. Tweet Properties Name

Type

Description

id

int

ID of the tweet

name

string

Title of the tweet

text

string

Message of the tweet

isPublished

bool

Published state

publishUp

datetime/null

Date/time when the tweet should be published

publishDown

datetime/null

Date/time the tweet should be un published

dateAdded

datetime

Date/time tweet was created

createdBy

int

ID of the user that created the tweet

createdByUser

string

Name of the user that created the tweet

dateModified

datetime/null

Date/time tweet was last modified

modifiedBy

int

ID of the user that last modified the tweet

modifiedByUser

string

Name of the user that last modified the tweet

language

string

Language locale of the tweet

category

null/object

Category

LIST TWEETS


HTTP REQUEST

GET /tweets


Description

search


start


limit


orderBy


orderByDir


publishedOnly



203/222

17/12/2017


Name

Description

minimal


RESPONSE



Same as Get Tweet. CREATE TWEET

=> 'Tweet A',

'heading' => 'Hello World!' 'message' => 'This is my first tweet created via API.', ); $tweet = $tweetApi->create($data);

Create a new tweet. HTTP REQUEST

POST /tweets/new


Type

Description

id

int

ID of the tweet

name

string

Title of the tweet

text

string


url

string

URL to go to when the tweet is clicked

isPublished

bool

Published state

publishUp

datetime/null


publishDown

datetime/null


language

string


RESPONSE


Properties

Same as Get Tweet. EDIT TWEET


204/222

17/12/2017


= 1;

$data = array( 'name' => 'Tweet A', 'text' => 'This is my first tweet created via API.', ); // Create new a tweet of ID 1 is not found? $createIfNotFound = true; $tweet = $tweetApi->edit($id, $data, $createIfNotFound);

Edit a new tweet. Note that this supports PUT or PATCH depending on the desired behavior. PUT creates a tweet if the given ID does not exist and clears all the tweet information, adds the information from the request. PATCH fails if the tweet with the given ID does not exist and updates the tweet field values with the values form the request. HTTP REQUEST

To edit a tweet and return a 404 if the tweet is not found: PATCH /tweets/ID/edit

To edit a tweet and create a new one if the tweet is not found: PUT /tweets/ID/edit


Type

Description

id

int

ID of the tweet

name

string

Title of the tweet

text

string


url

string

URL to go to when the tweet is clicked

isPublished

bool

Published state

publishUp

datetime/null


publishDown

datetime/null


language

string


RESPONSE

If

PUT ,


If

PATCH ,

200 if


the tweet was edited or

201 if

created.

200 .

Properties Same as Get Tweet. DELETE TWEET

delete($id);


205/222

17/12/2017


Delete a tweet. HTTP REQUEST

DELETE /tweets/ID/delete RESPONSE


Properties

Same as Get Tweet.

Users Use this endpoint to obtain details on Mautic’s users (administrators).


$apiUrl


$api

= new MauticApi();

$userApi

= $api->newApi("users", $auth, $apiUrl);

GET USER

get($id);

Get an individual user by ID. HTTP REQUEST

GET /users/ID RESPONSE


See JSON code example. User Properties Name

Type

Description

id

int

ID of the contact

dateAdded

datetime


createdBy

int



206/222

17/12/2017


Name

Type

Description

createdByUser

string


dateModified

datetime/null


lastActive

datetime/null

Date/time when the user last active

modifiedBy

int


modifiedByUser

string


username

string

Username which can be used for log in to Mautic.

firstName

string

First Name of the user

lastName

string

Last Name of the user

email

string

Email of the user

position

string

User’s position title

role

array

List of roles of the user

timezone

string

Timezone of the user

onlineStatus

string

Online status of the user

signature

string

Signature of the user which can be used in the emails

LIST CONTACT USERS


HTTP REQUEST

GET /users RESPONSE


See JSON code example. User Properties Name

Type

Description

id

int

ID of the contact

dateAdded

datetime


createdBy

int


createdByUser

string


dateModified

datetime/null



207/222

17/12/2017


Name

Type

Description

lastActive

datetime/null

Date/time when the user last active

modifiedBy

int


modifiedByUser

string


username

string

Username which can be used for log in to Mautic.

firstName

string

First Name of the user

lastName

string

Last Name of the user

email

string

Email of the user

position

string

User’s position title

role

array

List of roles of the user

timezone

string

Timezone of the user

onlineStatus

string

Online status of the user

signature

string

Signature of the user which can be used in the emails

CREATE USER

'apitest', 'firstName' => 'John', 'lastName' => 'Doe', 'email' => '[email protected]', 'plainPassword' => array( 'password' => 'topSecret007', 'confirm' => 'topSecret007', ), 'role' => 1, ); $user = $userApi->create($data);

Create a new user. HTTP REQUEST

POST /users/new


Description

username

string

firstName

string

lastName

string

email

string


208/222

17/12/2017


Name

Description

position

string

role

array

timezone

string

onlineStatus

string

signature

string

plainPassword

array

RESPONSE


Properties Same as Get User. EDIT USER

= 1;

$data = array( 'lastName' => 'Doeboe', ); // Create new a user of ID 1 is not found? $createIfNotFound = true; $user = $userApi->edit($id, $data, $createIfNotFound);

Edit a new user. User that this supports PUT or PATCH depending on the desired behavior. PUT creates a user if the given ID does not exist and clears all the user information, adds the information from the request. PATCH fails if the user with the given ID does not exist and updates the user field values with the values form the request. HTTP REQUEST

To edit a user and return a 404 if the user is not found: PATCH /users/ID/edit

To edit a user and create a new one if the user is not found: PUT /users/ID/edit


Description

username

string

firstName

string

lastName

string

email

string


209/222

17/12/2017

Name


Description

position

string

role

array

timezone

string

signature

string

RESPONSE

If PUT , the expected response code is 200 if the user was edited or 201 if created. If PATCH , the expected response code is 200 . Properties

Same as Get User. DELETE USER

delete($id);

Delete a user. HTTP REQUEST

DELETE /users/ID/delete RESPONSE


Properties

Same as Get User. GET SELF USER

getSelf();

Get a self user. HTTP REQUEST

GET /users/self RESPONSE


Properties

Same as Get User. CHECK USER PERMISSIONS


210/222

17/12/2017


$user = $userApi->checkPermission($id, $permission);

Get a self user. HTTP REQUEST

GET /users/ID/permissioncheck RESPONSE

Expected Response Code: 200 json { "user:users:create":true, "user:users:edit":true }

Properties

array of requested permissions of string in case of just one

Webhooks Use this endpoint to obtain details on Mautic’s webhooks. Implemented in Mautic 2.8.0.

= new ApiAuth();

$auth


$apiUrl


$api

= new MauticApi();

$webhookApi

= $api->newApi("webhooks", $auth, $apiUrl);

GET WEBHOOK

get($id);

Get an individual webhook by ID. HTTP REQUEST

GET /hooks/ID RESPONSE


See JSON code example. Webhook Properties Name

Type

Description

id

int

ID of the webhook

name

string

Title of the webhook

description

string

Description of the webhook


211/222

17/12/2017


Name

Type

Description

webhookUrl

string

Url to send the webhook payload to

eventsOrderbyDir

Order direction for queued events in one webhook. Can be “DESC” or “ASC”

isPublished

bool

Published state

publishUp

datetime/null

Date/time when the webhook should be published

publishDown

datetime/null

Date/time the webhook should be un published

dateAdded

datetime

Date/time webhook was created

createdBy

int

ID of the user that created the webhook

createdByUser

string

Name of the user that created the webhook

dateModified

datetime/null

Date/time webhook was last modified

modifiedBy

int

ID of the user that last modified the webhook

modifiedByUser

string

Name of the user that last modified the webhook

category

null/object

Category

triggers

array

List of triggers available in Mautic

LIST WEBHOOKS


HTTP REQUEST

GET /webhooks


Description

search


start


limit


orderBy


orderByDir


publishedOnly


minimal



212/222

17/12/2017


RESPONSE



Same as Get Webhook. CREATE WEBHOOK

'test', 'description' => 'Created via API', 'webhookUrl' => 'http://some.url', 'eventsOrderbyDir' => "ASC", 'triggers' => array( 'mautic.lead_post_save_update', 'mautic.lead_post_save_new', ) ); $webhook = $webhookApi->create($data);

Create a new webhook. HTTP REQUEST

POST /hooks/new


Type

Description

id

int

ID of the webhook

name

string


description

string


webhookUrl

string

URL to send the webhook payload to

eventsOrderbyDir


isPublished

bool

Published state

RESPONSE


Properties

Same as Get Webhook. EDIT WEBHOOK

= 1;

$data = array(


213/222

17/12/2017


'name' => 'Rename webhook 1 to this', ); // Create new a webhook of ID 1 is not found? $createIfNotFound = true; $webhook = $webhookApi->edit($id, $data, $createIfNotFound);

Edit a new webhook. Note that this supports PUT or PATCH depending on the desired behavior. PUT creates a webhook if the given ID does not exist and clears all the webhook information, adds the information from the request. PATCH fails if the webhook with the given ID does not exist and updates the webhook field values with the values form the request. HTTP REQUEST

To edit a webhook and return a 404 if the webhook is not found: PATCH /hooks/ID/edit

To edit a webhook and create a new one if the webhook is not found: PUT /hooks/ID/edit


Type

Description

id

int

ID of the webhook

name

string


description

string


webhookUrl

string

Url to send the webhook payload to

eventsOrderbyDir


isPublished

bool

Published state

RESPONSE

If PUT , the expected response code is 200 if the webhook was edited or 201 if created. If PATCH , the expected response code is 200 . Properties Same as Get Webhook. DELETE WEBHOOK

delete($id);

Delete a webhook. HTTP REQUEST

DELETE /hooks/ID/delete RESPONSE



214/222

17/12/2017


Same as Get Webhook. LIST AVAILABLE WEBHOOK TRIGGERS

getTriggers();

List webhook triggers HTTP REQUEST

GET /hooks/triggers RESPONSE


Webhooks Webhook is a universal way how to send data about leads, pages, forms and events. The data is sent in real-time when an action occurs so the system which listens form Mautic webhook data can process them without the need for a periodic scanning if Mautic has some new data.

Available webhook actions Mautic can send webhook payload on these actions: Email open Form submit Lead delete Lead point change Lead update Lead create Page hit

The webhook workflow The example workflow below describes a real-life workflow to get an idea how the webhooks can be used. Let’s imagine we have a project management system (PMS) and we want to create a new issue when a lead s ubmits a form. 1. A lead submits a Mautic form. 2. Mautic saves the form. 3. Mautic checks if there is a webhook with the Form submit event. If there is, Mautic sends the data to the URL address defined in the webhook. 4. PMS receives the data about the form submission and creates a new issue from it.

Create a webhook https://developer.mautic.org/#plugin-directory-structure

215/222

17/12/2017


It is possible to create multiple different webhooks. That will allow you to send different information to different apps/scripts. 1. Open the right hand side menu (click the cog icon in the top right corner) and select Webhooks . 2. Create a new webhook. 3. Fill in a Name , Webhook POST Url (see the next paragraph if you don’t have one) and select which Webhook Events should trigger this webhook.

Test a webhook The easiest way how to test a webhook payload is to use a service like RequestBin. RequestBin lets you create a URL which you can set as the Webhook POST Url in Mautic. Then click the Apply button to save it and then click the Send Test Payload button. That will send a test payload data to RequestBin and you will be able to see it at your RequestBin. When you have created your testing webhook, you can test the real data it sends when a defined action is triggered.

Immediate or queued webhooks There is an option to queue webhooks for background execution. The reason behind it is that every time an ac tion like contact update happens which has the webhook listener attached to it, the action has to wait for the webhook response untill the webhook res ponse returns or when it times out after 10 s enconds. So it is up to the webhook reciever how fast the contact update is. This lag can be more visible when you do a CSV import. It may be slow when it is waiting a second or two for webhook response for every imported contact. If you want to avoid this lag, c onfigure the webhook queue in the configuration and add this command to your cron tab: app/console mau‐ tic:webhooks:process .

This way every time the webhook is triggered, the action is queued as a new row into database, so it is much faster

and then the command will make the requests which may take some time. The caveat to this optimisation is that the webhooks are not fired every time the action happens, but every time the command runs.

Queued event order Mautic will send several events in one webhook if they happen before the queue trigger command runs. Mautic’s default order of those events is chronological. But Zapier integration which use webhooks havily requires reverse chronological order. Thereofore the new option to configure the order was added to webhooks as well as to the global configuration. Webhook configuration overwrites the global configuration, but if not set, the global configuration order value is applied.

Example webhook script If you need an idea about how to receive Mautic webhook data in your app, this script can be used as a starting point. The script will log the request and return a PHP object of the payload. Place this script on a publicly accessible URL (i.e. `http://yourwebsite.com/webhookTest.php), then fill in the Mautic Webhook POST Url to this script.


216/222

17/12/2017


/** * A helper class to log and get the Mautic webhook request */ class webhookTest { /** * Log a message to a file * * @param

mixed $message

* @param

string $type [info|error|request]

*/ public function log($message, $type = 'info') { $prefix = 'webhookLog_'; $file = $type . '.log'; $date = new DateTime(); error_log($date->format('Y-m-d H:i:s') . ' ' . $message . "\n\n", 3, $prefix . $file); } /** * Get the request JSON object and log the request * * @return object */ public function getRequest() { $rawData = file_get_contents("php://input"); $this->log($rawData, 'request'); return json_decode($rawData); } } $webhook = new webhookTest; $requestData = $webhook->getRequest(); // @todo Process the $requestData as needed

If you’d like to extend the webhook functionality with your plugin, read more in the plugin docs .

MauticJS API Mautic provides a means for plugins to inject custom JavaScript into mtc.js, the PHP generated script that manages Mautic’s tracking pixel, dynamic web content, etc. mtc.js is embedded in 3rd party websites to manage communication between those and Mautic.

mtc.js

217/222

17/12/2017


*/ public static function getSubscribedEvents() { return array( CoreEvents::BUILD_MAUTIC_JS => array('onBuildJs', 0) ); } /** * @param BuildJsEvent $event * * @return void */ public function onBuildJs(BuildJsEvent $event) { $js = <<appendJs($js, 'HelloWorld'); } }

To inject custom Jav ascript into mtc.js, use an event listener for the CoreEvents::BUILD_MAUTIC_JS event. This event receives a Mautic\Co‐ reBundle\Event\BuildJsEvent object where $event->appendJs($js, $sectionName); can be used to inject the script’s code.



Only native Javascript or MauticJs API functions should be used since jQuery and other libraries are not guaranteed to be

available in 3rd party websites.

JS Form Processing Hooks if (typeof MauticFormCallback == 'undefined') { var MauticFormCallback = {}; } MauticFormCallback['replaceWithFormName'] = { onValidateEnd: function (formValid) { // before form submit }, onResponse: function (response) { // after form submit } };

If you wish execute additional code to execute as form is being processed create a MauticFormCallback object. In the example code replace replaceWithFormName with the name of your form. onValidateEnd and onResponse are actions called by Form.customCallbackHandler . ONVALIDATE()

MauticFormCallback['replaceWithFormName'] = { onValidate: function () { // before form validation var formIsGood = True; var dontUpdate = False; if(dontUpdate){


218/222

17/12/2017

Mautic Developer Documentation return null; }else if(formIsGood){ return True; }else if(!formIsGood){ return False; }

}, };

Called before default form validation and can be used to override default form validation. Return

True to

skip the default form validation continue with form processing. Return

the form submission. Return

null to

False to

skip the default form validation and prevent

execute default form validation.

ONVALIDATESTART()

MauticFormCallback['replaceWithFormName'] = { onValidateStart: function () { // before default validation }, };

Called at the beginning of the default form validation. Receives no values and return value is not required and not processed.



onValidateStart may not be executed if the default form validation is handled during the ònValidate` callback

ONVALIDATEEND(FORMVALID)

MauticFormCallback['replaceWithFormName'] = { onValidateEnd: function (formValid) { // before form submit }, };

Called after all form validation is complete (default and/or

onValidate

callback) and before the form is submitted. Receives

formValid

to

determine if form is valid. Return value is not required and not processed. ONERRORMARK(CALLBACKDATA)

var callbackData = { containerId: containerId, valid: valid, validationMessage: callbackValidationMessage }; MauticFormCallback['replaceWithFormName'] = { onErrorMark: function (callbackData) { // called during error marking }, };

Called during error marking. Receives a

callbackData

object. Return

True to

skip the default error marking.

ONERRORCLEAR(CONTAINERID)

MauticFormCallback['replaceWithFormName'] = { onErrorClear: function (containerId) { // called to clear an existing error }, };


219/222

17/12/2017


Called to clear an existing error. Receives containerId with the id of the element containing the error. Return True to skip the default error clearing. ONRESPONSE(RESPONSE)

MauticFormCallback['replaceWithFormName'] = { onResponse: function (response) { // called to process the response to the form submission }, };

Called prior to default form submission response processing. Receives response containing the form submission response. Return True to skip the default form submission response processing. ONRESPONSESTART(RESPONSE)

MauticFormCallback['replaceWithFormName'] = { onResponseStart: function (response) { // called to process the response to the form submission }, };

Called at the beginning default form submission response processing. Receives response containing the form submission response. Return value is not required and not processed.



onResponseStart may not be executed if the default response processing is handled during the ònResponse` callback

ONRESPONSEEND(RESPONSE)

MauticFormCallback['replaceWithFormName'] = { onResponseEnd: function (response) { // called to process the response to the form submission }, };

Called at the end default form submission response proces sing. Receives response containing the form submission response. Return value is not required and not processed.



onResponseEnd may not be executed if the default response processing is handled during the ònResponse` callback

ONMESSAGESET(MESSAGEOBJECT)

var messageObject = { message: message, type: type }; MauticFormCallback['replaceWithFormName'] = { onErrorMark: function (messageObject) { // called prior to default message insertion }, };

Called prior to default message insertion. Receives a messageObject containing the message and message type. Return True to skip the default message insertion. https://developer.mautic.org/#plugin-directory-structure

220/222

17/12/2017


ONSUBMITBUTTONDISABLE(MESSAGEOBJECT)

MauticFormCallback['replaceWithFormName'] = { onErrorMark: function (messageObject) { // called prior to default message insertion }, };

Called prior to default disabling of the submit button. Receives no values. Return

True to

skip the default disabling of the submit button.

True to

skip the default enabling of the submit button.

ONSUBMITBUTTONENABLE()

MauticFormCallback['replaceWithFormName'] = { onErrorMark: function (messageObject) { // called prior to default message insertion }, };

Called prior to default enabling of the submit button. Receives no values. Return

MauticJS API Functions MAUTICJS.SERIALIZE(OBJECT)

This method will transform an object properties into a k ey=value string, concatenating them with an ampersand. It is used when submitting data via MauticJS.makeCORSRequest.

var obj = {firstname: "John", lastname: "Doe"}; var serialized = MauticJS.serialize(obj); alert(serialized); // Shows "firstname=John&lastname=Doe"

MAUTICJS.DOCUMENTREADY(FUNCTIONNAME|FUNCTION)

This method will check if the document has finished rendering, then execute the given function. The function argument can be the name of a function or an anonymous function.

function test() { alert('test'); } MauticJS.documentReady(test);

MAUTICJS.ITERATECOLLECTION(COLLECTION)(FUNCTIONNAME|FUNCTION)

This method will iterate over the provided collection (array, object, HTMLCollection, etc) using the provided function argument. The function argument can be the name of a function or an anonymous function. The function will receive the collection node and the iteration number as arguments.

var videos = document.getElementsByTagName('video'); // Add a custom data attribute to all videos MauticJS.iterateCollection(videos)(function(node, i) { node.dataset.customAttribute = 'test'; });


221/222

Another Mautic Guide

Recommend Documents

trans('plugin.helloworld.worlds', array('%world%', 'Mars'); ?>

trans('mautic.config.tab.helloworld_config'); ?>

Hello there!

{{ message|raw }}

{{ header }}

{{ message|raw }}