From b91adfb3aac70a8bf59238402f766e68f56db754 Mon Sep 17 00:00:00 2001
From: martin <martin@martin-ThinkPad-T410.(none)>
Date: Wed, 30 Mar 2011 13:53:48 -0400
Subject: [PATCH] -Airtime.ini should follow PHP coding guidelines more
 closely.

---
 install/include/AirtimeIni.php | 79 ++++++++++++++++++++++++++++------
 1 file changed, 67 insertions(+), 12 deletions(-)

diff --git a/install/include/AirtimeIni.php b/install/include/AirtimeIni.php
index 8a5071392..33e7f772e 100644
--- a/install/include/AirtimeIni.php
+++ b/install/include/AirtimeIni.php
@@ -1,4 +1,10 @@
 <?php
+/**
+ * @package Newscoop
+ * @subpackage Subscriptions
+ * @copyright 2011 Sourcefabric o.p.s.
+ * @license http://www.gnu.org/licenses/gpl-3.0.txt
+ */
 
 // Do not allow remote execution
 $arr = array_diff_assoc($_SERVER, $_ENV);
@@ -9,6 +15,7 @@ if (isset($arr["DOCUMENT_ROOT"]) && ($arr["DOCUMENT_ROOT"] != "") ) {
     exit(1);
 }
 
+//make sure user has Postgresql PHP extension installed.
 if (!function_exists('pg_connect')) {
     trigger_error("PostgreSQL PHP extension required and not found.", E_USER_ERROR);
     exit(2);
@@ -16,7 +23,12 @@ if (!function_exists('pg_connect')) {
 
 class AirtimeIni{
 
-    static function CreateIniFile(){
+    /**
+     * This function creates the /etc/airtime configuration folder
+     * and copies the default config files to it.
+     */
+    static function CreateIniFile()
+    {
         if (!file_exists("/etc/airtime/")){
             if (!mkdir("/etc/airtime/", 0755, true)){
                 echo "Could not create /etc/airtime/ directory. Exiting.";
@@ -42,7 +54,12 @@ class AirtimeIni{
         }
     }
 
-    static function RemoveIniFiles(){
+    /**
+     * This function removes /etc/airtime and the configuration
+     * files present within it.
+     */
+    static function RemoveIniFiles()
+    {
         if (file_exists("/etc/airtime/airtime.conf")){
             unlink("/etc/airtime/airtime.conf");
         }
@@ -64,6 +81,11 @@ class AirtimeIni{
         }
     }
 
+    /**
+     * Ensures that the user is running this PHP script with root
+     * permissions. If not running with root permissions, causes the
+     * script to exit. 
+     */
     static function ExitIfNotRoot()
     {
         // Need to check that we are superuser before running this.
@@ -73,35 +95,68 @@ class AirtimeIni{
         }
     }
 
-    static function GenerateRandomString($len=20, $chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789')
+    /**
+     * This function generates a random string.
+     *
+     * The random string uses two parameters: $p_len and $p_chars. These
+     * parameters do not need to be provided, in which case defaults are
+     * used.
+     *
+     * @param string $p_len
+     *      How long should the generated string be.
+     * @param string $p_chars
+     *      String containing chars that should be used for generating.
+     * @return string
+     *      The generated random string.
+     */
+    static function GenerateRandomString($p_len=20, $p_chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789')
     {
         $string = '';
-        for ($i = 0; $i < $len; $i++)
+        for ($i = 0; $i < $p_len; $i++)
         {
-            $pos = mt_rand(0, strlen($chars)-1);
-            $string .= $chars{$pos};
+            $pos = mt_rand(0, strlen($p_chars)-1);
+            $string .= $p_chars{$pos};
         }
         return $string;
     }
 
-    static function UpdateIniValue($filename, $property, $value)
+    /**
+     * This function updates an INI style config file.
+     *
+     * A property and the value the property should be changed to are
+     * supplied. If the property is not found, then no changes are made.
+     *
+     * @param string $p_filename
+     *      The path the to the file.
+     * @param string $p_property
+     *      The property to look for in order to change its value.
+     * @param string $p_value
+     *      The value the property should be changed to.
+     *      
+     */
+    static function UpdateIniValue($p_filename, $p_property, $p_value)
     {
-        $lines = file($filename);
+        $lines = file($p_filename);
         $n=count($lines);
         for ($i=0; $i<$n; $i++) {
-            if (strlen($lines[$i]) > strlen($property))
-            if ($property == substr($lines[$i], 0, strlen($property))){
-                $lines[$i] = "$property = $value\n";
+            if (strlen($lines[$i]) > strlen($p_property))
+            if ($p_property == substr($lines[$i], 0, strlen($p_property))){
+                $lines[$i] = "$p_property = $p_value\n";
             }
         }
 
-        $fp=fopen($filename, 'w');
+        $fp=fopen($p_filename, 'w');
         for($i=0; $i<$n; $i++){
             fwrite($fp, $lines[$i]);
         }
         fclose($fp);
     }
 
+    /**
+     * After the configuration files have been copied to /etc/airtime,
+     * this function will update them to values unique to this
+     * particular installation.
+     */
     static function UpdateIniFiles()
     {
         $api_key = AirtimeIni::GenerateRandomString();