meta data for 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.
Apache
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>
Explanation
- 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.
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:
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';
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.
Mysql
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 = '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;
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:
/lists/admin/?page=initialise&firstinstall=1
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.