What will we be doing?

Our goal during this sprint is to take a fresh look at key use cases and workflows, identify opportunities for improvement, review existing issue reports, proposed code changes (pull requests) on GitHub, and ideas from the Mautic forums.

Based on all this input, we aren’t just going to be prioritizing things – we’ll actually be implementing things! This is a great opportunity to join us in working to improve Mautic across many areas.

Who should join?

We’re hoping for 20-30 people to support the effort in Prague. Skills from all angles are needed, mainly:

• Experienced Mautic users: your insights into user experience are invaluable.
• Mautic developers: your coding skills are crucial for implementation.
• Anyone else! Marketing, design, documentation, testing – any perspective is welcome.

If you’ve never attended a Mautic event (and it’s geographically feasible for you to attend) this is the perfect place to get started!

Event details

• Start: Wednesday, July 9th, 12:00 AM CEST (no problem if you arrive later)
• End: Thursday, July 10th evening (most will stay for the night)
• Location: Impact Hub Praha D10, Drtinova 557/10, Smíchov, 150 00 Praha-Praha 5, Czech Republic. View on Map (Railway station is about 20 minutes away).

Sign up & support

Ready to join us in Prague? Sign up for free here: Sign Up for the Sprint!

Can’t make it to Prague? You now have two options: 

1. You can still help! We appreciate any contribution, big or small, to help cover event costs: Sponsor the Sprint (ideally €100,- or as much has you can)
2. You can attend remotely. As much as we would love to see you in person, we also would love to see you attend remotely and participate in the community sprint from the comfort of your (hopefully) cosy home.  

Shoutout

Let’s not forget to give a warm shoutout to the lovely people over at Impact Hub for giving us a nice NGO discount to run our sprint at their venue.  We can’t even begin to tell you how much we appreciate that.

Your feedback is important

Even if you can’t attend, please help us make the sprint a success by giving us your feedback / ideas on the most valuable quality improvements for Mautic: Give Us Your Quality Feedback!

We’re excited to work together to shape the future of Mautic!

But what exactly is Hacktoberfest? For those who might not know, Hacktoberfest is an annual, month-long celebration of open source software, held in October. It’s organized by DigitalOcean and encourages participation in the open source ecosystem, whether you’re a seasoned contributor or a first-timer. The event is open to everyone and all backgrounds and skill levels are encouraged to participate. In 2024, there’s been a greater focus on low- and no-code contributions, which has been great to see.

This year, we’ve experienced our most successful Hacktoberfest ever, and we couldn’t have done it without the amazing contributions from our Mautic community.

Over the course of October we’ve onboarded over 50 new contributors, which has been a record-breaker. Together, we’ve achieved:

• Completion of over 40 no-code tasks
• Completion of 18 pull request reviews
• Awarding of over 15 unique Holopin badges

Everyone who contributed received a ‘holobyte’ which allows them to claim our exclusive series of Hacktoberfest Holopin badges – don’t forget to check your GitHub issues and PRs if you haven’t claimed yours yet!

We’re incredibly proud of these achievements, but we also know that there’s always room for improvement. That’s why we’d love to hear your feedback on this year’s Hacktoberfest. 

Whether or not you contributed to Mautic during October, please take a moment to fill out the form here. Your insights will help us make future Hacktoberfests even better.

While Hacktoberfest may be over, the spirit of contribution lives on! We know that some of you didn’t manage to get around to contributing this time, but we’d love to have you joining us even outside of Hacktoberfest if you’re still looking for an opportunity to contribute to Mautic.

If this applies to you, please fill out the form above and select ‘yes’ in the field ‘do you still want to contribute to Mautic’. We’ll be in touch to give you a hand in getting started. You’ll receive an email with the relevant information for the tasks you wanted to contribute towards.

We’d like to extend a huge thank you to everyone who showed interest in contributing to Mautic. It’s incredibly exciting to see that over 300 of you cared enough to complete the form!

As we look forward to the future, we’re excited about the potential for growth, innovation, and community-building that lies ahead. Thank you for being a part of this journey. Here’s to many more successful Hacktoberfests!

We are hosting our first ever Mautic Developer Days event alongside the Drupal Developer Days in Ghent, Belgium from 4-8 April 2022.

From 4-6 April we will be having short talks and unconference-style sessions in the mornings, with dedicated sprint time in the afternoon to work on a range of tasks including the Symfony 5 upgrade.

There is also the option to extend your stay for the 7-8 April which will be open sprint time alongside other Open Source communities. It’s a great way to learn more from other developers and help us to really make progress with Mautic over the week of the event.

There will also be social events in the evening where we will join with other open source projects and visit some of the attractions in Ghent, go out for dinner and generally have a lot of fun!

What will we be working on?

During the contribution sprints, we will be focusing on the following:

• Symfony 5 support
• Testing and reviewing pull requests
• Working on the Mautic Marketplace
• Improving automation of code reviews with PHPSTAN and Rector
• Reviewing new features for 4.3

