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.

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

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.

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.