inc/DAVPrincipal.php

   1 <?php
   2 /**
   3 * An object representing a DAV 'Principal'
   4 *
   5 * @package   davical
   6 * @subpackage   Principal
   7 * @author    Andrew McMillan <andrew@mcmillan.net.nz>
   8 * @copyright Catalyst .Net Ltd, Morphoss Ltd <http://www.morhposs.com/>
   9 * @license   http://gnu.org/copyleft/gpl.html GNU GPL v2 or later
  10 */
  11
  12 require_once('Principal.php');
  13
  14 /**
  15 * A class for things to do with a DAV Principal
  16 *
  17 * @package   davical
  18 */
  19 class DAVPrincipal extends Principal
  20 {
  21
  22   /**
  23   * @var RFC4791: Identifies the URL(s) of any WebDAV collections that contain
  24   * calendar collections owned by the associated principal resource.
  25   */
  26   private $calendar_home_set;
  27
  28   /**
  29   * @var CardDAV: Identifies the URL(s) of any WebDAV collections that contain
  30   * addressbook collections owned by the associated principal resource.
  31   */
  32   private $addressbook_home_set;
  33
  34   /**
  35   * @var Obsolete: Identifies the URL(s) of any calendars participating in free/busy
  36   */
  37   private $calendar_free_busy_set;
  38
  39   /**
  40   * @var RFC3744: The principals that are direct members of this group.
  41   */
  42   protected $_is_group;
  43
  44   /**
  45   * @var RFC3744: The principals that are direct members of this group.
  46   */
  47   private $group_member_set;
  48
  49   /**
  50   * @var RFC3744: The groups in which the principal is directly a member.
  51   */
  52   private $group_membership;
  53
  54   /**
  55    * @var caldav-cu-proxy-02: The principals which this one has read permissions on.
  56    */
  57   private $read_proxy_for;
  58
  59   /**
  60    * @var caldav-cu-proxy-02: The principals which this one has read-write prmissions for.
  61    */
  62   private $write_proxy_for;
  63
  64    /**
  65    * @var caldav-cu-proxy-02: The principals which have read permissions on this one.
  66    */
  67   private $read_proxy_group;
  68
  69   /**
  70    * @var caldav-cu-proxy-02: The principals which have write permissions on this one.
  71    */
  72   private $write_proxy_group;
  73
  74   /**
  75    * @var CardDAV: The URL to an addressbook entry for this principal
  76    */
  77   private $principal_address;
  78
  79   /**
  80    * A unique tag which will change if this principal changes
  81    * @var string
  82    */
  83   private $unique_tag;
  84
  85   /**
  86   * Constructor
  87   * @param mixed $parameters If null, an empty Principal is created.  If it
  88   *              is an integer then that ID is read (if possible).  If it is
  89   *              an array then the Principal matching the supplied elements
  90   *              is read.  If it is an object then it is expected to be a 'usr'
  91   *              record that was read elsewhere.
  92   *
  93   * @return boolean Whether we actually read data from the DB to initialise the record.
  94   */
  95   function __construct( $parameters = null ) {
  96     global $session, $c;
  97
  98     $this->exists = null;
  99
 100     if ( $parameters == null ) return;
 101
 102     if ( is_object($parameters) ) {
 103       dbg_error_log( 'principal', 'Principal: record for %s', $parameters->username );
 104       parent::__construct('username',$parameters->username);
 105     }
 106     else if ( is_int($parameters) ) {
 107       dbg_error_log( 'principal', 'Principal: %d', $parameters );
 108       parent::__construct('principal_id',$parameters);
 109     }
 110     else if ( is_array($parameters) ) {
 111       if ( ! isset($parameters['options']['allow_by_email']) ) $parameters['options']['allow_by_email'] = false;
 112       if ( isset($parameters['username']) ) {
 113         parent::__construct('username',$parameters['username']);
 114       }
 115       else if ( isset($parameters['user_no']) ) {
 116         parent::__construct('user_no',$parameters['user_no']);
 117       }
 118       else if ( isset($parameters['principal_id']) ) {
 119         parent::__construct('principal_id',$parameters['principal_id']);
 120       }
 121       else if ( isset($parameters['email']) ) {
 122         parent::__construct('email',$parameters['email']);
 123       }
 124       else if ( isset($parameters['path']) ) {
 125         parent::__construct('path',$parameters['path']);
 126       }
 127       else if ( isset($parameters['principal-property-search']) ) {
 128         $username = $this->PropertySearch($parameters['principal-property-search']);
 129         parent::__construct('username',$username);
 130       }
 131     }
 132
 133     if ( ! $this->exists ) return;
 134
 135     $this->InitialiseRecord();
 136
 137   }
 138
 139
 140   /**
 141   * Initialise the Principal object from a $usr record from the DB.
 142   * @param object $usr The usr record from the DB.
 143   */
 144   function InitialiseRecord() {
 145     global $c;
 146
 147     $this->unique_tag = '"'.md5($this->username . $this->modified).'"';
 148     $this->_is_group = (isset($this->type_id) && $this->type_id == 3);
 149
 150     $this->principal_address = $this->url . 'principal.vcf';
 151
 152     $this->user_address_set = array(
 153        'mailto:'.$this->email,
 154        $this->url,
 155 //       ConstructURL( '/~'.$this->username.'/', true ),
 156 //       ConstructURL( '/__uuids__/'.$this->username.'/', true ),
 157     );
 158
 159     if ( isset ( $c->notifications_server ) ) {
 160       $this->xmpp_uri = 'xmpp:pubsub.'.$c->notifications_server['host'].'?pubsub;node=/davical-'.$this->principal_id;
 161       $this->xmpp_server = $c->notifications_server['host'];
 162     }
 163
 164     if ( $this->_is_group ) {
 165       $this->group_member_set = array();
 166       $qry = new AwlQuery('SELECT usr.username FROM group_member JOIN principal ON (principal_id=member_id) JOIN usr USING(user_no) WHERE group_id = :group_id ORDER BY principal.principal_id ', array( ':group_id' => $this->principal_id) );
 167       if ( $qry->Exec('DAVPrincipal') && $qry->rows() > 0 ) {
 168         while( $member = $qry->Fetch() ) {
 169           $this->group_member_set[] = ConstructURL( '/'. $member->username . '/', true);
 170         }
 171       }
 172     }
 173
 174     $this->group_membership = array();
 175     $qry = new AwlQuery('SELECT usr.username FROM group_member JOIN principal ON (principal_id=group_id) JOIN usr USING(user_no) WHERE member_id = :member_id UNION SELECT usr.username FROM group_member LEFT JOIN grants ON (to_principal=group_id) JOIN principal ON (principal_id=by_principal) JOIN usr USING(user_no) WHERE member_id = :member_id and by_principal != member_id ORDER BY 1', array( ':member_id' => $this->principal_id ) );
 176     if ( $qry->Exec('DAVPrincipal') && $qry->rows() > 0 ) {
 177       while( $group = $qry->Fetch() ) {
 178         $this->group_membership[] = ConstructURL( '/'. $group->username . '/', true);
 179       }
 180     }
 181
 182     $this->read_proxy_group = null;
 183     $this->write_proxy_group = null;
 184     $this->write_proxy_for = null;
 185     $this->read_proxy_for = null;
 186
 187     dbg_error_log( 'principal', ' User: %s (%d) URL: %s, By Email: %d', $this->username, $this->user_no, $this->url, $this->by_email );
 188   }
 189
 190
 191   /**
 192   * Split this out so we do it as infrequently as possible, given the cost.
 193   */
 194   function FetchProxyGroups() {
 195     global $c;
 196
 197     $this->read_proxy_group = array();
 198     $this->write_proxy_group = array();
 199     $this->write_proxy_for = array();
 200     $this->read_proxy_for = array();
 201
 202     if ( !isset($c->disable_caldav_proxy) || $c->disable_caldav_proxy === false ) {
 203
 204       $write_priv = privilege_to_bits(array('write'));
 205       // whom are we a proxy for? who is a proxy for us?
 206       // (as per Caldav Proxy section 5.1 Paragraph 7 and 5)
 207       $sql = 'SELECT principal_id, username, pprivs(:request_principal::int8,principal_id,:scan_depth::int) FROM principal JOIN usr USING(user_no) WHERE principal_id IN (SELECT * from p_has_proxy_access_to(:request_principal,:scan_depth))';
 208       $params = array( ':request_principal' => $this->principal_id, ':scan_depth' => $c->permission_scan_depth );
 209       $qry = new AwlQuery($sql, $params);
 210       if ( $qry->Exec('DAVPrincipal') && $qry->rows() > 0 ) {
 211         while( $relationship = $qry->Fetch() ) {
 212           if ( (bindec($relationship->pprivs) & $write_priv) != 0 ) {
 213             $this->write_proxy_for[] = ConstructURL( '/'. $relationship->username . '/', true);
 214             $this->group_membership[] = ConstructURL( '/'. $relationship->username . '/calendar-proxy-write/', true);
 215           }
 216           else {
 217             $this->read_proxy_for[] = ConstructURL( '/'. $relationship->username . '/', true);
 218             $this->group_membership[] = ConstructURL( '/'. $relationship->username . '/calendar-proxy-read/', true);
 219           }
 220         }
 221       }
 222
 223       $sql = 'SELECT principal_id, username, pprivs(:request_principal::int8,principal_id,:scan_depth::int) FROM principal JOIN usr USING(user_no) WHERE principal_id IN (SELECT * from grants_proxy_access_from_p(:request_principal,:scan_depth))';
 224       $qry = new AwlQuery($sql, $params ); // reuse $params assigned for earlier query
 225       if ( $qry->Exec('DAVPrincipal') && $qry->rows() > 0 ) {
 226         while( $relationship = $qry->Fetch() ) {
 227           if ( bindec($relationship->pprivs) & $write_priv ) {
 228             $this->write_proxy_group[] = ConstructURL( '/'. $relationship->username . '/', true);
 229           }
 230           else {
 231             $this->read_proxy_group[] = ConstructURL( '/'. $relationship->username . '/', true);
 232           }
 233         }
 234       }
 235 //      @dbg_error_log( 'principal', 'Read-proxy-for:    %s', implode(',',$this->read_proxy_for) );
 236 //      @dbg_error_log( 'principal', 'Write-proxy-for:   %s', implode(',',$this->write_proxy_for) );
 237 //      @dbg_error_log( 'principal', 'Read-proxy-group:  %s', implode(',',$this->read_proxy_group) );
 238 //      @dbg_error_log( 'principal', 'Write-proxy-group: %s', implode(',',$this->write_proxy_group) );
 239     }
 240   }
 241
 242
 243   /**
 244   * Accessor for the read proxy group
 245   */
 246   function ReadProxyGroup() {
 247     if ( !isset($this->read_proxy_group) ) $this->FetchProxyGroups();
 248     return $this->read_proxy_group;
 249   }
 250
 251
 252   /**
 253   * Accessor for the write proxy group
 254   */
 255   function WriteProxyGroup() {
 256     if ( !isset($this->write_proxy_group) ) $this->FetchProxyGroups();
 257     return $this->write_proxy_group;
 258   }
 259
 260
 261   /**
 262   * Accessor for read or write proxy
 263   * @param string read/write - which sort of proxy list is requested.
 264   */
 265   function ProxyFor( $type ) {
 266     if ( !isset($this->read_proxy_for) ) $this->FetchProxyGroups();
 267     if ( $type == 'write' ) return $this->write_proxy_for;
 268     return $this->read_proxy_for;
 269   }
 270
 271
 272   /**
 273   * Accessor for the group membership - the groups this principal is a member of
 274   */
 275   function GroupMembership() {
 276     if ( !isset($this->read_proxy_group) ) $this->FetchProxyGroups();
 277     return $this->group_membership;
 278   }
 279
 280
 281   /**
 282   * Accessor for the group member set - the members of this group
 283   */
 284   function GroupMemberSet() {
 285     if ( ! $this->_is_group ) return null;
 286     return $this->group_member_set;
 287   }
 288
 289
 290   /**
 291   * Is this a group principal?
 292   * @return boolean Whether this is a group principal
 293   */
 294   function IsGroup() {
 295     return $this->_is_group;
 296   }
 297
 298
 299   /**
 300   * Return an arbitrary property
 301   * @return string The name of the arbitrary property
 302   */
 303   function GetProperty( $property_id ) {
 304
 305     switch( $property_id ) {
 306       case 'DAV::resource-id':
 307         if ( $this->exists && $this->principal_id > 0 )
 308           ConstructURL('/.resources/'.$this->principal_id);
 309         else
 310           return null;
 311         break;
 312     }
 313
 314     if ( isset($this->{$property_id}) ) {
 315       if ( ! is_object($this->{$property_id}) ) return $this->{$property_id};
 316       return clone($this->{$property_id});
 317     }
 318     return null;
 319   }
 320
 321   /**
 322   * Returns the unique_tag (ETag or getctag) for this resource
 323   */
 324   public function unique_tag() {
 325     if ( isset($this->unique_tag) ) return $this->unique_tag;
 326
 327     if ( $this->exists !== true ) $this->unique_tag = '"-1"';
 328
 329     return $this->unique_tag;
 330   }
 331
 332
 333   /**
 334   * Get the calendar_home_set, as lazily as possible
 335   */
 336   function calendar_home_set() {
 337     if ( !isset($this->calendar_home_set) ) {
 338       $this->calendar_home_set = array();
 339       $qry = new AwlQuery('SELECT DISTINCT parent_container FROM collection WHERE is_calendar AND dav_name ~ :dav_name_start',
 340                              array( ':dav_name_start' => '^'.$this->dav_name));
 341       if ( $qry->Exec('principal',__LINE__,__FILE__) ) {
 342         if ( $qry->rows() > 0 ) {
 343           while( $calendar = $qry->Fetch() ) {
 344             $this->calendar_home_set[] = ConstructURL($calendar->parent_container, true);
 345           }
 346         }
 347         else {
 348           $this->calendar_home_set[] = $this->url;
 349         }
 350       }
 351     }
 352     return $this->calendar_home_set;
 353   }
 354
 355
 356   /**
 357   * Get the addressbook_home_set, as lazily as possible
 358   */
 359   function addressbook_home_set() {
 360     if ( !isset($this->addressbook_home_set) ) {
 361       $this->addressbook_home_set = array();
 362       $qry = new AwlQuery('SELECT DISTINCT parent_container FROM collection WHERE is_addressbook AND dav_name ~ :dav_name_start',
 363                              array( ':dav_name_start' => '^'.$this->dav_name));
 364       if ( $qry->Exec('principal',__LINE__,__FILE__) ) {
 365         if ( $qry->rows() > 0 ) {
 366           while( $addressbook = $qry->Fetch() ) {
 367             $this->addressbook_home_set[] = ConstructURL($addressbook->parent_container, true);
 368           }
 369         }
 370         else {
 371           $this->addressbook_home_set[] = $this->url;
 372         }
 373       }
 374     }
 375     return $this->addressbook_home_set;
 376   }
 377
 378
 379   /**
 380   * Get the calendar_free_busy_set, as lazily as possible
 381   */
 382   function calendar_free_busy_set() {
 383     if ( !isset($this->calendar_free_busy_set) ) {
 384       /**
 385       * calendar-free-busy-set has been dropped from draft 5 of the scheduling extensions for CalDAV
 386       * in favour of ???
 387       */
 388       $this->calendar_free_busy_set = array();
 389       $qry = new AwlQuery('SELECT dav_name FROM collection WHERE is_calendar AND (schedule_transp = \'opaque\' OR schedule_transp IS NULL) AND dav_name ~ :dav_name_start ORDER BY user_no, collection_id',
 390                              array( ':dav_name_start' => '^'.$this->dav_name));
 391       if ( $qry->Exec('principal',__LINE__,__FILE__) ) {
 392         while( $calendar = $qry->Fetch() ) {
 393           $this->calendar_free_busy_set[] = ConstructURL($calendar->dav_name, true);
 394         }
 395       }
 396     }
 397     return $this->calendar_free_busy_set;
 398   }
 399
 400
 401   /**
 402   * Return the privileges bits for the current session user to this resource
 403   */
 404   function Privileges() {
 405     global $session;
 406     if ( !isset($this->privileges) ) $this->privileges = 0;
 407     if ( is_string($this->privileges) ) $this->privileges = bindec( $this->privileges );
 408     if ( $this->_is_group ) {
 409       if ( in_array($session->principal->url(), $this->GroupMemberSet()) ) {
 410         $this->privileges |=  privilege_to_bits( array('DAV::read', 'DAV::read-current-user-privilege-set') );
 411       }
 412     }
 413     return $this->privileges;
 414   }
 415
 416
 417   /**
 418   * Returns a representation of the principal as a collection
 419   */
 420   function AsCollection() {
 421     $dav_name = (isset($this->original_request_url) ? DeconstructURL($this->original_request_url) : $this->dav_name());
 422     $collection = (object) array(
 423                             'collection_id' => ($this->principal_id() ? $this->principal_id() : 0),
 424                             'is_calendar' => false,
 425                             'is_addressbook' => false,
 426                             'is_principal' => true,
 427                             'type'     => 'principal' . (isset($this->original_request_url) ? '_link' : ''),
 428                             'user_no'  => ($this->user_no() ? $this->user_no() : 0),
 429                             'username' => $this->username(),
 430                             'dav_name' => $dav_name,
 431                             'parent_container' => '/',
 432                             'email'    => ($this->email()? $this->email() : ''),
 433                             'created'  => $this->created,
 434                             'updated'  => $this->modified,
 435                             'dav_etag' => substr($this->unique_tag(),1,-1),
 436                             'resourcetypes' => $this->resourcetypes
 437                   );
 438     $collection->dav_displayname =  (isset($this->dav_displayname) ? $this->dav_displayname : (isset($this->fullname) ? $this->fullname : $collection->username));
 439
 440     return $collection;
 441   }
 442
 443
 444   function PropertySearch( $parameters ) {
 445     throw new Exception("Unimplemented!");
 446   }
 447
 448   /**
 449   * Returns properties which are specific to this principal
 450   */
 451   function PrincipalProperty( $tag, $prop, &$reply, &$denied ) {
 452
 453     dbg_error_log('principal',': RenderAsXML: Principal Property "%s"', $tag );
 454     switch( $tag ) {
 455       case 'DAV::getcontenttype':
 456         $prop->NewElement('getcontenttype', 'httpd/unix-directory' );
 457         break;
 458
 459       case 'DAV::resourcetype':
 460         $prop->NewElement('resourcetype', array( new XMLElement('principal'), new XMLElement('collection')) );
 461         break;
 462
 463       case 'DAV::displayname':
 464         $prop->NewElement('displayname', $this->fullname );
 465         break;
 466
 467       case 'DAV::principal-URL':
 468         $prop->NewElement('principal-URL', $reply->href($this->url()) );
 469         break;
 470
 471       case 'DAV::getlastmodified':
 472         $prop->NewElement('getlastmodified', ISODateToHTTPDate($this->modified) );
 473         break;
 474
 475       case 'DAV::creationdate':
 476         $prop->NewElement('creationdate', DateToISODate($this->created) );
 477         break;
 478
 479       case 'DAV::getcontentlanguage':
 480         /** Use the principal's locale by preference, otherwise system default */
 481         $locale = (isset($c->current_locale) ? $c->current_locale : '');
 482         if ( isset($this->locale) && $this->locale != '' ) $locale = $this->locale;
 483         $prop->NewElement('getcontentlanguage', $locale );
 484         break;
 485
 486       case 'DAV::group-member-set':
 487         if ( ! $this->_is_group ) return false;
 488         $prop->NewElement('group-member-set', $reply->href($this->group_member_set) );
 489         break;
 490
 491       case 'DAV::group-membership':
 492         $prop->NewElement('group-membership', $reply->href($this->GroupMembership()) );
 493         break;
 494
 495       case 'urn:ietf:params:xml:ns:caldav:schedule-inbox-URL':
 496         $reply->CalDAVElement($prop, 'schedule-inbox-URL', $reply->href($this->url('schedule-inbox')) );
 497         break;
 498
 499       case 'urn:ietf:params:xml:ns:caldav:schedule-outbox-URL':
 500         $reply->CalDAVElement($prop, 'schedule-outbox-URL', $reply->href($this->url('schedule-outbox')) );
 501         break;
 502
 503       case 'urn:ietf:params:xml:ns:caldav:schedule-default-calendar-URL':
 504         $reply->CalDAVElement($prop, 'schedule-default-calendar-URL', $reply->href($this->url('schedule-default-calendar')) );
 505         break;
 506
 507       case 'http://calendarserver.org/ns/:dropbox-home-URL':
 508         $reply->CalendarserverElement($prop, 'dropbox-home-URL', $reply->href($this->url('dropbox')) );
 509         break;
 510
 511       case 'http://calendarserver.org/ns/:xmpp-server':
 512         if ( ! isset( $this->xmpp_uri ) ) return false;
 513         $reply->CalendarserverElement($prop, 'xmpp-server', $this->xmpp_server );
 514         break;
 515
 516       case 'http://calendarserver.org/ns/:xmpp-uri':
 517         if ( ! isset( $this->xmpp_uri ) ) return false;
 518         $reply->CalendarserverElement($prop, 'xmpp-uri', $this->xmpp_uri );
 519         break;
 520
 521       case 'urn:ietf:params:xml:ns:carddav:addressbook-home-set':
 522         $reply->NSElement($prop, $tag, $reply->href( $this->addressbook_home_set() ) );
 523         break;
 524
 525       case 'urn:ietf:params:xml:ns:caldav:calendar-home-set':
 526         $reply->NSElement($prop, $tag, $reply->href( $this->calendar_home_set() ) );
 527         break;
 528
 529       case 'urn:ietf:params:xml:ns:caldav:calendar-free-busy-set':
 530         $reply->CalDAVElement( $prop, 'calendar-free-busy-set', $reply->href( $this->calendar_free_busy_set() ) );
 531         break;
 532
 533       case 'urn:ietf:params:xml:ns:caldav:calendar-user-address-set':
 534         $reply->CalDAVElement($prop, 'calendar-user-address-set', $reply->href($this->user_address_set) );
 535         break;
 536
 537       case 'DAV::owner':
 538         // After a careful reading of RFC3744 we see that this must be the principal-URL of the owner
 539         $reply->DAVElement( $prop, 'owner', $reply->href( $this->url ) );
 540         break;
 541
 542       // Empty tag responses.
 543       case 'DAV::alternate-URI-set':
 544         $prop->NewElement( $reply->Tag($tag));
 545         break;
 546
 547       case 'SOME-DENIED-PROPERTY':  /** @todo indicating the style for future expansion */
 548         $denied[] = $reply->Tag($tag);
 549         break;
 550
 551       default:
 552         return false;
 553         break;
 554     }
 555
 556     return true;
 557   }
 558
 559
 560   /**
 561   * Render XML for a single Principal (user) from the DB
 562   *
 563   * @param array $properties The requested properties for this principal
 564   * @param reference $reply A reference to the XMLDocument being used for the reply
 565   * @param boolean $props_only Default false.  If true will only return the fragment with the properties, not a full response fragment.
 566   *
 567   * @return string An XML fragment with the requested properties for this principal
 568   */
 569   function RenderAsXML( $properties, &$reply, $props_only = false ) {
 570     global $request;
 571
 572     dbg_error_log('principal',': RenderAsXML: Principal "%s"', $this->username );
 573
 574     $prop = new XMLElement('prop');
 575     $denied = array();
 576     $not_found = array();
 577     foreach( $properties AS $k => $tag ) {
 578       if ( ! $this->PrincipalProperty( $tag, $prop, $reply, $denied ) ) {
 579         dbg_error_log( 'principal', 'Request for unsupported property "%s" of principal "%s".', $tag, $this->username );
 580         $not_found[] = $reply->Tag($tag);
 581       }
 582     }
 583
 584     if ( $props_only ) return $prop;
 585
 586     $status = new XMLElement('status', 'HTTP/1.1 200 OK' );
 587
 588     $propstat = new XMLElement( 'propstat', array( $prop, $status) );
 589     $href = $reply->href($this->url );
 590
 591     $elements = array($href,$propstat);
 592
 593     if ( count($denied) > 0 ) {
 594       $status = new XMLElement('status', 'HTTP/1.1 403 Forbidden' );
 595       $noprop = new XMLElement('prop');
 596       foreach( $denied AS $k => $v ) {
 597         $noprop->NewElement( $v );
 598       }
 599       $elements[] = new XMLElement( 'propstat', array( $noprop, $status) );
 600     }
 601
 602     if ( count($not_found) > 0 ) {
 603       $status = new XMLElement('status', 'HTTP/1.1 404 Not Found' );
 604       $noprop = new XMLElement('prop');
 605       foreach( $not_found AS $k => $v ) {
 606         $noprop->NewElement( $v );
 607       }
 608       $elements[] = new XMLElement( 'propstat', array( $noprop, $status) );
 609     }
 610
 611     $response = new XMLElement( 'response', $elements );
 612
 613     return $response;
 614   }
 615
 616 }