WebSVN – php_users – Diff – /trunk/documentation/users.class.txt

-By itself, the users class (with a data access class like the included UsersDataSourceMySQLi class) handles basic login/logout/editing functions.
+By itself, the users class (with a data access class usersDataSource like the included UsersDataSourceMySQLi class) handles basic login/logout/editing functions.
 The class(es) were, however, designed for extensibility and customization in mind. Some design considerations were made with this in mind.
 This code uses the ternary and null coelescing shortcuts ?: and ??. I THINK these were introduced in PHP 5.3, but not sure. This code will not work on versions which do not have these shortcuts. See https://www.php.net/manual/en/language.operators.comparison.php
+You can get a copy of this from our subversion repository
+svn co http://svn.dailydata.net/svn/php_users/stable php_users
+My working copy is at
+http://svn.dailydata.net/svn/php_users/trunk
+but I recommend NOT using that as I use trunk as my personal playground and will commit broken code to it regularly
 === Basic System ===
 With no modification, the system will store username, password and two booleans, isAdmin and enabled. The default table is created as
 <code sql>
 * login is filtered to alpha-numerics and the underscore character
 * password is stored as a hash using PHP's password_hash
 * users with isAdmin set will be able to add/edit other users
 * users with enabled set to false (0) will not be able to log in
-NOTE: the UsersDataSourceMySQLi class has a public function, buildTable, which will build the table, so installation involves simply calling that function.
+NOTE: the usersDataSource class has a public function, buildTable, which will build the table, so installation involves simply calling that function.
 IMPORTANT: to allow the Users class to work with a wide variety of data types, it does no data access itself. It requires a data access class.
 Basic use in a script involves instantiating a data access class object, then instantiating a Users class object.
       </div>
    </body>
 </html>
 </code>
-This example is using the UsersDataSourceMySQLi definition of  data access (included)
+This example is using the usersDataSource definition of  data access (included)
 If you run it the first time with <code php>$connection->buildTable( 'admin', 'admin' ); die;</code> uncommented, it will build the table. Comment that line out on the next run and you will be presented with a login screen.
 Class function HTML() displays various things to allow login, then quits displaying anything. Setting $_REQUEST['logout'] = 1 before calling HTML() will initiate a log out which will destroy the session variable
 First, everything is pretty basic. I tried to limit the number of fields to the absolute minimum, but also set it up to allow additional fields to be added programmatically. The example does this.
 If you open the class source, you'll find the private member $dbDefinition, which defines everything in the code (I hope). When you create a new instance, you can pass the constructor an array which will be merged with this member, optionally increasing the number and definition of the fields.
-WARNING: if you add new fields to the Users class, you must also add them to class UsersDataSourceMySQLi. See below
+WARNING: if you add new fields to the Users class, you must also add them to class usersDataSource. See below
 Let's add a new field, say we want to store the users e-mail address. In our PHP, create an array as follows:
 <code php>
    $customFields = array(
+            )
       );
  ?>
  </code>
- Now, when we instantiate a new object of class Users AND class UsersDataSourceMySQLi, we simply pass this array in.
+ Now, when we instantiate a new object of class Users AND class usersDataSource, we simply pass this array in.
  <code php>
     $connection = new usersDataSource(
          null,
          $customFields,
    if ( ! isset( $_SESSION['user'] ) ) {
       $_SESSION['user'] = new Users( $customFields );
+   }
 </php>
-Note that since we replicated the basic structure of $dbDefinition in Users and UsersDataSourceMySQLi, we can use the same hash to pass into both; they will store, but ignore values not relevant to them.
+Note that since we replicated the basic structure of $dbDefinition in Users and usersDataSource, we can use the same hash to pass into both; they will store, but ignore values not relevant to them.
 When the usersDataSource and Users objects are created, $customFields will be merged, with duplicates overwritten by the $customFields value.
 This is not limited to adding new columns; you can modify the display definitions also, ie how the information is stored on the screen, to some extent.
+==== usersDataSource ====
+This is our data access class. It really doesn't matter what it is called, though I plan to call it the same when I add more data access objects.
+This code accesses the data (duh), and is consistently called $connection in the Users class. The only requirement is that it must be able to implement the following functions
+getPassword( $username ) returns encrypted password
+getRecord( $username ) returns array containing the values for a user
+getAllUsers() returns an array of all user id's and names
+getARecord( array of key value pairs to limit what is retrieved ) returns all values
+update( array of key value pairs ) returns true/false on success/failure
+It is also nice is it can A) handle new columns and B) create and initialize the necessary storage
+I separated this out from the Users class because not all programs need database access. For instance, the favorites_urls app uses file based storage, so by writing a new access class for it, we will hopefully be able to get the same functionality, but with a different storage back end.
+==== Future ====
+This is only the initial part of this particular project. I now intend to extend both classes to allow boolean permissions which will be integrated into our new version of CAMP, giving very granular rights to users. It will be available as a second set of files in this repository and is planned for release by October 2021.

Subversion Repositories php_users

(root)/trunk/documentation/users.class.txt – Rev 4 → 6