Rainmaker, a local startup, was announcing a month-long API Challenge for their new web service.

The challenge: Build Something Cool! (along with a chance to win some fabulous prizes)

But what’s the API all about? Basically, you provide an email address to their API, and Rainmaker returns a rich set of contact information.

I took a quick browse of their contest page, saw the API and some examples, and immediately started thinking about something to build.

Today, I’m officially releasing my contest app:
The RainmakerMoxie Interactive WordPress Plugin.

How it works:
1) Enter an email address to lookup.
2) Available contact info for that email address appears in the sidebar: photo, contact information, interests, social profiles and links, tweets, and Plancast plans.

Highlights:
• Configurable to show 1-20 most recent tweets.
• Configurable to show 1-20 most recent Plancast plans.
• Setup is internationalized for Chinese, German, Italian, and Spanish.
• Mashup API’s include SendGrid, Twitter, and Plancast.

The Plugin can be downloaded from the WordPress hosted Plugin page.

The Plugin source code is located at the WordPress hosted SVN repository.

Faithfully submitted, Neil Simon

From the command line, this is the syntax to run it:
$ /SendGrid/sgstats2phone.php 3034029500 nsimon@solidcode.com MySecretApiKey

It calls my phone and delivers a text-to-speech message similar to this:
"send grid stats for nsimon at solidcode dot com May 10th 2011.
 requests 44, delivered 43, invalid 1. Thank you, good bye."

I scheduled a cron job to deliver the stats at 8:00pm every evening:
00 20 * * * /SendGrid/sgstats2phone.php 3034029500 nsimon@solidcode.com MySecretApiKey

App note: requires cURL, the Client URL Request Library. On my Ubuntu system, I installed cURL with this command:
$ sudo apt-get install php5-curl

If you’re a SendGrid developer, I hope you find this helpful.

Download the code
 

#!/usr/bin/php
<?php

/******************************************************************************/
/* Module ..... sgstats2phone.php                                             */
/* Author ..... Neil Simon                                                    */
/* Modified ... 06/07/2011                                                    */
/* Desc ....... Delivers SendGrid account stats to a phone call               */
/* Usage ...... sgstats2phone.php {phone} {username} {api_key}                */
/******************************************************************************/

/******************************************************************************/
/* Include classes                                                            */
/******************************************************************************/

require_once ("CommandLine.php");
require_once ("SendGrid.php");
require_once ("SendGridCurl.php");

/******************************************************************************/
/* main                                                                       */
/******************************************************************************/

main ($argc, $argv);

function main ($argc, $argv)
    {
    // Reset to 0 upon success
    $rc = 1;

    // 3 args (+progname) required
    if ($argc != 4)
        {
        usage ();
        printf ("ERROR: 3 args required.\n");
        }

    else
        {
        // Store args
        $commandLine = new CommandLine_sgstats2phone ($argc, $argv);

        // Extract args
        $commandLine->extractArgs ();

        // Validate args
        if (($argStatus = $commandLine->validateArgs ()) != 0)
            {
            usage ();
            $commandLine->printArgErrorMessage ($argStatus);
            }

        else
            {
            // Store the args in the sendGrid object
            $sendGrid = new SendGrid ($commandLine->argPhone,    // 3034029500
                                      $commandLine->argUser,     // nsimon@solidcode.com
                                      $commandLine->argApiKey);  // MySecretApiKey

            // Get the SendGrid stats for the current day (via REST/XML)
            if ($sendGrid->statsGet () != 0)
                {
                printf ("ERROR: sendGrid->statsGet()\n");
                }
            else
                {
                // Assemble the text-to-speech text, setup params to pass to curl
                $sendGrid->assembleStats ();

                // Send stats to phone
                if (SendGridCurl::issueRequest ($sendGrid->get_statsParams()) == 0)
                    {
                    // Successful
                    $rc = 0;
                    }
                }
            }
        }

    exit ($rc);
    }

function usage ()
    {
    printf ("Usage: sgstats2phone.php {phone} {username} {api_key}\n");
    printf ("Ex:    sgstats2phone.php 3034029500 nsimon@solidcode.com MySecretApiKey\n");
    }

<?php

