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 additional installation instructions, 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.
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.
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!
This mod is required to support British English only. Over the years, users have contributed translations for different languages. Currently Czech, French, Italian, Mandarin, Spanish and Swedish translations are available. However, translations often run many versions behind the current version. Those contributing language translations will not necessarily provide updates when a new version of phpBB Digests is released.
In addition, new language variables are often introduced with new versions of phpBB Digests, and sometimes language variables are removed. In addition, sometimes text within a language changes between version. In addition, some translators provide language changes for the user only, which some also provide languages changes for the Administration Control Panel.
For all languages, you need to copy the language email templates for British English into the email folder of your language. These particular files are actually language independent, so no translation is needed. For example, to copy the email templates into the French language folder:
The safest approach is to :
If you have a non-British English language translation for the Administration Control Panel, make changes for your language equivalent to the changes shown in the install.xml file. These file changes would be made to:
A common problem is that boards in the United States will use language en_us. British English (en) will be installed automatically. For these situations, copy relevant files into /language/en_us and make languages changes in the install.xml file, except make them to /language/en_us instead of /language/en.
You may need to purge your cache and refresh your templates to see the changes.
If you make a translation, please donate it by sending it to mark@phpbbservices.com so others do not have to go through the same exercise. Newest translations show up in the next version of digests and are often published to the phpBB Services support forum as well.
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 (mark@phpbbservices.com) 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.
I am logged out. What happened? Is this a bug?
This will happen while you test the program using a browser. Why? mail_digests.php works in a phpBB environment, which means it creates a phpBB session so it can use phpBB's functions. The program ends by cleaning up loose ends, like logging itself out and thus ending its session. However, when testing from your browser and running mail_digests.php, phpBB can tell if you are logged in by comparing a session cookie in your browser with a list of sessions in phpBB and will use that. Hence you get logged out because your session cookie will expire. Once it is all automated, this won't happen. Instead, it will create a guest session and use that.
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.
You may be wondering why you need to set up a cron job at all given that phpBB comes with cron.php. The reason it is necessary is that for lightly trafficked boards, cron.php is not guaranteed to be executed once an hour. If cron.php were called, users could potentially receive digests at an hour later than requested.
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 their control panel. You may have to hunt for it.
This example shows how it might be programmed using the Plesk Control Panel. Your cron tool may may look different. First, look for a Crontab or similar tool in your control panel. In Plesk it looks like an alarm clock.
Select the crontab tool and find the link that allows you to create a new crontab task. Here is an example using Plesk. 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 look at your web host's knowledge base or if it is not there file a support ticket with your web host. 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 annoying very quickly. 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 (*) in the picture 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/phpBB3/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 30 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/';
Setting up a cron job manually using SSH
If you have no cron tool in your control panel, but you do have SSH (secure shell), 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://www.example.com/phpBB3/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 find the above too complex or frustrating, there is another solution. Use a site monitoring service.
A site monitoring service is an internet company 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 mail_digests.php 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 6 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
The URLs embedded in the emailed digests are for a different domain than where my forum is hosted. The URLs points to my web host where my site is in some deeply nested folder!
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. You will need to know information about both the old and new database (they can be the same database). The tools is considered "beta" quality so there may be bugs. However, the utility provided works only with MySQL databases. phpBB 2.x to phpBB 3.x User Digest Settings Migration Tool for MySQL.
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 > General 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.