[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  namespace Box\Spout\Common\Escaper;
   4  
   5  /**
   6   * Class XLSX
   7   * Provides functions to escape and unescape data for XLSX files
   8   *
   9   * @package Box\Spout\Common\Escaper
  10   */
  11  class XLSX implements EscaperInterface
  12  {
  13      /** @var string[] Control characters to be escaped */
  14      protected $controlCharactersEscapingMap;
  15  
  16      /**
  17       *
  18       */
  19      public function __construct()
  20      {
  21          $this->controlCharactersEscapingMap = $this->getControlCharactersEscapingMap();
  22      }
  23  
  24      /**
  25       * Escapes the given string to make it compatible with XLSX
  26       *
  27       * @param string $string The string to escape
  28       * @return string The escaped string
  29       */
  30      public function escape($string)
  31      {
  32          $escapedString = $this->escapeControlCharacters($string);
  33          $escapedString = htmlspecialchars($escapedString, ENT_QUOTES);
  34  
  35          return $escapedString;
  36      }
  37  
  38      /**
  39       * Unescapes the given string to make it compatible with XLSX
  40       *
  41       * @param string $string The string to unescape
  42       * @return string The unescaped string
  43       */
  44      public function unescape($string)
  45      {
  46          $unescapedString = htmlspecialchars_decode($string, ENT_QUOTES);
  47          $unescapedString = $this->unescapeControlCharacters($unescapedString);
  48  
  49          return $unescapedString;
  50      }
  51  
  52      /**
  53       * Builds the map containing control characters to be escaped
  54       * mapped to their escaped values.
  55       * "\t", "\r" and "\n" don't need to be escaped.
  56       *
  57       * NOTE: the logic has been adapted from the XlsxWriter library (BSD License)
  58       * @link https://github.com/jmcnamara/XlsxWriter/blob/f1e610f29/xlsxwriter/sharedstrings.py#L89
  59       *
  60       * @return string[]
  61       */
  62      protected function getControlCharactersEscapingMap()
  63      {
  64          $controlCharactersEscapingMap = [];
  65          $whitelistedControlCharacters = ["\t", "\r", "\n"];
  66  
  67          // control characters values are from 0 to 1F (hex values) in the ASCII table
  68          for ($charValue = 0x0; $charValue <= 0x1F; $charValue++) {
  69              if (!in_array(chr($charValue), $whitelistedControlCharacters)) {
  70                  $charHexValue = dechex($charValue);
  71                  $escapedChar = '_x' . sprintf('%04s' , strtoupper($charHexValue)) . '_';
  72                  $controlCharactersEscapingMap[$escapedChar] = chr($charValue);
  73              }
  74          }
  75  
  76          return $controlCharactersEscapingMap;
  77      }
  78  
  79      /**
  80       * Converts PHP control characters from the given string to OpenXML escaped control characters
  81       *
  82       * Excel escapes control characters with _xHHHH_ and also escapes any
  83       * literal strings of that type by encoding the leading underscore.
  84       * So "\0" -> _x0000_ and "_x0000_" -> _x005F_x0000_.
  85       *
  86       * NOTE: the logic has been adapted from the XlsxWriter library (BSD License)
  87       * @link https://github.com/jmcnamara/XlsxWriter/blob/f1e610f29/xlsxwriter/sharedstrings.py#L89
  88       *
  89       * @param string $string String to escape
  90       * @return string
  91       */
  92      protected function escapeControlCharacters($string)
  93      {
  94          $escapedString = $this->escapeEscapeCharacter($string);
  95          return str_replace(array_values($this->controlCharactersEscapingMap), array_keys($this->controlCharactersEscapingMap), $escapedString);
  96      }
  97  
  98      /**
  99       * Escapes the escape character: "_x0000_" -> "_x005F_x0000_"
 100       *
 101       * @param string $string String to escape
 102       * @return string The escaped string
 103       */
 104      protected function escapeEscapeCharacter($string)
 105      {
 106          return preg_replace('/_(x[\dA-F]{4})_/', '_x005F_$1_', $string);
 107      }
 108  
 109      /**
 110       * Converts OpenXML escaped control characters from the given string to PHP control characters
 111       *
 112       * Excel escapes control characters with _xHHHH_ and also escapes any
 113       * literal strings of that type by encoding the leading underscore.
 114       * So "_x0000_" -> "\0" and "_x005F_x0000_" -> "_x0000_"
 115       *
 116       * NOTE: the logic has been adapted from the XlsxWriter library (BSD License)
 117       * @link https://github.com/jmcnamara/XlsxWriter/blob/f1e610f29/xlsxwriter/sharedstrings.py#L89
 118       *
 119       * @param string $string String to unescape
 120       * @return string
 121       */
 122      protected function unescapeControlCharacters($string)
 123      {
 124          $unescapedString = $string;
 125          foreach ($this->controlCharactersEscapingMap as $escapedCharValue => $charValue) {
 126              // only unescape characters that don't contain the escaped escape character for now
 127              $unescapedString = preg_replace("/(?<!_x005F)($escapedCharValue)/", $charValue, $unescapedString);
 128          }
 129  
 130          return $this->unescapeEscapeCharacter($unescapedString);
 131      }
 132  
 133      /**
 134       * Unecapes the escape character: "_x005F_x0000_" => "_x0000_"
 135       *
 136       * @param string $string String to unescape
 137       * @return string The unescaped string
 138       */
 139      protected function unescapeEscapeCharacter($string)
 140      {
 141          return preg_replace('/_x005F(_x[\dA-F]{4}_)/', '$1', $string);
 142      }
 143  }