[project @ Cleaned up documentation in consumer example]

1 files changed, 82 insertions, 8 deletions

diff --git a/examples/consumer.php b/examples/consumer.php
index 67187b7..8e79371 100644
--- a/examples/consumer.php
+++ b/examples/consumer.php
@@ -5,31 +5,62 @@
  * Net/OpenID has been installed and is in your PHP include path.
  */
 
-session_start();
+/**
+ * This is where the example will store its OpenID information.  You
+ * should change this path if you want the example store to be created
+ * elsewhere.  After you're done playing with the example script,
+ * you'll have to remove this directory manually.
+ */
+$store_path = "/tmp/_php_consumer_test";
 
+/**
+ * Require files to use the OpenID consumer.  We need the consumer
+ * itself, an OpenID store implementation, and some utility functions.
+ */
 require_once("Net/OpenID/Store/FileStore.php");
 require_once("Net/OpenID/Consumer/Consumer.php");
 require_once("Net/OpenID/OIDUtil.php");
 
-$store_path = "/tmp/_php_consumer_test";
-
+/**
+ * Try to create the store directory.
+ */
 if (!_ensureDir($store_path)) {
-    print "Could not create directory '$store_path'.  Please check the ".
-        "file's permissions.";
+    print "Could not create the FileStore directory '$store_path'.  Please ".
+        "check the effective permissions.";
     exit(0);
 }
 
+/**
+ * Create the OpenID store and consumer objects, which we'll use to
+ * perform the authentication.
+ */
 $store = new Net_OpenID_FileStore($store_path);
 $consumer = new Net_OpenID_Consumer($store);
 
-$action = null;
+/**
+ * Start the PHP session.
+ */
+session_start();
 
+/**
+ * Examine the CGI environment to find out what we should do.
+ */
+$action = null;
 if (array_key_exists('action', $_GET)) {
     $action = $_GET['action'];
 }
 
+/**
+ * Get this script's URL (since it's an example and may vary widely)
+ * and use it later when building URLs to use in the OpenID auth
+ * system.
+ */
 $self_url = $_SERVER['PHP_SELF'];
 
+/**
+ * These are the allowed values of the CGI 'action' variable.
+ * Anything else will be ignored and will result in a default page.
+ */
 $urls = array('verify' => $self_url . "?action=verify",
               'process' => $self_url . "?action=process");
 
@@ -38,16 +69,26 @@ if (!array_key_exists($action, $urls)) {
     $action = 'default_page';
 }
 
+/**
+ * Run the approriatley-named function based on the scrubbed value of
+ * $action.
+ */
 $action();
 
 
-
+/**
+ * Escapes double quotes in a value and returns the value wrapped in
+ * double quotes for use as an HTML attribute.
+ */
 function quoteattr($s)
 {
     $s = str_replace('"', '"', $s);
     return sprintf('"%s"', $s);
 }
 
+/**
+ * Prints the page header with a specified title.
+ */
 function print_header($title)
 {
 
@@ -95,6 +136,9 @@ function print_header($title)
     print sprintf($header_str, $title, $title);
 }
 
+/**
+ * Prints the page footer, which also includes the OpenID auth form.
+ */
 function print_footer()
 {
     global $urls;
@@ -113,11 +157,19 @@ function print_footer()
     print sprintf($footer_str, quoteattr($urls['verify']));
 }
 
+/**
+ * Render a default page.
+ */
 function default_page()
 {
     render();
 }
 
+/**
+ * Use some parameters to render a page with the specified title,
+ * including an optional message and CSS class to format the message
+ * in case the caller wants to display a notification or error.
+ */
 function render($message = null, $css_class = null,
                 $title = "PHP OpenID Consumer Example")
 {
@@ -131,6 +183,10 @@ function render($message = null, $css_class = null,
     print_footer();
 }
 
+/**
+ * Process the OpenID auth form submission by starting the OpenID auth
+ * process.
+ */
 function verify()
 {
     global $consumer, $urls, $self_url,
@@ -138,6 +194,8 @@ function verify()
         $Net_OpenID_PARSE_ERROR,
         $Net_OpenID_SUCCESS;
 
+    // Render a default page if we got a submission without an
+    // openid_url value.
     if (!array_key_exists('openid_url', $_GET) ||
         !$_GET['openid_url']) {
         default_page();
@@ -146,8 +204,10 @@ function verify()
 
     $openid_url = $_GET['openid_url'];
 
+    // Begin the OpenID authentication process.
     list($status, $info) = $consumer->beginAuth($openid_url);
 
+    // Handle failure status return values.
     if (in_array($status, array($Net_OpenID_HTTP_FAILURE, $Net_OpenID_PARSE_ERROR))) {
         if ($status == $Net_OpenID_HTTP_FAILURE) {
             render("HTTP failure");
@@ -155,6 +215,10 @@ function verify()
             render("HTTP Parse error");
         }
     } else if ($status == $Net_OpenID_SUCCESS) {
+        // If we got a successful return, continue the auth by
+        // redirecting the user agent to the OpenID server.  Be sure
+        // to give the server a URL that will cause this script's
+        // "process" function to process the server's response.
         $_SESSION['openid_token'] = $info->token;
         $return_to = "http://".$_SERVER['HTTP_HOST'].$urls['process'];
         $redirect_url = @$consumer->constructRedirect($info, $return_to,
@@ -166,26 +230,36 @@ function verify()
     }
 }
 
+/**
+ * Process the response from an OpenID server.
+ */
 function process()
 {
     global $consumer,
         $Net_OpenID_SUCCESS,
         $Net_OpenID_FAILURE;
 
-    // retrieve the token from the environment (in this case, the URL)
+    // Retrieve the token from the session.
     $token = $_SESSION['openid_token'];
 
     // Ask the library to check the response that the server sent us.
     // Status is a code indicating the response type. info is either
     // None or a string containing more information about the return
     // type.
+
+    // Because PHP mangles CGI names by replacing dots with
+    // underscores, try to fix the reponse by replacing underscores
+    // with dots so we can look for openid.* values.
     $data = Net_OpenID_Consumer::fixResponse($_GET);
 
+    // Complete the authentication process using the server's
+    // response.
     list($status, $info) = $consumer->completeAuth($token, $data);
 
     $css_class = 'error';
     $openid_url = null;
 
+    // React to the server's response status.
     if (($status == $Net_OpenID_FAILURE) &&
         $info) {
         // In the case of failure, if info is non-None, it is the URL