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: