vendor/Zend/Mvc/Controller/Plugin/FlashMessenger.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\Mvc\Controller\Plugin;
  11
  12 use ArrayIterator;
  13 use Countable;
  14 use IteratorAggregate;
  15 use Zend\Session\Container;
  16 use Zend\Session\ManagerInterface as Manager;
  17 use Zend\Stdlib\SplQueue;
  18
  19 /**
  20  * Flash Messenger - implement session-based messages
  21  */
  22 class FlashMessenger extends AbstractPlugin implements IteratorAggregate, Countable
  23 {
  24     /**
  25      * Default messages namespace
  26      */
  27     const NAMESPACE_DEFAULT = 'default';
  28
  29     /**
  30      * Success messages namespace
  31      */
  32     const NAMESPACE_SUCCESS = 'success';
  33
  34     /**
  35      * Warning messages namespace
  36      */
  37     const NAMESPACE_WARNING = 'warning';
  38
  39     /**
  40      * Error messages namespace
  41      */
  42     const NAMESPACE_ERROR = 'error';
  43
  44     /**
  45      * Info messages namespace
  46      */
  47     const NAMESPACE_INFO = 'info';
  48
  49     /**
  50      * @var Container
  51      */
  52     protected $container;
  53
  54     /**
  55      * Messages from previous request
  56      * @var array
  57      */
  58     protected $messages = [];
  59
  60     /**
  61      * @var Manager
  62      */
  63     protected $session;
  64
  65     /**
  66      * Whether a message has been added during this request
  67      *
  68      * @var bool
  69      */
  70     protected $messageAdded = false;
  71
  72     /**
  73      * Instance namespace, default is 'default'
  74      *
  75      * @var string
  76      */
  77     protected $namespace = self::NAMESPACE_DEFAULT;
  78
  79     /**
  80      * Set the session manager
  81      *
  82      * @param  Manager        $manager
  83      * @return FlashMessenger
  84      */
  85     public function setSessionManager(Manager $manager)
  86     {
  87         $this->session = $manager;
  88
  89         return $this;
  90     }
  91
  92     /**
  93      * Retrieve the session manager
  94      *
  95      * If none composed, lazy-loads a SessionManager instance
  96      *
  97      * @return Manager
  98      */
  99     public function getSessionManager()
 100     {
 101         if (!$this->session instanceof Manager) {
 102             $this->setSessionManager(Container::getDefaultManager());
 103         }
 104
 105         return $this->session;
 106     }
 107
 108     /**
 109      * Get session container for flash messages
 110      *
 111      * @return Container
 112      */
 113     public function getContainer()
 114     {
 115         if ($this->container instanceof Container) {
 116             return $this->container;
 117         }
 118
 119         $manager = $this->getSessionManager();
 120         $this->container = new Container('FlashMessenger', $manager);
 121
 122         return $this->container;
 123     }
 124
 125     /**
 126      * Change the namespace messages are added to
 127      *
 128      * Useful for per action controller messaging between requests
 129      *
 130      * @param  string         $namespace
 131      * @return FlashMessenger Provides a fluent interface
 132      */
 133     public function setNamespace($namespace = 'default')
 134     {
 135         $this->namespace = $namespace;
 136
 137         return $this;
 138     }
 139
 140     /**
 141      * Get the message namespace
 142      *
 143      * @return string
 144      */
 145     public function getNamespace()
 146     {
 147         return $this->namespace;
 148     }
 149
 150     /**
 151      * Add a message
 152      *
 153      * @param  string         $message
 154      * @param  null|string    $namespace
 155      * @param  null|int       $hops
 156      * @return FlashMessenger Provides a fluent interface
 157      */
 158     public function addMessage($message, $namespace = null, $hops = 1)
 159     {
 160         $container = $this->getContainer();
 161
 162         if (null === $namespace) {
 163             $namespace = $this->getNamespace();
 164         }
 165
 166         if (! $this->messageAdded) {
 167             $this->getMessagesFromContainer();
 168             $container->setExpirationHops($hops, null);
 169         }
 170
 171         if (! isset($container->{$namespace})
 172             || ! $container->{$namespace} instanceof SplQueue
 173         ) {
 174             $container->{$namespace} = new SplQueue();
 175         }
 176
 177         $container->{$namespace}->push($message);
 178
 179         $this->messageAdded = true;
 180
 181         return $this;
 182     }
 183
 184     /**
 185      * Add a message with "info" type
 186      *
 187      * @param  string         $message
 188      * @return FlashMessenger
 189      */
 190     public function addInfoMessage($message)
 191     {
 192         $this->addMessage($message, self::NAMESPACE_INFO);
 193
 194         return $this;
 195     }
 196
 197     /**
 198      * Add a message with "success" type
 199      *
 200      * @param  string         $message
 201      * @return FlashMessenger
 202      */
 203     public function addSuccessMessage($message)
 204     {
 205         $this->addMessage($message, self::NAMESPACE_SUCCESS);
 206
 207         return $this;
 208     }
 209
 210     /**
 211      * Add a message with "warning" type
 212      *
 213      * @param string        $message
 214      * @return FlashMessenger
 215      */
 216     public function addWarningMessage($message)
 217     {
 218         $this->addMessage($message, self::NAMESPACE_WARNING);
 219
 220         return $this;
 221     }
 222
 223     /**
 224      * Add a message with "error" type
 225      *
 226      * @param  string         $message
 227      * @return FlashMessenger
 228      */
 229     public function addErrorMessage($message)
 230     {
 231         $this->addMessage($message, self::NAMESPACE_ERROR);
 232
 233         return $this;
 234     }
 235
 236     /**
 237      * Whether a specific namespace has messages
 238      *
 239      * @param  string         $namespace
 240      * @return bool
 241      */
 242     public function hasMessages($namespace = null)
 243     {
 244         if (null === $namespace) {
 245             $namespace = $this->getNamespace();
 246         }
 247
 248         $this->getMessagesFromContainer();
 249
 250         return isset($this->messages[$namespace]);
 251     }
 252
 253     /**
 254      * Whether "info" namespace has messages
 255      *
 256      * @return bool
 257      */
 258     public function hasInfoMessages()
 259     {
 260         return $this->hasMessages(self::NAMESPACE_INFO);
 261     }
 262
 263     /**
 264      * Whether "success" namespace has messages
 265      *
 266      * @return bool
 267      */
 268     public function hasSuccessMessages()
 269     {
 270         return $this->hasMessages(self::NAMESPACE_SUCCESS);
 271     }
 272
 273     /**
 274      * Whether "warning" namespace has messages
 275      *
 276      * @return bool
 277      */
 278     public function hasWarningMessages()
 279     {
 280         return $this->hasMessages(self::NAMESPACE_WARNING);
 281     }
 282
 283     /**
 284      * Whether "error" namespace has messages
 285      *
 286      * @return bool
 287      */
 288     public function hasErrorMessages()
 289     {
 290         return $this->hasMessages(self::NAMESPACE_ERROR);
 291     }
 292
 293     /**
 294      * Get messages from a specific namespace
 295      *
 296      * @param  string         $namespace
 297      * @return array
 298      */
 299     public function getMessages($namespace = null)
 300     {
 301         if (null === $namespace) {
 302             $namespace = $this->getNamespace();
 303         }
 304
 305         if ($this->hasMessages($namespace)) {
 306             return $this->messages[$namespace]->toArray();
 307         }
 308
 309         return [];
 310     }
 311
 312     /**
 313      * Get messages from "info" namespace
 314      *
 315      * @return array
 316      */
 317     public function getInfoMessages()
 318     {
 319         return $this->getMessages(self::NAMESPACE_INFO);
 320     }
 321
 322     /**
 323      * Get messages from "success" namespace
 324      *
 325      * @return array
 326      */
 327     public function getSuccessMessages()
 328     {
 329         return $this->getMessages(self::NAMESPACE_SUCCESS);
 330     }
 331
 332     /**
 333      * Get messages from "warning" namespace
 334      *
 335      * @return array
 336      */
 337     public function getWarningMessages()
 338     {
 339         return $this->getMessages(self::NAMESPACE_WARNING);
 340     }
 341
 342     /**
 343      * Get messages from "error" namespace
 344      *
 345      * @return array
 346      */
 347     public function getErrorMessages()
 348     {
 349         return $this->getMessages(self::NAMESPACE_ERROR);
 350     }
 351
 352     /**
 353      * Clear all messages from the previous request & current namespace
 354      *
 355      * @param  string $namespace
 356      * @return bool True if messages were cleared, false if none existed
 357      */
 358     public function clearMessages($namespace = null)
 359     {
 360         if (null === $namespace) {
 361             $namespace = $this->getNamespace();
 362         }
 363
 364         if ($this->hasMessages($namespace)) {
 365             unset($this->messages[$namespace]);
 366
 367             return true;
 368         }
 369
 370         return false;
 371     }
 372
 373     /**
 374      * Clear all messages from specific namespace
 375      *
 376      * @param  string $namespaceToClear
 377      * @return bool True if messages were cleared, false if none existed
 378      */
 379     public function clearMessagesFromNamespace($namespaceToClear)
 380     {
 381         return $this->clearMessages($namespaceToClear);
 382     }
 383
 384     /**
 385      * Clear all messages from the container
 386      *
 387      * @return bool True if messages were cleared, false if none existed
 388      */
 389     public function clearMessagesFromContainer()
 390     {
 391         $this->getMessagesFromContainer();
 392         if (empty($this->messages)) {
 393             return false;
 394         }
 395         unset($this->messages);
 396         $this->messages = [];
 397
 398         return true;
 399     }
 400
 401     /**
 402      * Check to see if messages have been added to the current
 403      * namespace within this request
 404      *
 405      * @param  string $namespace
 406      * @return bool
 407      */
 408     public function hasCurrentMessages($namespace = null)
 409     {
 410         $container = $this->getContainer();
 411         if (null === $namespace) {
 412             $namespace = $this->getNamespace();
 413         }
 414
 415         return isset($container->{$namespace});
 416     }
 417
 418     /**
 419      * Check to see if messages have been added to "info"
 420      * namespace within this request
 421      *
 422      * @return bool
 423      */
 424     public function hasCurrentInfoMessages()
 425     {
 426         return $this->hasCurrentMessages(self::NAMESPACE_INFO);
 427     }
 428
 429     /**
 430      * Check to see if messages have been added to "success"
 431      * namespace within this request
 432      *
 433      * @return bool
 434      */
 435     public function hasCurrentSuccessMessages()
 436     {
 437         return $this->hasCurrentMessages(self::NAMESPACE_SUCCESS);
 438     }
 439
 440     /**
 441      * Check to see if messages have been added to "warning"
 442      * namespace within this request
 443      *
 444      * @return bool
 445      */
 446     public function hasCurrentWarningMessages()
 447     {
 448         return $this->hasCurrentMessages(self::NAMESPACE_WARNING);
 449     }
 450
 451     /**
 452      * Check to see if messages have been added to "error"
 453      * namespace within this request
 454      *
 455      * @return bool
 456      */
 457     public function hasCurrentErrorMessages()
 458     {
 459         return $this->hasCurrentMessages(self::NAMESPACE_ERROR);
 460     }
 461
 462     /**
 463      * Get messages that have been added to the current
 464      * namespace within this request
 465      *
 466      * @param  string $namespace
 467      * @return array
 468      */
 469     public function getCurrentMessages($namespace = null)
 470     {
 471         if (null === $namespace) {
 472             $namespace = $this->getNamespace();
 473         }
 474
 475         if ($this->hasCurrentMessages($namespace)) {
 476             $container = $this->getContainer();
 477
 478             return $container->{$namespace}->toArray();
 479         }
 480
 481         return [];
 482     }
 483
 484     /**
 485      * Get messages that have been added to the "info"
 486      * namespace within this request
 487      *
 488      * @return array
 489      */
 490     public function getCurrentInfoMessages()
 491     {
 492         return $this->getCurrentMessages(self::NAMESPACE_INFO);
 493     }
 494
 495     /**
 496      * Get messages that have been added to the "success"
 497      * namespace within this request
 498      *
 499      * @return array
 500      */
 501     public function getCurrentSuccessMessages()
 502     {
 503         return $this->getCurrentMessages(self::NAMESPACE_SUCCESS);
 504     }
 505
 506     /**
 507      * Get messages that have been added to the "warning"
 508      * namespace within this request
 509      *
 510      * @return array
 511      */
 512     public function getCurrentWarningMessages()
 513     {
 514         return $this->getCurrentMessages(self::NAMESPACE_WARNING);
 515     }
 516
 517     /**
 518      * Get messages that have been added to the "error"
 519      * namespace within this request
 520      *
 521      * @return array
 522      */
 523     public function getCurrentErrorMessages()
 524     {
 525         return $this->getCurrentMessages(self::NAMESPACE_ERROR);
 526     }
 527
 528     /**
 529      * Get messages that have been added to the current
 530      * namespace in specific namespace
 531      *
 532      * @param  string $namespaceToGet
 533      * @return array
 534      */
 535     public function getCurrentMessagesFromNamespace($namespaceToGet)
 536     {
 537         return $this->getCurrentMessages($namespaceToGet);
 538     }
 539
 540     /**
 541      * Clear messages from the current request and current namespace
 542      *
 543      * @param  string $namespace
 544      * @return bool True if current messages were cleared, false if none existed.
 545      */
 546     public function clearCurrentMessages($namespace = null)
 547     {
 548         if (null === $namespace) {
 549             $namespace = $this->getNamespace();
 550         }
 551
 552         if ($this->hasCurrentMessages($namespace)) {
 553             $container = $this->getContainer();
 554             unset($container->{$namespace});
 555
 556             return true;
 557         }
 558
 559         return false;
 560     }
 561
 562     /**
 563      * Clear messages from the current namespace
 564      *
 565      * @param  string $namespaceToClear
 566      * @return bool True if current messages were cleared from the given namespace, false if none existed.
 567      */
 568     public function clearCurrentMessagesFromNamespace($namespaceToClear)
 569     {
 570         return $this->clearCurrentMessages($namespaceToClear);
 571     }
 572
 573     /**
 574      * Clear messages from the container
 575      *
 576      * @return bool True if current messages were cleared from the container, false if none existed.
 577      */
 578     public function clearCurrentMessagesFromContainer()
 579     {
 580         $container = $this->getContainer();
 581
 582         $namespaces = [];
 583         foreach ($container as $namespace => $messages) {
 584             $namespaces[] = $namespace;
 585         }
 586
 587         if (empty($namespaces)) {
 588             return false;
 589         }
 590
 591         foreach ($namespaces as $namespace) {
 592             unset($container->{$namespace});
 593         }
 594
 595         return true;
 596     }
 597
 598     /**
 599      * Complete the IteratorAggregate interface, for iterating
 600      *
 601      * @return ArrayIterator
 602      */
 603     public function getIterator()
 604     {
 605         if ($this->hasMessages()) {
 606             return new ArrayIterator($this->getMessages());
 607         }
 608
 609         return new ArrayIterator();
 610     }
 611
 612     /**
 613      * Complete the countable interface
 614      *
 615      * @return int
 616      */
 617     public function count()
 618     {
 619         if ($this->hasMessages()) {
 620             return count($this->getMessages());
 621         }
 622
 623         return 0;
 624     }
 625
 626     /**
 627      * Get messages from a specific namespace
 628      *
 629      * @param  string $namespaceToGet
 630      * @return array
 631      */
 632     public function getMessagesFromNamespace($namespaceToGet)
 633     {
 634         return $this->getMessages($namespaceToGet);
 635     }
 636
 637     /**
 638      * Pull messages from the session container
 639      *
 640      * Iterates through the session container, removing messages into the local
 641      * scope.
 642      *
 643      * @return void
 644      */
 645     protected function getMessagesFromContainer()
 646     {
 647         if (!empty($this->messages) || $this->messageAdded) {
 648             return;
 649         }
 650
 651         $container = $this->getContainer();
 652
 653         $namespaces = [];
 654         foreach ($container as $namespace => $messages) {
 655             $this->messages[$namespace] = $messages;
 656             $namespaces[] = $namespace;
 657         }
 658
 659         foreach ($namespaces as $namespace) {
 660             unset($container->{$namespace});
 661         }
 662     }
 663 }