Fred.php

Go to the documentation of this file.

<?php

namespace Rsi;

ini_set('display_errors',false);
error_reporting(E_ALL);

/**
 *  Framework for Rapid and Easy Development.
 *
 *  The Fred object is at the core of the framework. From this object all components will be initialized. This is done in a
 *  'lazy' manner. That is: only when the component is specificly called (through the component() function or with a magic
 *  __get()).
 *
 *  This object also does autoloading and error handling. The magic __call() method is mapped to the item() function of the
 *  entity component.
 */
class Fred extends Thing{

  const EVENT_HALT = 'fred:halt';
  const EVENT_EXTERNAL_ERROR = 'fred:externalError';
  const EVENT_SHUTDOWN = 'fred:shutdown';

  public $debug = false; //!< True for debug modus.
  public $autoloadCacheKey = 'fred:autoloadCache'; //!< Session key for classnames cache.
  public $autoloadMissingKey = 'fred:autoloadMissing'; //!< Session key for missing classnames cache.
  public $defaultComponentNamespace = __CLASS__; //!< Default namespace for components. If there is no class name defined for a
    // component, then the framework will try to load the class in this namespace with the same name (ucfirst-ed).

  public $templatePath = __DIR__ . '/../../template/'; //!< Path for the framework templates.
  public $version = null; //!< Project version.
  public $ignoreErrors = '/^SOAP-ERROR/'; //!< Errors to ignore on shutdown (regex).
  public $stripObjectsMemoryLimit = null;
  public $stripObjectsMaxDepth = 10;

  protected $_startTime = null; //!< Time at which the request started.
  protected $_initialized = false; //!< True if the framework is initialised.
  protected $_config = []; //!< The configuration.
  protected $_internalError = false; //!< True if an internal error has (already) occured.
  protected $_errorHash = null; //!< Hash for the latest caught error.
  protected $_errorBacktrace = null; //!< Backtrace for the latest caught error.
  protected $_timeLimit = null; //!< Execution cut-off timestamp.

  protected $_autoloadNamespaces = []; //!< Autoload namespace prefix (key) en paths (value).
  protected $_autoloadClasses = []; //!< Autoload classes (key) and files (value).
  protected $_autoloadFiles = []; //!< Autoload files (if not covered by the previous options).
  protected $_autoloadCache = []; //!< Register direct location of class files.
  protected $_autoloadCacheLimit = 250; //!< Size limit for the autoload cache.
  protected $_autoloadMissing = []; //!< Register missing autoload classes (prevent double checking).
  protected $_sharedCacheFile = null; //!< Shared cache file.
  protected $_sharedCacheTime = null; //!< Creation time of the shared cache.
  protected $_sharedCacheTtl = 600; //!< Time-to-live for shared cache.
  protected $_sharedCacheTtlSpread = 10; //!< Random spread for TTL.
  protected $_components = []; //!< Initialized components (key = component name, value = component).

  protected $_releaseNotesFile = __DIR__ . '/../../doc/pages/notes.php';
  protected $_releaseNotesKey = 'fred:releaseNotesTime'; //!< Session key for release notes change time.

  protected $_maintenanceTime = null; //!< Date and time set for maintenance (site inaccessible) in 'Y-m-d H:i:s' format.
  protected $_maintenanceMessage = []; //!< Messages to show before maintenance starts. Key = seconds before start to show
    // message (once per session), from shortest to longer. Add a colon to specify message type, e.g. '30:error' (defaults to
    // warning). Value = message (translated, use 'time' tag to insert maintenance time, 'delta' for time left in minutes; time
    // 'limit' and message 'type' are also available).
  protected $_maintenanceKey = 'fred:maintenanceMessage'; //!< Session key for last maintenance message.

