Documentation Disaster

Product Support
1

Help help help. How did this happen. And how can I help (properly) to get this sorted. Mautic is awesome. The documentation is a disaster.

  1. The API docs are all over the place, out of date, “off-referencing” other locations - it’s a mess.
  2. The Joomla plugin is out of date and doesn’t push contacts. The URL in the docs to the git repository is broken.
  3. There’s information on Github and mautic… and in text files and in the dev docs - scattered around. Much of it out of date - or saying to read something else.
  4. There’s a distinct lack of hands-on, real-world code examples - i.e. actual workable PHP rather than conceptual PHP which just expects the user to have grasped all that has gone before.
  5. Videos on Youtube are 3,4,5 years out of date. Or show functionality that is now hidden (Table view/Card View) or a mystery (Tags in the menu items? where?)
  6. There is almost no information on how to use the API properly - it assumes you use Composer. It assumes you use PHP library. Both of which are not accessible to many on shared hosting.

It was hard enough to battle through the plethora of unclearness just to get the CRON jobs up and running. But, at least that is pretty simple.

The API docs are the most confusing. They assume you are using the PHP Librabry rather than cURL. I can’t get the PHP Library to work as it says it is missing bits - it can’t locate the following:

require_once DIR . ‘/lib/Psr/Log/LogLevel.php’;
require_once DIR . ‘/lib/Psr/Log/LoggerInterface.php’;
require_once DIR . ‘/lib/Psr/Log/AbstractLogger.php’;
require_once DIR . ‘/lib/Psr/Log/NullLogger.php’;
require_once DIR . ‘/lib/Psr/Log/LoggerAwareInterface.php’;

I wanted to use the Joomla plugin but that just gives me an authentication error. With no explanation. I suspect it is out of date?? (It still tries to use the “leads” context)

I am pretty tech savvy. And have wired up numerous REST APIs (hell, I have even built them) - - - So, I don’t think I am being unreasonable.

I know I am really new to the party, but how can I get the detail and build real-world working examples for people to access. Who “knows” this stuff in detail or can send me code samples that I can put together? Who can I access and turn their knowledge into some kind of 2021 “Dummies Guide To Mautic” because there isn’t the level of clarity I a used to seeing in documentation.

And I need to be able to API from my Databases in and out of Mautic.

1 Like
2

Hey,

The good news is: it was A LOT WORSE like a year ago. You would have written 3x longer list here.
I understand your frustration, my impression was also like: why is this project not better maintained?
Why can Wordpress do it better, or how come Sendy and Mailwizz have better docs?

Than I understood how things work around here. This is an open source project. You pay 0 for using and/or reselling Mautic. The above mentioned projects have their own ecosystems or you pay yearly fee for them, that allows the owners to pay people to write docs.

Well, Mautic is not entirely free, the currency you pay is your own contribution. Our common effort to make things better will bring us forward. Together.

Some part of the docs are outdated, because noone from the community picked up that thread and started to fix it. There was noone around with free time and skills to write it. Other parts are up-to-date, we are just working on docs regarding the new email builder.

But hey, I know where your frustration comes from, and I have some answers to you to put you on the fast track of using, embracing Mautic and maybe contributing.

There is a collection of Videos I curated, plz take a look:
The Videos on youtube are not out of date, but they are 3 years old :slight_smile: There are new ones as well, check my library: https://joeykeller.com/learn-mautic-with-community-videos/

If you are fiddling with API, maybe this helps:

There are snipplets with basic auth, maybe it points you to the right direction.
You can also ask me questions directly (altough I think you are more tech savy than me) and I try to point you at the right direction.

Dummies Guide to Mautic
This is a little bit like Dummies Guide to Dating. Sounds like a million dollar idea, but it’s a huge challenge to pull it off. There are just way too many used cases. At the same time the education team is working on that really hard and they are putting a FAQ together.
Sometimes when concrete questions come up, than I also try to even create a video, that takes your hand and guides you through. Recently with Dynamic content. Someone asked a question in the forums, and a video was made to help him (and other users out):

image
image486×767 57.4 KB

Access to information:

  • Try to follow contributors here, and don’t be shy to answer questions. I’ll answer every time for example.
  • Read the Knowledge base
  • Listen to the Mauticast to stay uptodate about developments
  • Visit the Lagos Mautic Meetup to learn about stuff (there are videos as well)
  • Come to the Slack channel and connect directly with people you share interest with (dev, marketing, design, mautic as business, your contrymates, etc.)

Once you spend more time here you will realise, that this community is small enough to be a friendly group of people even we are often competitors in the business world. We ACTUALLY help each other, ACTUALLY answer questions, and try to help each other out. We know, that things are a bit behind here, so we put our sh*t together and try to change it. We crowdfund, develop together, share stuff for free.

And once you feel comfortable with the rules above, you’ll read a thank you from a person who just created his first webhook thanks to your doc changes, and you will feel amazing about yourself.

Good Luck!
J

2 Likes
3

Thanks Joey…

I am a massive believer that Documentation maketh the app. And I am keen to help. My skill is communication, training and simplifying complex issue ‘for the lay person’. i.e. making Open Source easier means it democratises the tech and makes it accessible to a wider world.

It seems to me that there is the PHP Library layer above the REST API which has been invested heavily in time, energy and resources at the expense of just explaining how to use the REST API raw with cURL (which is really easy stuff!) examples - and then we get into all sorts of issues with classes and Composer and files missing and maintaining a massive “Context Layer” above the REST API and neglecting the basics.

Anyway, I really appreciate the answer above. Just to reassure, I am a big fan of open source and love to contribute, help and make it as awesome as possible. I used to be heavily involved in Joomla - devving components and plugins… but I haven’t for quite a while now. I actually met Ruth Cheesley at Joomla UK day a few (many!!!) years back and I am VERY keen to contribute and be part of the community.

But I feel like a real newbie at the moment and a bit out of my depth.

I will read all the info you posted above. I am actually putting together some “Basic Auth” help stuff now.

4

Hey! I’m glad my answer helped.
If you go with basic auth, you can start from here:

<?php
$loginname = 'apiuser';
// Loginname of your API user
$password = 'yourpasswordhere';
// This is the password of the API user
$siteurl = 'yoursiteurl.tld';
// example: mymautic.com
// The data you would like to transfer is called payload. We will set it for now, and later replace with the data we get from the webhook.

$email = 'captain_enterprise-d@starfleet.com';
$firstname = 'Jean-Luc';
$lastname = 'Picard';
$tag = 'purchased';
// This is our curl call:

$curl = curl_init();
// Set some options - we are passing in a user agent too here
  curl_setopt_array($curl, array(
  CURLOPT_RETURNTRANSFER => 1,
  CURLOPT_URL => "https://".$loginname.":".$password."@".$siteurl."/api/contacts/new",
  CURLOPT_USERAGENT => 'Wesleys Secret App',
  CURLOPT_POST => 1,
// posting the payload
  CURLOPT_POSTFIELDS => array(
    'firstname' => $firstname,
    'lastname' => $lastname,
    'email' => $email,
    'tags' => $tag
  )
));
curl_exec($curl);

GL:
Joey

5

OK… really interesting.

I was just about to message you about that!..

In the docs, it says to base64 encode the string and send it as an Auth header…

e.g.

$username = "myLoginUsernameToMyMauticInstance";
$password = "myPasswordToMyMauticInstance"; 
$str = $username . ":" . $password; echo "<p>str: " . $str . "</p>";
$apikey = base64_encode($str);

Then I did something like this:

$id=2;
$url = $endpoint . "contacts/" . $id; echo "<p>URL: " . $url . "</p>";
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);



curl_setopt($curl, CURLOPT_HTTPHEADER, array('Authorization: Basic ' . $apikey)); echo "<p>apikey: " . $apikey . "</p>";
curl_setopt($curl,CURLOPT_FOLLOWLOCATION,true);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); // Set the result output to be a string.
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
$data = curl_exec($curl);
if ($data === false) 
	{
	$info = curl_getinfo($curl);
	curl_close($curl);
	die('error occured during curl exec. Additional info: ' . var_export($info));
	}
	else
	{
	curl_close($curl);
	}





$decodedContact = json_decode($data);
echo "<h2>decodedContact</h2>";
echo "<pre>";
print_r($decodedContact);
echo "</pre>";

And it worked …

Is the whole UN & PW in the URL still working then???

6

However, I am struggling to do a POST…

I am not getting any error messages … but the data is not being added. I will rummage & learn, rummage & learn.

Thank you so much for your help so far. So grateful !!

7

And POST… Yes! Very excited !!!

Just a couple of code samples in the docs would have saved me hours. Thank you so much for your code samples Joey!!!

## Authenicate as per above.




$url = $endpoint . "contacts/new"; echo "<p>URL: " . $url . "</p>";
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);

## SET TO POST AND GET BUILD THE DATA ****************************** 
curl_setopt($curl, CURLOPT_POST, 1); // Set as a POST
$data = array(
    'owner' => 1,
    'firstname' => 'Jim',
    'lastname'  => 'Contact',
    'email'     => 'jim.contact@his-site.com',
    'ipAddress' => $_SERVER['REMOTE_ADDR'],
    'overwriteWithBlank' => true
);

echo "<pre>";
print_r($data);
echo "</pre>";


# curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
## ****************************************************************** 

curl_setopt($curl, CURLOPT_HTTPHEADER, array('Authorization: Basic ' . $apikey));
curl_setopt($curl,CURLOPT_HEADER,true); // copied from th PHP AbstractAuth.php "function makeRequest".
curl_setopt($curl,CURLOPT_FOLLOWLOCATION,true);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); // Set the result output to be a string.
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false); // copied from th PHP AbstractAuth.php "function makeRequest".
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
$data = curl_exec($curl);
if ($data === false) 
	{
	$info = curl_getinfo($curl);
	curl_close($curl);
	die('error occurred during curl exec. Additional info: ' . var_export($info));
	}
	else
	{
	$info = curl_getinfo($curl);
	var_export($info);
	curl_close($curl);
	}
1 Like
8

HI Adam,

Totally agree with the comments that @joeyk made above - we are working to address these issues but we have had very little interest from the community in improving the developer documentation. We absolutely would value some help in this.

We have an Education Team which is responsible for this and who work closely with the Product Team. Join us on Slack (https://mautic.org/slack for an invite) and join #t-education and #t-product respectively.

We are also in the slightly longer term looking to move to API Platform based architecture, which will have quite an impact on our developer docs in a practical sense.

If you’d like to contribute to improving the Developer Docs in the meantime (including adding code samples!), you can make a PR at github.com/mautic/developer-documentation - this is where all of the dev docs are built from.

9

Awesome. Thanks Ruth. Very keen to help. Mautic looks amazing. I am hoping to help with the Joomla Plugin too unless someone else is already on it. It appears out of date (but I may be wrong).

Thanks so much!

PS: I haven’t need to use GitHub for yonks… sooooooo I best refresh myself on that too I guess :slight_smile:

10

The Joomla plugin has not been updated in an embarrassingly long time

Updated on 11 Oct 2017

You can find the repo here:

Let me know if you would like any help getting to grips with Github!

I have several Joomla sites so happy to help with testing any PR’s!

This might also be helpful: