From c9f54c38061a6b2a5b0c4679c58387b1c11805b9 Mon Sep 17 00:00:00 2001 From: shubham_meena Date: Mon, 18 Aug 2014 07:13:15 +0530 Subject: [PATCH] Improved documentation with doxygen generated doc --- code/web/private_php/ams/autoload/dblayer.php | 97 ++++++++++++------- .../private_php/ams/autoload/plugincache.php | 26 +++-- .../web/private_php/ams/autoload/rest_api.php | 8 +- .../private_php/ams/autoload/ticket_log.php | 2 +- .../ams/plugins/API_key_management/.info | 2 +- .../public_php/ams/func/activate_plugin.php | 8 +- .../public_php/ams/func/deactivate_plugin.php | 10 +- .../web/public_php/ams/func/delete_plugin.php | 8 +- .../public_php/ams/func/install_plugin.php | 41 ++++++-- .../web/public_php/ams/func/update_plugin.php | 6 +- .../web/public_php/ams/inc/plugins_update.php | 2 +- 11 files changed, 146 insertions(+), 64 deletions(-) diff --git a/code/web/private_php/ams/autoload/dblayer.php b/code/web/private_php/ams/autoload/dblayer.php index 43282789e..7c4c5435c 100644 --- a/code/web/private_php/ams/autoload/dblayer.php +++ b/code/web/private_php/ams/autoload/dblayer.php @@ -3,13 +3,36 @@ * Handles the database connections. It uses PDO to connect to the different databases. It will use the argument of the constructor to setup a connection to the database * with the matching entry in the $cfg global variable. * + * --> First create an object of dblayer --> $db = new DBLayer('short database name used in config') + * + * --> Insert --> $db->insert( $tb_name, $data ) + * $tb_name = table name in which we want to insert data + * $data = array of data that needs to be inserted in format('fieldname' => $value) where fieldname must be a field in that table. + * + * --> select --> $db->select( $tb_name, $data, $where ) + * $tb_name = table name which we want to select + * $data = array of data which is then required in WHERE clause in format array('fieldname'=>$value) fieldname must be a field in that table. + * $where = string in format ('fieldname=:fieldname') where :fieldname takes it's value from $data array. + * + * --> update --> $db->update( $tb_name, $data, $where ) + * $tb_name = table name which we want to update + * $data = array of data which contains the filelds that need to be updated with their values in the format('fieldname' => $value,...) where fieldname must be a field in that table. + * $where = string contains the filename with a value at that field in the format ('fieldname = $value') where fieldname must be a field in that table and $value is value respect to that field. + * + * --> delete --> $db->delete( $tb_name, $data, $where ) + * $tb_name = table name where we want to delete. + * $data = array of data which is then required in WHERE clause in format array('fieldname'=> $value) where fieldname must be a field in that table. + * $where = string in format ('fieldname=:fieldname') where :fieldname takes it's value from $data array. + * + * * @author Daan Janssens, mentored by Matthew Lagoe + * */ class DBLayer { private $PDO; /** - * *< The PDO object, instantiated by the constructor + * The PDO object, instantiated by the constructor */ /** @@ -17,6 +40,7 @@ class DBLayer { * Instantiates the PDO object attribute by connecting to the arguments matching database(the db info is stored in the $cfg global var) * * @param $db String, the name of the databases entry in the $cfg global var. + * @param $dbn String, the name of the databases entry in the $cfg global var if $db referenced to an action(install etc). */ function __construct( $db, $dbn = null ) { @@ -49,10 +73,10 @@ class DBLayer { } /** - * execute a query that doesn't have any parameters + * Execute a query that doesn't have any parameters. * - * @param $query the mysql query - * @return returns a PDOStatement object + * @param $query the mysql query. + * @return returns a PDOStatement object. */ public function executeWithoutParams( $query ) { $statement = $this -> PDO -> prepare( $query ); @@ -61,11 +85,11 @@ class DBLayer { } /** - * execute a query that has parameters + * Execute a query that has parameters. * - * @param $query the mysql query - * @param $params the parameters that are being used by the query - * @return returns a PDOStatement object + * @param $query the mysql query. + * @param $params the parameters that are being used by the query. + * @return returns a PDOStatement object. */ public function execute( $query, $params ) { $statement = $this -> PDO -> prepare( $query ); @@ -74,10 +98,10 @@ class DBLayer { } /** - * execute a query (an insertion query) that has parameters and return the id of it's insertion + * Insert function which returns id of the inserting field. * - * @param $query the mysql query - * @param $params the parameters that are being used by the query + * @param $tb_name table name where we want to insert data. + * @param $data the parameters that are being inserted into table. * @return returns the id of the last inserted element. */ public function executeReturnId( $tb_name, $data ) { @@ -104,12 +128,14 @@ class DBLayer { } /** - * Select function using prepared statement + * Select function using prepared statement. + * For selecting particular fields. * - * @param string $tb_name Table Name to Select - * @param array $data Associative array - * @param string $where where to select - * @return statement object + * @param string $param field to select, can be multiple fields. + * @param string $tb_name Table Name to Select. + * @param array $data array of data to be used in WHERE clause in format('fieldname'=>$value). 'fieldname' must be a field in that table. + * @param string $where where to select. + * @return statement object. */ public function selectWithParameter( $param, $tb_name, $data, $where ) { @@ -129,12 +155,13 @@ class DBLayer { } /** - * Select function using prepared statement + * Select function using prepared statement. + * For selecting all fields in a table. * - * @param string $tb_name Table Name to Select - * @param array $data Associative array - * @param string $where where to select - * @return statement object + * @param string $tb_name Table Name to Select. + * @param array $data array of data to be used with WHERE part in format('fieldname'=>$value,...). 'fieldname' must be a field in that table. + * @param string $where where to select in format('fieldname=:fieldname' AND ...). + * @return statement object. */ public function select( $tb_name, $data , $where ) { @@ -154,12 +181,12 @@ class DBLayer { } /** - * Update function with prepared statement + * Update function with prepared statement. * - * @param string $tb_name name of the table - * @param array $data associative array with values - * @param string $where where part - * @throws Exception error in updating + * @param string $tb_name name of the table on which operation to be performed. + * @param array $data array of data in format('fieldname' => $value,...).Here, only those fields must be stored which needs to be updated. + * @param string $where where part in format ('fieldname'= $value AND ...). 'fieldname' must be a field in that table. + * @throws Exception error in updating. */ public function update( $tb_name, $data, $where ) { @@ -190,10 +217,11 @@ class DBLayer { } /** - * insert function using prepared statements + * insert function using prepared statements. * - * @param string $tb_name Name of the table to insert in - * @param array $data Associative array of data to insert + * @param string $tb_name Name of the table on which operation to be performed. + * @param array $data array of data to insert in format('fieldname' => $value,....). 'fieldname' must be a field in that table. + * @throws error in inserting. */ public function insert( $tb_name, $data ) { @@ -216,16 +244,17 @@ class DBLayer { { // for rolling back the changes during transaction $this -> PDO -> rollBack(); - throw new Exception( "error in inseting" ); + throw new Exception( "error in inserting" ); } } /** - * Delete database entery using prepared statement + * Delete database entery using prepared statement. * - * @param string $tb_name - * @param string $where - * @throws error in deleting + * @param string $tb_name table name on which operations to be performed. + * @param $data array with values in the format('fieldname'=> $value,...). 'fieldname' must be a field in that table. + * @param string $where condition based on $data array in the format('fieldname=:fieldname' AND ...). + * @throws error in deleting. */ public function delete( $tb_name, $data, $where ) { diff --git a/code/web/private_php/ams/autoload/plugincache.php b/code/web/private_php/ams/autoload/plugincache.php index c90665bc1..8ff258513 100644 --- a/code/web/private_php/ams/autoload/plugincache.php +++ b/code/web/private_php/ams/autoload/plugincache.php @@ -2,7 +2,7 @@ /** * API for loading and interacting with plugins - * contains getters and setters + * contains getters and setters. * * @author shubham meena mentored by Matthew Lagoe */ @@ -14,11 +14,11 @@ class Plugincache { private $plugin_status; private $plugin_info = array(); private $update_info = array(); + /** * A constructor. * Empty constructor */ - public function __construct() { } @@ -207,10 +207,12 @@ class Plugincache { } /** - * returns plugin information with respect to the id + * Returns plugin information with respect to the id. * - * @param id $ plugin id - * @return field info for the plugin + * @param $id plugin id. + * @param $fieldName string plugin field to return + * + * @return info field from the db. */ public static function pluginInfoUsingId( $id, $fieldName ) { @@ -221,9 +223,9 @@ class Plugincache { } /** - * function provides list of active plugins + * Function provides list of active plugins * - * @return $ac_plugins list of active plugins + * @return list of active plugins */ public static function activePlugins() { @@ -235,9 +237,15 @@ class Plugincache { /** * function to load hooks for the active plugins - * and return the contents in the hooks in an array + * and return the contents get from them. + * + * -->Get the list of active plugins then call the global + * hooks exists in the plugins hook file ($pluginName.php). + * -->Collect the contents from the hooks and associate within + * array with key referenced plugin name. + * -->return the content to use with smarty template loader * - * @return $content content available in hooks + * @return $content content get from hooks */ public static function loadHooks() { diff --git a/code/web/private_php/ams/autoload/rest_api.php b/code/web/private_php/ams/autoload/rest_api.php index 74281c6f6..e35586042 100644 --- a/code/web/private_php/ams/autoload/rest_api.php +++ b/code/web/private_php/ams/autoload/rest_api.php @@ -5,7 +5,7 @@ * * Request for the given url using cURL * and send the AccessToken for authentication - * to make public access for the user + * to make public access for the user. * * @author Shubham Meena, mentored by Matthew Lagoe */ @@ -13,12 +13,14 @@ class Rest_Api { /** - * Makes a request using cURL with authentication headers and returns the response. + * Makes a request using cURL with authentication headers , data to post and returns the response. * * @param $url where request is to be sent * @param $applicationKey user generated key * @param $host host for the website - * @return URL response. + * @param $data data to send using POST request + * + * @return $response URL response. */ public function request( $url , $applicationKey, $host , $data ) { diff --git a/code/web/private_php/ams/autoload/ticket_log.php b/code/web/private_php/ams/autoload/ticket_log.php index 6693fe3ce..f83d4b29e 100644 --- a/code/web/private_php/ams/autoload/ticket_log.php +++ b/code/web/private_php/ams/autoload/ticket_log.php @@ -143,7 +143,7 @@ class Ticket_Log{ /** * loads the object's attributes. * loads the object's attributes by giving a ticket_log entries ID (TLogId). - * @param id the id of the ticket_log entry that should be loaded + * @param $id the id of the ticket_log entry that should be loaded */ public function load_With_TLogId( $id) { $dbl = new DBLayer("lib"); diff --git a/code/web/private_php/ams/plugins/API_key_management/.info b/code/web/private_php/ams/plugins/API_key_management/.info index b185a31db..1da25516e 100644 --- a/code/web/private_php/ams/plugins/API_key_management/.info +++ b/code/web/private_php/ams/plugins/API_key_management/.info @@ -1,7 +1,7 @@ PluginName = API Key Management Description = Provides public access to the API's by generating access tokens. Version = 1.0.0 -Type = automatic +Type = Manual TemplatePath = ../../../ams_lib/plugins/API_key_management/templates/index.tpl diff --git a/code/web/public_php/ams/func/activate_plugin.php b/code/web/public_php/ams/func/activate_plugin.php index 930ed15f1..0a331f284 100644 --- a/code/web/public_php/ams/func/activate_plugin.php +++ b/code/web/public_php/ams/func/activate_plugin.php @@ -1,6 +1,9 @@ update( "plugins", array( 'Status' => '1' ), "Id = $id" ); if ( $result ) { + // if result is successfull it redirects and shows success message header( "Location: index.php?page=plugins&result=3" ); exit; } else { + //if result is unsuccessfull it redirects and throws error header( "Location: index.php?page=plugins&result=4" ); exit; } } else { + //if $_GET variable is not set it redirects and shows error header( "Location: index.php?page=plugins&result=4" ); exit; } diff --git a/code/web/public_php/ams/func/deactivate_plugin.php b/code/web/public_php/ams/func/deactivate_plugin.php index a4b6120b1..91986bb50 100644 --- a/code/web/public_php/ams/func/deactivate_plugin.php +++ b/code/web/public_php/ams/func/deactivate_plugin.php @@ -1,6 +1,9 @@ update( "plugins", array( 'Status' => '0' ), "Id = $id" ); if ( $result ) - { + { + // if result is successfull it redirects and shows success message header( "Location: index.php?page=plugins&result=5" ); exit; } else { + // if result is unsuccessfull it redirects and shows success message header( "Location: index.php?page=plugins&result=6" ); exit; @@ -30,6 +35,7 @@ function deactivate_plugin() { } else { + //if $_GET variable is not set it redirects and shows error header( "Location: index.php?page=plugins&result=6" ); exit; } diff --git a/code/web/public_php/ams/func/delete_plugin.php b/code/web/public_php/ams/func/delete_plugin.php index f3dc0311a..d85ed34b9 100644 --- a/code/web/public_php/ams/func/delete_plugin.php +++ b/code/web/public_php/ams/func/delete_plugin.php @@ -1,8 +1,9 @@ delete( 'plugins', array( 'id' => $id ), "Id=:id" ); + //if result successfull redirect and show success message header( "Location: index.php?page=plugins&result=2" ); exit; } else { + // if result unsuccessfull redirect and show error message header( "Location: index.php?page=plugins&result=0" ); exit; } @@ -40,6 +43,7 @@ function delete_plugin() { } else { + // if result unsuccessfull redirect and show error message header( "Location: index.php?page=plugins&result=0" ); exit; } diff --git a/code/web/public_php/ams/func/install_plugin.php b/code/web/public_php/ams/func/install_plugin.php index 052d4f14b..1ad7154d2 100644 --- a/code/web/public_php/ams/func/install_plugin.php +++ b/code/web/public_php/ams/func/install_plugin.php @@ -1,10 +1,32 @@ Check if the file type is .zip. + * --> Extract it to a temp folder. + * --> Check for the .info file. If not exists throw error + * --> Extract the information from the .info file. + * --> Check for the plugin name already exists or not. + * --> if Plugin Name exists it compare the version of .info and version of plugin stored in db. + * --> if same throw error and if different it checks for UpdateInfo field in .info file. + * --> if UpdateInfo not found throw error. + * --> if UpdateInfo found add the update to the ryzom_ams_lib.updates table. + * --> if it's not an update and plugin with same name already exists throw error. + * --> if plugin with same name not present provide option to install plugin + * + * @author Shubham Meena, mentored by Matthew Lagoe + * + */ + + /** - * This function is used in installing plugins - * It performs validation check for the compressed plugin - * then extract in plugin folder to get the info + * This function is used in installing plugins or adding updates + * for previously installed plugins. * - * @author Shubham Meena, mentored by Matthew Lagoe */ function install_plugin() { @@ -165,13 +187,14 @@ function zipExtraction( $target_path, $destination ) * PluginName = Name of the plugin * Version = version of the plugin * Type = type of the plugin + * TemplatePath = path to the template * Description = Description of the plugin ,it's functionality * ----------------------------------------------------------- * * reads only files with name .info * * @param $fileName file to read - * @param $targetPath path to the folder containing .info file + * @param $target_path path to the folder containing .info file * @return array containing above information in array(value => key) */ function readPluginFile( $fileName, $target_path ) @@ -190,8 +213,8 @@ function readPluginFile( $fileName, $target_path ) /** * function to check for updates or * if the same plugin already exists - * also, if the update founds ,check for the update info in the .info file. - * Update is saved in the temp direcotry with pluginName_version.zip + * also, if the update founds ,check for the UpdateInfo in the .info file. + * Update is saved in the temp directory with pluginName_version.zip * * @param $fileName file which is uploaded in .zip extension * @param $findPath where we have to look for the installed plugins @@ -286,8 +309,8 @@ function checkForUpdate( $fileName, $findPath, $tempFile, $tempPath ) * * @param $pluginId id of the plugin for which update is available * @param $updatePath path of the new update - * @return boolean if update for a plugin already exists or - * if update of same version is uploading + * @return boolean True if update already exists else False + * */ function PluginUpdateExists( $pluginId, $updatePath ) { diff --git a/code/web/public_php/ams/func/update_plugin.php b/code/web/public_php/ams/func/update_plugin.php index 1420572b1..cacc5f119 100644 --- a/code/web/public_php/ams/func/update_plugin.php +++ b/code/web/public_php/ams/func/update_plugin.php @@ -1,6 +1,9 @@ executeWithoutParams( "SELECT * FROM plugins INNER JOIN updates ON plugins.Id=updates.PluginId Where plugins.Id=$id" ); @@ -26,6 +29,7 @@ function update_plugin() { // deleting the previous update $db -> delete( "updates", array( 'id' => $row['s.no'] ), "s.no=:id" ); + // if update is installed succesffully redirect to show success message header( "Location: index.php?page=plugins&result=8" ); exit; diff --git a/code/web/public_php/ams/inc/plugins_update.php b/code/web/public_php/ams/inc/plugins_update.php index 89d547860..e08869f98 100644 --- a/code/web/public_php/ams/inc/plugins_update.php +++ b/code/web/public_php/ams/inc/plugins_update.php @@ -1,7 +1,7 @@