CreateMenu.php

<?php
/**
 * CreateMenu class
 * @copyright HomeCu 05/2019
 *
 * An abstract class to extend and create menus from any JSON file (possibly other formats,
 * such as HTML templates, in future versions.)
 *
 * Usage: See Documentation at the bottom of this file.
 */

abstract class CreateMenu
{
  /** @var array the array passed around system */
  protected $HB_ENV = [];

  /** @var array store params for substitution array here. */
  protected $params = [];

  /** @var array array decoded from JSON */
  protected $menu_array = [];

  /** @var string the return HTML (or error) string.  */
  protected $menu_html = '';

  /** @var array If any errors, store them in this array. */
  protected $errors = [];

  /**
   * CreateMenu constructor
   * @return void
   */
  public function __construct($HB_ENV = [])
  {
    if (count($HB_ENV) == 0) {
      return;
    }

    $this->HB_ENV = $HB_ENV;
  }

  /**
   * If we have no CU and user, no need to output anything.
   * @return bool
   */
  public function isCuAndUser()
  {
    return (
      isset($this->HB_ENV['Cu']) &&
      (strlen($this->HB_ENV['Cu']) > 0) &&
      isset($this->HB_ENV['Uid']) &&
      (strlen($this->HB_ENV['Uid']) > 0)
    );
  }

  /**
   * Main entry point, convert the JSON array to a menu, substituting any values
   * required and return final HTML.
   * @param array $params
   * @return string
   */
  public function makeMenu($params = [])
  {
    return $this
      ->setMenuArray($params)
      ->setMenuParams($params)
      ->makeMenuHtml()
      ->returnMenuHtml();
  }

  /**
   * Using the same methods above, return the content of a single node in the
   * array. Digs recursively into the array until it finds $node_id and
   * depending on the wrapper flag, returns the full node or its
   * content only.
   * @param string $node_id
   * @param array $params
   * @param bool $full_node - give us the element as is in the array false = just its content
   * @return string
   */
  public function makeSingleMenuNode($node_id = '', $params = [], $full_node = false)
  {
    $this
      ->setMenuArray($params)
      ->setMenuParams($params);

    $node = $this->findNode($node_id);
    if (count($node) > 0) {
      return ($full_node)?
        $this->createElementHtml($node, true) :
        $this->addElementContent($node_id, $node);
    }

    return '';
  }

  /**
   * Helper for makeSingleMenuNode(), find the node in the array identified by $node_id.
   * @param string $node_id
   * @return array
   */
  protected function findNode($node_id)
  {
    if (! (isset($this->menu_array['items']) && is_array($this->menu_array['items']))) {
      return [];
    }

    foreach ($this->menu_array['items'] as $item) {

      $arr = $this->recursivelyWalkArray($node_id, $item);
      if (count($arr) > 0) {
        return $arr;
      }
    }
    return [];
  }

  /**
   * Helper for findNode(). Recursively dig into the array and attempt to
   * locate the array identified by $node_id.
   * @param string $node_id
   * @param array $item
   * @return array
   */
  protected function recursivelyWalkArray($node_id, $item)
  {
    if (! is_array($item)) {
      return[];
    }

    // Check top level, if it's there cool, we're done.
    $id = $this->getElementId($item);
    if (($id == $node_id)) {
      return $item;
    }

    // Walk $item array, if a matching ID is found, also done.
    foreach ($item as $key => $value) {

      $id = $this->getElementId($value);
      if (($id == $node_id)) {
        return $value;
      }

      // If we have nothing, recurse this function and walk through sub arrays.
      $element_array = $this->recurseDigArray($node_id, $value);
      if (count($element_array) > 0) {
        return $element_array;
      }
    }

    return [];
  }

  /**
   * Helper for recursivelyWalkArray(), if we have a numerically indexed array,
   * walk it and look for the node identified by $node_id.
   * @param string $node_id
   * @param array $sub_array
   * @return array
   */
  protected function recurseDigArray($node_id, $sub_array)
  {
    if (is_array($sub_array) && ! $this->isAssociativeArray($sub_array)) {

      foreach ($sub_array as $node_array) {

        $element_array = $this->recursivelyWalkArray($node_id, $node_array);
        $id = $this->getElementId($element_array);

        if (($id == $node_id)) {
          return $element_array;
        }
      }
    }

    return [];
  }

