
Back when i first attempted to get phplist working with cPanel it took a ridiculous amount of time and i realized that a couple more hours spent writing some instructions would be nothing if it saved people the hours i'd wasted. Since then i've configured phplist painlessly on quite a few different webhosts and i hope this guide (periodically updated and collected from many, many other posts on the subject) helps make things that little bit easier for you all.
This howto does not cover general installation of phplist, instead it focuses on configuring cpanel to tell phplist to process large numbers of users in scheduled batches.
If you only have a couple of hundred or so email addresses you might want to configure phplist to deliver to all of them in one run when you click on 'Process Queue' rather than go thru the effort of setting up Cron as described here.

First we need to set $commandline_users to disabled. Ftp into your webspace and navigate to the phplist directory. Once inside that enter the config directory and download config.php. Now open the file in a text editor and look for a line similar to the one below. Make sure the line is uncommented (no preceding '#') and that it looks exactly like the text shown below:
- Code: Select all
$commandline_users = array();
Note the lack of words/characters inside the array() brackets. The above line disables a feature that checks to see whether the 'server user' is authorized to control phplist. Due to us not invoking the $commandline_users feature you shouldn't have to add username and password parameters to the cron line (as discussed later).
If you haven't already you will also need to edit some of the other parameters in config.php such as user details and batch size. Most of these options should be easy enough to work out from the documentation, however one important thing to get right here is the MAILQUEUE_BATCH_SIZE. Your webhost likely imposes a limit on the number of emails you can send (typically per hour). You will need to check with your host to find out what that maximum number is; anywhere between 400 and 1000 emails per hour is common. If you have a subscriber list that's the size of a small town you may want to inquire as to whether they can increase it or as a last resort find an alternative host. Once you know your limit set your batch size to just less than your sending limit. You will also need to set MAILQUEUE_BATCH_PERIOD to whatever the timeframe is. This is set in seconds so a value of 3600 would equal one hour.
Once your all done ftp the file back up to your web space in place of the original.

Next we will need to tell Cron to process the queue every hour. In your cpanel select the Cron icon and choose the 'Standard' experience level option. In the 'Command to run:' textbox stick the following text (it's all one line) but change *CPANELUSERNAME* and *PHPLISTDIR* to your own):
- Code: Select all
/usr/local/bin/php /home/*CPANELUSERNAME*/public_html/*PHPLISTDIR*/admin/index.php -p processqueue
Note: In some scenarios *CPANELUSERNAME* may be your domain name (ie: '/home/joebloggs.com/...' rather than '/home/joebloggs/...')
You will also need to select the regularity you want Cron to run at. Typically if your MAILQUEUE_BATCH_PERIOD value is set to 3600 (1 hour) then you will want to set Cron to run every hour, of each day & month.
For testing I recommend setting it to a frequency of 'every other minute' of every hour, day & month to test with. This means it will be attempting to send emails (ie: process the queue) every two minutes.
Now in the phplist admin click on 'Send a message' and create a basic mailout. Save it, select the 'List' tab in messages, select the 'test' list (make sure your email address is signed up to it) and click on 'Send to selected mailinglists'. Do NOT press 'Process queue' afterwards. It's Cron's job to automatically start the process queue routine for you based on the instructions you entered above. The 'test' list was present by default with my phplist installation however if no such list is present you will want to create one yourself.
Assuming you set it up correctly Cron should send you an error/confirmation email each time it is set to run (receiving any Cron emails, even errors, is good news as it means the Cron part is working).
Once you have phplist successfully sending mailouts you will want add: " > /dev/null" to the end of the line to stop it from sending all those confirmation mails and flooding your inbox. The final output looks like this:
- Code: Select all
/usr/local/bin/php /home/*CPANELUSERNAME*/public_html/*PHPLISTDIR*/admin/index.php -p processqueue > /dev/null
You will also want to revert Cron from sending messages every 2 minutes and set it to the equivalent of MAILQUEUE_BATCH_PERIOD as described above.
Hopefully you should now have everything working however if your still not up and running read on....

If you are receiving emails with error messages from cron try entering the text (or part thereof) in the forum search to get a better idea of the problem and (usually) find a fix to the issue.
If you are receiving some sort of email from Cron, but it is not sending the newsletter to anyone try tweaking the Cron command text. Have a look at some other forum posts on this issue and try any alternative command strings people are using. Some people might find that lengthening their string to add the path to config.php helps:
- Code: Select all
/usr/local/bin/php /home/*CPANELUSERNAME*/public_html/*PHPLISTDIR*/admin/index.php -pprocessqueue -c/home/*CPANELUSERNAME*/public_html/*PHPLISTDIR*/config/config.php
Another is to change the path to php from:
- Code: Select all
/usr/local/bin/php [...]
to
- Code: Select all
/usr/bin/php [...]
or, whatever directory your webhost has it setup as (use phpinfo() to find out).
http://uk.php.net/phpinfo
If you only seem to be sending a limited number of emails, or your account is being locked out, or it works sometimes and other times not then remember that your webhost is probably imposing a limit on the number of emails you can send and this may be affecting phplist's sending abilities.
For some hosts it seems that you may need to use $commandline_users = array(USERNAME) rather than $commandline_users = array();
You will also need to change the cron line adding login=USERNAME password=PASSWORD as below
- Code: Select all
/usr/local/bin/php /home/*CPANELUSERNAME*/public_html/*PHPLISTDIR*/admin/index.php -pprocessqueue login=USERNAME password=PASSWORD -c/home/*CPANELUSERNAME*/public_html/*PHPLISTDIR*/config/config.php
In the above situatiuons USERNAME (not CPANELUSERNAME) is specifed in phplist's README.commandline as the UNIX user. This would suggest that USERNAME should, in my interpretation, be the same as your cPanel user (the *CPANELUSERAME*). A later post in this thread however suggests they had success using the USERNAME (and assocaited PASSWORD) of the phplist admin.
http://forums.phplist.com/viewtopic.php?f=6&t=11712&start=45#p74433
This is a confusing matter that i have not gotten to the bottom of in over 3 years as most every installation i have done works fine without setting $commandline_users = array(USERNAME). If anyone can shed some light on what parameters should be given, and under what circumstances they are needed then please chip in.
Lastly it's also worth mentioning that your host will need to have the command line version of php enabled (php comes in two versions: command line and cgi). While the large majority of webhosts do supply a command line version if you encounter problems you should always contact them to check.
If your host does not have the command line version of php installed there are other ways of triggering the Process Queue through Cron. A great howto on how to do this can be found here...
http://forums.phplist.com/viewtopic.php?t=15148
Thanks for reading and if you have any additions or corrections post them below and I'll update this first post. Cheers.
Ps. More info here....
http://forums.phplist.com/viewtopic.php?f=16&t=9856
http://docs.phplist.com/CronJobExamples