Trans.php

Go to the documentation of this file.

<?php

namespace Rsi\Fred;

/**
 *  Translations component.
 */
class Trans extends Component{

  const TYPE_TAG = '+'; //!< Add a tag to to the tags: [+tag|value].
  const TYPE_OPTIONAL = '?'; //!< Optional sub-string (defaults to empty; no error): [?strId].
  const TYPE_SUBSTR = '@'; //!< Points to a sub-string: [\@strId].
  const TYPE_TRUE = '%'; //!< Show section when tag value is true: {[%tag]show when tag is not empty}.
  const TYPE_FALSE = '!'; //!< Show section when tag value is false: {[!tag]show when tag is empty}.
  const TYPE_COUNT = '#'; //!< Insert number of items in array: Array has [\#arrayTag] items.
  const TYPE_SUM = '='; //!< Sum of an array column: [=array|column|formatting].
  const TYPE_ARRAY = '*'; //!< Repeat section for each item (item aded to tags, including k = key, v = value - when record is
    // not an array, i = index, r = reverse index): Values: [*arrayTag|{\\[i\\], }\\[v\\]].
  const TYPE_DECODE = ':'; //!< Decode a value: [:intTag|1:foo|2:bar|default]. Set the value to '?' for a random selection.
  const TYPE_JSON = '$'; //!< Insert a JSON encoded value.
  const TYPE_RAW = '~'; //!< Insert value without inserting a conditional tag: [[~intTag],number].

  const MACRO_ESCAPE = 'escape'; //!< Escape the text between these tags (pre processing).
  const MACRO_SPACE = 'space'; //!< Remove white-space between tags.
  const MACRO_REPLACE = 'replace'; //!< Replace the text in attribute 'from' (regex) to 'to'.
  const MACRO_UNITS = 'units'; //!< Split the value of the tag name into units, so it can be used as an array (units in desired
    // order in the 'units' tag - e.g. 'km=1000,m=1,cm=0.01'; use the 'tolerance' tag to set a cut-off percentage; set the 'tag'
    // attribute to choose a custom result tag - defaults to current tag + 'Units'; add an 'empty' attribute to include units
    // without values, if there is a higher unit with a value; pre processing).
  const MACRO_CONST = 'const'; //!< Replace the text with the value of the constant between the tags (pre processing).
  const MACRO_CACHE = 'cache'; //!< Cache the (processed) text (set the 'ttl' tag to use the main cache; use the 'key'
    // attribute to define a custom cache key, otherwise one is generated; the key can contain tags).
  const MACRO_FRAGMENT = 'fragment'; //!< Replace the tag with a placeholder and replace it with the fragment later on (with
    // 'delay' attribute) or on demand (set the 'id' attribute).
  const MACRO_ROUTE = 'route'; //!< Create a (reverse) route for the controller name between the tags (attributes are params).
  const MACRO_LOCATION = 'location'; //!< Rewrite the location between the tags (pre processing).
  const MACRO_IMAGE = 'image'; //!< Generate an image tag for the image between the tags (the content is cached, set the 'ttl'
    // attribute to deviate from the default $imageTtl).
  const MACRO_URL = 'url'; //!< Load external content from the address between the tags (the content is cached, set the 'ttl'
    // attribute to deviate from the default $urlTtl; pre processing)).
  const MACRO_RIGHT = 'right'; //<!  Only include the text when the user is authorized for the 'right' attribute (set an
    // optional 'level'; add a 'not' attribute for the other way round; pre processing).

  const EVENT_FORMAT = 'trans:format:';

  public $namespace = 'trans';
  public $maxNested = 10; //!< Maximum number of times a sub-string may be nested.
  public $logPrio = Log::INFO; //!< Prio for translation related errors (invalid tags, format, etc).
  public $imageTtl = 86400; //!< Default cache TTL for image tag generation.
  public $imageKeyPrefix = 'trans-image-';
  public $urlTtl = 86400; //!< Default cache TTL for external content.
  public $urlKeyPrefix = 'trans-url-';
  public $cacheKeyPrefix = 'trans-cache-';