/******************************************************************************/
/* Module ..... CommandLine.php                                               */
/* Author ..... Neil Simon                                                    */
/* Modified ... 06/07/2011                                                    */
/******************************************************************************/

class CommandLine
    {
    protected $_argc = 0;  // Set in constructor
    protected $_argv = 0;  // Set in constructor

    public function __construct ($argc, $argv)
        {
        // Store count
        $this->_argc = $argc;

        // Store values array
        $this->_argv = $argv;
        }
    }

class CommandLine_sgstats2phone extends CommandLine
    {
    // Error constants
    const ERROR_ARG_PHONE_NOT_10      = 1;
    const ERROR_ARG_PHONE_NOT_NUMERIC = 2;

    // Extracted from command line positional values
    public $argPhone  = "";
    public $argUser   = "";
    public $argApiKey = "";

    public function __construct ($argc, $argv)
        {
        // Store argc, argv
        parent::__construct ($argc, $argv);
        }

    public function extractArgs ($display = true)
        {
        // Extract values
        $this->argPhone  = $this->_argv [1];
        $this->argUser   = $this->_argv [2];
        $this->argApiKey = $this->_argv [3];

        if ($display)
            {
            // Display the args
            printf ("argPhone ......... %s\n", $this->argPhone);
            printf ("argUser .......... %s\n", $this->argUser);
            printf ("argApiKey ........ %s\n", $this->argApiKey);
            printf ("\n");
            }
        }

    public function validateArgs ()
        {
        $rc = 1;

        // Phone must be length 10
        if (strlen ($this->argPhone) != 10)
            {
            $rc = self::ERROR_ARG_PHONE_NOT_10;
            }

        // Phone must be numeric
        elseif (!is_numeric ($this->argPhone))
            {
            $rc = self::ERROR_ARG_PHONE_NOT_NUMERIC;
            }

        else
            {
            // Success
            $rc = 0;
            }

        return ($rc);
        }

    public function printArgErrorMessage ($argErrorNum)
        {
        // Display error message
        switch ($argErrorNum)
            {
            case self::ERROR_ARG_PHONE_NOT_10:
                {
                printf ("ERROR: phone must be 10 characters.\n");
                break;
                }
            case self::ERROR_ARG_PHONE_NOT_NUMERIC:
                {
                printf ("ERROR: phone must be numeric.\n");
                break;
                }
            default:
                {
                printf ("ERROR: unknown error.\n");
                break;
                }
            }
        }
    }

<?php

/******************************************************************************/
/* Module ..... SendGrid.php                                                  */
/* Author ..... Neil Simon                                                    */
/* Modified ... 06/07/2011                                                    */
/******************************************************************************/

