====== Development of phpList using docker ======

This page describes how to set up a development environment to work on the phpList core code, the phpList plugins and/or the phpList themes.

The system will use docker, which is expected to be set up and working. This page is not to help with setting up docker.


===== Setup =====
 
Clone the repository https://github.com/phplist/phplist-docker somewhere on your machine

===== Config =====

Edit the file **.env** in the folder where you checked it out, or create a new one from the example that is in the repository.


The README in the repository explains how to set up a working phpList with an empty database. However, here we do not use that, we use a pre-populated database instead.

Therefore not all options in the .env file apply for the development environment setup.

The ones we need are

   PORT=8000
   HOSTNAME=localhost
   THEME_DEV_PATH=/home/yourhome/Projects/phpListThemes
   CODE_PATH=/home/yourhome/Projects/phpList3/public_html/
   PLUGIN_DEV_PATH=/home/yourhome/Projects/phpListPlugins



Explanation of the above config variables:

**PORT**
the PORT where you will be loading phpList

**HOSTNAME**
the hostname to connect to 

**THEME DEV PATH** 
The location on your local machine where you are working on the themes for phpList. You should checkout all the themes as sub-folders in this location. For example:


   /home/yourhome/Projects/phpListThemes
   /home/yourhome/Projects/phpListThemes/dressprow
   /home/yourhome/Projects/phpListThemes/phplist-ui-bootlist
   /home/yourhome/Projects/phpListThemes/phplist-ui-funkytheme


**CODE PATH**
The location on your local machine where you have your clone of the phpList3 code checked out. As you can tell, it should point to the public_html folder in the phpList repository.


**PLUGIN DEV PATH**
The location on your local machine where you have the plugin repositories checked out. Similar to the themes, this needs to be one main folder that has the plugins checked out as sub-folders, for example

   /home/yourhome/Projects/phpListPlugins
   /home/yourhome/Projects/phpListPlugins/phplist-plugin-common
   /home/yourhome/Projects/phpListPlugins/phplist-plugin-segment
   /home/yourhome/Projects/phpListPlugins/phplist-plugin-viewbrowser
   /home/yourhome/Projects/phpListPlugins/phplist-plugin-develop
   /home/yourhome/Projects/phpListPlugins/phplist-plugin-restapi
   /home/yourhome/Projects/phpListPlugins/phplist-plugin-ckeditor
   /home/yourhome/Projects/phpListPlugins/phplist-plugin-dateplaceholder
   /home/yourhome/Projects/phpListPlugins/phplist-plugin-domainthrottlemap
   /home/yourhome/Projects/phpListPlugins/phplist-plugin-rssfeed
   /home/yourhome/Projects/phpListPlugins/phplist-plugin-smtpbalancer
   /home/yourhome/Projects/phpListPlugins/phplist-plugin-subjectLinePlaceholdersPlugin


You can checkout the root of the plugins here, so the full structure would be:

   /home/yourhome/Projects/phpListPlugins
   /home/yourhome/Projects/phpListPlugins/phplist-plugin-common
   /home/yourhome/Projects/phpListPlugins/phplist-plugin-common/plugins
   /home/yourhome/Projects/phpListPlugins/phplist-plugin-common/plugins/Common
   /home/yourhome/Projects/phpListPlugins/phplist-plugin-common/plugins/CommonPlugin
   /home/yourhome/Projects/phpListPlugins/phplist-plugin-segment
   /home/yourhome/Projects/phpListPlugins/phplist-plugin-segment/plugins
   /home/yourhome/Projects/phpListPlugins/phplist-plugin-segment/plugins/SegmentPlugin
   
   etc
   

**Please note**: you need to have at least the phpList core code checked out. The themes and plugins are optional, but without at least one theme, it will be difficult to work with it. If you check out one theme, it will be used, if you check out more, you will be able to switch themes in the settings page.


===== Start and Stop =====

Once you have it set up and configured, you can run

   ./start-phplist.sh 

to start phpList. After a little while, it will be available on http://localhost:8000 if you keep the above example.

The data will be a sanitised dataset with a nice amount of data in a lot of places, which should help with development.

The login for the dev system is "admin" with password "phplist".

The Queue processing will be automatic, and all emails are sent to the mailhost container. 
   
To stop the system, run

    ./stop-phplist.sh

and the containers will be removed.