  protected $_langId = null;
  protected $_filename = null; //!< Filename for the translations (asterisk will be replace by the langId).
  protected $_prefix = null;
  protected $_strs = [];
  protected $_tags = []; //!< Default tags to use with every translation.

  protected $_escape = [];
  protected $_unescape = [];
  protected $_cache = [];

  protected $_types = null;
  protected $_regex = null;

  protected function init(){
    parent::init();
    if(!$this->_prefix) $this->_prefix = \Rsi\Str::random();
    foreach(['{','[',']','}'] as $char) $this->_unescape[$this->_escape['\\' . $char] = $this->_prefix . bin2hex($char)] = $char;
    $this->publish(['langId'],self::READWRITE);
  }
  /**
   * Available languages.
   * @return array  Key = ID, value = description.
   */
  public function langs(){
    return [$this->langId => null];
  }

  protected function error($message,$file = null,$line_no = null,$context = null){
    $this->component('log')->add($this->logPrio,$message,$file,$line_no,$context);
    return 'error';
  }
  /**
   * Get all strings.
   * @param string $lang_id  Language ID.
   * @return array  Key = string ID, value = string.
   */
  protected function getStrs($lang_id){
    return array_change_key_case(require(str_replace('*',$lang_id,$this->_filename)));
  }
  /**
   * Basic string getter.
   * @param string $id  String ID.
   * @param string $default  Default string when ID is not found.
   * @return string
   */
  public function getStr($id,$default = false){
    $id = explode('.',$id);
    $lang_id = count($id) > 1 ? $id[1] : $this->langId;
    if(!array_key_exists($lang_id,$this->_strs)) $this->_strs[$lang_id] = array_change_key_case($this->getStrs($lang_id));
    return array_key_exists($id = strtolower($id[0]),$this->_strs[$lang_id]) ? $this->_strs[$lang_id][$id] : $default;
  }

  protected function macro($str,$type,&$tags,$callback){
    if(
      strpos($str,'<' . ($tag = $this->namespace . ':' . $type)) &&
      preg_match_all("/<$tag(?<attribs>(" . \Rsi\Str::ATTRIBUTES_PATTERN . ")*)>(?<str>.*?)<\\/$tag>/s",$str,$matches,PREG_SET_ORDER)
    ) foreach($matches as $match) try{
      $str = str_replace($match[0],call_user_func_array($callback,[$match['str'],\Rsi\Str::attributes($match['attribs']),&$tags]),$str);
    }
    catch(\Exception $e){
      return $this->error($e,['macro' => $type]);
    }
    return $str;
  }

  protected function preProcess($str,&$tags){
    $str = strtr($this->macro($str,self::MACRO_ESCAPE,$tags,function($str){
      return strtr($str,array_flip($this->_unescape));
    }),$this->_escape);
    $str = $this->macro($str,self::MACRO_CACHE,$tags,function($str,$attribs,&$tags){
      if(!($key = $attribs['key'] ?? null)) $key = md5($str);
      elseif(preg_match_all('/\\[([\\w\\-]+)\\]/',$key,$matches,PREG_SET_ORDER)) foreach($matches as list($full,$tag)){
        if(is_array($value = $this->value($tag,null,$tags))) $value = md5(serialize($value));
        $key = str_replace($full,$value,$key);
      }
      $key .= '-' . $this->langId;
      $ttl = $attribs['ttl'] ?? 0;
      if(!array_key_exists($key,$this->_cache)) $this->_cache[$key] = $ttl ? $this->component('cache')->fetch($this->cacheKeyPrefix . $key) : false;
      $exists = $this->_cache[$key] !== false;
      $tag = $this->namespace . ':' . self::MACRO_CACHE;
      return "<$tag key='$key'" . ($exists ? '' : " ttl='$ttl'") . '>' . ($exists ? null : $str) . "</$tag>";
    });
    $str = $this->macro($str,self::MACRO_CONST,$tags,function($name){
      return constant($name);
    });
    $str = $this->macro($str,self::MACRO_UNITS,$tags,function($tag,$attribs,&$tags){
      $result = [];
      foreach(\Rsi\Number::units($value = $tags[$tag] ?? 0,\Rsi\Record::explode($attribs['units'] ?? null,',','='),$value * ($attribs['tolerance'] ?? 0) / 100) as $unit => $count)
        if($count || array_key_exists('empty',$attribs)) $result[] = compact('unit','count');
      $tags[$attribs['tag'] ?? $tag . 'Units'] = $result;
      return null;
    });
    $str = $this->macro($str,self::MACRO_LOCATION,$tags,function($str){
      return htmlspecialchars($this->component('location')->rewrite($str));
    });
    $str = $this->macro($str,self::MACRO_URL,$tags,function($url,$attribs){
      return $this->component('cache')->fetch($this->urlKeyPrefix . $url,$attribs['ttl'] ?? $this->urlTtl,function() use ($url){
        $this->component('log')->debug("Loading external content from '$url'",__FILE__,__LINE__);
        return preg_match('/^https?:\\/\\/(?!localhost|127\\.0\\.0\\.|\\[[0:]+1\\])/i',$url) ? file_get_contents($url) : $url;
      });
    });
    $str = $this->macro($str,self::MACRO_RIGHT,$tags,function($str,$attribs){
      return ($this->component('user')->authorized($attribs['right'] ?? null,$attribs['level'] ?? null) xor ($attribs['not'] ?? false)) ? $str : null;
    });
    return $str;
  }

