User Tools

Site Tools

Translations of this page:


Note: It is recommended to use Docker for setting up your development environment instead. This is the officially supported method. See the docker setup guide.

Development environment setup

Local setup

These steps explain how to run phpList from the latest code on your local machine, for development.

We expect you to have a machine that runs Apache with mod_php and Mysql. Feel free to add instructions for other setups.


For apache add a virtual host on your machine

<VirtualHost *.80>
DocumentRoot /home/.path-to-code./phplist/public_html
SetEnv ConfigFile /home/you/configdev.php 


  • ServerName
    [ANYTHING] always resolves to, so it points back to your own machine. This does require you to be online, so if you want to work offline, you can use any other hostname and put it in your hosts file to point back to your machine.
  • DocumentRoot
    Point this to where you put the code from SVN. You will want the Apache Document root to be the “public_html” folder from the phpList repository.
  • SetEnv ConfigFile /home/you/configdev.php
    it is useful to keep your local development config outside of the coderoot.

Themes / web interface

phpLists' themes each have their own code repository, much like plugins. phpList does not ship with a theme by default. You need to download a theme before you can use the phpList web interface.

The standard phpList is Dressprow. Clone the theme from the official repository into your theme directory, which is:


You can install other themes also into that folder, or make your own.

To configure phpList to use a particular theme, set the following value in phpList's config.php file (change the theme from 'phplist-ui-dressprow' as desired):

$ui = 'phplist-ui-dressprow';

Campaign editor / WYSIWYG

To enable a graphical editor for HTML campaigns, you need to install an editor plugin. For example you may install the CKEditor plugin to enable that editor for composing and reviewing campaign content.


Create a database for phpList, or use an existing one. You can probably use phpMyAdmin to create something, or just do

mysqladmin -uroot -prootpassword create phplistdb
mysql  -uroot -prootpassword -e "grant all on phplistdb.* to phplist@localhost identified by 'dbpass'"

If you want to kickstart your system with some data, you can download this database dump.

Fill your database with the following command

gunzip -c phplist-devdb.sql.gz | mysql -uphplist -pdbpass phplistdb

phpList database configuration

Where you pointed the VirtualHost to look for the phpList config, create the file (in the above example, /home/you/configdev.php)

Minimum requirements for the config file are:

  $database_name = "phplistdb";
  $database_host = "localhost";
  $database_user = "phplist";
  $database_password = "dbpass";
  $developer_email = '';
  /* Uncomment the line below if you are using database dump above. */
  //$table_prefix = "phplist_";

It will be best to try to run everything without any PHP errors (including notices) showing up. To get errors in a nice way, you should consider installing XDebug. On debian type systems run apt-get install php5-xdebug.

In order for the errors to actually show, use this in your config file:

$GLOBALS['show_dev_errors'] = true;

Reinstalling / reinitialising the database

If a new database is used with an existing phpList server you will need to reinitialise the database to install the phpList tables again. The following errors will appear until you do this:

Database error 1146 while doing query Table 'database_name.phplist_config' doesn't exist

You can reinitialise a new database by visiting the following URL at any time:


Working with custom plugins

Once you have the basics running, there are a few options that facilitate developing plugins.

PLUGIN_ROOTDIR = "plugins";

If you set the above, phpList will use the plugins folder in the admin directory to install plugins. You will need to make this webserver-writable in order to be able to use the auto-installer.

However, you will want to be able to create your own plugins. In order to tell phpList about the code location of your local plugins, you can use

PLUGIN_ROOTDIRS = "/path/to/your/github/coderoot;/some/other/path";

and phpList will look in /path/to/your/github/coderoot and /some/other/path for additional plugins.

Make sure to follow the plugin directory structure and activate your plugin, using the plugins page.

develop/developmentsetup.txt · Last modified: 2017/07/14 15:39 by samtuke

Contact Us


Boring Bit

phpList is a registered limited company

UK Company No. 07582966

VAT Registration 122 0788 37

© phpList 2016