PHP it’s self doesn’t have any native ability to multithread, which I remember as being a bit of an irritant when I started using the language, but you can use a couple of tricks to achieve a similar result.

Consider this scenario

Our SMS Gateway interface (or API) is accessed via an RESTful web service (HTTP POST) or our simple HTTP GET api, these services offer a simple way to integrate with us, however there are draw backs the main one being the speed at which you can send data to the interface in a serial fashion.

Imagine the following: Lets assume you want to send 10,000 text messages as fast as possible to the api, your method would do something like the following:

• construct data (your fully formed HTTP request)
• open port
• write data
• read response
• close port
• repeat 10,000 times

With PHP this process is carried out in a linear fashion in the context of a loop, now let’s look at the numbers:

Internet latency to the api is an assumed 10ms, which would put you somewhere in the UK

The ‘system’ that is the speed at which we can read and write back to your script is .5 ms

Total process time is 105000 ms or 105 seconds .. but wouldn’t it be nice to go quicker??

Now this is where in parallel or multi threading would come in handy, if we could kick say 5 of these processes off at once then we could send the same amount of texts in 105 / 5 which is 21 seconds and a vast improvement.

So how can this be done?

Say hello to the Curl Extension http://uk3.php.net/curl this isn’t necessarily included with your vanilla build of PHP so you’ll need to compile it in. The Curl extension offers many extras for the PHP developer one of which will will use to do our multithreading.

It is usually best to explain the idea by example, here ‘s a class called DoMultiThread that shows the basic idea

<?php

class DoMultiThread {

//// i’m not going to simulate a 10,000 volume send but you can get the idea!

// some dummy data an array of 5 names and numbers for constructing unique messages

private $names = array (array (“name” => “peter”, “number” => “077122345566″ ),

array (“name” => “fred”, “number” => “077122345567″ ),

array (“name” => “susan”, “number” => “077122345568″ ),

array (“name” => “jim”, “number” => “077122345569″ ),

array (“name” => “katie”, “number” => “077122345510″ ) );

function __contruct() {

/// function sets up and sends 5 simultaneous threads

/// returns an array of the 5 outputs

$output = $this->execute ();

}

protected function execute() {

$mh = curl_multi_init ();

$handles = array (); /// will hold all our handle instances

/// create our 5 threads, i wouldn’t advise trying many more

foreach ( $names as $item ) {

// create a new single curl handle

$curl_handle = curl_init ();

// our unique transaction / message

$url = “http://www.textmarketer.biz/gateway/?username=user&password=pass&message=Hi ” . $item ['name'] . “&orig=test&number=” . $item ['number'];

// setting several options like url, timeout, returntransfer

curl_setopt ( $curl_handle, CURLOPT_URL, $url );

curl_setopt ( $curl_handle, CURLOPT_HEADER, 0 );

curl_setopt ( $curl_handle, CURLOPT_RETURNTRANSFER, true );

curl_setopt ( $curl_handle, CURLOPT_TIMEOUT, 30 );

// add to the curl multi handle, this allows us to do the multi threading

curl_multi_add_handle ( $mh, $curl_handle );

// we will need to access the indvidual handles later

$handles [] = $curl_handle;

}

// execute the multi handle

$running = null;

do {

curl_multi_exec ( $mh, $running );

// it’s a good idea to reduce load, here it’s 1 micro second

usleep ( 10000 );

} while ( $running > 0 );

// get the content of the transaction, this will contain (in our case) things like the transaction id, credits remaining etc

for($i = 0; $i < count ( $handles ); $i ++) {

// get the content of the handle

$output [] = curl_multi_getcontent ( $handles [$i] );

// remove the handle from the multi handle

curl_multi_remove_handle ( $mh, $handles [$i] );

}

// close the multi curl handle to free system resources

curl_multi_close ( $mh );

return $output;

}

}

?>

In our REST API specification document we saw, in general terms, how to make a request to our REST SMS API and how to deal with the response. Here we provide you with some more concrete examples that you can copy & paste!

NOTE: You will want to add additional error checking to the examples below.

In each of the languages used here we create a request, send it, receive the response, and parse its contents.

PHP

Example for getting the number of credits:

$url = 'http://www.textmarketer.biz/services/rest/credits';
$username = 'myAPIusername'; // CHANGE THIS!!!
$password = 'myAPIpassword'; // CHANGE THIS!!!
$url = "$url?username=$username&password=$password";

// we're using the curl library to make the request
$curlHandle = curl_init();
curl_setopt($curlHandle, CURLOPT_URL, $url);
curl_setopt($curlHandle, CURLOPT_RETURNTRANSFER, true);
$responseBody = curl_exec($curlHandle);
$responseInfo  = curl_getinfo($curlHandle);
curl_close($curlHandle);

// deal with the response
if ($responseInfo['http_code']==200)
{
	$xml_obj = simplexml_load_string($responseBody);
	$credits = (int) $xml_obj->credits;
	// do something with the result
	echo $credits;

} else {
	// handle the error
	var_dump($responseBody);
}

Example for getting the list of delivery reports:

$url = 'http://www.textmarketer.biz/services/rest/deliveryReports';
$username = 'myAPIusername'; // CHANGE THIS!!!
$password = 'myAPIpassword'; // CHANGE THIS!!!
$url = "$url?username=$username&password=$password";

// we're using the curl library to make the request
$curlHandle = curl_init();
curl_setopt($curlHandle, CURLOPT_URL, $url);
curl_setopt($curlHandle, CURLOPT_RETURNTRANSFER, true);
$responseBody = curl_exec($curlHandle);
$responseInfo  = curl_getinfo($curlHandle);
curl_close($curlHandle);

// deal with the response
if ($responseInfo['http_code']==200)
{
	$xml_obj = simplexml_load_string($responseBody);
	$atts = $xml_obj->reports->attributes();
	$num_reports = (int) $atts->quantity;

	if ($num_reports > 0)
	{
		echo "$num_reports reports\n";
		$reports = array();
		foreach ($xml_obj->reports->report as $xml_report)
		{
			$atts = $xml_report->attributes();
			$name = (string) $atts->name;
			$updated = (string) $atts->last_updated;
			$reports[] = array('name'=>$name, 'modified'=>$updated);
		}
		// do something with the report details
		var_dump($reports);
	} else {
		echo 'No reports available';
	}
} else {
	// handle the error
	var_dump($responseBody);
}

Example for getting the details of a particular delivery report:

// TODO the URL will change according to the delivery report to retrieve...
$url = 'http://www.textmarketer.biz/services/rest/deliveryReport/GatewayAPI_09-02-10';
$username = 'myAPIusername'; // CHANGE THIS!!!
$password = 'myAPIpassword'; // CHANGE THIS!!!
$url = "$url?username=$username&password=$password";

// we're using the curl library to make the request
$curlHandle = curl_init();
curl_setopt($curlHandle, CURLOPT_URL, $url);
curl_setopt($curlHandle, CURLOPT_RETURNTRANSFER, true);
$responseBody = curl_exec($curlHandle);
$responseInfo  = curl_getinfo($curlHandle);
curl_close($curlHandle);

// deal with the response
if ($responseInfo['http_code']==200)
{
	$xml_obj = simplexml_load_string($responseBody);

	$reportRows = array();
	foreach ($xml_obj->report->reportrow as $xml_reportRow)
	{
		$atts = $xml_reportRow->attributes();
		$mobile = (string) $atts->mobile_number;
		$updated = (string) $atts->last_updated;
		$msgID = (int) $atts->message_id;
		$status = (string) $atts->status;
		$reports[] = array('mobile'=>$mobile, 'modified'=>$updated, 'messageID'=>$msgID, 'status'=>$status);
	}
	// do something with the report details
	var_dump($reports);

} else {
	// handle the error
	var_dump($responseBody);
}

