      1: <?php
      2:
      3:
      4: /**
      5:  * A RESTian_Service represents a service that can be called on an API.
      6:  *
      7:  * Often a service is defined as a URL endpoint plus an HTTP method.
      8:  * RESTian_Client subclasses are responsible to register the API services that they need to call.
      9:  *
     10:  */
     11: class RESTian_Service {
     12:   /**
     13:    * @var string - Name of this service in lowercase.
     14:    */
     15:   var $service_name;
     16:   /**
     17:    * @var string Type of service - 'resource', 'action' or (generic) 'service'
     18:    */
     19:   var $service_type = 'service';
     20:   /**
     21:    * @var string
     22:    */
     23:   var $path = '/';
     24:   /**
     25:    * @var string Specifies content type expected using RESTian defined content types.
     26:    */
     27:   var $content_type = 'json';
     28:   /**
     29:    * @var RESTian_Client - Reference back to the API that is managing these services.
     30:    */
     31:   var $client;
     32:   /**
     33:    * @var bool|array List of other variable names that are required for this servcie to be valid.
     34:    */
     35:   var $requires = false;
     36:   /**
     37:    * @var bool|array List of other variable names that make this variable invalid when they appear.
     38:    * If in "name=value" format then only invalid when the parameter appears with the specified value.
     39:    */
     40:   var $not_vars = false;
     41:   /**
     42:    * @var array List of valid parameter variables
     43:    */
     44:   var $vars = false;
     45:   /**
     46:    * @var bool If true this servie requires authentication
     47:    */
     48:   var $needs_authentication = false;
     49:   /**
     50:    * @var bool|string|RESTian_Settings If exists limits options for this service
     51:    */
     52:   var $request_settings = false;
     53:   /**
     54:    * @var string character set used
     55:    */
     56:   var $charset = 'utf-8';
     57:
     58:   /**
     59:    * @param string $service_name
     60:    * @param RESTian_Client $client
     61:    * @param array $args
     62:    * @throws Exception
     63:    */
     64:   function __construct( $service_name, $client, $args = array() ) {
     65:     $this->service_name = strtolower( $service_name );
     66:     $this->client = $client;
     67:
     68:     /**
     69:      * Set any defaults not set
     70:      */
     71:     foreach( $this->client->get_service_defaults() as $name => $value ) {
     72:       if ( ! isset( $args[$name] ) ) {
     73:         $args[$name] = $value;
     74:       }
     75:     }
     76:
     77:     /**
     78:      * Allow shorthand of 'auth' for 'needs_authentication'
     79:      */
     80:     $args = RESTian::expand_shortnames( $args, array(
     81:       'auth'      => 'needs_authentication',
     82:       'settings'  => 'settings_name',
     83:     ));
     84:
     85:     /**
     86:      * Copy properties in from $args, if they exist.
     87:      */
     88:     foreach( $args as $property => $value )
     89:       if ( property_exists(  $this, $property ) )
     90:         $this->$property = $value;
     91:
     92:     /*
     93:      * Transform from shortcut names like json and xml to valid mime type names application/json and application/xml.
     94:      * @see: https://www.iana.org/assignments/media-types/index.html
     95:      */
     96:     $this->content_type = RESTian::expand_content_type( $this->content_type );
     97:
     98:     /*
     99:      * Convert strings to arrays.
    100:      */
    101:     if ( is_string( $this->requires ) )
    102:       $this->requires = RESTian::parse_string( $this->requires );
    103:
    104:     /*
    105:      * TODO: Note=> 'not_vars' is not yet tested.
    106:       */
    107:     if ( is_string( $this->not_vars ) )
    108:       $this->not_vars = RESTian::parse_string( $this->not_vars );
    109:     if ( is_string( $this->vars ) )
    110:       $this->vars = RESTian::parse_string( $this->vars );
    111:
    112:     if ( isset( $args['var_set'] ) ) {
    113:       $var_set_vars =  $client->get_var_set( $args['var_set'] );
    114:       $this->vars = $this->vars ? array_merge( $var_set_vars, $this->vars ) : $var_set_vars;
    115:     }
    116:   }
    117:
    118:   /**
    119:    * @param $code
    120:    *
    121:    * @return string
    122:    */
    123:   function get_error_message( $code ) {
    124:     /**
    125:      * See if the API handles this error.
    126:       */
    127:     $message = $this->client->get_error_message( $code );
    128:     if ( ! $message ) {
    129:       $message = $this->client->get_auth_provider()->get_error_message( $code );
    130:     }
    131:     return $message;
    132:   }
    133:
    134:   /**
    135:    * @return bool|RESTian_Settings
    136:    */
    137:   function get_request_settings() {
    138:     if ( ! is_a( $this->request_settings, 'RESTian_Settings' ) )
    139:       $this->request_settings = $this->client->get_settings( $this->request_settings );
    140:     return $this->request_settings;
    141:   }
    142:
    143:   /**
    144:    * @return bool|RESTian_Settings
    145:    */
    146:   function has_request_settings() {
    147:     return false !== $this->get_request_settings();
    148:   }
    149: }
    150:
    151: