<?php

/**
* DIDWW API PHP Class
* Based on: http://sandbox.didww.com/
* Written by Peter Beckman 
* March 1, 2007
*
* This work is licensed under a 
* Creative Commons Attribution-Share Alike 3.0 United States License
* http://creativecommons.org/licenses/by-sa/3.0/us/
*
* Requires the PEAR SOAP Library, http://pear.php.net/package/SOAP/
*
* All functions return 1 on failure, or 0 on success, either:
*
* 0 the command returned "success"
* array an array containing the data returned from the command
*
* If a failure occurs, $this->errormsg will be set with the reason it failed.
*
* USAGE:
*
* require_once('didww-api.inc');
* $v = new didwwapi;
* $countries = $v->getcountries();
*
*   ERROR CODES:
*   100 Access denied
*   105 Order already exists
*   106 DID ID: DID_ID NOT found
*   107 Invalid Protocol
*   108 DID: DIDNUMBER NOT found
*   109 DID: DIDNUMBER in pending status
*   110 DID: DIDNUMBER NOT renewed
*   111 Invalid status code. Valid codes: 0 - Disable, 1 - Enable
*   120 UNIQ: UNIQUEKEY NOT found
*   121 No cities for this country
*   200 Internal Server Error
*/

require_once("SOAP/Client.php");

class didwwapi 
{

    /**
    * Class Variables
    *
    * $this->username The username on DIDww given to you.
    * $this->key The long string that will give you access to the API
    * $this->testmode If set to 1 or evals to true, will use the DIDww sandbox.
    *
    * Private Variables, but you could modify them
    * $this->url The DIDww API URL.
    */

    var $testmode = 0;
    var $debug = 0;
    var $username = '';
    var $key = '';
    var $authstr = '';
    var $testurl = 'http://sandbox.didww.com/api/?wsdl';
    var $produrl = 'http://api.didww.com/api/?wsdl';
    var $url = '';
    var $soap = '';


    /**
    * getcountries() - get a list of available countries
    *
    * @returns Array Country
    * country_id DIDww Internal Country ID
    * country_prefix Country Code
    * country_name The name of the Country
    *
    *
    * Array
    * (
    * [0] => Array
    * (
    * [country_id] => 10
    * [country_prefix] => 54
    * [country_name] => Argentina
    * )
    * ...
    */
    function getcountries(){
        return $this->_handleQuery(array('cmd' => __FUNCTION__));
    }

    /**
    * getcities() - Get a list of available cities in a given Country ID
    *
    * @param $country_id int DIDww Country ID for a given country
    * @returns Array CitiesArray
    * uniq Unique ID within DIDww
    * city_prefix City Prefix
    * city_name Name of the city
    * monthly Monthly Recurring Fee for resellers only
    *
    * Object
    * (
    * [0] => Array
    * (
    * [uniq] => 10541111
    * [city_prefix] => 11
    * [city_name] => Buenos Aires
    * [monthly] => 4.45
    * )
    * [1] ...
    */
    function getcities($country_id) {
        return $this->_handleQuery(array('cmd' => __FUNCTION__,    'country_id' => $country_id));
    }

    /**
    * neworder() - order a new DID
    *
    * @param $uniq string DID ID from DIDww
    * @param $hash string optional A unique hash to represent the order
    * @param $autorenew int optional AutoRenew this DID or not
    * @return object DID
    * did_id Unique ID within DIDww
    * did_number The actual DID number, including Country and City Code
    */
    function neworder($uniq, $hash='', $autorenew=1) {
        if ($hash == '') {
            $hash = md5($uniq.mt_rand());
        }

        return $this->_handleQuery(array('cmd' => __FUNCTION__, 
                                        'hashkey' => $hash,
                                        'uniq' => $uniq,
                                        'autorenew' => $autorenew));
    }

