Core Boxx – Core Engine & Concepts

TABLE OF CONTENTS

Files Config Notes

Core Concepts

Reference & Examples

FILES LIST

• lib/CORE-Go.php The “firestarter”. All your scripts only need to include this file to get Core Boxx started.
• lib/CORE-Config.php System settings.
• lib/LIB-Core.php The core engine itself.

INSTALLER

• lib/CORE-Install.php This is the “install starter”.
• lib/LIB-Install.php Installation process.
• lib/CORE-Install-HTML.php The installation page.
• lib/CORE-Install-JS.php The installation Javascript.

Feel free to reuse the installer for your own project, or delete these when you are done.

PART 1) A QUICK TRACE OF WHAT HAPPENS

1A) OLD SCHOOL OBJECT

class CoreBoxx { ... }
 
// (G) CORE OBJECT + GLOBAL ERROR HANDLING
$_CORE = new CoreBoxx();

In CORE-Go.php, we require "LIB-Core.php" and $_CORE will magically appear. Here is the answer.

1B) EXTEND OBJECT

// (B2) LOAD MODULE
// $module : module to load
function load ($module) : void {
  if ($this->loaded($module)) { return; }
  $file = PATH_LIB . "LIB-$module.php";
  if (file_exists($file)) {
    require $file;
    $this->modules[$module] = new $module($this);
  } else { throw new Exception("$module module not found!"); }
}

The whole idea of “modular” is to extend the $_CORE object using $_CORE->load(). Let us walk through what happens when we load the database module using $_CORE->load("DB"):

• require "LIB-DB.php";
• $_CORE->modules["DB"] = new DB($_CORE);

Yes, that’s all. It’s just “normal OOP in a lazy manner”.

1C) LAZY REFERENCE

// (B3) "MAGIC LINK" TO MODULE
function __get ($name) {
  if (isset($this->modules[$name])) { return $this->modules[$name]; }
}

With the database module loaded, we can now access the database functions with $_CORE->modules["DB"]->FUNCTION(). But staying true to “as lazy as possible”, let’s shorten that to $_CORE->DB->FUNCTION() using the magic __get().

1D) MODULES LINKING

// (F) ALL MODULES SHOULD EXTEND THIS CORE CLASS
class Core {
  // (F1) LINK MODULE TO CORE
  public $Core;
  public $error;
  function __construct ($core) {
    $this->Core =& $core;
    $this->error =& $core->error;
  }
 
  // (F2) MAKE MODULES LINKING EASIER
  function __get ($name) {
    if (isset($this->Core->modules[$name])) { return $this->Core->modules[$name]; }
  }
}

Finally, notice that we pass in the core object when loading modules $_CORE->modules["DB"] = new DB($_CORE). To explain why this is essential for lazy people:

• $_CORE->DB->Core =& $_CORE
• $_CORE->DB->error =& $_CORE->error
• The same old trick with magic __get(). In all the functions of $_CORE->DB, $this->MOD will refer to $_CORE->modules["MOD"].

In short, this will “link” all modules together using pointers. Unorthodox? Yes, but it’s not illegal.

PART 2) LAZY AUTO-CALL FUNCTIONS

// LET'S SAY WE SUBMIT A FORM
$_CORE->load("MyLib");
$result = $_CORE->MyLib->save(
  $_POST["name"], $_POST["email"], $_POST["tel"]
);

This is what “normal people” do to pass a submitted form to a library function. It works. But do this over a million times, and you will be sick of this “map parameters to function sh*t”.

$result = $_CORE->autoCall("MyLib", "save");

Study $_CORE->autoCall() if you want, but it pretty much does “EVIL EVAL” to map $_POST $_GET to the specified module/function. Unorthodox? So what? Would you rather do countless hours of “parameters mapping”?

PART 3) GLOBAL ERROR HANDLER

// (G) CORE OBJECT + GLOBAL ERROR HANDLING
function _CORERR ($ex) { global $_CORE; $_CORE->ouch($ex); }
set_exception_handler("_CORERR");

One last bit to highlight:

• All the errors will be handled by $_CORE->ouch().
• When serving HTML pages, it will show something like a “blue screen of death”. Otherwise, it just outputs a JSON-encoded error message.
• In CORE-Config.php, you may want to hide the error messages on your live server – Keep the error messages in a log file instead.

PROPERTIES

• $modules – Array to “store” loaded modules.
• $error – Last error message.
• $page – Pagination data.
• $mode – Current “operation mode”.
  • C Command line.
  • W Serving a webpage.
  • A Answering an API call.

MODULES

$_CORE->load("Users");

if ($_CORE->loaded("Users")) { ... }

FUNCTION MAPPING

$users = $_CORE->autoCall("Users", "getAll");

$_CORE->autoAPI([
  ["get" => ["Users", "get"]],
  ["save" => ["Users", "save"]],
  ["del" => ["Users", "del"]],
]);

SYSTEM

$_CORE->respond(0, "An error has occurred!", null, null, 500);

OTHER CONVENIENCE

$password = $_CORE->random(10);

$entries = 1234; // DO YOUR OWN SELECT COUNT(*) FROM `TABLE`
$now = 4; // CURRENT PAGE
$_CORE->paginator($entries, $now);
/* $_CORE->page = [
  "entries" => TOTAL NUMBER OF ENTRIES
  "total" => TOTAL NUMBER OF PAGES
  "now" => CURRENT PAGE
  "x" => STARTING ENTRY
  "y" => ENDING ENTRY
  "lim" => "LIMIT X,Y" FOR SQL QUERIES
] */

if (!isset($_SESSION["user"])) {
  $_CORE->redirect("login/");
}

// ONLY ADMINISTRATORS CAN ACCESS THIS PAGE OR API
$_CORE->ucheck("A");