improve setReference/getReference with documentation or functionality

[SimonHeimberg]

What I found out by trying is that setReference/getRefrence only support to store database entities. This should be improved that it is clear before trying.

Current behaviour:

• passing a non-object (like 1 or array()) to setReference raises an error telling that only objects are supported

 [Symfony\Component\Debug\Exception\ContextErrorException]
  Warning: spl_object_hash() expects parameter 1 to be object, integer given

• reading a non-entity object to with getReference raises an error telling that the object class was not found

 [Doctrine\Common\Persistence\Mapping\MappingException]
  The class 'stdClass' was not found in the chain configured namespaces  AppBundle\Entity, FOS\UserBundle\Model

• transferring the entities outside of setReference/getReference (example: by a static property containing an array(Collection) of entities) reports the entities as unexisting in the db

[Doctrine\ORM\ORMInvalidArgumentException]
  A new entity was found through the relationship 'AppBundle\Entity\Tag#parents' that was not configured to cascade persist
   operations for entity: entityNr1 To solve this issue: Either explicitly call EntityManager#persist() on this unknown entity or configure cascade persist  this association in the mapping for example @ManyToOne(
  ..,cascade={"persist"}).

suggestions

• improve the doc (on Readme) to mention the behaviour
• improve setReference to throw clear error messages when something invalid is passed (throw before getReference fails)
• support transfering an ArrayCollection with entities by setReference/getReference

work around for transfering array of entities

set

$i=0;
foreach ($entities as $entity) {
    $this->setReference('some_reference_name_'.$i);
    ++$i;
}

get

$entities = array();
$i=0;
try {
    while (true) {
        $entities[] = $this->getReference('some_reference_name_'.$i);
        ++$i;
    }
} catch (\OutOfBoundsException $e) {
    //finished
}

[Ocramius]

improve the doc (on Readme) to mention the behaviour

Can be done in the docblock of the interface, IMO.

improve setReference to throw clear error messages when something invalid is passed (throw before getReference fails)

If we modify the docs, this is a must anyway.

support transfering an ArrayCollection with entities by setReference/getReference

I wouldn't do this, since it is still possible to persist/load anything (event Traversable implementations) if correctly implemented.