Download here
Functionality
phpBB does not provide the ability to send regular emails to users with summarized postings on a forum. Instead, phpBB expects that users will visit the phpBB forum regularly if they want to keep up with what is going on at the site or use the phpBB 3 Atom feed feature.
phpBB Digests are emails sent to users periodically with summary of postings made on a phpBB forum for discrete time periods. Digests makes some phpBB forum users’ lives easier. They don’t have to explicitly visit the site to see what conversations are going on around there. They just read their digest and if there is some topic that seems of interest, they click on the topic link in their email program and start participating! They can unsubscribe at any time. By default, weekly digests are sent on Sundays. The users determines the hour they want to receive the digest. Whatever time they choose, they will always get the latest news so they can pick a time that suits their lifestyle.
Digests can be daily, weekly or monthly. Posts older than this will not be sent in a digest. In addition, if you want you can elect not to see posts since you last logged in, if you visited recently. You can even filter out your own posts.
If a user does not want summaries of every post, they can be selective. They can pick the forum or forums that interests them. By default they will get posts for all forums that they are allowed to access.
Digests can be sent as emails containing HTML or plain text. By default the user gets the entire post as text, but they can also select to see excerpts of each post or get a list of posts with links to each post.
Please note that each digest is unique, and may have different posts in it compared to another digest going out at the same hour. It may not be an appropriate digest solution for very large boards, very busy boards or for those who want to send bulk emails of all posts for a given time period, as it is designed for flexibility, not efficiency.
Installation
If you installed an earlier version of the digests extension, first disable it like any other extension. If you are using digests in a production situation, if you also delete the data you will lose any digest subscriptions. Also use your FTP program to remove the entire
/ext/phpbbservices/digests directory.Install this release as you would any other extension. The digest tree should be in
/ext/phpbbservices/digests.Digests are sent via either a phpBB cron or a system cron.
Sending digests via a phpBB cron
A phpBB cron event occurs when traffic hits your forum. This default method is the easiest way to go. It has one downside. If your forum traffic is light, your users may not receive their digest in the hour requested. It assumes there is regular traffic for pretty much any hour, even in the middle night and on weekends. If this happens digests will usually be delivered in the hour requested. If received late, digests will still contain posts for the time period wanted.
If your forum gets little traffic, using this approach can be counterproductive. Digests may arrive hours or days later than expected. If digests will be an important feature of your forum, then using a system cron to send digests is the preferred approach to use. On shared hosting a queue may develop that becomes so large it will trigger resource limitation. In cases like this you might want to "reset" digests so that digests will start processing for the current hour. ACP > Extensions > Digests > Reset mailer.
Sending digests via a system cron
This is a better way to go as users will receive their digests in the hour requested. A system cron will send not just digests that need to be sent but other topic and forum notifications as well. So think about how frequently you want to call the cron job. Since digests are sent no more frequently than once an hour, at a minimum the cron should go out once an hour, at the top of the hour is ideal. But since this may delay notification emails you might want to make it more frequent. I recommend every 15 minutes but it depends on traffic on your forum and user expectations for receiving timely notifications and digests.
Instructions can be found at:
https://wiki.phpbb.com/PhpBB3.1/RFC/Mod ... ystem_cron
For Windows hosting, the equivalent of a Unix cron is available. Please learn about Windows scheduled tasks.
phpBB is usually installed on shared hosting. In this case the official phpBB approach probably won't work. So this approach is probably needed:
Language translationsIn shared hosting environments cron may be allowed but multiple commands may not be allowed in the cron. You may be able to use curl or wget instead of a system cron. Using this approach do NOT select 'Run periodic tasks from system cron' setting in the 'Server settings' tab of the ACP. You will still need to create a cron, however. The purpose of the cron is to trigger phpBB's cron regularly so if there is no board traffic programmed phpBB crons are still executed. A cron command similar to the following may work:
or if your forum uses HTTPS, you may find you need to disable checking the site's certificate, which often causes problems:Code: Select all
* * * * * curl -A=Mozilla/4.0 http://www.yourforum.com/forum/cron.php?cron_type=cron.task.cron_task
With this approach some trial and error may be necessary. Have the results of the cron sent to an email address that you can read and examine it for troubleshooting. It may be necessary to use a different user agent or to prepend curl or wget with the path, which might be /usr/bin or /bin. Your web host can provide information on the paths needed if necessary. When it is all working you may want to turn off the cron notifications.Code: Select all
* * * * * curl -A=Mozilla/4.0 -k https://www.yourforum.com/forum/cron.php?cron_type=cron.task.cron_task
Here are the known language translations for the digests extension. Since not all translations are current or available on GitHub, using a translation for a different version of the digests extension than you have installed may result in an inconsistent rendering and possible incorrect usage of the extension. Languages files need to be placed in
/ext/phpbbservices/digests/language in a folder with the correct language code, e.g.: /ext/phpbbservices/digests/language/fr.- French (provided by Bonnaphil)
- German (provided by Praggle)
- Czech (provided by Petr Hendl)
- Spanish (provided by kamaleon)
Remove old modules!
Before installing the extension, you should remove old digest modules or the extension may fail to install. Note that there are both ACP and UCP digest modules. These can be removed via ACP > System > Module management. For ACP modules, find them under Administration Control Panel > ACP_DIGEST_SETTINGS. Delete all these modules including the ACP_DIGEST_SETTINGS category itself working from the bottom up. For UCP modules, find them under User Control Panel > UCP_DIGESTS. Delete all these modules including the UCP_DIGESTS category itself working from the bottom up.
If AutoMOD was previously installed, the AutoMOD modules are likely still in the database too. These should be removed via ACP > System > Module management > Administration Control Panel. Select ACP_CAT_MODS and delete all modules and categories including the ACP_CAT_MODS category itself working from the bottom up.
Subscriber settings in the database from the digests modification should be successfully retained during installation.
Remove the old cron job!
Digests no longer requires that a cron job be run hourly. It now uses phpBB's built in cron.php program. If traffic is light on your forum, digests may be delivered hours or even days later than the scheduled time. However the digest will always contain posts for the date and time requested.
If your old cron job for sending out digests is still running, it should be removed. This is usually easy to do in your web host control panel. Look for a cron setting, look for a cron job that has mail_digests.php in it and delete that cron job.
If you were doing this through a site monitoring service, log into that service and delete that monitor.
Setting up digests
Once installed you should see:
- An Administration Control Panel interface for digests on the Extensions tab with seven modules of major functionality
- Users will have an interface to subscribe to digests in the User Control Panel. Look for a digests tab.
The first thing to do is to make sure digests that are configured the way you want them to be.
- ACP > Extensions > Digests
- Select General settings and review these, changing as you prefer. To start off, it is recommended that you set “Write all digest actions to the admin log” to Yes and “Show email address in log” to Yes.
- Select User default settings next. If a user chooses to subscribe to digests these will be the defaults. Change defaults as you prefer.
- If you want to subscribe members of your forum to digests, use the Mass subscribe/unsubscribe option. Generally, this is not a good idea because it can feel like spam. It’s better to let members know the option exists and let them elect to receive a digest.
To make sure things are working, first send yourself a digest.
- Set yourself up correctly
- Go to the User Control Panel > Board preferences. Edit Global Settings appears by default.
- Verify your time zone is correct where it says “My time zone”. If incorrect, fix then press Submit.
- Select the Profile tab. Then select Edit account settings. Check your email address and correct if necessary. Digests will be sent to this email address.
- There should be a Digests tab on the far right (assuming you are using the prosilver style). Select Digests. The Basics module should be displayed by default.
- For “Type of Digest Wanted” click on “Daily”. For “Hour sent” select the current hour in your current timezone. Then press Submit.
- Select the Digests Additional Criteria tab. For “Send a digest if there are no new posts” select Yes. Then press Submit.
- Do a test mailing manually
- ACP > Extensions > Digests > Manually run the mailer
- Set “Run the mailer” to Yes
- Set “Send results to files instead of emailing” to No
- Press submit. If an error occurred you should see a message to this effect. You might also want to check the admin log on the maintenance tab for any informational messages. The error log should show errors that may have occurred.
- Look for an email in the email inbox of the email address in your phpBB profile. If you don’t see it, it may be in your spam folder. (Note: if they appear in your spam folder, it may be because the email is coming from an address that is not part of your domain. Check your board contact email address and your board reply to email address and verify it uses an @mydomain.com address. Set up an email address like [email protected] if it does not exist. Create the email account in your web host control panel or set up a mail forwarder there so it forwards emails to the address of your choice.)
The manual mailer feature in the Administration Control Panel allows digests to be stored in a
/store/phpbbservices/digests directory instead of emailing. This is useful for troubleshooting. You can download these files with FTP and open them in a browser in local mode to view them. The file names have the format username-yyyy-mm-dd-hh.html or username-yyyy-mm-dd-hh.txt. The dates in the file name are based on your server's timezone.To open in local mode, press CTRL-O (the letter, not the number), or CMD+O on the Mac, navigate to the folder where they were downloaded to, and open the .html or .txt file. Please note that since these are not emailed, they include only the HTML or text portion of the digest. Email headers are not captured. Viewing these in a browser shows the ideal presentation of the digest. Individual email clients may alter the styles changing the look actually seen by the recipient on their device.
Automated mailer test
Once you have verified a digest can be successfully sent, test that it will work automatically!
- If you haven’t set up the phpBB system cron using the instructions in the last section, you can do it now but it is not required.
- Go back into the User Control Panel and make sure that the hour you want to receive your digest is for the current hour.
- Go back into the ACP > Extensions > Digest settings > Reset mailer. Set the first radio button to "Yes" and submit the form.
- If you are NOT using a system cron, going to the board's index should trigger a phpBB cron. If nothing happens, try logging out and logging back in. This will usually trigger a phpBB cron event, triggering the mailer. Evidence that the cron ran should be in ACP > Maintenance > Admin log. In addition you should check the appropriate email inboxes for the digests. If you don't see them, look in your spam folder.
Once you are all done and ready to "go live" you should choose reset the mailer: ACP > Extensions > Digests > Reset mailer.
Troubleshooting
If you followed the instructions above, actions will be written to the Admin log (ACP > Maintenance > Admin log). Generally there should be a "Starting digest mailer" log entry near the current time and a "Ending digest mailer". There should also be an entry indicating the type of mailer used: manual, system or regular (phpBB). When a digest is mailed if logging is turned on to show the email address it will also be in the log. The log should indicate the date and hour for which digests were mailed, in UTC. This is a useful aid when troubleshooting or fielding questions. If a phpBB error occurred it is probably in the error log.
Most problems during testing are a result of missing steps in the testing procedures. There are many filters that can keep a digest from going out so the test case has to be good. Frequently, there are no digests scheduled for the hour so it's important to make sure a test user is setup to send one for the current hour. Note: you can use the Balance Load function to get an idea of how many digests are programmed to go out for a particular hour. (Whether they will actually go out depends on filters specified by the subscriber.)
For a list of all the reasons why posts may not be appearing in a digest read this blog post.
If the mailer was run successfully, you have to wait an hour before another one will go out unless you use the manual mailer.
If it has been many days or more since digests have been run, you might want to reset digests. This can be done as follows: ACP > Extensions > Digests > Reset mailer. The next time digests are run, only digests for the current hour will be processed.
On shared hosting, resource limitations often kick in if many hours or days have passed since the mailer was last successfully run. To lessen the likelihood of an error in this case, you might want to set the "Maximum hours for mailer to process" option to a small number: ACP > Extensions > Digests > General options. This is not normally an issue on a dedicated or virtual server, but there may be quotas imposed by your web host on outgoing emails for an hour or a day.
Great care was taken to ensure faithfulness to the 3.0 digest modification. Screens for the most part look identical and the functionality and layout of the digests is virtually the same as well. Since the architecture for phpBB 3.1 and 3.2 is much different than for phpBB 3.0, some features were removed. Don’t panic, because they don’t make sense anymore.