  /**
   * Extract the JSON file path and convert to an array. Or try to.
   * @param array $params
   * @return $this
   */
  protected function setMenuArray($params = [])
  {
    $json_path = $this->jsonPathParam($params);

    if (! is_readable($json_path)) {
      $this->errors[] = "File $json_path is not readable.";
      return $this;
    }

    $arr = json_decode(file_get_contents($json_path), 1);
    if (! $this->isValidConfig($arr)) {
      return $this;
    }

    $this->menu_array = $arr;

    return $this;
  }

  /**
   * Get the JSON file path from params.
   * @param $params
   * @return string|null
   */
  protected function jsonPathParam($params)
  {
    if (! (isset($params['json_path']) && ! empty($params['json_path']))) {
      return null;
    }

    return $params['json_path'];
  }

  /**
   * Check that the array decoded from JSON has valid array members.
   * @param array $arr
   * @return bool
   */
  protected function isValidConfig($arr = [])
  {
    if ($arr === false) {
      $this->errors[] = "Could not read the JSON configuration.";
      return false;
    }

    if (! (isset($arr['container']) && is_array($arr['container']))) {
      $this->errors[] = "There is no container element in the configuration.";
    }

    if (! (isset($arr['items']) && is_array($arr['items']))) {
      $this->errors[] = "There is no menu items array in the configuration.";
    }

    return true;
  }

  /**
   * Extract substitution values from input and set them as input params as an internal property.
   * @param array $params
   * @return $this
   */
  protected function setMenuParams($params = [])
  {
    if ($this->isErrors()) {
      return $this;
    }

    if (
      ! isset($params['substitute_values']) &&
      is_array($params['substitute_values'])
    ) {
      return $this;
    }

    foreach ($params['substitute_values'] as $key => $value) {
      $this->params[$key] = $value;
    }

    return $this;
  }

  /**
   * Make the menu and store in $this->menu_html.
   * @return $this
   */
  protected function makeMenuHtml()
  {
    if ($this->isErrors()) {
      return $this;
    }

    // Already checked for these keys.
    $container  = $this->menu_array['container'];
    $items      = $this->menu_array['items'];

    $this->menu_html =
      $this->createMenuToggleElement() .
      $this->createElementHtml($container, false) .
      $this->walkMenuItems($items) .
      $this->closeHtmlElement($container);

    return $this;
  }

  /**
   * Create the "non menu" toggle element if it exists. It is still contained by the
   * parent wrapper but not in the menu element list.
   * @return string|null
   */
  protected function createMenuToggleElement()
  {
    if (!
      isset($this->menu_array['toggle-element']) &&
      is_array($this->menu_array['toggle-element'])
    ) {
      return null;
    }

    return $this->createElementHtml($this->menu_array['toggle-element'], true);
  }

  /**
   * Helper for makeMenuHtml(), walk the menu items and compose the HTML string.
   * @param array $items
   * @return string|null
   */
  protected function walkMenuItems($items = [])
  {
    $html = null;

    foreach ($items as $item) {
      $html .= $this->createElementHtml($item, true);
    }

    return $html;
  }

  /**
   * The meat of the meal, output an HTML element. As we encounter content elements,
   * this method is called recursively, allowing deeply nested elements to output.
   * @param array $arr
   * @param bool $close_tag - container needs to be closed after items done.
   * @return string|null
   */
  protected function createElementHtml($arr = [], $close_tag = true)
  {
    // This check allows raw data in the content member, i.e. "content" : ["nothing but a string"]
     if (isset($arr[0]) && is_string($arr[0])) {
      return $arr . PHP_EOL;
     }

    $id = $this->getElementId($arr);
    if (! $this->hasDisplayValue($id, $arr)) {
      return null;
    }

    $html =
      $this->openHtmlElement($arr) .
      $this->addElementAttributes($id, $arr) .
      $this->addElementClasses($id, $arr) .
      $this->closeElementOpen($arr) .
      $this->addElementContent($id, $arr);

    if ($close_tag) {
      $html .= $this->closeHtmlElement($arr);
    }

    return $html;
  }

