Source for file Album.php

Documentation is available at Album.php

  1. <?
  2.  
  3. /** Represents an album and provides different methods to query album information.
  4.  *
  5.  * @package    php-lastfm-api
  6.  * @author  Felix Bruns <felixbruns@web.de>
  7.  * @version    1.0
  8.  */
  9. class Album extends Media {
  10.     /** Artist of this album.
  11.      *
  12.      * @var        mixed 
  13.      * @access    private
  14.      */
  15.     private $artist;
  16.  
  17.     /** Album ID.
  18.      *
  19.      * @var        integer 
  20.      * @access    private
  21.      */
  22.     private $id;
  23.  
  24.     /** Album release date.
  25.      *
  26.      * @var        integer 
  27.      * @access    private
  28.      */
  29.     private $releaseDate;
  30.  
  31.     /** Album top tags.
  32.      *
  33.      * @var        array 
  34.      * @access    private
  35.      */
  36.     private $topTags;
  37.  
  38.     /** Create an album object.
  39.      *
  40.      * @param mixed        $artist            An artist object or string.
  41.      * @param string    $name            Name of this album.
  42.      * @param integer    $id                ID of this album.
  43.      * @param string    $mbid            MusicBrainz ID of this album.
  44.      * @param string    $url            Last.fm URL of this album.
  45.      * @param array        $images            An array of cover art images of different sizes.
  46.      * @param integer    $listeners        Number of listeners of this album.
  47.      * @param integer    $playCount        Play count of this album.
  48.      * @param integer    $releaseDate    Release date of this album.
  49.      * @param array        $topTags        An array of top tags of this album.
  50.      *
  51.      * @access    public
  52.      */
  53.     public function __construct($artist, $name, $id, $mbid, $url, array $images,
  54.                                 $listeners, $playCount, $releaseDate,
  55.                                 array $topTags){
  56.         parent::__construct($name, $mbid, $url, $images, $listeners, $playCount);
  57.  
  58.         $this->artist      = $artist;
  59.         $this->id          = $id;
  60.         $this->releaseDate = $releaseDate;
  61.         $this->topTags     = $topTags;
  62.     }
  63.  
  64.     /** Returns the artist of this album.
  65.      *
  66.      * @return    mixed    An {@link de.felixbruns.lastfm.Artist Artist} object or the artists name.
  67.      * @access    public
  68.      * @see        Artist
  69.      */
  70.     public function getArtist(){
  71.         return $this->artist;
  72.     }
  73.  
  74.     /** Returns the ID of this album.
  75.      *
  76.      * @return    integer    The ID of this album.
  77.      * @access    public
  78.      */
  79.     public function getId(){
  80.         return $this->id;
  81.     }
  82.  
  83.     /** Returns the release date of this album.
  84.      *
  85.      * @return    integer    Release date of this album as a unix timestamp.
  86.      * @access    public
  87.      */
  88.     public function getReleaseDate(){
  89.         return $this->releasedate;
  90.     }
  91.  
  92.     /** Returns the top tags of this album.
  93.      *
  94.      * @return    array    An array of {@link de.felixbruns.lastfm.Tag Tag} objects.
  95.      * @access    public
  96.      * @see        Tag
  97.      */
  98.     public function getTopTags(){
  99.         return $this->topTags;
  100.     }
  101.  
  102.     /** Tag an album using a list of user supplied tags.
  103.      *
  104.      * @param    string    $artist        The artist name in question. (Required)
  105.      * @param    string    $album        The album name in question. (Required)
  106.      * @param    array    $tags        An array of user supplied tags to apply to this album. Accepts a maximum of 10 tags. (Required)
  107.      * @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)
  108.      *
  109.      * @static
  110.      * @access    public
  111.      * @throws    Error
  112.      */
  113.     public static function addTags($artist, $album, array $tags,
  114.                                    Session $session){
  115.         CallerFactory::getDefaultCaller()->signedCall('album.addTags', array(
  116.             'artist' => $artist,
  117.             'album'  => $album,
  118.             'tags'   => implode(',', $tags)
  119.         ), $session, 'POST');
  120.     
  121.  
  122.     /** Get the metadata for an album on last.fm using the album name or a MusicBrainz ID. See playlist.fetch on how to get the album playlist.
  123.      *
  124.      * @param    string    $artist    The artist name in question. (Optional)
  125.      * @param    string    $album    The album name in question. (Optional)
  126.      * @param    string    $mbid    The MusicBrainz ID for the album. (Optional)
  127.      * @param    string    $lang    The language to return the biography in, expressed as an ISO 639 alpha-2 code. (Optional)
  128.      * @return    Album            An Album object.
  129.      *
  130.      * @static
  131.      * @access    public
  132.      * @throws    Error
  133.      */
  134.     public static function getInfo($artist, $album, $mbid = null, $lang = null){
  135.         $xml = CallerFactory::getDefaultCaller()->call('album.getInfo', array(
  136.             'artist' => $artist,
  137.             'album'  => $album,
  138.             'mbid'   => $mbid,
  139.             'lang'   => $lang
  140.         ));
  141.  
  142.         return Album::fromSimpleXMLElement($xml);
  143.     }
  144.  
  145.     /** Get the tags applied by an individual user to an album on last.fm.
  146.      *
  147.      * @param    string    $artist        The artist name in question. (Required)
  148.      * @param    string    $album        The album name in question. (Required)
  149.      * @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)
  150.      * @return    array                An array of Tag objects.
  151.      * @see        Tag
  152.      *
  153.      * @static
  154.      * @access    public
  155.      * @throws    Error
  156.      */
  157.     public static function getTags($artist, $album, Session $session){
  158.         $xml = CallerFactory::getDefaultCaller()->signedCall('album.getTags', array(
  159.             'artist' => $artist,
  160.             'album'  => $album
  161.         ), $session);
  162.  
  163.         $tags = array();
  164.  
  165.         foreach($xml->children() as $tag){
  166.             $tags[] = Tag::fromSimpleXMLElement($tag);
  167.         }
  168.  
  169.         return $tags;
  170.     }
  171.  
  172.     /** Remove a user's tag from an album.
  173.      *
  174.      * @param    string    $artist        The artist name in question. (Required)
  175.      * @param    string    $album        The album name in question. (Required)
  176.      * @param    string    $tag        A single user tag to remove from this album. (Required)
  177.      * @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)
  178.      *
  179.      * @static
  180.      * @access    public
  181.      * @throws    Error
  182.      */
  183.     public static function removeTag($artist, $album, $tag, Session $session){
  184.         CallerFactory::getDefaultCaller()->signedCall('album.removeTag', array(
  185.             'artist' => $artist,
  186.             'album'  => $album,
  187.             'tag'    => $tag
  188.         ), $session, 'POST');
  189.     }
  190.  
  191.     /** Search for an album by name. Returns album matches sorted by relevance.
  192.      *
  193.      * @param    string    $album    The album name in question. (Required)
  194.      * @param    integer    $limit    Limit the number of albums returned at one time. Default (maximum) is 30. (Optional)
  195.      * @param    integer    $page    Scan into the results by specifying a page number. Defaults to first page. (Optional)
  196.      * @return    PaginatedResult    A PaginatedResult object.
  197.      * @see        PaginatedResult
  198.      *
  199.      * @static
  200.      * @access    public
  201.      * @throws    Error
  202.      */
  203.     public static function search($album, $limit = null, $page = null){
  204.         $xml = CallerFactory::getDefaultCaller()->call('album.search', array(
  205.             'album' => $album,
  206.             'limit' => $limit,
  207.             'page'  => $page
  208.         ));
  209.  
  210.         $albums = array();
  211.  
  212.         foreach($xml->albummatches->children() as $album){
  213.             $artists[] = Album::fromSimpleXMLElement($album);
  214.         }
  215.  
  216.         $opensearch = $xml->children('http://a9.com/-/spec/opensearch/1.1/');
  217.  
  218.         return new PaginatedResult(
  219.             Util::toInteger($opensearch->totalResults),
  220.             Util::toInteger($opensearch->startIndex),
  221.             Util::toInteger($opensearch->itemsPerPage),
  222.             $artists
  223.         );
  224.     }
  225.  
  226.     /** Get an album playlist for streaming. INOFFICIAL.
  227.      *
  228.      * @param    string    $artist    The artist name in question. (Required)
  229.      * @param    string    $album    The album name in question. (Required)
  230.      * @return    Playlist        A Playlist object.
  231.      * @see        Playlist
  232.      *
  233.      * @static
  234.      * @access    public
  235.      * @throws    Error
  236.      */
  237.     public static function getPlaylist($artist, $album){
  238.         $xml = CallerFactory::getDefaultCaller()->call('album.getPlayerMenu', array(
  239.             'artist' => $artist,
  240.             'album'  => $album
  241.         ));
  242.  
  243.         return Playlist::fetch(Util::toString($xml->playlist->url), true, true);
  244.     }
  245.  
  246.     /** Create an Album object from a SimpleXMLElement object.
  247.      *
  248.      * @param    SimpleXMLElement    $xml    A SimpleXMLElement object.
  249.      * @return    Album                        An Album object.
  250.      *
  251.      * @static
  252.      * @access    public
  253.      * @internal
  254.      */
  255.     public static function fromSimpleXMLElement(SimpleXMLElement $xml){
  256.         $images  = array();
  257.         $topTags = array();
  258.  
  259.         /* TODO: tagcount | library.getAlbums */
  260.  
  261.         if($xml->mbid){
  262.             $mbid = Util::toString($xml->mbid);
  263.         }
  264.         else if($xml['mbid']){
  265.             $mbid = Util::toString($xml['mbid']);
  266.         }
  267.         else{
  268.             $mbid = '';
  269.         }
  270.  
  271.         foreach($xml->image as $image){
  272.             $images[Util::toImageType($image['size'])] = Util::toString($image);
  273.         }
  274.  
  275.         if($xml->toptags){
  276.             foreach($xml->toptags->children() as $tag){
  277.                 $topTags[] = Tag::fromSimpleXMLElement($tag);
  278.             }
  279.         }
  280.  
  281.         if($xml->artist->name && $xml->artist->mbid && $xml->artist->url){
  282.             $artist = new Artist(
  283.                 Util::toString($xml->artist->name),
  284.                 Util::toString($xml->artist->mbid),
  285.                 Util::toString($xml->artist->url),
  286.                 array(), 0, 0, 0, array(), array(), '', 0.0
  287.             );
  288.         }
  289.         if($xml->artist && $xml->artist['mbid']){
  290.             $artist = new Artist(
  291.                 Util::toString($xml->artist),
  292.                 Util::toString($xml->artist['mbid']),
  293.                 '', array(), 0, 0, 0, array(), array(), '', 0.0
  294.             );
  295.         }
  296.         else{
  297.             $artist = Util::toString($xml->artist);
  298.         }
  299.  
  300.         return new Album(
  301.             $artist,
  302.             Util::toString($xml->name),
  303.             Util::toInteger($xml->id),
  304.             $mbid,
  305.             Util::toString($xml->url),
  306.             $images,
  307.             Util::toInteger($xml->listeners),
  308.             Util::toInteger($xml->playcount),
  309.             Util::toTimestamp($xml->releasedate),
  310.             $topTags
  311.         );
  312.     }
  313. }
  314.  
  315. ?>

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