Unfortunately, the install.xml file does not capture the extent of the work required for a digest installation. This is because the mod only works if the mail_digests.php program is called hourly. Currently, phpBB 3 does not have such a feature. These instructions provide the details for testing the mailing of digests and establishing a "cron" process so digests can be mailed hourly. In most cases this is straightforward but in unusual cases it could take hours or days.
The initial instructions for installing the Digest Mod for phpBB 3 can be found in the install.xml file in the top folder of the archive. I recommend that you use AutoMOD to copy the files and make these file changes, as they are complicated. If you do not have AutoMOD installed, you must first install it. Make sure you have the AutoMOD Configuration settings correct, as appropriate file permissions by AutoMOD are needed to write files.
If you use AutoMod, copy the entire archive into your phpBB store/mods folder. It should then appear as a modification to install.
If you do the file changes manually take care because it is easy to miss a file change. If you make the file changes manually, I recommend that you double check them because many admins will inadvertently leave one or more changes out and then spend much time trying to figure out why this mod isn't working correctly. In most cases, these problems can be attributed to an installation error.
Do not begin these instructions until you have completed all the instructions in the install.xml file.
UMIL (phpBB's Unified MOD Install Library) is included in this archive. It facilitates making changes to the database and installs the necessary modules in the Administration Control Panel and in the User Control Panel. You do not need to run a UMIL install program. So to complete this step, you must run the umil_digests_install.php from your phpBB root directory. Example:
http://www.example.com/phpBB3/umil_digests_install.php
After successfully running the UMIL script, make sure you can access the Digests tab in the User Control Panel and see selections for both links under the Digest Settings category under the General Tab in the Administration Control Panel.
I recommend you remove umil_digests_install.php from your phpBB root folder as it is no longer be needed.
If either by default or optionally your board supports the subsilver2 style, now is a logical time to install the style and make necessary template changes. For your convenience you can use this link. Please follow all instructions including the DIY instructions before resuming.
If your board uses neither prosilver or subsilver2 styles, you probably would like to make it work for your preferred style.
Most styles are based on either prosilver or subsilver2. To find out which your style is based on, look at the overall_header.html file in your style's template folder. If after the <body> tag you find a <div class="navbar"> the style is subsilver2 based, otherwise it is probably prosilver based.
When copying files, copy the files for the style yours is based on (prosilver or subsilver2) into your style directory.
See if the template files and template changes for that style work for your style. Style changes for prosilver are included in the install.xml file. File changes for subsilver2 can be found here. In some cases you may have to tweak the HTML embedded in the template a bit to make it match your style. If you do not have experience in HTML, consult someone with these skills, although some experimentation usually works. Keep a backup copy of the template in case you make a mistake!
We want to see if digests can be successfully sent before we automate the process. It is not unusual to find issues associated with emailing digests. As its name suggests, the mail_digests.php program actually sends emails containing the digests.
Via URL invoke the mail_digests.php program in your phpBB root folder. (Mail will be sent to you at the address in your phpBB profile.) Example URL to invoke:
http://www.example.com/phpBB3/mail_digests.php
If it worked correctly, you should get a response page in your browser similar to this:
Starting mail_digests.php at Wed Dec 03, 2008 6:39 pm
A digest was sent to Mark D Hamill (mhamilll@computer.org) containing 1 posts and 0 private messages at Wed Dec 03, 2008 6:39 pm.
Ending mail_digests.php at Wed Dec 03, 2008 6:39 pm
The summary should report that 1 digest went out to your email address.
Now to check your email inbox to see if the digest arrived. It may take some minutes (or in some cases, some hours) before the mail arrives.
mail_digests.php says no digests were sent
I get a white screen when I run mail_digests.php
mail_digests.php returns an error message
mail_digests.php says it sent me a digest, but I never received it
I cannot see my board's style applied to the text in the email digest
Now that you have verified that digests can be sent manually, it is time to automate the process. Most typically this is done by accessing your server's cron tool. Cron is a Unix/Linux/Mac operating system program that can cause jobs to begin automatically at specified times. Windows servers have a similar functionality.
Regardless of the method used, you need a way to automatically call mail_digests.php once an hour, every hour, every day of the week.
This is typically the toughest part of the digest installation. If you get too confused, you are advised to find a friend or consultant who is perhaps more tech savvy with "server stuff" and have him/her help you. If you get to the point where you are totally frustrated or your web host simply doesn't offer cron, or a cron like feature, there is an alternative: use an external web monitoring service.
This is the typical way to call mail_digests.php automatically. Most web hosts will provide a cron tool in the control panel they provide. You may have to hunt for it.
This example shows how it might be programmed using the cPanel cron tool (Advanced settings). Your cron tool may may look different. Note that the command is longer than what fits in the text box, so the full command is not shown:
Using curl to run mail_digests.php automatically
I recommend creating a cron job that uses curl. curl is a Unix utility that can call a URL, hence its name. It does lots of other things too but our need is simple. It is also almost always supplied with Unix servers. The syntax is simple:
curl <url_to_call>
So an example might be:
curl http://www.example.com/phpBB3/mail_digests.php
You can try programming your cron job to run this command. Often it work fine, so give it a try. However, you may find it won't work. In that case you need to know the absolute path on your system to curl. You can ask your web host by filing a support ticket. Sometimes the information is in the host's knowledge base. If you have access to SSH, you might be able to find it with this command:
whereis curl
or
which curl
If you don't have SSH, you can write a short PHP program that can probably tell you this information. This short script, perhaps saved as test.php, saved to and run from your phpBB root directory might tell you. This should work if PHP was compiled to allow shell scripts to be executed, which is the typical case:
<?php
$output = shell_exec('whereis curl');
echo 'The curl program is in one or more of these directories: ' . $output;
?>
The curl program is typically some place like /usr/bin or /usr/lib/bin. So the full command to program into your cron tool might be something like:
/usr/bin/curl http://www.example.com/phpBB3/mail_digests.php
One problem that may occur is that cron will want to report to you on the success and/or failure of running the cron job by shooting you an email. This is interesting at first, but an email once an hour gets old after a while. Some cron interfaces allow you to suppress emails generated by the cron. If yours does not and this happens to you, revising the command to something like this might "shut up" curl and your cron tool:
/usr/bin/curl -s -o /dev/null http://www.example.com/phpBB3/mail_digests.php
The -s option should put curl in silent mode, and using -o redirects output if there is any. If sent to /dev/null output should go into the bit bucket.
Note the asterisks (*) above. The asterisk is a wild card and means repeat for every unit. So the * under hour means run it every hour. You should program a cron job like this. You should use * in all the columns except the first (minute). You can enter 0 to kick of mail_digests.php at the top of the hour, or you can enter any number between 0 and 59 to kick it off on a different minute.
Now change your digest settings to the next hour. Once you save your changes sit back and wait to see if you get your digest in your email box shortly after the time you programmed the cron.
If it works once then it should work as long as you do not change the cron tool. You have completed cron installation.
Using wget to run mail_digests.php automatically
Note: if curl is not available or not accessible, see if wget is available on your server. The syntax will be different but the principle is the same.
Using command line PHP to run mail_digests.php automatically
Instead of curl or wget, you can also invoke PHP from a cron job directly, if you know the path to PHP. The following program might tell you the location of PHP on your system.
<?php
$output = shell_exec('whereis php');
echo 'PHP is in one or more of these directories: ' . $output;
?>
Here is an example of how the cron might be programmed:
/usr/bin/php /www/htdocs/mydomainname/phpBB/mail_digests.php
The following program, if stored in your phpBB root folder as test.php and run should give you the absolute path needed for the second argument. It may not work if safe mode is enabled for your installation of PHP. You can use the second argument for constructing your cron job, as in the example above.
<?php
$output = shell_exec('pwd');
echo 'The current directory is : ' . $output;
?>
If this approach still does not work then you may have change line 23 of mail_digests.php to show the absolute path to your phpBB root directory.
$phpbb_root_path = (defined('PHPBB_ROOT_PATH')) ? PHPBB_ROOT_PATH : './';
The result might look something like this, but will depend on what your absolute path actually is:
$phpbb_root_path = '/www/htdocs/mydomainname/phpBB3/mail_digests.php';
Setting up a cron job manually using SSH or Telnet
Real men (and women) program from the command line! If you have the right stuff or, more importantly, you have no cron tool in your control panel, but you do have SSH (secure shell) or telnet access to your server, you can program cron the old fashioned way from the Unix prompt. Here are some instructions that may work.
0 * * * * /usr/bin/curl -s -o /dev/null http://www.example.com/phpBB3/mail_digests.php
I have not installed phpBB Digests on a Windows box, but other users have. I will pass on what I have learned. Essentially you need two things:
Create a batch file (with a .bat extension) in Notepad or a similar text editor and call it from Windows Scheduled Tasks. The batch file should look something like this:
wget -q -O - http://full.url.to/mail_digests.php exit
As with Unix cron jobs, you need to program Windows Scheduled Tasks to call this batch file once an hour, every hour, every day of the week. I am not sure if Windows will retain this job if you log out or reboot your server.
After setting up Windows Scheduled Tasks, keep trying and tweaking things until it works. Wait to see if you get your digest in your email box shortly after the time you programmed the cron. Did you succeed? If so, you have completed cron installation.
If you are tearing your hair out at this point and ready to spit nails because all this is too hard to figure out and too geeky, there is another solution. Use a site monitoring service.
A site monitoring service is an internet company that provides servers that periodically polls your server to see if it is "up". It notifies you via email if the site is down, so you can complain to your web host. To check if a site is up, you have to provide a URL to check. Instead of having it check your top level page, you can have it run mail_digests.php instead. As part of checking it, it will also run the script and send out digests. So if you can get it to call your mail_digests.php program once an hour, you are home free. You will need to program the URL you used in Step 9 when prompted by the site monitoring service.
This sounds like a simple, hassle free way to go. Why am I not recommending it by default?
This Google Search should give you some site monitoring services worth checking out:
http://www.google.com/search?q=uptime+monitors+free&btnG=Search
I experimented with SiteUpTime and it seems to work well for me. I am not recommending it, but you might want to give it a try.
Regardless of the service you will have to register on the service, create an account, probably create an ID and password and then work your way through the interface. If it can't check at least hourly, don't use this service.
Now change your digest settings to the next hour. Hopefully the site monitoring service will call your program at the top of the hour. Wait to see if you get your digest in your email box shortly after the time you programmed the site monitoring service. Did it succeed? If so, you have completed cron installation.
I can get mail_digests.php to run manually, but it fails to run automatically
I am getting email every hour with lots of cryptic stuff in it. Make it stop!
I want to keep a log to troubleshoot problems. How do I do it?
I can't seem to use "vi" to edit the crontab
crontab < uploaded_file.txt
I don't see the answer to my question. What now?
If you have a phpBB 2 forum with the Digests Mod installed and you upgraded to phpBB 3 you may be able to move over your user's digest settings. The tools is considered "beta" quality so there may be bugs. However, the utility provided works only with MySQL databases. The link is in the install.xml file in the archive, near the top. Look for "Additional ModX Files", follow the link and follow the instructions.
You may want to enable some settings in the Administration Control Panel. The instructions should be self explanatory. To access:
Administration Control Panel > General > Digest Settings
You should seriously consider enabling the key parameter in the ACP. If enabled and a key parameter is passed, the parameter value of "key" will be checked. If the parameter value does not match the allowed value no digests will be processed. This can be a valuable security precaution, because otherwise any hacker or malicious user could call mail_digests.php repeatedly, causing your users to receive multiple copies of the digest in their email.
An example of using the key parameter:
http://www.example.com/phpBB3/mail_digests.php?key=goskins
Of course you would need to reprogram your cron job to pass the correct parameter. Please choose a different parameter than the one suggested that would be unique to your board.
If you have tried the phpbb.com Digests topic and still find yourself at a loss, try posting a question on my support forum.
Please read this, which contains useful information on how to be notified of new bugs or new versions of the Digests mod.
This mod was first released in 2003 for phpBB 2 by Mark D. Hamill. It has undergone numerous upgrades to improve functionality. Without a doubt though it would not be so popular without the extensive beta testing done by many users and the suggestions and feedback provided on the phpBB forums.
I hope you find this mod useful. Allowing similar users to come together online is what phpBB is all about. With the digest mod content can be pushed back to the community.
Pay Pal donations are always gratefully appreciated, but not expected. Donations can be sent to markdhamill@gmail.com.