Subversion Repositories php_users

<?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.

*/

/*

 * 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 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>",

            'password'  => "<div class='login_field'>\n<label>%s\n<input class='login_field' type='password' name='%s' title='%s' placeholder='%s'>\n</label>\n</div>",

            'boolean'   => "<div class='login_field'>\n<label>%s\n<input class='login_field' type='checkbox' name='%s' title='%s' value='1' %s ~~%s~~>\n</label>\n</div>",

            'textarea'  => "<div class='login_field'>\n<label>%s\n<textarea class='login_field' name='%s' title='%s' placeholder='%s'>~~%s~~</textarea>\n</label>\n</div>",

         ),

      'input prefix' => 'admin_', // prefix the name with this in a form

      'tables'    => array(

         'users'  => array(

            'table'     => '_users',   // table name for user records

            'id'        => '_user_id', // ID column name

            'display'   => array(      // fields which are displayed to select

               'login'

               ),         

            'form test' => 'login',    // field to test if form submitted

            'fields' => array(

               'login'  => array(

                     'label'        => 'Username',       // login name column name

                     'html type'    => 'text',

                     'filter'       => '/[a-zA-Z0-9_]/',

                     'instructions' => 'Username can only contain alpha numerics and an underscore',

                     'hint'         => 'Change User Name'

                     ),

               'pass'   => array( 

                     'label'        => 'Password',    // password column name

                     'html type'    => 'password',

                     'instructions' => 'Leave blank to keep same password',

                     'hint'         => 'Change Password'

                     ),

               'admin'  => array(

                     'label'        => 'isAdmin',

                     'html type'    => 'boolean',

                     'restrict'     => true,

                     'instructions' => 'If checked, user will be able to add/edit users',

                     ),

               'enabled' => array(

                     'label'        => 'Enabled',

                     'html type'    => 'boolean',

                     'restrict'     => true,

                     'instructions' => 'Uncheck to disable log in',

                     ),

               ) // 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 $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

    * 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' ) {

         $this->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

    * 

    */

   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: 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 ) {

         if ( $row['id'] == $this->data['id'] ) // don't do ourselves

            continue;

         $return .= sprintf( "<li><a href='$nextPage?doAdmin=1&id=%s'>%s</a></li>\n", $row['id'], $row['login'] );

      }

      $return .= sprintf( "<li><a href='$nextPage?doAdmin=1&id=%s'>%s</a></li>\n", -1, 'Add New User' );

      // wrap in ul, then put a div around it

      $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

    */

   private function logInScreen( $nextScript = null ) {

      $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, 

                        !empty($record['instructions']) ? $record['instructions'] : '',

                        !empty($record['hint']) ? $record['hint'] : '',

                        $field

                     );

      switch ($record['html type'] ) {

         case 'text':

         case 'textarea':

                        $temp = preg_replace( "/~~$field~~/", isset( $value ) ? $value : '', $temp );

                        break;

         case 'password' :

                        break;

         case 'boolean' :  // boolean is set by checkboxes

                        $temp = preg_replace( "/~~$field~~/", $value ? 'checked' : '', $temp );

                        break;

      } // 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 ) {

         // if this field is restricted and we are not admin, just skip it

         // also skip if it is our record

         if ( isset( $record['restrict'] ) && ( $this->data['id'] == $this->workingOn['id'] ) )

            continue;

         // now process the field

         $return[] = $this->makeHTMLField( $field, $record, $this->workingOn[$field] ?? '' );

      }

      return implode( "\n", $return );

   } // editScreen

   /**

    * Creates a variable designed to replace $this->workingOn

    * 

    * 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'] ) ) {

            $new[$field] = $record['default'];

         } else {

            switch ($record['html type']) {

               case 'text'    :

               case 'blob'    :  $new[$field] = '';

                                 break;

               case 'boolean' :  $new[$field] = 1;

                                 break;

               case 'password':  $new[$field] = '';

                                 break;

            }

         } // 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;

      } elseif ( isset($_REQUEST['id'] ) && $this->workingOn['id'] != $_REQUEST['id'] ) {

         // we're working on a different user

         if ( $_REQUEST['id'] == -1 ) { // we are adding a new user

            $this->workingOn = $this->emptyWorkingOn();

         } else { // this is an existing user

            $this->workingOn = $connection->getARecord( array( 'id' => $_REQUEST['id'] ) );

         }

      }

      // default to working on ourself

      if ( ! ( isset( $this->workingOn ) && count( $this->workingOn ) ) ) {

         $this->workingOn = $this->data;

      }

      // 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 .= $this->allUsersHTML( $connection );

         }

         return sprintf( $this->dbDefinition['screens']['edit form'],

            $nextScript,

            $return

            );

      } else { // we are processing

         $data = array();

         foreach ( $this->dbDefinition['tables']['users']['fields'] as $field => $record ) {

            // if this field is restricted it is our record, skip it

            if ( isset( $record['restrict'] ) && ( $this->data['id'] == $this->workingOn['id'] ) )

               continue;

            $htmlFieldName = $this->dbDefinition['input prefix'] . $field;

            $temp = '';

            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 ) {

                        $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;

               case 'boolean' :

                  if ( $this->workingOn['id'] == -1 || ( isset( $_REQUEST[$htmlFieldName] ) != $this->workingOn[$field] ) ) {

                     $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'] ) );

         } else {

            $return = "No changes";

         }

         unset( $this->workingOn );

         return $return;

      } // else

   } // admin

} // class Users

?>