php-bulksms

website & users' manual for the php class

Official links directly maintained by the author of this class (LiamHatton):\n* ''[[Official website for php-bulksms|http://php-bulksms.liam.hatton.name]]''\n* ''[[PHP Classes project page|http://lhatton.users.phpclasses.org/browse/package/2257.html]]''\n* ''[[Public forum on Yahoo! Groups:|http://groups.yahoo.com/group/php-bulksms/]]'' used for new version announcements and user support,\n* ''[[Project listing on freshmeat.net|http://freshmeat.net/projects/php-bulksms/]]''\n\nThe following web sites are not affiliated with this class or the author:\n* ''[[BulkSMS website:|http://www.bulksms.com/]]'' website for the service this PHP class is written for,\n* ''[[BulkSMS EAPI documentation:|http://bulksms.vsms.net/docs/eapi/]]'' documentation for user development based on the BulkSMS HTTP API,\n* ''[[Net::SMS::BulkSMS:|http://search.cpan.org/~pedwards/Net-SMS-BulkSMS-1.00/]]'' Perl API on CPAN,\n* ''[[sendbulksms:|http://sendbulksms.sourceforge.net/]]'' Perl API,\n* ''[[pybulksms:|http://botanicus.net/dw/homepage.php]]'' Python API.

A TiddlyWiki is like a blog because it's divided up into neat little chunks, but it encourages you to read it by hyperlinking rather than sequentially: if you like, a non-linear blog analogue that binds the individual microcontent items into a cohesive whole. \n\nFor more information or to create your own TiddlyWiki, please visit the [[TiddlyWiki website|http://www.tiddlywiki.com/]].

Welcome to the website and users' manual for php-bulksms, a PHP class for the purpose of sending SMS (short text messages) to mobile phones from your PHP scripts using the BulkSMS service.\n\nThis website is a single self-contained hypertext document using a MicroContent WikiWikiWeb called TiddlyWiki. It's written in HTML, CSS and JavaScript to run on any modern browser without needing any server-side logic. See UsingThisSite for more information on how to use this page.

Liam Hatton is the author of php-bulksms. His website is located [[here|http://liam.hatton.name/]], or you can send him an e-mail at [[liam@hatton.name|mailto:liam@hatton.name]], however please forward all support questions and comments to the MailingList so the answers can be available for the benefit of all people.

{{{bulksms->send_sms(@@color(red):array( … )@@, @@color(green):$quote=(false (default)|true)@@);}}}\n\nMethod for sending an SMS. Requires an array to be sent to it containing parameters like those listed in the [[EAPI documentation|http://bulksms.vsms.net/docs/eapi/submission/send_sms/]]. Returns a StatusCode – this code can be checked to see whether the command has succeeded or not.\n\n$quote is an optional parameter which defaults to false if it is not specified. If this parameter is set to true, it will obtain a price quote (using the EAPI function get_quote) but will not send the SMS. If you are obtaining a price quote, the quotation can be read using the [[get_quotation]] method.\n\n----\n\n//Example #1: Sending an SMS://\n{{{\ninclude_once('bulksms.php');\n$sms = new bulksms;\n$vars = array("message" => "Hello, this is a test", "msisdn" => "61433315882");\nif($sms->send_sms($vars) == SUCCESS) {\n echo "Message sending succeded";\n} else {\n echo "There was an error, status code: ".$sms->get_status();\n}\n}}}\n\n//Example #2: Getting a price quote for sending an SMS://\n{{{\ninclude_once('bulksms.php');\n$sms = new bulksms;\n$vars = array("message" => "Hello, this is a test", "msisdn" => "61433315882");\nif($sms->send_sms($vars, true) == SUCCESS) {\n echo "Cost to send SMS (in credits): ".$sms->get_quotation();\n} else {\n echo "There was an error, status code: ".$sms->get_status();\n}\n}}}

{{{bulksms->get_credits();}}}\n\nRetrieves the remaining credit balance in your BulkSMS account. Returns a status code – this code can be checked to see whether the command has succeeded or not. After executing this function, retrieve your credit balance using [[get_response]].\n\n----\n\n//Example #1: Checking credit balance://\n{{{\ninclude_once('bulksms.php');\n$sms = new bulksms;\nif($sms->get_credits() == SUCCESS) {\n echo "Remaining credit balance: ".$sms->get_response();\n} else {\n echo "There was an error, status code: ".$sms->get_status();\n}}}\n\n

For push/manual retrieval of incoming messages:\n* [[get_inbox]]: retrieve inbox\n* [[get_status_report]]: get a status report for a particular SMS message\n\nFor handling messages pushed to the script by the BulkSMS servers (where the arrangement has been made with BulkSMS to do so):\n*[[load_incoming_vars]]: initialise/load incoming message variables,\n*[[get_incoming_obj]]: get incoming message information as an array.

{{{bulksms->get_status_report(@@color(red):array( … )@@);}}}\n\nAllows you to get status information for a message you have previously sent. Requires an array to be sent to it containing parameters like those listed in the [[EAPI documentation| http://bulksms.vsms.net/docs/eapi/submission/send_sms/]]. Returns a StatusCode – this code can be checked to see whether the command has succeeded or not.\n\n//Note: This method is not recommended by BulkSMS unless there is no other option - it is apparently better to have BulkSMS set up their system to send status reports via HTTP to your server directly. There are functions implemented in this class to handle this sort of arrangement documented here under the section IncomingMessages.//\n\nYou need to read the response using the [[get_response]] method. The response is in a multidimensional array, like this:\n\n{{{\nArray\n(\n [1] => Array // First object\n (\n [0] => 6143315882 // MSISDN\n [1] => 10 // Status Code\n )\n)\n}}}\n\nEach line returned is a new array item $array[x], with each item containing the information returned to this function by the EAPI. Please see the [[EAPI documentation|http://bulksms.vsms.net/docs/eapi/status_reports/get_report/]] for more information.\n\n----\n\n//Example #1: Printing status information://\n{{{\ninclude_once('bulksms.php');\n$sms = new bulksms;\nif($sms->get_status_report(array("batch_id" => "000")) == SUCCESS) {\n echo "Status report array:\n"\n print_r($sms->get_response());\n} else {\n echo "There was an error, status code: ".$sms->get_status();\n}\n}}}

Functions to add SMS messages to a queue, and send them all at once using EAPI functions.\n*[[push_sms_to_queue]]: add an SMS to the queue,\n*[[del_sms_from_queue]]: delete an SMS from the queue,\n*[[clear_queue]]: clear the queue,\n*[[get_queue]]: get the message queue as an array,\n*[[process_queue]]: process and send the messages in the queue.

Functions used for basic implementation of SMS services.\n*[[send_sms]]: send a SMS or get a price quote;\n*[[get_credits]]: get credit balance for your account.\n\nAlso see ResponseInfo & StatusCode for response and status information after running a function.

Used to retrieve a response, status or error code after you run a function.\n*[[get_status]]: returns StatusCode for method that has previously been run,\n*[[get_eapi_status_code]] & [[get_eapi_status_msg]]: returns status code or message returned by BulkSMS EAPI,\n*[[get_batch_id]], [[get_response]] & [[get_quotation]]

BulkSMS is a service offered by Celerity Systems Pty Ltd (SA), providing SMS gateway services to mobile telephones worldwide. I am not affiliated with Celerity Systems or BulkSMS in any way; I am merely a customer. Therefore, I cannot assist in support questions regarding their service.\n\nPlease visit the [[BulkSMS website|http://www.bulksms.com/]] for more information.

php-bulksms is open source and licensed under the LGPL (Lesser GNU Public License). The major difference between the standard and common GPL versus the lesser-known LGPL licence is that use in proprietary programs (ie. not open source) is permitted. A copy of this license is included in the official distribution archive.\n\nPlease visit the [[GNU LGPL website|http://www.gnu.org/copyleft/lesser.html]] to see more information about this license.

A forum on Yahoo! Groups exists for the purpose of user discussion, announcements and support. It is currently a low volume mailing list (approx. 1-2 messages a month) and it is strongly recommended that you subscribe to receive announcements for new releases of the class.\n\n* ''Subscribe to the list:'' send a blank e-mail to [[php-bulksms-subscribe@yahoogroups.com|mailto:php-bulksms-subscribe@yahoogroups.com]] or subscribe to the RSS feed at http://rss.groups.yahoo.com/group/php-bulksms/rss\n* ''Unsubscribe to the list:'' send a blank e-mail to [[php-bulksms-unsubscribe@yahoogroups.com|mailto:php-bulksms-unsubscribe@yahoogroups.com]]\n* ''Post to the list:'' send your message to [[php-bulksms@yahoogroups.com|mailto:php-bulksms@yahoogroups.com]]\n* ''List archives & website:'' http://groups.yahoo.com/group/php-bulksms/

This class has the option of an inbuilt number list, ie. you can add numbers to the list in your PHP scripts (by, for example, reading them from a database) and send them all a short text message at once. There are a number of processing functions to make it easier to handle long lists of numbers.\n*[[get_number_list]]: returns an array containing all the numbers added to the list,\n*[[add_number_to_list]]: adds a number to the list,\n*[[del_number_from_list]]: removes a number from the list,\n*[[clear_list]]: erases the entire number list,\n*[[send_to_list]]: send to the numbers in the number list,\n*[[list2group]]: exports the number list to a PublicGroup.

Used to fix a number so it is correctly formatted for use with BulkSMS (for example, a number that a user has entered) or to check to see if a number is in the correct format.\n*[[fix_number]]: fixes a phone number into the correct format\n*[[check_number]]: checks to see if a number sent to it is already in the correct format.

{{{bulksms->load_incoming_vars(@@color(red):$password@@, @@color(green):$type=(AUTO (default) | INBOX | STATUS)@@);}}}\n\nThis function is for loading IncomingMessages and is put near the top of your script before you do anything else. The password that you have arranged with BulkSMS for HTTP message pushing needs to be specified. The second parameter is optional, it is set to AUTO (0) by default which means it will automatically guess the type of message being pushed, otherwise you can specify it as INBOX (2) for incoming inbox messages, or STATUS (1) for incoming status reports.\n\nThis function will also output headers to prevent caching in case your web server uses a reverse proxy. Do not output anything to the user when using this function because it will cause problems with setting the headers, and it will automatically output a sort of status code back to the BulkSMS server so there is no need to send anything back. If you experience errors with this relating to setting the HTTP headers and you have made sure you are not outputting anything to the user in your script, it is probably because there is some white space before the <?php tag in your script.\n\nThe script that you use for handling incoming messages should be hidden somewhere publicly on your webserver so it is not accessible to users, and it is a good idea to specify in your robots.txt file to prevent search bots from indexing the script.\n\nThis function will return [[FATAL]] (-1) if there is something wrong with the input provided, or [[SUCCESS]] (1) if the operation is successful.\n\n----\n\n//Example #1: Framework for incoming message handling script://\n{{{\n<?php\ninclude_once('bulksms.php');\n$sms = new bulksms;\nif($sms->load_incoming_vars("password") == SUCCESS) {\n $msg = get_incoming_obj();\n switch($msg['incoming_type']) {\n case INBOX:\n // Put handling code for new inbox messages here.\n break;\n case STATUS:\n // Put handling code for status reports here.\n break;\n }\n} else {\n // It looks like somebody probably accessed the script directly.\n} ?>\n}}}

See StatusCode.

See GettingStarted.

See StatusCode.

{{{bulksms->get_inbox(@@color(red):array( … )@@);}}}\n\nRetrieves the contents of your message inbox. Can be sent an array containing parameters like those listed in the [[EAPI documentation|http://bulksms.vsms.net/docs/eapi/reception/get_inbox/]], but if no parameters are sent to it, it will retrieve all messages in your inbox. Returns a StatusCode – this code can be checked to see whether the command has succeeded or not.\n\n//Note: This method is not recommended by BulkSMS unless there is no other option - it is apparently better to have BulkSMS set up their system to send new messages via HTTP to your server directly. There are functions implemented in this class to handle this sort of arrangement documented here under the section IncomingMessages.//\n\nYou need to read the response using the [[get_response]] method. The response is in a multidimensional array, like this:\n\n{{{\nArray\n(\n [1] => Array // First message.\n (\n [0] => 57770 // Message ID\n [1] => 61433315882 // MSISDN of sender\n [2] => Test // Message\n [3] => 2005-04-11 14:39:44 // Date & Time\n [4] => 447797803200 // MSISDN that received the message\n [5] => 43722027 // Referring message id.\n )\n)\n}}}\n\nEach message is a new array item $array[x], with each array item containing the information returned to this function by the EAPI. Please see [[the EAPI section|http://bulksms.vsms.net/docs/eapi/reception/get_inbox/]] for more information. If there are no messages, this method will return a [[StatusCode]] of 1 ([[SUCCESS]]), but when you use [[get_response]], the response will be NULL.\n\n----\n\n//Example #1: Listing messages in the inbox://\n{{{\ninclude_once('bulksms.php');\n$sms = new bulksms;\nif($sms->get_inbox() == SUCCESS) {\n $msgs = $sms->get_response();\n if(!$msgs) {\n echo "No messages in your inbox.";\n } else {\n echo count($msgs)." inbox messages, as follows:\n\n"\n foreach($msgs as $item) {\n echo "Message ID: ".$item[0]."\n";\n echo "Sender: ".$item[1]."\n";\n echo "Message: ".$item[2]."\n";\n echo "Date & Time: ".$item[3]."\n";\n echo "MSISDN: ".$item[4]."\n";\n echo "Referring message ID: ".$item[5]."\n\n";\n }\n }\n} else {\n echo "There was an error, status code: ".$sms->get_status();\n}\n}}}

{{{bulksms->get_incoming_obj();}}}\n\nThis function will return an array containing the information pushed to the script (ie. inbox message or status report). It is similar to simply reading the $_GET array, but at this time it adds one more field called 'incoming_type' which is for the message type, and is either set to INBOX (1) for new inbox message or STATUS (2) for status reports. \n\nSee [[here|http://bulksms.vsms.net/docs/eapi/reception/http_push/]] and [[here|http://bulksms.vsms.net/docs/eapi/status_reports/http_push/]] for more information on the parameters that are sent by BulkSMS.

HelloThere\nMailingList\nRelatedLinks\nLicenseInfo\nChangeList\n\n''About this page''\nTiddlyWiki\nUsingThisSite\nSaveChanges\n\n''Documentation''\nGettingStarted\n\n''Implementation''\nSimpleFunctionality\nIncomingMessages\nNumberList\nPublicGroup\nMessageQueuing\nNumberFormatting\nResponseInfo\nStatusCode\n\n© LiamHatton 2005

{{{bulksms->check_number(@@color(red):$num@@);}}}\n\nChecks to see if a number sent to it is in the correct format for use with BulkSMS. Returns Boolean - true if the number is in the correct format, otherwise it returns false.\n\n----\n\n//Example #1: Checking phone numbers.//\n{{{\ninclude_once('bulksms.php');\n$sms = new bulksms;\n$arr = array("61433315882", // will evaluate as correct\n "01161433315882", // will evaluate as invalid (IDD code)\n "12345", // will evaluate as invalid (too short)\n "+61-433315882", // will evaluate as invalid (invalid characters)\n "61 433 315 882" // will evaluate as invalid (whitespaces)\n );\nforeach($arr as $i) {\n if($sms->check_number($i) == true) {\n echo $i.": correct\n";\n } else {\n echo $i.": incorrect\n";\n }\n}\n}}}

{{{bulksms->get_number_list();}}}\n\nReturns an array containing all the numbers added to the list.

{{{bulksms->clear_list();}}}\n\nErases the entire number list.

{{{send_to_list(@@color(red):array( … )@@, @@color(green):$quote=(false (default)|true), $remove_dups=(false (default)|true), $split=(int or NULL)@@);}}}\n\nCalls the [[send_sms]] method to send to the numbers in the number list. First parameter is required and is an array containing parameters like those listed in the EAPI documentation [[here|http://bulksms.vsms.net/docs/eapi/submission/send_sms/]]. \n\nFirst parameter is optional and set as false by default. When it is set to true, it will use quote_sms and get a price quote for sending the message to the list rather than actually sending the message.\n\nSecond parameter is set as false by default and is optional. When it is set to true, it will remove all duplicate numbers from the number list before sending.\n\nThird parameter is optional and is set as NULL by default. When set as an integer, it will split the list into the size as specified and send the list in chunks. If your list is larger than 5000 numbers, this function will automatically split the list otherwise you might experience timeouts. Please note that this class is untested and not recommended for large lists of numbers - I suggest writing your own software instead if you need to send to a large list of recipients.\n\nIf the number list is split, when you use [[get_status]], [[get_batch_id]], [[get_eapi_status_code]], [[get_eapi_status_msg]], [[get_eapi_status_msg]] & bulksms->get_quotation() you will get back an array containing the information for each iteration of [[send_sms]]. Also, in this case, this method will also return an array containing the status codes returned by each iteration of [[send_sms]]. If the number list is not split, these commands will act as normal like [[send_sms]].\n\n----\n\n//Example #1: Adding numbers to the list and sending a SMS (simple)://\n{{{\ninclude_once('bulksms.php');\n$sms = new bulksms;\n$sms->add_number_to_list('61433315882');\n$sms->add_number_to_list('18005551212');\n$vars = array("message" => "Hello, this is a test.");\nif($sms->send_to_list($vars) == SUCCESS) {\n echo "Message sending succeded";\n} else {\n echo "There was an error, status code: ".$sms->get_status();\n}\n}}}\n\n//Example #2: Adding an array of numbers and sending an SMS to the list://\n{{{\ninclude_once('bulksms.php');\n$sms = new bulksms;\n$arr = array('61433315882', '18005551212', '44987654321', '44123456789');\nforeach($arr as $item) {\n $sms->add_number_to_list($item);\n}\n$vars = array("message" => "Hello, this is a test.");\nif($sms->send_to_list($vars) == SUCCESS) {\n echo "Message sending succeded";\n} else {\n echo "There was an error, status code: ".$sms->get_status();\n}\n}}}\n\n//Example #3: Adding a longer list of numbers and sending an SMS (with split function) to the list://\n{{{\ninclude_once('bulksms.php');\n$sms = new bulksms;\n$sms->add_number_to_list('61433315882');\n$sms->add_number_to_list('18005551212');\n$sms->add_number_to_list('44123456789');\n$sms->add_number_to_list('44987654321');\n$sms->add_number_to_list('44112233445');\n$sms->add_number_to_list('32112233445');\n// … add more numbers here …\n$vars = array("message" => "Hello, this is a test.");\n$status = $sms->send_to_list($vars, false, false, 5);\necho "Sent SMS to list: "\nforeach($status as $i) {\n if($i == SUCCESS) {\n echo "Iteration successful";\n } else {\n echo "Iteration not successful, returned: ".$i;\n }\n}\n}}}

{{{bulksms->add_to_public_group(@@color(red):$group_id, $msisdn,@@ @@color(green):$firstname, $lastname, $fixnumber=(true (default)|false)@@);}}}\n \nAdd a single number to a PublicGroup. This is a new function added in version 0.93 of this class.\n\nRequired parameters include the group ID as the first parameter (specified as $group_id) and phone number as the second. Optional parameters include the first and last name for the user associated with the mobile number (for your reference), and the option $fixnumber which will fix the number using [[fix_number]] unless otherwise specified as false. If $fixnumber is set as false, this function will return [[INPUT_ERR]] (-3) if the number is not in the correct format.\n\nIf the operation was successful, this command will return [[SUCCESS]] (1), otherwise it will return [[FATAL]] (-1).\n\n----\n\n//Example #1: Adding a number to a public group://\n{{{\ninclude_once('bulksms.php');\n$sms = new bulksms;\nif($sms->add_to_public_group("000", "61433315882", "Liam", "Hatton", false) == SUCCESS) {\n echo "Added to public group";\n} else {\n echo "There was an error, status code: ".$sms->get_status();\n}\n}}}

{{{bulksms->list2group(@@color(red):$group_id@@);}}}\n\nExports the number list to a PublicGroup. This is a new function added in version 0.93 of this class.\n\nBecause this function executes an iteration of [[add_to_public_group]] for each number, it may take a while (and create a lot of traffic to the BulkSMS servers, which BulkSMS may not like) if your number list is very large. If there are more than 20-30 numbers in the list, you may need to extend the allowed execution of PHP scripts on your system otherwise you might experience problems with your scripts being terminated before this function has been given adequate time to add all numbers.\n\nThis function automatically removes duplicates from the NumberList, which accelerates the addition process (because BulkSMS doesn't allow duplicate numbers in a group) by requiring less instances of [[add_to_public_group]].\n\nThis function will return an array containing all the status codes for each iteration of [[add_to_public_group]] run.\n\n----\n\n//Example #1: Adding numbers to the list, and exporting the list to a public group://\n{{{\ninclude_once('bulksms.php');\n$sms = new bulksms;\n$sms->add_number_to_list('61433315882');\n$sms->add_number_to_list('18005551212');\n$status = $sms->list2group("000");\necho "Added number list to public group: "\nforeach($status as $i) {\n if($i == SUCCESS) {\n echo "Iteration successful";\n } else {\n echo "Iteration not successful, returned: ".$i;\n }\n}\n}}}

You can create a public group by creating a group using the BulkSMS web interface, and giving it permissions for public addition/deletion of numbers. These functions are ideal if you wish to run your own SMS mailing list, because you can subscribe/unsubscribe numbers using this class and send a message to the entire group using the BulkSMS web interface, or by using the send_sms function.\n*[[add_to_public_group]]: add a single number to a public group,\n*[[del_from_public_group]]: delete a number from a public group,\n*[[list2group]]: exports the NumberList to a public group

{{{bulksms->del_from_public_group(@@color(red):$group_id, $msisdn@@, @@color(green):$fixnumber=(true (default)|false)@@);}}}\n\nDeletes a single number from a PublicGroup. This is a new function added in version 0.93 of this class.\n\nRequired parameters include the group ID as the first parameter (specified as $group_id) and phone number as the second. The only optional parameter is $fixnumber which will fix the number provided using [[fix_number]] unless otherwise specified as false. If $fixnumber is set as false, this function will return [[INPUT_ERR]] (-3) if the number is not in the correct format.\n\nIf the operation was successful, this command will return [[SUCCESS]] (1), otherwise it will return [[FATAL]] (-1).\n\n---- \n\n//Example #1: Deleting a number from a public group://\n{{{\ninclude_once('bulksms.php');\n$sms = new bulksms;\nif($sms->del_from_public_group("61433315882") == SUCCESS) {\n echo "Deleted public group";\n} else {\n echo "There was an error, status code: ".$sms->get_status();\n}\n}}}

{{{bulksms->push_sms_to_queue(@@color(red):$vars@@);}}}\n\nAdds an SMS to the queue. Needs to be sent an array containing variables for the message as defined [[here|http://bulksms.vsms.net/docs/eapi/submission/send_batch/]] (under required and optional CSV columns). Returns a unique ID code associated with the message added to the queue.\n\n----\n\n//Example #1: Adding SMS messages to queue://\n{{{\ninclude_once('bulksms.php');\n$sms = new bulksms;\n$sms->push_sms_to_queue(array("msisdn" => "61400233646", "message" => "Test #1"));\n$sms->push_sms_to_queue(array("msisdn" => "44123456789", "message" => "Test #2"));\n$sms->push_sms_to_queue(array("msisdn" => "12125551212", "message" => "Test #3"));\n}}}

{{{bulksms->del_number_from_list(@@color(red):$num@@);}}}\n\nRemoves a number from the list. This method will only delete the first addition of the number from the list, so if the number is added multiple times, you will need to use this method for each time the number is listed. This function returns 1 ([[SUCCESS]]) if is has successfully deleted the number from the list, or -3 (INPUT_ERR) if the number was not in the list. Therefore, if you wanted to delete a number that has been listed multiple times, you could write a loop to run this method until -3 ([[INPUT_ERR]]) has been returned.\n\n----\n\n//Example #1: Deleting a number, and printing the list.//\n{{{\ninclude_once('bulksms.php');\n$sms = new bulksms;\n$sms->add_number_to_list('61433315882');\n$sms->add_number_to_list('18005551212');\n$sms->del_number_from_list('61433315882');\n$list = $sms->get_number_list();\necho "Numbers in the list:\n";\nforeach($list as $item) {\n echo $item."\n";\n}\n}}}

{{{bulksms->add_number_to_list(@@color(red):$num@@);}}}\n\nAdds a number to the list. Does not check number for correct formatting, use [[check_number]] to do this. Returns a status code of 1 ([[SUCCESS]]), but you don't need to check for this.\n\n----\n\n//Example #1: Adding numbers to the list (simple)://\n{{{\ninclude_once('bulksms.php');\n$sms = new bulksms;\n$sms->add_number_to_list('61433315882');\n$sms->add_number_to_list('18005551212');\n}}}\n\n//Example #2: Reformats numbers, adds them to the list and prints out the number list://\n{{{\ninclude_once('bulksms.php');\n$sms = new bulksms;\n$arr = array('0433315882', '1 800 555 1212', '1800COLLECT', '44123456789');\nforeach($arr as $item) {\n $item = $sms->fix_number($item);\n $sms->add_number_to_list($item);\n}\n$list = $sms->get_number_list();\necho "Reformatted/fixed numbers in the list:\n";\nforeach($list as $item) {\n echo $item."\n";\n}\n}}}\n\n//Example #3: Only adds numbers that are correctly formatted, and prints out the number list://\n{{{\ninclude_once('bulksms.php');\n$sms = new bulksms;\n$arr = array('+61-433-315-882', '1 800 555 1212', '1800COLLECT', '44123456789');\nforeach($arr as $item) {\n if($sms->check_number($item) == true) { // this will only evaluate true for 44123456789\n $sms->add_number_to_list($item);\n }\n}\n$list = $sms->get_number_list();\necho "Correctly formatted numbers added to the list:\n";\nforeach($list as $item) {\n echo $item."\n";\n}\n}}}

{{{bulksms->clear_queue();}}}\n\nClears the message queue completely. Always returns a response code of [[SUCCESS]] (1), but you don't need to check for this.

{{{bulksms->del_sms_from_queue(@@color(red):$id@@);}}}\n\nDeletes an SMS from the queue. Requires the ID for the message you want to delete (as provided by [[push_sms_to_queue]]) and returns a response code of [[SUCCESS]] (1) if it deleted the message from the queue, or [[INPUT_ERR]] (-3) if message associated with the ID could not be found.\n\n----\n\n//Example #1: SMS deletion from queue://\n{{{\ninclude_once('bulksms.php');\n$sms = new bulksms;\n$id = $sms->push_sms_to_queue(array("msisdn" => "61400233646", "message" => "Test"));\n$sms->del_sms_from_queue($id);\necho "Number of messages in queue: ".count($sms->get_queue());\n}}}

{{{bulksms->get_queue();}}}\n\nReturns the message queue as an array.

{{{bulksms->get_status();}}}\n\nReturns StatusCode for method that has previously been run (or an array of status codes if you have used the [[send_to_list]] method). See StatusCode for a list of the status codes used.

{{{\nbulksms->get_eapi_status_code();\nbulksms->get_eapi_status_msg();\n}}}\n\nReturns status code or message returned by BulkSMS's EAPI for method that has previously been run (or an array of status codes if you have used the [[send_to_list]] method). According to BulkSMS, you should not rely on the status message because it might change in future versions of the EAPI - you should only use the status code. There are consonants defined in the script for your convenience, please examine the script if you wish to see the entire list.\n\nIn most cases, it isn't necessary to test for the EAPI status code to see if an operation has been successful, because [[get_status]] will return to you a suitable code for how you should handle the error in your script. You would only want to check this to see what kind of error occurred if you get back an error-type code from running the method.

See [[get_eapi_status_code]].

{{{bulksms->get_response();}}}\n\n[[get_response]] returns the response after running a particular method, and is only used for some methods which return content.

{{{bulksms->get_quotation();}}}\n\n[[get_quotation]] returns a price quotation after using [[send_sms]] with the quotation feature enabled.

{{{bulksms->get_batch_id();}}}\n \n[[get_batch_id]] returns batch ID received after using [[send_sms]] (or an array of batch ID's if you have used the [[send_to_list]] method).

{{{bulksms->process_queue(@@color(green):$vars = NULL@@);}}}\n\nProcesses the message queue by generating a CSV from the queue and sending it via the BulkSMS EAPI function send_batch. Like [[send_sms]], it returns a StatusCode for the operation. You can retrieve the batch ID and various EAPI status information using the functions defined under ResponseInfo.\n\n$vars is an optional parameter which allows you to specify optional parameters in an array to be sent to the EAPI function send_batch as defined under Optional HTTP Parameters [[here|http://bulksms.vsms.net/docs/eapi/submission/send_batch/]].\n\n----\n\n//Example #1: Processing queue of SMS messages://\n{{{\ninclude_once('bulksms.php');\n$sms = new bulksms;\n$sms->push_sms_to_queue(array("msisdn" => "61400233646", "message" => "Test #1"));\n$sms->push_sms_to_queue(array("msisdn" => "44123456789", "message" => "Test #2"));\n$sms->push_sms_to_queue(array("msisdn" => "12125551212", "message" => "Test #3"));\n$status = $sms->process_queue();\nif($status == SUCCESS) {\n echo "Queue successfully processed, batch id: ".$sms->get_batch_id();\n} else {\n echo "There was an error: ".$sms->get_eapi_status_msg()." (".$sms->get_eapi_status_code().")";\n}\n}}}

{{{bulksms->fix_number(@@color(red):$num@@, @@color(green):$tr_letters=(true (default)|false)@@);}}}\n\nFixes a phone number that a user has supplied into the correct format for use with BulkSMS and returns the fixed number. If COUNTRY_CODE (when first setting up this script for use) has been set to something other than zero, it will add the correct country code where the first digit is 0 and the first digits cannot be identified as an IDD access code (suitable where this type of numbering plan is in place in some European countries). However, it is best in your script to ask the user to provide the number in the correct format, to make sure that what the user is entering is actually a phone number and not something else.\n\nA new feature was added with version 0.93 of this class, which provides an optional parameter $tr_letters which can be set to false. If this option is set to false, this function will not convert letters into numbers (ie. ABCD into 2223). If the number provided contains letters and this feature is set to false, this function will return false as the number is not valid. You might want to use this feature if you want to repair a number that a user has provided in a form, but you don't want to accept the input if the user has simply entered a text string. Is set to true by default for backward compatibility with older versions of this class.\n\n----\n\n//Example #1: Fixing phone numbers.//\n{{{\ninclude_once('bulksms.php');\n$sms = new bulksms;\necho $sms->fix_number("01161433315882")."\n"; // removes most IDD access codes\necho $sms->fix_number("+61 433 315 882")."\n"; // removes plus sign and whitespaces\necho $sms->fix_number("+61-433-315-882")."\n"; // removes foreign characters such as dashes\necho $sms->fix_number("614333HELLO2")."\n"; // converts letters into numbers\nif($sms->fix_number("614333HELLO2", false) == false) echo "invalid\n"; // will not convert this\necho $sms->fix_number("0433315882")."\n"; // drops 0 and appends country code set in COUNTRY_CODE\n}}}

''The latest recommended stable release is //1.0//.'' It is recommended that you keep your version up-to-date to account for new updates to the EAPI and bug fixes.\n!!!Download the latest version as a [[.ZIP|http://liam.hatton.name/dl/php-bulksms.zip]] or [[.TAR.GZ|http://liam.hatton.name/dl/php-bulksms.tar.gz]] archive.\nIt is also a good idea to save the latest copy of this documentation to your hard drive - see UsingThisSite on how to do this. You must also create a BulkSMS account online by visiting [[their website|http://www.bulksms.com/]] if you don't already have one.\n\nSimply open the file //'bulksms.php'// using your favourite text editor ([[SciTE|http://www.scintilla.org/SciTE.html]] is a good open-source text editor if you are still using Notepad) and edit the header to reflect your account details. Make sure you uncomment the correct country-based host for the country where your account is registered, otherwise your username/password combination will not work. \n\nUpload the two files //'bulksms.php'// & //'http.inc'// (required for HTTP connectivity) to the same directory on your webserver. You can also upload the test suite script called //'test.php'// if you wish to test the class on your server.

OldVersionWarning HelloThere BulkSMS GettingStarted MailingList LicenseInfo RelatedLinks

#tiddlerOldVersionWarning { border:1px solid black; background-color: aliceblue; }

''1.0 (released 29th August 2005):''\n* First stable version.\n* Wrote new documentation using TiddlyWiki.\n\n''0.93 (released 22nd May 2005):''\n* Added new functions for MessageQueuing and handling IncomingMessages.\n* Added new feature allowing you to change the HTTP port used for connection (if you are behind a firewall)\n* Tidied up the header and added additional error handling for BULKSMS_HOST, in case it isn't set (before it would freeze if this was not set)\n\n''0.92 (released 4th May 2005):''\n* Fixed major bug in [[send_to_list]] which affected the StatusCode returned by the function (missing ()’s)\n* Added new functions for PublicGroups.\n* Added international support (thank you Andrew for letting me know – I completely forgot about this!).\n* Added new feature in [[fix_number]] function which makes it optional to translate letters.\n* Fixed some more grammatical errors in documentation, and fixed some errors in the examples.\n* Created MailingList on Yahoo! Groups for announcements and user support.\n\n''0.91 (released 13th April 2005):''\n* Fixed major bug in one of the regexp that caused the library to parse the status returned by EAPI incorrectly.\n* Corrected some grammatical and colouring errors in the documentation.\n\n''0.9 (released 12th April 2005):''\n* First release.

Within the main story column you can click on bold links to read a linked tiddler. Click on italic links to create a new tiddler. When you hover the mouse over a tiddler several ToolbarButtons appear. You can edit the text of any tiddler by double-clicking on it (or selecting 'edit' from the toolbar), but your changes won't get saved permanently until you make your own copy of TiddlyWiki, as described in SaveChanges.\n\nIf you would like to save a copy of this documentation on your hard drive or add your own notes and additions to it and SaveChanges, you can do this by right clicking on [[this link|index.htm]] and selecting 'Save link as...' or 'Save target as...'. You can choose where to save the file, and what to call it (but keep the .HTML extension). Do ''not'' use the File/Save command in your browser to save TiddlyWiki, because of SaveUnpredictabilities.

You can SaveChanges if you're using FireFox or InternetExplorer:\n# if you're using Windows XP you might run into ServicePack2Problems\n# right click on [[this link|index.htm]] and select 'Save link as...' or 'Save target as...'\n** do ''not'' try to use the File/Save command in your browser because of SaveUnpredictabilities.\n** choose where to save the file, and what to call it (but keep the .HTML extension)\n# open the newly downloaded file in your browser\n# click the 'options' button on the right to set your username\n# edit, create and delete the tiddlers you want\n** you can change the SpecialTiddlers to change the SiteTitle and MainMenu etc.\n# click the 'save changes' button on the right to save your changes\n# TiddlyWiki will make a backup copy of the existing file, and then replace it with the new version\n

This is a saved copy of the website at [[http://liam.hatton.name/php-bulksms/|http://liam.hatton.name/php-bulksms/]] for distribution with the php-bulksms class archive, and may have been updated since release. To download the latest copy of this documentation, right click [[here|http://liam.hatton.name/php-bulksms/index.php]] and choose 'Save link as...' or 'Save target as...'. Save it in the same place and name as this file, overwriting the old version, and refresh your browser to see the latest changes.