Source for file Track.php

Documentation is available at Track.php

  1. <?
  2.  
  3. /** Represents a track and provides different methods to query track information.
  4.  *
  5.  * @package    php-lastfm-api
  6.  * @author  Felix Bruns <felixbruns@web.de>
  7.  * @version    1.0
  8.  */
  9. class Track extends Media {
  10.     /** The artist of this track.
  11.      *
  12.      * @var mixed 
  13.      * @access    private
  14.      */
  15.     private $artist;
  16.  
  17.     /** The album of this track.
  18.      *
  19.      * @var mixed 
  20.      * @access    private
  21.      */
  22.     private $album;
  23.  
  24.     /** The tracks duration.
  25.      *
  26.      * @var integer 
  27.      * @access    private
  28.      */
  29.     private $duration;
  30.  
  31.     /** The tracks top tags.
  32.      *
  33.      * @var array 
  34.      * @access    private
  35.      */
  36.     private $topTags;
  37.  
  38.     /** The tracks id.
  39.      *
  40.      * @var integer 
  41.      * @access    private
  42.      */
  43.     private $id;
  44.  
  45.     /** The tracks location.
  46.      *
  47.      * @var string 
  48.      * @access    private
  49.      */
  50.     private $location;
  51.  
  52.     /** Indicates if this track is streamable.
  53.      *
  54.      * @var boolean 
  55.      * @access    private
  56.      */
  57.     private $streamable;
  58.  
  59.     /** Indicates if this track is a full streamable track.
  60.      *
  61.      * @var boolean 
  62.      * @access    private
  63.      */
  64.     private $fullTrack;
  65.  
  66.     /** The tracks wiki information.
  67.      *
  68.      * @var string 
  69.      * @access    private
  70.      */
  71.     private $wiki;
  72.  
  73.     /** The unix timestamp indicating when this track was last played.
  74.      *
  75.      * @var string 
  76.      * @access    private
  77.      */
  78.     private $lastPlayed;
  79.  
  80.     /** Create an album object.
  81.      *
  82.      * @param mixed        $artist        An artist object or string.
  83.      * @param mixed        $album        An album object or string.
  84.      * @param string    $name        Name of this track.
  85.      * @param string    $mbid        MusicBrainz ID of this track.
  86.      * @param string    $url        Last.fm URL of this track.
  87.      * @param array        $images        An array of cover art images of different sizes.
  88.      * @param integer    $listeners    Number of listeners of this track.
  89.      * @param integer    $playCount    Play count of this album.
  90.      * @param integer    $duration    Duration of this track.
  91.      * @param array        $topTags    An array of top tags of this track.
  92.      * @param integer    $id            ID of this track.
  93.      * @param string    $location    Location of this track.
  94.      * @param boolean    $streamable    Track is streamable.
  95.      * @param boolean    $fullTrack    Track is a full streamable track.
  96.      * @param string    $wiki        Wiki data of this track.
  97.      * @param integer    $lastPlayed    When this track was last played.
  98.      *
  99.      * @access    public
  100.      */
  101.     public function __construct($artist, $album, $name, $mbid, $url,
  102.                                 array $images, $listeners, $playCount,
  103.                                 $duration, array $topTags, $id, $location,
  104.                                 $streamable, $fullTrack, $wiki, $lastPlayed){
  105.         parent::__construct($name, $mbid, $url, $images, $listeners, $playCount);
  106.  
  107.         $this->artist     = $artist;
  108.         $this->album      = $album;
  109.         $this->duration   = $duration;
  110.         $this->topTags    = $topTags;
  111.         $this->id         = $id;
  112.         $this->location   = $location;
  113.         $this->streamable = $streamable;
  114.         $this->fullTrack  = $fullTrack;
  115.         $this->wiki       = $wiki;
  116.         $this->lastPlayed = $lastPlayed;
  117.     }
  118.  
  119.     /** Returns the artist of this track.
  120.      *
  121.      * @return    mixed    An {@link de.felixbruns.lastfm.Artist Artist} object or the artists name.
  122.      * @access    public
  123.      */
  124.     public function getArtist(){
  125.         return $this->artist;
  126.     }
  127.  
  128.     /** Returns the album of this track.
  129.      *
  130.      * @return    mixed    An {@link de.felixbruns.lastfm.Album Album} object or the albums name.
  131.      * @access    public
  132.      */
  133.     public function getAlbum(){
  134.         return $this->album;
  135.     }
  136.  
  137.     /** Returns the duration of this track.
  138.      *
  139.      * @return    integer    The duration of this track.
  140.      * @access    public
  141.      */
  142.     public function getDuration(){
  143.         return $this->duration;
  144.     }
  145.  
  146.     /** Returns the tracks top tags.
  147.      *
  148.      * @return    array    An array of Tag objects.
  149.      * @access    public
  150.      * @see        getTopTags
  151.      */
  152.     public function getTrackTopTags(){
  153.         return $this->topTags;
  154.     }
  155.  
  156.     /** Returns the ID of this track.
  157.      *
  158.      * @return    integer    The ID of this track.
  159.      * @access    public
  160.      */
  161.     public function getId(){
  162.         return $this->id;
  163.     }
  164.  
  165.     /** Returns the location of this track.
  166.      *
  167.      * @return    string    The location of this track.
  168.      * @access    public
  169.      */
  170.     public function getLocation(){
  171.         return $this->location;
  172.     }
  173.  
  174.     /** Returns if this track is streamable.
  175.      *
  176.      * @return    boolean    A boolean.
  177.      * @access    public
  178.      */
  179.     public function isStreamable(){
  180.         return $this->streamable;
  181.     }
  182.  
  183.     /** Returns if this track is a full streamable track.
  184.      *
  185.      * @return    boolean    A boolean.
  186.      * @access    public
  187.      */
  188.     public function isFullTrack(){
  189.         return $this->fullTrack;
  190.     }
  191.  
  192.     /** Returns the wiki data of this track.
  193.      *
  194.      * @return    string    Wiki data.
  195.      * @access    public
  196.      */
  197.     public function getWiki(){
  198.         return $this->wiki;
  199.     }
  200.  
  201.     /** Returns the unix timestamp indication when this track was last played.
  202.      *
  203.      * @return    integer    A unix timestamp.
  204.      * @access    public
  205.      */
  206.     public function getLastPlayed(){
  207.         return $this->lastPlayed;
  208.     }
  209.  
  210.     /** Tag an album using a list of user supplied tags.
  211.      *
  212.      * @param    string    $artist        The artist name in question. (Required)
  213.      * @param    string    $track        The track name in question. (Required)
  214.      * @param    array    $tags        A comma delimited list of user supplied tags to apply to this track. Accepts a maximum of 10 tags. (Required)
  215.      * @param    Session    $session    A session obtained by {@link de.felixbruns.lastfm.Auth#getSession Auth::getSession} or {@link de.felixbruns.lastfm.Auth#getMobileSession Auth::getMobileSession}. (Required)
  216.      *
  217.      * @static
  218.      * @access    public
  219.      * @throws    Error
  220.      */
  221.     public static function addTags($artist, $track, array $tags, $session){
  222.         CallerFactory::getDefaultCaller()->signedCall('track.addTags', array(
  223.             'artist' => $artist,
  224.             'track'  => $track,
  225.             'tags'   => implode(',', $tags)
  226.         ), $session, 'POST');
  227.     
  228.  
  229.     /** Ban a track for a given user profile. This needs to be supplemented with a scrobbling submission containing the 'ban' rating (see the audioscrobbler API).
  230.      *
  231.      * @param    string    $artist        An artist name. (Required)
  232.      * @param    string    $track        A track name. (Required)
  233.      * @param    Session    $session        A session obtained by {@link de.felixbruns.lastfm.Auth#getSession Auth::getSession} or {@link de.felixbruns.lastfm.Auth#getMobileSession Auth::getMobileSession}. (Required)
  234.      *
  235.      * @static
  236.      * @access    public
  237.      * @throws    Error
  238.      */
  239.     public static function ban($artist, $track, $session){
  240.         CallerFactory::getDefaultCaller()->signedCall('track.ban', array(
  241.             'artist' => $artist,
  242.             'track'  => $track
  243.         ), $session, 'POST');
  244.     }
  245.  
  246.     /** Get the metadata for a track on last.fm using the artist/track name or a MusicBrainz id.
  247.      *
  248.      * @param    string    $artist    The artist name in question. (Optional)
  249.      * @param    string    $track    The track name in question. (Optional)
  250.      * @param    string    $mbid    The MusicBrainz ID for the track. (Optional)
  251.      * @return    array            A Track object.
  252.      *
  253.      * @static
  254.      * @access    public
  255.      * @throws    Error
  256.      */
  257.     public static function getInfo($artist, $track, $mbid = null){
  258.         $xml = CallerFactory::getDefaultCaller()->call('track.getInfo', array(
  259.             'artist' => $artist,
  260.             'track'  => $track,
  261.             'mbid'   => $mbid
  262.         ));
  263.  
  264.         return Track::fromSimpleXMLElement($xml);
  265.     }
  266.  
  267.     /** Get the similar tracks for this track on last.fm, based on listening data.
  268.      *
  269.      * @param    string    $artist    The artist name in question. (Optional)
  270.      * @param    string    $track    The track name in question. (Optional)
  271.      * @param    string    $mbid    The MusicBrainz ID for the track. (Optional)
  272.      * @return    array            An array of Track objects.
  273.      *
  274.      * @static
  275.      * @access    public
  276.      * @throws    Error
  277.      */
  278.     public static function getSimilar($artist, $track, $mbid = null){
  279.         $xml = CallerFactory::getDefaultCaller()->call('track.getSimilar', array(
  280.             'artist' => $artist,
  281.             'track'  => $track,
  282.             'mbid'   => $mbid
  283.         ));
  284.  
  285.         $tracks = array();
  286.  
  287.         foreach($xml->children() as $track){
  288.             $tracks[] = Track::fromSimpleXMLElement($track);
  289.         }
  290.  
  291.         return $tracks;
  292.     }
  293.  
  294.     /** Get the tags applied by an individual user to a track on last.fm.
  295.      *
  296.      * @param    string    $artist    The artist name in question. (Required)
  297.      * @param    string    $track    The track name in question. (Required)
  298.      * @param    Session    $session    A session obtained by {@link de.felixbruns.lastfm.Auth#getSession Auth::getSession} or {@link de.felixbruns.lastfm.Auth#getMobileSession Auth::getMobileSession}. (Required)
  299.      * @return    array            An array of Tag objects.
  300.      *
  301.      * @static
  302.      * @access    public
  303.      * @throws    Error
  304.      */
  305.     public static function getTags($artist, $track, $session){
  306.         $xml = CallerFactory::getDefaultCaller()->signedCall('track.getTags', array(
  307.             'artist'  => $artist,
  308.             'track'   => $track
  309.         ), $session);
  310.  
  311.         $tags = array();
  312.  
  313.         foreach($xml->children() as $tag){
  314.             $tags[] = Tag::fromSimpleXMLElement($tag);
  315.         }
  316.  
  317.         return $tags;
  318.     }
  319.  
  320.     /** Get the top fans for this track on last.fm, based on listening data. Supply either track & artist name or MusicBrainz id.
  321.      *
  322.      * @param    string    $artist    The artist name in question. (Optional)
  323.      * @param    string    $track    The track name in question. (Optional)
  324.      * @param    string    $mbid    The MusicBrainz ID for the track. (Optional)
  325.      * @return    array            An array of User objects.
  326.      *
  327.      * @static
  328.      * @access    public
  329.      * @throws    Error
  330.      */
  331.     public static function getTopFans($artist, $track, $mbid = null){
  332.         $xml = CallerFactory::getDefaultCaller()->call('track.getTopFans', array(
  333.             'artist' => $artist,
  334.             'track'  => $track,
  335.             'mbid'   => $mbid
  336.         ));
  337.  
  338.         $users = array();
  339.  
  340.         foreach($xml->children() as $user){
  341.             $users[] = User::fromSimpleXMLElement($user);
  342.         }
  343.  
  344.         return $users;
  345.     }
  346.  
  347.     /** Get the top tags for this track on last.fm, ordered by tag count. Supply either track & artist name or mbid.
  348.      *
  349.      * @param    string    $artist    The artist name in question. (Optional)
  350.      * @param    string    $track    The track name in question. (Optional)
  351.      * @param    string    $mbid    The MusicBrainz ID for the track. (Optional)
  352.      * @return    array            An array of Tag objects.
  353.      *
  354.      * @static
  355.      * @access    public
  356.      * @throws    Error
  357.      */
  358.     public static function getTopTags($artist, $track, $mbid = null){
  359.         $xml = CallerFactory::getDefaultCaller()->call('track.getTopTags', array(
  360.             'artist' => $artist,
  361.             'track'  => $track,
  362.             'mbid'   => $mbid
  363.         ));
  364.  
  365.         $tags = array();
  366.  
  367.         foreach($xml->children() as $tag){
  368.             $tags[] = Tag::fromSimpleXMLElement($tag);
  369.         }
  370.  
  371.         return $tags;
  372.     }
  373.  
  374.     /** Love a track for a user profile. This needs to be supplemented with a scrobbling submission containing the 'love' rating (see the audioscrobbler API).
  375.      *
  376.      * @param    string    $artist        An artist name. (Required)
  377.      * @param    string    $track        A track name. (Required)
  378.      * @param    Session    $session    A session obtained by {@link de.felixbruns.lastfm.Auth#getSession Auth::getSession} or {@link de.felixbruns.lastfm.Auth#getMobileSession Auth::getMobileSession}. (Required)
  379.      *
  380.      * @static
  381.      * @access    public
  382.      * @throws    Error
  383.      */
  384.     public static function love($artist, $track, $session){
  385.         $xml = CallerFactory::getDefaultCaller()->signedCall('track.love', array(
  386.             'artist' => $artist,
  387.             'track'  => $track
  388.         ), $session, 'POST');
  389.  
  390.         return $xml;
  391.     }
  392.  
  393.     /** Remove a user's tag from a track.
  394.      *
  395.      * @param    string    $artist        The artist name in question. (Required)
  396.      * @param    string    $track        The track name in question. (Required)
  397.      * @param    string    $tag        A single user tag to remove from this track. (Required)
  398.      * @param    Session    $session    A session obtained by {@link de.felixbruns.lastfm.Auth#getSession Auth::getSession} or {@link de.felixbruns.lastfm.Auth#getMobileSession Auth::getMobileSession}. (Required)
  399.      *
  400.      * @static
  401.      * @access    public
  402.      * @throws    Error
  403.      */
  404.     public static function removeTag($artist, $track, $tag, $session){
  405.         CallerFactory::getDefaultCaller()->signedCall('track.removeTag', array(
  406.             'artist' => $artist,
  407.             'track'  => $track,
  408.             'tag'    => $tag
  409.         ), $session, 'POST');
  410.     }
  411.  
  412.     /** Search for a track by track name. Returns track matches sorted by relevance.
  413.      *
  414.      * @param    string    $track    The track name in question. (Required)
  415.      * @param    string    $artist    Narrow your search by specifying an artist. (Optional)
  416.      * @param    integer    $limit    Limit the number of tracks returned at one time. Default (maximum) is 30. (Optional)
  417.      * @param    integer    $page    Scan into the results by specifying a page number. Defaults to first page. (Optional)
  418.      * @return    PaginatedResult    A PaginatedResult object.
  419.      *
  420.      * @static
  421.      * @access    public
  422.      * @throws    Error
  423.      */
  424.     public static function search($track, $artist = null, $limit = null, $page = null){
  425.         $xml = CallerFactory::getDefaultCaller()->call('track.search', array(
  426.             'artist' => $artist,
  427.             'track'  => $track,
  428.             'limit'  => $limit,
  429.             'page'   => $page
  430.         ));
  431.  
  432.         $tracks = array();
  433.  
  434.         foreach($xml->trackmatches->children() as $track){
  435.             $tracks[] = Track::fromSimpleXMLElement($track);
  436.         }
  437.  
  438.         $opensearch = $xml->children('http://a9.com/-/spec/opensearch/1.1/');
  439.  
  440.         return new PaginatedResult(
  441.             Util::toInteger($opensearch->totalResults),
  442.             Util::toInteger($opensearch->startIndex),
  443.             Util::toInteger($opensearch->itemsPerPage),
  444.             $tracks
  445.         );
  446.     }
  447.  
  448.     /** Share a track twith one or more last.fm users or other friends.
  449.      *
  450.      * @param    string    $artist        An artist name. (Required)
  451.      * @param    string    $track        A track name. (Required)
  452.      * @param    array    $recipients    A comma delimited list of email addresses or last.fm usernames. Maximum is 10. (Required)
  453.      * @param    string    $message    An optional message to send with the recommendation. If not supplied a default message will be used. (Optional)
  454.      * @param    Session    $session    A session obtained by {@link de.felixbruns.lastfm.Auth#getSession Auth::getSession} or {@link de.felixbruns.lastfm.Auth#getMobileSession Auth::getMobileSession}. (Required)
  455.      *
  456.      * @static
  457.      * @access    public
  458.      * @throws    Error
  459.      */
  460.     public static function share($artist, $track, array $recipients,
  461.                                  $message = null, $session){
  462.         CallerFactory::getDefaultCaller()->signedCall('track.share', array(
  463.             'artist'    => $artist,
  464.             'track'     => $track,
  465.             'recipient' => implode(',', $recipients),
  466.             'message'   => $message
  467.         ), $session, 'POST');
  468.     
  469.  
  470.     /** Get a track playlist for streaming. INOFFICIAL.
  471.      *
  472.      * @param    string    $artist    An artist name. (Required)
  473.      * @param    string    $track    A track name. (Required)
  474.      * @return    mixed            A Playlist object.
  475.      *
  476.      * @static
  477.      * @access    public
  478.      * @throws    Error
  479.      */
  480.     public static function getPlaylist($artist, $track){
  481.         $xml = CallerFactory::getDefaultCaller()->call('track.getPlayerMenu', array(
  482.             'artist' => $artist,
  483.             'track'  => $track
  484.         ));
  485.  
  486.         return Playlist::fetch(Util::toString($xml->playlist->url), true, true);
  487.     }
  488.  
  489.     /** Create a Track object from a SimpleXMLElement.
  490.      *
  491.      * @param    SimpleXMLElement    $xml    A SimpleXMLElement.
  492.      * @return    Track                        A Track object.
  493.      *
  494.      * @static
  495.      * @access    public
  496.      * @internal
  497.      */
  498.     public static function fromSimpleXMLElement(SimpleXMLElement $xml){
  499.         $images  = array();
  500.         $topTags = array();
  501.  
  502.         if(count($xml->image) > 1){
  503.             foreach($xml->image as $image){
  504.                 $images[Util::toImageType($image['size'])] = Util::toString($image);
  505.             }
  506.         }
  507.         else{
  508.             $images[Media::IMAGE_UNKNOWN] = Util::toString($xml->image);
  509.         }
  510.  
  511.         if($xml->toptags){
  512.             foreach($xml->toptags->children() as $tag){
  513.                 $topTags[] = Tag::fromSimpleXMLElement($tag);
  514.             }
  515.         }
  516.  
  517.         if($xml->artist){
  518.             if($xml->artist->name && $xml->artist->mbid && $xml->artist->url){
  519.                 $artist = new Artist(
  520.                     Util::toString($xml->artist->name),
  521.                     Util::toString($xml->artist->mbid),
  522.                     Util::toString($xml->artist->url),
  523.                     array(), 0, 0, 0, array(), array(), '', 0.0
  524.                 );
  525.             }
  526.             else{
  527.                 $artist = Util::toString($xml->artist);
  528.             }
  529.         }
  530.         else if($xml->creator){
  531.             $artist = Util::toString($xml->creator);
  532.         }
  533.         else{
  534.             $artist = '';
  535.         }
  536.  
  537.         if($xml->name){
  538.             $name = Util::toString($xml->name);
  539.         }
  540.         else if($xml->title){
  541.             $name = Util::toString($xml->title);
  542.         }
  543.         else{
  544.             $name = '';
  545.         }
  546.  
  547.         // TODO: <extension application="http://www.last.fm">
  548.  
  549.         return new Track(
  550.             $artist,
  551.             Util::toString($xml->album),
  552.             $name,
  553.             Util::toString($xml->mbid),
  554.             Util::toString($xml->url),
  555.             $images,
  556.             Util::toInteger($xml->listeners),
  557.             Util::toInteger($xml->playcount),
  558.             Util::toInteger($xml->duration),
  559.             $topTags,
  560.             Util::toInteger($xml->id),
  561.             Util::toString($xml->location),
  562.             Util::toBoolean($xml->streamable),
  563.             Util::toBoolean($xml->streamable['fulltrack']),
  564.             $xml->wiki, // TODO: Wiki object
  565.             Util::toTimestamp($xml->date)
  566.         );
  567.     }
  568. }
  569.  
  570. ?>

Documentation generated on Mon, 22 Dec 2008 16:57:48 +0100 by phpDocumentor 1.4.1