PHPList API Service Script

subscribe_service.php

<?php

    /* subscribe_service.php --

    Purpose: Remote List Control via HTTP, subscribe function
    Original Author: Rich Cowan, 8/8/05
    Modified by: Jesse Heap 1/3/2006     : http://forums.phplist.com/viewtopic.php?f=7&t=3252
    Modified by: Chad Phillips 1/11/2012 : http://forums.phplist.com/viewtopic.php?f=7&t=3252&start=30
    Modified by: Kyle Harrison 7/18/2014 : http://forums.phplist.com/viewtopic.php?f=7&t=3252&start=30
        Notes:  - Changed success found string to match default installation. Was always returning false otherwise. 
                - Would be nice to clean this up a bit\

    Details:
    With PHPList installed this procedure can be use to
    subscribe a user using the HTTP command.  The procedure works
    by simulating a POST to the default subscribe page.  It requires
    the CURL PHP library.


    USAGE:

    (Here we assume script password is "letmein")

    Command:
    http://mydomain.com/lists/subscribe_service.php?password=letmein&email=johndoe%40aol.com

    Result:
    This will subscribe John Doe to the default email list; note that the
    '@' sign has been replaced here by %40 which is needed by most web servers.

    Command:
    http://mydomain.com/lists/subscribe_service.php?password=letmein&email=johndoe%40aol.com&attribute1=John&attribute2=Doe&attribute3=TX

    Result:
    This will subscribe John Doe to the email list, but also add
    user data for him, namely John's first name, last name, and
    state, which must be set up as phplist attributes for List #2

    NOTES:
    
    The following special parameters can also be passed:
      - htmlemail=1 : Format the list emails using HTML instead of plain text.
      - makeconfirmed=1 : Confirm user immediately, bypassing confirmation email.
      - list_ids=1,2,N : Subscribe to lists other than the default list. Pass a
                         comma separated list of list IDs.
      - _jsonp_callback=[name] : Use this to send the response in JSONP format,
                                 [name] is the function to wrap the JSON response
                                 in.

    By default, debugging is disabled, if the functionality is not working, you
    can enable it to get more helpful output.

    The script returns JSON to the caller.

    This script is a pretty bad hack, but given that there's no usable API in
    PHPList to subscribe users, it's a decent tool.  Unfortunately, there's no
    good way to get feedback on the success of the cURL calls, so it's a bit of a
    send and pray...  ;)


    INSTALLATION AND CONFIGURATION:

    1. Copy this script to the home directory of PHPList (the lists folder), and
       make sure that your webserver settings allow access to the file -- in the
       default PHPList setup, you'll need to edit the allowed list of top-level PHP
       files in the .htaccess file (located in the lists folder) to include this
       script, eg:

         <FilesMatch "(index.php|dl.php|ut.php|lt.php|download.php|subscribe_service.php)$">

    2. Copy the subscribe_service_settings.inc file to the home directory of
       PHPList. Make sure your webserver settings deny access to this file. In the
       default PHPList setup on Apache, no change should be necessary.

    3. Add the following line to the end of the 'Thank you page' setting for your
       subscribe page:

         <div style="display:none">###subscribe_success###</div>

       This is necessary for validating that the subscription request was
       successful.

    4. Edit any necessary settings in the CONFIGURATION SETTINGS section below.

    5. Edit any necessary settings in the subscribe_service_settings.inc file.

    */


    // CONFIGURATION SETTINGS.
    // The site-specific settings for this script are located in the file
    // referenced by the require statement below -- see the file for directions
    // on how to configure this script for your site. They are placed in a separate
    // file for security -- should the PHP parsing engine fail, the settings will
    // not be exposed to end users.
    require_once "./subscribe_service_settings.inc";

    // The string to search for when verifying that the subscribe thank you page
    // was returned on subscription. This is a poor verification method, but the
    // best we can do given that there's no subscription API.
    define('SUBSCRIBE_SUCCESS_STRING', "Thank you for subscribing to our newsletters");

    // CODE

    /**
    * Simple debug logger.
    */
    function debug_log($message) {
      if (DEBUG) {
        print("$message<br />");
      }
    }

    function json_output($code, $message, $params = array()) {
      $data = array(
        "result" => array(
          "result_num" => $code,
          "result_text" => $message,
        ),
      );
      $json = json_encode($data);
      if (!empty($params['_jsonp_callback'])) {
        $callback = $params['_jsonp_callback'];
        header('Content-type: text/javascript');
        $json = "$callback($json)";
      }
      else {
        header('Content-type: application/json');
      }
      print($json);
    }

    /**
    * Make sure script password matches.
    */
    function validate_access($params) {
      if (empty($params['password'])) {
        $message = "Access password not supplied.";
        debug_log($message);
        json_output(1, $message, $params);
        exit(0);
      }
      if (SCRIPT_PASSWORD != $params['password']) {
        $message = "Access password incorrect.";
        debug_log($message);
        json_output(1, $message, $params);
        exit(0);
      }
      debug_log("Access password correct.");
      return TRUE;
    }

    /**
    * Convert query parameters into subscribe post data.
    */
    function process_query_params($params) {
      $list_ids = !empty($params['list_ids']) ? $params['list_ids'] : DEFAULT_LIST;
      // Remove list_ids parameter, handled separately.
      unset($params['list_ids']);
      // Remove password parameter, not needed for POST.
      unset($params['password']);
      $post_data = array();
      foreach ($params as $key => $value) {
        // Set each GET value pair to the post_data associative array in
        // preperation for the POST.
        $post_data[urldecode($key)] = urldecode($value);
      }
      // Multiple list IDs can be passed in a comma separated string.
      $list_ids_array = explode(",", $list_ids);
      foreach ($list_ids_array as $list_id) {
        $post_data["list[$list_id]"] = "signup";
        $post_data["listname[$list_id]"] = "list[$list_id]";
      }
      return $post_data;
    }

    /**
    * Ensure email is provided.
    */
    function validate_email($post_data) {
      if (empty($post_data['email'])) {
        $message = "You must supply an email address";
        debug_log($message);
        json_output(1, $message, $post_data);
        exit(0);
      }
      debug_log("Email validated");
      return TRUE;
    }

    /**
    * Login to phplist as admin and save cookie using CURLOPT_COOKIEFILE.
    */
    function admin_login(&$ch) {
      $url = DOMAIN . "admin/?";
      $login_data = array(
        "login" => PHPLIST_ADMIN_USERNAME,
        "password" => PHPLIST_ADMIN_PASSWORD,
      );
      curl_setopt($ch, CURLOPT_POST, 1);
      curl_setopt($ch, CURLOPT_URL, $url);
      curl_setopt($ch, CURLOPT_POSTFIELDS, $login_data);
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
      // Enable Cookie Parser.  File does not need to exist.
      // http://curl.netmirror.org/libcurl/c/libcurl-tutorial.html for more info.
      curl_setopt($ch, CURLOPT_COOKIEFILE, "/tmp/nofileneeded.txt");
      $result = curl_exec($ch);
      debug_log("Admin login result was: " . htmlentities($result));
    }

    /**
    * Simulate post to subscriber form.
    */
    function post_subscribe(&$ch, $post_data) {
      $post_data["emailconfirm"] = $post_data['email'];
      $post_data["subscribe"] = "Subscribe";
      debug_log("Post data: " . var_export($post_data, TRUE));
      $url = DOMAIN . "?p=subscribe";
      curl_setopt($ch, CURLOPT_POST, 1);
      curl_setopt($ch, CURLOPT_URL, $url);
      curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
      $result = curl_exec($ch);
      debug_log("Subscribe result was:" . htmlentities($result));
      if (strpos($result, SUBSCRIBE_SUCCESS_STRING) !== FALSE) {
        $message = "User subscribe request successful";
        $result = 0;
      }
      else {
        $message = "User subscribe request failed";
        $result = 1;
      }
      debug_log($message);
      json_output($result, $message, $post_data);
    }

    // Parse query params.
    parse_str($_SERVER['QUERY_STRING'], $params);
    debug_log("Parsed params: " . var_export($params, TRUE));

    if (validate_access($params)) {
      $post_data = process_query_params($params);
      if (validate_email($post_data)) {
        $ch = curl_init();
        admin_login($ch);
        post_subscribe($ch, $post_data);
        curl_close($ch);
      }
    }

