vendor/zendframework/zend-form/src/Element/Collection.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\Form\Element;
  11
  12 use Traversable;
  13 use Zend\Form\Element;
  14 use Zend\Form\ElementInterface;
  15 use Zend\Form\Exception;
  16 use Zend\Form\Fieldset;
  17 use Zend\Form\FieldsetInterface;
  18 use Zend\Form\FormInterface;
  19 use Zend\Stdlib\ArrayUtils;
  20
  21 class Collection extends Fieldset
  22 {
  23     /**
  24      * Default template placeholder
  25      */
  26     const DEFAULT_TEMPLATE_PLACEHOLDER = '__index__';
  27
  28     /**
  29      * Element used in the collection
  30      *
  31      * @var ElementInterface
  32      */
  33     protected $targetElement;
  34
  35     /**
  36      * Initial count of target element
  37      *
  38      * @var int
  39      */
  40     protected $count = 1;
  41
  42     /**
  43      * Are new elements allowed to be added dynamically ?
  44      *
  45      * @var bool
  46      */
  47     protected $allowAdd = true;
  48
  49     /**
  50      * Are existing elements allowed to be removed dynamically ?
  51      *
  52      * @var bool
  53      */
  54     protected $allowRemove = true;
  55
  56     /**
  57      * Is the template generated ?
  58      *
  59      * @var bool
  60      */
  61     protected $shouldCreateTemplate = false;
  62
  63     /**
  64      * Placeholder used in template content for making your life easier with JavaScript
  65      *
  66      * @var string
  67      */
  68     protected $templatePlaceholder = self::DEFAULT_TEMPLATE_PLACEHOLDER;
  69
  70     /**
  71      * Whether or not to create new objects during modify
  72      *
  73      * @var bool
  74      */
  75     protected $createNewObjects = false;
  76
  77     /**
  78      * Element used as a template
  79      *
  80      * @var ElementInterface|FieldsetInterface
  81      */
  82     protected $templateElement;
  83
  84     /**
  85      * The index of the last child element or fieldset
  86      *
  87      * @var int
  88      */
  89     protected $lastChildIndex = -1;
  90
  91     /**
  92      * Should child elements must be created on self::prepareElement()?
  93      *
  94      * @var bool
  95      */
  96     protected $shouldCreateChildrenOnPrepareElement = true;
  97
  98     /**
  99      * Accepted options for Collection:
 100      * - target_element: an array or element used in the collection
 101      * - count: number of times the element is added initially
 102      * - allow_add: if set to true, elements can be added to the form dynamically (using JavaScript)
 103      * - allow_remove: if set to true, elements can be removed to the form
 104      * - should_create_template: if set to true, a template is generated (inside a <span>)
 105      * - template_placeholder: placeholder used in the data template
 106      *
 107      * @param array|Traversable $options
 108      * @return Collection
 109      */
 110     public function setOptions($options)
 111     {
 112         parent::setOptions($options);
 113
 114         if (isset($options['target_element'])) {
 115             $this->setTargetElement($options['target_element']);
 116         }
 117
 118         if (isset($options['count'])) {
 119             $this->setCount($options['count']);
 120         }
 121
 122         if (isset($options['allow_add'])) {
 123             $this->setAllowAdd($options['allow_add']);
 124         }
 125
 126         if (isset($options['allow_remove'])) {
 127             $this->setAllowRemove($options['allow_remove']);
 128         }
 129
 130         if (isset($options['should_create_template'])) {
 131             $this->setShouldCreateTemplate($options['should_create_template']);
 132         }
 133
 134         if (isset($options['template_placeholder'])) {
 135             $this->setTemplatePlaceholder($options['template_placeholder']);
 136         }
 137
 138         if (isset($options['create_new_objects'])) {
 139             $this->setCreateNewObjects($options['create_new_objects']);
 140         }
 141
 142         return $this;
 143     }
 144
 145     /**
 146      * Checks if the object can be set in this fieldset
 147      *
 148      * @param object $object
 149      * @return bool
 150      */
 151     public function allowObjectBinding($object)
 152     {
 153         return true;
 154     }
 155
 156     /**
 157      * Set the object used by the hydrator
 158      * In this case the "object" is a collection of objects
 159      *
 160      * @param  array|Traversable $object
 161      * @return Fieldset|FieldsetInterface
 162      * @throws Exception\InvalidArgumentException
 163      */
 164     public function setObject($object)
 165     {
 166         if (! is_array($object) && ! $object instanceof Traversable) {
 167             throw new Exception\InvalidArgumentException(sprintf(
 168                 '%s expects an array or Traversable object argument; received "%s"',
 169                 __METHOD__,
 170                 (is_object($object) ? get_class($object) : gettype($object))
 171             ));
 172         }
 173
 174         $this->object = $object;
 175         $this->count  = max(count($object), $this->count);
 176
 177         return $this;
 178     }
 179
 180     /**
 181      * Populate values
 182      *
 183      * @param array|Traversable $data
 184      * @throws \Zend\Form\Exception\InvalidArgumentException
 185      * @throws \Zend\Form\Exception\DomainException
 186      * @return void
 187      */
 188     public function populateValues($data)
 189     {
 190         if (! is_array($data) && ! $data instanceof Traversable) {
 191             throw new Exception\InvalidArgumentException(sprintf(
 192                 '%s expects an array or Traversable set of data; received "%s"',
 193                 __METHOD__,
 194                 (is_object($data) ? get_class($data) : gettype($data))
 195             ));
 196         }
 197
 198         if (! $this->allowRemove && count($data) < $this->count) {
 199             throw new Exception\DomainException(sprintf(
 200                 'There are fewer elements than specified in the collection (%s). Either set the allow_remove option '
 201                 . 'to true, or re-submit the form.',
 202                 get_class($this)
 203             ));
 204         }
 205
 206         // Check to see if elements have been replaced or removed
 207         $toRemove = [];
 208         foreach ($this as $name => $elementOrFieldset) {
 209             if (isset($data[$name])) {
 210                 continue;
 211             }
 212
 213             if (! $this->allowRemove) {
 214                 throw new Exception\DomainException(sprintf(
 215                     'Elements have been removed from the collection (%s) but the allow_remove option is not true.',
 216                     get_class($this)
 217                 ));
 218             }
 219
 220             $toRemove[] = $name;
 221         }
 222
 223         foreach ($toRemove as $name) {
 224             $this->remove($name);
 225         }
 226
 227         foreach ($data as $key => $value) {
 228             if ($this->has($key)) {
 229                 $elementOrFieldset = $this->get($key);
 230             } else {
 231                 $elementOrFieldset = $this->addNewTargetElementInstance($key);
 232
 233                 if ($key > $this->lastChildIndex) {
 234                     $this->lastChildIndex = $key;
 235                 }
 236             }
 237
 238             if ($elementOrFieldset instanceof FieldsetInterface) {
 239                 $elementOrFieldset->populateValues($value);
 240             } else {
 241                 $elementOrFieldset->setAttribute('value', $value);
 242             }
 243         }
 244
 245         if (! $this->createNewObjects()) {
 246             $this->replaceTemplateObjects();
 247         }
 248     }
 249
 250     /**
 251      * Checks if this fieldset can bind data
 252      *
 253      * @return bool
 254      */
 255     public function allowValueBinding()
 256     {
 257         return true;
 258     }
 259
 260     /**
 261      * Bind values to the object
 262      *
 263      * @param array $values
 264      * @param array $validationGroup
 265      *
 266      * @return array|mixed|void
 267      */
 268     public function bindValues(array $values = [], array $validationGroup = null)
 269     {
 270         $collection = [];
 271         foreach ($values as $name => $value) {
 272             $element = $this->get($name);
 273
 274             if ($element instanceof FieldsetInterface) {
 275                 $collection[] = $element->bindValues($value, $validationGroup);
 276             } else {
 277                 $collection[] = $value;
 278             }
 279         }
 280
 281         return $collection;
 282     }
 283
 284     /**
 285      * Set the initial count of target element
 286      *
 287      * @param $count
 288      * @return Collection
 289      */
 290     public function setCount($count)
 291     {
 292         $this->count = $count > 0 ? $count : 0;
 293         return $this;
 294     }
 295
 296     /**
 297      * Get the initial count of target element
 298      *
 299      * @return int
 300      */
 301     public function getCount()
 302     {
 303         return $this->count;
 304     }
 305
 306     /**
 307      * Set the target element
 308      *
 309      * @param ElementInterface|array|Traversable $elementOrFieldset
 310      * @return Collection
 311      * @throws \Zend\Form\Exception\InvalidArgumentException
 312      */
 313     public function setTargetElement($elementOrFieldset)
 314     {
 315         if (is_array($elementOrFieldset)
 316             || ($elementOrFieldset instanceof Traversable && ! $elementOrFieldset instanceof ElementInterface)
 317         ) {
 318             $factory = $this->getFormFactory();
 319             $elementOrFieldset = $factory->create($elementOrFieldset);
 320         }
 321
 322         if (! $elementOrFieldset instanceof ElementInterface) {
 323             throw new Exception\InvalidArgumentException(sprintf(
 324                 '%s requires that $elementOrFieldset be an object implementing %s; received "%s"',
 325                 __METHOD__,
 326                 __NAMESPACE__ . '\ElementInterface',
 327                 (is_object($elementOrFieldset) ? get_class($elementOrFieldset) : gettype($elementOrFieldset))
 328             ));
 329         }
 330
 331         $this->targetElement = $elementOrFieldset;
 332
 333         return $this;
 334     }
 335
 336     /**
 337      * Get target element
 338      *
 339      * @return ElementInterface|null
 340      */
 341     public function getTargetElement()
 342     {
 343         return $this->targetElement;
 344     }
 345
 346     /**
 347      * Get allow add
 348      *
 349      * @param bool $allowAdd
 350      * @return Collection
 351      */
 352     public function setAllowAdd($allowAdd)
 353     {
 354         $this->allowAdd = (bool) $allowAdd;
 355         return $this;
 356     }
 357
 358     /**
 359      * Get allow add
 360      *
 361      * @return bool
 362      */
 363     public function allowAdd()
 364     {
 365         return $this->allowAdd;
 366     }
 367
 368     /**
 369      * @param bool $allowRemove
 370      * @return Collection
 371      */
 372     public function setAllowRemove($allowRemove)
 373     {
 374         $this->allowRemove = (bool) $allowRemove;
 375         return $this;
 376     }
 377
 378     /**
 379      * @return bool
 380      */
 381     public function allowRemove()
 382     {
 383         return $this->allowRemove;
 384     }
 385
 386     /**
 387      * If set to true, a template prototype is automatically added to the form
 388      * to ease the creation of dynamic elements through JavaScript
 389      *
 390      * @param bool $shouldCreateTemplate
 391      * @return Collection
 392      */
 393     public function setShouldCreateTemplate($shouldCreateTemplate)
 394     {
 395         $this->shouldCreateTemplate = (bool) $shouldCreateTemplate;
 396
 397         return $this;
 398     }
 399
 400     /**
 401      * Get if the collection should create a template
 402      *
 403      * @return bool
 404      */
 405     public function shouldCreateTemplate()
 406     {
 407         return $this->shouldCreateTemplate;
 408     }
 409
 410     /**
 411      * Set the placeholder used in the template generated to help create new elements in JavaScript
 412      *
 413      * @param string $templatePlaceholder
 414      * @return Collection
 415      */
 416     public function setTemplatePlaceholder($templatePlaceholder)
 417     {
 418         if (is_string($templatePlaceholder)) {
 419             $this->templatePlaceholder = $templatePlaceholder;
 420         }
 421
 422         return $this;
 423     }
 424
 425     /**
 426      * Get the template placeholder
 427      *
 428      * @return string
 429      */
 430     public function getTemplatePlaceholder()
 431     {
 432         return $this->templatePlaceholder;
 433     }
 434
 435     /**
 436      * @param bool $createNewObjects
 437      * @return Collection
 438      */
 439     public function setCreateNewObjects($createNewObjects)
 440     {
 441         $this->createNewObjects = (bool) $createNewObjects;
 442         return $this;
 443     }
 444
 445     /**
 446      * @return bool
 447      */
 448     public function createNewObjects()
 449     {
 450         return $this->createNewObjects;
 451     }
 452
 453     /**
 454      * Get a template element used for rendering purposes only
 455      *
 456      * @return null|ElementInterface|FieldsetInterface
 457      */
 458     public function getTemplateElement()
 459     {
 460         if ($this->templateElement === null) {
 461             $this->templateElement = $this->createTemplateElement();
 462         }
 463
 464         return $this->templateElement;
 465     }
 466
 467     /**
 468      * Prepare the collection by adding a dummy template element if the user want one
 469      *
 470      * @param  FormInterface $form
 471      * @return mixed|void
 472      */
 473     public function prepareElement(FormInterface $form)
 474     {
 475         if (true === $this->shouldCreateChildrenOnPrepareElement) {
 476             if ($this->targetElement !== null && $this->count > 0) {
 477                 while ($this->count > $this->lastChildIndex + 1) {
 478                     $this->addNewTargetElementInstance(++$this->lastChildIndex);
 479                 }
 480             }
 481         }
 482
 483         // Create a template that will also be prepared
 484         if ($this->shouldCreateTemplate) {
 485             $templateElement = $this->getTemplateElement();
 486             $this->add($templateElement);
 487         }
 488
 489         parent::prepareElement($form);
 490
 491         // The template element has been prepared, but we don't want it to be
 492         // rendered nor validated, so remove it from the list.
 493         if ($this->shouldCreateTemplate) {
 494             $this->remove($this->templatePlaceholder);
 495         }
 496     }
 497
 498     /**
 499      * @return array
 500      * @throws \Zend\Form\Exception\InvalidArgumentException
 501      * @throws \Zend\Stdlib\Exception\InvalidArgumentException
 502      * @throws \Zend\Form\Exception\DomainException
 503      * @throws \Zend\Form\Exception\InvalidElementException
 504      */
 505     public function extract()
 506     {
 507         if ($this->object instanceof Traversable) {
 508             $this->object = ArrayUtils::iteratorToArray($this->object, false);
 509         }
 510
 511         if (! is_array($this->object)) {
 512             return [];
 513         }
 514
 515         $values = [];
 516
 517         foreach ($this->object as $key => $value) {
 518             // If a hydrator is provided, our work here is done
 519             if ($this->hydrator) {
 520                 $values[$key] = $this->hydrator->extract($value);
 521                 continue;
 522             }
 523
 524             // If the target element is a fieldset that can accept the provided value
 525             // we should clone it, inject the value and extract the data
 526             if ($this->targetElement instanceof FieldsetInterface) {
 527                 if (! $this->targetElement->allowObjectBinding($value)) {
 528                     continue;
 529                 }
 530                 $targetElement = clone $this->targetElement;
 531                 $targetElement->setObject($value);
 532                 $values[$key] = $targetElement->extract();
 533                 if (! $this->createNewObjects() && $this->has($key)) {
 534                     $this->get($key)->setObject($value);
 535                 }
 536                 continue;
 537             }
 538
 539             // If the target element is a non-fieldset element, just use the value
 540             if ($this->targetElement instanceof ElementInterface) {
 541                 $values[$key] = $value;
 542                 if (! $this->createNewObjects() && $this->has($key)) {
 543                     $this->get($key)->setValue($value);
 544                 }
 545                 continue;
 546             }
 547         }
 548
 549         return $values;
 550     }
 551
 552     /**
 553      * Create a new instance of the target element
 554      *
 555      * @return ElementInterface
 556      */
 557     protected function createNewTargetElementInstance()
 558     {
 559         return clone $this->targetElement;
 560     }
 561
 562     /**
 563      * Add a new instance of the target element
 564      *
 565      * @param string $name
 566      * @return ElementInterface
 567      * @throws Exception\DomainException
 568      */
 569     protected function addNewTargetElementInstance($name)
 570     {
 571         $this->shouldCreateChildrenOnPrepareElement = false;
 572
 573         $elementOrFieldset = $this->createNewTargetElementInstance();
 574         $elementOrFieldset->setName($name);
 575
 576         $this->add($elementOrFieldset);
 577
 578         if (! $this->allowAdd && $this->count() > $this->count) {
 579             throw new Exception\DomainException(sprintf(
 580                 'There are more elements than specified in the collection (%s). Either set the allow_add option ' .
 581                 'to true, or re-submit the form.',
 582                 get_class($this)
 583             ));
 584         }
 585
 586         return $elementOrFieldset;
 587     }
 588
 589     /**
 590      * Create a dummy template element
 591      *
 592      * @return null|ElementInterface|FieldsetInterface
 593      */
 594     protected function createTemplateElement()
 595     {
 596         if (! $this->shouldCreateTemplate) {
 597             return;
 598         }
 599
 600         if ($this->templateElement) {
 601             return $this->templateElement;
 602         }
 603
 604         $elementOrFieldset = $this->createNewTargetElementInstance();
 605         $elementOrFieldset->setName($this->templatePlaceholder);
 606
 607         return $elementOrFieldset;
 608     }
 609
 610     /**
 611      * Replaces the default template object of a sub element with the corresponding
 612      * real entity so that all properties are preserved.
 613      *
 614      * @return void
 615      */
 616     protected function replaceTemplateObjects()
 617     {
 618         $fieldsets = $this->getFieldsets();
 619
 620         if (! count($fieldsets) || ! $this->object) {
 621             return;
 622         }
 623
 624         foreach ($fieldsets as $fieldset) {
 625             $i = $fieldset->getName();
 626             if (isset($this->object[$i])) {
 627                 $fieldset->setObject($this->object[$i]);
 628             }
 629         }
 630     }
 631 }