File/program/modules/newsletter/newsletter_common.php

Description

/program/modules/newsletter/newsletter_common.php - code shared between admin and view

This file defines various constants and subroutines used from both and newsletter_view.php.

Constants
NEWSLETTER_ALERT_SITE = 2 (line 32)
NEWSLETTER_CHORE_ADD = add (line 51)
NEWSLETTER_CHORE_DELETE = delete (line 52)
NEWSLETTER_CHORE_DESELECT = deselect (line 53)
NEWSLETTER_CHORE_DOWN = down (line 56)
NEWSLETTER_CHORE_DOWNLOAD = download (line 61)
NEWSLETTER_CHORE_EDIT = edit (line 57)
NEWSLETTER_CHORE_LIST = list (line 60)
NEWSLETTER_CHORE_PREVIEW = preview (line 58)
NEWSLETTER_CHORE_SELECT = select (line 54)
NEWSLETTER_CHORE_TESTMAIL = testmail (line 59)
NEWSLETTER_CHORE_UP = up (line 55)
NEWSLETTER_CHORE_UPLOAD = upload (line 62)
NEWSLETTER_CONFIRM_ADD = A (line 64)
NEWSLETTER_CONFIRM_DEL = D (line 65)
NEWSLETTER_CONFIRM_LEN = 12 (line 66)
NEWSLETTER_CONTRIBUTION_POLICY_NO = 0 (line 35)
NEWSLETTER_CONTRIBUTION_POLICY_USERS = 1 (line 36)
NEWSLETTER_CONTRIBUTION_POLICY_YES = 2 (line 37)
NEWSLETTER_FULLMAIL_ONLY = 1 (line 31)
NEWSLETTER_FULLMAIL_SITE = 3 (line 33)
NEWSLETTER_SUBSCRIPTION_APPROVED = 2 (line 47)
NEWSLETTER_SUBSCRIPTION_BLACKLIST = 3 (line 48)
NEWSLETTER_SUBSCRIPTION_CONFIRMED = 1 (line 46)
NEWSLETTER_SUBSCRIPTION_NEW = 0 (line 45)
NEWSLETTER_SUBSCRIPTION_POLICY_NONE = 0 (line 39)
NEWSLETTER_SUBSCRIPTION_POLICY_ONE = 1 (line 40)
NEWSLETTER_SUBSCRIPTION_POLICY_TWO = 2 (line 41)
NEWSLETTER_SUBSCRIPTION_SKIP = 0 (line 44)
NEWSLETTER_UNPUBLISHED = 0 (line 30)
Functions
newsletter_config (line 96)

retrieve the newsletter configuration

  • return: FALSE on error, otherwise the configuration from table
bool|array newsletter_config (int $node_id)
  • int $node_id: the node to which the content is connected
newsletter_consolidate_subscribers (line 181)

remove obsolete subscriber data from the database

this removes superfluous subscribers from the database; eventually there should only be a single instance of an email address per newsletter. However, during the process of subscribing or re-subscribing it may be possible for different records with the same email address (in the same newsletter) to co-exist, be it with different values for status.

This routine is supposedly called after a particular record reaches the status of either NEWSLETTER_SUBSCRIPTION_APPROVED (2) or NEWSLETTER_SUBSCRIPTION_BLACKLIST (3). In those cases all other records with the same email address should simply be removed.

On difficulty may be that there can still be records in the queue that point to 'old' subscribers that are about to be deleted; that would break the foreign key. So, the strategy here is to

  • change the current records in the queue so that they are linked to the new record (if the status is 'APPROVED') OR
  • delete the current records in the queue if the status is 'BLACKLIST'.
  • delete all other records with the same email address.

  • return: TRUE on success, FALSE otherwise
bool newsletter_consolidate_subscribers (int $newsletter_id, int $subscriber_id, string $email, int $status)
  • int $newsletter_id: the newsletter of interest
  • int $subscriber_id: the subscriber record we want to keep
  • string $email: the corresponding email address
  • int $status: the new status of the subscriber
newsletter_dialog_validate (line 125)

validate the data entered by the (un)subscriber

Apart from the standard validation we check for at least 1 @-sign in the email address. (It is non-trivial to validate an email address, it may not even be possible to do it in a single regular expression. See http://stackoverflow.com/questions/201323 for more information.)

As an added bonus the email address is trimmed and standardised in lowercase.

Note that this routine is used both in newsletter_view.php where visitors can subscribe/unsubscribe themselves and where the administrator is responsible.

  • return: TRUE if valid, else FALSE + messages added to dialogdef
bool newsletter_dialog_validate (object &$dialogdef)
  • object &$dialogdef: defines the dialog and will hold POSTed values
newsletter_get_emails (line 85)

create a neat array with email-addresses from a (possibly messy) text

this routine converts a (messy) list of email addresses to an array with a single address per array element. If there are no addresses, an empty array is returned. The addresses are supposed to be comma-delimited and/or newline and/or space delimited. Note that we expect only plain email addresses, no readable names etc. (KISS)

  • return: with one email address per element (or an empty array)
array newsletter_get_emails (string $buffer)
  • string $buffer: holds the messy list of email addresses
newsletter_queue_run (line 285)

attempt to send out as many queued newsletters as possible

this constructs a list of all queued mails ordered by - issue_id - retry time (oldest go first; fifo) - queue_id

This attempts to send out as many queued newsletters as possible. Depending on the value of $node_id we are looking at a specific newsletter ($node_id == $newsletter_id) or any newsletter ($node_id = NULL). Either way we retrieve a list of at most $limit records from the queue. We select only records that have a retry-time in the past, Within that selection, we order the records by issue_id and subsequently the retry time. This means that we can re-use the issue data if there are more queued requests for the same issue. In the same way we also cache the newsletter configuration; read once and hopefully use many.

Note that we start each queue record with incrementing the error count before we do anything else; this means that if somehow the first record gets 'stuck' we can continue with the queue on the next run without hitting the same error over and over again.

This is a best effort; if there's an error we simply bail..

Note that this routine is not interactive (no output to a browser), so it can easily be called from a cronjob.

  • return: FALSE on error, number of sent messages otherwise
bool|int newsletter_queue_run ([int $node_id = NULL], [int $limit = 50])
  • int $node_id: indicates which newsletter to handle
  • int $limit: maximum number of mails to send this time

Documentation generated on Tue, 28 Jun 2016 19:10:59 +0200 by phpDocumentor 1.4.0