+-----------------------+
| Controller files: PHP |
+-----------------------+

Location: /PhotoSite/controller

-------------------------------- session controllers ---------------------------

Filename:   sessionVariables.js
-------------------------------
Purpose:    To interact with client-side JavaScript/jQuery functions and the
            server-side controllers that involve SESSION variables.  Invokes
            and receives result of all session-based Ajax calls.
Features:   1) Manages client-side variable sessionArray.

Filename:   getSessionVariables.php
-----------------------------------
Purpose:    Returns all SESSION variables as JSON so the client can maintain
            its own copy of the values without constant server polling.
                      
Filename:   setSessionPageRegion.php
------------------------------------
Purpose:    To set (via Ajax call) the SESSION variable which holds the region
            of the portal page a user was on.  (Useful for page refreshes)
            
Filename:   setSessionUserID.php
------------------------------------
Purpose:    To set (via Ajax call) the SESSION variable which holds the user_id
            and username.
            
------------------------------- pure  DB controllers ---------------------------
          
Filename:   getStandardTags.php
-------------------------------
Purpose:    This PHP file will invoke a database function in tagFunctions.php
            which, in turn, echos the appropriate values for the standard
            hashtags as JSON.

Filename:   getTags.php
-----------------------
Purpose:    (UNUSED).  Original intention was to load the entire tag table into
            client memory to enable autocomplete.
Futures:    1) This PHP should be reworked to use the query string to either
               retrieve all hashtags in use, or only the standard ones.  Then,
               getStandardTags.php can be eliminted.
               
Filename:   getPhotoComments.php
--------------------------------
Purpose:    Retrieve all comments on a photos as JSON.
Futures:    1) Should be merged with getPhotoCommentsSince.php using a 
               querystring.

Filename:   getPhotoCommentsSince.php
-------------------------------------
Purpose:    Retrieve all comments on a photos as JSON after a certain date.

Filename:   getUsers.php
------------------------
Purpose:    Based on querystring, invokes DB function to get all users or only
            the user record for a given user_id.
      
Filename:   getUserPhotos.php
-----------------------------
Purpose:    Retrieve a users photos.  Based on querystring, it will either
            retreive these photos as normal JSON (using database field names) or
            as JSON that can be consumed by ddslick for image dropdowns.

Filename:   getRelationships.php
--------------------------------
Purpose:    Leverage the relationships view to return as JSON all of the
            people you have friended and all the people that have friended you.
Features:   1) The DB UNION view builds the structure against the
               photo_friendships table that has relationship records whether
               a person has friended another or been friended.  (Friendships may
               be one-way in this application.)
               
Filenames:  searchByTag.php, seachByTerm.php, searchByUser.php
--------------------------------------------------------------
Purpose:    Pass a substring to the database and return search results as JSON.
            Depending on which controller is invoked, a different DB search
            routine will be run.  Each routine targets specific columns of a
            DB view.  searchByTerm() is the least specific.
               
Filename:   storeComment.php
----------------------------
Purpose:    Insert comment into the database.

Filename:   updateOrDeleteComment.php
-------------------------------------
Purpose:    Based on querystring, this will invoke the DB functions to either
            update or delete a comment.
            
Filename:   updateOrDeleteUser.php
-------------------------------------
Purpose:    Based on querystring, this will invoke the DB functions to either
            update or delete a user.
Features:   1) Primary key changes for user_id if a user is activated or
               deactivated.
            2) Handles requests from both user maintainence forms and username/
               password reset forms.

Fileame:    DBfunctionTester.php
--------------------------------
Purpose:    A comprehensive tester of all database selects that can be run by
            an admin for troubleshooting.

---------------------------------- file controllers ----------------------------

Filename:   getDocumentation.php
--------------------------------
Purpose:    Reads a documentation text file on the server and returns the data
Parameters: Querystring parameter for the name of the file
Features:   1) If the querystring is not set, it will begin scraping with the
               current chart, othewise it will start on the specified date.
            2) Includes a PHP library to manipulate the HTML DOM.  The
               technique used is to load all HTML elements of a given type
               e.g., $html->find("option") to place all <option>s into an
               array or $html->find("a[onClick]"); to load anchor tags that
               have an onClick attrbute similarly.
               
deprotectDirectoryAndRemoveFiles.php
------------------------------------
Purpose:    A backend controller that will deprotect a directory and delete
            all files in that directory.  Used during development, but is a
            good example of directing PHP shell_exec results to the browser.
    
------------------------------- DB/file controllers ----------------------------

Filename:   storePhoto.php
--------------------------
Purpose:    Store photo metadata in the database and the imag file on the file
            server.
Features:   1) Aggregation of user-specified hashtags with any selected standard
               hashtags.
            2) Creation of a photo record in the database
            3) Use of the photo's primary key to generate a unique filename.
               The filename is based on the combination of the uploaded filename
               and the primary key, e.g.,  "myCat_78.jpg"
            4) Directory creation for each user (if not previously built)
            
Filename:   deletePhoto.php
---------------------------
Purpose:    Delete a photo from the database and the file system
       
----------------------------- special use controllers --------------------------

Filename:   login.php
---------------------
Purpose:    Starts a user session upon successful login and provides back-end
            server validation of login form data (as last resort / safeguard)
Features:   1) Various validation checks on username and password fields
            2) Manage the database calls to obtain user information and react
               accordingly
            3) Utilizes login form parameters to perform either a login or a
               registration.
               
Filename:   usernameAndPasswordValidation.php
---------------------------------------------
Purpose:    Provids back-end server validation of usernames and passwords.
Note:       Should never be needed, as this reproduces all of the client checks,
            but is still utilized as a fail-safe measure.