  protected function postProcess($str,&$tags){
    if($str){
      $str = $this->macro($str,self::MACRO_CACHE,$tags,function($str,$attribs){
        $key = $attribs['key'];
        if(($ttl = $attribs['ttl'] ?? false) === false) return $this->_cache[$key];
        if($ttl) $this->component('cache')->save($this->cacheKeyPrefix . $key,$str,$ttl);
        return $this->_cache[$key] = $str;
      });
      $str = $this->macro($str,self::MACRO_FRAGMENT,$tags,function($str,$attribs){
        $fragments = $this->session->fragments ?: [];
        $fragments[$id = $attribs['id'] ?? 'fragment-' . \Rsi\Str::random()] = $str;
        $this->session->fragments = $fragments;
        return ($delay = $attribs['delay'] ?? null)
          ? "<div class='fred-fragment' id='$id'><script>document.addEventListener('DOMContentLoaded',function(){" .
              "setTimeout(function(){ fred.controller.fragment('#$id','$id') },$delay * 1000)" .
            "},true)</script></div>"
          : null;
      });
      $str = $this->macro($str,self::MACRO_ROUTE,$tags,function($controller_name,$params){
        $controller_name = explode('.',$controller_name);
        if(array_key_exists('_',$params)){
          foreach(($params['_'] == '*' ? array_keys($_GET) : explode(',',$params['_'])) as $key)
            if(!array_key_exists($key,$params) && ($value = $this->component('request')->complex($key))) $params[$key] = $value;
          unset($params['_']);
        }
        return htmlspecialchars($this->component('router')->reverse($controller_name[0],$controller_name[1] ?? null,$params));
      });
      $str = $this->macro($str,self::MACRO_SPACE,$tags,function($str){
        return trim(preg_replace('/\\s*\\n\\s*/',"\n",preg_replace('/>\\s+</','><',$str)));
      });
      $str = $this->macro($str,self::MACRO_REPLACE,$tags,function($str,$attribs){
        if(!array_key_exists('from',$attribs)) return $str;
        if(substr($from = $attribs['from'],0,1) != '/') $from = '/' . preg_quote($from,'/') . '/';
        return preg_replace($from,$attribs['to'] ?? null,$str);
      });
      $str = $this->macro($str,self::MACRO_IMAGE,$tags,function($url,$attribs){
        return $this->component('cache')->fetch($this->imageKeyPrefix . $url . '?' . http_build_query($attribs),$attribs['ttl'] ?? $this->imageTtl,function() use ($url,$attribs){
          unset($attribs['ttl']);
          foreach(['width','height','background'] as $key) if(array_key_exists($key,$attribs) && ($attribs[$key] == 'auto')) $attribs[$key] = true;
          return $this->component('html')->img($url,$attribs);
        });
      });
    }
    return $str;
  }
  /**
   * Escape tag values (convert special characters to HTML entities).
   * @param array $tags  Tags with raw values (keys starting with '!' or not escaped - '!' is removed from key).
   * @return array  Escaped tags
   */
  public function escape($tags){
    $escaped = [];
    if($tags) foreach($tags as $tag => $value){
      switch(substr($tag,0,1)){
        case '!': $tag = substr($tag,1); //raw
        case '@': break; //callback
        default: if(!is_object($value)) $value = is_array($value) ? $this->escape($value) : htmlspecialchars($value);
      }
      $escaped[$tag] = $value;
    }
    return $escaped;
  }