subscribe_service_settings.inc

<?php
    /* subscribe_service_settings.inc --

    Purpose: Remote List Control via HTTP, settings
    Original Author: Chad Phillips 1/11/2012

    Details:
    Controls the site-specific settings for the subscribe_service.php script.

    INSTALLATION AND CONFIGURATION:

    Copy this script to the home directory of phplist, the lists folder.

    To configure, just replace the values below for settings with the
    location of your PHPList installation, and a working admin password
    for this installation.

    IMPORTANT NOTE:

    Exposing these settings can compromise the security of your list, therefore
    you should ensure that this file is not directly visible to the outside world.
    In the default PHPList installation, the .htaccess settings in the lists
    directory should handle this for you.

    */

    // The PHPList site to send subscriptions to.
    define('DOMAIN', "http://mysite.com/lists/");
    // Admin username for the PHPList site.
    define('PHPLIST_ADMIN_USERNAME', "admin");
    // Admin password for the PHPList site.
    define('PHPLIST_ADMIN_PASSWORD', "******");
    // The list ID to subscribe a user to by default, if no other is provided.
    define('DEFAULT_LIST', 1);
    // Simple access control for the script. Callers must send this in their
    // request in the 'password' query parameter.
    define('SCRIPT_PASSWORD', "letmein");
    // If set to TRUE, prints extra debugging information.
    define('DEBUG', TRUE);