Example for sending an SMS:

$url = 'http://www.textmarketer.biz/services/rest/sms';
$username = 'myAPIusername'; // CHANGE THIS!!!
$password = 'myAPIpassword'; // CHANGE THIS!!!

$data = array('message'=>'hello','mobile_number'=>'447777777777', 'originator'=>'me',
	'username'=>$username, 'password'=>$password);
$data = http_build_query($data, '', '&');
// we're using the curl library to make the request
$curlHandle = curl_init();
curl_setopt($curlHandle, CURLOPT_URL, $url);
curl_setopt($curlHandle, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curlHandle, CURLOPT_POSTFIELDS, $data);
curl_setopt($curlHandle, CURLOPT_POST, 1);
$responseBody = curl_exec($curlHandle);
$responseInfo  = curl_getinfo($curlHandle);
curl_close($curlHandle);

// deal with the response
if ($responseInfo['http_code']==200)
{
	$xml_obj = simplexml_load_string($responseBody);
	// do something with the result
	echo "Message ID: $xml_obj->message_id\n";
	echo "Credits used: $xml_obj->credits_used\n";

	var_dump($responseBody);

} else {
	// handle the error
	var_dump($responseInfo);
	var_dump($responseBody);
}

Example for transferring credits:

<?php
/**
 * POST request on the 'credits' resource (credit transfer)
 */
$url = 'http://www.textmarketer.biz/services/rest/credits';
// for testing:
//$url = 'http://sandbox.textmarketer.biz/services/rest/credits';
$username = 'myAPIusername'; // CHANGE THIS!!! - the username of the account you're transferring FROM
$password = 'myAPIpassword'; // CHANGE THIS!!!
$targetAccountNumber = 0; // CHANGE THIS!!

$data = array('quantity'=>'1','target'=>$targetAccountNumber,
	'username'=>$username, 'password'=>$password);
$data = http_build_query($data, '', '&');
// we're using the curl library to make the request
$curlHandle = curl_init();
curl_setopt($curlHandle, CURLOPT_URL, $url);
curl_setopt($curlHandle, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curlHandle, CURLOPT_POSTFIELDS, $data);
curl_setopt($curlHandle, CURLOPT_POST, 1);
$responseBody = curl_exec($curlHandle);
$responseInfo  = curl_getinfo($curlHandle);
curl_close($curlHandle);

// deal with the response
if ($responseInfo['http_code']==200)
{
 // success - you may want to read in the return data here to see how many credits were  left on each account

} else {
	// handle the error here
	// var_dump($responseInfo);
	// var_dump($responseBody);
}

?>

For more details on creating REST requests in PHP, see here.

To create an interactive game using Text Messaging and to show how easy it is to create interactive experiences using your Text Marketer Account. The example uses both our short code API (to receive the customer responses) and then our  gateway API to send out the ‘answer’.

The Game

Guess the number of sweets in a jar. A simple game where the participant texts in the number of sweets they think is in the jar and then receives a message indicating if they are high,  low , close or have correctly guessed to the number of sweets. Download all the required classes.

Mechanics

Fig 1 shows the how the basic flow of the systems works. The game is initiated by an incoming text message (as shown in orange) to our 88802 shortcode. The text message contains a keyword  in this case sweets and the data you which you need to parse.

Once the text message has been received in your account you can enable a trigger to be sent to your own script residing on your own server. The trigger is a GET request with the parameters added to it as per our short code documentation.

Your application/script can then use the data to geenrate a response. In our case we find out whether the participant has guessed the correct number and we send back an apporprate response using the Text Marketer API  Gateway see documentation for details.

Creating the game and code examples

The Guess number of sweets in a jar game and all the code you need can be downloaded here. It’s written in PHP 5.

Once you have created yourself a free account you need to request a free shortcode keyword from Text Marketer.

Next login into your account and set the url your wish to use for accessing your script. To access the set up screen, select from the menu “Incoming SMS” => “Change Reply Settings” then click “Configure” next to the keyword. You’ll then be able to paste the URL into the API URL window. Then press submit.

The game is broken the code down into 4 classes.

class SweetsInAJar

{

    function __construct()

    {

    $sms = new SendSMSXML("myUsername","myPassword");

    $theData = new ExtractData("sweets",$_GET['message'],$_GET['number']);

    $logic = new MessageLogic();

    $logic->setClosenessRangeInPercent(15);

    if($theData->isValid()){

       $sms->send($theData->getNumber(),$logic->getMessage($theData->getData()),"GuessGame");

    }

    else

    {

       $sms->send($theData->getNumber(),$logic->getFailedMessage(),"GuessGame");

     }

   }

}

Explanation
This is our main class that calls all the relevant objects and class together. Simply the logic works like this:

1. Set up all the objects you need.
2. Set the closeness to the number of sweets you will need to get before the “your are close” message will get sent .
3. If there is data we can use from the incoming message,  select the correct response and send it.
4. Otherwise select the “invalid format message” and send that.

class ExtractData

{
   private $theData;
   private $theMobileNumber;
   private $keyword;
   private $valid=false;
	

   function __construct($keyword,$message,$number)
   {
      $this->keyword = $keyword;
      $this->valid = $this->getMessageInfo($message);
      $this->theMobileNumber = $number;
    }

    public function isValid()

    {		

       return $this->valid;

     }

     public function getData()

     {

       return $this->theData;

     }

      public function getNumber()
      {
        return $this->theMobileNumber;
      }

      private function getMessageInfo($m)
      {
         //remove the keyword and set the result
	 //remove extra spaces
         $m=trim($m);

         $m=str_ireplace($this->keyword,"",$m); /// remove keyword
         $m=ltrim($m); // remove any spaces

         if(is_numeric($m)) {

              $this->theData = $m;
              return true; // is it data?
          }

           else return false;
      }

}

Explanation
This simple class allows us to extract the data we need from the short code response. The response contains the enitre message so we need to remove the keyword and any spaces then check to see if the result is a number.  If it is then the object is “valid” else it’s not valid and we can use this state to send the “invalid format message” as described above.

class MessageLogic

{

    private static $lowGuess ="Bad Luck! There are more sweets in the jar than you think, try again.";
    private static $highGuess="Bad Luck! There are less sweets in the jar than you think, try again.";
    private static $correctGuess="Well done! You have guessed the correct amount.";
    private static $closeGuess="Close Guess! you are within {value}% of the correct answer.";
    private static $badData="We couldn't understand your answer please text in the word SWEETS and your answer, for example SWEETS 300";
    private $numSweets=5678; //default
    private $closenessRange=5;  //5 percent as default 

	
    public function setNumberOfSweets($value)

    {
         $this->numSweets=$value;
    }

    public function setClosenessRangeInPercent($value) //in percent
    {
         $this->closenessRange=$value;
    }

    public function getFailedMessage()

    {
         return self::$badData;
    }

    public  function getMessage($value)
    {
         /// some very simple rules
         if($value==$this->numSweets) return self::$correctGuess;
         $isClose = round(((abs($this->numSweets - $value)) / $this->numSweets) * 100); // calculate how close the number is
         if($isClose < $this->closenessRange) return str_replace("{value}",$this->closenessRange,self::$closeGuess);    // if with in the closeness range return close messsage
         else{
              if($value > $this->numSweets) return self::$highGuess;
              else return self::$lowGuess;
         }
     }
}

Explanation

This is the game logic class, the getMessage function requires the integer that we extracted using the ExtractData class.  There are then some simple rules that select the appropriate message as the returned value.

2 classes available in php 5, SendSMS and SendSMSXML (recommended)