Want to know more?

Check out our page here: https://drupalcamp.be/en/drupal-dev-days-2022/mautic-developer-days-2022

Tickets are 90 euro (early bird) or 115 euro after they sell out for the entire week, which includes food and unlimited tea/coffee during the event, and access to the Mautic/Drupal Developer Days events.

Please let us know if you’re planning to attend by emailing ruth.cheesley@mautic.org.

Many organizations are moving toward a GitOps-based approach to managing software, and the way that Mautic was configured from the Composer perspective was previously suboptimal for organizations who need to manage Mautic installation and deployment with Composer.

This also made it very difficult to apply patches – whether from Mautic or from the organization themselves – in a way that is commonly accepted as best practice.

Two other Strategic Initiatives – Mautic Next Generation and the Mautic Marketplace – depend on significant changes to our architecture for being able to decouple plugins and themes and also have them managed independently.

We announced the Composer Initiative as a Strategic Initiative in November 2020 and work started to determine how to move Mautic toward a more future-friendly configuration.

What we have done

This project has been led by Nick Veenhof from Dropsolid and we are extremely grateful for his knowledge and time in making this initiative a reality. Also, big thanks to Rahul Shinde, John Linhart, and Dennis Ameling for their support in testing, reviewing, and suggesting improvements; and to the Drupal project from which we have taken much inspiration!

Three things were kept in mind when deciding how to execute this project:

• Making the developer experience as smooth as possible
• Enabling a phased approach to decoupling from core
• Following established best practices

There are several key things to be aware of now that we have mostly completed this project.

1. While we have ‘technically’ decoupled the app directory, all plugins, and themes into separate repositories, you will still find them located in the original folders in github.com/mautic/mautic at this stage:
   1. This approach allows for a smooth development process as all the files and folders that you see in Mautic are in the same repository.
   2. In the future, we may consider removing some plugins that are not widely used from Core and enabling users to selectively install them via the marketplace.
   3. Those plugins will, at that point, become maintained by a separate Tiger Team.
   4. The mirror repositories are read-only, pull requests should be made against https://github.com/mautic/mautic, not the mirrors – you will receive a reply from the bot if you attempt to make a PR against a mirror.
2. Whenever a pull request is made which touches any of these files, the changes are automatically pushed down to the read-only mirror repositories thanks to the amazing tool SubTreeSplit by Tobias Nyholm.
3. We now have a composer.json file in /app (as well as in all plugin and theme directories) which is used to build Mautic when installing with Composer.
4. We now have the Recommended Project repository – https://github.com/mautic/recommended-project and the scaffold – https://github.com/mautic/core-composer-scaffold which allows you to manage dependencies and move files outside the web root directory if you wish to do so.

What happens when you build Mautic

As before, you can still pull down Mautic and use the composer install command to install dependencies. This will now be much faster thanks to the upgrade to Composer 2.

You will notice that we now have a requirement on mautic/core-lib – this is the /app folder. We also now pull in all of the plugins and themes individually however in this first phase, we are telling Composer to use the files which it finds in mautic/mautic rather than looking elsewhere for the files – this is a precursor to being able to move some of this outside of the core.

We have also added some configuration settings and we set the correct paths for the different types of resources we are pulling in – the app directory, plugins, and themes.

Within the app folder, we have an additional composer.json file (in fact, all plugins and themes also now have a composer.json file) which has some settings relating to the scaffolding.

How do you use the recommended project?

This recommended project template provides a starter kit for managing your Mautic dependencies with Composer.

Usage

Note: The instructions below refer to the global composer installation. You might need to replace composer with php composer.phar (or similar) for your setup.

After that you can create the project:

composer create-project mautic/recommended-project:4.x-dev some-dir --no-interaction

With composer require … you can download new dependencies to your installation.

cd some-dir
composer require mautic/mautic-saelos-bundle:~2.0

The composer create-project command passes ownership of all files to the project that is created. You should create a new git repository, and commit all files not excluded by the .gitignore file.

What does the template do?

When installing the given composer.json some tasks are taken care of:

• Mautic will be installed in the public-directory.
• Autoloader is implemented to use the generated composer autoloader in vendor/autoload.php, instead of the one provided by Mautic (public/vendor/autoload.php).
• Plugins (packages of type mautic-plugin) will be placed in public/plugins/
• Themes (packages of type mautic-theme) will be placed in public/themes/
• Creates public/media directory.
• Creates environment variables based on your .env file. See .env.example.

Updating Mautic Core

This project will attempt to keep all of your Mautic Core files up-to-date; the project mautic/core-composer-scaffold is used to ensure that your scaffold files are updated every time mautic/core is updated. If you customize any of the “scaffolding” files (commonly .htaccess), you may need to merge conflicts if any of your modified files are updated in a new release of Mautic core.

Follow the steps below to update your core files.

1. Run composer update mautic/core –with-dependencies to update Mautic Core and its dependencies.
2. Run git diff to determine if any of the scaffolding files have changed. Review the files for any changes and restore any customizations to .htaccess or others.
3. Commit everything all together in a single commit, so the public will remain in sync with the core when checking out branches or running git bisect.
4. In the event that there are non-trivial conflicts in step 2, you may wish to perform these steps on a branch, and use git merge to combine the updated core files with your customized files. This facilitates the use of a three-way merge tool such as kdiff3. This setup is not necessary if your changes are simple; keeping all of your modifications at the beginning or end of the file is a good strategy to keep merges easy.

FAQs

Should I commit the contributed plugins I download?

Composer recommends no. They provide arguments against but also workarounds if a project decides to do it anyway.

Should I commit the scaffolding files?

The Mautic Composer Scaffold plugin can download the scaffold files (like index.php, .htaccess, …) to the public/ directory of your project. If you have not customized those files you could choose to not check them into your version control system (e.g. git). If that is the case for your project it might be convenient to automatically run the mautic-scaffold plugin after every install or update of your project. You can achieve that by registering @composer mautic:scaffold as post-install and post-update command in your composer.json:

"scripts": {
"post-install-cmd": [
"@composer mautic:scaffold",
"..."
],
"post-update-cmd": [
"@composer mautic:scaffold",
"..."
]
},

How can I apply patches to downloaded plugins?

If you need to apply patches (depending on the project being modified, a pull request is often a better solution), you can do so with the composer-patches plugin.

To add a patch to Mautic plugin foobar insert the patches section in the extra section of composer.json:

"extra": {
"patches": {
"mautic/foobar": {
"Patch description": "URL or local path to patch"
}
}
}

How do I specify a PHP version?

This project supports PHP 7.4 as the minimum version, however, it’s possible that a composer update will upgrade some package that will then require PHP 7+ or 8+.

To prevent this you can add this code to specify the PHP version you want to use in the config section of composer.json:

"config": {
"sort-packages": true,
"platform": {
"php": "7.4"
}
},

Proposed tiers for triaging pull requests

We propose a tier-based approach to categorising pull requests (PRs) in the Mautic Community. This would allow the Product Team to establish clear governance approaches to how PRs will be dealt with and what the criteria will be for merging.

These changes will allow the processing of minor fixes and improvements more rapidly, while time-boxing community testing for major pull requests, enabling the Product Team to make decisions on whether to merge new features once those time periods have passed.

Tier 1

Small changes such as typo fixing, bug fixes, translation changes, minor UI improvements or minor enhancements. Most simple bug fixes are probably going to be in Tier 1.

Examples

https://github.com/mautic/mautic/pull/8393 (simple bug fix with very few changes)

https://github.com/mautic/mautic/pull/8116/files (very simple bug fix)

Requirements for merging a Tier 1 PR

• Thorough testing to ensure that it does what it’s expected to do and does not break anything else
• Full unit testing coverage
• Code review from 1 core team member
• Full testing and approval by at least one community member (could be the person doing the code review, but should not be from the same company/organisation as the person submitting the PR).

  As an example: If an employee or contractor from Company A were to submit a PR, the community testing/approval must come from someone outside Company A’s influence (e.g. not an employee, contractor etc of Company A)

Tier 2

Minor features or enhancements which do not significantly change any part of Mautic.

More complex bug fixes are also probably going to be in Tier 2, as well as PRs that are related to external services (e.g. Salesforce/HubSpot) for which accounts need to be created in order to test.

Examples

https://github.com/mautic/mautic/pull/6090 (new feature, fairly simple and doesn’t significantly change any major part of Mautic)

https://github.com/mautic/mautic/pull/7432/ (a lot of new code which extends an existing feature, enhancing reports with a scheduling option)

Requirements for merging a Tier 2 PR

• Thorough testing to ensure that it does what it’s expected to do and does not break anything else
• Full unit/functional test coverage
• Full documentation support if it’s a feature change/addition
• Code review from 1 core team member
• Full testing and approval by at least one community member (could be the person doing the code review, but should not be from the same company/organisation as the person submitting the PR as mentioned above)

Tier 3

Major changes touching multiple parts of Mautic, completely changing the way some aspect of the code works, or large amounts of code changed.

Examples

https://github.com/mautic/mautic/pull/6875 (complex code changes across multiple areas, with significant impact)

https://github.com/mautic/mautic/pull/6584 (not too complex but a large visual change in the UI with the potential to cause significant disruption to the end user)

Requirements for merging a Tier 3 PR

• Thorough testing to ensure that it does what it’s expected to do and does not break anything else
• Thorough testing across the whole product
• Full unit/functional test coverage
• Full documentation support
• Code review from 1-2 core team members
• Full testing and approval by at least two community members (could be the people doing the review, but should not be from the same company/organisation as the person submitting the PR as mentioned above)
• 2 week community review period – after which Product Team decides via a vote in the next available team meeting whether to merge (assuming code review and all other requirements are in place to permit merging)