  /**
   * Get the ID of an element if it exists.
   * @param array $element
   * @return string|null
   */
  protected function getElementId($element = [])
  {
    if (! isset($element['attributes']['id'])) {
      return null;
    }

    return $element['attributes']['id'];
  }

  /**
   * Helper for recursively walking array, looking for ID.
   * @param array $arr
   * @return bool
   */
  protected function isAssociativeArray($arr = [])
  {
    if (! is_array($arr)) {
      return false;
    }

    return array_keys($arr) !== range(0, count($arr) - 1);
  }

  /**
   * See if an element has an explicitly set display value. Default to true.
   * @param string $id
   * @param array $element
   * @return bool
   */
  protected function hasDisplayValue($id, $element = [])
  {
    if (! isset($element['display'])) {
      return true;
    }

    return $this->hasUserDisplayValue($id, $element['display']);
  }

  /**
   * See if there is a display value set on the member.
   * @param string $id
   * @param bool $display
   * @return bool|mixed
   */
  protected function hasUserDisplayValue($id, $display)
  {
    $key = $id . '.display';
    if (array_key_exists($key, $this->params)) {
      return $this->params[$key];
    }

    return $display === true;
  }

  /**
   * Open a valid HTML element.
   * @param array $element
   * @return string|null
   */
  protected function openHtmlElement($element = [])
  {
    if (! isset($element['html-element'])) {
      return null;
    }

    return
        $this->addIndent($element['html-element']) .
        "<{$element['html-element']}";
  }

  /**
   * Output the closing tag for any opened element. Only outputs for valid tags,
   * allowing raw content members to output.
   * @param array $element
   * @return string|null
   */
  protected function closeHtmlElement($element = [])
  {
    if (! isset($element['html-element'])) {
      return null;
    }

    return
      "</{$element['html-element']}>" .
      $this->addNewLine($element['html-element']);
  }

  /**
   * Add indents after some elements
   * @TODO let's see if we can better format output?
   * @param $tag
   * @return string|null
   */
  protected function addIndent($tag)
  {
    if (in_array($tag, ['p', 'li', 'div'])) {
      return "    ";
    }

    return null;
  }

  /**
   * Add newlines after some elements
   * @TODO let's see if we can better format output?
   * @param $tag
   * @return string|null
   */
  protected function addNewLine($tag)
  {
    if (in_array($tag, ['ul', 'li', 'p', 'div'])) {
      return PHP_EOL;
    }

    return null;
  }

  /**
   * Return the ending carat for an opened HTML tag.
   * @param array $element
   * @return string|null
   */
  protected function closeElementOpen($element = [])
  {
    // This check allows raw data in the content member, i.e. content : ["string without a tag"]
    if (! array_key_exists('html-element', $element)) {
      return null;
    }

    // @TODO hinky
    if (in_array($element['html-element'], ['i', 'em', 'b', 'strong', 'label', 'span'])) {
      return '>';
    }

    return '>' . PHP_EOL;
  }

  /**
   * Walk the attributes array and add all attributes EXCEPT class, special handling.
   * @param string $id
   * @param array $element
   * @return string|null
   */
  protected function addElementAttributes($id, $element = [])
  {
    if (! $this->isAttributeMember($element)) {
      return null;
    }

    $attributes = null;

    foreach ($element['attributes'] as $attr => $value) {
      if ($attr == 'class') {
        continue;
      }

      $val        = $this->setMemberValue($id, $value, $attr, $element);
      $set_value  = $this->translateValuesIfRequired($attr, $val);

      if ($set_value) {
        $attributes .= " $attr=\"$set_value\" ";
      }

    }

    return rtrim($attributes);
  }

  /**
   * @param $attr
   * @param $value
   * @return string
   */
  protected function translateValuesIfRequired($attr, $value)
  {
    if (! in_array($attr, ['title', 'aria-label', 'alt', 'label'])) {
      return $value;
    }
      $translate = $this->HB_ENV['MC']->msg($value);
      return (! empty($translate))? $translate : $value;
  }

  /**
   * Helper for addElementAttributes, is this an attributes array member?
   * @param array $element
   * @return bool
   */
  protected function isAttributeMember($element = [])
  {
    return
      isset($element['attributes']) &&
      is_array($element['attributes']);
  }

  /**
   * Add classes to the HTML element.
   * @param string $id
   * @param array $element
   * @return string|null
   */
  protected function addElementClasses($id, $element = [])
  {
    if (! $this->isClassMember($element)) {
      return null;
    }

    $classes = null;

    foreach ($element['attributes']['class'] as $classname => $value) {

      $set_value = $this->setMemberValue($id, $value, $classname, $element);

      if ($set_value) {
        $classes .= "$classname ";
      }
    }

    return (empty($classes))? null : ' class="' . rtrim($classes) . '"';
  }

  /**
   * Set substitution value if found, otherwise return what's already in the array.
   * @param string $id, the  element ID
   * @param mixed $value, existing value in array
   * @param string $key_to_find, the current member we are looking for if found in input
   * @param array $element
   * @return mixed|null
   */
  protected function setMemberValue($id, $value, $key_to_find, $element = [])
  {
    $sub_value = $this->setSubValue($id, $key_to_find, $element);

    if (! is_null($sub_value)) {
      return $sub_value;
    }

    return $value;
  }

  /**
   * If there is a substitution value in input params, return it.
   * @param string $id
   * @param string $key_to_find, the current member we are looking for if found in input
   * @param array $element
   * @return mixed|null
   */
  protected function setSubValue($id, $key_to_find, $element = [])
  {
    foreach ($this->params as $identifier => $value) {

        $ret = $this->isKeyInArray($id, $key_to_find, $identifier, $element);

        if ($ret) {
          return $value;
        }

    }
    return null;
  }

  /**
   * Recursively dig into  the element array looking for a match on the dot syntax string.
   * If found, return true and we will use the input substitution value for the existing
   * array value.
   * @param string $id, the element container ID attribute
   * @param string $key_to_find, the current member key we are looking for
   * @param string $input_string, the dot-syntax input string
   * @param array $element, current element array
   * @return bool
   */
  protected function isKeyInArray($id, $key_to_find, $input_string, $element = [])
  {
    if (!is_string($input_string) || empty($input_string) || !count($element))
    {
        return false;
    }

    if (strpos($input_string, '.') !== false)
    {
        $key_found  = false;
        $keys       = explode('.', $input_string);
        // We are already checking the parent element
        $find_id = array_shift($keys);
        if (! ($find_id == $id)) {
          return false;
        }

        foreach ($keys as $inner_key)
        {
            if (array_key_exists($inner_key, $element)) {

              if ($inner_key == $key_to_find) {
                $key_found = true;
                break;
              }

              $element = $element[$inner_key];
            }
        }

        return $key_found;
    }

    // No one home
    return false;
}

  /**
   * Helper for addElementClasses, is this a class array member?
   * @param array $element
   * @return bool
   */
  protected function isClassMember($element = [])
  {
    return
      isset($element['attributes']['class']) &&
      is_array($element['attributes']['class']);
  }

  /**
   * Add content members. This method is called recursively for nested content members.
   * @param string id, container id
   * @param array $element
   * @return string|null
   */
  protected function addElementContent($id, $element = [])
  {
    $translate = null;
    if (! $this->isContentMember($element)) {
      return null;
    }

    // Do not translate - these items should already be translated.
    $user_content = $this->userContentOverride($id);
    if (! empty($user_content)) {
      return $user_content;
    }

    $content = null;

    foreach ($element['content'] as $content_arr) {
      $content .= $this->createElementHtml($content_arr, true);
    }

    return $content;
  }