  protected function value($tag,$params,&$tags){
    if(\Rsi\Str::numeric($tag)) return $tag;
    $value = $tags;
    $found = true;
    foreach(explode('.',$tag) as $key){
      if(is_object(($value))) try{
        $value = $this->escape([$value->$key])[0];
      }
      catch(\Exception $e){
        $this->error("Property '$key' does not exists for tag '$tag'",__FILE__,__LINE__,compact('value'));
        $found = false;
        break;
      }
      elseif(!array_key_exists($key,$value)){
        $found = false;
        break;
      }
      else $value = $value[$key];
    }
    if($found) try{
       return is_object($value) ? strval($value) : $value;
    }
    catch(\Exception $e){
      $this->error("Could not convert object for tag '$tag' to string",__FILE__,__LINE__,compact('value'));
    }
    foreach($tags as $key => $value) if((substr($key,0,1) == '@') && !strcasecmp($tag,trim($key,'@!'))){
      $value = [$tag => call_user_func($value,$tag,$tags,$params)];
      $tags += substr($key,1,1) == '!' ? $value : $this->escape($value);
      return $tags[$tag];
    }
    return $tags[$tag] = null;
  }

  protected function evaluate($expr,$tag,&$tags){
    $expr = strtr($expr,[$this->_prefix . true => '','?' => is_array($tag) ? implode(',',$tag) : $tag]);
    foreach($tags as $key => $value) if(preg_match($mask = '/\\b' . preg_quote($tag = trim($key,'@!'),'/') . '\\b/',$expr)){
      if(is_array($value = $this->value($tag,null,$tags))) $value = implode(',',$value);
      elseif(preg_match('/^\\d{4}-\\d{2}-\\d{2}/',$value)) $value = "'$value'";
      $expr = preg_replace($mask,$value,$expr);
    }
    return \Rsi\Number::evaluate($expr);
  }

  protected function formatSubstr($value,$start,$length = null){
    return $length === null ? substr($value,$start) : substr($value,$start,$length);
  }

  protected function formatReplace($value,$search,$replace){
    return str_replace($search,$replace,$value);
  }