  /**
   * Initialize the framework.
   * @param string|array $config  The configuration. In case of a string, the file with this name will be included.
   */
  public function __construct($config){
    try{
      $this->_startTime = $_SERVER['REQUEST_TIME_FLOAT'] ?? microtime(true);
      $this->_config = is_array($config) ? $config : require($config);
      spl_autoload_register([$this,'autoload'],true,true);
      $this->init();
    }
    catch(\Exception $e){
      $this->exceptionHandler($e);
    }
  }
  /**
   * Initialize the framework.
   */
  protected function init(){
    $this->configure($this->_config);
    ini_set('display_errors',$this->debug);
    set_error_handler([$this,'errorHandler']);
    set_exception_handler([$this,'exceptionHandler']);
    register_shutdown_function([$this,'shutdownFunction']);
    $this->publish(['startTime' => self::READABLE,'autoloadNamespaces' => self::READABLE,'autoloadClasses' => self::READABLE]);
    try{
      if(session_status() == PHP_SESSION_NONE) session_start();
      if($this->_sharedCacheFile) try{
        include($this->_sharedCacheFile);
        if((($delta = $this->_startTime - $this->_sharedCacheTime - $this->_sharedCacheTtl) > 0) && ($delta > rand(0,1000) / 1000 * $this->_sharedCacheTtlSpread)){
          $this->_autoloadCache = $this->_autoloadMissing = [];
          $this->_sharedCacheTime = null;
        }
      }
      catch(\Throwable $e){
        \Rsi\File::unlink($this->_sharedCacheFile);
        $this->log->info($e);
      }
      if(array_key_exists($this->autoloadCacheKey,$_SESSION))
        $this->_autoloadCache = array_merge($this->_autoloadCache,$_SESSION[$this->autoloadCacheKey]);
      if(array_key_exists($this->autoloadMissingKey,$_SESSION))
        $this->_autoloadMissing = array_merge($this->_autoloadMissing,$_SESSION[$this->autoloadMissingKey]);
    }
    catch(\Exception $e){
      if($this->debug) throw $e;
    }
    if($this->debug){
      $this->log->debug('FRED™ framework initialized',__FILE__,__LINE__);
      $this->releaseNotes();
    }
    else $this->maintenance();
    $this->_initialized = true;
  }

  protected function saveSharedCache(){
    if($this->_initialized && $this->_sharedCacheFile) try{
      file_put_contents($temp = $this->_sharedCacheFile . uniqid('-',true) . '.tmp',"<?php\n" .
        '$this->_sharedCacheTime = ' . ($this->_sharedCacheTime ?: $this->_startTime) . '; //modified ' . date('Y-m-d H:i:s') . "\n" .
        '$this->_autoloadCache = ' . var_export($this->_autoloadCache,true) . ";\n" .
        '$this->_autoloadMissing = ' . var_export(count($this->_autoloadMissing) > $this->_autoloadCacheLimit ? [] : $this->_autoloadMissing,true) . ';'
      );
      if(!rename($temp,$this->_sharedCacheFile)) throw new \Exception("Could not rename('$temp','{$this->_sharedCacheFile}')");
      chmod($this->_sharedCacheFile,0666);
    }
    catch(\Exception $e){
      $this->log->info($e);
      try{
        unlink($temp);
      }
      catch(\Exception $e){}
    }
    else{
      $_SESSION[$this->autoloadCacheKey] = array_slice($this->_autoloadCache,0,$this->_autoloadCacheLimit,true);
      $_SESSION[$this->autoloadMissingKey] = array_slice($this->_autoloadMissing,0,$this->_autoloadCacheLimit);
    }
  }
  /**
   * Autoloader.
   * The autoloader tries to load a class in 3 steps:
   * - If the class is specificly mentioned in the $_autoloadClasses, then the corresponding file will be loaded.
   * - If the class name starts with a prefix from the $_autoloadNamespaces, then the rest of the class name (namespace
   *   separator = directory separator) and the path corresponding path will be used to create the filename.
   * - If both these options fail, all files in the $_autoloadFiles will be loaded (once) (hoping the sought class will be in
   *   there).
   */
  public function autoload($class_name){
    if($this->debug && $this->_initialized) $this->log->debug(__CLASS__ . "::autoload('$class_name')",__FILE__,__LINE__,['className' => $class_name]);
    if(array_key_exists($class_name,$this->_autoloadCache)) require($this->_autoloadCache[$class_name]);
    elseif(array_key_exists($class_name,$this->_autoloadClasses)) return require($this->_autoloadClasses[$class_name]);
    elseif(!in_array($class_name,$this->_autoloadMissing)){
      $prefix_match = false;
      foreach($this->_autoloadNamespaces as $prefix => $paths) if(substr($class_name,0,strlen($prefix)) == $prefix){
        $prefix_match = true;
        foreach($paths as $path) if(is_file($filename = $path . str_replace(['_','\\'],'/',substr($class_name,strlen(rtrim($prefix,'\\')))) . '.php')){
          $this->_autoloadCache[$class_name] = $filename;
          $this->saveSharedCache();
          return require($filename);
        }
      }
      if(!$prefix_match && ($files = $this->_autoloadFiles)){
        $this->_autoloadFiles = false;
        foreach($files as $filename) require($filename);
      }
      else{
        $this->_autoloadMissing[] = $class_name;
        $this->saveSharedCache();
      }
    }
  }
  /**
   * End the request.
   * @param int|string $status  Value to pass to the exit() function.
   */
  public function halt($status = null){
    if($this->event->trigger(self::EVENT_HALT,$this,$status) !== false) exit($status);
  }
  /**
   * Separate objects.
   * @param mixed $item  Item to check on (recursive for arrays).
   * @param array $objects  Array to store objects in. Item will be replaced with name of key.
   * @param int $level  Current nesting level (stops at 10).
   */
  protected function stripObjects(&$item,&$objects,$level = 0){
    if(is_object($item)) try{
      if($item instanceof \Closure){
        $reflect = new \ReflectionFunction($item);
        $filename = $reflect->getFileName();
        $line_no = $reflect->getStartLine();
        $item =
          "<closure file='$filename' line='$line_no'>\n" .
          implode(array_slice(file($filename),$line_no - 1,$reflect->getEndLine() - $line_no + 1)) .
          '</closure>';
      }
      else{
        if(!$this->stripObjectsMemoryLimit) $this->stripObjectsMemoryLimit = \Rsi::memoryLimit() / 5;
        if(memory_get_usage() > $this->stripObjectsMemoryLimit) $item = 'out of memory';
        $objects[$key = '@@object_' . md5(print_r($item,true)) . '@@'] = $item;
        $item = $key;
      }
    }
    catch(\Exception $e){
      $item = '@@' . $e->getMessage() . '@@';
    }
    elseif(is_array($item) && ($level < $this->stripObjectsMaxDepth)) foreach($item as &$sub) $this->stripObjects($sub,$objects,$level + 1);
    unset($sub);
  }
  /**
   * Separate objects from a trace.
   * @param array $trace
   * @param array $objects  Array to store objects in. Item will be replaced with name of key.
   */
  protected function stripTraceObjects(&$trace,&$objects){
    foreach($trace as &$step){
      if(array_key_exists('object',$step)) $this->stripObjects($step['object'],$objects);
      if(array_key_exists('args',$step) && $step['args']) $this->stripObjects($step['args'],$objects);
      else unset($step['args']);
    }
    unset($step);
  }
  /**
   * Handle an (deliberately caused) external error.
   */
  public function externalError($message,$context = null){
    if($this->debug){
      print($message . "\n\n");
      if(!\Rsi::commandLine()){
        $trace = debug_backtrace();
        $objects = [];
        $this->stripTraceObjects($trace,$objects);
        print_r($context);
        print_r($trace);
        print_r($objects);
      }
      $this->halt('External error');
    }
    $this->log->notice('External error: ' . $message,$context);
    if($this->event->trigger(self::EVENT_EXTERNAL_ERROR,$this,$message) !== false){
      http_response_code(400); //Bad Request
      $_SESSION = [];
      $this->halt();
    }
  }
  /**
   * Handle an internal error.
   * @param string $message  Error message.
   * @param string $filename  File in which the error occured.
   * @param int $line_no  Line at which the error occured.
   * @param array $trace  Backtrace of the moment the error occured.
   */
  public function internalError($message,$filename = null,$line_no = null,$trace = null){
    try{
      if(ob_get_length()) ob_clean();
      $objects = [];
      if($this->debug && (strpos($message,'Undefined variable: ') === 0)){
        $this->_internalError = true;
        $trace = false;
      }
      else{
        if(!$trace) $trace = debug_backtrace();
        $this->log->error($message,$filename,$line_no);
        $this->stripTraceObjects($trace,$objects);
      }
      if($this->_internalError){
        if($this->debug){
          if(\Rsi::commandLine()){
            print("$message ($filename:$line_no)\n");
            print_r($trace);
          }
          else{
            print("<code>$message ($filename:$line_no)<code><br><br>");
            $dump = $this->dump();
            print($dump->head() . $dump->source($filename,$line_no));
            if($trace) print($dump->var('trace',$trace));
            if($objects) print($dump->var('objects',$objects));
          }
        }
        exit('Internal error');
      }
      $this->_internalError = true;

      if(!$this->debug) try{
        $this->log->emergency($message,array_filter([
          'filename' => $filename,
          'lineNo' => $line_no,
          'trace' => $trace,
          'objects' => $objects,
          'headers' => function_exists('getallheaders') ? getallheaders() : null,
          'args' => $_SERVER['argv'] ?? null,
          'GET' => $_GET,
          'POST' => $_POST,
          'COOKIE' => $_COOKIE,
          'SESSION' => isset($_SESSION) ? $_SESSION : null
        ]));
        usleep(rand(0,10000000));
        http_response_code(500);
        if(is_file($template = $this->templatePath . 'error.php')) require($template);
      }
      catch(\Exception $e){
        print('An unexpected error has occurred');
      }
      elseif(!\Rsi::commandLine() && is_file($template = $this->templatePath . 'debug.php')) require($template);
      else print($message . ($filename ? " ($filename" . ($line_no ? "@$line_no" : null) . ")" : null) . "\n\n");
      $this->halt();
    }
    catch(\Exception $e){ //the default exception handler is not called again on an unhandled exception
      $this->internalError($e->getMessage(),$e->getFile(),$e->getLine(),$e->getTrace());
    }
  }

  protected function errorHash($message,$filename,$line_no){
    return md5("errorHash($message,$filename,$line_no)");
  }
  /**
   * Error handler.
   * Throws an exception to get a unified error handling. Errors that are suppressed are only logged.
   */
  public function errorHandler($error_no,$message,$filename,$line_no){
    if(error_reporting()){
      $this->_errorHash = $this->errorHash($message,$filename,$line_no);
      $this->_errorBacktrace = debug_backtrace();
      throw new \ErrorException($message,$error_no,0,$filename,$line_no);
    }
    elseif($this->_initialized) $this->log->info($message,$filename,$line_no);
  }
  /**
   * Exception handler.
   * @param Exception $exception
   */
  public function exceptionHandler($exception){
    $message = $exception->getMessage();
    $filename = $exception->getFile();
    $line_no = $exception->getLine();
    if(!($exception instanceof \ErrorException) || ($this->errorHash($message,$filename,$line_no) != $this->_errorHash)) $this->_errorBacktrace = null;
    $this->internalError($message,$filename,$line_no,$this->_errorBacktrace ?: $exception->getTrace());
  }
  /**
   * Shutdown function.
   * If a (non catched) error is the reason for the shutdown (e.g. a timeout), then the shutdown will be processed as an
   * internal error.
   * @see internalError()
   */
  public function shutdownFunction(){
    if(
      $this->_initialized && !$this->_internalError &&
      ($error = error_get_last()) && !preg_match($this->ignoreErrors,$error['message']) &&
      ($this->event->trigger(self::EVENT_SHUTDOWN,$this,$error) !== false)
    ) $this->internalError($error['message'],$error['file'],$error['line']);
  }
  /**
   * Version without hash.
   * @param string $hash  Hash from version string.
   * @return string  Version number.
   */
  public function version(&$hash = null){
    list($version,$hash) = explode('-',$this->version . '-',2);
    return $version;
  }
  /**
   * Add new release notes to messages and log.
   */
  protected function releaseNotes(){
    if(
      $this->_releaseNotesFile &&
      ($time = File::mtime($this->_releaseNotesFile)) &&
      ($time != Record::get($_SESSION,$this->_releaseNotesKey)) &&
      preg_match_all('/\\n- ([\\d\\.]+): (.*)/',file_get_contents($this->_releaseNotesFile),$matches,PREG_SET_ORDER)
    ){
      $messages = [];
      foreach($matches as $match){
        $version = $match[1] . '-' . str_replace(' ','-',strtolower(\Rsi\Str::codeName(crc32($match[2]))));
        if($this->version == $version) $messages = [];
        else $messages[] = "FRED™ version $version: " . str_replace('\\\\','\\',$match[2]);
      }
      if($messages){
        foreach($messages as $message){
          $this->message->warning($message);
          $this->log->warning($message,__FILE__,__LINE__);
        }
        $this->log->notice("Upgraded to FRED™ version $version.",__FILE__,__LINE__);
      }
      else $_SESSION[$this->_releaseNotesKey] = $time;
    }
  }
  /**
   * Check for maintenance.
   */
  protected function maintenance(){
    if($this->_maintenanceTime){
      if(($delta = (strtotime($this->_maintenanceTime)) - $this->_startTime) <= 0){
        if(is_file($template = $this->templatePath . 'maintenance.php')) require($template);
        http_response_code(503); //Service Unavailable
        $_SESSION = [];
        $this->halt();
      }
      else foreach($this->_maintenanceMessage as $limit => $message){
        list($limit,$type) = explode(':',$limit . ':warning');
        if($delta <= $limit){
          if($limit != \Rsi\Record::get($_SESSION,$this->_maintenanceKey)){
            $this->message->add($type,$message,['time' => $this->_maintenanceTime,'delta' => round($delta / 60)] + compact('limit','type'));
            $_SESSION[$this->_maintenanceKey] = $limit;
          }
          break;
        }
      }
    }
  }
  /**
   * Replace config keys with variables.
   * @param mixed $config  For arrays, values with keys starting with a '@' the value is replaced by the variable with that
   *   name (and the '@' is removed from the key).
   * @return mixed
   */
  public function replaceVars($config){
    if(!is_array($config)) return $config;
    $result = [];
    foreach($config as $key => $value) if(substr($key,0,1) == '@')
      $result[substr($key,1)] = (substr($value,0,1) == '{') && (substr($value,-1) == '}')
        ? json_decode($this->vars->value(substr($value,1,-1)),true)
        : $this->vars->value($value);
    else $result[$key] = $this->replaceVars($value);
    return $result;
  }
  /**
   * Get a dumper.
   * @return \\Rsi\\Dump
   */
  public function dump(){
    $config = $this->config('dump');
    $class_name = $config['className'] ?? 'Rsi\\Dump';
    return new $class_name($config);
  }
  /**
   * Get a value from the configuration.
   * @param string|array $key  Key to get the value from the configuration (array = nested).
   * @param mixed $default  Default value if the key does not exist.
   * @return mixed  Found value, or default value if the key does not exist.
   */
  public function config($key,$default = null){
    return $this->replaceVars(Record::get($this->_config,$key,$default));
  }

