combindma / laravel-mautic
Mautic API for Laravel applications
Requires
- php: ^8.1
- guzzlehttp/guzzle: ^7.5|^8.0
- illuminate/contracts: ^10.0|^11.0
- saloonphp/laravel-plugin: ^3.0
- spatie/laravel-package-tools: ^1.14.0
Requires (Dev)
- laravel/pint: ^1.0
- mockery/mockery: ^1.5
- nunomaduro/collision: ^7.0|^8.0
- orchestra/testbench: ^8.0|^9.0
- pestphp/pest: ^2.0
- pestphp/pest-plugin-arch: ^2.0
- pestphp/pest-plugin-laravel: ^2.0
README
Free and Open Source Marketing Automation APIFree and Open Source Marketing Automation API
Installation
You can install the package via composer:
composer require combindma/laravel-mautic
You can publish the config file with:
php artisan vendor:publish --tag="laravel-mautic-config"
This is the contents of the published config file:
return [ /* |-------------------------------------------------------------------------- | Auth Type |-------------------------------------------------------------------------- | Version of the auth can be OAuth2 or BasicAuth. OAuth2 is the default value. | */ 'version' => env('MAUTIC_VERSION', 'OAuth2'), //or BasicAuth /* * Base URL of the Mautic instance */ 'baseUrl' => env('MAUTIC_BASE_URL'), /* * Client/Consumer key from Mautic */ 'clientKey' => env('MAUTIC_PUBLIC_KEY'), /* * Client/Consumer secret key from Mautic */ 'clientSecret' => env('MAUTIC_SECRET_KEY'), /* * Redirect URI/Callback URI for this script */ 'callback' => env('MAUTIC_CALLBACK'), /* |-------------------------------------------------------------------------- | Mautic App Credentials |-------------------------------------------------------------------------- | | This is used in case of BasicAuth | */ 'username' => env('MAUTIC_USERNAME'), 'password' => env('MAUTIC_PASSWORD'), /* * Enable or disable Mautic. Useful for local development when running tests. */ 'apiEnabled' => env('MAUTIC_ENABLED', false), /* * Filename to use when storing mautic access token. Must be a json File */ 'fileName' => 'mautic.json', ];
Optionally, you can publish the views using
php artisan vendor:publish --tag="laravel-mautic-views"
Authorization
This Library only supports OAuth2
and BasicAuth
Authentication.
For OAuth2 you need to create a OAuth2
client in order to use the api.
OAuth2 Mautic Setup
The API must be enabled in Mautic.
Within Mautic, go to the Configuration page (located in the Settings menu) and under API Settings enable Mautic's API.
After saving the configuration, go to the API Credentials page (located in the Settings menu) and create a new client.
Enter the callback/redirect URI (Should be https://your-domain.com/integration/mautic/callback
). Click Apply, then copy the Client ID and Client Secret to the .env file.
This is an example of .env file:
MAUTIC_VERSION="OAuth2"
MAUTIC_BASE_URL=https://mautic-domain.com
MAUTIC_PUBLIC_KEY=XXXXXXXXXXXXXXXX
MAUTIC_SECRET_KEY=XXXXXXXXXX
MAUTIC_CALLBACK=https://your-domain.com/integration/mautic/callback
MAUTIC_ENABLED=true
BasicAuth Mautic Setup
You need to add your username
and password
in .env file for BasicAuth:
MAUTIC_VERSION="BasicAuth"
MAUTIC_BASE_URL=https://mautic-domain.com
MAUTIC_USERNAME=email@email.com
MAUTIC_PASSWORD=password
MAUTIC_ENABLED=true
Registering Application (Only OAuth2 Authentication)
In order to register you application with mautic ping this url one time to register your application.
https://your-domain.com/integration/mautic
Usage
Managing Contacts
When working with Contact API, the IpAddress and lastActive parameters are added by default, so that you don't have to include them.
use Combindma\Mautic\Facades\Mautic; //Create a new contact Mautic::contacts()->create('email@gmail.com'); //with $parameters $params = array( 'firstname' => 'bullet', 'lastname' => 'proof', ); Mautic::contacts()->create('email@gmail.com', $params); //Edit a given contact Mautic::contacts()->edit($contactId, $params); //Delete a contact Mautic::contacts()->delete(567);//567 is the contact ID, change it to your needs
Managing Contacts with segment
use Combindma\Mautic\Facades\Mautic; //Add contact to a segment Mautic::segments()->addContact($segmentId, $contactId); //Create a contact and add it to a segment $response = Mautic::contacts()->create(strtolower($request->input('email'))); if ($response && !$response->failed()) { $contactId = $response->object()->contact->id; Mautic::segments()->addContact(4, $contactId);//4 is the segment ID, change it to your needs } //Remove a contact from a given segment Mautic::segments()->removeContact($segmentId, $contactId);
Managing Contacts with UTM Tags
use Combindma\Mautic\Facades\Mautic; //Add UTM tags to a given contact $data = array( 'utm_campaign' => 'apicampaign', 'utm_source' => 'fb', 'utm_medium' => 'social', 'utm_content' => 'fbad', 'utm_term' => 'mautic api', 'useragent' => 'Mozilla/5.0 (Windows NT 10.0; WOW64; rv:50.0) Gecko/20100101 Firefox/50.0', 'url' => '/product/fbad01/', 'referer' => 'https://google.com/q=mautic+api', 'query' => ['cid'=>'abc','cond'=>'new'], // or as string with "cid=abc&cond=new" 'remotehost' => 'example.com', 'lastActive' => '2017-01-17T00:30:08+00:00' ); Mautic::utmTags()->addUtmTag($contactId, $data); //Remove a given UTM Tag from contact Mautic::utmTags()->removeUtmTag($utmId, $contactId);
Managing Contacts points
use Combindma\Mautic\Facades\Mautic; //Add contact points $data = array( 'eventName' => 'Score via api', 'actionName' => 'Adding', ); Mautic::points()->addPoints($contactId, 10, $data);//$data is optional //Subtract contact points $data = array( 'eventname' => 'Score via api', 'actionname' => 'Subtracting', ); Mautic::points()->subtractPoints($contactId, 10, $data);//$data is optional
Macrobale
Communicating with the API can become a repetitive process. that's why we made this package macroable.
use Combindma\Mautic\Facades\Mautic; //include this in your macrobale file Mautic::macro('subscribe', function(string $email) { $response = Mautic::contacts()->create(strtolower($request->input('email'))); if ($response && !$response->failed()) { $contactId = $response->object()->contact->id; Mautic::segments()->addContact(4, $contactId);//4 is the segment ID, change it to your needs } }); //In your controller, you only need to call your method Mautic::sbscribe('email@email.com');
Please refer to Documentation. for all customizable parameters.
Testing
composer test
Contributing
Please see CONTRIBUTING for details.
Security Vulnerabilities
Please review our security policy on how to report security vulnerabilities.
Credits
License
The MIT License (MIT). Please see License File for more information.