README

Primary Deep Thought module for building data providers

Creating a Provider

To create a new data provider, extend the DTProvider or DTRESTProvider class and add an access point called action_{YourAction}_, as shown below.

<?php
	class MyProvider extends DTProvider {
	
		/**
		*	action: hit_me
		*	@return an object containing the result
		*/
		public function actionHitMe(){
			return array("result"=>"success");
		}
}

To allow the provider to respond to HTTP requests, instantiate the provider at an end-point location, such as api/v1.0/my_provider.php, and call handleRequest().

<?php
	require(__DIR__."/vendor/autoload.php");
	$provider = new MyProvider();
	$provider->handleRequest();

Automatic Actions

There are a series of common, pre-defined actions which you can enable through the DTProvider::$automatic_actions variable.

To use automatic actions, you must define the primary model for the provider and optionally define a new set of enabled automatic actions (the default set is 'read-only'--get, list, and count).

<?php
	class MyAutoProvider extends DTProvider {
		protected static $model = "MyModel";
		protected static $automatic_actions = array(
			"get","list","count","upsert","remove"
		);
	}

The following is a list of available automatic actions.

Action	Description
get	Retrieve a single record by lookup value
list	Retrieve many records
count	Get the total number of records
create	Create a new record (returns error 409 if records already exists)
create_many	Create many new records
update	Update an existing record (returns 404 if record could not be found)
update_many	Updates many existing records
upsert	Updates or creates a new record, as necessary
remove	Removes one or more records by lookup value
remove_all	Removes all records from a model's storage

RESTful Providers

To allow providers to observe the REST API standards, we provider a subclass that listens for the corresponding HTTP methods.

REST Action Map

Method	Type	CRUD Action	Description
GET	/	actionList()	Returns a list of relevant items. Can be paginated by passing `dt_pg` and `dt_ct`, which returns `{'total':Int,'items':Array}`
GET	/:id	actionGet()	Returns the relevant object, or 404 Not Found
POST	/	actionCreate()	Returns the newly created object
POST	/:id	actionUpdate()	Returns the updated object or throws a 404 Not Found for invalid identifiers.
DELETE	/	actionRemoveMany()	Removes multiple items specified by `ids` param.
DELETE	/:id	actionRemove()	Removes the relevant object.
PUT	/	actionRemoveMany(), actionCreateMany()	Replaces the relevant objects
PUT	/:id	actionRemove(), actionCreate()	Replaces the relevant object
PATCH	/	actionUpsertMany()	Adds or updates the relevant set of objects and parameters.
PATCH	/:id	actionUpsert()	Adds or updates the relevant object and parameters.

To create a RESTful provider, subclass DTRESTProvider.

<?php
	class MyRestfulProvider extends DTRESTProvider {
		protected static $model = "MyModel";
		protected static $automatic_actions = array(
			"get", //allows GET for entities
			"list", //allows GET for collections
			"create", //allows POST for entities
			"create_many", //allows PUT for collections
			"update", //allows POST for entities
			"remove", // allows DELETE, PUT for entities
			"remove_many", //allows DELETE, PUT for collections
			"upsert_many", //allows PATCH for collections
			"upsert" // allows PATCH for entities
		);
}

Advanced Providers

Adding Authentication

By default, the provider uses DTBasicVerifier to validate requests. The basic verifier simply confirms the correct token, which is created by a DTProviderConsumer during the request. If you would like to add additional verification, you can attach a different verifier to the provider in the constructor. A common scenario is using this method to enforce that a user is logged in and has a valid OAuth token. You can use DTOAuthVerifier from the deep-thought.php-provider-oauth module to ensure secure access to your protected actions (typically a subclass of the public provider). See Deep Thought's OAuth Providers Module for more details.

<?php
	...
	$provider = new MyProvider(new DTOAuthVerifier());
	...

Alternate Storage

By default, the provider will use the first entry in your storage config as the primary storage. If you would like to use a different store for the provider, pass it as the second argument to the constructor.

<?php
	...
	$provider = new MyProvider(null,DTStore::connect(null,"other_db"));
	...

expressive-analytics / deep-thought-provider

Maintainers

Details