Note: Tier 3 PRs which relate to new features that impact users of Mautic should be linked to in an individual forum thread at forum.mautic.org/c/ideas and discussed on the forums. This gives the non-technical user base an opportunity to be involved in the discussions on new features.

If a thread doesn’t exist prior to the PR being submitted (a feature created without the community suggesting it, for example), it should be created during triage when a Tier 3 & Feature label is added.

The Github URL should be shared in a single line on the forum thread (enables the ‘onebox’ to be created) which will create a reciprocal link on the Github PR.

Proposed tiers for triaging issues

At present there is no documented issue triaging process, and labels are not organised in a structured way. We propose addressing both as part of this process.

To bring issues in line with PRs, we propose adopting the same tiered approach, so that the same label set can be used for issues. We are establishing a triage team, who will be responsible for daily/weekly/monthly and quarterly review processes.

Tier 1 issues

Minor issues which are non-critical in nature.

Examples

https://github.com/mautic/mautic/issues/8974 – an issue with translations

https://github.com/mautic/mautic/issues/8986 – checkbox in the wrong place

Tier 2 issues

Issues which are more complex and/or which may impact a large volume of users.

Examples

https://github.com/mautic/mautic/issues/8621 – impacts all Sparkpost users

https://github.com/mautic/mautic/issues/7062 – appears often but not always when multiple forms are added on a single page, making it tricky to reproduce

Tier 3 issues

Complex issues which impact multiple areas of Mautic or which require extensive debugging to identify/resolve.

Examples

https://github.com/mautic/mautic/issues/9072 – will likely touch many areas and is complex to solve, requiring in-depth technical knowledge of PHPUnit

https://github.com/mautic/mautic/issues/7032 – took a lot of time to confirm the issue and find a proper solution without breaking other things

Labels

We currently have quite a lot of labels which aren’t being used in a consistent way and have little organisation.

We propose cleaning up the labels to make it easier to understand triaging workflows.

It should be possible to group the labels using colours and/or prefixes to make it easier to work with.

Complexity-based labels

• Tier 1-2-3 [T1, T2, T3] (for PR’s and issues)

Semantic versioning related labels

• BC Break
• Deprecation
• Essential (required to close the milestone)

Type-based labels

• Bug
• New feature
• Enhancement
• Dependencies (used by Dependabot)
• Regression

Status-based labels

• Needs triage

• Rebase needed
• WIP
• Requires automated tests
• Requires documentation
• Requires code review
• Pending feedback
• Pending code changes
• Has conflicts
• Ready to test (PR’s only, and only applied when the PR is passing tests, has no conflicts, has automated tests written and is mergeable)
• Pending test confirmation (PR’s only, and only applied when the PR is passing tests, has no conflicts, has automated tests written and is mergeable)
• Ready to commit (PR’s only, and only applied when the PR is passing tests, has no conflicts, has automated tests written, has the required signoff/approvals and is mergeable)

Area affected labels (which part of the product does this affect?)

• Assets
• Builders (email and LP)
• Calendar
• Campaigns
• Categories
• Channels
• Companies
• Configuration
• Contacts
• Dashboard
• Dynamic Content
• Editor
• Email
• File Uploader
• Focus Items
• Forms
• Import Export
• Installation
• Integrations
• Landing Pages
• Notifications
• Plugin
• Points/Scoring
• Queue
• Reports
• Roles
• Segments
• SMS
• Social Monitoring
• Stages
• Tags
• Tracking
• Translations
• User Interface
• User Experience
• Webhooks
• Widgets

Some points of clarification:

Core team: individuals selected by the Project Lead with technical ability to manage and maintain the core of Mautic – includes Release Leaders, Core Committers, Maintainers (see mautic.org/about/governance ). Currently listed here.

Product team: members of the Mautic Product Team. They may also be part of the Core Team, but not necessarily. Currently listed here .

Triage Team: members of the Mautic Product Team who are responsible for triaging issues and PR’s. They may also be part of the Core Team, but not necessarily. Currently listed here .

Code review and testing: must not be done by the author of the PR.

Closing stale pull requests: If the PR is pending feedback or inactive for over 30 days, the Product Team may decide to close the PR.

Closing stale issues: If the issue is pending feedback or inactive for over 14 days, the Product Team may decide to close the issue.

While the core team is hard at work getting Mautic 3.0 production-ready, we are looking for a Community Release Leader for Mautic 2.16.1. This release will only contain bug fixes for the 2.16 branch, so it’s going to be a relatively small release.

I’m interested, what do I need to do as a Community Release Leader?

