Core Boxx – Core Library Reference

TABLE OF CONTENTS

 

CORE ENGINE CONCEPTS

So you want to learn more about the Core Boxx engine? Well, you may be surprised… The basic concept is kind of funky, but also very lazy.

 

CORE ENGINE FILES

  • 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/Core.php The core engine itself.

 

A QUICK TRACE

OLD SCHOOL OBJECT

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

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

 

EXTEND OBJECT

lib/LIB-Core.php
// (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 this function. For those who are lost, let us walk through what happens when we call $_CORE->load("DB"):

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

That’s all. This is something we do very often in “everyday OOP”, just in a funky manner.

 

 

LAZY REFERENCE

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

We can access the module functions with $_CORE->modules["DB"]->FUNCTION(). But let’s shorten that to $_CORE->DB->FUNCTION() using the magic __get().

 

MODULES LINKING

lib/LIB-Core.php
// (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]; }
  }
}

To explain why we pass in the core object when loading modules $_CORE->modules["DB"] = new DB($_CORE), and for those who are lost:

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

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

 

 

LAZY AUTO-CALL FUNCTIONS

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

Works. But do this over a million times, and you will be sick of this “mapping sh*t”.

 

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

Study $_CORE->autoCall() if you want, but it’s pretty much “EVIL EVAL” to map $_POST $_GET to the specified module/function. Unorthodox? Yes, but will save countless hours of doing “manual mapping”.

 

GLOBAL ERROR HANDLER

LIB-Core.php
// (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.

 

CORE LIBRARY REFERENCES

Now for the list of core library functions, and a few short examples.

 

PROPERTIES

  • $module – Array to “store” loaded modules.
  • $error – Last error message.
  • $page – Pagination data.
  • $mode – Current “operation mode”. Serving a webpage, answering an API call, or running in the command line.

 

MODULES

function load($module)

Loads lib/LIB-$module.php, and extends it to $_CORE->modules[$module] = new $module();

  • $module – String, module to load.
$_CORE->load("Users");
function loaded($module)

Checks if the specified $module is loaded.

  • $module – String, module to check.
if ($_CORE->loaded("Users")) { ... }

 

 

FUNCTION MAPPING

function autoCall($module, $function, $mode)

Automatically map POST or GET variables to the specified module function, and run it.

  • $module – String, module to load.
  • $function – String, function to call.
  • $mode – String, POST or GET. Defaults to POST.
$users = $_CORE->autoCall("Users", "getAll");
function autoAPI($actions, $mode)

Automatically map POST or GET variables to the specified module function, and respond after running it.

  • $actions – Array. The list of API actions and respective module/function handler.
  • $mode – String, POST or GET. Defaults to POST.
$_CORE->autoAPI([
  ["get" => ["Users", "get"]],
  ["save" => ["Users", "save"]],
  ["del" => ["Users", "del"]],
]);

 

SYSTEM

function respond($status, $msg, $data, $more, $http, $exit)

Formats and outputs a standard JSON encoded string.

  • $status – Boolean, 1, 0, or invent your own set of status code.
  • $msg – String, system message.
  • $data – Data if any.
  • $more – Additional data, if any.
  • $http – Optional, HTTP response code.
  • $exit – Optional, stop processing after JSON string output. Defaults to true.
$_CORE->respond(0, "An error has occurred!", null, null, 500);
function ouch($ex)

Nothing to see here. This one is used to handle errors globally.

function random($length)

Creates an alphanumeric string.

  • $length – Integer, number of bytes. Defaults to 8.
$password = $_CORE->random(10);

 

 

OTHER CONVENIENCE

function paginator($entries, $now)

Calculates pagination.

  • $entries – Integer, the total number of entries.
  • $now – Integer, the current page number.
$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
] */
function redirect ($page, $url)

HTTP redirect.

  • $page – Page or path.
  • $url – Defaults to HOST_BASE.
if (!isset($_SESSION["user"])) {
  $_CORE->redirect("login/");
}

Leave a Comment

Your email address will not be published. Required fields are marked *