PHPlist Tutorial and Installation How To

This tutorial describes how to use the PHPlist mailing list and customer relationship management software with your Nexcess web hosting account. Nexcess specializes in hosting PHPlist software and this tutorial is meant to help you quickly setup your site with our web hosting service.

PHPlist is open source, meaning that you can use and distribute it as you'd like as long as you don't change it.

For the sake of this tutorial we'll assume that you own the domain 'johnsmith.com' and are setting up PHPlist at http://johnsmith.com/phplist/.

Follow these steps to complete the tutorial:

The first thing to do is to run through the SiteWorx MySQL tutorial and create a database for PHPlist to use to store the information it needs.
Create a database called 'phplist' with a user named 'phplist'. When you do this SiteWorx will prefix the database and user names with some text resembling your domain name.
With our example domain of 'johnsmith.com' the database name is 'johnsmit_phplist' and the username is the same 'johnsmit_phplist'.
Download the latest version of PHPlist from the PHPlist website and unzip the contents of the zip file to your desktop using http://winzip.com.
You should now have a folder which contains all the files and folders you need to install and run PHPlist. Rename the 'phplist-2.8.5/public_html/lists' folder to 'phplist'. You need to edit some files to change their settings. Open the 'phplist/config/config.php' file. You need to change the following values using the information for the database you created in step #1:
- $database_host = "localhost"; - Stays the same.
- $database_name = "johnsmit_phplist";
- $database_user = "johnsmit_phplist";
- $database_password = 'mypassword';
Your screen should look like this:

Scroll down the page until you see the line that says '$pageroot = '/lists';'. You need to change this to '$pageroot = '/phplist';' so the script can find the right directory. Your screen should look like this:

Save and close the 'config.php' file.
Upload the 'phplist' folder to your web hosting account. You can do this using an FTP program. If you don't know how to do this, check out the FTP tutorial on our tutorials page.
Once the PHPlist files and folders are finished uploading you can access the admin page.
For this example, we'll point to 'http://www.johnsmith.com/phplist/admin'. You should now be on the first admin page. You should see an error saying that you haven't initialized your database yet. Your screen should look like this:

Click on the 'initialize database' link to continue. The script will create tables in your database. If you receive any errors, make sure you entered the correct information for your database in the 'config.php' file. Your screen should look like this:

Click on the 'phplist setup' link at the bottom to continue. You should now be on the PHPlist admin login page. Enter 'admin' for the username and 'phplist' as the password. Your screen should look like this:

Click on the 'Enter' button to login. You should now see the checklist for setting up this script. Your screen should look like this:

Click on the 'go there' link for the 'Change Admin Password' section. Enter your e-mail address and enter a new password. Your screen should look like this:

Click on the 'Save Changes' button to save the new password. Your changes should be saved. Click on the 'Configure' link to access the checklist. You should now see that you have 2 out of 6 steps complete now. Your screen should look like this:

Click on the 'go there' link for the 'Configure General Values' section. You should now see all the general settings. You can change these according to your preferences. For this example, we'll leave them set as the defaults. Your screen should look like this:

If you decide to change the values, once you're finished, click on the 'Configure' link at the top of the page to go back to the checklist. Click on the link next to the 'Configure Attributes' section. The attributes are the fields that people need to fill out when they sign up for your mailing list. For this example, we'll create one called 'E-mail Address' with a default value of 'home@company.com' and make this a required field. Your screen should look like this:

Click on the 'Save Changes' button to create this attribute. The page will refresh and show you the attribute you just created. Click on the 'Configure' link at the top to go back to the checklist. You should now have two steps left. Click on the link next to the 'Create Lists' section. You should see a test list that has been created. For this example, we'll use the test list. Your screen should look like this:

Click the 'Active' checkbox to make this list active. Click on the 'Save Changes' button to continue. The script will save your list. Click on the 'Configure' link to go back to the checklist. You should now have one more step to go. Click on the last link. You should now be on the main page for creating subscribe pages. Your screen should look like this:

Click on the 'add a new one' link to make a subscribe page. You should now be on the page for creating subscribe pages. Your screen should look like this:

Fill out this page according to your preference. Check the 'Use this attribute' box for the e-mail address attribute you created at the bottom. Check the 'test list' checkbox to select this list. Your screen should look like this:

Click on the 'Save and Activate' button to create a subscribe page. The script will now take you back to the admin control panel. Your screen should look like this:

Your installation is finished and the PHPlist tutorial is now complete.
For more information on how to use PHPlist once it's installed, check out the PHPlist Support Page.