Site Home

phpBB Services

Digests

Smartfeed

AJAX Shoutbox with Sounds

Support Forums New!


phpBB 3 Digest DIY (Do it Yourself) Instructions

If you want to encourage me to maintain this Digests mod, please consider sending me a small donation.

These instructions are only good for the current version of phpBB Digests for phpBB3. The current version can be downloaded from the Digests home page. If you have an earlier version they may work or they may not. As of version 2.2.3, these instructions are included in the archive!

Contents

  1. Complete the instructions in the digests_install.xml file
  2. Purge the cache
  3. Add a Digests interface to the User Control Panel
  4. Add a Digests interface to the Administration Control Panel
  5. Send yourself a test digest manually
  6. Enable the cron job
  7. Optional: Install subsilver2 style
  8. Optional: Move over user digest settings and subscriptions from phpBB2 board
  9. Optional: Adjust your Administration Control Panel Digest Settings
  10. Troubleshooting, questions and keeping up with bugs and new versions
  11. History and Acknowledgements

1. Complete the instructions in the digests_install.xml file

The primary instructions for installing the Digest Mod for phpBB 3 can be found in the digests_install.xml file in the root folder of the archive. When you get to the DIY Instructions at the bottom, you should be pointed to this web page. Do not begin these instructions until you have completed all the instructions in the digests_install.xml file. You must copy all the files down, make some changes to the database and make a number of file changes before doing anything else.

2. Purge the cache

During Step 1, you added a number of new configuration variables. You cannot use them until you purge the cache. This is easy to do.

  1. Log into the Administration Control Panel
  2. The General Tab is selected by default. On the right side panel near the bottom (you may have to scroll down) there is a "Purge the Cache" with a button "Run Now" next to it. Press the button.
  3. When asked "Are you sure you wish to purge the cache?" of course click on the Yes button.

3. Add a Digests interface to the User Control Panel

Goal: add a new tab called "Digests" in the User Control Panel. Here users will control their digest settings.

  1. Log into the Administration Control Panel.
  2. System tab > Module Management > User Control Panel
  3. In the text box, enter "Digests" and press "Create new module"
  4. Check Yes for "Module enabled" and press Submit
  5. Click on the "Back to previous page" link
  6. Now we will add four digest modules to the new UCP category we created. We'll start with Basics. Click on the new Digests link you just created.
  7. Open the control to the left of the "Add Module" button. Find "Digests [ucp_digests]" and select "Basics" under it. Then click Add Module.
  8. When prompted with an "Are you sure you want to add the selected module with the selected mode?" click "Yes".
  9. Click on the "Back to previous page" link
  10. Click on the "Enable" link next to the Basics module you just added.
  11. Repeat steps 7,10 three times adding modules "Post Selection", "Post Filter" and "Additional Criteria" in turn

4. Add a Digests interface to the Administration Control Panel

Goal: add a new category and three modules on the General Tab of the Administration Control Panel for administering Digests. Once done you will be able to control how digests behave and are administered.

  1. Log into the Administration Control Panel.
  2. System tab > Module Management >Administration Control Panel
  3. Click on the "General" link
  4. In the text box, enter "Digest Settings" and press "Create new module"
  5. Check Yes for "Module enabled" and press Submit
  6. Click on the "Back to previous page" link
  7. Now we will add three digest modules to the new ACP category we created. We'll start with General settings. Click on the new Digest Settings link you just created.
  8. Open the select control to the left of the "Add Module" button. Find "Board Management [acp_board]" and select "General Settings " under it. Then click Add Module.
  9. When prompted with an "Are you sure you want to add the selected module with the selected mode?" click "Yes".
  10. Click on the "Back to previous page" link
  11. Click on the "Enable" link next to the Basics module you just added.
  12. Repeat steps 8,11 two times adding modules "Log settings " and "User default settings" in turn

5. Send yourself a test digest manually

First, configure your digest settings

  1. First, verify your user profile indicates the right time zone and Summer Time/DST offset. Leave the Administration Control Panel if in it and go to the Board index.
  2. User Control Panel > Board Settings. Edit Global Settings appears by default.
  3. Verify your time zone is correct where it says "My time zone" and verify whether summer time/DST is in effect in your time zone. If incorrect, fix then press Submit
  4. There should be a Digests tab on the far right (assuming you are using prosilver). If you do not see it, it was probably not installed properly. The Basics module should be displayed by default.
  5. For "Type of Digest Wanted" click on "Daily". For "Hour sent" select the current hour in your current time zone. Then press Submit. Do not modify any other settings at this time.

Second, run mail_digests.php manually

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.

Troubleshooting Digest Problems

mail_digests.php says no digests were sent

mail_digests.php returns an error message

mail_digests.php says it sent me a digest, but I never received it

I get no feedback when I run mail_digests.php manually

I cannot see my board's style applied to the text in the email digest

6. Enable the Cron Job

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.

Linux/Unix Hosting

Setting up the cron using a Cron Tool in your web host control panel

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.

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. 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

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:

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.

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.

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.

  1. If your web host allows straight telnet access, great. Log in. Skip the next step.
  2. Most web hosts they require that if you want a telnet access you have to use a secure telnet program, such as Secure Shell (SSH). (Putty is a free SSH tool you can install on your computer.) Find out from your web host what you need to do to use SSH. This may not be a trivial process. Elapsed time may take a day or two if you haven't done it before. Often your web host's control panel will contain instructions on how to use SSH. Not all web hosts allow SSH.
  3. You will need a passing ability to use the Unix "vi" text editor to program your crontab job. Here is how I did it (do not send the quotes as part of the commands). Note that you need to first figure out the path to the curl. See the instructions above.
    1. From the command prompt, I entered the command "crontab -e" then Enter, which took me into a "vi" environment
    2. Typing "i" put me in the vi insert mode
    3. Very carefully I typed the following:
     0 * * * * /usr/bin/curl -s -o /dev/null http://www.example.com/phpBB3/mail_digests.php
    1. I pressed the Escape key to get out of vi insert mode
    2. Typed ":wq" then Enter to get out of vi.
    3. To verify the job was scheduled I entered the command "crontab -l" then Enter.
    4. Logged out
  4. Now change your digest settings to the next hour. Wait to see if you get your digest in your email box shortly after the time you programmed the cron. You have completed cron installation.

Windows Hosting

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.

Using an External Web Monitoring Service

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 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.

Troubleshooting Cron Problems

I can get mail_digests.php to run manually, but it fails from a cron

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? 

tail /www/htdocs/mydomainname/phpBB3/files/digests.log

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?

7. Optional: Install subsilver2 style

A digest interface is available for the subsilver2 style. Now would be a good time to install it if you support subsilver2. If you support subsilver2 and do not install these files, users may get error screens in the User Control Panel. All you have to do is copy three files over. Instructions are in the digests_install.xml file in the archive, near the top. Look for "Additional ModX Files", follow the link and follow the instructions.

8. Optional: Move over user digest settings and subscriptions from phpBB2 board

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. However, the utility provided works only with MySQL databases. Instructions are in the digests_install.xml file in the archive, near the top. Look for "Additional ModX Files", follow the link and follow the instructions.

9. Optional: Adjust your Administration Control Panel Digest Settings

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.

10. Troubleshooting, questions and keeping up with bugs and new versions

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.

11. History & Acknowledgements

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 mhamill@computer.org.