  /**
   * Users **may** override content, such as a dynamically created link text or other content.
   * The first and last elements (container id and identifier 'content') are all we need
   * in this case. if the ID and identifier match, return user-provided content.
   * @param string $id
   * @return string|null
   */
  protected function userContentOverride($id)
  {
    foreach ($this->params as $identifier => $value) {

        $path     = explode('.', $identifier);
        $find_id  = array_shift($path);
        $target   = array_pop($path);

        if (($target == 'content') && ($find_id == $id)) {
          return $value;
        }
    }

    return null;
  }

  /**
   * Helper for addElementContent, is this a content member in the array?
   * @param array $element
   * @return bool
   */
  protected function isContentMember($element = [])
  {
      return
      isset($element['content']) &&
      is_array($element['content']);
  }

  /**
   * Return the response, whether it's errors or the menu.
   * @return string
   */
  protected function returnMenuHtml()
  {
    if ($this->isErrors()) {
      return $this->composeErrors();
    }

    return $this->menu_html;
  }

  /**
   * Basic filter (could use improvement, but all values should be internal)
   * @param mixed $value
   * @return mixed
   */
  protected function filterInputValue($value)
  {
    return filter_var($value, FILTER_UNSAFE_RAW);
  }

  /**
   * Compose error HTML from $this->errors array.
   * @return string
   */
  protected function composeErrors()
  {
    $errors = "<ul class=\"error\">";

    foreach ($this->errors as $error) {
      $errors .= "<li>$error</li>";
    }

    return "$errors</ul>";
  }

  /**
   * Determine if there are errors.
   * @return bool
   */
  protected function isErrors()
  {
    return (count($this->errors) > 0);
  }

}

