www.aleph1.co.uk Git - yaffs-website/blob - vendor/zendframework/zend-feed/src/Writer/Entry.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-2015 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
  15 /**
  16 */
  17 class Entry
  18 {
  19     /**
  20      * Internal array containing all data associated with this entry or item.
  21      *
  22      * @var array
  23      */
  24     protected $data = [];
  25
  26     /**
  27      * Registered extensions
  28      *
  29      * @var array
  30      */
  31     protected $extensions = [];
  32
  33     /**
  34      * Holds the value "atom" or "rss" depending on the feed type set when
  35      * when last exported.
  36      *
  37      * @var string
  38      */
  39     protected $type = null;
  40
  41     /**
  42      * Constructor: Primarily triggers the registration of core extensions and
  43      * loads those appropriate to this data container.
  44      *
  45      */
  46     public function __construct()
  47     {
  48         Writer::registerCoreExtensions();
  49         $this->_loadExtensions();
  50     }
  51
  52     /**
  53      * Set a single author
  54      *
  55      * The following option keys are supported:
  56      * 'name'  => (string) The name
  57      * 'email' => (string) An optional email
  58      * 'uri'   => (string) An optional and valid URI
  59      *
  60      * @param array $author
  61      * @throws Exception\InvalidArgumentException If any value of $author not follow the format.
  62      * @return Entry
  63      */
  64     public function addAuthor(array $author)
  65     {
  66         // Check array values
  67         if (! array_key_exists('name', $author)
  68             || empty($author['name'])
  69             || ! is_string($author['name'])
  70         ) {
  71             throw new Exception\InvalidArgumentException(
  72                 'Invalid parameter: author array must include a "name" key with a non-empty string value'
  73             );
  74         }
  75
  76         if (isset($author['email'])) {
  77             if (empty($author['email']) || ! is_string($author['email'])) {
  78                 throw new Exception\InvalidArgumentException(
  79                     'Invalid parameter: "email" array value must be a non-empty string'
  80                 );
  81             }
  82         }
  83         if (isset($author['uri'])) {
  84             if (empty($author['uri']) || ! is_string($author['uri']) ||
  85                 ! Uri::factory($author['uri'])->isValid()
  86             ) {
  87                 throw new Exception\InvalidArgumentException(
  88                     'Invalid parameter: "uri" array value must be a non-empty string and valid URI/IRI'
  89                 );
  90             }
  91         }
  92
  93         $this->data['authors'][] = $author;
  94
  95         return $this;
  96     }
  97
  98     /**
  99      * Set an array with feed authors
 100      *
 101      * @see addAuthor
 102      * @param array $authors
 103      * @return Entry
 104      */
 105     public function addAuthors(array $authors)
 106     {
 107         foreach ($authors as $author) {
 108             $this->addAuthor($author);
 109         }
 110
 111         return $this;
 112     }
 113
 114     /**
 115      * Set the feed character encoding
 116      *
 117      * @param string $encoding
 118      * @throws Exception\InvalidArgumentException
 119      * @return Entry
 120      */
 121     public function setEncoding($encoding)
 122     {
 123         if (empty($encoding) || ! is_string($encoding)) {
 124             throw new Exception\InvalidArgumentException('Invalid parameter: parameter must be a non-empty string');
 125         }
 126         $this->data['encoding'] = $encoding;
 127
 128         return $this;
 129     }
 130
 131     /**
 132      * Get the feed character encoding
 133      *
 134      * @return string|null
 135      */
 136     public function getEncoding()
 137     {
 138         if (! array_key_exists('encoding', $this->data)) {
 139             return 'UTF-8';
 140         }
 141         return $this->data['encoding'];
 142     }
 143
 144     /**
 145      * Set the copyright entry
 146      *
 147      * @param string $copyright
 148      * @throws Exception\InvalidArgumentException
 149      * @return Entry
 150      */
 151     public function setCopyright($copyright)
 152     {
 153         if (empty($copyright) || ! is_string($copyright)) {
 154             throw new Exception\InvalidArgumentException('Invalid parameter: parameter must be a non-empty string');
 155         }
 156         $this->data['copyright'] = $copyright;
 157
 158         return $this;
 159     }
 160
 161     /**
 162      * Set the entry's content
 163      *
 164      * @param string $content
 165      * @throws Exception\InvalidArgumentException
 166      * @return Entry
 167      */
 168     public function setContent($content)
 169     {
 170         if (empty($content) || ! is_string($content)) {
 171             throw new Exception\InvalidArgumentException('Invalid parameter: parameter must be a non-empty string');
 172         }
 173         $this->data['content'] = $content;
 174
 175         return $this;
 176     }
 177
 178     /**
 179      * Set the feed creation date
 180      *
 181      * @param null|int|DateTime $date
 182      * @throws Exception\InvalidArgumentException
 183      * @return Entry
 184      */
 185     public function setDateCreated($date = null)
 186     {
 187         if ($date === null) {
 188             $date = new DateTime();
 189         } elseif (is_int($date)) {
 190             $date = new DateTime('@' . $date);
 191         } elseif (! $date instanceof DateTime) {
 192             throw new Exception\InvalidArgumentException(
 193                 'Invalid DateTime object or UNIX Timestamp passed as parameter'
 194             );
 195         }
 196         $this->data['dateCreated'] = $date;
 197
 198         return $this;
 199     }
 200
 201     /**
 202      * Set the feed modification date
 203      *
 204      * @param null|int|DateTime $date
 205      * @throws Exception\InvalidArgumentException
 206      * @return Entry
 207      */
 208     public function setDateModified($date = null)
 209     {
 210         if ($date === null) {
 211             $date = new DateTime();
 212         } elseif (is_int($date)) {
 213             $date = new DateTime('@' . $date);
 214         } elseif (! $date instanceof DateTime) {
 215             throw new Exception\InvalidArgumentException(
 216                 'Invalid DateTime object or UNIX Timestamp passed as parameter'
 217             );
 218         }
 219         $this->data['dateModified'] = $date;
 220
 221         return $this;
 222     }
 223
 224     /**
 225      * Set the feed description
 226      *
 227      * @param string $description
 228      * @throws Exception\InvalidArgumentException
 229      * @return Entry
 230      */
 231     public function setDescription($description)
 232     {
 233         if (empty($description) || ! is_string($description)) {
 234             throw new Exception\InvalidArgumentException('Invalid parameter: parameter must be a non-empty string');
 235         }
 236         $this->data['description'] = $description;
 237
 238         return $this;
 239     }
 240
 241     /**
 242      * Set the feed ID
 243      *
 244      * @param string $id
 245      * @throws Exception\InvalidArgumentException
 246      * @return Entry
 247      */
 248     public function setId($id)
 249     {
 250         if (empty($id) || ! is_string($id)) {
 251             throw new Exception\InvalidArgumentException('Invalid parameter: parameter must be a non-empty string');
 252         }
 253         $this->data['id'] = $id;
 254
 255         return $this;
 256     }
 257
 258     /**
 259      * Set a link to the HTML source of this entry
 260      *
 261      * @param string $link
 262      * @throws Exception\InvalidArgumentException
 263      * @return Entry
 264      */
 265     public function setLink($link)
 266     {
 267         if (empty($link) || ! is_string($link) || ! Uri::factory($link)->isValid()) {
 268             throw new Exception\InvalidArgumentException(
 269                 'Invalid parameter: parameter must be a non-empty string and valid URI/IRI'
 270             );
 271         }
 272         $this->data['link'] = $link;
 273
 274         return $this;
 275     }
 276
 277     /**
 278      * Set the number of comments associated with this entry
 279      *
 280      * @param int $count
 281      * @throws Exception\InvalidArgumentException
 282      * @return Entry
 283      */
 284     public function setCommentCount($count)
 285     {
 286         if (! is_numeric($count) || (int) $count != $count || (int) $count < 0) {
 287             throw new Exception\InvalidArgumentException(
 288                 'Invalid parameter: "count" must be a positive integer number or zero'
 289             );
 290         }
 291         $this->data['commentCount'] = (int) $count;
 292
 293         return $this;
 294     }
 295
 296     /**
 297      * Set a link to a HTML page containing comments associated with this entry
 298      *
 299      * @param string $link
 300      * @throws Exception\InvalidArgumentException
 301      * @return Entry
 302      */
 303     public function setCommentLink($link)
 304     {
 305         if (empty($link) || ! is_string($link) || ! Uri::factory($link)->isValid()) {
 306             throw new Exception\InvalidArgumentException(
 307                 'Invalid parameter: "link" must be a non-empty string and valid URI/IRI'
 308             );
 309         }
 310         $this->data['commentLink'] = $link;
 311
 312         return $this;
 313     }
 314
 315     /**
 316      * Set a link to an XML feed for any comments associated with this entry
 317      *
 318      * @param array $link
 319      * @throws Exception\InvalidArgumentException
 320      * @return Entry
 321      */
 322     public function setCommentFeedLink(array $link)
 323     {
 324         if (! isset($link['uri']) || ! is_string($link['uri']) || ! Uri::factory($link['uri'])->isValid()) {
 325             throw new Exception\InvalidArgumentException(
 326                 'Invalid parameter: "link" must be a non-empty string and valid URI/IRI'
 327             );
 328         }
 329         if (! isset($link['type']) || ! in_array($link['type'], ['atom', 'rss', 'rdf'])) {
 330             throw new Exception\InvalidArgumentException('Invalid parameter: "type" must be one'
 331             . ' of "atom", "rss" or "rdf"');
 332         }
 333         if (! isset($this->data['commentFeedLinks'])) {
 334             $this->data['commentFeedLinks'] = [];
 335         }
 336         $this->data['commentFeedLinks'][] = $link;
 337
 338         return $this;
 339     }
 340
 341     /**
 342      * Set a links to an XML feed for any comments associated with this entry.
 343      * Each link is an array with keys "uri" and "type", where type is one of:
 344      * "atom", "rss" or "rdf".
 345      *
 346      * @param array $links
 347      * @return Entry
 348      */
 349     public function setCommentFeedLinks(array $links)
 350     {
 351         foreach ($links as $link) {
 352             $this->setCommentFeedLink($link);
 353         }
 354
 355         return $this;
 356     }
 357
 358     /**
 359      * Set the feed title
 360      *
 361      * @param string $title
 362      * @throws Exception\InvalidArgumentException
 363      * @return Entry
 364      */
 365     public function setTitle($title)
 366     {
 367         if (empty($title) || ! is_string($title)) {
 368             throw new Exception\InvalidArgumentException('Invalid parameter: parameter must be a non-empty string');
 369         }
 370         $this->data['title'] = $title;
 371
 372         return $this;
 373     }
 374
 375     /**
 376      * Get an array with feed authors
 377      *
 378      * @return array
 379      */
 380     public function getAuthors()
 381     {
 382         if (! array_key_exists('authors', $this->data)) {
 383             return;
 384         }
 385         return $this->data['authors'];
 386     }
 387
 388     /**
 389      * Get the entry content
 390      *
 391      * @return string
 392      */
 393     public function getContent()
 394     {
 395         if (! array_key_exists('content', $this->data)) {
 396             return;
 397         }
 398         return $this->data['content'];
 399     }
 400
 401     /**
 402      * Get the entry copyright information
 403      *
 404      * @return string
 405      */
 406     public function getCopyright()
 407     {
 408         if (! array_key_exists('copyright', $this->data)) {
 409             return;
 410         }
 411         return $this->data['copyright'];
 412     }
 413
 414     /**
 415      * Get the entry creation date
 416      *
 417      * @return string
 418      */
 419     public function getDateCreated()
 420     {
 421         if (! array_key_exists('dateCreated', $this->data)) {
 422             return;
 423         }
 424         return $this->data['dateCreated'];
 425     }
 426
 427     /**
 428      * Get the entry modification date
 429      *
 430      * @return string
 431      */
 432     public function getDateModified()
 433     {
 434         if (! array_key_exists('dateModified', $this->data)) {
 435             return;
 436         }
 437         return $this->data['dateModified'];
 438     }
 439
 440     /**
 441      * Get the entry description
 442      *
 443      * @return string
 444      */
 445     public function getDescription()
 446     {
 447         if (! array_key_exists('description', $this->data)) {
 448             return;
 449         }
 450         return $this->data['description'];
 451     }
 452
 453     /**
 454      * Get the entry ID
 455      *
 456      * @return string
 457      */
 458     public function getId()
 459     {
 460         if (! array_key_exists('id', $this->data)) {
 461             return;
 462         }
 463         return $this->data['id'];
 464     }
 465
 466     /**
 467      * Get a link to the HTML source
 468      *
 469      * @return string|null
 470      */
 471     public function getLink()
 472     {
 473         if (! array_key_exists('link', $this->data)) {
 474             return;
 475         }
 476         return $this->data['link'];
 477     }
 478
 479
 480     /**
 481      * Get all links
 482      *
 483      * @return array
 484      */
 485     public function getLinks()
 486     {
 487         if (! array_key_exists('links', $this->data)) {
 488             return;
 489         }
 490         return $this->data['links'];
 491     }
 492
 493     /**
 494      * Get the entry title
 495      *
 496      * @return string
 497      */
 498     public function getTitle()
 499     {
 500         if (! array_key_exists('title', $this->data)) {
 501             return;
 502         }
 503         return $this->data['title'];
 504     }
 505
 506     /**
 507      * Get the number of comments/replies for current entry
 508      *
 509      * @return int
 510      */
 511     public function getCommentCount()
 512     {
 513         if (! array_key_exists('commentCount', $this->data)) {
 514             return;
 515         }
 516         return $this->data['commentCount'];
 517     }
 518
 519     /**
 520      * Returns a URI pointing to the HTML page where comments can be made on this entry
 521      *
 522      * @return string
 523      */
 524     public function getCommentLink()
 525     {
 526         if (! array_key_exists('commentLink', $this->data)) {
 527             return;
 528         }
 529         return $this->data['commentLink'];
 530     }
 531
 532     /**
 533      * Returns an array of URIs pointing to a feed of all comments for this entry
 534      * where the array keys indicate the feed type (atom, rss or rdf).
 535      *
 536      * @return string
 537      */
 538     public function getCommentFeedLinks()
 539     {
 540         if (! array_key_exists('commentFeedLinks', $this->data)) {
 541             return;
 542         }
 543         return $this->data['commentFeedLinks'];
 544     }
 545
 546     /**
 547      * Add an entry category
 548      *
 549      * @param array $category
 550      * @throws Exception\InvalidArgumentException
 551      * @return Entry
 552      */
 553     public function addCategory(array $category)
 554     {
 555         if (! isset($category['term'])) {
 556             throw new Exception\InvalidArgumentException('Each category must be an array and '
 557             . 'contain at least a "term" element containing the machine '
 558             . ' readable category name');
 559         }
 560         if (isset($category['scheme'])) {
 561             if (empty($category['scheme'])
 562                 || ! is_string($category['scheme'])
 563                 || ! Uri::factory($category['scheme'])->isValid()
 564             ) {
 565                 throw new Exception\InvalidArgumentException('The Atom scheme or RSS domain of'
 566                 . ' a category must be a valid URI');
 567             }
 568         }
 569         if (! isset($this->data['categories'])) {
 570             $this->data['categories'] = [];
 571         }
 572         $this->data['categories'][] = $category;
 573
 574         return $this;
 575     }
 576
 577     /**
 578      * Set an array of entry categories
 579      *
 580      * @param array $categories
 581      * @return Entry
 582      */
 583     public function addCategories(array $categories)
 584     {
 585         foreach ($categories as $category) {
 586             $this->addCategory($category);
 587         }
 588
 589         return $this;
 590     }
 591
 592     /**
 593      * Get the entry categories
 594      *
 595      * @return string|null
 596      */
 597     public function getCategories()
 598     {
 599         if (! array_key_exists('categories', $this->data)) {
 600             return;
 601         }
 602         return $this->data['categories'];
 603     }
 604
 605     /**
 606      * Adds an enclosure to the entry. The array parameter may contain the
 607      * keys 'uri', 'type' and 'length'. Only 'uri' is required for Atom, though the
 608      * others must also be provided or RSS rendering (where they are required)
 609      * will throw an Exception.
 610      *
 611      * @param array $enclosure
 612      * @throws Exception\InvalidArgumentException
 613      * @return Entry
 614      */
 615     public function setEnclosure(array $enclosure)
 616     {
 617         if (! isset($enclosure['uri'])) {
 618             throw new Exception\InvalidArgumentException('Enclosure "uri" is not set');
 619         }
 620         if (! Uri::factory($enclosure['uri'])->isValid()) {
 621             throw new Exception\InvalidArgumentException('Enclosure "uri" is not a valid URI/IRI');
 622         }
 623         $this->data['enclosure'] = $enclosure;
 624
 625         return $this;
 626     }
 627
 628     /**
 629      * Retrieve an array of all enclosures to be added to entry.
 630      *
 631      * @return array
 632      */
 633     public function getEnclosure()
 634     {
 635         if (! array_key_exists('enclosure', $this->data)) {
 636             return;
 637         }
 638         return $this->data['enclosure'];
 639     }
 640
 641     /**
 642      * Unset a specific data point
 643      *
 644      * @param string $name
 645      * @return Entry
 646      */
 647     public function remove($name)
 648     {
 649         if (isset($this->data[$name])) {
 650             unset($this->data[$name]);
 651         }
 652
 653         return $this;
 654     }
 655
 656     /**
 657      * Get registered extensions
 658      *
 659      * @return array
 660      */
 661     public function getExtensions()
 662     {
 663         return $this->extensions;
 664     }
 665
 666     /**
 667      * Return an Extension object with the matching name (postfixed with _Entry)
 668      *
 669      * @param string $name
 670      * @return object
 671      */
 672     public function getExtension($name)
 673     {
 674         if (array_key_exists($name . '\\Entry', $this->extensions)) {
 675             return $this->extensions[$name . '\\Entry'];
 676         }
 677         return;
 678     }
 679
 680     /**
 681      * Set the current feed type being exported to "rss" or "atom". This allows
 682      * other objects to gracefully choose whether to execute or not, depending
 683      * on their appropriateness for the current type, e.g. renderers.
 684      *
 685      * @param string $type
 686      * @return Entry
 687      */
 688     public function setType($type)
 689     {
 690         $this->type = $type;
 691         return $this;
 692     }
 693
 694     /**
 695      * Retrieve the current or last feed type exported.
 696      *
 697      * @return string Value will be "rss" or "atom"
 698      */
 699     public function getType()
 700     {
 701         return $this->type;
 702     }
 703
 704     /**
 705      * Method overloading: call given method on first extension implementing it
 706      *
 707      * @param  string $method
 708      * @param  array $args
 709      * @return mixed
 710      * @throws Exception\BadMethodCallException if no extensions implements the method
 711      */
 712     public function __call($method, $args)
 713     {
 714         foreach ($this->extensions as $extension) {
 715             try {
 716                 return call_user_func_array([$extension, $method], $args);
 717             } catch (\BadMethodCallException $e) {
 718             }
 719         }
 720         throw new Exception\BadMethodCallException('Method: ' . $method
 721             . ' does not exist and could not be located on a registered Extension');
 722     }
 723
 724     /**
 725      * Creates a new Zend\Feed\Writer\Source data container for use. This is NOT
 726      * added to the current feed automatically, but is necessary to create a
 727      * container with some initial values preset based on the current feed data.
 728      *
 729      * @return Source
 730      */
 731     public function createSource()
 732     {
 733         $source = new Source;
 734         if ($this->getEncoding()) {
 735             $source->setEncoding($this->getEncoding());
 736         }
 737         $source->setType($this->getType());
 738         return $source;
 739     }
 740
 741     /**
 742      * Appends a Zend\Feed\Writer\Entry object representing a new entry/item
 743      * the feed data container's internal group of entries.
 744      *
 745      * @param Source $source
 746      * @return Entry
 747      */
 748     public function setSource(Source $source)
 749     {
 750         $this->data['source'] = $source;
 751         return $this;
 752     }
 753
 754     /**
 755      * @return Source
 756      */
 757     public function getSource()
 758     {
 759         if (isset($this->data['source'])) {
 760             return $this->data['source'];
 761         }
 762         return;
 763     }
 764
 765     /**
 766      * Load extensions from Zend\Feed\Writer\Writer
 767      *
 768      * @return void
 769      */
 770     // @codingStandardsIgnoreStart
 771     protected function _loadExtensions()
 772     {
 773         // @codingStandardsIgnoreEnd
 774         $all     = Writer::getExtensions();
 775         $manager = Writer::getExtensionManager();
 776         $exts    = $all['entry'];
 777         foreach ($exts as $ext) {
 778             $this->extensions[$ext] = $manager->get($ext);
 779             $this->extensions[$ext]->setEncoding($this->getEncoding());
 780         }
 781     }
 782 }