Main -> 5.x

.github/styles/Vocab/Mautic/accept.txt

@@ -22,6 +22,7 @@ CCPA
 Citrix
 Clearbit
 CloudAMQP
+Codecov
 config
 Config
 Company(ies)

.readthedocs.yaml

@@ -6,6 +6,6 @@ sphinx:
 
 # Explicitly set the version of Python and its requirements
 python:
-  version: 3.7
+  version: 3.8
   install:
     - requirements: docs/requirements.txt

docs/_static/theme.css

@@ -1,4 +1,4 @@
-.wy-side-nav-search, .wy-nav-side {
+.wy-side-nav-search, .wy-nav-side, .wy-nav-top {
     background-color: #4e5e9e;
 }
 

docs/development-environment/environments.rst

@@ -0,0 +1,83 @@
+Environments
+############
+
+:xref:`Symfony 4 environment conventions`
+
+In all environments, Mautic loads the following files if they exist,
+the latter taking precedence over the former:
+
+* ``.env``                contains default values for the environment variables needed by the app
+* ``.env.local``          uncommitted file with local overrides
+* ``.env.$APP_ENV``       committed environment-specific defaults
+* ``.env.$APP_ENV.local`` uncommitted environment-specific overrides
+
+Real environment variables win over ``.env`` files.
+
+.. warning:: Don't define secrets in this file, or any other committed files. Set secrets via environment variables, or through other secret management tools.
+
+Run ``composer dump-env prod`` to compile .env files for production use (``requires symfony/flex >=1.2``). Read more about 
+:xref:`Symfony 4 best practices environment variables`.
+
+By default the structure come with 3 environments
+``.env``
+``.env.test``
+``.env.test.local``
+
+Mautic loads default values filled in the ``app/config/parameters.php`` file at installation.
+These values can be overridden by the ``.env`` structure.
+
+Development environment
+=======================
+``.env`` come with two values:
+
+.. code-block:: bash
+
+    APP_ENV=prod
+    APP_DEBUG=0
+
+It's recommended to create the ``.env.local`` file. This file overrides the values in ``.env`` file.
+Example:
+
+.. code-block:: bash
+
+    APP_ENV=dev
+    APP_DEBUG=1
+    DB_HOST=...
+    DB_PORT=3306
+    DB_NAME=...
+    DB_USER=...
+    DB_PASSWD=...
+    MAUTIC_DB_PREFIX=...
+    MAUTIC_TABLE_PREFIX=...
+
+Test environment
+================
+
+In the test environment there are two files.
+
+The first one is the default file ``.env.test`` that includes credentials used to create a test instance of Mautic.
+
+.. code-block:: bash
+
+    DB_HOST=127.0.0.1
+    DB_PORT=3306
+    DB_NAME=mautictest
+    DB_USER=root
+    DB_PASSWD=
+    MAUTIC_DB_PREFIX=test_
+    MAUTIC_TABLE_PREFIX=test_
+    MAUTIC_ENV=test
+    MAUTIC_ADMIN_USERNAME=admin
+    MAUTIC_ADMIN_PASSWORD=mautic
+
+The second one, ``.env.test.local`` includes values for the DDEV local development environment, overriding the ``.env.test`` values.
+It's recommended making any changes to this file with its values.
+
+.. code-block:: bash
+
+    DB_HOST=db
+    DB_USER=db
+    DB_PASSWD=db
+    DB_NAME=test
+    ...
+    MAUTIC_DB_PREFIX=...

docs/development-environment/getting_started.rst

@@ -0,0 +1,11 @@
+Development environment
+#######################
+
+Introduction
+============
+Mautic is a system based on the :xref:`Symfony framework` and :xref:`Doctrine`.
+
+Mautic uses the :xref:`Symfony framework` as a foundation for the app. 
+
+It follows the :xref:`Symfony coding standards` and :xref:`Symfony best practices`.
+

docs/development-environment/how_to_install_with_ddev.rst

@@ -0,0 +1,37 @@
+How to install Mautic with DDEV
+###############################
+
+.. note:: 
+    If you get stuck, join the lively Mautic Community on :xref:`Mautic Slack` or the :xref:`Developer Forum` for support and answers. **Please first post in the forum**, then share the link in Slack, so others can learn from your question.
+
+Pre-requisites with DDEV
+========================
+1. You should have DDEV and Docker or Colima installed on your machine. If not, please follow the instructions here: :xref:`ddev install`
+
+Installing Mautic is a two-step process:
+========================================
+1. Clone this repository
+
+.. code-block:: bash
+
+    git clone https://github.com/mautic/mautic.git
+
+.. Note:: Clone the repository in the directory where you want to install Mautic.
+
+1. Install Mautic running DDEV.
+
+.. code-block:: bash
+
+    cd mautic
+    ddev start
+
+.. list-table:: Users and passwords
+    :header-rows: 1
+
+    * - Username
+      - Password
+    * - ``admin``
+      - ``mautic``
+    * - ``sales``
+      - ``mautic``
+

docs/development-environment/setup.rst

@@ -0,0 +1,42 @@
+How to install Mautic manually
+##############################
+
+Pre-requisites to setup
+=======================
+
+Mautic assumed that the system already has ``composer`` and ``git`` installed and configured.
+
+.. note:: 
+    If you get stuck, join the lively Mautic Community on :xref:`Mautic Slack` or the :xref:`Developer Forum` for support and answers. **Please first post in the forum**, then share the link in Slack, so others can learn from your question.
+
+Steps
+=====
+1. To setup the developer environment, fork and clone the source from GitHub as outlined in :doc:`/development-environment/how_to_install_with_ddev`. 
+2. Run ``composer install`` on the source.
+3. Open your browser and complete the installation through the Mautic installer.
+
+You can also run the install process from command line:
+
+* Add a ``local.php`` file in ``app/config``
+* Edit the ``local.php`` file using the following template (Mautic adapts to new local settings):
+
+.. code-block:: php
+
+    <?php
+        $parameters = array(
+            'db_driver' => 'pdo_mysql',
+            'db_host' => 'localhost',
+            'db_table_prefix' => null,
+            'db_port' => '3306',
+            'db_name' => 'mautic',
+            'db_user' => 'root',
+            'db_password' => 'root_password',
+            'db_backup_tables' => true,
+            'db_backup_prefix' => 'bak_',
+    );
+
+* Run the following command and add your own options:
+
+.. code-block:: bash
+
+    php bin/console mautic:install https://mautic.example.com

docs/index.rst

@@ -3,6 +3,16 @@ Welcome to Mautic's developer documentation
 
 This is a work in progress. More to come soon. In the meantime, go to :xref:`Legacy Developer Docs` to view the developer documentation.
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Development Environment
+   :hidden:
+
+   development-environment/getting_started
+   development-environment/how_to_install_with_ddev
+   development-environment/setup
+   development-environment/environments
+
 .. toctree::
    :maxdepth: 2
    :caption: Themes
@@ -56,6 +66,7 @@ This is a work in progress. More to come soon. In the meantime, go to :xref:`Leg
    plugins/installation
    plugins/data
    plugins/translations
+   plugins/continuous-integration
 
 .. toctree::
    :maxdepth: 2
@@ -95,6 +106,7 @@ This is a work in progress. More to come soon. In the meantime, go to :xref:`Leg
    rest_api/categories
    rest_api/contacts
    rest_api/fields
+   rest_api/notifications
    rest_api/reports
    rest_api/text_messages
 

docs/links/codecov.py

@@ -0,0 +1,7 @@
+from . import link
+
+link_name = "codecov" 
+link_text = "Codecov" 
+link_url = "https://about.codecov.io" 
+
+link.xref_links.update({link_name: (link_text, link_url)})

docs/links/codecov_gh_app.py

@@ -0,0 +1,7 @@
+from . import link
+
+link_name = "codecov_gh_app" 
+link_text = "Codecov GitHub App" 
+link_url = "https://github.com/apps/codecov" 
+
+link.xref_links.update({link_name: (link_text, link_url)})

docs/links/composer.py

@@ -0,0 +1,7 @@
+from . import link
+
+link_name = "composer" 
+link_text = "Composer" 
+link_url = "https://getcomposer.org" 
+
+link.xref_links.update({link_name: (link_text, link_url)})

docs/links/ddev_install.py

@@ -0,0 +1,7 @@
+from . import link
+
+link_name = "ddev install" 
+link_text = "Install DDEV" 
+link_url = "https://ddev.readthedocs.io/en/stable/#installation" 
+
+link.xref_links.update({link_name: (link_text, link_url)})

docs/links/doctrine.py

@@ -0,0 +1,7 @@
+from . import link
+
+link_name = "Doctrine" 
+link_text = "Doctrine" 
+link_url = "https://www.doctrine-project.org/" 
+
+link.xref_links.update({link_name: (link_text, link_url)})

docs/links/hello_world_plugin.py

@@ -0,0 +1,7 @@
+from . import link
+
+link_name = "hello_world_plugin" 
+link_text = "Hello World Plugin" 
+link_url = "https://github.com/mautic/plugin-helloworld" 
+
+link.xref_links.update({link_name: (link_text, link_url)})

docs/links/mautic_dev_forum.py

@@ -0,0 +1,7 @@
+from . import link
+
+link_name = "Developer Forum" 
+link_text = "Developer Forum" 
+link_url = "https://forum.mautic.org/c/development" 
+
+link.xref_links.update({link_name: (link_text, link_url)})

docs/links/mautic_github.py

@@ -0,0 +1,7 @@
+from . import link
+
+link_name = "Mautic's GitHub Repo" 
+link_text = "Mautic's GitHub repository" 
+link_url = "https://github.com/mautic/mautic" 
+
+link.xref_links.update({link_name: (link_text, link_url)})

docs/links/mautic_slack.py

@@ -0,0 +1,7 @@
+from . import link
+
+link_name = "Mautic Slack" 
+link_text = "Slack" 
+link_url = "https://mau.tc/slack-invite" 
+
+link.xref_links.update({link_name: (link_text, link_url)})

docs/links/php_cs_fixer.py

@@ -0,0 +1,7 @@
+from . import link
+
+link_name = "php_cs_fixer" 
+link_text = "PHP CS Fixer" 
+link_url = "https://github.com/PHP-CS-Fixer/PHP-CS-Fixer" 
+
+link.xref_links.update({link_name: (link_text, link_url)})

docs/links/phpstan.py

@@ -0,0 +1,7 @@
+from . import link
+
+link_name = "phpstan" 
+link_text = "PHPStan" 
+link_url = "https://phpstan.org" 
+
+link.xref_links.update({link_name: (link_text, link_url)})

docs/links/phpunit.py

@@ -0,0 +1,7 @@
+from . import link
+
+link_name = "phpunit" 
+link_text = "PHPUnit" 
+link_url = "https://phpunit.de" 
+
+link.xref_links.update({link_name: (link_text, link_url)})

docs/links/rector.py

@@ -0,0 +1,7 @@
+from . import link
+
+link_name = "rector" 
+link_text = "Rector" 
+link_url = "https://getrector.com" 
+
+link.xref_links.update({link_name: (link_text, link_url)})

docs/links/symfony_best_practices.py

@@ -0,0 +1,7 @@
+from . import link
+
+link_name = "Symfony best practices" 
+link_text = "Symfony best practices" 
+link_url = "https://symfony.com/doc/current/best_practices.html" 
+
+link.xref_links.update({link_name: (link_text, link_url)})

docs/links/symfony_coding_standards.py

@@ -0,0 +1,7 @@
+from . import link
+
+link_name = "Symfony coding standards" 
+link_text = "Symfony coding standards" 
+link_url = "https://symfony.com/doc/current/contributing/code/standards.html" 
+
+link.xref_links.update({link_name: (link_text, link_url)})

docs/links/symfony_docs_best_pratice_environments.py

@@ -0,0 +1,7 @@
+from . import link
+
+link_name = "Symfony 4 best practices environment variables"
+link_text = "best practices"
+link_url = "https://symfony.com/doc/current/best_practices.html#use-environment-variables-for-infrastructure-configuration"
+
+link.xref_links.update({link_name: (link_text, link_url)})

docs/links/symfony_docs_configuration_environments.py

@@ -0,0 +1,7 @@
+from . import link
+
+link_name = "Symfony 4 environment conventions"
+link_text = "Mautic follows the Symfony 4.4 environment conventions:"
+link_url = "https://symfony.com/doc/4.4/index.html" 
+
+link.xref_links.update({link_name: (link_text, link_url)})

docs/links/symfony_framework.py

@@ -0,0 +1,7 @@
+from . import link
+
+link_name = "Symfony framework" 
+link_text = "Symfony framework" 
+link_url = "https://symfony.com/" 
+
+link.xref_links.update({link_name: (link_text, link_url)})

docs/links/twig_lint.py

@@ -0,0 +1,7 @@
+from . import link
+
+link_name = "twig_lint" 
+link_text = "Twig Lint" 
+link_url = "https://symfony.com/doc/5.4/templates.html#linting-twig-templates" 
+
+link.xref_links.update({link_name: (link_text, link_url)})