add various comments to functions.php

functions.php

@@ -1,13 +1,16 @@
 <?php
+//load the database functions
 require('db.php');
-// the function which varifies a users credentials
+
-// against the database
+/* the function which verifies a user's credentials
+   against the database */
 function login ()
 {
     session_start();
     if (isset($_REQUEST['username'])) {
-        //Checking if the user exists in the database or not
         global $con;
+
+        /* assign the variables with data from the login form */
         $username = stripslashes($_REQUEST['username']);
         //escapes special characters in a string
         $username = mysqli_real_escape_string($con,$username);
@@ -15,9 +18,14 @@ function login ()
         $current_user = $username;
         $password = stripslashes($_REQUEST['password']);
         $password = mysqli_real_escape_string($con,$password);
+
+        //check the form data against the database
         $query = "SELECT * FROM users WHERE userLogin='$username'
                   and userPass='$password'";
         $result = mysqli_query($con,$query) or die(mysqli_error());
+
+        /* forward the user to the home.php page if the login is correct
+           otherwise prompt an error message*/
         $rows = mysqli_num_rows($result);
         if ($rows==1) {
             $_SESSION['username'] = $username;
@@ -34,6 +42,8 @@ function register ()
 {
     if (isset($_REQUEST['username'])) {
         global $con;
+
+        /* assign the variables with data from the login form */
         // removes backslashes
         $username = stripslashes($_REQUEST['username']);
         //escapes special characters in a string
@@ -42,10 +52,15 @@ function register ()
         $email = mysqli_real_escape_string($con,$email);
         $password = stripslashes($_REQUEST['password']);
         $password = mysqli_real_escape_string($con,$password);
+
+        /* create a new user entry inside the database */
         $query = "INSERT into users (userLogin, userPass, userEmail)
                   VALUES ('$username', '$password', '$email')";
         $result = mysqli_query($con,$query);
-        // checks if the username or email addresse is already taken
+
+        /* tell the user if the username or the email address are
+           already present in the database based on the return code
+           of the database*/
         if ($result) {
             echo "<div class='form'>
                   <h3>You are registered successfully.</h3>
@@ -56,7 +71,8 @@ function register ()
     }
 }
 
-//A function to read out the userId of the current user
+/*A function to get the userId from the database for the current
+  logged in user based on the username used to login*/
 function get_userid ()
 {
     global $con;
@@ -74,13 +90,17 @@ function post_demand ()
     if (isset($_POST['submit'])) {
         global $con;
         $userId = get_userid();
+
+        /* assign the variables with data from the demand form */
         $piecesMax = $_POST['piecesMax'];
         $piecesMin = $_POST['piecesMin'];
         $qualityId = $_POST['quality'];
         $deliveryDate = $_POST['deliveryDate'];
         $title = $_POST['title'];
         $text = $_POST['text'];
-        // Inserts Data into Database
+
+        /* check if the values make sense before adding them to
+           the databse */
         if ($piecesMax <= $piecesMin) {
             echo "<strong class='warning'>
                   The Maximum must be bigger than the Minimum!
@@ -96,28 +116,38 @@ function post_demand ()
     }
 }
 
-// A function to insert the own posts from the database into the website
+// A function to insert the demand titles from the database into the website
 function get_demand_titles ()
 {
     global $con;
+
+    //get the data from the database
     $sql = "SELECT * FROM demands";
     $result = mysqli_query($con, $sql);
+
+    /*fetch the data from the $result array and insert it into
+      the corresponding HTML code */
     while ($row = $result->fetch_assoc()) {
         echo "<div class='post-box'><p>";
         echo "<strong>" . $row['demandTitle'] . "</strong></a>" . "<br>";
         echo $row['date'] . "<br>";
 
+        //add a delete button to the demand output
         echo "<form class= 'delete-form' method= 'POST'
         action='".delete_demand()."'>
         <input type='hidden' name='demandId' value='".$row['demandId']."'>
         <button type='submit' name= 'deletepost'> Delete</button>
         </form>";
 
+        /*add a button to the demand output which let's the user view
+        the demand details */
         echo "<form method= 'POST' action='show_demand.php'>
         <input type='hidden' name='demandId' value='".$row['demandId']."'>
         <button>Show Details</button>
         </form>";
 
+        /* add an edit button to the demand output and give it the
+           necessary data to edit. */
         echo "<form class= 'edit-form' method= 'POST' action='edit_demand.php'>
         <input type='hidden' name='userId' value='".$row['userId']."'>
         <input type='hidden' name='demandId' value='".$row['demandId']."'>
@@ -138,6 +168,8 @@ function edit_demand ()
 {
     if (isset($_POST['edit'])) {
         global $con;
+
+        /* assign the variables with data from the edit button */
         $demandId = $_POST['demandId'];
         $piecesMax = $_POST['piecesMax'];
         $piecesMin = $_POST['piecesMin'];
@@ -145,7 +177,8 @@ function edit_demand ()
         $title = $_POST['title'];
         $text = $_POST['text'];
 
-        // Inserts Updates Database
+        /* Inserts the updates into the database if the values
+           make sense otherwise inform the user about his error*/
         if ($piecesMax <= $piecesMin) {
             echo "<strong class='warning'>
                   The Maximum must be bigger than the Minimum!
@@ -163,36 +196,45 @@ function edit_demand ()
         }
     }
 }
+
 // A function to delete a post
 function delete_demand()
 {
     if (isset($_POST['deletepost'])) {
         global $con;
+
+        /* assign the variable with data from the delete button */
         $demandId = $_POST['demandId'];
 
-        // Delete Post from Database
+        // Delete the demand matching the demandId from the database
         $sql = "DELETE FROM demands WHERE demandId='$demandId'";
         $result = mysqli_query($con, $sql) or die(mysqli_error($con));
         header('Location: board.php');
   }
 }
 
+//a function to show a demand's details
 function show_demand ()
 {
     global $con;
+
+    /* assign the variable with data from the details button */
     $demandId = $_POST['demandId'];
 
+    //get the corresponding data from the database
     $demand_query = "SELECT * FROM demands where demandId='$demandId'";
     $demand_query_result = mysqli_query($con, $demand_query) or
                          die(mysqli_error($con));
     $demand_rows = $demand_query_result->fetch_object();
 
+    //get the quality requested in the demand from the database
     $qualityId = $demand_rows->qualityId;
     $quality_query = "SELECT * FROM quality where qualityId='$qualityId'";
     $quality_query_result = mysqli_query($con, $quality_query) or
                           die(mysqli_error($con));
     $quality_rows = $quality_query_result->fetch_object();
 
+    //print the demand details
     echo "<h2>" . $demand_rows->demandTitle . "</h2>";
     echo "<br>
           <br>";
@@ -210,24 +252,32 @@ function show_demand ()
           <br>
           <strong>Description:</strong><br>";
     echo "$demand_rows->demandText<br><br>";
+
+    /*add a "Post Offer" button to the demand's details to let a user
+      post an offer */
     echo "<form method= 'POST' action='add_offer.php'>
          <input type='hidden' name='demandId' value='$demand_rows->demandId'>
          <button>Post Offer</button>
          </form><br>";
-    
 }
 
+//A function to post an offer to a demand
 function post_offer()
 {
     if (isset($_POST['submit'])) {
         global $con;
+
+        //get the current user's ID
         $userId = get_userid();
+
+        /* assign the variables with data from the "Post Offer" form*/
         $demandId = $_POST['demandId'];
         $pieces = $_POST['pieces'];
         $price = $_POST['price'];
         $qualityId = $_POST['quality'];
         $text = $_POST['text'];
-        // Inserts Data into Database
+
+        // Insert the offer into the database
         $sql = "INSERT INTO offers (pieces, text, price, userId, qualityId,
                                     demandId)
                VALUES ('$pieces', '$text', '$price', '$userId', '$qualityId',
@@ -236,9 +286,12 @@ function post_offer()
     }
 }
 
+//A function to print out the offers to a demand
 function show_offer ()
 {
     global $con;
+
+    /* assign the variables with data from demand*/
     $demandId = $_POST['demandId'];
 
     // get the offers matching the demand from the database
@@ -248,6 +301,8 @@ function show_offer ()
 
     // if the query on the database returned data print the data
     while ($offer_rows = $offer_query_result->fetch_object()) {
+
+        //get the corresponding quality data from the database
         $qualityId = $offer_rows->qualityId;
         $quality_query = "SELECT * FROM quality where qualityId='$qualityId'";
         $quality_query_result = mysqli_query($con, $quality_query) or
@@ -268,6 +323,8 @@ function show_offer ()
             <br>
             <strong>Description:</strong><br>";
         echo $offer_rows->text . "<br><br>";
+
+        /*Add a button to each offer which let's the user export the offer*/
         echo "<form method= 'POST' action='export_offer.php'>
          <input type='hidden' name='offerId' value='$offer_rows->offerId'>
          <button>Export this Offer</button>
@@ -275,11 +332,15 @@ function show_offer ()
     }
 }
 
+//A function which exports an offer to XML
 function export_offer ()
 {
     global $con;
+
+    /* assign the variable with data from "Export Offer" button*/
     $offerId = $_POST['offerId'];
 
+    /*get the offer and all it's related the data from the database*/
     $offer_export_query = "SELECT o.offerId,
                                   o.text,
                                   o.price,
@@ -295,17 +356,17 @@ function export_offer ()
                            WHERE o.offerId = '$offerId';";
     $query_result = mysqli_query($con, $offer_export_query) or
                         die(mysqli_error($con));
-
     $export_rows = $query_result->fetch_object();
 
     //create a dom document with encoding utf8
     $domtree = new DOMDocument('1.0', 'UTF-8');
 
-    // create the root element of the xml tree
+    /* create the root element of the xml tree and append it to
+       the dom document*/
     $xmlRoot = $domtree->createElement("offer");
-    // append it to the document created
     $offer_export = $domtree->appendChild($xmlRoot);
 
+    //add the offer fields as child elements to the XML
     $offer_export->appendChild(
         $domtree->createElement('demand_title',$export_rows->demandTitle));
     $offer_export->appendChild(
@@ -321,7 +382,9 @@ function export_offer ()
     $offer_export->appendChild(
         $domtree->createElement('offer_date',$export_rows->date));
 
-    /* get the xml printed */
+    // format the dom document
+     $offer_export->formatOutput = true;
+    // print out the generate dom document
     echo $domtree->saveXML();
 }
 ?>