The Mautic team has created a Community Release Leader document, which describes exactly, step by step, what you’ll be doing to work towards the 2.16.1 release. You can interact with the Product team on Slack (#t-product channel) to ask questions and to share your progress. 

If you’re interested, please feel free to drop a message in the #t-product channel! Ideally we’re looking for someone who is willing to contribute on a more regular basis, but if you just have time for the 2.16.1 release, that’s fine too

Looking forward to meeting you soon,

The Mautic Team

In this guide we will show you how to set up a local development environment for Mautic, using DDEV.

Installing Docker and DDEV

Before we can get started you will need to install Docker and Docker Compose. You can find documentation on how to correctly do this here.

Once those are installed we can continue with installing DDEV. You can find installation instructions for Linux, MacOS and Windows here.

Installing Mautic

Clone the Mautic repository into a folder of your choice. Once that is done make sure to install the Composer dependencies with composer install.

Starting DDEV and configuring Mautic

Use the command line and navigate to the root of your Mautic installation. Once there, run 

ddev config

It will ask you for a project name – you can leave it at the default, or give it a custom name. This is really up to you. For the purposes of this example, we will name this project mautic.

Next it will ask for the docroot of the project.

Since the index.php of Mautic is located in the root folder of the project, we can just go with the default value. Simply press enter.

After this it will ask for the project type. Enter php and hit enter again.

Everything should now be configured. We just need to change one more thing! Go to .ddev/config.yaml and you’ll find something similar to:

APIVersion: v1.13.1
name: demodir
type: php
docroot: ""
php_version: "7.3"
webserver_type: nginx-fpm
router_http_port: "80"
router_https_port: "443"
xdebug_enabled: false
additional_hostnames: []
additional_fqdns: []
nfs_mount_enabled: false
provider: default
use_dns_when_possible: true
timezone: ""

… change the webserver type to the following:

webserver_type: apache-fpm

… add the following row (make sure to replace 7.3 with whichever PHP version you’re using!):

webimage_extra_packages: [php7.3-imap]

… and change the timezone to whichever timezone you’re in, for example:

timezone: "Europe/Amsterdam"

… you’ll have the following config.yaml file then:

APIVersion: v1.13.1
name: mautic
type: php
docroot: ""
php_version: "7.3"
webserver_type: apache-cgi
router_http_port: "80"
router_https_port: "443"
xdebug_enabled: false
additional_hostnames: []
additional_fqdns: []
nfs_mount_enabled: false
provider: default
use_dns_when_possible: true
timezone: "Europe/Amsterdam"
webimage_extra_packages: [php7.3-imap]

Note: if you have Apache2 or nginx installed, and they are currently using port 80, ensure that you shut them down or change their ports before starting the DDEV instance. If you do not follow this step, starting will fail with an error message telling you that port 80 is already in use.

You can start DDEV by running 

ddev start 

on the command line. 

If this is your first DDEV instance this can take a bit of time to initialise, as it will need to pull all the containers. 

If you cloned Mautic from GitHub, you need to run composer install in order to get started. Run

ddev ssh
composer install

… and you should be good to go.

Once started you will find your project at mautic.ddev.site (in case you used a different project name it will be yourprojectname.ddev.site).

Navigating there in the browser should bring up the Mautic installation. Make sure that during the installation you use the following settings:

• Database port: 3306
• Database host: db
• Database name: db
• Database user: db
• Database password: db

You can now finish the installation process. Your local Mautic instance should be up and running!

To stop the containers, simply run 

ddev stop 

on the command line.

Opening Mautic’s development environment (index_dev.php)

Mautic has a development environment (index_dev.php) which shows a profiler toolbar at the bottom, shows more error details, and caches less (so you have to clear your cache less often). 

The only downside is that the development environment is designed to work on localhost only. Since DDEV uses Docker, which has a slightly different networking stack, we need to make a small change in the code to get index_dev.php to work on DDEV.

Open app/middlewares/Dev/IpRestrictMiddleware.php and replace this code snippet:

    /**
     * This check prevents access to debug front controllers
     * that are deployed by accident to production servers.
     *
     * {@inheritdoc}
     */
    public function handle(Request $request, $type = self::MASTER_REQUEST, $catch = true)
    {
        if (in_array($request->getClientIp(), $this->allowedIps)) {
            return $this->app->handle($request, $type, $catch);
        }

        return new Response('You are not allowed to access this file.', 403);
    }

… with this one:

/**
     * This check prevents access to debug front controllers
     * that are deployed by accident to production servers.
     *
     * {@inheritdoc}
     */
    public function handle(Request $request, $type = self::MASTER_REQUEST, $catch = true)
    {
        return $this->app->handle($request, $type, $catch);
    }

 That way, we bypass the IP restriction middleware (otherwise you’ll get an error “You are not allowed to access this file” when trying to access index_dev.php).

Now you should be able to open index_dev.php in your DDEV environment

Running Mautic CLI commands in DDEV

You can run Mautic CLI commands (like clearing cache) as follows:

ddev ssh

Then you can run CLI commands, for example:

bin/console cache:clear --env=dev
bin/console mautic:campaigns:update
etc.

Using MailHog to catch emails in DDEV

(update: MailHog is no longer available as an option)

Run

ddev describe

And it’ll show you the following at the bottom (example):

Other Services
--------------
MailHog:        http://mautic.ddev.site:8025
phpMyAdmin:     http://mautic.ddev.site:8036

You can use MailHog to catch all emails sent by Mautic (without having to use an SMTP server). In your Mautic email configuration, go to Email Settings and select “Other SMTP server”, then enter “localhost” and use port 1025. All emails will end up in MailHog.

 

Further useful DDEV tips and tricks

Here you can find some other useful things you might need later along the way.

SSH into the container

To SSH in to the web container, simply use 

ddev ssh 

on the command line. 

If you wish to directly execute a command inside the container without going in with ssh first you can use 

ddev exec yourcommandhere

Using Xdebug

You can use 

ddev exec enable_xdebug

and 

ddev exec disable_xdebug

respectively to turn Xdebug on and off.

Changing PHP versions

Navigate to .ddev/config.yaml and edit the parameter called php_version. Once that is saved, run 

ddev restart

Using additional PHP modules

Once DDEV has been set up, you can find its configuration in the .ddev folder. 

If you need an extra PHP modules enabled such as IMAP for example, you can add it doing the following:

Navigate to .ddev/config.yaml and find the following row:

webimage_extra_packages: [php7.3-imap]

So, if you want to add the php-imap package, you would add the package as above. You can add additional packages by comma-separating them. 

Now save this file and restart your DDEV instance by running 

ddev restart

Using PHPMyAdmin

A DDEV instance comes with PHPMyAdmin by default. To find out the location of the PHPMyAdmin instance of the current project, use 

ddev describe

This will give you a lot of information about your containers, including the URL to the PHPMyAdmin instance.

Running PHPUNIT tests

In Mautic 5, you need to create .env.test.local file that will configure the test environment. Here is the content of this file:

# .env.test.local
DB_HOST=db
DB_PORT=3306
DB_NAME=test
DB_USER=db
DB_PASSWD=db
MAUTIC_DB_PREFIX=
MAUTIC_TABLE_PREFIX=
MAUTIC_ENV=test
MAUTIC_ADMIN_USERNAME=admin
MAUTIC_ADMIN_PASSWORD=Maut1cR0cks!

Make sure that the database with name “test” exists. You can add a prefix if you want.

Then run the tests with:

composer test

or if you want to run a specific test then you can filter for it:

composer test -- --filter specificTest

Recently I decided to do a little digging into Mautic’s contributor logs to see who was doing big things when it comes to Mautic’s marketing automation code. I also wanted to compare how we compared 2016 to 2017 since we’re fast approaching the end of 2017. It seems hard to believe that we’re almost ready to close the book on another year!

I thought the best thing to do would be to look at a variety of stats first comparing different metrics between last year and this year. One thing that I believe is very important to mention at the beginning before we start looking at specific numbers is how much of Mautic community growth can NOT be measured by a number or a specific number of lines of code. The following metrics simply report on one aspect of the overall community and should in no wise be considered indicative of the community as a whole (good or bad). The code aspect is merely one facet of our community.

Number of Developers

The number of developers contributing code to Mautic can be viewed in several different ways so I’ll share a few of them and let you draw your own conclusions.

This first graph shows the growth of developers and reviewers over the past two years. As you can see we have a steady increase in the number of “contributors” over the past 24 months. This time period covers Mautic versions 1.2 through 2.11 and does not include the month of December of this year, 2017. There are significantly more reviewers than developers but this is expected and both are still considered contributors as Mautic requires reviews to be done before a pull request can be merged. The Mautic company is identified by the dark grey in the chart as well. You can see that although proportionally Mautic the company (MCO) contributes the greatest number of developers than other companies there are increasingly more and more months developers and reviewers from the community.

There is an important side note that should be considered when reviewing the number of contributors and the relationship between MCO engineers and community developers. The amount of code contributed by MCO engineers comprises approximately 82%. This means that although the number of developers in the community is increasing MCO is still the largest single contributor by a significant amount.

But just to give a bit more recognition I’d like to share a specific list of the top 20 individuals who have contributed code to Mautic in the past year. This list isn’t exhaustive; there are many more (as the stats above demonstrate). But these individuals deserve a special specific callout for their work. Here is a list of the top 20 individuals and the number of lines of code they have contributed to Mautic.

• • alanhartless*, 91179
  • escopecz*, 55362
  • dongilbert*, 39954
  • mqueme*, 33581
  • stollz, 22008
  • virlatinus*, 20850
  • GaberNeighbor*, 12113
  • Maxell92*, 10950
  • kuzmany, 6768
  • thecodeine, 5525
  • drmmr763*, 5287
  • npracht, 3783
  • MarkLL, 2541
  • mikegillis677, 2309

• Woeler, 1546
• shulard, 1439
• jordan8037310, 964
• isleshocky77, 750
• lightweight, 678
• Dreiser*, 634

But code contribution is more than just lines of code. (I’ll be the first to suggest that the number of lines of code may be a terrible metric for judging activity…more on that later). So here is a second list. This list recognizes the top 20 individuals and the number of merged pull requests to the Mautic code. Again, they each deserve recognition for their contributions.

• alanhartless*, 628
• escopecz*, 390
• mqueme*, 150
• dongilbert*, 98
• kuzmany, 83
• virlatinus*, 76
• mbabker*, 37
• MaxWebmecanik*, 27
• drmmr763*, 23
• Dcoutelle, 18
• isleshocky77, 16
• arulrajsm28, 12
• phil-davis, 11
• shulard, 11
• SamWebmecanik, 11
• chandon, 10
• jordan8037310, 9
• Woeler, 9
• npracht, 9

Comments & Pull Requests

The second chart I would like to share with you is in relation to the overall comments and pull requests that the Mautic codebase has received over the previous 24 months.

This chart highlights the pull requests (in red) and the comments (in blue) as they have occurred since January 2016. Here again we see a gradual increase in contributions (trend lines added). As you would expect the amount of discussion surrounding code contributions increases over time and there is a gradual increase in the number of pull requests submitted as well. Peaks typically correspond with the various release dates of the Mautic code.

Code Comment Growth

The next chart demonstrates a comparison between comments on code between last year and this year (again keeping in mind that this year we are not showing data from the month of December).

I share this chart because it signifies the engagement aspect from the community. Again, comments and involvement increases around release times as you would expect, but the overall trend line demonstrates increased discussion occurring around the code over time.

Of course all of these charts above are specifically related to the pull requests submitted and as a result there is a significant portion of the contributor engagement that is not represented by these charts. The reason for this lies in the feature request section of GitHub. Feature requests are ideas generated by the community for future consideration within Mautic. Because they are not associated with a specific pull request they do not show in the above stats.

Current Code Status

Let’s now take a look at our current GitHub status and repositories and draw some conclusions about where we have come and where we are going to go from here. This is also a chance to identify ways we need to improve processes and new areas of focus for 2018.

Currently in GitHub there are 726 issues and 103 pull requests. Breaking the issues down further we have the following stats:

• 321 issues marked as Bugs
• 308 issues marked as Feature Requests
• 171 issues marked as Backlog
• 98 issues not labeled
• 20 issues marked as Pending Feedback

There are several conclusions we can draw from this. First, because we use GitHub for our bugs and feature tracking there is a slight skewing of perception when viewing the open issues on Mautic. Instead of there being almost 730 “bugs” in Mautic code, it is better to view this list with the appropriate filter applied. When you do this you’ll find that the relationship of bugs to pull requests is much closer to a reasonable ratio with 1 pull request existing for every 3 bugs.

The second item that is a problem for Mautic is the 98 issues that are currently unlabeled. This means someone has written up an issue but it has not been reviewed by anyone with appropriate permissions for applying a label. This is a problem. There are two possible explanations. Either we don’t have enough active community members monitoring the GitHub repositories to mark new issues with the appropriate labels or we don’t have enough community members with the knowledge to apply the appropriate labels and therefore they don’t add them.

Side Note: There’s also the problem presented by GitHub repositories and permissions that allow or disallow access to label creation and application of those labels. This is something Mautic has not yet solved successfully.

In the future we need to educate community members on reading and assigning labels to issues so that they can be correctly categorize as they are created. We also need to determine the number of community volunteers actively monitoring GitHub repositories. One of the first ways we can determine this number is by looking at the number of reviewers we saw in the charts earlier. This number gives a suitable estimates of those contributors capable of responding to issues and therefore also capable of attaching labels to issues.

There are several advantages to correctly categorizing issues. With proper categorization we can more readily identify which bugs need to be resolved first and which are feature requests instead of actual bugs. This will increase productivity from the developers writing pull requests as well as clarify public understanding of the project’s status.

Lastly, from the list of issue stats we can see that there are a significant amount of feature requests. We can draw a conclusion or two from this metric as well. Feature requests can mean the software is not completely fulfilling everyone’s ideal marketing solution (though this is a more delicate issue as Mautic should never attempt to be all things for all people). More importantly the relationship between number of feature requests submitted and number of pull requests submitted suggests that the community is made up of more end-users (marketers) or implementer types of users rather than coders or developers. In fact, when we take this ratio and compare it to the downloads from Mautic.org of the software we find a fairly similar breakdown of user types. This means the assumption we draw from the feature request submissions is accurate.

Understanding the make-up of our community when it comes to the Mautic code helps us to continue making improvements and growing. I hope that as you have read through this you’ve been able to get a better understanding of how I look at things and what the different metrics you might see or hear actually mean. Once we have a shared understanding of how to look at the Mautic codebase we will have a greater opportunity for moving faster.

Have you ever wondered if you could track more than just visits via the Mautic tracking script? I know I did, and in this article I will show you how we can use URL’s to track anything you want.

The Basics

Before we start let’s have a look at these two URL examples. This one is without extra parameter:

https://mydomain.com/page/test/

And here we have the same URL with an extra parameter:

https://mydomain.com/page/test/?email=johndoe@company.com

If you use for example MailChimp or CampaignMonitor to send out marketing emails, consider using this technique. Simply add the email address as a parameter at the end of the URL.

In php one can catch this parameter simply with a:

$email = $_GET[‘email’];

And then proceed to use that parameter for processing. However, there is also a clever way of using the Mautic Javascript to track visitors on your site. Only some slight modifications can make it send off any lead field you want to Mautic.

Get Tracking with Mautic

Here is the default script:

<script>
    (function(w,d,t,u,n,a,m){w&#91;'MauticTrackingObject']=n;
        w&#91;n]=w&#91;n]||function(){(w&#91;n].q=w&#91;n].q||&#91;]).push(arguments)},a=d.createElement(t),
        m=d.getElementsByTagName(t)&#91;0];a.async=1;a.src=u;m.parentNode.insertBefore(a,m)
    })(window,document,'script','https://mydomain.com/mtc.js','mt');

    mt('send', 'pageview');
</script>

In short, what this does is simply pass along the identification parameters such as IP address and device fingerprint, together with the page the user is visiting. Now have a look at the script below.

<script>
	function getUrlParameter(name) {
		name = name.replace(/[[]/, '\[').replace(/[]]/, '\]');
		var regex = new RegExp('[\?&]' + name + '=([^&#]*)');
		var results = regex.exec(location.search);
		return results === null ? '' : decodeURIComponent(results[1].replace(/+/g, ' '));
	};
	
    (function(w,d,t,u,n,a,m){w['MauticTrackingObject']=n;
        w[n]=w[n]||function(){(w[n].q=w[n].q||[]).push(arguments)},a=d.createElement(t),
        m=d.getElementsByTagName(t)[0];a.async=1;a.src=u;m.parentNode.insertBefore(a,m)
    })(window,document,'script','https://domain.com/mtc.js','mt');

	var email  = getUrlParameter('e');

	if(email !== ''){
		mt('send', 'pageview', {email: email});
	} else {
		mt('send', 'pageview');
	}
</script>

The first function is used to extract a custom parameter from the URL. You can use this function for any parameter you want. Just make sure to pass the correct name to the function. In our case the name is ‘email’.

Below that you can see the default part of the Mautic tracking script. This is not relevant for us. It does what it needs to do, no need to concern us with that for now. Below that you will see a new variable is created with the name ‘email’ and the value it will get is the URL parameter for ‘email’. This means that this variable will hold the content of the URL that comes after ‘?email=’, which should be the email address of the user.

Then we have a short if-statement. This statement simply checks if the email parameter is filled or not. If it is not (which is the case for people that visit your website without a newsletter link) it will simply pass along the usual parameters. But if the email parameter is present it will pass along the usual parameters together with the email address.

Sending a Custom Parameter

You can send this along by adding ‘{email: email}’ to the mt method. Keep in mind that the first string identifies the field you want to pass along. In this case we want to pass along the email, but this could also be any other field like firstname or lastname, or even a custom field you have created. The second string or value is the actual value that needs to be passed along. Since we put the value we got from the URL in the ‘email’ parameter we just write ‘email’ to indicated that we want to pass along the string inside this value.

Lastly, make sure you enable public updating for the fields you want to track using this method. If public updating is not enabled Mautic will simply drop the field. You can do this by going to the ‘Custom fields’ section, then selecting the field you want and changing ‘publicly updatable’ from ‘no’ to ‘yes’.

Congratulations! You can now track custom parameters on your website!

The Possibilities Are Endless

Using the Mautic tracking script this way opens up new ways to identify your contacts. Think about the contact points you have and how you can use them to track different data sets.

If you are using mailing tools like Mailchimp or CampaignMonitor it is super easy to add the add extra parameters to your newsletters. Simply append the extra parameter to all the URL’s in your mail and there you go! In fact, you can use any contact network on point you have and use this methods for the parameters at hand.

Security

We should not forget that we are still handing personal data here. If you are appending sensitive data to a URL make sure you think about handling the data safely. What you could do is hash the parameters and de-hash them in your website before you send them off to Mautic. This way anyone who might come across the link cannot read or use the parameters.

Also make sure to use https, also known as SSL if possible. This is simply an extra layer of security added to the request the user will make. Best practice is to use both SSL for your website as well as the connection between your website and Mautic. You will see in the examples above the I have used https in the code, and not http.

And there you go. Now you know how to track custom parameters with the Mautic tracking script. I cannot wait to see what creative ways you all come up with to use this!