From c870b0f4bb688d58575c700f523972bd5cf1be55 Mon Sep 17 00:00:00 2001
From: George Halkiadakis <gchalkiadakis@sklavenitis.co.gr>
Date: Wed, 17 May 2023 03:27:03 +0300
Subject: initializing framework refactoring completed

---
 core/classes/cache/Cache_interface.php |  5 ++++-
 core/classes/cache/FileCache.php       | 24 +++++++++++++--------
 public/app/config/bootstrap.php        |  2 +-
 public/app/config/setup_framework.php  | 39 +++++++++++++++++++++-------------
 public/index.php                       | 17 ++++++---------
 5 files changed, 50 insertions(+), 37 deletions(-)

diff --git a/core/classes/cache/Cache_interface.php b/core/classes/cache/Cache_interface.php
index 7c49789..1c96f5a 100644
--- a/core/classes/cache/Cache_interface.php
+++ b/core/classes/cache/Cache_interface.php
@@ -1,9 +1,12 @@
 <?php
 
 /** Cache interface
- * ---
+ * -----------------------------------------------------------------------------
+ * 
  * Interface to save results of expensive data-extraction proccess,
  * in a fast-accessed medium (ussually RAM or NVME SSD units)
+ * 
+ * -----------------------------------------------------------------------------
  */
 interface Cache_interface
 {
diff --git a/core/classes/cache/FileCache.php b/core/classes/cache/FileCache.php
index fb7eee5..fe4a4e4 100644
--- a/core/classes/cache/FileCache.php
+++ b/core/classes/cache/FileCache.php
@@ -1,20 +1,26 @@
 <?php
 
 /* FileCache
- * ---
+ * -----------------------------------------------------------------------------
+ * 
  * Saves serialized data into filesystem.
- * Use it for expensive database-queries.
- * Performanve on a NVMe-SSD drive is really great;
- * (even better than MemCached and Redis)
- * performance on a typical HDD is just fair.
+ * 
+ * Use it for repetitive expensive database-queries
+ * or other common time/source-consuming tasks
+ * 
+ * Performance on a local NVMe-SSD drive can be great;
+ * Performance on a typical HDD is just fair.
  *
  * NOTE:
  * Memcached and Redis are much faster cache-technologies
- * and generally recommended; but they are not always available;
+ * (when implemented locally) but not always available;
  * FileCache is (almost) always available;
  * 
- * Before tou decide on your caching technology
- * run some benchmarks.
+ * RECOMMENDATION:
+ * Before you decide on your actual caching technology
+ * design and run a few comparative benchmarks
+ * 
+ * -----------------------------------------------------------------------------
  */
 class FileCache implements Cache_interface
 {
@@ -28,7 +34,7 @@ class FileCache implements Cache_interface
     {
         // filename is a hashed 48-hex-digit string
         // probability of collision = exp( (-k*(k-1)) / 2N )
-        // ex: for 10tril.samples P(collision) = 1.5E-11%
+        // example case: for 10tril.samples P(collision) = 1.5E-11
         $filename = FILECACHE_PATH . sha1($key);
 
         // Opening file for write
diff --git a/public/app/config/bootstrap.php b/public/app/config/bootstrap.php
index a51272e..4a482f9 100644
--- a/public/app/config/bootstrap.php
+++ b/public/app/config/bootstrap.php
@@ -19,7 +19,7 @@
  * -----------------------------------------------------------------------------
  */
 
-// setup error-handliing
+// include error-handliing
 // -----------------------------------------------------------------------------
 require_once APP_ROOT.'/core/helpers/error_handling.php';
 
diff --git a/public/app/config/setup_framework.php b/public/app/config/setup_framework.php
index 69c3402..384a643 100644
--- a/public/app/config/setup_framework.php
+++ b/public/app/config/setup_framework.php
@@ -47,7 +47,7 @@ if (file_exists(APP_ROOT ."/.env")) {
 
 
 
-/** ENVIRONMENT constant
+/** ENVIRONMENT constant ///////////////////////////////////////////////////////
  * -----------------------------------------------------------------------------
  * 
  * define application's environment stage; [PRODUCTION|staging|develpment|testing|*]
@@ -63,7 +63,7 @@ define('PRODUCTION', ($env['ENVIRONMENT'] == 'PRODUCTION') );
 
 
 
-/** APPLICATION NAMES AND URL DEFAULTS
+/** APPLICATION NAMES AND URL DEFAULTS /////////////////////////////////////////
  * -----------------------------------------------------------------------------
  * 
  * NOTE:
@@ -88,12 +88,12 @@ define('SITE_URL', $env['ANOM_HOSTNAME']);
 
 
 
-/** APPLICATION PATHS
+/** APPLICATION PATHS //////////////////////////////////////////////////////////
  * -----------------------------------------------------------------------------
  * 
  * Obligarory:
  * These are needed in order to run the bare minimum MVC system
- * They also make code easier to read
+ * They also make code easier to oranize and navigate into.
  * 
  * NOTE:
  * most likely you do not need to change any of these subsection defines;
@@ -134,7 +134,7 @@ define('AUTOLOADER' , APP_ROOT.'/vendor/autoload.php');
  * -----------------------------------------------------------------------------
  * 
  * NOTE: if the custom autoloadet is used
- * then you need to defing CLASSPATHS constant-array too;
+ * then you need to define CLASSPATHS constant-array too;
  */
 
 # define('AUTOLOADER' , '../core/helpers/autoload.php');
@@ -165,7 +165,7 @@ define('AUTOLOADER' , APP_ROOT.'/vendor/autoload.php');
 
 
 
-/** SESSION HANDLING
+/** SESSION HANDLING ///////////////////////////////////////////////////////////
  * -----------------------------------------------------------------------------
  * 
  * there are several session drivers for session handling:
@@ -196,7 +196,7 @@ define('SESSION_DRIVER', $env['SESSION_DRIVER'] ?? 'DefaultSession');
 
 
 
-/** COOKIE SETTINGS
+/** COOKIE SETTINGS ////////////////////////////////////////////////////////////
  * -----------------------------------------------------------------------------
  * 
  * Define cookie policy (cookie sharing and securing)
@@ -233,6 +233,7 @@ define('MAX_SESSION_LIFE', 2*60*60);    // maximum session lifetime (2 hours)
 
 
 
+
 /** SECURITY SETTINGS ///////////////////////////////////////////////////////////
  * -----------------------------------------------------------------------------
  * 
@@ -259,7 +260,7 @@ define('CSRF_EXCLUDE_URIS', array());   // Array of URIs which ignore CSRF check
 
 
 
-/* ADVANCED OPTIMIZATION ///////////////////////////////////////////////////////
+/* CACHE DRIVER ////////////////////////////////////////////////////////////////
  * -----------------------------------------------------------------------------
  *
  * APP_CACHE defines the cache-driver;
@@ -269,11 +270,14 @@ define('CSRF_EXCLUDE_URIS', array());   // Array of URIs which ignore CSRF check
  * 'FileCache'  : caching in filesystem; fair if caching on HDD; great on SSD
  * 'RedisCache' : caching in Redis server; generally recommended if available
  * 'MemCachedCache' : caching in Memcached server; recommended if available
+ * 
+ * You can configure the caching parametres later on this file;
  *
- * NOTE: FileCache on a NVMe SDD is the fastest option;
+ * NOTE:
+ * Nowadays FileCache on a NVMe SDD seems to be the fastest option;
  * Redis and Memcached are really-fast caching options and are available for
- * scaling horizontaly your application (eache one has it's own strngths;
- * study, then choose the one that fulfills your needs;
+ * scaling horizontaly your application (each one having it's own strengths)
+ *
  * -----------------------------------------------------------------------------
  */
   
@@ -311,7 +315,9 @@ define('CACHE_DRIVER', $env['CACHE_DRIVER'] ?? 'FileCache');
  * /////////////////////////////////////////////////////////////////////////////
  */
 
-/** DATABASE CONNECTION PARAMETRES
+
+
+/** DATABASE CONNECTION PARAMETRES /////////////////////////////////////////////
  * -----------------------------------------------------------------------------
  * Production and staging environments may use different databases.
  * 
@@ -345,7 +351,7 @@ define('DB_TIMEZONE', "SET time_zone = 'Europe/Athens'");
  
  
  
-/** CACHED SERVICES
+/** CACHED SERVICES ////////////////////////////////////////////////////////////
  * -----------------------------------------------------------------------------
  * 
  * impemented services:
@@ -411,7 +417,7 @@ define('MEDIA_STORAGE_ROOT', APP_ROOT.'/storage/uploads/');    // Media files ro
 
 
 
-/** General Scope Constants
+/** General Scope Constants ////////////////////////////////////////////////////
  * -----------------------------------------------------------------------------
  * 
  * needed by the framework for common tasks
@@ -423,6 +429,8 @@ define('MEDIA_STORAGE_ROOT', APP_ROOT.'/storage/uploads/');    // Media files ro
  * -----------------------------------------------------------------------------
  */
 
+
+
 /** COMMON CONTENT TYPES
  * -----------------------------------------------------------------------------
  */
@@ -449,6 +457,7 @@ define('COMMON_CONTENT_TYPES', array(
 );
 
 
+
 /** PROXY_FLAGS
  * -----------------------------------------------------------------------------
  * These options represend altered/non-default behaviour
@@ -461,7 +470,7 @@ define('PROXY_DO_NOT_CACHE', 4);  // do not cache result
 
 
 
-/** need even more constants?
+/** need even more constants? //////////////////////////////////////////////////
  * -----------------------------------------------------------------------------
  * 
  * Append them here,
diff --git a/public/index.php b/public/index.php
index 9dea217..c0b0b68 100644
--- a/public/index.php
+++ b/public/index.php
@@ -7,8 +7,7 @@
  * Let's keep it simple and clear
  * 
  * anom is an(other) Object-Oriented MVC php-framework.
- * It is a super-light, fast and extensible development
- * tool.
+ * It is a super-light, fast and extensible.
  * 
  * Contains implementations of almost anything you need
  * to start and optimize a server-based web-application.
@@ -22,22 +21,18 @@
  * -----------------------------------------------------------------------------
  */
 
-// specify base paths
+// Define the Base Paths
 // -----------------------------------------------------------------------------
-
 $dir = explode('/', __DIR__);
 $pub = array_pop($dir);
 
-define('APP_ROOT', implode('/',$dir));      // root of application (public's parent)
-
-define('WEB_ROOT', APP_ROOT.'/'.$pub);      // root of public directory
-
+define('APP_ROOT', implode('/',$dir));  // App's root directory
+define('WEB_ROOT', APP_ROOT.'/'.$pub);  // the public directory
 
 
 // Load parametres:
-// contants and constant arrays
+// paths, contants and central arrays
 // -----------------------------------------------------------------------------
-
 require_once WEB_ROOT.'/app/config/setup_framework.php';        // application constants
 
 
@@ -64,10 +59,10 @@ if (!PRODUCTION)   Benchmark::add_spot('start');    // benchmark request's life
 // Initialize Application
 // finalize framework; handle credentials; setup app-engine; insert routes
 // -----------------------------------------------------------------------------
-
 require_once APPLICATION_BOOTSTRAP;
 
 
+
 // Application is ready!
 // -----------------------------------------------------------------------------
 
-- 
cgit v1.2.3