Class Name: SendSMS (depreciated)

This class is a nice and easy way to start sending SMS’s with the Text Marketer system, please feel free to modify at will. You just need the username and password from your account login as the constructor arguments.

Download the PHP 5 SMS API Class

Example of use

<?

$sms = new SendSMS("myUsername","myPassword");
if($sms->send("4477777777","my message","me")) echo "message sent";
else echo "message failed";

?>

Class Name: SendSMSXML

An updated class from SendSMS which uses the XML response and is simpler to use, please feel free to modify at will. You just need the username and password from your account login as the constructor arguments.

Download PHP 5 SMS API Class

Example of use

<?

$sms = new SendSMSXML("myUsername","myPassword");
if($sms->send("4477777777","my message","me")){

 	echo "I have ".$sms->getCreditsRemaining()." left and I used  ".$sms->getCreditsUsed()." credits";

}

else {

     while($error = $sms->getError())

     {

         echo $error;

     }

}

?>

This class enables you to access your delivery reports in a nice simplified way. You can search for the outcome of a message for a given number, specify the outcome and the number, download all the data for the given date or parse the reports line by line.

The constructor requires the delivery report directory that is shown in your account. To find your  delivery report directory, log into your system click the menu heading “Reports” then select “Delivery Reporting”, you will see a green icon, roll over this and you can find the directory name at the bottom.

If you have sent a message greater than 160 characters you will find multiple entries for that particular number . For instance if your message was 200 characters you will find 2 reports for that number. A message is built from 160 chunks

Download the PHP 5 Delivery Report Class

Example of use

<?

$reports = new ProcessDeliveryReport ( "Kt65CZMtxlIiEU328ilCBgC38" ); // your delivery report directory
if ($reports->setReportDate ( "20-05-09" )) print_r ( $reports->findNumber ( "44777777777", "r" ) ); // print the array of results
else echo "Not found";

?>

This class is designed around the FREE Text Marketer SMS API, you need to sign up here to use it.

SendSMSNotifier is a singleton class design, incorporating listeners. Your class must include the following public functions: creditAlert($credits_remaining) and failureAlert($error,$number,$message,$error).

Download the class from here

Example of use

class MyTestClass
{

        /// simple array of data in: number, message, sender Id (aka originator) format, ideally the data will come from a database
	private $mySMSdata = array(array("44777777777","Hello World!","Me"),
			                             array("text","This will throw an error, mobile number is text","Me"));

	function __construct()
	{
		$sms = SendSMSNotifier::getInstance("myUsername","myPassword"); // your account login details
		$sms->addListener($this); // Your class gets added to the listeners that will get notified on an event
		$sms->setCreditThreshold(5); // You want o be notified when you have 5 credits left

		foreach($this->mySMSdata as $record) // send some data
		{
			list($number,$message,$sender) = $record;
			$sms->send($number,$message,$sender); // send to the api
		}
		echo $sms->getCredits();
		print_r($this->errors);
	}

	public function failureAlert($error,$number,$message,$originator)
	{
		/// Required function for failure messages, you could stop the sending here or log the results
		$this->errors[] = array($error,$number,$message,$originator);
	}

	public function creditAlert($credits)
	{
		/// Required function for credit alerts, this basic implementation stops sending anymore SMS's
		die("I have nearly run out of credits($credits left), abandon sending!");
	}
}

So here’s what happens. You send a bunch of text messages to the gateway using your class (in this example MyTestClass), if you get a failure such as a badly formatted number your function failureAlert gets called with the parameters of the failure and data, you can then decide on the implmentation. In the above example it just stores them in an array, once you have sent all the data you could then use the data to clean your database etc.

If the credit limit (in the above case this is 5 $sms->setCreditThreshold(5) ) your function creditAlert will get called, in this case we think this is bad so we use the hammer of the die() function to stop the sending, obviously you would handle this much more elegantly :-)