CLEANUP: more comments for index.php
authorArun Persaud <arun@nubati.net>
Sat, 15 Mar 2008 23:44:58 +0000 (16:44 -0700)
committerArun Persaud <arun@nubati.net>
Sat, 15 Mar 2008 23:44:58 +0000 (16:44 -0700)
managed to comment the code a bit more ;)

Signed-off-by: Arun Persaud <arun@nubati.net>
index.php

index 80a732fa111e85d5ded99f1e8404ad4610335df7..0c288c71802e529ffdf88f9a7517ac74d6a2cd87 100644 (file)
--- a/index.php
+++ b/index.php
@@ -6,8 +6,10 @@ include_once("output.php");      /* html output only */
 include_once("db.php");          /* database only */
 include_once("functions.php");   /* the rest */
 
 include_once("db.php");          /* database only */
 include_once("functions.php");   /* the rest */
 
+/* make sure that user has set all variables in config.php */
 config_check();
 
 config_check();
 
+/* open database */
 if(DB_open()<0)
   {
     output_header();
 if(DB_open()<0)
   {
     output_header();
@@ -17,13 +19,17 @@ if(DB_open()<0)
     exit();
   }
 
     exit();
   }
 
-/* start a session, if it is not already running */
+/* start a session, if it is not already running.
+ * This way people don't have to log in all the times. 
+ * The session variables can also be read out from different
+ * php scripts, so that the code can be easily split up across several files
+ */
 session_start();
 
 /* done major error checking, output header of HTML page */
 output_header();
 
 session_start();
 
 /* done major error checking, output header of HTML page */
 output_header();
 
-/* check if we want to start a new game */
+/* does the user want to log out? */
 if(myisset("logout"))
   {
     session_unset();
 if(myisset("logout"))
   {
     session_unset();
@@ -32,9 +38,11 @@ if(myisset("logout"))
     echo "<div class=\"message\"><span class=\"bigger\">You are now logged out!</span><br />\n".
       "(<a href=\"$INDEX\">This will take you back to the home-page</a>)</div>";
   }
     echo "<div class=\"message\"><span class=\"bigger\">You are now logged out!</span><br />\n".
       "(<a href=\"$INDEX\">This will take you back to the home-page</a>)</div>";
   }
