Improved SDK, more clean and with new examples

veridu · Oct 30, 2013 · 3240198 · 3240198
1 parent 168e5f4
commit 3240198
Show file tree

Hide file tree

Showing 23 changed files with 884 additions and 402 deletions.
diff --git a/composer.json b/composer.json
@@ -9,7 +9,10 @@
         }
     ],
     "require": {
-        "php": ">=5.3.0"
+        "php": ">=5.4.0"
+    },
+    "require-dev": {
+        "phpdocumentor/phpdocumentor": "~2.1"
     },
     "minimum-stability": "dev",
     "autoload": {

diff --git a/examples/README.md b/examples/README.md
@@ -0,0 +1,34 @@
+Examples
+========
+
+Here you'll find pieces of code to help you use the SDK.
+
+apicall.php
+-----------
+This example demonstrates how to perform an API request
+
+autoload.php.dist
+-----------------
+This is an `autoloader` (class loader), in case you are not using `Composer` to install this package.
+To use this `autoloader`, rename it to autoload.php and change the `require_once` directive on the example files.
+
+logged.php
+----------
+Common workflow for logged users
+
+session.php
+-----------
+This example demonstrates how to handle a read/write session, for logged in users
+
+settings.php.dist
+------------
+On this file you'll have to fill in with your client details, like Client ID, Shared secret and API/Widget version.
+You also need to rename this file to settings.php
+
+unlogged.php
+------------
+Common workflow for unlogged users (visitors)
+
+widget.php
+----------
+This example demonstrates how to use widgets
diff --git a/examples/apicall.php b/examples/apicall.php
@@ -0,0 +1,52 @@
+<?php
+/*
+* API request
+*
+* This example demonstrates how to perform an API request
+*/
+
+//getting the session management
+require_once __DIR__ . '/session.php';
+
+try {
+	//retrieve API SDK instance from Session SDK instance
+	$api = $session->getAPI();
+	//fetchs provider information (user verifications based on Social Media and Online Services
+	$information = $api->fetch('GET', "provider/{$user_id}/all");
+	/*
+		Provider information is now available on $information
+		Example:
+			Array
+			(
+			    [status] => 1
+			    [list] => Array
+			        (
+			            [0] => facebook
+			            [1] => linkedin
+			            [2] => twitter
+			        )
+
+			    [info] => Array
+			        (
+			            [facebook] => Array
+			                (
+			                    [picture] => https://fbcdn-profile-a.akamaihd.net/static-ak/rsrc.php/v2/yo/r/UlIqmHJ-SK.gif
+			                    [overall] => 0.65
+			                )
+
+			            [linkedin] => Array
+			                (
+			                    [picture] => http://m.c.lnkd.licdn.com/mpr/mprx/0_FJCU17ic7na5SMBtbVhe12hzfPgzTV9t5UnX12tErnWLYY3-w0tBgu6k3jjoGjcY6V85pwhdT7
+			                    [overall] => 0.81
+			                )
+
+			            [twitter] => (NULL)
+			        )
+
+			)
+	*/
+} catch (Exception $exception) {
+	//error with API usage
+	printf("Error with API usage: [%s] %s\n", $api->lastError(), $exception->getMessage());
+	exit;
+}
diff --git a/examples/autoload.php.dist b/examples/autoload.php.dist
@@ -0,0 +1,50 @@
+<?php
+
+class autoload {
+	private $includePath;
+	private $map;
+
+	public function __construct($includePath = null) {
+		$this->includePath = $includePath;
+	}
+
+	//https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md
+	public function loadClass($name) {
+		$name = ltrim($name, '\\');
+		$file  = (is_null($this->includePath) ? '' : $this->includePath . DIRECTORY_SEPARATOR);
+		$namespace = '';
+		$pos = strrpos($name, '\\');
+		if ($pos !== false) {
+			$namespace = substr($name, 0, $pos);
+			$name = substr($name, ($pos + 1));
+			if (isset($this->map[$namespace]))
+				$file = $this->map[$namespace];
+			$file .= str_replace('\\', DIRECTORY_SEPARATOR, $namespace) . DIRECTORY_SEPARATOR;
+		}
+		$file .= str_replace('_', DIRECTORY_SEPARATOR, $name) . '.php';
+		require $file;
+	}
+
+	public function register($prepend = false) {
+		spl_autoload_register(array($this, 'loadClass'), true, $prepend);
+	}
+
+	public function addMap($prefix, $path) {
+		$prefix = trim($prefix, '\\') . '\\';
+		$path = rtrim($path, DIRECTORY_SEPARATOR) . DIRECTORY_SEPARATOR;
+		$map[$prefix] = $path;
+	}
+
+	public function setIncludePath($path) {
+		$this->includePath = $path;
+	}
+
+	public function getIncludePath() {
+		return $this->includePath;
+	}
+
+}
+
+$autoload = new autoload;
+$autoload->register();
+return $autoload;
diff --git a/examples/logged.php b/examples/logged.php
@@ -6,36 +6,36 @@
 
 try {
 	session_start();
-	//api object creation
-	$api = new Veridu\SDK\API(
-		$config['client'],
-		$config['secret'],
-		$config['version'],
-		new Veridu\HTTPClient\CurlClient,
-		new Veridu\Signature\HMAC(
-			$config['client'],
-			$config['secret'],
-			$config['version']
+	//session object creation
+	$session = new Veridu\SDK\Session(
+		new Veridu\SDK\API(
+			new Veridu\Common\Config(
+				$config['client'],
+				$config['secret'],
+				$config['version']
+			),
+			new Veridu\HTTPClient\CurlClient,
+			new Veridu\Signature\HMAC
 		)
 	);
 
 	//cache check / expire check
 	if ((empty($_SESSION['veridu']['expires'])) || ((intval($_SESSION['veridu']['expires']) - time()) <= 0)) {
-		$api->sessionCreate(false);
-		$api->userCreate('user-unique-id');
+		$session->create(false);
+		$session->assign('user-unique-id');
 		$_SESSION['veridu'] = array(
-			'session' => $api->getSession(),
-			'expires' => $api->getExpires(),
-			'username' => $api->getUsername()
+			'session' => $session->getToken(),
+			'expires' => $session->getExpires(),
+			'username' => $session->getUsername()
 		);
 	} else {
-		$api->setSession($_SESSION['veridu']['session']);
-		$api->setUsername($_SESSION['veridu']['username']);
+		$session->setToken($_SESSION['veridu']['session']);
+		$session->setUsername($_SESSION['veridu']['username']);
 
 		//extend session if it will expire in less than a minute
 		if ((intval($_SESSION['veridu']['expires']) - time()) < 60) {
-			$api->sessionExtend();
-			$_SESSION['veridu']['expires'] = $api->getExpires();
+			$session->extend();
+			$_SESSION['veridu']['expires'] = $session->getExpires();
 		}
 	}
 } catch (Exception $exception) {
@@ -50,17 +50,17 @@
 		<meta charset="utf-8">
 		<title>For logged in users</title>
 		<script type="text/javascript" src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
-		<script type="text/javascript" src="//assets.veridu.com/<?=$api->getVersion();?>/sdk/veridu.min.js"></script>
+		<script type="text/javascript" src="//assets.veridu.com/<?=$config['version'];?>/sdk/veridu.min.js"></script>
 	</head>
 	<body>
 		<!-- content goes here -->
 		<script type="text/javascript">
 			$(function() {
-				var user = '<?=$api->getUsername();?>',
+				var user = '<?=$session->getUsername();?>',
 					veridu = new Veridu({
-						client: '<?=$api->getClient();?>',
-						session: '<?=$api->getSession();?>',
-						version: '<?=$api->getVersion();?>'
+						client: '<?=$config['client'];?>',
+						session: '<?=$session->getToken();?>',
+						version: '<?=$config['version'];?>'
 					});
 				//code goes here
 			});

diff --git a/examples/session.php b/examples/session.php
@@ -0,0 +1,74 @@
+<?php
+/*
+* Session management
+*
+* This example demonstrates how to handle a read/write session, for logged in users
+*/
+
+//using composer's autoloader
+require_once __DIR__ . '/../vendor/autoload.php';
+
+//using distribution autoloader
+//$autoloader = require_once __DIR__ . '/autoload.php.dist';
+//$autoloader->setIncludePath(__DIR__ . '/../src/');
+
+//requiring client configuration
+require_once __DIR__ . '/settings.php';
+
+//logged in user ID
+$user_id = 'some-system-unique-user-id';
+
+try {
+	session_start();
+	//Session SDK instantiation
+	$session = new Veridu\SDK\Session(
+		new Veridu\SDK\API(
+			new Veridu\Common\Config(
+				$config['client'],
+				$config['secret'],
+				$config['version']
+			),
+			new Veridu\HTTPClient\CurlClient,
+			new Veridu\Signature\HMAC
+		)
+	);
+
+	//cache check / expire check
+	if ((empty($_SESSION['veridu']['expires'])) || ((intval($_SESSION['veridu']['expires']) - time()) <= 0)) {
+		/*
+			A Veridu session wasn't found or it was already expired, so create a new one
+		*/
+
+		//creates new a read/write Veridu session
+		$session->create(false);
+		//assigns the fresh Veridu session to currently logged in user
+		$session->assign($user_id);
+		//stores Veridu's session information on cache for later use
+		$_SESSION['veridu'] = array(
+			'session' => $session->getToken(),
+			'expires' => $session->getExpires()
+		);
+	} else {
+		/*
+			A Veridu session was found and it's still valid
+		*/
+
+		//sets the session token to the previous created token
+		$session->setToken($_SESSION['veridu']['session']);
+		//sets the user identification to the current user
+		//note that this MUST be the same user that the session was assigned to
+		$session->setUsername($user_id);
+
+		//checks if Veridu's session will expire in less than a minute
+		if ((intval($_SESSION['veridu']['expires']) - time()) < 60) {
+			//extends Veridu's session lifetime
+			$session->extend();
+			//stores new expiration unixtime for later use
+			$_SESSION['veridu']['expires'] = $session->getExpires();
+		}
+	}
+} catch (Exception $exception) {
+	//error with session setup
+	printf("Error with session setup: %s\n", $exception->getMessage());
+	exit;
+}
diff --git a/examples/settings.php → examples/settings.php.dist b/examples/settings.php → examples/settings.php.dist
diff --git a/examples/unlogged.php b/examples/unlogged.php
@@ -6,33 +6,33 @@
 
 try {
 	session_start();
-	//api object creation
-	$api = new Veridu\SDK\API(
-		$config['client'],
-		$config['secret'],
-		$config['version'],
-		new Veridu\HTTPClient\CurlClient,
-		new Veridu\Signature\HMAC(
-			$config['client'],
-			$config['secret'],
-			$config['version']
+	//session object creation
+	$session = new Veridu\SDK\Session(
+		new Veridu\SDK\API(
+			new Veridu\Common\Config(
+				$config['client'],
+				$config['secret'],
+				$config['version']
+			),
+			new Veridu\HTTPClient\CurlClient,
+			new Veridu\Signature\HMAC
 		)
 	);
 
 	//cache check / expire check
 	if ((empty($_SESSION['veridu']['expires'])) || ((intval($_SESSION['veridu']['expires']) - time()) <= 0)) {
-		$api->sessionCreate(true);
+		$session->create(true);
 		$_SESSION['veridu'] = array(
-			'session' => $api->getSession(),
-			'expires' => $api->getExpires()
+			'session' => $session->getToken(),
+			'expires' => $session->getExpires()
 		);
 	} else {
-		$api->setSession($_SESSION['veridu']['session']);
+		$session->setToken($_SESSION['veridu']['session']);
 
 		//extend session if it will expire in less than a minute
 		if ((intval($_SESSION['veridu']['expires']) - time()) < 60) {
-			$api->sessionExtend();
-			$_SESSION['veridu']['expires'] = $api->getExpires();
+			$session->extend();
+			$_SESSION['veridu']['expires'] = $session->getExpires();
 		}
 	}
 } catch (Exception $exception) {
@@ -47,16 +47,16 @@
 		<meta charset="utf-8">
 		<title>For unlogged users</title>
 		<script type="text/javascript" src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
-		<script type="text/javascript" src="//assets.veridu.com/<?=$api->getVersion();?>/sdk/veridu.min.js"></script>
+		<script type="text/javascript" src="//assets.veridu.com/<?=$config['version'];?>/sdk/veridu.min.js"></script>
 	</head>
 	<body>
 		<!-- content goes here -->
 		<script type="text/javascript">
 			$(function() {
 				var veridu = new Veridu({
-					client: '<?=$api->getClient();?>',
-					session: '<?=$api->getSession();?>',
-					version: '<?=$api->getVersion();?>'
+					client: '<?=$config['client'];?>',
+					session: '<?=$session->getToken();?>',
+					version: '<?=$config['version'];?>'
 				});
 				//code goes here
 			});