Improved basic example and documentation

Author: hrajchert

README.md

@@ -1,8 +1,10 @@
 # Auth0 PHP SDK
 
-## Installation
+### 1. Install the SDK
 
-Using [Composer](http://getcomposer.org/doc/01-basic-usage.md):
+We recommend using [Composer](http://getcomposer.org/doc/01-basic-usage.md) to install the library.
+
+Modify your `composer.json` to add the following dependencies and run `composer update`.
 
 ~~~js
 {
@@ -13,24 +15,10 @@ Using [Composer](http://getcomposer.org/doc/01-basic-usage.md):
 }
 ~~~
 
-## Usage
-
-1- Include the [Auth0 Widget](https://docs.auth0.com/login-widget2):
+### 2. Setup the callback action
+Create a php page (or action if you are using an MVC framework) that will handle the callback from the login attempt.
 
-~~~html
-<a href="javascript:widget.signin();">Login</a>
-
-<script src="https://d19p4zemcycm7a.cloudfront.net/w2/auth0-widget-2.4.min.js"></script>
-<script type="text/javascript">
-    var widget = new Auth0Widget({
-        domain:       'YOUR_AUTH0_DOMAIN',
-        clientID:     'YOUR_AUTH0_CLIENT_ID',
-        callbackURL:  'YOUR_AUTH0_APP_CALLBACK'
-    });
-</script>
-~~~
-
-2- Edit the callback page to create an instance of the `Auth0` class in order to exchange the authorization code (provided by Auth0) for an access_token:
+In there, you should create an instance of the SDK with the proper configuration and ask for the user information.
 
 ~~~php
 use Auth0SDK\Auth0;
@@ -39,19 +27,69 @@ $auth0 = new Auth0(array(
     'domain'        => 'YOUR_AUTH0_DOMAIN',
     'client_id'     => 'YOUR_AUTH0_CLIENT_ID',
     'client_secret' => 'YOUR_AUTH0_CLIENT_SECRET',
-    'redirect_uri'  => 'YOUR_AUTH0_APP_CALLBACK',
-    'debug'         => true
+    'redirect_uri'  => 'http://<name>/callback.php'
 ));
 
-$access_token = $auth0->getAccessToken();
+$userInfo = $auth0->getUserInfo();
 ~~~
 
-3- Once the user successfully authenticated to the application, you can retrieve his profile:
+If the user was already logged in, `getUserInfo()` will retrieve that [user information](https://docs.auth0.com/user-profile) from the `PHP Session`. If not, it will try to exchange the code given to the callback to get an access token, id token and the [user information](https://docs.auth0.com/user-profile) from auth0.
+
+This makes it possible to use the same code in the callback action and any other page, so to see if there is a logged in user, you can call
+
 
 ~~~php
-$userProfile = $auth0->getUserInfo();
+// ...
+// code from above
+
+if (!$userInfo) {
+    // print login button
+} else {
+    // Say hello to $userInfo['name']
+    // print logout button
+}
 ~~~
 
+### 3. Setup the callback action in Auth0
+
+After authenticating the user on Auth0, we will do a GET to a URL on your web site. For security purposes, you have to register this URL on the Application Settings section on Auth0 Admin app.
+
+    http://<name>/callback.php
+
+
+### 4. Triggering login manually or integrating the Auth0 widget
+
+You can trigger the login in different ways, like redirecting to a login link or using the [Login Widget](https://docs.auth0.com/login-widget2), by adding the following javascript into your page
+
+
+    <a href="javascript:widget.signin();">Login</a>
+
+    <script src="https://cdn.auth0.com/w2/auth0-widget-3.0.min.js"></script>
+    <script type="text/javascript">
+        var widget = new Auth0Widget({
+            domain:       'YOUR_AUTH0_DOMAIN',
+            clientID:     'YOUR_AUTH0_CLIENT_ID',
+            callbackURL:  'http://<name>/callback.php'
+        });
+    </script>
+
+
+### 5. (Optional) Configure session data
+
+By default, the SDK will store the [user information](https://docs.auth0.com/user-profile) in the `PHP Session` and it will discard the access token and the id token. If you like to persist them as well, you can pass `persist_access_token => true` and `persist_id_token => true` to the SDK configuration in step 2. You can also disable session all together by passing `store => false`.
+
+If you want to change `PHP Session` and use Laravel, Zend, Symfony or other abstraction to the session, you can create a class that implements `get`, `set`, `delete` and pass it to the SDK as following.
+
+~~~php
+$laravelStore = new MyLaravelStore();
+$auth0 = new Auth0(array(
+    // ...
+    'store' => $laravelStore,
+    // ...
+));
+~~~
+
+
 ## Develop
 
 This SDK uses [Composer](http://getcomposer.org/doc/01-basic-usage.md) to manage its dependencies.

examples/basic/index.php

@@ -11,7 +11,7 @@
     'redirect_uri'  => $auth0_cfg['redirect_uri']
 ));
 
-$access_token = $auth0->getAccessToken();
+$userInfo = $auth0->getUserInfo();
 
 ?>
 <!doctype html>
@@ -21,18 +21,18 @@
     <title>Testing Auth0 PHP</title>
 </head>
 <body>
-<?php if(!$access_token): ?>
+<?php if(!$userInfo): ?>
     <script src="https://d19p4zemcycm7a.cloudfront.net/w2/auth0-widget-2.3.min.js"></script>
-	<script type="text/javascript">
-  		var widget = new Auth0Widget({
-	    	domain:         "<?php echo $auth0->getDomain() ?>",
-	    	clientID:       "<?php echo $auth0->getClientId() ?>",
-	    	callbackURL:    "<?php echo $auth0->getRedirectUri() ?>"
-	  	});
-	</script>
-	<button onclick="widget.signin()">Login</button>
+    <script type="text/javascript">
+        var widget = new Auth0Widget({
+            domain:         "<?php echo $auth0->getDomain() ?>",
+            clientID:       "<?php echo $auth0->getClientId() ?>",
+            callbackURL:    "<?php echo $auth0->getRedirectUri() ?>"
+        });
+    </script>
+    <button onclick="widget.signin()">Login</button>
 <?php else: ?>
-    <?php var_dump($auth0->getUserInfo()) ?>
+    <?php var_dump($userInfo) ?>
 <?php endif ?>
 </body>
 </html>