[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /**
   4   * Exception class for Services_Twilio_Twiml.
   5   */
   6  class Services_Twilio_TwimlException extends Exception {}
   7  
   8  /**
   9   * Twiml response generator.
  10   *
  11   * Author:   Neuman Vong <neuman at ashmoremusic dot com>
  12   * License:  http://creativecommons.org/licenses/MIT/ MIT
  13   */
  14  class Services_Twilio_Twiml {
  15  
  16      protected $element;
  17  
  18      /**
  19       * Constructs a Twiml response.
  20       *
  21       * :param SimpleXmlElement|array $arg: Can be any of
  22       *
  23       *   - the element to wrap
  24       *   - attributes to add to the element
  25       *   - if null, initialize an empty element named 'Response'
  26       */
  27      public function __construct($arg = null) {
  28          switch (true) {
  29          case $arg instanceof SimpleXmlElement:
  30              $this->element = $arg;
  31              break;
  32          case $arg === null:
  33              $this->element = new SimpleXmlElement('<Response/>');
  34              break;
  35          case is_array($arg):
  36              $this->element = new SimpleXmlElement('<Response/>');
  37              foreach ($arg as $name => $value) {
  38                  $this->element->addAttribute($name, $value);
  39              }
  40              break;
  41          default:
  42              throw new TwimlException('Invalid argument');
  43          }
  44      }
  45  
  46      /**
  47       * Converts method calls into Twiml verbs.
  48       *
  49       * A basic example:
  50       *
  51       * .. code-block:: php
  52       *
  53       *     php> print $this->say('hello');
  54       *     <Say>hello</Say>
  55       *
  56       * An example with attributes:
  57       *
  58       * .. code-block:: php
  59       *
  60       *     print $this->say('hello', array('voice' => 'woman'));
  61       *     <Say voice="woman">hello</Say>
  62       *
  63       * You could even just pass in an attributes array, omitting the noun:
  64       *
  65       * .. code-block:: php
  66       *
  67       *     print $this->gather(array('timeout' => '20'));
  68       *     <Gather timeout="20"/>
  69       *
  70       * :param string $verb: The Twiml verb.
  71       * :param array  $args:
  72       *   - (noun string)
  73       *   - (noun string, attributes array)
  74       *   - (attributes array)
  75       *
  76       * :return: A SimpleXmlElement
  77       * :rtype: SimpleXmlElement
  78       */
  79      public function __call($verb, array $args)
  80      {
  81          list($noun, $attrs) = $args + array('', array());
  82          if (is_array($noun)) {
  83              list($attrs, $noun) = array($noun, '');
  84          }
  85          /* addChild does not escape XML, while addAttribute does. This means if
  86           * you pass unescaped ampersands ("&") to addChild, you will generate
  87           * an error.
  88           *
  89           * Some inexperienced developers will pass in unescaped ampersands, and
  90           * we want to make their code work, by escaping the ampersands for them
  91           * before passing the string to addChild. (with htmlentities)
  92           *
  93           * However other people will know what to do, and their code
  94           * already escapes ampersands before passing them to addChild. We don't
  95           * want to break their existing code by turning their &amp;'s into
  96           * &amp;amp;
  97           *
  98           * We also want to use numeric entities, not named entities so that we
  99           * are fully compatible with XML
 100           *
 101           * The following lines accomplish the desired behavior.
 102           */
 103          $decoded = html_entity_decode($noun, ENT_COMPAT, 'UTF-8');
 104          $normalized = htmlspecialchars($decoded, ENT_COMPAT, 'UTF-8', false);
 105          $child = empty($noun)
 106              ? $this->element->addChild(ucfirst($verb))
 107              : $this->element->addChild(ucfirst($verb), $normalized);
 108          foreach ($attrs as $name => $value) {
 109              /* Note that addAttribute escapes raw ampersands by default, so we
 110               * haven't touched its implementation. So this is the matrix for
 111               * addAttribute:
 112               *
 113               * & turns into &amp;
 114               * &amp; turns into &amp;amp;
 115               */
 116              if (is_bool($value)) {
 117                  $value = ($value === true) ? 'true' : 'false';
 118              }
 119              $child->addAttribute($name, $value);
 120          }
 121          return new static($child);
 122      }
 123  
 124      /**
 125       * Returns the object as XML.
 126       *
 127       * :return: The response as an XML string
 128       * :rtype: string
 129       */
 130      public function __toString()
 131      {
 132          $xml = $this->element->asXml();
 133          return str_replace(
 134              '<?xml version="1.0"?>',
 135              '<?xml version="1.0" encoding="UTF-8"?>', $xml);
 136      }
 137  }