  protected function formatRegex($value,$pattern,$replace){
    return preg_replace($pattern,$replace,$value);
  }
  /**
   * Format a value.
   * @param string $tag  Tag name.
   * @param mixed $value  Tag value.
   * @param string $params  Formatting params.
   * @param array $tags  Other tags.
   * @return string  Formatted value.
   */
  protected function format($tag,$value,$params,&$tags){
    foreach(explode('|',$params) as $format) if($format) try{
      if(substr($format,0,1) == '=') $value = $this->evaluate(substr($format,1),$tag,$tags);
      elseif(preg_match('/(\w+)\\((.*)\\)$/',$format,$match)){
        $func_name = 'format' . ucfirst($match[1]);
        $params = array_merge([$value],$match[2] ? array_map('urldecode',explode(',',$match[2])) : []);
        if(method_exists($component = $this,$func_name) || method_exists($component = $this->component('local'),$func_name))
          $value = call_user_func_array([$component,$func_name],$params);
        else $value = call_user_func_array(
          [$this->component('event'),'trigger'],
          array_merge([self::EVENT_FORMAT . $match[1],$this],$params)
        );
      }
      else{
        $value = \Rsi\Str::transform($value,$format,$count);
        if(!$count) $value = date($format,strtotime($value));
      }
    }
    catch(\Exception $e){
      $value = $this->error($e,compact('tag','value','params'));
      break;
    }
    return is_array($value) ? false : $value;
  }
  /**
   * Replace a tag with its value.
   * @param string $str  String to replace tag in.
   * @param string $full  Full match for the tag (including brackets).
   * @param string $type  Type of tag (see TYPE_* constants).
   * @param string $tag  Name of the tag.
   * @param string $operator  Operator for the tag (e.g. '==').
   * @param string $params  Extra parameters in the tag.
   * @param mixed $value  Value for the tag.
   * @param array $tags  All available tags (values).
   * @param array $strs  Loaded sub-strings.
   * @return string  Original input string with the full tag replaced with its value.
   */
  protected function replace($str,$full,$type,$tag,$operator,$params,$value,&$tags,&$strs){
    $default = $replace = $raw = false;
    if($type) switch($type){
      case self::TYPE_TAG:
        $tags[$tag] = substr($params,1);
        $raw = true;
        break;
      case self::TYPE_OPTIONAL:
        $default = null; //fall through
      case self::TYPE_SUBSTR:
        if(!in_array($tag,$strs)) $strs[] = $tag;
        $replace = \Rsi\Str::transform($this->preProcess($this->getStr($tag,$default),$tags),$params = explode('|',$params));
        $raw = !in_array(self::MACRO_ESCAPE,$params);
        break;
      case self::TYPE_TRUE:
        if(substr($params,0,2) == '|=') $value = $this->evaluate(substr($params,2),$tag,$tags);
        if($value) $replace = $this->_prefix . true;
        $raw = true;
        break;
      case self::TYPE_FALSE:
        if(substr($params,0,2) == '|=') $value = $this->evaluate(substr($params,2),$tag,$tags);
        if(!$value) $replace = $this->_prefix . true;
        $raw = true;
        break;
      case self::TYPE_COUNT:
        $replace = count($value);
        $raw = true;
        break;
      case self::TYPE_SUM:
        if(is_array($value)){
          $params = explode('|',substr($params,1),2);
          $replace = $this->format($tag,array_sum(\Rsi\Record::column($value,$params[0])),$params[1] ?? null,$tags) . $this->_prefix . true;
        }
        break;
      case self::TYPE_ARRAY:
        if($value && (is_array($value) || (is_numeric($value) && ($value > 0) && ($value = range(1,$value))))){
          $replace = $this->_prefix . true;
          $sub = strtr(substr($params,1),$this->_unescape);
          $i = 0; //index
          $r = count($value); //reverse
          foreach($value as $key => $record) $replace .=
            $this->trans($sub,(is_array($record) ? $record : []) + ['v' => $record,'k' => $key,'i' => $i++,'r' => --$r] + $tags);
        }
        break;
      case self::TYPE_DECODE:
        $options = explode('|',substr($params,1));
        $random = $value == '?' ? rand(0,count($options) - 1) : false;
        foreach($options as $index => $option){
          $i = strpos($option,':');
          if($i === false) $replace = $option; //default
          elseif($random === false ? substr($option,0,$i) == $value : $index == $random){
            $replace = substr($option,$i + 1);
            break;
          }
          if(!\Rsi::nothing($replace)) $replace .= $this->_prefix . true;
        }
        $replace = $this->trans(strtr($replace,$this->_unescape),$tags);
        break;
      case self::TYPE_JSON:
        $replace = json_encode($value);
        break;
      case self::TYPE_RAW:
        $replace = $this->format($tag,$value,$params,$tags);
        break;
    }
    elseif($operator){
      if(\Rsi\Str::operator(strtr(is_array($value) ? count($value) : $value,array_flip($this->_unescape)),$operator,$params)) $replace = $this->_prefix . true;
      $raw = true;
    }
    elseif(!\Rsi::nothing($value)) //standard tag
      $replace = $this->format($tag,$value,$params,$tags) . $this->_prefix . true;
    return str_replace($full,$raw ? $replace : strtr($replace,array_flip($this->_unescape)),$str);
  }
  /**
   * Elaborate conditional parts.
   * @param string $str  String with conditional parts.
   * @return string  String with elaborated conditional parts.
   */
  protected function brush($str){
    while($str && preg_match_all('/{([^{}]*?)}/',$str,$matches,PREG_SET_ORDER)) foreach($matches as list($full,$inner))
      $str = str_replace($full,strpos($full,$this->_prefix . true) ? str_replace($this->_prefix . true,'',$inner) : '',$str);
    return $str;
  }
  /**
   * Translate a string.
   * @param string $str  Basic string with tags.
   * @param array $tags  Tags to use when translating the string. Values are automaticle escaped, except when the key starts
   *   with a '!'. For keys starting with a '@' the value is used as a callback function (only called when the tag is present
   *   in the string; use '@!' prefix for callback values that should not be escaped).
   * @return string  Translated string.
   */
  protected function trans($str,$tags = null){
    if(!$str) return $str;
    $tags = array_merge($this->_tags,$tags ?: []);
    $count = $strs = [];
    if(($str = $this->preProcess($str,$tags)) && $tags) foreach($tags as $key => $value)
      if(is_scalar($value)) $str = str_replace("[$key]",\Rsi::nothing($value) ? false : strtr($value,array_flip($this->_unescape)) . $this->_prefix . true,$str);
    while($str && preg_match_all($this->regex,$str,$matches,PREG_SET_ORDER)){
      foreach($strs as $id){
        if(!array_key_exists($id,$count)) $count[$id] = 0;
        elseif(++$count[$id] >= $this->maxNested){
          $this->error("Sub-string '$id' nested more than {$this->maxNested} times",__FILE__,__LINE__,compact('str','tags'));
          break 2;
        }
      }
      $strs = $done = [];
      foreach($matches as $match){
        list($full,$type,$tag,$operator,$params) = $match;
        if(!in_array($full,$done)){
          if(substr($type,0,1) == '{') $type = $this->types[substr($type,1,-1)] ?? null;
          $value = in_array($type,[self::TYPE_TAG,self::TYPE_OPTIONAL,self::TYPE_SUBSTR]) ? null : $this->value($tag,$params,$tags);
          $str = $this->replace($str,$full,$type,$tag,$operator,$params,$value,$tags,$strs);
          $done[] = $full;
        }
      }
    }
    return $this->postProcess(str_replace($this->_prefix . true,'',strtr($this->brush($str),$this->_unescape)),$tags);
  }
  /**
   * Translate a string.
   * @param string $str  Basic string with tags.
   * @param array $tags  Tags to use when translating the string.
   * @return string  Translated string.
   */
  public function str($str,$tags = null){
    return $this->trans($str,$this->escape($tags));
  }
  /**
   * Translate a string by ID.
   * @param string $id  String ID.
   * @param array $tags  Tags to use when translating the string.
   * @param string $default  Default string when ID is not found.
   * @return string  Translated string.
   */
  public function id($id,$tags = null,$default = false){
    return $this->str($this->getStr($id,$default),$tags);
  }

