5. Digest creation

5.1 Thoughts

Digest creation must happen on a regular basis. Different from every other action in the Action Applications, the event triggering this procedure is not a user requesting a page through http. We have to create this event ourselves, and it is to be regularly created by a timer.

PHP itself as a language does not have capabilities to provide such events. The cron daemon existing on every unix system is the obvious instance for this functionality. cron can be set up to start any program on a regular basis. However, there is one problem if we want to continue using php here: PHP is not necessarily installed as a standalone version. More likely, it exists as a module integrated in the http server and thus PHP programs cannot be called directly from cron.

There are three possible ways out of this problem:

1. Not to use PHP for digest creation and email sending. The advantage would be that the program can easily be called. Written in perl or in C, it would access the Action Applications database through the language specific API. However, there is a major disadvantage: All configuration information is in PHP files, and this info would have to be duplicated if we don't want to start writing a PHP parser in perl or C which is the last thing the whole project wants to go for. Also, existing library functions in php include files cannot be used in this case. This makes this option quite unusable.
2. Require a standalone PHP interpreter. The PHP installation process targets installing either as a http server module or as a standalone (CGI) program. This means that PHP would have to be installed twice. Current Linux distribution vendors provide PHP as a module only. This would add another level of complexity to the installation process (which is already too complex).
3. Use PHP as the http server module and use a small program in another language which requests a specific page. This program could then be called by cron. This would avoid the additional installation effort for php. If we manage to create the page request helper program with tools that exist on every unix system, we would not add any additional installation overhead.

In this specification, the third solution is specified because it seems to be easiest for users to install and to maintain.

5.2 Specification

Page request program to be called from cron (aa-http-request)

This should be a small program aa-http-request which only uses standard unix functions and programs such as /bin/sh. If possible, there should be no configuration or system type dependent parts. It accepts two parameters which specify the host name and the page to be requested.

Usage would be

        aa-http-request <host> <file>

        aa-http-request localhost /aa/admin/cron.php3

The program should wait for the server to close the connection but throw away anything it sends.

The following is the result of experiments the specification writer has made and it can be used as an implementation hint source (it does not provide the functionality specified in full).

        #!/bin/sh
        TMPFILE=/tmp/aa.$$
        (
        touch $TMPFILE
        sleep 1; 
        echo "GET /aa/admin/"; 
        while true; do sleep 5; test -f $TMPFILE || break; done
        ) | (telnet localhost 80; rm -f $TMPFILE)

php script for cron to call daily (cron-daily.php3)

The new php file cron-daily.php3 is meant to be called by cron through the aa-http-request script.

In order to keep an open architecture, the file should not do much but call other scripts which have to do things on a regular, daily basis.

One of the scripts to call is email-digest.php3 , a second one is new also new script email_auto_cleanup.php3 .

php script which actually sends the digests: email-digest.php3

The program file that actually sends digests resulting from subscriptions is called email-digest.php3. When started, it will

• initialize the environment (read config files etc.)
• select unique user ids (uid) and frequency combinations from subscriptions table
• iterate over combinations selected. For each combination, do
  • select records from the subscriptions table which belong to the current combination and which
    • in case of a frequency of daily have the last post date of yesterday or older or
    • in case of a frequency of weekly have the last post date of the day seven days ago or older
  • From the records selected, create a complex SQL statement which selects all information from the database, mainly from the items table, which the subscriptions cover. The statement should sort items by post date.
  • Execute the complex SQL statement.
  • Create the email message text from the resulting records as described in the requirements section of this paper
  • While creating the email message, remember the charset used by the first item that is included into the digest.
  • use the aaemail() function to send the message. The subject line should be taken from the common language file together with the time period this posting covers. The charset to be used should be the one just remembered.