    /**
    * buildmapping() - Map a DID to an new URI and protocol
    *
    * Proto: 1 = SIP, 2 = IAX2, 3 = H.323
    * @param $did_id int Unique ID of that DID
    * @param $proto int Protocol ID as specified above
    * @param $uri string URI for the mapping of the DID
    * @param $add_did int optional Add DIDNUMBER to the URI. 0 - No (default), 1 - Yes.
    * @return int success or failure, 0 or 1
    */
    function buildmapping($did_id, $proto=1, $uri='', $add_did = 0) {
        if ($uri == '') {
            $uri = $did_id.'@sip.didww.com';
        }

        return $this->_handleQuery(array('cmd' => __FUNCTION__, 
                                        'did_id' => $did_id,
                                        'map_proto' => $proto,
                                        'map_uri' => $uri, 
                                        'add_did' => $add_did));
    }

    /**
    * get_region_details() - Get info about a DID
    *
    * @param $uniq string UNIQUE KEY of region you want info about
    * @return object Region
    * country_name Country Name DID is in
    * city_name City Name DID is in
    * monthly Monthly Recurring Fee for resellers only
    */
    function get_region_details($uniq) {
        return $this->_handleQuery(array('cmd' => __FUNCTION__,    'uniq' => $uniq));
    }

    /**
    * get_did_details() - Get info about a DID
    *
    * @param $did_number string DID you want info about
    * @return object DID_data
    * did_country_name
    * did_city_name
    * did_number_format
    * did_status
    * did_timeleft
    * did_expire_date
    * did_order_id
    * did_order_status
    * did_autorenew
    * did_mapping_format
    * did_mapping_default
    * did_id
    */
    function get_did_details($did_number) {
        return $this->_handleQuery(array('cmd' => __FUNCTION__,    'did_number' => $did_number));
    }

    /**
    * order_autorenew_status() - Change the auto-renew status of a DID
    *
    * @param $did_number string DID you want info about
    * @param $status int Change autorenew status. 0 - Disable, 1 - Enable
    */
    function order_autorenew_status($did_number, $status=0) {
        return $this->_handleQuery(array('cmd' => __FUNCTION__,
                                        'did_number' => $did_number,
                                        'status' => $status));
    }

    /**
    * new_order_renew() - Renew an existing DID for a given period
    *
    * @param $did_number string DID you want to modify active period for
    * @param $period string Number of months to extend the DID for
    * @param $autorenew int 0 for no 1 for yes
    * @return object DID_data
    * did_country_name
    * did_city_name
    * did_number_format
    * did_status
    * did_timeleft
    * did_expire_date
    * did_order_id
    * did_order_status
    * did_autorenew
    * did_mapping_format
    * did_mapping_default
    * did_id
    */
    function new_order_renew($did_number, $period=1, $autorenew=1) {
        return $this->_handleQuery(array('cmd' => __FUNCTION__,
                                        'did_number' => $did_number,
                                        'period' => $period,
                                        'autorenew' => $autorenew));
    }

    /**
    * did_cancel() - Disconnect and stop billing for a given DID
    *
    * @param $did_number string DID you want to cancel
    * @return int success or failure
    */
    function did_cancel($did_number) {
        return $this->_handleQuery(array('cmd' => __FUNCTION__,    'did_number' => $did_number));
    }

    /***************************************
    * These functions are private; you *
    * can access them, but you shouldn't. *
    ***************************************/

    function _handleQuery($params) {

        if ($this->testmode == 0) {
            $this->authstr = sha1($this->username.$this->key);
            $this->url = $this->produrl;
        } else {
            $this->authstr = sha1($this->username.$this->key.'sandbox');
            $this->url = $this->testurl;
        }

        $soap = new SOAP_Client($this->url, true);
        if (PEAR::isError($soap)) {
            $this->errorstr = $soap->getMessage();
            if ($this->debug) error_log("Error on initialize: {$params['cmd']} {$this->errorstr}");
            return false;
        }

        $soapdata = array('auth_string' => $this->authstr);

        foreach($params as $k => $v) {
            if ($k == 'cmd') continue;
                $soapdata[$k] = $v;
        }

        $result = $soap->call($params['cmd'], $soapdata);

        if (PEAR::isError($result)) {
            $this->errorstr = $result->getMessage();
            if ($this->debug) error_log("Error on request: {$params['cmd']} {$this->errorstr}");
            return false;
        }

        if ($this->debug) error_log("V Params: " . print_r($params,1));
        if ($this->debug) error_log("Got Result: " . print_r($result,1));
        return $result;
    }
} 

?>