Minor - updating comments

main/inc/global.inc.php

@@ -19,13 +19,13 @@
  */
 
 // Fix bug in IIS that doesn't fill the $_SERVER['REQUEST_URI'].
-//@todo not sure if this is needed any more
+//@todo not sure if we need this
 //api_request_uri();
 
 // This is for compatibility with MAC computers.
 //ini_set('auto_detect_line_endings', '1');
 
-//Autoloader
+// Composer autoloader
 require_once __DIR__.'../../../vendor/autoload.php';
 
 use Silex\Application;
@@ -46,11 +46,12 @@ $app = new Application();
 $includePath = dirname(__FILE__);
 
 // Include the main Chamilo platform configuration file.
-//@todo use a service provider like:
+// @todo use a service provider to load configuration files:
 /*
     $app->register(new Igorw\Silex\ConfigServiceProvider($settingsFile));
 */
 
+/** Loading configuration files */
 $configurationFilePath = $includePath.'/conf/configuration.php';
 $configurationYMLFile = $includePath.'/../../config/configuration.yml';
 $configurationFileAppPath = $includePath.'/../../config/configuration.php';
@@ -85,6 +86,8 @@ if (file_exists($configurationYMLFile)) {
 
 // End reading configuration file
 
+/** Loading legacy libs */
+
 // Include the main Chamilo platform library file.
 require_once $includePath.'/lib/main_api.lib.php';
 
@@ -97,7 +100,7 @@ require_once $includePath.'/lib/internationalization_internal.lib.php';
 // Do not over-use this variable. It is only for this script's local use.
 $libPath = $includePath.'/lib/';
 
-// Loading config files
+/** Loading config files */
 if ($alreadyInstalled) {
     $configPath = $includePath.'/../../config/';
 
@@ -249,13 +252,13 @@ $app->register(new Silex\Provider\SecurityServiceProvider(), array(
     )
 ));*/
 
-// Setting controllers as services
+// Setting Controllers as services provider
 $app->register(new Silex\Provider\ServiceControllerServiceProvider());
 
 // Validator provider
 $app->register(new Silex\Provider\ValidatorServiceProvider());
 
-// Implements Symfony2 translator
+// Implements Symfony2 translator (needed when using forms in Twig)
 $app->register(new Silex\Provider\TranslationServiceProvider(), array(
     'locale' => 'en',
     'locale_fallback' => 'en'
@@ -346,7 +349,7 @@ $app['template_style'] = 'default';
 // Default layout
 $app['default_layout'] = $app['template_style'].'/layout/layout_1_col.tpl';
 
-//Setting the Twig service provider
+// Setting Twig as a service provider
 $app->register(
     new Silex\Provider\TwigServiceProvider(),
     array(
@@ -387,10 +390,10 @@ $app['twig'] = $app->share(
     })
 );
 
-// Registering Menu extension
+// Registering Menu service provider (too gently creating menus with the URLgenerator provider)
 $app->register(new \Knp\Menu\Silex\KnpMenuServiceProvider());
 
-//Pagerfanta settings (Pagination)
+// Pagerfanta settings (Pagination using Doctrine2, arrays, etc)
 use FranMoreno\Silex\Provider\PagerfantaServiceProvider;
 $app->register(new PagerfantaServiceProvider());
 
@@ -401,13 +404,13 @@ $app['pagerfanta.view.options'] = array(
     'proximity'     => 3,
     'next_message'  => '»',
     'prev_message'  => '«',
-    'default_view'  => 'twitter_bootstrap'
+    'default_view'  => 'twitter_bootstrap' // the pagination style
 );
-
+// Custom route params see https://github.com/franmomu/silex-pagerfanta-provider/pull/2
 //$app['pagerfanta.view.router.name']
 //$app['pagerfanta.view.router.params']
 
-//Monolog only available if cache is writable
+// Monolog only available if the log dir is writable
 if (is_writable($app['temp.path'])) {
 
     /*
@@ -478,24 +481,23 @@ if (isset($app['configuration']['main_database'])) {
 
 define('IMAGE_PROCESSOR', 'gd'); // imagick or gd strings
 
+// Setting the Imagine service provider to deal with image transformations used in social group.
 $app->register(new Grom\Silex\ImagineServiceProvider(), array(
     'imagine.factory' => 'Gd',
     //'imagine.base_path' => __DIR__.'/vendor/imagine',
 ));
 
-
+// Manage Chamilo error messages
-
-
-//Manage error messages
 $app->error(
     function (\Exception $e, $code) use ($app) {
 
         if ( $e instanceof PDOException) {
-
         }
+
         if ($app['debug']) {
             //return;
         }
+
         if (isset($code)) {
             switch ($code) {
                 case 404:
@@ -534,7 +536,7 @@ if ($app['debug'] && isset($app['configuration']['main_database'])) {
 
 // Database constants
 require_once $libPath.'database.constants.inc.php';
-//@todo tranform the events.lib.inc.php in a class
+// @todo Rewrite the events.lib.inc.php in a class
 require_once $libPath.'events.lib.inc.php';
 
 // Connect to the server database and select the main chamilo database.
@@ -631,13 +633,13 @@ if ($alreadyInstalled && $checkConnection) {
 // Load allowed tag definitions for kses and/or HTMLPurifier.
 require_once $libPath.'formvalidator/Rule/allowed_tags.inc.php';
 
-// which will then be usable from the banner and header scripts
+// Section (tabs in the main chamilo menu)
 $app['this_section'] = SECTION_GLOBAL;
 
 // include the local (contextual) parameters of this course or section
 require $includePath.'/local.inc.php';
 
-//Adding web profiler
+// Adding symfony2 web profiler (memory, time, logs, etc)
 if (is_writable($app['temp.path'])) {
     //if ($app['debug']) {
 
@@ -647,6 +649,7 @@ if (is_writable($app['temp.path'])) {
             ));
         $app->mount('/_profiler', $p);
     }
+
     //$app->register(new Whoops\Provider\Silex\WhoopsServiceProvider);
     //}
 }
@@ -667,19 +670,24 @@ $app->register(new Silex\Provider\SwiftmailerServiceProvider(), array(
 $app['mailer'] = $app->share(function ($app) {
     return new \Swift_Mailer($app['swiftmailer.transport']);
 });
-use Bt51\Silex\Provider\GaufretteServiceProvider\GaufretteServiceProvider;
 
+// Gaufrette service provider (to manage files/dirs) (not used yet)
+/*
+use Bt51\Silex\Provider\GaufretteServiceProvider\GaufretteServiceProvider;
 $app->register(new GaufretteServiceProvider(), array(
     'gaufrette.adapter.class' => 'Local',
     'gaufrette.options' => array(api_get_path(SYS_DATA_PATH))
 ));
+*/
 
+// Use symfony2 filesystem instead of custom scripts
 use Neutron\Silex\Provider\FilesystemServiceProvider;
 $app->register(new FilesystemServiceProvider());
 
+// Setting languages
 $app['api_get_languages'] = api_get_languages();
 
-/*	Loading languages and sublanguages */
+/**	Loading languages and sublanguages **/
 
 // if we use the javascript version (without go button) we receive a get
 // if we use the non-javascript version (with the go button) we receive a post
@@ -773,8 +781,6 @@ if (isset($this_script) && $this_script == 'sub_language') {
     }
 }
 
-
-
 /**
  * Include all necessary language files
  * - trad4all
@@ -839,13 +845,13 @@ if (is_array($language_files)) {
         }
     }
 }
-
+// End loading languages
-/* End loading languages */
 
 // Specification for usernames:
 // 1. ASCII-letters, digits, "." (dot), "_" (underscore) are acceptable, 40 characters maximum length.
 // 2. Empty username is formally valid, but it is reserved for the anonymous user.
 // 3. Checking the login_is_email portal setting in order to accept 100 chars maximum
+// @todo this should be configured somewhere else usermanager.class.php? a users.yml setting?
 
 $default_username_length = 40;
 if (api_get_setting('login_is_email') == 'true') {
@@ -854,7 +860,9 @@ if (api_get_setting('login_is_email') == 'true') {
 
 define('USERNAME_MAX_LENGTH', $default_username_length);
 
-/** Silex Middlewares: A before application middleware allows you to tweak the Request before the controller is executed */
+/** Silex Middlewares: */
+
+/** A "before" middleware allows you to tweak the Request before the controller is executed */
 
 $app->before(
     function () use ($app, $checkConnection) {
@@ -890,20 +898,21 @@ $app->before(
     }
 );
 
-/** Silex Middlewares: An after application middleware allows you to tweak the Response before it is sent to the client */
+/** An after application middleware allows you to tweak the Response before it is sent to the client */
 $app->after(
     function (Request $request, Response $response) {
 
     }
 );
 
-/** Silex Middlewares: A finish application middleware allows you to execute tasks after the Response has been sent to
+/** A "finish" application middleware allows you to execute tasks after the Response has been sent to
  * the client (like sending emails or logging) */
 $app->finish(
     function (Request $request) use ($app) {
 
     }
 );
+// End Silex Middlewares
 
 // The global variable $charset has been defined in a language file too (trad4all.inc.php), this is legacy situation.
 // So, we have to reassign this variable again in order to keep its value right.
@@ -915,6 +924,7 @@ $text_dir = api_get_text_direction();
 
 // Update of the logout_date field in the table track_e_login (needed for the calculation of the total connection time)
 
+/** "Login as user" custom script */
 if (!isset($_SESSION['login_as']) && isset($_user)) {
     // if $_SESSION['login_as'] is set, then the user is an admin logged as the user
 
@@ -949,23 +959,29 @@ if (!isset($_SESSION['login_as']) && isset($_user)) {
 // The langstat object will then be used in the get_lang() function.
 // This block can be removed to speed things up a bit as it should only ever
 // be used in development versions.
+// @todo create a service provider to load this
 if (isset($app['configuration']['language_measure_frequency']) && $app['configuration']['language_measure_frequency'] == 1) {
     require_once api_get_path(SYS_CODE_PATH).'/cron/lang/langstats.class.php';
     $langstats = new langstats();
 }
 
+/** Setting the course quota */
+// @todo move this somewhere else
+
 // Default quota for the course documents folder
 $default_quota = api_get_setting('default_document_quotum');
 // Just in case the setting is not correctly set
 if (empty($default_quota)) {
     $default_quota = 100000000;
 }
-
 define('DEFAULT_DOCUMENT_QUOTA', $default_quota);
 
+/** Setting the is_admin key */
+
 $app['is_admin'] = false;
 
-// Creating a Chamilo service provider
+/** Chamilo service provider */
+
 use Silex\ServiceProviderInterface;
 
 class ChamiloServiceProvider implements ServiceProviderInterface
@@ -1000,6 +1016,7 @@ class ChamiloServiceProvider implements ServiceProviderInterface
 $app->register(new ChamiloServiceProvider(), array());
 
 // Controller as services definitions
+// @todo move definitions in another file
 
 $app['pages.controller'] = $app->share(function () use ($app) {
     return new PagesController($app['pages.repository']);
@@ -1058,8 +1075,8 @@ $app['posts.controller'] = $app->share(function() use ($app) {
 $app->mount('/', "posts.controller");*/
 
 /**
- * Nice middlewares that will fix the permission problems in Chamilo
+ * Custom chamilo middlewares that will fix the permission problems in Chamilo
- * @todo move this in a permission class
+ * @todo move this
  **/
 $checkCourse = function (Request $request) use ($app) {
     $courseCode = $request->get('courseCode');
@@ -1096,7 +1113,7 @@ $userAccessPermissions = function (Request $request) use ($app) {
     $courseCode = $request->get('cidReq');
 };
 
-// End middlewares
+// End custom middlewares
 
 // @todo put routes somewhere else, in a yml/php file .
 
@@ -1104,6 +1121,7 @@ $userAccessPermissions = function (Request $request) use ($app) {
  * All calls made in Chamilo (olds ones) are manage in the LegacyController::classicAction function located here:
  * src/ChamiloLMS/Controller/LegacyController.php
  */
+
 $app->get('/', 'legacy.controller:classicAction')
     ->before($courseAccessConditions)
     ->before($userAccessPermissions);
@@ -1116,7 +1134,7 @@ $app->post('/', 'legacy.controller:classicAction')
 $app->match('/index', 'index.controller:indexAction', 'GET|POST')
     ->bind('index');
 
-// web/userportal
+// Userportal
 $app->get('/userportal', 'userPortal.controller:indexAction');
 $app->get('/userportal/{type}/{filter}/{page}', 'userPortal.controller:indexAction')
     ->value('type', 'courses') //default values
@@ -1170,4 +1188,5 @@ $app->get('/data/document_templates/{file}', 'index.controller:getDocumentTempla
 // Data default_platform_document files
 $app->get('/data/default_platform_document/', 'index.controller:getDefaultPlatformDocumentAction')
     ->assert('type', '.+');
+
 return $app;