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

*/

/*
 * UsersDataSource.class.php
 * 
 * Authors: R. W. Rodolico
 * 
 */

/**
 * usersDataSource class
 * 
 * usersDataSource provides the data access capabilities for the Users
 * class.
 * 
 * To build a data access class for Users, the following 5 methods must
 * exist.
 * getPassword(username)
 * getAllUsers()
 * getARecord
 * update
 * 
 * Additionally, where appropriate, the following function is useful
 * buildTable()
 * 
 * This particular instance provides an interface to MySQL using
 * the mysqli libraries.
 * 
 * Create an instance of this, then pass the variable to several Users
 * calls.
 * 
 * @author R. W. Rodolico <rodo@unixservertech.com>
 * 
 * @version 0.9.0 (beta)
 * @copyright 2021 Daily Data, Inc.
 * 
 */

abstract class usersDataSource {
   
   /**
    * @var string[] $configuration Contains the configuration for the class
    * 
    * May be modified by the calling program. Must be replicated in userDataSource class
    */
   protected $configuration = array();

   /**
    * constructor for an instance of the class
    * 
    * If $dbConnection is not null, will be used for database access
    * If $dbLoginInfo is not null, will override $dbConnection, make
    * a new connection and use that.
    * 
    * If $dbDef is set, will be merged with $configuration
    * 
    * @param mysqli $dbConnection Existing mysqli database connection
    * @param string[] $dbDef Array to be merged with $configuration
    * @param string[] $dbLoginInfo Array containing username, hostname, etc.. to make mysqli connection_aborted
    * 
    * @return null
    * 
    */
   public function __construct( $dbDef = array() ) {
      if ( $dbDef ) {
         $this->configuration = array_merge_recursive( $this->configuration, $dbDef );
      }
   }
   
   /**
    * Get a record from the database
    * 
    * Gets a single record from the database which matches $field containing
    * $username. If more than one record is returned, will return the first
    * one
    * 
    * @param string[] $whereFields column=>value pairs for where clause
    * @param string[] $fieldList a list of columns to return. If empty, returns all columns
    * 
    * @return string[] a hash containing fieldname=>value pairs from fetch_assoc
    * 
   */
   abstract public function getARecord( $whereFields, $fieldList = null );
   
   /**
    * Retrieves the password field from table
    * 
    * Note that the password is stored as a hash in the table
    * 
    * @param string $username username used to find record
    * @return string[] an array of values key/value pairs
    */
   abstract public function getPassword( $username );
   
   /**
    * updates row in database with $newData
    * 
    * @param string[] $newData fieldname/value pairs to be updated in table
    * 
    * @return mysqli_result|bool The mysqli result from a query
    */
   abstract public function update ( $newData );
   
   /**
    * retrieves all users from the database
    * 
    * Retrieves all data for all users from table
    * 
    * @return string[] array of array of rows/columns
    */
   abstract public function getAllUsers();


}

?>