  public function fragment($id){
    $fragments = $this->session->fragments ?: [];
    $fragment = $fragments[$id] ?? false;
    unset($fragments[$id]);
    $this->session->fragments = $fragments;
    return $fragment;
  }

  protected function getRegex(){
    if(!$this->_regex){
      $this->_regex = '/\\[(';
      foreach($this->types as $type) $this->_regex .= preg_quote($type,'/') . '|';
      $this->_regex .=
        '\\{\\w+\\})?' . //type
        '(\\w[\\w\\-\\/\\.]*\\w|\\w+)' . //tag
        '(==|!=|>=?|<=?|%|=%|-?\\*-?|\\/\\/)?' . //operator
        '([^\\[\\]]*)' . //params
        '\\]/';
    }
    return $this->_regex;
  }

  protected function setTags($value){
    $this->_tags = $value === false ? [] : array_merge($this->_tags,$value);
  }

  protected function getTypes(){
    if(!$this->_types){
      $this->_types = [];
      foreach($this->constants('TYPE_') as $name => $value) $this->_types[strtolower($name)] = $value;
    }
    return $this->_types;
  }

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

  public function __call($func_name,$params){
    return $this->id($func_name,array_shift($params),array_shift($params));
  }

  public function __invoke($str,$tags = null){
    return $this->str($str,$tags);
  }

}