Development environment 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>
ServerName devel.localdev.phplist.com 
DocumentRoot /home/.path-to-code./phplist/public_html
SetEnv ConfigFile /home/you/configdev.php 
</VirtualHost>

• ServerName devel.localdev.phplist.com

[ANYTHING].localdev.phplist.com always resolves to 127.0.0.1, 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.

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:

public_html/lists/admin/ui/

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';

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

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 = 'you@yourdomain.com';
  /* 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;

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:

/lists/admin/?page=initialise&firstinstall=1

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.