+/* check if we want to start a new game */
 else if(myisset("new"))
   {
     output_status();
 else if(myisset("new"))
   {
     output_status();
+    /* user need to be logged in to do this */
     if( isset($_SESSION["name"]) )
       {
        $names = DB_get_all_names();
     if( isset($_SESSION["name"]) )
       {
        $names = DB_get_all_names();
@@ -52,6 +60,7 @@ else if(myisset("new"))
 else if( myisset("PlayerA", "PlayerB","PlayerC","PlayerD","dullen","schweinchen","call" ))
   {
     output_status();
 else if( myisset("PlayerA", "PlayerB","PlayerC","PlayerD","dullen","schweinchen","call" ))
   {
     output_status();
+    /* user needs to be logged in */
     if( !isset($_SESSION["name"]) )
       {
        echo "<div class=\"message\">Please <a href=\"$INDEX\">log in</a>.</div>";
     if( !isset($_SESSION["name"]) )
       {
        echo "<div class=\"message\">Please <a href=\"$INDEX\">log in</a>.</div>";
@@ -61,12 +70,13 @@ else if( myisset("PlayerA", "PlayerB","PlayerC","PlayerD","dullen","schweinchen"
        /* get my name */
        $name = $_SESSION["name"];
 
        /* get my name */
        $name = $_SESSION["name"];
 
+       /* the names of the four players */
        $PlayerA = $_REQUEST["PlayerA"];
        $PlayerB = $_REQUEST["PlayerB"];
        $PlayerC = $_REQUEST["PlayerC"];
        $PlayerD = $_REQUEST["PlayerD"];
 
        $PlayerA = $_REQUEST["PlayerA"];
        $PlayerB = $_REQUEST["PlayerB"];
        $PlayerC = $_REQUEST["PlayerC"];
        $PlayerD = $_REQUEST["PlayerD"];
 
-       /* check if user is in the game */
+       /* the person who sets up the game has to be one of the players */
        if(!in_array($name,array($PlayerA,$PlayerB,$PlayerC,$PlayerD)))
          {
            echo "<div class=\"message\">You need to be one of the players to start a <a href=\"$INDEX?new\">new game</a>.</div>";
        if(!in_array($name,array($PlayerA,$PlayerB,$PlayerC,$PlayerD)))
          {
            echo "<div class=\"message\">You need to be one of the players to start a <a href=\"$INDEX?new\">new game</a>.</div>";
@@ -74,16 +84,19 @@ else if( myisset("PlayerA", "PlayerB","PlayerC","PlayerD","dullen","schweinchen"
            DB_close();
            exit();
          }
            DB_close();
            exit();
          }
-
+       
+       /* what rules were selected */
        $dullen      = $_REQUEST["dullen"];
        $schweinchen = $_REQUEST["schweinchen"];
        $call        = $_REQUEST["call"];
 
        $dullen      = $_REQUEST["dullen"];
        $schweinchen = $_REQUEST["schweinchen"];
        $call        = $_REQUEST["call"];
 
+       /* get the emails addresses of the players */
        $EmailA  = DB_get_email_by_name($PlayerA);
        $EmailB  = DB_get_email_by_name($PlayerB);
        $EmailC  = DB_get_email_by_name($PlayerC);
        $EmailD  = DB_get_email_by_name($PlayerD);
 
        $EmailA  = DB_get_email_by_name($PlayerA);
        $EmailB  = DB_get_email_by_name($PlayerB);
        $EmailC  = DB_get_email_by_name($PlayerC);
        $EmailD  = DB_get_email_by_name($PlayerD);
 
+       /* this is used to check if the player names are all ok */
        if($EmailA=="" || $EmailB=="" || $EmailC=="" || $EmailD=="")
          {
            echo "couldn't find one of the names, please start a new game";
        if($EmailA=="" || $EmailB=="" || $EmailC=="" || $EmailD=="")
          {
            echo "couldn't find one of the names, please start a new game";
@@ -92,6 +105,7 @@ else if( myisset("PlayerA", "PlayerB","PlayerC","PlayerD","dullen","schweinchen"
            exit();
          }
 
            exit();
          }
 
+       /* get user ids */
        $useridA  = DB_get_userid_by_name($PlayerA);
        $useridB  = DB_get_userid_by_name($PlayerB);
        $useridC  = DB_get_userid_by_name($PlayerC);
        $useridA  = DB_get_userid_by_name($PlayerA);
        $useridB  = DB_get_userid_by_name($PlayerB);
        $useridC  = DB_get_userid_by_name($PlayerC);
@@ -103,6 +117,7 @@ else if( myisset("PlayerA", "PlayerB","PlayerC","PlayerD","dullen","schweinchen"
 
        /* create game */
        $followup = NULL;
 
        /* create game */
        $followup = NULL;
+       /* is this game a follow up in an already started session? */
        if(myisset("followup") )
          {
            $followup= $_REQUEST["followup"];
        if(myisset("followup") )
          {
            $followup= $_REQUEST["followup"];
@@ -131,7 +146,7 @@ else if( myisset("PlayerA", "PlayerB","PlayerC","PlayerD","dullen","schweinchen"
                          "'$ruleset','$session' ,NULL)");
            else
              {
                          "'$ruleset','$session' ,NULL)");
            else
              {
-               /* get max session */
+               /* get max session and start a new one */
                $max = DB_get_max_session();
                $max++;
                mysql_query("UPDATE Game SET session='".$max."' WHERE id=".DB_quote_smart($followup));
                $max = DB_get_max_session();
                $max++;
                mysql_query("UPDATE Game SET session='".$max."' WHERE id=".DB_quote_smart($followup));
@@ -139,7 +154,7 @@ else if( myisset("PlayerA", "PlayerB","PlayerC","PlayerD","dullen","schweinchen"
                            "'$ruleset','$max' ,NULL)");
              }
          }
                            "'$ruleset','$max' ,NULL)");
              }
          }
-       else
+       else /* no follow up, start a new session */
          {
            /* get ruleset information or create new one */
            $ruleset = DB_get_ruleset($dullen,$schweinchen,$call);
          {
            /* get ruleset information or create new one */
            $ruleset = DB_get_ruleset($dullen,$schweinchen,$call);
@@ -210,7 +225,8 @@ else if( myisset("PlayerA", "PlayerB","PlayerC","PlayerD","dullen","schweinchen"
 
        echo "<div class=\"message\">You started a new game. The emails have been sent out!</div>\n";
       }
 
        echo "<div class=\"message\">You started a new game. The emails have been sent out!</div>\n";
       }
-  }    /* end set up a new game */
+    /* end set up a new game */
+  }    
 /* cancel a game, if nothing has happend in the last N minutes */
 else if(myisset("cancel","me"))
   {
 /* cancel a game, if nothing has happend in the last N minutes */
 else if(myisset("cancel","me"))
   {
@@ -235,7 +251,7 @@ else if(myisset("cancel","me"))
     $gameid   = DB_get_gameid_by_hash($me);
     $myname   = DB_get_name_by_hash($me);
 
     $gameid   = DB_get_gameid_by_hash($me);
     $myname   = DB_get_name_by_hash($me);
 
-    /* check if game really is old enough */
+    /* check if game really is old enough to be canceled */
     $result = mysql_query("SELECT mod_date from Game WHERE id='$gameid' " );
     $r = mysql_fetch_array($result,MYSQL_NUM);
     if(time()-strtotime($r[0]) > 60*60*24*30) /* = 1 month */
     $result = mysql_query("SELECT mod_date from Game WHERE id='$gameid' " );
     $r = mysql_fetch_array($result,MYSQL_NUM);
     if(time()-strtotime($r[0]) > 60*60*24*30) /* = 1 month */
@@ -284,13 +300,13 @@ else if(myisset("remind","me"))
     $gameid   = DB_get_gameid_by_hash($me);
     $myname   = DB_get_name_by_hash($me);
 
     $gameid   = DB_get_gameid_by_hash($me);
     $myname   = DB_get_name_by_hash($me);
 
-    /* check if game really is old enough */
+    /* check if player hasn't done anything in a while */
     $result = mysql_query("SELECT mod_date,player,status from Game WHERE id='$gameid' " );
     $r = mysql_fetch_array($result,MYSQL_NUM);
     if( (time()-strtotime($r[0]) > 60*60*24*7)  && ($r[2]!='gameover') ) /* = 1 week */
       {
        $name = DB_get_name_by_userid($r[1]);
     $result = mysql_query("SELECT mod_date,player,status from Game WHERE id='$gameid' " );
     $r = mysql_fetch_array($result,MYSQL_NUM);
     if( (time()-strtotime($r[0]) > 60*60*24*7)  && ($r[2]!='gameover') ) /* = 1 week */
       {
        $name = DB_get_name_by_userid($r[1]);
-       $To = DB_get_email_by_userid($r[1]);
+       $To   = DB_get_email_by_userid($r[1]);
        $userhash = DB_get_hash_from_gameid_and_userid($gameid,$r[1]);
 
        $message = "Hello $name, \n\n".
        $userhash = DB_get_hash_from_gameid_and_userid($gameid,$r[1]);
 
        $message = "Hello $name, \n\n".
@@ -299,6 +315,7 @@ else if(myisset("remind","me"))
          "Please visit this link now to continue: \n".
          " ".$HOST.$INDEX."?me=".$userhash."\n\n" ;
 
          "Please visit this link now to continue: \n".
          " ".$HOST.$INDEX."?me=".$userhash."\n\n" ;
 
+       /* make sure we don't send too  many reminders to one person */
        if(DB_get_reminder($r[1],$gameid)>0)
          {
            echo "<p>An email has already been sent out.</p>\n";
        if(DB_get_reminder($r[1],$gameid)>0)
          {
            echo "<p>An email has already been sent out.</p>\n";
@@ -331,7 +348,8 @@ else if(myisset("me"))
        DB_close();
        exit();
       }
        DB_close();
        exit();
       }
-
+    
+    /* user might get here by clicking on the link in an email, so session might not be set */
     if(isset($_SESSION["name"]))
       output_status($_SESSION["name"]);
 
     if(isset($_SESSION["name"]))
       output_status($_SESSION["name"]);
 
@@ -424,11 +442,13 @@ else if(myisset("me"))
       case 'start':
        if( !myisset("in") )
          {
       case 'start':
        if( !myisset("in") )
          {
+           /* asks the player, if he wants to join the game */
            output_check_want_to_play($me);
            break;
          }
        else
          {
            output_check_want_to_play($me);
            break;
          }
        else
          {
+           /* check the result, if player wants to join, got next stage, else cancel game */
            if($_REQUEST["in"] == "no")
              {
                /* cancel the game */
            if($_REQUEST["in"] == "no")
              {
                /* cancel the game */
@@ -487,7 +507,7 @@ else if(myisset("me"))
                        DB_set_player_by_gameid($gameid,$who);
 
                        $message = "It's your turn now in game ".DB_format_gameid($gameid).".\n".
                        DB_set_player_by_gameid($gameid,$who);
 
                        $message = "It's your turn now in game ".DB_format_gameid($gameid).".\n".
-                         "Use this link to play a card: ".$HOST.$INDEX."?me=".$hash."\n\n" ;
+                         "Use this link to go the game: ".$HOST.$INDEX."?me=".$hash."\n\n" ;
                        mymail($email,$EmailName."ready, set, go... (game ".DB_format_gameid($gameid).") ",$message);
                        */
                      }
                        mymail($email,$EmailName."ready, set, go... (game ".DB_format_gameid($gameid).") ",$message);
                        */
                      }
@@ -2060,8 +2080,10 @@ else if( myisset("email","password") || isset($_SESSION["name"]) )
         $password  = DB_get_passwd_by_name($name);
        };
 
         $password  = DB_get_passwd_by_name($name);
        };
 
+     /* user has forgotten his password */
      if(myisset("forgot"))
        {
      if(myisset("forgot"))
        {
+        /* check if player is in the database */
         $ok = 1;
 
         $myid = DB_get_userid_by_email($email);
         $ok = 1;
 
         $myid = DB_get_userid_by_email($email);
@@ -2083,6 +2105,7 @@ else if( myisset("email","password") || isset($_SESSION["name"]) )
                 echo "The new password will be valid for one day, make sure you reset it to something else.<br />";
                 echo "Back to the  <a href=\"$INDEX\">main page</a>.";
 
                 echo "The new password will be valid for one day, make sure you reset it to something else.<br />";
                 echo "Back to the  <a href=\"$INDEX\">main page</a>.";
 
+                /* create temporary password, use the fist 8 letters of a md5 hash */
                 $TIME  = (string) time(); /* to avoid collisions */
                 $hash  = md5("Anewpassword".$email.$TIME);
                 $newpw = substr($hash,1,8);
                 $TIME  = (string) time(); /* to avoid collisions */
                 $hash  = md5("Anewpassword".$email.$TIME);
                 $newpw = substr($hash,1,8);
@@ -2095,28 +2118,33 @@ else if( myisset("email","password") || isset($_SESSION["name"]) )
                   " also still be valid until you set a new one\n";
                 mymail($email,$EmailName."recovery ",$message);
 
                   " also still be valid until you set a new one\n";
                 mymail($email,$EmailName."recovery ",$message);
 
+                /* we save these in the database */
                 DB_set_recovery_password($myid,md5($newpw));
               }
             else
               {
                 DB_set_recovery_password($myid,md5($newpw));
               }
             else
               {
+                /* make it so that people (or a robot) can request thousands of passwords within a short time
+                 * and spam a user this way */
                 echo "Sorry you already tried 5 times during the last 24h.<br />".
                   "You need to use one of those passwords or wait to get a new one.<br />";
                 echo "Back to the <a href=\"$INDEX\">main page</a>.";
               }
           }
         else
                 echo "Sorry you already tried 5 times during the last 24h.<br />".
                   "You need to use one of those passwords or wait to get a new one.<br />";
                 echo "Back to the <a href=\"$INDEX\">main page</a>.";
               }
           }
         else
-          {
+          {/* can't find user id in the database */
+            
+            /* no email given? */
             if($email=="")
               echo "You need to give me an email address! <br />".
                 "Please try <a href=\"$INDEX\">again</a>.";
             if($email=="")
               echo "You need to give me an email address! <br />".
                 "Please try <a href=\"$INDEX\">again</a>.";
-            else
+            else /* default error message */
               echo "Couldn't find a player with this email! <br />".
                 "Please contact Arun, if you think this is a mistake <br />".
                 "or else try <a href=\"$INDEX\">again</a>.";
           }
        }
               echo "Couldn't find a player with this email! <br />".
                 "Please contact Arun, if you think this is a mistake <br />".
                 "or else try <a href=\"$INDEX\">again</a>.";
           }
        }
-     else
-     {
+   else 
+     { /* normal user page */
        /* verify password and email */
        if(strlen($password)!=32)
         $password = md5($password);
        /* verify password and email */
        if(strlen($password)!=32)
         $password = md5($password);
@@ -2128,12 +2156,14 @@ else if( myisset("email","password") || isset($_SESSION["name"]) )
 
        if($ok)
         {
 
        if($ok)
         {
+          /* user information is ok */
           $myname = DB_get_name_by_email($email);
           $_SESSION["name"] = $myname;
           output_status();
 
           DB_get_PREF($myid);
 
           $myname = DB_get_name_by_email($email);
           $_SESSION["name"] = $myname;
           output_status();
 
           DB_get_PREF($myid);
 
+          /* does the user want to change some preferences? */
           if(myisset("setpref"))
             {
               $setpref=$_REQUEST["setpref"];
           if(myisset("setpref"))
             {
               $setpref=$_REQUEST["setpref"];
@@ -2165,6 +2195,7 @@ else if( myisset("email","password") || isset($_SESSION["name"]) )
                   break;
                 }
             }
                   break;
                 }
             }
+          /* user wants to change his password or request a temporary one */
           else if(myisset("passwd"))
             {
               if( $_REQUEST["passwd"]=="ask" )
           else if(myisset("passwd"))
             {
               if( $_REQUEST["passwd"]=="ask" )
@@ -2211,6 +2242,7 @@ else if( myisset("email","password") || isset($_SESSION["name"]) )
 
               display_user_menu();
 
 
               display_user_menu();
 
+              /* display all games the user has played */
               echo "<div class=\"user\">";
               echo "<h4>These are all your games:</h4>\n";
               echo "<p>Session: <br />\n";
               echo "<div class=\"user\">";
               echo "<h4>These are all your games:</h4>\n";
               echo "<p>Session: <br />\n";
@@ -2273,11 +2305,13 @@ else if( myisset("email","password") || isset($_SESSION["name"]) )
                 }
               echo "</td></tr>\n</table>\n";
 
                 }
               echo "</td></tr>\n</table>\n";
 
+              /* display last 5 users that have signed up to e-DoKo */
               $names = DB_get_names_of_new_logins(5);
               echo "<h4>New Players:</h4>\n<p>\n";
               echo implode(", ",$names).",...\n";
               echo "</p>\n";
 
               $names = DB_get_names_of_new_logins(5);
               echo "<h4>New Players:</h4>\n<p>\n";
               echo implode(", ",$names).",...\n";
               echo "</p>\n";
 
+              /* display last 5 users that logged on */
               $names = DB_get_names_of_last_logins(5);
               echo "<h4>Players last logged in:</h4>\n<p>\n";
               echo implode(", ",$names).",...\n";
               $names = DB_get_names_of_last_logins(5);
               echo "<h4>Players last logged in:</h4>\n<p>\n";
               echo implode(", ",$names).",...\n";
@@ -2298,6 +2332,8 @@ else if( myisset("email","password") || isset($_SESSION["name"]) )
 /* default login page */
  else
    {
 /* default login page */
  else
    {
+     /* this outputs the default home page with some extra statistics on it */
+
      $pre[0]=0;$game[0]=0;$done[0]=0;
      $r=mysql_query("SELECT COUNT(id) FROM Game GROUP BY status");
      if($r) {
      $pre[0]=0;$game[0]=0;$done[0]=0;
      $r=mysql_query("SELECT COUNT(id) FROM Game GROUP BY status");
      if($r) {