WebSVN – php_users – Diff – /trunk/Users.class.php

 <?php
+/*
+   Copyright (c) 2021, Daily Data, Inc. Redistribution and use in
+   source and binary forms, with or without modification, are permitted
+   provided that the following conditions are met:
+   * Redistributions of source code must retain the above copyright
+     notice, this list of conditions and the following disclaimer.
+   * Redistributions in binary form must reproduce the above copyright
+     notice, this list of conditions and the following disclaimer in the
+     documentation and/or other materials provided with the distribution.
+   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+*/
+/*
-class Users {
+ * users.class.php
+ *
+ * Authors: R. W. Rodolico
+ *
+ */
+/**
+ * User Login class
+ *
+ * IMPORTANT: Requires a data source. See UsersDataSourceMySQLi.class.php
+ * for code which provides this for MySQLi
+ *
+ * Users encapsulates a basic login and authentication package. It
+ * provides a login screen, authentication, the ability to edit oneself,
+ * and for users with the admin flag set, the ability to edit others.
+ *
+ * It also allows a user to be disabled.
+ *
+ * Users was designed to be extensible, adding new fields by the calling
+ * program, modifying the HTML elements, etc...
+ *
+ * @author R. W. Rodolico <rodo@unixservertech.com>
+ *
+ * @version 0.9.0 (beta)
+ * @copyright 2021 Daily Data, Inc.
+ *
+ */
+ class Users {
+   /**
+    * @var string[] $dbDefinition Contains the configuration for the class
+    *
+    * May be modified by the calling program. Must be replicated in userDataSource class
+    */
    private $dbDefinition = array(
       /*
        * what to use for html input fields
        * These are passed to sprintf, with label, fieldname, title, placeholder and current value, in that order
        */
       'screens'         => array (
          'login form' => "<h1>Login</h1>\n<form class='login_form' action='%s' method='post'>\n%s\n<input type='submit' value='Login'></form>\n",
          'edit form'  => "<form class='login_form' action='%s' method='post'>\n%s\n<input type='submit' id='btnUpdate' name='btnUpdate' value='Update'>\n</form>",
-         'loginScreen' => "<div class='login_field'>\n<input class='login_field' type='text' name='username' placeholder='Username' required>\n</div>\n<div class='login_field'>\n<input class='login_field' type='password' name='password' placeholder='Password' required>\n</div>",
+         'loginScreen' => "<div class='login_field'>\n<input class='login_field' type='text' name='username' placeholder='Username' required autofocus>\n</div>\n<div class='login_field'>\n<input class='login_field' type='password' name='password' placeholder='Password' required>\n</div>",
          'adminScreen' => "<input type='hidden' name='doAdmin' value='1'>\n",
          'validateScript' => '',
          ),
       'html input fields' => array(
             'text'      => "<div class='login_field'>\n<label>%s\n<input class='login_field' type='text' name='%s' title='%s' placeholder='%s' value='~~%s~~'>\n</label>\n</div>",
                ) // fields
             ) // table users
          ) // tables
       );
+   /** @var string[] $data Contains the information for the current logged in user */
+   private $data = array();
+   /** @var string[] $errors Contains errors that can occur */
-   private $data = array(
+   private $errors = array();
+   /** @var string[] $workingOn During administration, contains the record being modified */
+   private $workingOn = array();
-      );
+   /**
+    * constructor for an instance of the class
+    *
+    * Anything in $customFields will be recursively merged with $dbDefinition, overwriting
-//   private $workingOn = array();
+    * as necessary.
+    *
+    * @param string[] $customFields array to merge into $dbDefinition
+    */
    public function __construct( $customFields = array() ) {
       if ( $customFields ) {
          $this->dbDefinition = array_merge_recursive( $this->dbDefinition, $customFields );
+      }
    } // constructor