  protected function defaultComponentClassName($name){
    return $this->defaultComponentNamespace . '\\' . ucfirst($name);
  }
  /**
   * Get a component.
   * @param string $name  Name of the component.
   * @return Fred\\Component
   */
  public function component($name){
    if(!$this->has($name)){
      $config = $this->config($name);
      if($config && !is_array($config)){
        if(is_callable($config)) $config = call_user_func($config,$name);
        if(is_string($config)) $config = require($config);
      }
      if(!class_exists($class_name = Record::get($config,'className') ?: $this->defaultComponentClassName($name)))
        throw new \Exception("Unknown component '$name' ($class_name)");
      $this->_components[$name] = new $class_name($this,array_merge(['name' => $name],$config ?: []));
    }
    return $this->_components[$name];
  }
  /**
   * Get a component if there is a configuration entry for it.
   * @param string $name  Name of the component.
   * @return Fred\\Component  False if there is no configuration.
   */
  public function may($name){
    return array_key_exists($name,$this->_components) || array_key_exists($name,$this->_config) || class_exists($this->defaultComponentClassName($name))
      ? $this->component($name)
      : false;
  }
  /**
   * Get a component if it already exists.
   * @param string $name  Name of the component.
   * @return Fred\\Component  False if it did not exist.
   */
  public function has($name){
    return $this->_components[$name] ?? false;
  }
  /**
   * Public configuration.
   * @return array  Public configuration for all components (key = component name, value = public component configuration).
   */
  public function clientConfig(){
    $config = [];
    if($this->debug) $config['debug'] = true;
    foreach($this->_components as $name => $component) $config[$name] = $component->clientConfig();
    return array_filter($config);
  }

  protected function setAutoloadNamespaces($namespaces){
    $this->_autoloadNamespaces = array_merge($this->_autoloadNamespaces,$namespaces);
  }

  protected function setAutoloadClasses($classes){
    $this->_autoloadClasses = array_merge($this->_autoloadClasses,$classes);
  }

  protected function setAutoloadFiles($classes){
    $this->_autoloadFiles = array_merge($this->_autoloadFiles,$classes);
  }

  protected function setTimeLimit($value){
    set_time_limit($value);
    $this->_timeLimit = microtime(true) + $value;
  }

  protected function getTimeLimit(){
    if($this->_timeLimit === null) $this->_timeLimit = $this->_startTime + ini_get('max_execution_time');
    return max(0,$this->_timeLimit - microtime(true));
  }

  protected function _get($key){
    return $this->component($key);
  }

  public function __call($func_name,$params){
    return call_user_func_array([$this->entity,'item'],array_merge([$func_name],$params));
  }

}