/**************************************************************************************
 * DOCUMENTATION
 **************************************************************************************
 *
 * Basic usage: (Full menu, see methods to access a node below)
 *
 * $CreateMenuObject = new YourConcreteClassExtendingCreateMenu($HB_ENV);
 * echo $CreateMenuObject->buildYourParamsAndOutput($params);
 *
 * Within your concrete extended class, create a method to build substitution params
 * and pass the params to $this->makeMenu($this->sub_params).
 *
 * If no substitution values are provided, this class will output everything in the JSON as HTML
 * for all nodes that do not have a property of display: false or classname: false. To populate
 * dynamic and conditional values in the JSON array dynamically, extend this class and add
 * methods in your concrete class to create a substitution array as below, then set it as
 * a param to $this->makeMenu(). These will overwrite default values set in the JSON.
 *
 * Substituting Dynamic Values:
 *
 * This class parses keys as a dot syntax for the substitution values. This may seem complicated
 * but is quite simple: imagine your html flattened into a single string with the id attribute
 * the first member of the string. This is used to set dynamic values externally or internally
 * in your concrete class. A simple example:
 *
 * $params = [
 *  config_path => path to JSON,
 *  substitute_values => [
 *    'container_id.attributes.href.class.some-class' => someFunctionCaclulatingBoolean(),
 *    'link_id.attributes.href' => 'some-external-dynamic-link.php',
 *    'link_id.content' => 'Go to Dynamic Link Here',
 * ];
 *
 * This would result in something like
 *
 * <p id="container_id" class="some-other-class-in-json some-class">
 *   <a id="link_id" href="some-external-dynamic-link.php">Go to Dynamic Link Here</a>
 * </p>
 *
 * Four basic rules for substituting values:
 * - Must have container and items members, see below.
 * - Substitution keys are STRINGS, this is not Javascript. :-) , do not mistakenly use
 *   identifier.attributes.property instead of 'identifier.attributes.property'
 * - The element to substitute **MUST** have an ID attribute.
 * - The element to substitute **MUST** exist in the JSON, it will not create new
 *   nodes (in this version, maybe later.)
 *
 * The provided JSON object must contain two members:
 *
 * - container: the parent container object of the menu, usually UL
 * - items: array of item objects in the container
 *
 * {
 *   "container" : {
 *   },
 *   "items": [
 *      {
 *      }
 *   ]
 * }
 *
 * Both the container object and the item objects adhere to the same structure. The only exception is
 * content in items, explained below.
 *
 * JSON Properties
 *
 * {
 *  "display"       : [boolean],
    "html-element"  : [string],
    "attributes"      : {
      [id] : [string],
      "class" : {
          "css-class-name" [string] : [boolean]
      }
    },
 *  "content" [
 *    [mixed: string or {other HTML element objects } ]
 *  ]
 * }
 *
 * display: boolean, optional, if omitted defaults to true, if present must be true|false. This
 * determines an HTML element is added to the output by default. For example if the display
 * property of a div is set to false and you conditionally want to enable it,
 *
 * 'element_id.display' = true
 *
 * html-element: string, required, any standard HTML element that opens and closes, examples ul, li, p, a.
 * Self-closing HTML elements can be included raw in a content node, see below.
 *
 * attributes: object, optional, any attributes to assign to html-element with the exception of
 * special case class, below. Examples: id, href, role, data-something. **ID IS REQUIRED** if you
 * want to leverage the simplicity of dot syntax (or drive yourself crazy doing something like
 * $this->menu_array['items'][5]['attributes']['class']['some-class-name'] = false )
 *
 * class: object, special attribute to allow control over multiple class assignments. Setting a
 * class value to true will display it, false will remove it from the HTML. Classes specified
 * in the JSON will only be overwritten if specified in the input attributes.class object.
 * Example
 *
 * "class" :  {
 *   "show-me" : true
 *   "do-not-show-me" : false
 * }
 *
 * 'element_id.attributes.class.show-me' = false
 * 'element_id.attributes.class.do-not-show-me' = true
 *
 * Result: the do-not-show-me class will be added to the DOM and show-me not added:
 *
 * <p id="element_id" class="do-not-show-me">
 *
 * content: array of content objects, applies only to items and not container. Content
 * can be a simple string (but must be in an array)
 *
 * "content" : ["I am the egg man", '<br>', '&nbsp; <!-- ugh -->' ]
 *
 * or it can be an array of HTML elements that contain content objects themselves. Content
 * objects adhere to the same structure as parent objects, and can contain as many other
 * content objects as needed. You **do not** need to traverse the entire tree to access
 * nested objects, which is why the ID's are so important.
 *
 * This class recursively reads nested content objects, just find it by ID.
 *
 * {
 *  "html-element" : "li",
 *    "attributes": {
 *      "id" : "unique-id",
 *        "title" : My List Item",
 *        "data-list-count" : "first item",
 *        "role" : "list item",
 *        "class" : {
 *          "my-normal-display-class" : true,
 *          "my-warning-display-class" : false
 *        }
 *    },
 *    "content" : [
 *      {
 *        "html-element" : "a",
 *          "attributes": {
 *            "id" : "my-list-item-link",
 *            "href" : "",
 *            "aria-label" : "my list item link",
 *            "class" : {
 *              "my-normal-display-class" : true,
 *              "my-warning-display-class" : false
 *            }
 *          },
 *          "content": []
 *      },
 *
 *      '<hr>'
 *    ],
 *  }
 *
 * You can guess what the following might do.
 *
 * [
 *  'unique-id.attributes.class.my-warning-display-class' => someFunctionThatChecksForWarning(),
 *  'my-list-item-link.attributes.class.my-warning-display-class' => someFunctionThatChecksForWarning(),
 *  'my-list-item-link.attributes.href' => 'you-have-been-warned.html',
 *  'my-list-item-link' => 'Warning, Link Text Here'
 * ]
 *
 **************************************************************************************
 * Access a single node of the menu
 **************************************************************************************
 *
 * Sometimes you just want a single node. The full_node param determines whether you want
 * just the content of the node or the wrapper (usually an <li>.)
 *
 * Setup is the same, in your concrete class call makeSingleMenuNode() instead.
 *
 * makeSingleMenuNode([string DOM ID if element to get], [array of input params], [optional bool full node])
 *
 * CreateMenuObject = new YourConcreteClassExtendingCreateMenu($HB_ENV);
 * echo $CreateMenuObject->buildYourSingleNodeParamsAndOutput($params);
 *
 * Without full node,
 * $compass_menu->singleCompassMenuNode($json_path, $json, 'dropdown-user-menu-ul-li', true)
 *
 * will give you the element content with the <li> wrapper. Eliminate/set to false and outputs
 * just the content.
 */