interface/modules/zend_modules/library/Zend/Feed/Writer/AbstractFeed.php

   1 <?php
   2 /**
   3  * Zend Framework (http://framework.zend.com/)
   4  *
   5  * @link      http://github.com/zendframework/zf2 for the canonical source repository
   6  * @copyright Copyright (c) 2005-2013 Zend Technologies USA Inc. (http://www.zend.com)
   7  * @license   http://framework.zend.com/license/new-bsd New BSD License
   8  */
   9
  10 namespace Zend\Feed\Writer;
  11
  12 use DateTime;
  13 use Zend\Feed\Uri;
  14 use Zend\Validator;
  15
  16 class AbstractFeed
  17 {
  18     /**
  19      * Contains all Feed level date to append in feed output
  20      *
  21      * @var array
  22      */
  23     protected $data = array();
  24
  25     /**
  26      * Holds the value "atom" or "rss" depending on the feed type set when
  27      * when last exported.
  28      *
  29      * @var string
  30      */
  31     protected $type = null;
  32
  33     /**
  34      * @var $extensions
  35      */
  36     protected $extensions;
  37
  38     /**
  39      * Constructor: Primarily triggers the registration of core extensions and
  40      * loads those appropriate to this data container.
  41      *
  42      */
  43     public function __construct()
  44     {
  45         Writer::registerCoreExtensions();
  46         $this->_loadExtensions();
  47     }
  48
  49     /**
  50      * Set a single author
  51      *
  52      * The following option keys are supported:
  53      * 'name'  => (string) The name
  54      * 'email' => (string) An optional email
  55      * 'uri'   => (string) An optional and valid URI
  56      *
  57      * @param array $author
  58      * @throws Exception\InvalidArgumentException If any value of $author not follow the format.
  59      * @return AbstractFeed
  60      */
  61     public function addAuthor(array $author)
  62     {
  63         // Check array values
  64         if (!array_key_exists('name', $author)
  65             || empty($author['name'])
  66             || !is_string($author['name'])
  67         ) {
  68             throw new Exception\InvalidArgumentException(
  69                 'Invalid parameter: author array must include a "name" key with a non-empty string value');
  70         }
  71
  72         if (isset($author['email'])) {
  73             if (empty($author['email']) || !is_string($author['email'])) {
  74                 throw new Exception\InvalidArgumentException(
  75                     'Invalid parameter: "email" array value must be a non-empty string');
  76             }
  77         }
  78         if (isset($author['uri'])) {
  79             if (empty($author['uri']) || !is_string($author['uri']) ||
  80                 !Uri::factory($author['uri'])->isValid()
  81             ) {
  82                 throw new Exception\InvalidArgumentException(
  83                     'Invalid parameter: "uri" array value must be a non-empty string and valid URI/IRI');
  84             }
  85         }
  86
  87         $this->data['authors'][] = $author;
  88
  89         return $this;
  90     }
  91
  92     /**
  93      * Set an array with feed authors
  94      *
  95      * @see addAuthor
  96      * @param array $authors
  97      * @return AbstractFeed
  98      */
  99     public function addAuthors(array $authors)
 100     {
 101         foreach ($authors as $author) {
 102             $this->addAuthor($author);
 103         }
 104
 105         return $this;
 106     }
 107
 108     /**
 109      * Set the copyright entry
 110      *
 111      * @param  string      $copyright
 112      * @throws Exception\InvalidArgumentException
 113      * @return AbstractFeed
 114      */
 115     public function setCopyright($copyright)
 116     {
 117         if (empty($copyright) || !is_string($copyright)) {
 118             throw new Exception\InvalidArgumentException('Invalid parameter: parameter must be a non-empty string');
 119         }
 120         $this->data['copyright'] = $copyright;
 121
 122         return $this;
 123     }
 124
 125     /**
 126      * Set the feed creation date
 127      *
 128      * @param null|int|DateTime
 129      * @throws Exception\InvalidArgumentException
 130      * @return AbstractFeed
 131      */
 132     public function setDateCreated($date = null)
 133     {
 134         if ($date === null) {
 135             $date = new DateTime();
 136         } elseif (is_int($date)) {
 137             $date = new DateTime('@' . $date);
 138         } elseif (!$date instanceof DateTime) {
 139             throw new Exception\InvalidArgumentException('Invalid DateTime object or UNIX Timestamp'
 140                                                          . ' passed as parameter');
 141         }
 142         $this->data['dateCreated'] = $date;
 143
 144         return $this;
 145     }
 146
 147     /**
 148      * Set the feed modification date
 149      *
 150      * @param null|int|DateTime
 151      * @throws Exception\InvalidArgumentException
 152      * @return AbstractFeed
 153      */
 154     public function setDateModified($date = null)
 155     {
 156         if ($date === null) {
 157             $date = new DateTime();
 158         } elseif (is_int($date)) {
 159             $date = new DateTime('@' . $date);
 160         } elseif (!$date instanceof DateTime) {
 161             throw new Exception\InvalidArgumentException('Invalid DateTime object or UNIX Timestamp'
 162                                                          . ' passed as parameter');
 163         }
 164         $this->data['dateModified'] = $date;
 165
 166         return $this;
 167     }
 168
 169     /**
 170      * Set the feed last-build date. Ignored for Atom 1.0.
 171      *
 172      * @param null|int|DateTime
 173      * @throws Exception\InvalidArgumentException
 174      * @return AbstractFeed
 175      */
 176     public function setLastBuildDate($date = null)
 177     {
 178         if ($date === null) {
 179             $date = new DateTime();
 180         } elseif (is_int($date)) {
 181             $date = new DateTime('@' . $date);
 182         } elseif (!$date instanceof DateTime) {
 183             throw new Exception\InvalidArgumentException('Invalid DateTime object or UNIX Timestamp'
 184                                                          . ' passed as parameter');
 185         }
 186         $this->data['lastBuildDate'] = $date;
 187
 188         return $this;
 189     }
 190
 191     /**
 192      * Set the feed description
 193      *
 194      * @param string $description
 195      * @throws Exception\InvalidArgumentException
 196      * @return AbstractFeed
 197      */
 198     public function setDescription($description)
 199     {
 200         if (empty($description) || !is_string($description)) {
 201             throw new Exception\InvalidArgumentException('Invalid parameter: parameter must be a non-empty string');
 202         }
 203         $this->data['description'] = $description;
 204
 205         return $this;
 206     }
 207
 208     /**
 209      * Set the feed generator entry
 210      *
 211      * @param array|string $name
 212      * @param null|string $version
 213      * @param null|string $uri
 214      * @throws Exception\InvalidArgumentException
 215      * @return AbstractFeed
 216      */
 217     public function setGenerator($name, $version = null, $uri = null)
 218     {
 219         if (is_array($name)) {
 220             $data = $name;
 221             if (empty($data['name']) || !is_string($data['name'])) {
 222                 throw new Exception\InvalidArgumentException('Invalid parameter: "name" must be a non-empty string');
 223             }
 224             $generator = array('name' => $data['name']);
 225             if (isset($data['version'])) {
 226                 if (empty($data['version']) || !is_string($data['version'])) {
 227                     throw new Exception\InvalidArgumentException('Invalid parameter: "version" must be a non-empty string');
 228                 }
 229                 $generator['version'] = $data['version'];
 230             }
 231             if (isset($data['uri'])) {
 232                 if (empty($data['uri']) || !is_string($data['uri']) || !Uri::factory($data['uri'])->isValid()) {
 233                     throw new Exception\InvalidArgumentException('Invalid parameter: "uri" must be a non-empty string and a valid URI/IRI');
 234                 }
 235                 $generator['uri'] = $data['uri'];
 236             }
 237         } else {
 238             if (empty($name) || !is_string($name)) {
 239                 throw new Exception\InvalidArgumentException('Invalid parameter: "name" must be a non-empty string');
 240             }
 241             $generator = array('name' => $name);
 242             if (isset($version)) {
 243                 if (empty($version) || !is_string($version)) {
 244                     throw new Exception\InvalidArgumentException('Invalid parameter: "version" must be a non-empty string');
 245                 }
 246                 $generator['version'] = $version;
 247             }
 248             if (isset($uri)) {
 249                 if (empty($uri) || !is_string($uri) || !Uri::factory($uri)->isValid()) {
 250                     throw new Exception\InvalidArgumentException('Invalid parameter: "uri" must be a non-empty string and a valid URI/IRI');
 251                 }
 252                 $generator['uri'] = $uri;
 253             }
 254         }
 255         $this->data['generator'] = $generator;
 256
 257         return $this;
 258     }
 259
 260     /**
 261      * Set the feed ID - URI or URN (via PCRE pattern) supported
 262      *
 263      * @param string $id
 264      * @throws Exception\InvalidArgumentException
 265      * @return AbstractFeed
 266      */
 267     public function setId($id)
 268     {
 269         if ((empty($id) || !is_string($id) || !Uri::factory($id)->isValid())
 270             && !preg_match("#^urn:[a-zA-Z0-9][a-zA-Z0-9\-]{1,31}:([a-zA-Z0-9\(\)\+\,\.\:\=\@\;\$\_\!\*\-]|%[0-9a-fA-F]{2})*#", $id)
 271             && !$this->_validateTagUri($id)
 272         ) {
 273             throw new Exception\InvalidArgumentException('Invalid parameter: parameter must be a non-empty string and valid URI/IRI');
 274         }
 275         $this->data['id'] = $id;
 276
 277         return $this;
 278     }
 279
 280     /**
 281      * Validate a URI using the tag scheme (RFC 4151)
 282      *
 283      * @param string $id
 284      * @return bool
 285      */
 286     protected function _validateTagUri($id)
 287     {
 288         if (preg_match('/^tag:(?P<name>.*),(?P<date>\d{4}-?\d{0,2}-?\d{0,2}):(?P<specific>.*)(.*:)*$/', $id, $matches)) {
 289             $dvalid = false;
 290             $nvalid = false;
 291             $date = $matches['date'];
 292             $d6 = strtotime($date);
 293             if ((strlen($date) == 4) && $date <= date('Y')) {
 294                 $dvalid = true;
 295             } elseif ((strlen($date) == 7) && ($d6 < strtotime("now"))) {
 296                 $dvalid = true;
 297             } elseif ((strlen($date) == 10) && ($d6 < strtotime("now"))) {
 298                 $dvalid = true;
 299             }
 300             $validator = new Validator\EmailAddress;
 301             if ($validator->isValid($matches['name'])) {
 302                 $nvalid = true;
 303             } else {
 304                 $nvalid = $validator->isValid('info@' . $matches['name']);
 305             }
 306             return $dvalid && $nvalid;
 307
 308         }
 309         return false;
 310     }
 311
 312     /**
 313      * Set a feed image (URI at minimum). Parameter is a single array with the
 314      * required key 'uri'. When rendering as RSS, the required keys are 'uri',
 315      * 'title' and 'link'. RSS also specifies three optional parameters 'width',
 316      * 'height' and 'description'. Only 'uri' is required and used for Atom rendering.
 317      *
 318      * @param array $data
 319      * @throws Exception\InvalidArgumentException
 320      * @return AbstractFeed
 321      */
 322     public function setImage(array $data)
 323     {
 324         if (empty($data['uri']) || !is_string($data['uri'])
 325             || !Uri::factory($data['uri'])->isValid()
 326         ) {
 327             throw new Exception\InvalidArgumentException('Invalid parameter: parameter \'uri\''
 328             . ' must be a non-empty string and valid URI/IRI');
 329         }
 330         $this->data['image'] = $data;
 331
 332         return $this;
 333     }
 334
 335     /**
 336      * Set the feed language
 337      *
 338      * @param string $language
 339      * @throws Exception\InvalidArgumentException
 340      * @return AbstractFeed
 341      */
 342     public function setLanguage($language)
 343     {
 344         if (empty($language) || !is_string($language)) {
 345             throw new Exception\InvalidArgumentException('Invalid parameter: parameter must be a non-empty string');
 346         }
 347         $this->data['language'] = $language;
 348
 349         return $this;
 350     }
 351
 352     /**
 353      * Set a link to the HTML source
 354      *
 355      * @param string $link
 356      * @throws Exception\InvalidArgumentException
 357      * @return AbstractFeed
 358      */
 359     public function setLink($link)
 360     {
 361         if (empty($link) || !is_string($link) || !Uri::factory($link)->isValid()) {
 362             throw new Exception\InvalidArgumentException('Invalid parameter: parameter must be a non-empty string and valid URI/IRI');
 363         }
 364         $this->data['link'] = $link;
 365
 366         return $this;
 367     }
 368
 369     /**
 370      * Set a link to an XML feed for any feed type/version
 371      *
 372      * @param string $link
 373      * @param string $type
 374      * @throws Exception\InvalidArgumentException
 375      * @return AbstractFeed
 376      */
 377     public function setFeedLink($link, $type)
 378     {
 379         if (empty($link) || !is_string($link) || !Uri::factory($link)->isValid()) {
 380             throw new Exception\InvalidArgumentException('Invalid parameter: "link"" must be a non-empty string and valid URI/IRI');
 381         }
 382         if (!in_array(strtolower($type), array('rss', 'rdf', 'atom'))) {
 383             throw new Exception\InvalidArgumentException('Invalid parameter: "type"; You must declare the type of feed the link points to, i.e. RSS, RDF or Atom');
 384         }
 385         $this->data['feedLinks'][strtolower($type)] = $link;
 386
 387         return $this;
 388     }
 389
 390     /**
 391      * Set the feed title
 392      *
 393      * @param string $title
 394      * @throws Exception\InvalidArgumentException
 395      * @return AbstractFeed
 396      */
 397     public function setTitle($title)
 398     {
 399         if (empty($title) || !is_string($title)) {
 400             throw new Exception\InvalidArgumentException('Invalid parameter: parameter must be a non-empty string');
 401         }
 402         $this->data['title'] = $title;
 403
 404         return $this;
 405     }
 406
 407     /**
 408      * Set the feed character encoding
 409      *
 410      * @param string $encoding
 411      * @throws Exception\InvalidArgumentException
 412      * @return AbstractFeed
 413      */
 414     public function setEncoding($encoding)
 415     {
 416         if (empty($encoding) || !is_string($encoding)) {
 417             throw new Exception\InvalidArgumentException('Invalid parameter: parameter must be a non-empty string');
 418         }
 419         $this->data['encoding'] = $encoding;
 420
 421         return $this;
 422     }
 423
 424     /**
 425      * Set the feed's base URL
 426      *
 427      * @param string $url
 428      * @throws Exception\InvalidArgumentException
 429      * @return AbstractFeed
 430      */
 431     public function setBaseUrl($url)
 432     {
 433         if (empty($url) || !is_string($url) || !Uri::factory($url)->isValid()) {
 434             throw new Exception\InvalidArgumentException('Invalid parameter: "url" array value'
 435             . ' must be a non-empty string and valid URI/IRI');
 436         }
 437         $this->data['baseUrl'] = $url;
 438
 439         return $this;
 440     }
 441
 442     /**
 443      * Add a Pubsubhubbub hub endpoint URL
 444      *
 445      * @param string $url
 446      * @throws Exception\InvalidArgumentException
 447      * @return AbstractFeed
 448      */
 449     public function addHub($url)
 450     {
 451         if (empty($url) || !is_string($url) || !Uri::factory($url)->isValid()) {
 452             throw new Exception\InvalidArgumentException('Invalid parameter: "url" array value'
 453             . ' must be a non-empty string and valid URI/IRI');
 454         }
 455         if (!isset($this->data['hubs'])) {
 456             $this->data['hubs'] = array();
 457         }
 458         $this->data['hubs'][] = $url;
 459
 460         return $this;
 461     }
 462
 463     /**
 464      * Add Pubsubhubbub hub endpoint URLs
 465      *
 466      * @param array $urls
 467      * @return AbstractFeed
 468      */
 469     public function addHubs(array $urls)
 470     {
 471         foreach ($urls as $url) {
 472             $this->addHub($url);
 473         }
 474
 475         return $this;
 476     }
 477
 478     /**
 479      * Add a feed category
 480      *
 481      * @param array $category
 482      * @throws Exception\InvalidArgumentException
 483      * @return AbstractFeed
 484      */
 485     public function addCategory(array $category)
 486     {
 487         if (!isset($category['term'])) {
 488             throw new Exception\InvalidArgumentException('Each category must be an array and '
 489             . 'contain at least a "term" element containing the machine '
 490             . ' readable category name');
 491         }
 492         if (isset($category['scheme'])) {
 493             if (empty($category['scheme'])
 494                 || !is_string($category['scheme'])
 495                 || !Uri::factory($category['scheme'])->isValid()
 496             ) {
 497                 throw new Exception\InvalidArgumentException('The Atom scheme or RSS domain of'
 498                 . ' a category must be a valid URI');
 499             }
 500         }
 501         if (!isset($this->data['categories'])) {
 502             $this->data['categories'] = array();
 503         }
 504         $this->data['categories'][] = $category;
 505
 506         return $this;
 507     }
 508
 509     /**
 510      * Set an array of feed categories
 511      *
 512      * @param array $categories
 513      * @return AbstractFeed
 514      */
 515     public function addCategories(array $categories)
 516     {
 517         foreach ($categories as $category) {
 518             $this->addCategory($category);
 519         }
 520
 521         return $this;
 522     }
 523
 524     /**
 525      * Get a single author
 526      *
 527      * @param  int $index
 528      * @return string|null
 529      */
 530     public function getAuthor($index = 0)
 531     {
 532         if (isset($this->data['authors'][$index])) {
 533             return $this->data['authors'][$index];
 534         }
 535
 536         return null;
 537     }
 538
 539     /**
 540      * Get an array with feed authors
 541      *
 542      * @return array
 543      */
 544     public function getAuthors()
 545     {
 546         if (!array_key_exists('authors', $this->data)) {
 547             return null;
 548         }
 549         return $this->data['authors'];
 550     }
 551
 552     /**
 553      * Get the copyright entry
 554      *
 555      * @return string|null
 556      */
 557     public function getCopyright()
 558     {
 559         if (!array_key_exists('copyright', $this->data)) {
 560             return null;
 561         }
 562         return $this->data['copyright'];
 563     }
 564
 565     /**
 566      * Get the feed creation date
 567      *
 568      * @return string|null
 569      */
 570     public function getDateCreated()
 571     {
 572         if (!array_key_exists('dateCreated', $this->data)) {
 573             return null;
 574         }
 575         return $this->data['dateCreated'];
 576     }
 577
 578     /**
 579      * Get the feed modification date
 580      *
 581      * @return string|null
 582      */
 583     public function getDateModified()
 584     {
 585         if (!array_key_exists('dateModified', $this->data)) {
 586             return null;
 587         }
 588         return $this->data['dateModified'];
 589     }
 590
 591     /**
 592      * Get the feed last-build date
 593      *
 594      * @return string|null
 595      */
 596     public function getLastBuildDate()
 597     {
 598         if (!array_key_exists('lastBuildDate', $this->data)) {
 599             return null;
 600         }
 601         return $this->data['lastBuildDate'];
 602     }
 603
 604     /**
 605      * Get the feed description
 606      *
 607      * @return string|null
 608      */
 609     public function getDescription()
 610     {
 611         if (!array_key_exists('description', $this->data)) {
 612             return null;
 613         }
 614         return $this->data['description'];
 615     }
 616
 617     /**
 618      * Get the feed generator entry
 619      *
 620      * @return string|null
 621      */
 622     public function getGenerator()
 623     {
 624         if (!array_key_exists('generator', $this->data)) {
 625             return null;
 626         }
 627         return $this->data['generator'];
 628     }
 629
 630     /**
 631      * Get the feed ID
 632      *
 633      * @return string|null
 634      */
 635     public function getId()
 636     {
 637         if (!array_key_exists('id', $this->data)) {
 638             return null;
 639         }
 640         return $this->data['id'];
 641     }
 642
 643     /**
 644      * Get the feed image URI
 645      *
 646      * @return array
 647      */
 648     public function getImage()
 649     {
 650         if (!array_key_exists('image', $this->data)) {
 651             return null;
 652         }
 653         return $this->data['image'];
 654     }
 655
 656     /**
 657      * Get the feed language
 658      *
 659      * @return string|null
 660      */
 661     public function getLanguage()
 662     {
 663         if (!array_key_exists('language', $this->data)) {
 664             return null;
 665         }
 666         return $this->data['language'];
 667     }
 668
 669     /**
 670      * Get a link to the HTML source
 671      *
 672      * @return string|null
 673      */
 674     public function getLink()
 675     {
 676         if (!array_key_exists('link', $this->data)) {
 677             return null;
 678         }
 679         return $this->data['link'];
 680     }
 681
 682     /**
 683      * Get a link to the XML feed
 684      *
 685      * @return string|null
 686      */
 687     public function getFeedLinks()
 688     {
 689         if (!array_key_exists('feedLinks', $this->data)) {
 690             return null;
 691         }
 692         return $this->data['feedLinks'];
 693     }
 694
 695     /**
 696      * Get the feed title
 697      *
 698      * @return string|null
 699      */
 700     public function getTitle()
 701     {
 702         if (!array_key_exists('title', $this->data)) {
 703             return null;
 704         }
 705         return $this->data['title'];
 706     }
 707
 708     /**
 709      * Get the feed character encoding
 710      *
 711      * @return string|null
 712      */
 713     public function getEncoding()
 714     {
 715         if (!array_key_exists('encoding', $this->data)) {
 716             return 'UTF-8';
 717         }
 718         return $this->data['encoding'];
 719     }
 720
 721     /**
 722      * Get the feed's base url
 723      *
 724      * @return string|null
 725      */
 726     public function getBaseUrl()
 727     {
 728         if (!array_key_exists('baseUrl', $this->data)) {
 729             return null;
 730         }
 731         return $this->data['baseUrl'];
 732     }
 733
 734     /**
 735      * Get the URLs used as Pubsubhubbub hubs endpoints
 736      *
 737      * @return string|null
 738      */
 739     public function getHubs()
 740     {
 741         if (!array_key_exists('hubs', $this->data)) {
 742             return null;
 743         }
 744         return $this->data['hubs'];
 745     }
 746
 747     /**
 748      * Get the feed categories
 749      *
 750      * @return string|null
 751      */
 752     public function getCategories()
 753     {
 754         if (!array_key_exists('categories', $this->data)) {
 755             return null;
 756         }
 757         return $this->data['categories'];
 758     }
 759
 760     /**
 761      * Resets the instance and deletes all data
 762      *
 763      * @return void
 764      */
 765     public function reset()
 766     {
 767         $this->data = array();
 768     }
 769
 770     /**
 771      * Set the current feed type being exported to "rss" or "atom". This allows
 772      * other objects to gracefully choose whether to execute or not, depending
 773      * on their appropriateness for the current type, e.g. renderers.
 774      *
 775      * @param string $type
 776      * @return AbstractFeed
 777      */
 778     public function setType($type)
 779     {
 780         $this->type = $type;
 781         return $this;
 782     }
 783
 784     /**
 785      * Retrieve the current or last feed type exported.
 786      *
 787      * @return string Value will be "rss" or "atom"
 788      */
 789     public function getType()
 790     {
 791         return $this->type;
 792     }
 793
 794     /**
 795      * Unset a specific data point
 796      *
 797      * @param string $name
 798      * @return AbstractFeed
 799      */
 800     public function remove($name)
 801     {
 802         if (isset($this->data[$name])) {
 803             unset($this->data[$name]);
 804         }
 805         return $this;
 806     }
 807
 808     /**
 809      * Method overloading: call given method on first extension implementing it
 810      *
 811      * @param  string $method
 812      * @param  array $args
 813      * @return mixed
 814      * @throws Exception\BadMethodCallException if no extensions implements the method
 815      */
 816     public function __call($method, $args)
 817     {
 818         foreach ($this->extensions as $extension) {
 819             try {
 820                 return call_user_func_array(array($extension, $method), $args);
 821             } catch (Exception\BadMethodCallException $e) {
 822             }
 823         }
 824         throw new Exception\BadMethodCallException(
 825             'Method: ' . $method . ' does not exist and could not be located on a registered Extension'
 826         );
 827     }
 828
 829     /**
 830      * Load extensions from Zend\Feed\Writer\Writer
 831      *
 832      * @throws Exception\RuntimeException
 833      * @return void
 834      */
 835     protected function _loadExtensions()
 836     {
 837         $all     = Writer::getExtensions();
 838         $manager = Writer::getExtensionManager();
 839         $exts    = $all['feed'];
 840         foreach ($exts as $ext) {
 841             if (!$manager->has($ext)) {
 842                 throw new Exception\RuntimeException(sprintf('Unable to load extension "%s"; could not resolve to class', $ext));
 843             }
 844             $this->extensions[$ext] = $manager->get($ext);
 845             $this->extensions[$ext]->setEncoding($this->getEncoding());
 846         }
 847     }
 848 }