Mautic Introduction
Supported Versions
Please note that the release dates indicated with * below are estimations, no rights can be derived from them., Branch, Beta Release, Initial Release, Active Support Until, Security Support Until, --, --, --, --, --, 2.15, 27 Sep 2019, 8 Oct 2019, 8 Oct 2019, 8 Oct 2019, 2.16, 30 Jan 2020*, 13 Feb 2020*, 13 Feb 2020, June 2020? (TBD)**, 3.0, 27 Jan 2020*, 3 Feb 2020*, TBD, TBD
** = Security Support for 2.16 will only be provided for Mautic itself, not for core dependencies that are EOL like Symfony 2.8.
Getting Started
The GitHub version is recommended for development or testing. Production package ready for install with all the libraries is at https://www.mautic.org/download.
Documentation on how to use Mautic is available at https://www.mautic.org/docs.
This is a simple 3 step installation process. You'll want to make sure you already have Composer available on your computer as this is a development release and you'll need to use Composer to download the vendor packages.
Get stuck? No problem. Check out general troubleshooting and if it won't solve your issue join us at the Mautic community for help and answers.
Disclaimer
Installing from source is only recommended if you are comfortable using the command line. You'll be required to use various CLI commands to get Mautic working and to keep it working. If the source and/or database schema gets out of sync with Mautic's releases, the release updater may not work and will require manual updates. For production the pre-packaged Mautic available at mautic.org/download is recommended.
Also note that the source outside a tagged release should be considered "alpha" and may contain bugs, cause unexpected results, data corruption or loss, and is not recommended for use in a production environment. Use at your own risk.
Requirements
Contributor Agreement
By contributing to this project, you accept and agree to the Contributor Agreement in its entirety.
Development / Build process requirements
- Mautic uses Git as a version control system. Download and install git for your OS from https://git-scm.com/.
- Install a server, PHP and MySql to be able to run Mautic locally. Easy option is _AMP package for your OS.
- Install Composer, the dependency manager for PHP.
- Install NPM.
- Install Grunt.
Mautic requirements
- See Mautic requirements.
- PHP modules:
- required:
zip, xml, mcrypt, imap, mailparse
- recommended:
openssl, opcache / apcu / memcached
- recommended for development:
xdebug
- Recommended memory limit: minimally 256 MB for testing, 512 MB and more for production.
- Recommended MySQL defaults can be set by running the queries
SET GLOBAL innodb_default_row_format=DYNAMIC; SET GLOBAL sql_mode=(SELECT REPLACE(@@sql_mode,'ONLY_FULL_GROUP_BY',''));
Installation
- Open a Terminal/Console window.
- Change directory to the server root (i.e.
cd /var/www if your local server root is at /var/www).
- Clone the repository (
git clone https://github.com/mautic/mautic.git)
- The mautic directory should appear in the server root. Change directory to mautic directory (
cd mautic).
- Install dependencies (
composer install).
- Visit Mautic in a browser (probably at http://localhost/mautic) and follow installation steps.
Keeping Up-To-Date
Source Files
Each time you update Mautic's source after the initial setup/installation via a new checkout, download, git pull, etc; you will need to clear the cache. To do so, run the following command:
$ cd /your/mautic/directory
$ php app/console cache:clear
(Note that if you are accessing Mautic through the dev environment (via index_dev.php), you would need to add the --env=dev from the command).
Vendors
Run composer install to ensure new vendors are installed and/or existing upgraded.
Database Schema
Before running these commands, please make a backup of your database.
If updating from a tagged release to a tagged release, schema changes will be included in a migrations file. To apply the changes, run
$ php app/console doctrine:migrations:migrate
If you are updating to the latest source (remember this is alpha), first run
$ php app/console doctrine:schema:update --dump-sql
This will list out the queries Doctrine wants to execute in order to get the schema up-to-date (no queries are actually executed). Review the queries to ensure there is nothing detrimental to your data. If you have doubts about a query, submit an issue here and we'll verify it.
If you're satisfied with the queries, execute them with
$ php app/console doctrine:schema:update --force
Your schema should now be up-to-date with the source.
Development environment
Mautic downloaded from GitHub has the development environment. You can access it by adding index_dev.php after the Mautic URL. Eg. http://localhost/mautic/index_dev.php/s/. Or in case of CLI commands, add --env=dev attribute to it.
This development environment will display the PHP errors, warnings and notices directly as the output so you don't have to open the log to see them. It will also load for example translations without cache, so every change you make will be visible without clearing it. The only changes which require clearing the cache are in the config.php files.
In case of assets like JS, CSS, the source files are loaded instead of concatenated, minified files. This way the changes in those files will be directly visible on refresh. If you'd wanted to see the change in the production environment, you'd have to have run the app/console mautic:assets:generate command.
In many cases, the CSS files are built from LESS files. To compile the changes in the LESS files, run grunt compile-less command.
Testing
Pull Request Testing
Everyone can test submitted features and bug fixes. No programming skills are required. All you have to do is to follow the steps below.
Every change to Mautic core happens via PRs. Every PR must have 2 successful tests to be merged to the core and released in the next version. Testing a PR is a great way to move Mautic forward and personally improve its quality and stability.
- Select a PR to test.
- Read the description and steps to test. If it's a bug fix, follow the steps to ensure you can recreate the issue.
- Use the development environment (above) for testing.
- Apply the PR
- Clear cache for development environment (
rm -rf app/cache/* or app/console cache:clear -e dev).
- Follow the steps from the PR description again to see if the result is as described.
- Write a comment about how the test went. If there is a problem, provide as much information as possible including error log messages.
Automated Testing
Mautic uses Codeception, PHPUnit, and Selenium
as our suite of testing tools.
PHPUnit
Before executing unit tests, copy the .env.dist file to .env then update to reflect your local environment
configuration.
Running functional tests without setting the .env file with a different database will result in the configured database being overwritten.
To run the entire test suite:
bin/phpunit --bootstrap vendor/autoload.php --configuration app/phpunit.xml.dist
To run tests for a specific bundle:
bin/phpunit --bootstrap vendor/autoload.php --configuration app/phpunit.xml.dist --filter EmailBundle
To run a specific test:
bin/phpunit --bootstrap vendor/autoload.php --configuration app/phpunit.xml.dist --filter "/::testVariantEmailWeightsAreAppropriateForMultipleContacts( .*)?$/" Mautic\EmailBundle\Tests\EmailModelTest app/bundles/EmailBundle/Tests/Model/EmailModelTest.php
Codeception/Selenium
If you plan on running the acceptance test suite, you'll need to have the Selenium Server Standalone installed and the
Chrome WebDriver available locally.
Mac OS
If you're on a Mac and you use Homebrew, you can install Selenium by running brew install selenium-server-standalone.
You'll also need to download the latest Chrome WebDriver.
Unzip and move the chromedriver file to /usr/local/Cellar/selenium-server-standalone/drivers/chromedriver.
Once you have Selenium installed and the WebDriver available at the specified location, open and modify the plist file found at /usr/local/Cellar/selenium-server-standalone/3.5.3/homebrew.mxcl.selenium-server-standalone.plist.
In the <dict><array> block under ProgramArguments, add the following after the line containing <string>-jar</string>"
...
<string>-Dwebdriver.chrome.driver=/usr/local/Cellar/selenium-server-standalone/drivers/chromedriver</string>
...
With that completed, you may now start the Selenium server using brew services start selenium-server-standalone.
Follow the standard installation procedure for Selenium server standalone. Ensure that you have the chrome driver
available, and startup the server with the following command:
java -jar -Dwebdriver.chrome.driver=/path/to/chromedriver /full/path/to/selenium-server-standalone.3.x.x.jar
Executing Tests
All test suites can be executed by running bin/codecept run from the project root. Optionally, you can specify
running just the acceptance, functional, or unit test suites by adding one of those words after the run command.
Static Analysis
Mautic uses PHPSTAN for some of its parts during continuous integration tests. If you want to test your specific contribution locally, install PHPSTAN globally with composer global require phpstan/phpstan-shim. Mautic cannot have PHPSTAN as its dev dependency, because it requires PHP7+. To run analysis on a specific bundle, run ~/.composer/vendor/phpstan/phpstan-shim/phpstan.phar analyse app/bundles/*Bundle
Marketing automation has historically been a difficult tool to implement in a business. The Mautic community is a rich environment for you to learn from others and share your knowledge as well. Open source means more than open code. Open source is providing equality for all and a chance to improve. If you have questions then the Mautic community can help provide the answers.
Ready to get started with the community? You can get more involved on the Mautic website. Or follow Mautic on social media just to stay current with what's happening!
Developers
We love testing our user interface on as many platforms as possible (even those browsers we prefer to not mention). In order to help us do this we use and recommend BrowserStack.
