[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /**
   4   * Joomla! Content Management System
   5   *
   6   * @copyright  (C) 2005 Open Source Matters, Inc. <https://www.joomla.org>
   7   * @license    GNU General Public License version 2 or later; see LICENSE.txt
   8   */
   9  
  10  namespace Joomla\CMS\Help;
  11  
  12  use Joomla\CMS\Application\ApplicationHelper;
  13  use Joomla\CMS\Component\ComponentHelper;
  14  use Joomla\CMS\Factory;
  15  use Joomla\CMS\Language\Text;
  16  use Joomla\CMS\Version;
  17  
  18  // phpcs:disable PSR1.Files.SideEffects
  19  \defined('JPATH_PLATFORM') or die;
  20  // phpcs:enable PSR1.Files.SideEffects
  21  
  22  /**
  23   * Help system class
  24   *
  25   * @since  1.5
  26   */
  27  class Help
  28  {
  29      /**
  30       * Create a URL for a given help key reference
  31       *
  32       * @param   string   $ref           The name of the help screen (its key reference)
  33       * @param   boolean  $useComponent  Use the help file in the component directory
  34       * @param   string   $override      Use this URL instead of any other
  35       * @param   string   $component     Name of component (or null for current component)
  36       *
  37       * @return  string
  38       *
  39       * @since   1.5
  40       */
  41      public static function createUrl($ref, $useComponent = false, $override = null, $component = null)
  42      {
  43          $local = false;
  44          $app   = Factory::getApplication();
  45  
  46          if ($component === null) {
  47              $component = ApplicationHelper::getComponentName();
  48          }
  49  
  50          //  Determine the location of the help file.  At this stage the URL
  51          //  can contain substitution codes that will be replaced later.
  52  
  53          if ($override) {
  54              $url = $override;
  55          } else {
  56              // Get the global help URL.
  57              $url = $app->get('helpurl');
  58  
  59              // Component help URL overrides user and global.
  60              if ($useComponent) {
  61                  // Look for help URL in component parameters.
  62                  $params = ComponentHelper::getParams($component);
  63                  $url    = $params->get('helpURL');
  64  
  65                  if ($url == '') {
  66                      $local = true;
  67                      $url   = 'components/{component}/help/{language}/{keyref}';
  68                  }
  69              }
  70  
  71              // Set up a local help URL.
  72              if (!$url) {
  73                  $local = true;
  74                  $url   = 'help/{language}/{keyref}';
  75              }
  76          }
  77  
  78          // If the URL is local then make sure we have a valid file extension on the URL.
  79          if ($local) {
  80              if (!preg_match('#\.html$|\.xml$#i', $ref)) {
  81                  $url .= '.html';
  82              }
  83          }
  84  
  85          /*
  86           *  Replace substitution codes in the URL.
  87           */
  88          $lang    = Factory::getLanguage();
  89          $version = new Version();
  90          $jver    = explode('.', $version->getShortVersion());
  91          $jlang   = explode('-', $lang->getTag());
  92  
  93          $debug  = $lang->setDebug(false);
  94          $keyref = Text::_($ref);
  95          $lang->setDebug($debug);
  96  
  97          // Replace substitution codes in help URL.
  98          $search = array(
  99              // Application name (eg. 'Administrator')
 100              '{app}',
 101              // Component name (eg. 'com_content')
 102              '{component}',
 103              // Help screen key reference
 104              '{keyref}',
 105              // Full language code (eg. 'en-GB')
 106              '{language}',
 107              // Short language code (eg. 'en')
 108              '{langcode}',
 109              // Region code (eg. 'GB')
 110              '{langregion}',
 111              // Joomla major version number
 112              '{major}',
 113              // Joomla minor version number
 114              '{minor}',
 115              // Joomla maintenance version number
 116              '{maintenance}',
 117          );
 118  
 119          $replace = array(
 120              // {app}
 121              $app->getName(),
 122              // {component}
 123              $component,
 124              // {keyref}
 125              $keyref,
 126              // {language}
 127              $lang->getTag(),
 128              // {langcode}
 129              $jlang[0],
 130              // {langregion}
 131              $jlang[1],
 132              // {major}
 133              $jver[0],
 134              // {minor}
 135              $jver[1],
 136              // {maintenance}
 137              $jver[2],
 138          );
 139  
 140          // If the help file is local then check it exists.
 141          // If it doesn't then fallback to English.
 142          if ($local) {
 143              $try = str_replace($search, $replace, $url);
 144  
 145              if (!is_file(JPATH_BASE . '/' . $try)) {
 146                  $replace[3] = 'en-GB';
 147                  $replace[4] = 'en';
 148                  $replace[5] = 'GB';
 149              }
 150          }
 151  
 152          $url = str_replace($search, $replace, $url);
 153  
 154          return $url;
 155      }
 156  
 157      /**
 158       * Builds a list of the help sites which can be used in a select option.
 159       *
 160       * @param   string  $pathToXml  Path to an XML file.
 161       *
 162       * @return  array  An array of arrays (text, value, selected).
 163       *
 164       * @since   1.5
 165       */
 166      public static function createSiteList($pathToXml)
 167      {
 168          $list = array();
 169          $xml  = false;
 170  
 171          if (!empty($pathToXml)) {
 172              $xml = simplexml_load_file($pathToXml);
 173          }
 174  
 175          if (!$xml) {
 176              $option['text']  = 'English (GB) help.joomla.org';
 177              $option['value'] = 'https://help.joomla.org';
 178  
 179              $list[] = (object) $option;
 180          } else {
 181              $option = array();
 182  
 183              foreach ($xml->sites->site as $site) {
 184                  $option['text']  = (string) $site;
 185                  $option['value'] = (string) $site->attributes()->url;
 186  
 187                  $list[] = (object) $option;
 188              }
 189          }
 190  
 191          return $list;
 192      }
 193  }