documentation/manual/en/module_specs/Zend_Gdata_YouTube.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.gdata.youtube">
   4     <title>Using the YouTube Data API</title>
   5
   6     <para>
   7         The YouTube Data <acronym>API</acronym> offers read and write access to YouTube's content.
   8         Users can perform unauthenticated requests to Google Data feeds to
   9         retrieve feeds of popular videos, comments, public information about
  10         YouTube user profiles, user playlists, favorites, subscriptions and so on.
  11     </para>
  12
  13     <para>
  14         For more information on the YouTube Data <acronym>API</acronym>, please refer
  15         to the official <ulink
  16             url="http://code.google.com/apis/youtube/developers_guide_php.html"><acronym>PHP</acronym>
  17             Developer's Guide</ulink> on code.google.com.
  18     </para>
  19
  20     <sect2 id="zend.gdata.youtube.authentication">
  21         <title>Authentication</title>
  22
  23         <para>
  24             The YouTube Data <acronym>API</acronym> allows read-only access to public data, which
  25             does not require authentication. For any write requests, a user
  26             needs to authenticate either using ClientLogin or AuthSub authentication. Please refer
  27             to the <ulink
  28                 url="http://code.google.com/apis/youtube/developers_guide_php.html#Authentication">Authentication
  29                 section in the <acronym>PHP</acronym> Developer's Guide</ulink> for more detail.
  30         </para>
  31     </sect2>
  32
  33     <sect2 id="zend.gdata.youtube.developer_key">
  34         <title>Developer Keys and Client ID</title>
  35
  36         <para>
  37             A developer key identifies the YouTube developer that is submitting
  38             an <acronym>API</acronym> request. A client ID identifies your application for logging
  39             and debugging purposes. Please visit <ulink
  40                 url="http://code.google.com/apis/youtube/dashboard/">http://code.google.com/apis/youtube/dashboard/</ulink>
  41             to obtain a developer key and client ID. The example below demonstrates how to pass the
  42             developer key and client ID to the <ulink
  43                 url="http://framework.zend.com/apidoc/core/Zend_Gdata/Zend_Gdata_YouTube.html">Zend_Gdata_YouTube</ulink>
  44             service object.
  45         </para>
  46
  47         <example id="zend.gdata.youtube.developer_key.example">
  48             <title>Passing a Developer Key and ClientID to Zend_Gdata_YouTube</title>
  49
  50             <programlisting language="php"><![CDATA[
  51 $yt = new Zend_Gdata_YouTube($httpClient,
  52                              $applicationId,
  53                              $clientId,
  54                              $developerKey);
  55 ]]></programlisting>
  56         </example>
  57     </sect2>
  58
  59     <sect2 id="zend.gdata.youtube.videos">
  60         <title>Retrieving public video feeds</title>
  61
  62         <para>
  63             The YouTube Data <acronym>API</acronym> provides numerous feeds that return a list of
  64             videos, such as standard feeds, related videos, video responses,
  65             user's uploads, and user's favorites. For example, the
  66             user's uploads feed returns all videos uploaded by a specific user. See the <ulink
  67                 url="http://code.google.com/apis/youtube/reference.html#Video_Feeds">YouTube
  68                 <acronym>API</acronym> reference guide</ulink> for a detailed list of available
  69             feeds.
  70         </para>
  71
  72         <sect3 id="zend.gdata.youtube.videos.searching">
  73             <title>Searching for videos by metadata</title>
  74
  75             <para>
  76                 You can retrieve a list of videos that match specified
  77                 search criteria, using the YouTubeQuery class. The following query
  78                 looks for videos which contain the word "cat" in their
  79                 metadata, starting with the 10th video and displaying 20
  80                 videos per page, ordered by the view count.
  81             </para>
  82
  83             <example id="zend.gdata.youtube.videos.searching.example">
  84                 <title>Searching for videos</title>
  85
  86                 <programlisting language="php"><![CDATA[
  87 $yt = new Zend_Gdata_YouTube();
  88 $query = $yt->newVideoQuery();
  89 $query->videoQuery = 'cat';
  90 $query->startIndex = 10;
  91 $query->maxResults = 20;
  92 $query->orderBy = 'viewCount';
  93
  94 echo $query->queryUrl . "\n";
  95 $videoFeed = $yt->getVideoFeed($query);
  96
  97 foreach ($videoFeed as $videoEntry) {
  98     echo "---------VIDEO----------\n";
  99     echo "Title: " . $videoEntry->getVideoTitle() . "\n";
 100     echo "\nDescription:\n";
 101     echo $videoEntry->getVideoDescription();
 102     echo "\n\n\n";
 103 }
 104 ]]></programlisting>
 105             </example>
 106
 107             <para>
 108                 For more details on the different query parameters, please refer to the <ulink
 109                     url="http://code.google.com/apis/youtube/reference.html#Searching_for_videos">
 110                     Reference Guide</ulink>. The available helper functions in <ulink
 111                     url="http://framework.zend.com/apidoc/core/Zend_Gdata/Zend_Gdata_YouTube_VideoQuery.html"><classname>Zend_Gdata_YouTube_VideoQuery</classname></ulink>
 112                 for each of these parameters are described in more detail in the <ulink
 113                     url="http://code.google.com/apis/youtube/developers_guide_php.html#SearchingVideos">PHP
 114                     Developer's Guide</ulink>.
 115             </para>
 116         </sect3>
 117
 118         <sect3 id="zend.gdata.youtube.videos.searchingcategories">
 119             <title>Searching for videos by categories and tags/keywords</title>
 120
 121             <para>
 122                 Searching for videos in specific categories is done by generating a <ulink
 123                     url="http://code.google.com/apis/youtube/reference.html#Category_search">specially
 124                     formatted <acronym>URL</acronym></ulink>. For example, to search for
 125                 comedy videos which contain the keyword dog:
 126             </para>
 127
 128             <example id="zend.gdata.youtube.videos.searchingcategories.example">
 129                 <title>Searching for videos in specific categories</title>
 130
 131                 <programlisting language="php"><![CDATA[
 132 $yt = new Zend_Gdata_YouTube();
 133 $query = $yt->newVideoQuery();
 134 $query->category = 'Comedy/dog';
 135
 136 echo $query->queryUrl . "\n";
 137 $videoFeed = $yt->getVideoFeed($query);
 138 ]]></programlisting>
 139             </example>
 140         </sect3>
 141
 142         <sect3 id="zend.gdata.youtube.videos.standard">
 143             <title>Retrieving standard feeds</title>
 144
 145             <para>
 146                 The YouTube Data <acronym>API</acronym> has a number of <ulink
 147                     url="http://code.google.com/apis/youtube/reference.html#Standard_feeds">standard
 148                     feeds</ulink>. These standard feeds can be retrieved as <ulink
 149                     url="http://framework.zend.com/apidoc/core/Zend_Gdata/Zend_Gdata_YouTube_VideoFeed.html">Zend_Gdata_YouTube_VideoFeed</ulink>
 150                 objects using the specified <acronym>URL</acronym>s, using the predefined constants
 151                 within the <ulink
 152                     url="http://framework.zend.com/apidoc/core/Zend_Gdata/Zend_Gdata_YouTube.html">Zend_Gdata_YouTube</ulink>
 153                 class (Zend_Gdata_YouTube::STANDARD_TOP_RATED_URI for example) or
 154                 using the predefined helper methods (see code listing below).
 155             </para>
 156
 157             <para>
 158                 To retrieve the top rated videos using the helper method:
 159             </para>
 160
 161             <example id="zend.gdata.youtube.videos.standard.example-1">
 162                 <title>Retrieving a standard video feed</title>
 163
 164                 <programlisting language="php"><![CDATA[
 165 $yt = new Zend_Gdata_YouTube();
 166 $videoFeed = $yt->getTopRatedVideoFeed();
 167 ]]></programlisting>
 168             </example>
 169
 170             <para>
 171                 There are also query parameters to specify the time period
 172                 over which the standard feed is computed.
 173             </para>
 174
 175             <para>
 176                 For example, to retrieve the top rated videos for today:
 177             </para>
 178
 179             <example id="zend.gdata.youtube.videos.standard.example-2">
 180                 <title>Using a Zend_Gdata_YouTube_VideoQuery to Retrieve Videos</title>
 181
 182                 <programlisting language="php"><![CDATA[
 183 $yt = new Zend_Gdata_YouTube();
 184 $query = $yt->newVideoQuery();
 185 $query->setTime('today');
 186 $videoFeed = $yt->getTopRatedVideoFeed($query);
 187 ]]></programlisting>
 188             </example>
 189
 190             <para>
 191                 Alternatively, you could just retrieve the feed using the
 192                 <acronym>URL</acronym>:
 193             </para>
 194
 195             <example id="zend.gdata.youtube.videos.standard.example-3">
 196                 <title>Retrieving a video feed by URL</title>
 197
 198                 <programlisting language="php"><![CDATA[
 199 $yt = new Zend_Gdata_YouTube();
 200 $url = 'http://gdata.youtube.com/feeds/standardfeeds/top_rated?time=today'
 201 $videoFeed = $yt->getVideoFeed($url);
 202 ]]></programlisting>
 203             </example>
 204         </sect3>
 205
 206         <sect3 id="zend.gdata.youtube.videos.user">
 207             <title>Retrieving videos uploaded by a user</title>
 208
 209             <para>
 210                 You can retrieve a list of videos uploaded by a particular user
 211                 using a simple helper method. This example retrieves videos
 212                 uploaded by the user 'liz'.
 213             </para>
 214
 215             <example id="zend.gdata.youtube.videos.user.example">
 216                 <title>Retrieving videos uploaded by a specific user</title>
 217
 218                 <programlisting language="php"><![CDATA[
 219 $yt = new Zend_Gdata_YouTube();
 220 $videoFeed = $yt->getUserUploads('liz');
 221 ]]></programlisting>
 222             </example>
 223         </sect3>
 224
 225         <sect3 id="zend.gdata.youtube.videos.favorites">
 226             <title>Retrieving videos favorited by a user</title>
 227
 228             <para>
 229                 You can retrieve a list of a user's favorite videos
 230                 using a simple helper method. This example retrieves videos
 231                 favorited by the user 'liz'.
 232             </para>
 233
 234             <example id="zend.gdata.youtube.videos.favorites.example">
 235                 <title>Retrieving a user's favorite videos</title>
 236
 237                 <programlisting language="php"><![CDATA[
 238 $yt = new Zend_Gdata_YouTube();
 239 $videoFeed = $yt->getUserFavorites('liz');
 240 ]]></programlisting>
 241             </example>
 242         </sect3>
 243
 244         <sect3 id="zend.gdata.youtube.videos.responses">
 245             <title>Retrieving video responses for a video</title>
 246
 247             <para>
 248                 You can retrieve a list of a video's video responses
 249                 using a simple helper method. This example retrieves video
 250                 response for a video with the ID 'abc123813abc'.
 251             </para>
 252
 253             <example id="zend.gdata.youtube.videos.responses.example">
 254                 <title>Retrieving a feed of video responses</title>
 255
 256                 <programlisting language="php"><![CDATA[
 257 $yt = new Zend_Gdata_YouTube();
 258 $videoFeed = $yt->getVideoResponseFeed('abc123813abc');
 259 ]]></programlisting>
 260             </example>
 261         </sect3>
 262     </sect2>
 263
 264     <sect2 id="zend.gdata.youtube.comments">
 265         <title>Retrieving video comments</title>
 266
 267         <para>
 268             The comments for each YouTube video can be retrieved in
 269             several ways. To retrieve the comments for the video with
 270             the ID 'abc123813abc', use the following code:
 271         </para>
 272
 273         <example id="zend.gdata.youtube.videos.comments.example-1">
 274             <title>Retrieving a feed of video comments from a video ID</title>
 275
 276             <programlisting language="php"><![CDATA[
 277 $yt = new Zend_Gdata_YouTube();
 278 $commentFeed = $yt->getVideoCommentFeed('abc123813abc');
 279
 280 foreach ($commentFeed as $commentEntry) {
 281     echo $commentEntry->title->text . "\n";
 282     echo $commentEntry->content->text . "\n\n\n";
 283 }
 284 ]]></programlisting>
 285         </example>
 286
 287         <para>
 288             Comments can also be retrieved for a video if you have a copy of the <ulink
 289                 url="http://framework.zend.com/apidoc/core/Zend_Gdata/Zend_Gdata_YouTube_VideoEntry.html">Zend_Gdata_YouTube_VideoEntry</ulink>
 290             object:
 291         </para>
 292
 293         <example id="zend.gdata.youtube.videos.comments.example-2">
 294             <title>Retrieving a Feed of Video Comments from a Zend_Gdata_YouTube_VideoEntry</title>
 295
 296             <programlisting language="php"><![CDATA[
 297 $yt = new Zend_Gdata_YouTube();
 298 $videoEntry = $yt->getVideoEntry('abc123813abc');
 299 // we don't know the video ID in this example, but we do have the URL
 300 $commentFeed = $yt->getVideoCommentFeed(null,
 301                                         $videoEntry->comments->href);
 302 ]]></programlisting>
 303         </example>
 304     </sect2>
 305
 306     <sect2 id="zend.gdata.youtube.playlists">
 307         <title>Retrieving playlist feeds</title>
 308
 309         <para>
 310           The YouTube Data <acronym>API</acronym> provides information about users, including
 311             profiles, playlists, subscriptions, and more.
 312         </para>
 313
 314         <sect3 id="zend.gdata.youtube.playlists.user">
 315             <title>Retrieving the playlists of a user</title>
 316
 317             <para>
 318                 The library provides a helper method to retrieve
 319                 the playlists associated with a given user. To retrieve the
 320                 playlists for the user 'liz':
 321             </para>
 322
 323             <example id="zend.gdata.youtube.playlists.user.example">
 324                 <title>Retrieving the playlists of a user</title>
 325
 326                 <programlisting language="php"><![CDATA[
 327 $yt = new Zend_Gdata_YouTube();
 328 $playlistListFeed = $yt->getPlaylistListFeed('liz');
 329
 330 foreach ($playlistListFeed as $playlistEntry) {
 331     echo $playlistEntry->title->text . "\n";
 332     echo $playlistEntry->description->text . "\n";
 333     echo $playlistEntry->getPlaylistVideoFeedUrl() . "\n\n\n";
 334 }
 335 ]]></programlisting>
 336             </example>
 337         </sect3>
 338
 339         <sect3 id="zend.gdata.youtube.playlists.special">
 340             <title>Retrieving a specific playlist</title>
 341
 342             <para>
 343                 The library provides a helper method to retrieve
 344                 the videos associated with a given playlist. To retrieve the
 345                 playlists for a specific playlist entry:
 346             </para>
 347
 348             <example id="zend.gdata.youtube.playlists.special.example">
 349                 <title>Retrieving a specific playlist</title>
 350
 351                 <programlisting language="php"><![CDATA[
 352 $feedUrl = $playlistEntry->getPlaylistVideoFeedUrl();
 353 $playlistVideoFeed = $yt->getPlaylistVideoFeed($feedUrl);
 354 ]]></programlisting>
 355             </example>
 356         </sect3>
 357     </sect2>
 358
 359     <sect2 id="zend.gdata.youtube.subscriptions">
 360         <title>Retrieving a list of a user's subscriptions</title>
 361
 362         <para>
 363             A user can have several types of subscriptions: channel
 364             subscription, tag subscription, or favorites subscription. A <ulink
 365                 url="http://framework.zend.com/apidoc/core/Zend_Gdata/Zend_Gdata_YouTube_SubscriptionEntry.html">Zend_Gdata_YouTube_SubscriptionEntry</ulink>
 366             is used to represent individual subscriptions.
 367         </para>
 368
 369         <para>
 370             To retrieve all subscriptions for the user 'liz':
 371         </para>
 372
 373         <example id="zend.gdata.youtube.subscriptions.example">
 374             <title>Retrieving all subscriptions for a user</title>
 375
 376             <programlisting language="php"><![CDATA[
 377 $yt = new Zend_Gdata_YouTube();
 378 $subscriptionFeed = $yt->getSubscriptionFeed('liz');
 379
 380 foreach ($subscriptionFeed as $subscriptionEntry) {
 381     echo $subscriptionEntry->title->text . "\n";
 382 }
 383 ]]></programlisting>
 384         </example>
 385     </sect2>
 386
 387     <sect2 id="zend.gdata.youtube.profile">
 388         <title>Retrieving a user's profile</title>
 389
 390         <para>
 391             You can retrieve the public profile information
 392             for any YouTube user. To retrieve the profile
 393             for the user 'liz':
 394         </para>
 395
 396         <example id="zend.gdata.youtube.profile.example">
 397             <title>Retrieving a user's profile</title>
 398
 399             <programlisting language="php"><![CDATA[
 400 $yt = new Zend_Gdata_YouTube();
 401 $userProfile = $yt->getUserProfile('liz');
 402 echo "username: " . $userProfile->username->text . "\n";
 403 echo "age: " . $userProfile->age->text . "\n";
 404 echo "hometown: " . $userProfile->hometown->text . "\n";
 405 ]]></programlisting>
 406         </example>
 407     </sect2>
 408
 409     <sect2 id="zend.gdata.youtube.uploads">
 410         <title>Uploading Videos to YouTube</title>
 411
 412         <para>
 413             Please make sure to review the diagrams in the <ulink
 414                 url="http://code.google.com/apis/youtube/developers_guide_protocol.html#Process_Flows_for_Uploading_Videos">protocol
 415                 guide</ulink> on code.google.com for a high-level
 416             overview of the upload process. Uploading videos can be done in one of
 417             two ways: either by uploading the video directly or by sending just the
 418             video meta-data and having a user upload the video through an HTML form.
 419         </para>
 420
 421         <para>
 422             In order to upload a video directly, you must first construct a new <ulink
 423                 url="http://framework.zend.com/apidoc/core/Zend_Gdata/Zend_Gdata_YouTube_VideoEntry.html">Zend_Gdata_YouTube_VideoEntry</ulink>
 424             object and specify some required meta-data. The following example shows uploading the
 425             Quicktime video "mytestmovie.mov" to YouTube with the following properties:
 426         </para>
 427
 428         <table id="zend.gdata.youtube.uploads.metadata">
 429             <title>Metadata used in the code-sample below</title>
 430
 431             <tgroup cols="2" align="left" colsep="1" rowsep="1">
 432                 <thead>
 433                     <row>
 434                         <entry>Property</entry>
 435                         <entry>Value</entry>
 436                     </row>
 437                 </thead>
 438
 439                 <tbody>
 440                     <row>
 441                         <entry>Title</entry>
 442                         <entry>My Test Movie</entry>
 443                     </row>
 444
 445                     <row>
 446                         <entry>Category</entry>
 447                         <entry>Autos</entry>
 448                     </row>
 449
 450                     <row>
 451                         <entry>Keywords</entry>
 452                         <entry>cars, funny</entry>
 453                     </row>
 454
 455                     <row>
 456                         <entry>Description</entry>
 457                         <entry>My description</entry>
 458                     </row>
 459
 460                     <row>
 461                         <entry>Filename</entry>
 462                         <entry>mytestmovie.mov</entry>
 463                     </row>
 464
 465                     <row>
 466                         <entry>File <acronym>MIME</acronym> type</entry>
 467                         <entry>video/quicktime</entry>
 468                     </row>
 469
 470                     <row>
 471                         <entry>Video private?</entry>
 472                         <entry><constant>FALSE</constant></entry>
 473                     </row>
 474
 475                     <row>
 476                         <entry>Video location</entry>
 477                         <entry>37, -122 (lat, long)</entry>
 478                     </row>
 479
 480                     <row>
 481                         <entry>Developer Tags</entry>
 482                         <entry>mydevelopertag, anotherdevelopertag</entry>
 483                     </row>
 484                 </tbody>
 485             </tgroup>
 486         </table>
 487
 488         <para>
 489             The code below creates a blank <ulink
 490                 url="http://framework.zend.com/apidoc/core/Zend_Gdata/Zend_Gdata_YouTube_VideoEntry.html">Zend_Gdata_YouTube_VideoEntry</ulink>
 491             to be uploaded. A <ulink
 492                 url="http://framework.zend.com/apidoc/core/Zend_Gdata/Zend_Gdata_App_MediaFileSource.html">Zend_Gdata_App_MediaFileSource</ulink>
 493             object is then used to hold the actual video file. Under the hood, the <ulink
 494                 url="http://framework.zend.com/apidoc/core/Zend_Gdata/Zend_Gdata_YouTube_Extension_MediaGroup.html">Zend_Gdata_YouTube_Extension_MediaGroup</ulink>
 495             object is used to hold all of the video's meta-data. Our helper methods detailed below
 496             allow you to just set the video meta-data without having to worry about the media group
 497             object. The $uploadUrl is the location where the new entry gets posted to.
 498             This can be specified either with the $userName of the
 499             currently authenticated user, or, alternatively, you can simply use the
 500             string 'default' to refer to the currently authenticated user.
 501         </para>
 502
 503         <example id="zend.gdata.youtube.uploads.example">
 504             <title>Uploading a video</title>
 505
 506             <programlisting language="php"><![CDATA[
 507 $yt = new Zend_Gdata_YouTube($httpClient);
 508 $myVideoEntry = new Zend_Gdata_YouTube_VideoEntry();
 509
 510 $filesource = $yt->newMediaFileSource('mytestmovie.mov');
 511 $filesource->setContentType('video/quicktime');
 512 $filesource->setSlug('mytestmovie.mov');
 513
 514 $myVideoEntry->setMediaSource($filesource);
 515
 516 $myVideoEntry->setVideoTitle('My Test Movie');
 517 $myVideoEntry->setVideoDescription('My Test Movie');
 518 // Note that category must be a valid YouTube category !
 519 $myVideoEntry->setVideoCategory('Comedy');
 520
 521 // Set keywords, note that this must be a comma separated string
 522 // and that each keyword cannot contain whitespace
 523 $myVideoEntry->SetVideoTags('cars, funny');
 524
 525 // Optionally set some developer tags
 526 $myVideoEntry->setVideoDeveloperTags(array('mydevelopertag',
 527                                            'anotherdevelopertag'));
 528
 529 // Optionally set the video's location
 530 $yt->registerPackage('Zend_Gdata_Geo');
 531 $yt->registerPackage('Zend_Gdata_Geo_Extension');
 532 $where = $yt->newGeoRssWhere();
 533 $position = $yt->newGmlPos('37.0 -122.0');
 534 $where->point = $yt->newGmlPoint($position);
 535 $myVideoEntry->setWhere($where);
 536
 537 // Upload URI for the currently authenticated user
 538 $uploadUrl =
 539     'http://uploads.gdata.youtube.com/feeds/users/default/uploads';
 540
 541 // Try to upload the video, catching a Zend_Gdata_App_HttpException
 542 // if availableor just a regular Zend_Gdata_App_Exception
 543
 544 try {
 545     $newEntry = $yt->insertEntry($myVideoEntry,
 546                                  $uploadUrl,
 547                                  'Zend_Gdata_YouTube_VideoEntry');
 548 } catch (Zend_Gdata_App_HttpException $httpException) {
 549     echo $httpException->getRawResponseBody();
 550 } catch (Zend_Gdata_App_Exception $e) {
 551     echo $e->getMessage();
 552 }
 553 ]]></programlisting>
 554         </example>
 555
 556         <para>
 557             To upload a video as private, simply use: $myVideoEntry->setVideoPrivate(); prior to
 558             performing the upload. $videoEntry->isVideoPrivate() can be used to check whether a
 559             video entry is private or not.
 560         </para>
 561     </sect2>
 562
 563     <sect2 id="zend.gdata.youtube.uploads.browser">
 564         <title>Browser-based upload</title>
 565
 566         <para>
 567             Browser-based uploading is performed almost identically to direct uploading,
 568             except that you do not attach a <ulink
 569                 url="http://framework.zend.com/apidoc/core/Zend_Gdata/Zend_Gdata_App_MediaFileSource.html">Zend_Gdata_App_MediaFileSource</ulink>
 570             object to the <ulink
 571                 url="http://framework.zend.com/apidoc/core/Zend_Gdata/Zend_Gdata_YouTube_VideoEntry.html">Zend_Gdata_YouTube_VideoEntry</ulink>
 572             you are constructing. Instead you simply submit all of your video's meta-data to receive
 573             back a token element which can be used to construct an HTML upload form.
 574         </para>
 575
 576         <example id="zend.gdata.youtube.uploads.browser.example-1">
 577             <title>Browser-based upload</title>
 578
 579             <programlisting language="php"><![CDATA[
 580 $yt = new Zend_Gdata_YouTube($httpClient);
 581
 582 $myVideoEntry= new Zend_Gdata_YouTube_VideoEntry();
 583 $myVideoEntry->setVideoTitle('My Test Movie');
 584 $myVideoEntry->setVideoDescription('My Test Movie');
 585
 586 // Note that category must be a valid YouTube category
 587 $myVideoEntry->setVideoCategory('Comedy');
 588 $myVideoEntry->SetVideoTags('cars, funny');
 589
 590 $tokenHandlerUrl = 'http://gdata.youtube.com/action/GetUploadToken';
 591 $tokenArray = $yt->getFormUploadToken($myVideoEntry, $tokenHandlerUrl);
 592 $tokenValue = $tokenArray['token'];
 593 $postUrl = $tokenArray['url'];
 594 ]]></programlisting>
 595         </example>
 596
 597         <para>
 598             The above code prints out a link and a token that is used to construct an
 599             HTML form to display in the user's browser. A simple example form is shown
 600             below with $tokenValue representing the content of the returned token element,
 601             as shown being retrieved from $myVideoEntry above. In order for the user
 602             to be redirected to your website after submitting the form, make sure to
 603             append a $nextUrl parameter to the $postUrl above, which functions in the
 604             same way as the $next parameter of an AuthSub link. The only difference is
 605             that here, instead of a single-use token, a status and an id variable are
 606             returned in the <acronym>URL</acronym>.
 607         </para>
 608
 609         <example id="zend.gdata.youtube.uploads.browser.example-2">
 610             <title>Browser-based upload: Creating the HTML form</title>
 611
 612             <programlisting language="php"><![CDATA[
 613 // place to redirect user after upload
 614 $nextUrl = 'http://mysite.com/youtube_uploads';
 615
 616 $form = '<form action="'. $postUrl .'?nexturl='. $nextUrl .
 617         '" method="post" enctype="multipart/form-data">'.
 618         '<input name="file" type="file"/>'.
 619         '<input name="token" type="hidden" value="'. $tokenValue .'"/>'.
 620         '<input value="Upload Video File" type="submit" />'.
 621         '</form>';
 622 ]]></programlisting>
 623         </example>
 624     </sect2>
 625
 626     <sect2 id="zend.gdata.youtube.uploads.status">
 627         <title>Checking upload status</title>
 628
 629         <para>
 630             After uploading a video, it will immediately be visible in an
 631             authenticated user's uploads feed. However, it will not be public on
 632             the site until it has been processed. Videos that have been rejected or
 633             failed to upload successfully will also only be in the authenticated
 634             user's uploads feed. The following code checks the status of a <ulink
 635                 url="http://framework.zend.com/apidoc/core/Zend_Gdata/Zend_Gdata_YouTube_VideoEntry.html">Zend_Gdata_YouTube_VideoEntry</ulink>
 636             to see if it is not live yet or if it has been rejected.
 637         </para>
 638
 639         <example id="zend.gdata.youtube.uploads.status.example">
 640             <title>Checking video upload status</title>
 641
 642             <programlisting language="php"><![CDATA[
 643 try {
 644     $control = $videoEntry->getControl();
 645 } catch (Zend_Gdata_App_Exception $e) {
 646     echo $e->getMessage();
 647 }
 648
 649 if ($control instanceof Zend_Gdata_App_Extension_Control) {
 650     if ($control->getDraft() != null &&
 651         $control->getDraft()->getText() == 'yes') {
 652         $state = $videoEntry->getVideoState();
 653
 654         if ($state instanceof Zend_Gdata_YouTube_Extension_State) {
 655             print 'Upload status: '
 656                   . $state->getName()
 657                   .' '. $state->getText();
 658         } else {
 659             print 'Not able to retrieve the video status information'
 660                   .' yet. ' . "Please try again shortly.\n";
 661         }
 662     }
 663 }
 664 ]]></programlisting>
 665         </example>
 666     </sect2>
 667
 668     <sect2 id="zend.gdata.youtube.other">
 669         <title>Other Functions</title>
 670
 671         <para>
 672             In addition to the functionality described above, the YouTube <acronym>API</acronym>
 673             contains many other functions that allow you to modify video meta-data,
 674             delete video entries and use the full range of community features on the site. Some of
 675             the community features that can be modified through the <acronym>API</acronym> include:
 676             ratings, comments, playlists, subscriptions, user profiles, contacts and messages.
 677         </para>
 678         <para>
 679             Please refer to the full documentation available in the <ulink
 680                 url="http://code.google.com/apis/youtube/developers_guide_php.html">PHP Developer's
 681                 Guide</ulink> on code.google.com.
 682         </para>
 683     </sect2>
 684 </sect1>