+   /**
+    * getter for $this->errors
+    *
+    * @return string html div containing one paragraph for every error
+    */
+   public function errors() {
+      $return = "<p>" . implode( "</p>\n<p>", $this->errors ) . "</p>\n";
+      return "<div class='login_errors'>\n$return</div>\n";
+   }
+   /**
+    * clears the errors array
+    */
+   public function clearErrors() {
+      $this->errors = array();
+   }
+   /**
+    * getter for isAdmin
+    *
+    * @return boolean true if user is an admin, false if not
+    */
    public function isAdmin() {
       return $this->data['admin'];
+   }
+   /**
+    * getter for login name
+    *
+    * @return string user name
+    */
    public function name() {
       return isset( $this->data['login'] ) ? $this->data['login'] : null;
+   }
+   /**
+    * Main display function.
+    *
+    * This function should be called to perform the login. It performs all functions
+    * needed to log in and validate, but once logged in, will return an empty string.
+    *
+    * @param usersDataSource $connection A connection to the data source
+    * @param string $nextScript The url to be run when logged in
+    *
+    * @return string A (possibly empty) HTML div
+    */
    public function HTML( $connection, $nextScript = null ) {
       if ( isset( $_REQUEST['username'], $_REQUEST['password'] ) ) {
          $this->validate( $_REQUEST['username'], $_REQUEST['password'], $connection );
+      }
       if ( isset( $_REQUEST['logout'] ) && $_REQUEST['logout'] == 'Logout' ) {
       if ( ! isset( $this->data['login'], $this->data['id'] ) ) {
          return $this->logInScreen();
+      }
+   }
+   /**
+    * Validates a connection and, on success, populates $data
+    *
+    * Function will validate the username and password passed in, using
+    * data connection $connection. On success, populates class member $data
+    * with the values from the database (only those listed in $dbDefinition)
+    *
+    * On Failure, appends $error with a failure string
+    *
+    * @param string $username The username to be matched in database
+    * @param string $password The password (unencrypted) the user entered
+    * @param usersDataSource $connection A connection to the data source
+    *
+    */
-   public function validate( $username, $password, $connection ) {
+   private function validate( $username, $password, $connection ) {
       $result = $connection->getPassword( $username );
       if ( password_verify( $password, $result['pass'] ) ) {
          $result = $connection->getRecord( $username );
          $this->data['id'] = $result['id'];
          foreach ( $this->dbDefinition['tables']['users']['fields'] as $key => $record ) {
             if ( $key != 'pass' )
                $this->data[$key] = $result[$key];
+         }
       } else {
-         $this->errors[] = 'Login Failed';
+         $this->errors[] = 'Login Failed: Unknown username or password';
          foreach ( $this->dbDefinition['tables']['users']['fields'] as $key => $record ) {
             $this->data[$key] = null;
+         }
+      }
    } // validate
+   /**
+    * Get all users from data source and put them in an HTML list
+    *
+    * Will retrieve the ID and login name of all users, putting them
+    * in a list of anchors to allow an admin to select one for editing
+    *
+    * @param  usersDataSource $connection A connection to the data source
+    * @param string $nextPage The URL of the page to be used in the link
+    *
+    * @return  string   an unordered list (UL) containing links with names
+    */
    public function allUsersHTML ( $connection, $nextPage = null ) {
       $nextPage = self::getNextScript( $nextPage );
       $return = '';
       $allUsers = $connection->getAllUsers();
       foreach ( $allUsers as $row ) {
       $return = "<ul class='login_list'>\n$return\n</ul>\n";
       $return = "<div class='login_list'>\n$return\n</div>\n";
       return $return;
+   }
+   /**
+    * Logs user out of system
+    *
+    * destroys itself ($_SESSION['user'], then session, then calls
+    * $nextScript by doing a header call.
+    *
+    * @param string $nextScript URL of next script to call
+    */
    public function logOut( $nextScript = null ) {
       $nextScript = $this->getNextScript( $nextScript );
       $_SESSION['user'] = null;
       session_destroy();
       header( "Location: $nextScript" );
+   }
+   /**
+    * Simple helper script to calculate next script to call
+    *
+    * Returns one of three URL strings, in order of precedence
+    * $nextScript
+    * $dbDefinition['screens']['validateScript']
+    * PHP_SELF
+    *
+    * @param string $nextScript URL to call
+    * @return string URL
+    */
    private function getNextScript( $nextScript = null ) {
       if ( ! isset( $nextScript ) ) {
          $nextScript = $this->dbDefinition['screens']['validateScript'] ?:
                            htmlentities($_SERVER["PHP_SELF"]);
+      }
       return $nextScript;
+   }
+   /**
+    * Creates the fields needed for a login screen
+    *
+    * Populates %s's in 'login form' with values for $nextScript and
+    * 'loginScreen'
+    *
+    * @param string $nextScript URL to call form
+    *
+    * @return string HTML code for display
+    */
-   public function logInScreen( $nextScript = null ) {
+   private function logInScreen( $nextScript = null ) {
-      return sprintf(
+      $return =  sprintf(
          $this->dbDefinition['screens']['login form'],
          $this->getNextScript( $nextScript ),
          $this->dbDefinition['screens']['loginScreen']
       );
+      $return .= $this->errors();
+      $this->clearErrors();
+      return $return;
+   }
+   /**
+    * Creates an HTML field for display
+    *
+    * Retrieves the template for the record type, then populates it from
+    * $record, $value and $field. The template MUST have %s's in the
+    * following order for an HTML INPUT field
+    * label=
+    * name=
+    * title=
+    * placeholder=
+    * value
+    *
+    * Knows how to handle INPUT types TEXT, TEXTAREA, PASSWORD and
+    * special html type boolean, which is checkboxes.
+    *
+    * @param string $field name of the field to populate
+    * @param string[] $record Record from $dbDefinition[...][fields]
+    * @param string $value the current value to put in INPUT
+    *
+    * @return string An HTML INPUT entity
+    */
    private function makeHTMLField ( $field, $record, $value ) {
       $return = array();
       $temp = sprintf( $this->dbDefinition['html input fields'][$record['html type']],
                         $record['label'] ?: $field,
                         $this->dbDefinition['input prefix'] . $field,
       } // case
       return $temp;
    } // makeHTMLField
+   /**
+    * Creates an edit screen for display to user
+    *
+    * This function will create an edit screen which, when displayed to
+    * the user, allows them to edit a users record. The record is stored
+    * in $this->workingOn
+    *
+    * Function will go through each field in the users table and call makeHTMLField
+    * for it, unless the field is restricted and the user is editing their own
+    * entry. It will also create a hidden input field with the users ID
+    *
+    * NOTE: this will not create the form; the form is created someplace else
+    *
+    * @return string HTML containing all of the INPUT records a user can edit
+    */
    public function editScreen() {
       $return = array();
       $return[] = $this->dbDefinition['screens']['adminScreen'];
       $return[] = "<input type='hidden' name='id' value=" . $this->workingOn['id'] . "'>\n";
       foreach ( $this->dbDefinition['tables']['users']['fields'] as $field => $record ) {
          $return[] = $this->makeHTMLField( $field, $record, $this->workingOn[$field] ?? '' );
+      }
       return implode( "\n", $return );
    } // editScreen
+   /**
-   public function adminScreen( $connection ) {
+    * Creates a variable designed to replace $this->workingOn
+    *
-      return $this->allUsersHTML( $connection );
+    * Initializes all fields to something non-null and sets id to -1
-   }
+    *
+    * @return string[] An array initialized with all records needed
+    */
    private function emptyWorkingOn() {
       $new = array();
       $new['id'] = -1;
       foreach ( $this->dbDefinition['tables']['users']['fields'] as $field => $record ) {
          if ( isset( $record['default'] ) ) {
          } // else
       } // foreach
       return $new;
+   }
+   /**
+    * Sets up the admin function which allows users to edit themselves and, optionally, others
+    *
+    * This should be called the first time, then repeatedly called until it is done
+    * (it returns the string "Updated", "Failed" or "No changes".
+    *
+    * The first iteration returns an edit screen displaying the users
+    * information for them to edit. It will display an HTML INPUT for
+    * each field that is not restricted. The user can then edit the
+    * chosen entries and press the button, which will call the script
+    * again, and update the record.
+    *
+    * If the user has the admin right, the Edit screen also displays a
+    * list of all users as an unsigned list of anchors. If the user
+    * clicks on one of those, it will choose that user, load their data
+    * and allow the user to edit that users record. NOTE: this is the
+    * only way to edit fields with the restrict flag set.
+    *
+    * @param  usersDataSource $connection A connection to the data source
+    * @param string $nextPage The URL of the page to be used in the link
+    *
+    * @return string This may be an HTML table or a single screen
+    */
    public function admin ( $connection, $nextScript = null ) {
       $nextScript = $this->getNextScript( $nextScript );
       if ( ! isset($_REQUEST['id']) ) {
          // we're working on ourself
          $this->workingOn = $this->data;
+      }
       // default to working on ourself
       if ( ! ( isset( $this->workingOn ) && count( $this->workingOn ) ) ) {
          $this->workingOn = $this->data;
+      }
-      //print "<pre>thisworkingOn=\n" . print_r($this->workingOn, true ) . "</pre>";
       // we have no data, so we should create a form for them to enter something
       if ( ! isset( $_REQUEST[$this->dbDefinition['input prefix'] . $this->dbDefinition['tables']['users']['form test']] ) ) {
          // create the screen
          $return = $this->editScreen();
          if ( $this->data['admin'] ) {
-            $return .= self::adminScreen( $connection );
+            $return .= $this->allUsersHTML( $connection );
+         }
          return sprintf( $this->dbDefinition['screens']['edit form'],
             $nextScript,
             $return
             );
             switch ( $record['html type'] ) {
                case 'textarea':
                case 'text' :
                   if ( $this->workingOn['id'] == -1 || ( isset( $_REQUEST[$htmlFieldName] ) && $_REQUEST[$htmlFieldName] !== $this->workingOn[$field] ) ) {
                      $data[$field] = $_REQUEST[$htmlFieldName];
-/*                     if ( isset( $record['filter'] ) && preg_filter( $record['filter'], '', $temp ) !== $temp ) {
+                     if ( isset( $record['filter'] ) && preg_filter( $record['filter'], '', $temp ) !== $temp ) {
-                        $this->errors[] = "Invalid characters in $field";
+                        $this->errors[] = sprintf( "Invalid characters in %s, %s", $record['label'], $record['instructions'] );
                         $temp = '';
+                     }
-*/                  }
+                  }
                   break;
                case 'password':
                   if ( ! empty( $_REQUEST[$htmlFieldName] ) )
                      $data[$field] = password_hash( $_REQUEST[$htmlFieldName], PASSWORD_DEFAULT );
                   break;
                      $data[$field] = isset( $_REQUEST[$htmlFieldName] ) ? 1 : 0;
+                  }
                   break;
             } // switch
          } // foreach
+         if ( count($this->errors) ) { // we have some errors
+            $this->errors[] = 'Record not updated';
+            return 'Error';
+         }
          if ( $data ) {
             $data['id'] = $this->workingOn['id'];
             $return = $connection->update( $data ) ? "Updated" : "Failed";
             if ( $this->workingOn['id'] == $this->data['id'] ) // we just updated us, reload record
                $this->data = $connection->getARecord( array( 'id' => $this->data['id'] ) );
          unset( $this->workingOn );
          return $return;
       } // else
    } // admin
-   public function errors() {
-      return $this->errors;
-   }
 } // class Users
 ?>

Subversion Repositories php_users

(root)/trunk/Users.class.php – Rev 4 → 7