Zend/Gdata/YouTube/VideoQuery.php

   1 <?php
   2
   3 /**
   4  * Zend Framework
   5  *
   6  * LICENSE
   7  *
   8  * This source file is subject to the new BSD license that is bundled
   9  * with this package in the file LICENSE.txt.
  10  * It is also available through the world-wide-web at this URL:
  11  * http://framework.zend.com/license/new-bsd
  12  * If you did not receive a copy of the license and are unable to
  13  * obtain it through the world-wide-web, please send an email
  14  * to license@zend.com so we can send you a copy immediately.
  15  *
  16  * @category   Zend
  17  * @package    Zend_Gdata
  18  * @subpackage YouTube
  19  * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
  20  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  21
  22  */
  23
  24 /**
  25  * Zend_Gdata_YouTube
  26  */
  27 require_once('Zend/Gdata/YouTube.php');
  28
  29 /**
  30  * Zend_Gdata_Query
  31  */
  32 require_once('Zend/Gdata/Query.php');
  33
  34 /**
  35  * Assists in constructing queries for YouTube videos
  36  *
  37  * @link http://code.google.com/apis/youtube/
  38  *
  39  * @category   Zend
  40  * @package    Zend_Gdata
  41  * @subpackage YouTube
  42  * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
  43  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  44  */
  45 class Zend_Gdata_YouTube_VideoQuery extends Zend_Gdata_Query
  46 {
  47
  48     /**
  49      * Create Gdata_YouTube_VideoQuery object
  50      */
  51     public function __construct($url = null)
  52     {
  53         parent::__construct($url);
  54     }
  55
  56     /**
  57      * Sets the type of feed this query should be used to search
  58      *
  59      * @param string $feedType The type of feed
  60      * @param string $videoId The ID of the video associated with this query
  61      * @param string $entry The ID of the entry associated with this query
  62      */
  63     public function setFeedType($feedType, $videoId = null, $entry = null)
  64     {
  65         switch ($feedType) {
  66         case 'top rated':
  67             $this->_url = Zend_Gdata_YouTube::STANDARD_TOP_RATED_URI;
  68             break;
  69         case 'most viewed':
  70             $this->_url = Zend_Gdata_YouTube::STANDARD_MOST_VIEWED_URI;
  71             break;
  72         case 'recently featured':
  73             $this->_url = Zend_Gdata_YouTube::STANDARD_RECENTLY_FEATURED_URI;
  74             break;
  75         case 'mobile':
  76             $this->_url = Zend_Gdata_YouTube::STANDARD_WATCH_ON_MOBILE_URI;
  77             break;
  78         case 'related':
  79             if ($videoId === null) {
  80                 require_once 'Zend/Gdata/App/InvalidArgumentException.php';
  81                 throw new Zend_Gdata_App_InvalidArgumentException(
  82                     'Video ID must be set for feed of type: ' . $feedType);
  83             } else {
  84                 $this->_url = Zend_Gdata_YouTube::VIDEO_URI . '/' . $videoId .
  85                     '/related';
  86             }
  87             break;
  88         case 'responses':
  89             if ($videoId === null) {
  90                 require_once 'Zend/Gdata/App/InvalidArgumentException.php';
  91                 throw new Zend_Gdata_App_Exception(
  92                     'Video ID must be set for feed of type: ' . $feedType);
  93             } else {
  94                 $this->_url = Zend_Gdata_YouTube::VIDEO_URI . '/' . $videoId .
  95                     'responses';
  96             }
  97             break;
  98         case 'comments':
  99             if ($videoId === null) {
 100                 require_once 'Zend/Gdata/App/InvalidArgumentException.php';
 101                 throw new Zend_Gdata_App_Exception(
 102                     'Video ID must be set for feed of type: ' . $feedType);
 103             } else {
 104                 $this->_url = Zend_Gdata_YouTube::VIDEO_URI . '/' .
 105                     $videoId . 'comments';
 106                 if ($entry !== null) {
 107                     $this->_url .= '/' . $entry;
 108                 }
 109             }
 110             break;
 111         default:
 112             require_once 'Zend/Gdata/App/Exception.php';
 113             throw new Zend_Gdata_App_Exception('Unknown feed type');
 114             break;
 115         }
 116     }
 117
 118     /**
 119      * Sets the location parameter for the query
 120      *
 121      * @param string $value
 122      * @throws Zend_Gdata_App_InvalidArgumentException
 123      * @return Zend_Gdata_YouTube_VideoQuery Provides a fluent interface
 124      */
 125     public function setLocation($value)
 126     {
 127         switch($value) {
 128             case null:
 129                 unset($this->_params['location']);
 130             default:
 131                 $parameters = explode(',', $value);
 132                 if (count($parameters) != 2) {
 133                     require_once 'Zend/Gdata/App/InvalidArgumentException.php';
 134                     throw new Zend_Gdata_App_InvalidArgumentException(
 135                         'You must provide 2 coordinates to the location ' .
 136                         'URL parameter');
 137                 }
 138
 139                 foreach($parameters as $param) {
 140                     $temp = trim($param);
 141                     // strip off the optional exclamation mark for numeric check
 142                     if (substr($temp, -1) == '!') {
 143                         $temp = substr($temp, 0, -1);
 144                     }
 145                     if (!is_numeric($temp)) {
 146                         require_once 'Zend/Gdata/App/InvalidArgumentException.php';
 147                         throw new Zend_Gdata_App_InvalidArgumentException(
 148                             'Value provided to location parameter must' .
 149                             ' be in the form of two coordinates');
 150                     }
 151                 }
 152                 $this->_params['location'] = $value;
 153         }
 154     }
 155
 156     /**
 157      * Get the value of the location parameter
 158      *
 159      * @return string|null Return the location if it exists, null otherwise.
 160      */
 161     public function getLocation()
 162     {
 163         if (array_key_exists('location', $this->_params)) {
 164             return $this->_params['location'];
 165         } else {
 166             return null;
 167         }
 168     }
 169
 170
 171     /**
 172      * Sets the location-radius parameter for the query
 173      *
 174      * @param string $value
 175      * @return Zend_Gdata_YouTube_VideoQuery Provides a fluent interface
 176      */
 177     public function setLocationRadius($value)
 178     {
 179         switch($value) {
 180             case null:
 181                 unset($this->_params['location-radius']);
 182             default:
 183                 $this->_params['location-radius'] = $value;
 184         }
 185     }
 186
 187     /**
 188      * Get the value of the location-radius parameter
 189      *
 190      * @return string|null Return the location-radius if it exists,
 191      * null otherwise.
 192      */
 193     public function getLocationRadius()
 194     {
 195         if (array_key_exists('location-radius', $this->_params)) {
 196             return $this->_params['location-radius'];
 197         } else {
 198             return null;
 199         }
 200     }
 201
 202     /**
 203      * Sets the time period over which this query should apply
 204      *
 205      * @param string $value
 206      * @throws Zend_Gdata_App_InvalidArgumentException
 207      * @return Zend_Gdata_YouTube_VideoQuery Provides a fluent interface
 208      */
 209     public function setTime($value = null)
 210     {
 211         switch ($value) {
 212             case 'today':
 213                 $this->_params['time'] = 'today';
 214                 break;
 215             case 'this_week':
 216                 $this->_params['time'] = 'this_week';
 217                 break;
 218             case 'this_month':
 219                 $this->_params['time'] = 'this_month';
 220                 break;
 221             case 'all_time':
 222                 $this->_params['time'] = 'all_time';
 223                 break;
 224             case null:
 225                 unset($this->_params['time']);
 226             default:
 227                 require_once 'Zend/Gdata/App/InvalidArgumentException.php';
 228                 throw new Zend_Gdata_App_InvalidArgumentException(
 229                     'Unknown time value');
 230                 break;
 231         }
 232         return $this;
 233     }
 234
 235     /**
 236      * Sets the value of the uploader parameter
 237      *
 238      * @param string $value The value of the uploader parameter. Currently this
 239      *        can only be set to the value of 'partner'.
 240      * @throws Zend_Gdata_App_InvalidArgumentException
 241      * @return Zend_Gdata_YouTube_VideoQuery Provides a fluent interface
 242      */
 243     public function setUploader($value = null)
 244     {
 245         switch ($value) {
 246             case 'partner':
 247                 $this->_params['uploader'] = 'partner';
 248                 break;
 249             case null:
 250                 unset($this->_params['uploader']);
 251                 break;
 252             default:
 253                 require_once 'Zend/Gdata/App/InvalidArgumentException.php';
 254                 throw new Zend_Gdata_App_InvalidArgumentException(
 255                     'Unknown value for uploader');
 256         }
 257         return $this;
 258     }
 259
 260     /**
 261      * Sets the formatted video query (vq) URL param value
 262      *
 263      * @param string $value
 264      * @return Zend_Gdata_YouTube_VideoQuery Provides a fluent interface
 265      */
 266     public function setVideoQuery($value = null)
 267     {
 268         if ($value != null) {
 269             $this->_params['vq'] = $value;
 270         } else {
 271             unset($this->_params['vq']);
 272         }
 273         return $this;
 274     }
 275
 276     /**
 277      * Sets the param to return videos of a specific format
 278      *
 279      * @param string $value
 280      * @return Zend_Gdata_YouTube_VideoQuery Provides a fluent interface
 281      */
 282     public function setFormat($value = null)
 283     {
 284         if ($value != null) {
 285             $this->_params['format'] = $value;
 286         } else {
 287             unset($this->_params['format']);
 288         }
 289         return $this;
 290     }
 291
 292     /**
 293      * Sets whether or not to include racy videos in the search results
 294      *
 295      * @param string $value
 296      * @return Zend_Gdata_YouTube_VideoQuery Provides a fluent interface
 297      */
 298     public function setRacy($value = null)
 299     {
 300         switch ($value) {
 301             case 'include':
 302                 $this->_params['racy'] = $value;
 303                 break;
 304             case 'exclude':
 305                 $this->_params['racy'] = $value;
 306                 break;
 307             case null:
 308                 unset($this->_params['racy']);
 309                 break;
 310         }
 311         return $this;
 312     }
 313
 314     /**
 315      * Whether or not to include racy videos in the search results
 316      *
 317      * @return string|null The value of racy if it exists, null otherwise.
 318      */
 319     public function getRacy()
 320     {
 321         if (array_key_exists('racy', $this->_params)) {
 322             return $this->_params['racy'];
 323         } else {
 324             return null;
 325         }
 326     }
 327
 328     /**
 329      * Set the safeSearch parameter
 330      *
 331      * @param string $value The value of the parameter, currently only 'none',
 332      *        'moderate' or 'strict' are allowed values.
 333      * @throws Zend_Gdata_App_InvalidArgumentException
 334      * @return Zend_Gdata_YouTube_VideoQuery Provides a fluent interface
 335      */
 336     public function setSafeSearch($value)
 337     {
 338         switch ($value) {
 339             case 'none':
 340                 $this->_params['safeSearch'] = 'none';
 341                 break;
 342             case 'moderate':
 343                 $this->_params['safeSearch'] = 'moderate';
 344                 break;
 345             case 'strict':
 346                 $this->_params['safeSearch'] = 'strict';
 347                 break;
 348             case null:
 349                 unset($this->_params['safeSearch']);
 350             default:
 351                 require_once 'Zend/Gdata/App/InvalidArgumentException.php';
 352                 throw new Zend_Gdata_App_InvalidArgumentException(
 353                     'The safeSearch parameter only supports the values '.
 354                     '\'none\', \'moderate\' or \'strict\'.');
 355         }
 356     }
 357
 358     /**
 359      * Return the value of the safeSearch parameter
 360      *
 361      * @return string|null The value of the safeSearch parameter if it has been
 362      *         set, null otherwise.
 363      */
 364     public function getSafeSearch()
 365     {
 366         if (array_key_exists('safeSearch', $this->_params)) {
 367             return $this->_params['safeSearch'];
 368         }
 369         return $this;
 370     }
 371
 372     /**
 373      * Set the value of the orderby parameter
 374      *
 375      * @param string $value
 376      * @return Zend_Gdata_YouTube_Query Provides a fluent interface
 377      */
 378     public function setOrderBy($value)
 379     {
 380         if ($value != null) {
 381             $this->_params['orderby'] = $value;
 382         } else {
 383             unset($this->_params['orderby']);
 384         }
 385         return $this;
 386     }
 387
 388     /**
 389      * Return the value of the format parameter
 390      *
 391      * @return string|null The value of format if it exists, null otherwise.
 392      */
 393     public function getFormat()
 394     {
 395         if (array_key_exists('format', $this->_params)) {
 396             return $this->_params['format'];
 397         } else {
 398             return null;
 399         }
 400     }
 401
 402     /**
 403      * Return the value of the video query that has been set
 404      *
 405      * @return string|null The value of the video query if it exists,
 406      *         null otherwise.
 407      */
 408     public function getVideoQuery()
 409     {
 410         if (array_key_exists('vq', $this->_params)) {
 411             return $this->_params['vq'];
 412         } else {
 413             return null;
 414         }
 415     }
 416
 417     /**
 418      * Return the value of the time parameter
 419      *
 420      * @return string|null The time parameter if it exists, null otherwise.
 421      */
 422     public function getTime()
 423     {
 424         if (array_key_exists('time', $this->_params)) {
 425             return $this->_params['time'];
 426         } else {
 427             return null;
 428         }
 429     }
 430
 431     /**
 432      * Return the value of the orderby parameter if it exists
 433      *
 434      * @return string|null The value of orderby if it exists, null otherwise.
 435      */
 436     public function getOrderBy()
 437     {
 438         if (array_key_exists('orderby', $this->_params)) {
 439             return $this->_params['orderby'];
 440         } else {
 441             return null;
 442         }
 443     }
 444
 445     /**
 446      * Generate the query string from the URL parameters, optionally modifying
 447      * them based on protocol version.
 448      *
 449      * @param integer $majorProtocolVersion The major protocol version
 450      * @param integer $minorProtocolVersion The minor protocol version
 451      * @throws Zend_Gdata_App_VersionException
 452      * @return string querystring
 453      */
 454     public function getQueryString($majorProtocolVersion = null,
 455         $minorProtocolVersion = null)
 456     {
 457         $queryArray = array();
 458
 459         foreach ($this->_params as $name => $value) {
 460             if (substr($name, 0, 1) == '_') {
 461                 continue;
 462             }
 463
 464             switch($name) {
 465                 case 'location-radius':
 466                     if ($majorProtocolVersion == 1) {
 467                         require_once 'Zend/Gdata/App/VersionException.php';
 468                         throw new Zend_Gdata_App_VersionException("The $name " .
 469                             "parameter is only supported in version 2.");
 470                     }
 471                     break;
 472
 473                 case 'racy':
 474                     if ($majorProtocolVersion == 2) {
 475                         require_once 'Zend/Gdata/App/VersionException.php';
 476                         throw new Zend_Gdata_App_VersionException("The $name " .
 477                             "parameter is not supported in version 2. " .
 478                             "Please use 'safeSearch'.");
 479                     }
 480                     break;
 481
 482                 case 'safeSearch':
 483                     if ($majorProtocolVersion == 1) {
 484                         require_once 'Zend/Gdata/App/VersionException.php';
 485                         throw new Zend_Gdata_App_VersionException("The $name " .
 486                             "parameter is only supported in version 2. " .
 487                             "Please use 'racy'.");
 488                     }
 489                     break;
 490
 491                 case 'uploader':
 492                     if ($majorProtocolVersion == 1) {
 493                         require_once 'Zend/Gdata/App/VersionException.php';
 494                         throw new Zend_Gdata_App_VersionException("The $name " .
 495                             "parameter is only supported in version 2.");
 496                     }
 497                     break;
 498
 499                 case 'vq':
 500                     if ($majorProtocolVersion == 2) {
 501                         $name = 'q';
 502                     }
 503                     break;
 504             }
 505
 506             $queryArray[] = urlencode($name) . '=' . urlencode($value);
 507
 508         }
 509         if (count($queryArray) > 0) {
 510             return '?' . implode('&', $queryArray);
 511         } else {
 512             return '';
 513         }
 514     }
 515
 516     /**
 517      * Returns the generated full query URL, optionally modifying it based on
 518      * the protocol version.
 519      *
 520      * @param integer $majorProtocolVersion The major protocol version
 521      * @param integer $minorProtocolVersion The minor protocol version
 522      * @return string The URL
 523      */
 524     public function getQueryUrl($majorProtocolVersion = null,
 525         $minorProtocolVersion = null)
 526     {
 527         if (isset($this->_url)) {
 528             $url = $this->_url;
 529         } else {
 530             $url = Zend_Gdata_YouTube::VIDEO_URI;
 531         }
 532         if ($this->getCategory() !== null) {
 533             $url .= '/-/' . $this->getCategory();
 534         }
 535         $url = $url . $this->getQueryString($majorProtocolVersion,
 536             $minorProtocolVersion);
 537         return $url;
 538     }
 539
 540 }