From eadb83ceb120ba306715caab4a018c709555a3fe Mon Sep 17 00:00:00 2001
From: Skylar <admin@netsyms.com>
Date: Thu, 19 May 2016 00:41:51 -0600
Subject: [PATCH] Add comments/documentation

---
 database.php         |  5 ++++-
 dieifnotloggedin.php |  4 +++-
 getitem.php          |  4 +++-
 getlocation.php      |  4 +++-
 getmodel.php         |  4 +++-
 getstatus.php        |  4 +++-
 login.php            |  5 ++++-
 readfrom.php         |  5 ++++-
 required.php         | 29 +++++++++++++++++++----------
 search.php           |  5 ++++-
 updateitem.php       |  7 +++++--
 11 files changed, 55 insertions(+), 21 deletions(-)

diff --git a/database.php b/database.php
index 5a0619c..87ab2d6 100644
--- a/database.php
+++ b/database.php
@@ -1,5 +1,8 @@
 <?php
-
+/**
+ * Database configuration.  If running on the same machine as snipeit,
+ * you can probably use the same settings here.
+ */
 $database = new medoo(
         [
     'database_type' => 'mysql',
diff --git a/dieifnotloggedin.php b/dieifnotloggedin.php
index b68e9f1..3fc2ad3 100644
--- a/dieifnotloggedin.php
+++ b/dieifnotloggedin.php
@@ -1,5 +1,7 @@
 <?php
-
+/**
+ * Simple way to block people that aren't logged in.
+ */
 require_once 'required.php';
 
 if ($_SESSION['loggedin'] !== true || is_empty($_SESSION['user'])) {
diff --git a/getitem.php b/getitem.php
index fae3708..6120fa2 100644
--- a/getitem.php
+++ b/getitem.php
@@ -1,5 +1,7 @@
 <?php
-
+/**
+ * Dump a database row for a given asset/accessory/consumable
+ */
 require 'required.php';
 require 'dieifnotloggedin.php';
 
diff --git a/getlocation.php b/getlocation.php
index f97a612..f604c31 100644
--- a/getlocation.php
+++ b/getlocation.php
@@ -1,5 +1,7 @@
 <?php
-
+/**
+ * Get a list of all locations, and the location for a given id if any.
+ */
 require 'required.php';
 //require 'dieifnotloggedin.php';
 
diff --git a/getmodel.php b/getmodel.php
index 34d15bc..ec99a14 100644
--- a/getmodel.php
+++ b/getmodel.php
@@ -1,5 +1,7 @@
 <?php
-
+/**
+ * Get all the models.
+ */
 require 'required.php';
 //require 'dieifnotloggedin.php';
 
diff --git a/getstatus.php b/getstatus.php
index 6eb2ad2..855e1a8 100644
--- a/getstatus.php
+++ b/getstatus.php
@@ -1,5 +1,7 @@
 <?php
-
+/**
+ * Get all status types.
+ */
 require 'required.php';
 //require 'dieifnotloggedin.php';
 
diff --git a/login.php b/login.php
index a529dcf..9cd85eb 100644
--- a/login.php
+++ b/login.php
@@ -1,7 +1,10 @@
 <?php
-
+/**
+ * Handles login requests, authentication, and session creation.
+ */
 require 'required.php';
 
+// For lazy browser testing
 //$_POST = $_GET;
 
 $user = $_POST['user'];
diff --git a/readfrom.php b/readfrom.php
index 2593080..8853ed7 100644
--- a/readfrom.php
+++ b/readfrom.php
@@ -1,5 +1,8 @@
 <?php
-
+/**
+ * Filter table info to sane choices.  You could add aliases if you like.
+ * The app uses all of these variations because I'm lazy and just pass label text.
+ */
 switch ($from) {
     case 'accessories':
     case 'accessory':
diff --git a/required.php b/required.php
index 4ed4aca..bdaedae 100644
--- a/required.php
+++ b/required.php
@@ -1,12 +1,16 @@
 <?php
 
-ob_start();
+ob_start(); // No worries about sending headers before/after content
 session_start();
-require 'vendor/autoload.php';
-require 'database.php';
 
-define('JSON', true);
-header('Content-Type: application/json');
+require 'vendor/autoload.php'; // Load database stuff from Composer
+require 'database.php'; // Load database settings
+
+define('JSON', true); // Don't touch this or Something Bad might happen.
+header('Content-Type: application/json'); // Don't touch this either.
+
+// Completely disable CORS stuff, everything is allowed.  You could change this
+// if you know exactly what domain traffic is coming from.
 header('Access-Control-Allow-Origin: ' . $_SERVER['HTTP_ORIGIN']);
 header('Access-Control-Allow-Credentials: true');
 
@@ -39,11 +43,6 @@ function authenticate_user($username, $password) {
     global $database;
     $qf = 'username';
     if (!username_exists($username)) {
-//        if (!email_exists($username)) {
-//            return false;
-//        } else {
-//            $qf = 'email';
-//        }
         return false;
     }
     $hash = $database->select('users', ['password'], [$qf => $username])[0]['password'];
@@ -59,6 +58,11 @@ function is_empty($str) {
     return (!isset($str) || $str == '' || $str == null);
 }
 
+/**
+ * Send a generic OK message.
+ * @param string $message Optional message text.
+ * @param boolean $die End execution after sending message (default true).
+ */
 function sendOK($message = "", $die = true) {
     if (!is_empty($message) && JSON) {
         echo '{ "status": "OK", "message": "' . $message . '" }';
@@ -74,6 +78,11 @@ function sendOK($message = "", $die = true) {
     }
 }
 
+/**
+ * Send an error message.
+ * @param string $error Error text.
+ * @param boolean $die End execution after sending error (default true).
+ */
 function sendError($error, $die = true) {
     if (JSON) {
         echo '{ "status": "ERROR", "message": "' . $error . '" }';
diff --git a/search.php b/search.php
index 8111594..e12f1c5 100644
--- a/search.php
+++ b/search.php
@@ -1,5 +1,7 @@
 <?php
-
+/**
+ * Search for a given term (q=) in a given category (from=) and spit out JSON.
+ */
 require 'required.php';
 
 require 'dieifnotloggedin.php';
@@ -13,6 +15,7 @@ if (is_empty($q)) {
 }
 
 $results;
+// If you want to search through more/different fields, just add them.
 if ($from == 'assets') {
     $results = $database->select($from, '*', ['OR' => ['name[~]' => $q, 'asset_tag[~]' => $q, 'serial[~]' => $q, 'order_number[~]' => $q]]);
 } else {
diff --git a/updateitem.php b/updateitem.php
index 869448c..d74bdfb 100644
--- a/updateitem.php
+++ b/updateitem.php
@@ -1,5 +1,7 @@
 <?php
-
+/**
+ * Create/update an item.
+ */
 require 'required.php';
 require 'dieifnotloggedin.php';
 
@@ -12,6 +14,7 @@ if (is_empty($_POST['asset_tag']) && $from == 'assets') {
 }
 
 if (is_empty($id)) {
+    // We need to create an item
     if ($from == 'assets') {
         $user_id = $database->select('users', 'id', ['username' => $_SESSION['user']])[0];
         $database->insert($from, ['name' => $_POST['name'], 'user_id' => $user_id, 'asset_tag' => $_POST['asset_tag'], 'rtd_location_id' => $_POST['location'], 'order_number' => $_POST['order_number'], 'status_id' => $_POST['status'], 'serial' => $_POST['serial'], 'model_id' => $_POST['model'], '#updated_at' => 'NOW()', '#created_at' => 'NOW()', '_snipeit_hard_drive_secure__y_n_' => $_POST['hdd_secure']]);
@@ -19,7 +22,7 @@ if (is_empty($id)) {
         $database->insert($from, ['name' => $_POST['name'], 'location_id' => $_POST['location'], 'qty' => $_POST['qty'], 'order_number' => $_POST['order_number'], '#updated_at' => 'NOW()', '#created_at' => 'NOW()']);
     }
 } else {
-
+    // Update an existing item by id
     if ($from == 'assets') {
         $database->update($from, ['name' => $_POST['name'], 'asset_tag' => $_POST['asset_tag'], 'rtd_location_id' => $_POST['location'], 'order_number' => $_POST['order_number'], 'status_id' => $_POST['status'], 'serial' => $_POST['serial'], 'model_id' => $_POST['model'], '#updated_at' => 'NOW()', '_snipeit_hard_drive_secure__y_n_' => $_POST['hdd_secure']], ['id' => $id]);
     } else {