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

As training for the Rio Olympics  gets underway, we see the immense work that is done by these athletes in preparation for the games. In a similar manner, each of us works hard to compete in today’s business world. We plan, organize, implement and deploy new ideas. Although our environment may not be an open stadium, it is certainly an open marketplace. And unlike the real Olympics where only a single person is rewarded with a medal, everyone wins when you contribute to an open source project like Mautic.

Who can participate?

According to Olympic records, Cecilia Colledge was the youngest female competitor in the Olympics. She was only 11YO.  The oldest to ever compete? Arthur von Pongracz of Austria, who was 72. We’d like to approach the Mautic Summer Games in a same manner. We believe everyone has worth and value. That you can contribute and participate to this community in some way shape or form. So we’re excited to open up the competition to developers/creators/designers of all ages.

What are the events?

In preparation for the Mautic Summer Games we wanted to give you a rundown of all the different events that we will be offering. Regardless of your skill level or expertise, everyone should be able to participate.

UPDATED: Scoring for events

When do the Mautic Summer Games start/end?

Our Summer Games will run the entire month of August. So as you’re watching the Rio Olympics take some time to contribute to an international phenomenon that is disrupting an entire industry. When you participate in these summer games, you also add value to others.

What’s in it for me?

Our undying gratitude! ? Aside from the knowledge that you receive by helping people move horizons, there will be prizes! Be on the lookout for more detail on mautic.org as we design our scoring system and determine the prizes. Also keep in mind there will be prizes for country participation! Do you have colleagues that are willing and able to participate? Invite them to join in on the games!

By holding this fun-filled event, we hope to show the world that an inspired community, gathered around a common ideal, can change the way we communicate. And that given the proper tools and inspiration, we can create an open space where creative ideas can be  shared and horizons can be moved.

UPDATE: Summer Games Prizes

We’ve created our very own Mautic Summer Games swag bags! Proudly display your contribution to Mautic as you collect points to contribute to one of the fastest growing open source projects in the world. There will be a different set of swag for gold, silver and bronze, so do your best!

UPDATE: Rules of the Games

We’d like to request that all content produced or developed be done during the timing of the games (the month of August). Please no recycling of content that has already been created. We encourage everyone who is participating do use creativity and innovation when applying their talents to each of these events.

The business is an interesting collection of talented individuals. They’re comprised of educators, strategists, programmers, artists, designers and more. The variety of talent gives them an advantage over their competition. But more importantly, their collaboration creates innovative solutions for their clients.

The solutions they produce are highly visual in nature. These large images help communicate strategy so that employees can understand the “big picture”. Associates can then have a dialogue with their peers about important, strategic issues. The visuals unlock understanding, that words so often, can not.

The Team

The outcome of these engagements were often riddled with “a-ha” moments. They are moments when an employee would stop and say “I get it!”. The visuals provided a much clearer picture than a presentation filled with bullet points. But the visual isn’t born out of thin air. It takes a close partnership between the business strategist and the creative artist.

The development of these visuals always begins with the problem. It starts with the team sitting down with the client and listening to the challenges they face. Each team member hears the problem from their own point of view. These unique perspectives add immense value to the solution. In today’s marketplace, the collaboration between marketing and software development teams will become invaluable. This partnership can spark innovation and will be more powerful when they work together. And as marketing continues to move online, development must have a seat at the table. They will play a vital role in growing the customer relationship.

The Collaboration

This partnership between the artist and the strategist is important. Even though their views are different, the goal of engaging associates is the same. Likewise, the collaboration between technology and marketing is critical. These two functions have operated in silos. They are focused on their own goals, without consideration for the other.

The collaboration between marketing and software development will become invaluable and more powerful when they work together.

The collective reset button needs pressed. Teams should tear down their silos and realign on the purpose and goals set out by the organization. What is that purpose and goal? Creating seamless user experiences that add value at every stage of the customer relationship. Media buyers used to operate in lock step with marketing, and many still do today. They work together to understand how customers buy products. But communication channels are changing. Digital is now how we reach and connect with our audiences. Many organizations must work to help teams come out of the dark ages. They must forge bridges of awareness and understanding.

The Approach

So what approach do we take when aligning marketing and development? Marketing automation is a perfect place to start. These two teams must converge to meet today’s customer demands. Just like the artist and the strategist, aligning around the common goal is where we start. People would always wonder how an artist and strategist could work together. With a common goal, these two different views always produced incredible results.

Let’s take a moment to reflect on the roles of marketing and software development. Although unique, they are two sides of the same coin. How does this collaboration work effectively?

• Listening: Strong developers and designers always begin by listening. Both these roles need a thorough understanding of the problem. This understanding is important before thinking through the problem and crafting the solution.
• Design: Any approach to solving a problem requires a big picture view. This view reveals all the elements that may impact the desired solution. Trusted marketers understand the entire customer experience and likewise, trusted developers are focused on creating structure and order in their code.
• Focus: Good marketing and design requires simplicity. There should be one single theme or idea. Great developers create beautiful code that works well with as little “extra” fluff as possible. This focus removes clutter and aligns our efforts.
• Vision: One of the most important elements that developers and marketers exhibit is vision. Marketing should take into account customer buying trends and consider feedback from their audience. Developers should also look ahead. Potential problems should be identified and resolved before they become an issue.

This approach, combined with a common goal, will create more meaningful value. And at the end of the day, that is what we want for our customers.

Marketing automation is becoming a more integrated way to do business in the digital age. It’s clear that these two roles not only have common ground, but approach their work in a similar way.

We are excited about the community of Mauticians that represent both marketing and development. It has, and will continue to, provide us with the ability to meet the needs of organizations around the world. It is in this special collaboration that we can provide tools to help you reach, engage and develop relationships with your audience.