class SendGrid
    {
    private $_argPhone  = "";  // Set in constructor
    private $_argUser   = "";  // Set in constructor
    private $_argApiKey = "";  // Set in constructor

    private $_statsGetXml;     // Returned from stats.get.xml
    private $_statsParams;     // Filled by assembleStats ()

    public function __construct ($argPhone, $argUser, $argApiKey)
        {
        // Store values
        $this->_argPhone  = $argPhone;
        $this->_argUser   = $argUser;
        $this->_argApiKey = $argApiKey;
        }

    public function get_statsParams ()
        {
        // This is passed to curl
        return ($this->_statsParams);
        }

    public function statsGet ()
        {
        // Reset to 0 upon success
        $rc = 1;

        // Define constant for stats get
        define ("SENDGRID_XML_STATS_GET", "https://sendgrid.com/api/stats.get.xml?" .
                "api_user=$this->_argUser&api_key=$this->_argApiKey");

        // Call the SendGrid API -- suppress any errors
        if (($statsGet = @file_get_contents (SENDGRID_XML_STATS_GET)) != FALSE)
            {
            // Create addressable XML array object to pass out
            $this->_statsGetXml = new SimpleXMLElement ($statsGet);

            // Success
            $rc = 0;
            }

        return ($rc);
        }

    public function assembleStats ($display = true)
        {
        // Split-out the date
        $month = date ("F",  strtotime ($this->_statsGetXml->day->date));  // May
        $day   = date ("jS", strtotime ($this->_statsGetXml->day->date));  // 10th
        $year  = date ("Y",  strtotime ($this->_statsGetXml->day->date));  // 2011

        // Extract the stats
        $requests      = $this->_statsGetXml->day->requests;
        $delivered     = $this->_statsGetXml->day->delivered;
        $invalid_email = $this->_statsGetXml->day->invalid_email;

        if ($display)
            {
            printf ("month ............ %s\n", $month);
            printf ("day .............. %s\n", $day);
            printf ("year ............. %s\n", $year);
            printf ("\n");

            printf ("requests ......... %s\n", $requests);
            printf ("delivered ........ %s\n", $delivered);
            printf ("invalid_email .... %s\n", $invalid_email);
            printf ("\n");
            }

        // Split-out the user email into 3 pieces (split on @ and .)
        $emailPieces = preg_split ("/[@\.]/", $this->_argUser);  // nsimon solidcode com

        // Build the text-to-speech string, part 1
        $textToSpeech1 = sprintf ("send grid stats for . " .
                                   "%s . at %s dot %s . %s %s . %s . ",
                                   $emailPieces [0],
                                   $emailPieces [1],
                                   $emailPieces [2],
                                   $month,
                                   $day,
                                   $year);

        // Build the text-to-speech string, part 2
        $textToSpeech2 = sprintf ("requests . %s . delivered . %s . in valid . %s . ",
                                   $requests,
                                   $delivered,
                                   $invalid_email);

        // Build the text-to-speech string, part 3
        $textToSpeech3 = "thank you . good bye";

        if ($display)
            {
            printf ("textToSpeech1 .... %s\n", $textToSpeech1);
            printf ("textToSpeech2 .... %s\n", $textToSpeech2);
            printf ("textToSpeech3 .... %s\n", $textToSpeech3);
            printf ("\n");
            }

        // Assemble the 3 text-to-speech pieces into the fullText
        $fullText = $textToSpeech1 . $textToSpeech2 . $textToSpeech3;

        // Setup params array for curl POSTFIELDS
        $this->_statsParams = array ("api_user"  => $this->_argUser,
                                     "api_key"   => $this->_argApiKey,
                                     "x-smtpapi" => "",
                                     "to"        => $this->_argPhone . "@phone",
                                     "subject"   => "",
                                     "html"      => "",
                                     "text"      => $fullText,
                                     "from"      => "");
        }
    }

<?php

/******************************************************************************/
/* Module ..... SendGridCurl.php                                              */
/* Author ..... Neil Simon                                                    */
/* Modified ... 06/07/2011                                                    */
/******************************************************************************/

class SendGridCurl
    {
    public function issueRequest ($params, $display = true)
        {
        // Reset to 0 upon success
        $rc = 1;

        // Define constant for SendGrid JSON URL
        define ("SENDGRID_JSON_REQUEST_URL", "http://sendgrid.com/api/mail.send.json");

        // Generate curl request
        if (($hCurl = curl_init (SENDGRID_JSON_REQUEST_URL)) == FALSE)
            {
            if ($display)
                {
                printf ("STATUS ........... ERROR: curl_init() failed\n");
                }
            }

        else
            {
            // Set the curl options
            curl_setopt ($hCurl, CURLOPT_POST,           true);    // POST
            curl_setopt ($hCurl, CURLOPT_HEADER,         false);   // Dont return headers
            curl_setopt ($hCurl, CURLOPT_RETURNTRANSFER, true);    // Return the response
            curl_setopt ($hCurl, CURLOPT_POSTFIELDS,     $params); // Add the POST body

            // Exec curl
            if (($response = curl_exec ($hCurl)) == FALSE)
                {
                if ($display)
                    {
                    printf ("STATUS ........... ERROR: curl_exec() failed\n");
                    }
                }

            else
                {
                if ($display)
                    {
                    printf ("STATUS ........... Message sent successfully\n");
                    }

                // Success
                $rc = 0;
                }

            // Close the curl handle
            curl_close ($hCurl);
            }

        return ($rc);
        }
    }

The plugin, written in PHP, has several well-documented examples of helpful WordPress plugin features.

See how the readme.txt maps to the hosted plugin pages and the 5 hosted screenshots.

The main code module dandyid-services.php has examples of:

• Creating a sidebar widget.
• Processing returned XML that is PHP4 and PHP5 compatible.
• Storing and retrieving wp-database options in an array.
• Embedding the plugin name and version-number into a <div> tag that appears on all blog pages that render the plugin. (useful for debugging — many versions of the plugin can be out there in the wild)
• Localization for international language support.
• Creating an options page for admin plugin configuration, including HTML that renders radio buttons and checkboxes.
• Caching the DandyID API results — on a busy blog, the plugin only calls the DandyID API once every 2 hours.
• A plugin activation hook that creates initialized, defaulted wp-database options.
• A plugin deactivation hook that cleanly removes the plugin wp-database options.

The WordPress maintained repository contains all of the DandyID Services Plugin files for the current release. WordPress automatically packages the plugin files as a zipfile for downloading.

Thanks to Ryan Cook for organizing this Boulder Startup Week session.

#!/usr/local/php5/bin/php
<?php

/*****************************************************************************/
/* This demo was created by Neil Simon for Ryan Cooks PHP Hacking Session    */
/* Boulder Startup Week, 05/05/2010                                          */
/*****************************************************************************/
/* Module ........ get_forecast.php                                          */
/* Description ... (1) Uses PHP to create a command-line utility             */
/*                 (2) Passes arguments in from the command-line             */
/*                 (3) Calls the Weather Underground REST API (returns XML)  */
/*                 (4) Extracts the weather text from the returned XML       */
/* Usage ......... get_forecast.php {zip5}                                   */
/* Example ....... get_forecast.php 80304                                    */
/*****************************************************************************/

// First executable line, calls main()
main ($argc, $argv);

function main ($argc, $argv)
    {
    // Initialize to failure, set to 0 upon success
    $rc = 1;

    // Ex: $argv[0] get_forecast.php
    // Ex: $argv[1] 80304
    if ($argc != 2)
        {
        printf ("Usage ..... get_forecast.php {zip5}\n");
        printf ("Example ... get_forecast.php 80304\n");
        }
    else
        {
        // Extract option value
        $zip5 = $argv [1];

        // Get weather lines of text
        $weatherForecastLinesArray = array ();

        // Get lines of weather text
        if (getWeatherForecast ($zip5, $weatherForecastLinesArray) == 0)
            {
            // Display lines
            foreach ($weatherForecastLinesArray as $weatherForecastLine)
                {
                printf ("%s\n", $weatherForecastLine);
                }

            // Successful
            $rc = 0;
            }
        }

    // Returns status code to the operating system
    return ($rc);
    }

function getWeatherForecast ($zip5, &$weatherForecastLinesArray)
    {
    // Initialize to failure, set to 0 upon success
    $rc = 1;

    // Create a constant that points to the REST API
    define (WUNDERGROUND_API_URL,
    "http://api.wunderground.com/auto/wui/geo/ForecastXML/index.xml?query=$zip5");

    // Get the weather text -- returned as XML
    if (($wundergroundStr = file_get_contents (WUNDERGROUND_API_URL)) == FALSE)
        {
        printf ("ERROR: file_get_contents (WUNDERGROUND_API_URL) failed.\n");
        }
    else
        {
        // Create the XML array from the returned data
        $wundergroundXml = new SimpleXMLElement ($wundergroundStr);

        // Extract the text fields
        $forecastday = $wundergroundXml->txt_forecast->forecastday [0];
        $weatherForecastLinesArray [] = $forecastday->title;
        $weatherForecastLinesArray [] = $forecastday->fcttext . "\n";

        // Successful
        $rc = 0;
        }

    return ($rc);
    }

?>

Technologies come and go, but good working practices last forever.

The easiest mistakes to fix are the ones you don’t make.

• People like to work with people they like.
• A genuine smile and a positive attitude goes a long way.
• Respect everyone — you can learn from everyone.

Be Collaborative

• Work hard to build concensus among stakeholders.
• Be willing to compromise.
• If you don’t agree with an idea, suggest creative alternatives that can incorporate the idea in different ways.

Be a Great Listener

• What does the user really need?
• It’s not what you want — it’s what they want.
• Listen objectively. Ask open ended questions. Allow everyone the opportunity to speak.

Deliver Some Early Pieces Quickly

• Lets your user know you’ve been listening.
• Gives users an opportunity for feedback.
• Keeps the conversation going in a positive direction.