Home

HttpSource is an abstract plugin that may be used as base plugin for any plugin that handle remote data source. Remote data source can be any RESTful interface (Facebook, Twitter api's, etc) or even raw socket interface. There is very flexible configuration provided by base plugin, but if you want something special you can extend reach HttpSource classes.

###Config

First of all you need to create config file in your plugin: [MyPlugin]/Config/[MyPlugin].php Then init basic config structure:

<?
//Support only version 2
$config['MyPlugin']['config_version'] = 2;

$CF = HttpSourceConfigFactory::instance();
$Config = $CF->config();

//Configuration makes here

$config['MyPlugin']['config'] = $Config;

You can use endpoint-specific or config-specific settings. Endpoint settings will replace config settings. This is next settings:

<?
$Config
	//Global limit/offset to params mapping
	->readParams(array(
		'count' => 'limit+offset'
	))
	//Global result handler
	->result(
		//Result handler object
		$CF->result()
		//Add result handler callback
		->map(function($result) {
			//handle result
			return $result;
		}
	))
;

For more details please see HttpSourceConfig and HttpSourceConfigFactory classes.

###Endpoint

Now let's make our first configuration (in place of '//Configuration makes here'). We must add endpoint(s) to our config:

<?
$Config
	->add(
		//Endpoint object
		$CF->endpoint()
		//Unique id (in this plugin config)
		->id(1)
		//Method that corresponds fot this endpoint: read/update/delete/create
		->methodRead()
		//Table name for use in Model::useTable
		->table('table_name')
		//Path that will be add in request uri (if not present `table` will used)
		->path('path_name.json')
		//Params for method read - map limit/offset into query condition. Key is condition name
		//value can be limit, offset or limit+offset
		//If not present will used config-level setting
		->readParams(array(
			'count' => 'limit+offset'
		))
		//Result handler. Must extract needed data from decoded raw result.
		//If not present config-level setting will be used
		->result(
			//Result handler object
			$CF->result()
			//Add result handler callback
			->map(function($result) {
				//handle result
				return $result;
			}
		))
		//If you want to split request to this endpoint you can set this callback
		->requestSplitter(function($request) {
			//split request into subrequests
			return $subrequests;
		})
		//If you need additional rules for join results of subquerues
		//you may yse your callback (by default used array_merge)
		->responseJoiner(function ($responses) {
			//join responses
			return $joinedResponse;
		})
	)
;

For more details please see HttpSourceEndpoint class.

###Endpoint condition

After you add Endpoint-specific settings you need to add available conditions. By default not described conditions are skipped.

To add conditions:

<?
$CF->endpoint()
	->addCondition(
		//Make conditions object
		$CF->condition()
		//Condition name (used to identify condition in 'conditions' of `find`)
		->name('condition_name')
		//Set default value
		->defaults('default_value')
		//If condition is required - add this
		->required()
		//For additional condition processing you can map callback and/or rename
		//condition right before request
		->map(function ($condition) {
			//process condition value
			return $processedCondition;
		}, 'new_condition_name')
	)
;

For more details please see HttpSourceCondition class.

###Endpoint field

You can describe all or some specific fields. If you not describe field they will NOT be ignored, so you can skip this descriptions. But to help people that might use your plugin is better to describe all available fields.

Lets add field:

<?
$CF->endpoint()
	->addField(
		//Make field object
		$CF->field()
		//Field name (used to extract field from response)
		->name('field_name')
		//For additional field processing you can map callback and/or rename field
		->map(function ($field) {
			//process field value
			return $processedField;
		}, 'new_field_name')
	)
;

For more details please see HttpSourceField class.

###Cache

To enable requests cache just add cache config and set it name in config:

<?
$Config->cacheName('CacheConfigName');