Source for file Tag.php

Documentation is available at Tag.php

  1. <?
  2.  
  3. /** Represents a tag and provides different methods to query tag information.
  4.  *
  5.  * @package    php-lastfm-api
  6.  * @author  Felix Bruns <felixbruns@web.de>
  7.  * @version    1.0
  8.  */
  9. class Tag {
  10.     /** The tags name.
  11.      *
  12.      * @var string 
  13.      * @access    private
  14.      */
  15.     private $name;
  16.  
  17.     /** The tags count.
  18.      *
  19.      * @var integer 
  20.      * @access    private
  21.      */
  22.     private $count;
  23.  
  24.     /** The tags last.fm URL.
  25.      *
  26.      * @var string 
  27.      * @access    private
  28.      */
  29.     private $url;
  30.  
  31.     /** Create a Tag object.
  32.      *
  33.      * @param string    $name    Tag name.
  34.       * @param integer    $count    Tag count.
  35.       * @param string    $url    Tag URL.
  36.       *
  37.      * @access    public
  38.      */
  39.     public function __construct($name, $count, $url){
  40.         $this->name  = $name;
  41.         $this->count = $count;
  42.         $this->url   = $url;
  43.     }
  44.  
  45.     /** Returns the tags name.
  46.      *
  47.      * @return    string    Tag name.
  48.      * @access    public
  49.      */
  50.     public function getName(){
  51.         return $this->name;
  52.     }
  53.  
  54.     /** Returns the tags count.
  55.      *
  56.      * @return    integer    Tag count.
  57.      * @access    public
  58.      */
  59.     public function getCount(){
  60.         return $this->count;
  61.     }
  62.  
  63.     /** Returns the tags last.fm URL.
  64.      *
  65.      * @return    string    Tag URL.
  66.      * @access    public
  67.      */
  68.     public function getUrl(){
  69.         return $this->url;
  70.     }
  71.  
  72.     /** Search for tags similar to this one. Returns tags ranked by similarity, based on listening data.
  73.      *
  74.      * @param    string    $tag    The tag name in question. (Required)
  75.      * @return    array            An array of Tag objects.
  76.      *
  77.      * @static
  78.      * @access    public
  79.      * @throws    Error
  80.      */
  81.     public static function getSimilar($tag){
  82.         $xml = CallerFactory::getDefaultCaller()->call('tag.getSimilar', array(
  83.             'tag' => $tag
  84.         ));
  85.  
  86.         $tags = array();
  87.  
  88.         foreach($xml->children() as $tag){
  89.             $tags[] = Tag::fromSimpleXMLElement($tag);
  90.         }
  91.  
  92.         return $tags;
  93.     }
  94.  
  95.     /** Get the top albums tagged by this tag, ordered by tag count.
  96.      *
  97.      * @param    string    $tag    The tag name in question. (Required)
  98.      * @return    array            An array of Album objects.
  99.      *
  100.      * @static
  101.      * @access    public
  102.      * @throws    Error
  103.      */
  104.     public static function getTopAlbums($tag){
  105.         $xml = CallerFactory::getDefaultCaller()->call('tag.getTopAlbums', array(
  106.             'tag' => $tag
  107.         ));
  108.  
  109.         $albums = array();
  110.  
  111.         foreach($xml->children() as $album){
  112.             $albums[] = Album::fromSimpleXMLElement($album);
  113.         }
  114.  
  115.         return $albums;
  116.     }
  117.  
  118.     /** Get the top artists tagged by this tag, ordered by tag count.
  119.      *
  120.      * @param    string    $tag    The tag name in question. (Required)
  121.      * @return    array            An array of Artist objects.
  122.      *
  123.      * @static
  124.      * @access    public
  125.      * @throws    Error
  126.      */
  127.     public static function getTopArtists($tag){
  128.         $xml = CallerFactory::getDefaultCaller()->call('tag.getTopArtists', array(
  129.             'tag' => $tag
  130.         ));
  131.  
  132.         $artists = array();
  133.  
  134.         foreach($xml->children() as $artist){
  135.             $artists[] = Artist::fromSimpleXMLElement($artist);
  136.         }
  137.  
  138.         return $artists;
  139.     }
  140.  
  141.     /** Fetches the top global tags on last.fm, sorted by popularity (number of times used).
  142.      *
  143.      * @return    array    An array of Tag objects.
  144.      *
  145.      * @static
  146.      * @access    public
  147.      * @throws    Error
  148.      */
  149.     public static function getTopTags(){
  150.         $xml = CallerFactory::getDefaultCaller()->call('tag.getTopTags');
  151.  
  152.         $tags = array();
  153.  
  154.         foreach($xml->children() as $tag){
  155.             $tags[] = Tag::fromSimpleXMLElement($tag);
  156.         }
  157.  
  158.         return $tags;
  159.     }
  160.  
  161.     /** Get the top tracks tagged by this tag, ordered by tag count.
  162.      *
  163.      * @param    string    $tag    The tag name in question. (Required)
  164.      * @return    array            An array of Track objects.
  165.      *
  166.      * @static
  167.      * @access    public
  168.      * @throws    Error
  169.      */
  170.     public static function getTopTracks($tag){
  171.         $xml = CallerFactory::getDefaultCaller()->call('tag.getTopTracks', array(
  172.             'tag' => $tag
  173.         ));
  174.  
  175.         $tracks = array();
  176.  
  177.         foreach($xml->children() as $track){
  178.             $tracks[] = Track::fromSimpleXMLElement($track);
  179.         }
  180.  
  181.         return $tracks;
  182.     }
  183.  
  184.     /** Get an artist chart for a tag, for a given date range. If no date range is supplied, it will return the most recent artist chart for this tag.
  185.      *
  186.      * @param    string    $tag    The tag name in question. (Required)
  187.      * @param    integer    $from    The date at which the chart should start from. See Tag.getWeeklyChartList for more. (Optional)
  188.      * @param    integer    $to        The date at which the chart should end on. See Tag.getWeeklyChartList for more. (Optional)
  189.      * @param    integer    $limit    The number of chart items to return (default = 50). (Optional)
  190.      * @return    array            An array of Artist objects.
  191.      *
  192.      * @static
  193.      * @access    public
  194.      * @throws    Error
  195.      */
  196.     public static function getWeeklyArtistChart($tag, $from = null, $to = null,
  197.                                                 $limit = null){
  198.         $xml = CallerFactory::getDefaultCaller()->call('tag.getWeeklyArtistChart', array(
  199.             'tag'   => $tag,
  200.             'from'  => $from,
  201.             'to'    => $to,
  202.             'limit' => $limit
  203.         ));
  204.  
  205.         $artists = array();
  206.  
  207.         foreach($xml->children() as $artist){
  208.             $artists[] = Artist::fromSimpleXMLElement($artist);
  209.         }
  210.  
  211.         return $artists;
  212.     }
  213.  
  214.     /** Get a list of available charts for this group, expressed as date ranges which can be sent to the chart services.
  215.      *
  216.      * @param    string    $tag    The tag name in question. (Required)
  217.      * @return    array            An array of from/to unix timestamp pairs.
  218.      *
  219.      * @static
  220.      * @access    public
  221.      * @throws    Error
  222.      */
  223.     public static function getWeeklyChartList($tag){
  224.         $xml = CallerFactory::getDefaultCaller()->call('tag.getWeeklyChartList', array(
  225.             'tag' => $tag
  226.         ));
  227.  
  228.         $chartList = array();
  229.  
  230.         foreach($xml->children() as $chart){
  231.             $chartList[] = array(
  232.                 'from' => Util::toInteger($chart['from']),
  233.                 'to'   => Util::toInteger($chart['to']),
  234.             );
  235.         }
  236.  
  237.         return $chartList;
  238.     }
  239.  
  240.     /** Search for a tag by name. Returns matches sorted by relevance.
  241.      *
  242.      * @param    string    $tag    The tag name in question. (Required)
  243.      * @param    integer    $limit    Limit the number of tags returned at one time. Default (maximum) is 30. (Optional)
  244.      * @param    integer    $page    Scan into the results by specifying a page number. Defaults to first page. (Optional)
  245.      * @return    array            An array of Tag objects.
  246.      *
  247.      * @static
  248.      * @access    public
  249.      * @throws    Error
  250.      */
  251.     public static function search($tag, $limit = null, $page = null){
  252.         $xml = CallerFactory::getDefaultCaller()->call('tag.search', array(
  253.             'tag'   => $tag,
  254.             'limit' => $limit,
  255.             'page'  => $page
  256.         ));
  257.  
  258.         $tags = array();
  259.  
  260.         foreach($xml->tagmatches->children() as $tag){
  261.             $tags[] = Tag::fromSimpleXMLElement($tag);
  262.         }
  263.  
  264.         return $tags;
  265.     }
  266.  
  267.     /** Create a Tag object from a SimpleXMLElement.
  268.      *
  269.      * @param    SimpleXMLElement    $xml    A SimpleXMLElement.
  270.      * @return    Tag                            A Tag object.
  271.      *
  272.      * @static
  273.      * @access    public
  274.      * @internal
  275.      */
  276.     public static function fromSimpleXMLElement(SimpleXMLElement $xml){
  277.         return new Tag(
  278.             Util::toString($xml->name),
  279.             Util::toInteger($xml->count),
  280.             Util::toString($xml->url)
  281.         );
  282.     }
  283. }
  284.  
  285. ?>

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