library/Zend/Layout.php

   1 <?php
   2 /**
   3  * Zend Framework
   4  *
   5  * LICENSE
   6  *
   7  * This source file is subject to the new BSD license that is bundled
   8  * with this package in the file LICENSE.txt.
   9  * It is also available through the world-wide-web at this URL:
  10  * http://framework.zend.com/license/new-bsd
  11  * If you did not receive a copy of the license and are unable to
  12  * obtain it through the world-wide-web, please send an email
  13  * to license@zend.com so we can send you a copy immediately.
  14  *
  15  * @category   Zend
  16  * @package    Zend_Layout
  17  * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
  18  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  19  * @version    $Id$
  20  */
  21
  22 /**
  23  * Provide Layout support for MVC applications
  24  *
  25  * @category   Zend
  26  * @package    Zend_Layout
  27  * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
  28  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  29  */
  30 class Zend_Layout
  31 {
  32     /**
  33      * Placeholder container for layout variables
  34      * @var Zend_View_Helper_Placeholder_Container
  35      */
  36     protected $_container;
  37
  38     /**
  39      * Key used to store content from 'default' named response segment
  40      * @var string
  41      */
  42     protected $_contentKey = 'content';
  43
  44     /**
  45      * Are layouts enabled?
  46      * @var bool
  47      */
  48     protected $_enabled = true;
  49
  50     /**
  51      * Helper class
  52      * @var string
  53      */
  54     protected $_helperClass = 'Zend_Layout_Controller_Action_Helper_Layout';
  55
  56     /**
  57      * Inflector used to resolve layout script
  58      * @var Zend_Filter_Inflector
  59      */
  60     protected $_inflector;
  61
  62     /**
  63      * Flag: is inflector enabled?
  64      * @var bool
  65      */
  66     protected $_inflectorEnabled = true;
  67
  68     /**
  69      * Inflector target
  70      * @var string
  71      */
  72     protected $_inflectorTarget = ':script.:suffix';
  73
  74     /**
  75      * Layout view
  76      * @var string
  77      */
  78     protected $_layout = 'layout';
  79
  80     /**
  81      * Layout view script path
  82      * @var string
  83      */
  84     protected $_viewScriptPath = null;
  85
  86     protected $_viewBasePath = null;
  87     protected $_viewBasePrefix = 'Layout_View';
  88
  89     /**
  90      * Flag: is MVC integration enabled?
  91      * @var bool
  92      */
  93     protected $_mvcEnabled = true;
  94
  95     /**
  96      * Instance registered with MVC, if any
  97      * @var Zend_Layout
  98      */
  99     protected static $_mvcInstance;
 100
 101     /**
 102      * Flag: is MVC successful action only flag set?
 103      * @var bool
 104      */
 105     protected $_mvcSuccessfulActionOnly = true;
 106
 107     /**
 108      * Plugin class
 109      * @var string
 110      */
 111     protected $_pluginClass = 'Zend_Layout_Controller_Plugin_Layout';
 112
 113     /**
 114      * @var Zend_View_Interface
 115      */
 116     protected $_view;
 117
 118     /**
 119      * View script suffix for layout script
 120      * @var string
 121      */
 122     protected $_viewSuffix = 'phtml';
 123
 124     /**
 125      * Constructor
 126      *
 127      * Accepts either:
 128      * - A string path to layouts
 129      * - An array of options
 130      * - A Zend_Config object with options
 131      *
 132      * Layout script path, either as argument or as key in options, is
 133      * required.
 134      *
 135      * If mvcEnabled flag is false from options, simply sets layout script path.
 136      * Otherwise, also instantiates and registers action helper and controller
 137      * plugin.
 138      *
 139      * @param  string|array|Zend_Config $options
 140      * @return void
 141      */
 142     public function __construct($options = null, $initMvc = false)
 143     {
 144         if (null !== $options) {
 145             if (is_string($options)) {
 146                 $this->setLayoutPath($options);
 147             } elseif (is_array($options)) {
 148                 $this->setOptions($options);
 149             } elseif ($options instanceof Zend_Config) {
 150                 $this->setConfig($options);
 151             } else {
 152                 require_once 'Zend/Layout/Exception.php';
 153                 throw new Zend_Layout_Exception('Invalid option provided to constructor');
 154             }
 155         }
 156
 157         $this->_initVarContainer();
 158
 159         if ($initMvc) {
 160             $this->_setMvcEnabled(true);
 161             $this->_initMvc();
 162         } else {
 163             $this->_setMvcEnabled(false);
 164         }
 165     }
 166
 167     /**
 168      * Static method for initialization with MVC support
 169      *
 170      * @param  string|array|Zend_Config $options
 171      * @return Zend_Layout
 172      */
 173     public static function startMvc($options = null)
 174     {
 175         if (null === self::$_mvcInstance) {
 176             self::$_mvcInstance = new self($options, true);
 177         }
 178
 179         if (is_string($options)) {
 180             self::$_mvcInstance->setLayoutPath($options);
 181         } elseif (is_array($options) || $options instanceof Zend_Config) {
 182             self::$_mvcInstance->setOptions($options);
 183         }
 184
 185         return self::$_mvcInstance;
 186     }
 187
 188     /**
 189      * Retrieve MVC instance of Zend_Layout object
 190      *
 191      * @return Zend_Layout|null
 192      */
 193     public static function getMvcInstance()
 194     {
 195         return self::$_mvcInstance;
 196     }
 197
 198     /**
 199      * Reset MVC instance
 200      *
 201      * Unregisters plugins and helpers, and destroys MVC layout instance.
 202      *
 203      * @return void
 204      */
 205     public static function resetMvcInstance()
 206     {
 207         if (null !== self::$_mvcInstance) {
 208             $layout = self::$_mvcInstance;
 209             $pluginClass = $layout->getPluginClass();
 210             $front = Zend_Controller_Front::getInstance();
 211             if ($front->hasPlugin($pluginClass)) {
 212                 $front->unregisterPlugin($pluginClass);
 213             }
 214
 215             if (Zend_Controller_Action_HelperBroker::hasHelper('layout')) {
 216                 Zend_Controller_Action_HelperBroker::removeHelper('layout');
 217             }
 218
 219             unset($layout);
 220             self::$_mvcInstance = null;
 221         }
 222     }
 223
 224     /**
 225      * Set options en masse
 226      *
 227      * @param  array|Zend_Config $options
 228      * @return void
 229      */
 230     public function setOptions($options)
 231     {
 232         if ($options instanceof Zend_Config) {
 233             $options = $options->toArray();
 234         } elseif (!is_array($options)) {
 235             require_once 'Zend/Layout/Exception.php';
 236             throw new Zend_Layout_Exception('setOptions() expects either an array or a Zend_Config object');
 237         }
 238
 239         foreach ($options as $key => $value) {
 240             $method = 'set' . ucfirst($key);
 241             if (method_exists($this, $method)) {
 242                 $this->$method($value);
 243             }
 244         }
 245     }
 246
 247     /**
 248      * Initialize MVC integration
 249      *
 250      * @return void
 251      */
 252     protected function _initMvc()
 253     {
 254         $this->_initPlugin();
 255         $this->_initHelper();
 256     }
 257
 258     /**
 259      * Initialize front controller plugin
 260      *
 261      * @return void
 262      */
 263     protected function _initPlugin()
 264     {
 265         $pluginClass = $this->getPluginClass();
 266         require_once 'Zend/Controller/Front.php';
 267         $front = Zend_Controller_Front::getInstance();
 268         if (!$front->hasPlugin($pluginClass)) {
 269             if (!class_exists($pluginClass)) {
 270                 require_once 'Zend/Loader.php';
 271                 Zend_Loader::loadClass($pluginClass);
 272             }
 273             $front->registerPlugin(
 274                 // register to run last | BUT before the ErrorHandler (if its available)
 275                 new $pluginClass($this),
 276                 99
 277             );
 278         }
 279     }
 280
 281     /**
 282      * Initialize action helper
 283      *
 284      * @return void
 285      */
 286     protected function _initHelper()
 287     {
 288         $helperClass = $this->getHelperClass();
 289         require_once 'Zend/Controller/Action/HelperBroker.php';
 290         if (!Zend_Controller_Action_HelperBroker::hasHelper('layout')) {
 291             if (!class_exists($helperClass)) {
 292                 require_once 'Zend/Loader.php';
 293                 Zend_Loader::loadClass($helperClass);
 294             }
 295             Zend_Controller_Action_HelperBroker::getStack()->offsetSet(-90, new $helperClass($this));
 296         }
 297     }
 298
 299     /**
 300      * Set options from a config object
 301      *
 302      * @param  Zend_Config $config
 303      * @return Zend_Layout
 304      */
 305     public function setConfig(Zend_Config $config)
 306     {
 307         $this->setOptions($config->toArray());
 308         return $this;
 309     }
 310
 311     /**
 312      * Initialize placeholder container for layout vars
 313      *
 314      * @return Zend_View_Helper_Placeholder_Container
 315      */
 316     protected function _initVarContainer()
 317     {
 318         if (null === $this->_container) {
 319             require_once 'Zend/View/Helper/Placeholder/Registry.php';
 320             $this->_container = Zend_View_Helper_Placeholder_Registry::getRegistry()->getContainer(__CLASS__);
 321         }
 322
 323         return $this->_container;
 324     }
 325
 326     /**
 327      * Set layout script to use
 328      *
 329      * Note: enables layout by default, can be disabled
 330      *
 331      * @param  string $name
 332      * @param  boolean $enabled
 333      * @return Zend_Layout
 334      */
 335     public function setLayout($name, $enabled = true)
 336     {
 337         $this->_layout = (string) $name;
 338         if ($enabled) {
 339             $this->enableLayout();
 340         }
 341         return $this;
 342     }
 343
 344     /**
 345      * Get current layout script
 346      *
 347      * @return string
 348      */
 349     public function getLayout()
 350     {
 351         return $this->_layout;
 352     }
 353
 354     /**
 355      * Disable layout
 356      *
 357      * @return Zend_Layout
 358      */
 359     public function disableLayout()
 360     {
 361         $this->_enabled = false;
 362         return $this;
 363     }
 364
 365     /**
 366      * Enable layout
 367      *
 368      * @return Zend_Layout
 369      */
 370     public function enableLayout()
 371     {
 372         $this->_enabled = true;
 373         return $this;
 374     }
 375
 376     /**
 377      * Is layout enabled?
 378      *
 379      * @return bool
 380      */
 381     public function isEnabled()
 382     {
 383         return $this->_enabled;
 384     }
 385
 386
 387     public function setViewBasePath($path, $prefix = 'Layout_View')
 388     {
 389         $this->_viewBasePath = $path;
 390         $this->_viewBasePrefix = $prefix;
 391         return $this;
 392     }
 393
 394     public function getViewBasePath()
 395     {
 396         return $this->_viewBasePath;
 397     }
 398
 399     public function setViewScriptPath($path)
 400     {
 401         $this->_viewScriptPath = $path;
 402         return $this;
 403     }
 404
 405     public function getViewScriptPath()
 406     {
 407         return $this->_viewScriptPath;
 408     }
 409
 410     /**
 411      * Set layout script path
 412      *
 413      * @param  string $path
 414      * @return Zend_Layout
 415      */
 416     public function setLayoutPath($path)
 417     {
 418         return $this->setViewScriptPath($path);
 419     }
 420
 421     /**
 422      * Get current layout script path
 423      *
 424      * @return string
 425      */
 426     public function getLayoutPath()
 427     {
 428         return $this->getViewScriptPath();
 429     }
 430
 431     /**
 432      * Set content key
 433      *
 434      * Key in namespace container denoting default content
 435      *
 436      * @param  string $contentKey
 437      * @return Zend_Layout
 438      */
 439     public function setContentKey($contentKey)
 440     {
 441         $this->_contentKey = (string) $contentKey;
 442         return $this;
 443     }
 444
 445     /**
 446      * Retrieve content key
 447      *
 448      * @return string
 449      */
 450     public function getContentKey()
 451     {
 452         return $this->_contentKey;
 453     }
 454
 455     /**
 456      * Set MVC enabled flag
 457      *
 458      * @param  bool $mvcEnabled
 459      * @return Zend_Layout
 460      */
 461     protected function _setMvcEnabled($mvcEnabled)
 462     {
 463         $this->_mvcEnabled = ($mvcEnabled) ? true : false;
 464         return $this;
 465     }
 466
 467     /**
 468      * Retrieve MVC enabled flag
 469      *
 470      * @return bool
 471      */
 472     public function getMvcEnabled()
 473     {
 474         return $this->_mvcEnabled;
 475     }
 476
 477     /**
 478      * Set MVC Successful Action Only flag
 479      *
 480      * @param bool $successfulActionOnly
 481      * @return Zend_Layout
 482      */
 483     public function setMvcSuccessfulActionOnly($successfulActionOnly)
 484     {
 485         $this->_mvcSuccessfulActionOnly = ($successfulActionOnly) ? true : false;
 486         return $this;
 487     }
 488
 489     /**
 490      * Get MVC Successful Action Only Flag
 491      *
 492      * @return bool
 493      */
 494     public function getMvcSuccessfulActionOnly()
 495     {
 496         return $this->_mvcSuccessfulActionOnly;
 497     }
 498
 499     /**
 500      * Set view object
 501      *
 502      * @param  Zend_View_Interface $view
 503      * @return Zend_Layout
 504      */
 505     public function setView(Zend_View_Interface $view)
 506     {
 507         $this->_view = $view;
 508         return $this;
 509     }
 510
 511     /**
 512      * Retrieve helper class
 513      *
 514      * @return string
 515      */
 516     public function getHelperClass()
 517     {
 518         return $this->_helperClass;
 519     }
 520
 521     /**
 522      * Set helper class
 523      *
 524      * @param  string $helperClass
 525      * @return Zend_Layout
 526      */
 527     public function setHelperClass($helperClass)
 528     {
 529         $this->_helperClass = (string) $helperClass;
 530         return $this;
 531     }
 532
 533     /**
 534      * Retrieve plugin class
 535      *
 536      * @return string
 537      */
 538     public function getPluginClass()
 539     {
 540         return $this->_pluginClass;
 541     }
 542
 543     /**
 544      * Set plugin class
 545      *
 546      * @param  string $pluginClass
 547      * @return Zend_Layout
 548      */
 549     public function setPluginClass($pluginClass)
 550     {
 551         $this->_pluginClass = (string) $pluginClass;
 552         return $this;
 553     }
 554
 555     /**
 556      * Get current view object
 557      *
 558      * If no view object currently set, retrieves it from the ViewRenderer.
 559      *
 560      * @todo Set inflector from view renderer at same time
 561      * @return Zend_View_Interface
 562      */
 563     public function getView()
 564     {
 565         if (null === $this->_view) {
 566             require_once 'Zend/Controller/Action/HelperBroker.php';
 567             $viewRenderer = Zend_Controller_Action_HelperBroker::getStaticHelper('viewRenderer');
 568             if (null === $viewRenderer->view) {
 569                 $viewRenderer->initView();
 570             }
 571             $this->setView($viewRenderer->view);
 572         }
 573         return $this->_view;
 574     }
 575
 576     /**
 577      * Set layout view script suffix
 578      *
 579      * @param  string $viewSuffix
 580      * @return Zend_Layout
 581      */
 582     public function setViewSuffix($viewSuffix)
 583     {
 584         $this->_viewSuffix = (string) $viewSuffix;
 585         return $this;
 586     }
 587
 588     /**
 589      * Retrieve layout view script suffix
 590      *
 591      * @return string
 592      */
 593     public function getViewSuffix()
 594     {
 595         return $this->_viewSuffix;
 596     }
 597
 598     /**
 599      * Retrieve inflector target
 600      *
 601      * @return string
 602      */
 603     public function getInflectorTarget()
 604     {
 605         return $this->_inflectorTarget;
 606     }
 607
 608     /**
 609      * Set inflector target
 610      *
 611      * @param  string $inflectorTarget
 612      * @return Zend_Layout
 613      */
 614     public function setInflectorTarget($inflectorTarget)
 615     {
 616         $this->_inflectorTarget = (string) $inflectorTarget;
 617         return $this;
 618     }
 619
 620     /**
 621      * Set inflector to use when resolving layout names
 622      *
 623      * @param  Zend_Filter_Inflector $inflector
 624      * @return Zend_Layout
 625      */
 626     public function setInflector(Zend_Filter_Inflector $inflector)
 627     {
 628         $this->_inflector = $inflector;
 629         return $this;
 630     }
 631
 632     /**
 633      * Retrieve inflector
 634      *
 635      * @return Zend_Filter_Inflector
 636      */
 637     public function getInflector()
 638     {
 639         if (null === $this->_inflector) {
 640             require_once 'Zend/Filter/Inflector.php';
 641             $inflector = new Zend_Filter_Inflector();
 642             $inflector->setTargetReference($this->_inflectorTarget)
 643                       ->addRules(array(':script' => array('Word_CamelCaseToDash', 'StringToLower')))
 644                       ->setStaticRuleReference('suffix', $this->_viewSuffix);
 645             $this->setInflector($inflector);
 646         }
 647
 648         return $this->_inflector;
 649     }
 650
 651     /**
 652      * Enable inflector
 653      *
 654      * @return Zend_Layout
 655      */
 656     public function enableInflector()
 657     {
 658         $this->_inflectorEnabled = true;
 659         return $this;
 660     }
 661
 662     /**
 663      * Disable inflector
 664      *
 665      * @return Zend_Layout
 666      */
 667     public function disableInflector()
 668     {
 669         $this->_inflectorEnabled = false;
 670         return $this;
 671     }
 672
 673     /**
 674      * Return status of inflector enabled flag
 675      *
 676      * @return bool
 677      */
 678     public function inflectorEnabled()
 679     {
 680         return $this->_inflectorEnabled;
 681     }
 682
 683     /**
 684      * Set layout variable
 685      *
 686      * @param  string $key
 687      * @param  mixed $value
 688      * @return void
 689      */
 690     public function __set($key, $value)
 691     {
 692         $this->_container[$key] = $value;
 693     }
 694
 695     /**
 696      * Get layout variable
 697      *
 698      * @param  string $key
 699      * @return mixed
 700      */
 701     public function __get($key)
 702     {
 703         if (isset($this->_container[$key])) {
 704             return $this->_container[$key];
 705         }
 706
 707         return null;
 708     }
 709
 710     /**
 711      * Is a layout variable set?
 712      *
 713      * @param  string $key
 714      * @return bool
 715      */
 716     public function __isset($key)
 717     {
 718         return (isset($this->_container[$key]));
 719     }
 720
 721     /**
 722      * Unset a layout variable?
 723      *
 724      * @param  string $key
 725      * @return void
 726      */
 727     public function __unset($key)
 728     {
 729         if (isset($this->_container[$key])) {
 730             unset($this->_container[$key]);
 731         }
 732     }
 733
 734     /**
 735      * Assign one or more layout variables
 736      *
 737      * @param  mixed $spec Assoc array or string key; if assoc array, sets each
 738      * key as a layout variable
 739      * @param  mixed $value Value if $spec is a key
 740      * @return Zend_Layout
 741      * @throws Zend_Layout_Exception if non-array/string value passed to $spec
 742      */
 743     public function assign($spec, $value = null)
 744     {
 745         if (is_array($spec)) {
 746             $orig = $this->_container->getArrayCopy();
 747             $merged = array_merge($orig, $spec);
 748             $this->_container->exchangeArray($merged);
 749             return $this;
 750         }
 751
 752         if (is_string($spec)) {
 753             $this->_container[$spec] = $value;
 754             return $this;
 755         }
 756
 757         require_once 'Zend/Layout/Exception.php';
 758         throw new Zend_Layout_Exception('Invalid values passed to assign()');
 759     }
 760
 761     /**
 762      * Render layout
 763      *
 764      * Sets internal script path as last path on script path stack, assigns
 765      * layout variables to view, determines layout name using inflector, and
 766      * renders layout view script.
 767      *
 768      * $name will be passed to the inflector as the key 'script'.
 769      *
 770      * @param  mixed $name
 771      * @return mixed
 772      */
 773     public function render($name = null)
 774     {
 775         if (null === $name) {
 776             $name = $this->getLayout();
 777         }
 778
 779         if ($this->inflectorEnabled() && (null !== ($inflector = $this->getInflector())))
 780         {
 781             $name = $this->_inflector->filter(array('script' => $name));
 782         }
 783
 784         $view = $this->getView();
 785
 786         if (null !== ($path = $this->getViewScriptPath())) {
 787             if (method_exists($view, 'addScriptPath')) {
 788                 $view->addScriptPath($path);
 789             } else {
 790                 $view->setScriptPath($path);
 791             }
 792         } elseif (null !== ($path = $this->getViewBasePath())) {
 793             $view->addBasePath($path, $this->_viewBasePrefix);
 794         }
 795
 796         return $view->render($name);
 797     }
 798 }