/** * Returns the related objects of a given $relatedClass for $object. * * This method returns the related objects of type $relatedClass for the * given $object. This method (in contrast to {@link getRelatedObject()}) * always returns an array of found objects, no matter if only 1 object * was found (e.g. {@link ezcPersistentManyToOneRelation}), none or several * ({@link ezcPersistentManyToManyRelation}). * * In case the set of related objects has already been fetched earlier, the * request to the database is not repeated, but the recorded object set is * returned. If the set of related objects was not recorded, yet, it is * fetched from the database and recorded afterwards. * * Example: * <code> * $person = $session->load( "Person", 1 ); * $relatedAddresses = $session->getRelatedObjects( $person, "Address" ); * echo "Number of addresses found: " . count( $relatedAddresses ); * </code> * * Relations that should preferably be used with this method are: * <ul> * <li>{@link ezcPersistentOneToManyRelation}</li> * <li>{@link ezcPersistentManyToManyRelation}</li> * </ul> * For other relation types {@link getRelatedObject()} is recommended. * * If multiple relations are defined for the $relatedClass (using {@link * ezcPersistentRelationCollection}), the parameter $relationName becomes * mandatory to determine which relation definition to use. For normal * relations, this parameter is silently ignored. * * @param object $object * @param string $relatedClass * @param string $relationName * * @return array(int=>object($relatedClass)) * * @throws ezcPersistentRelationNotFoundException * if the given $object does not have a relation to $relatedClass. */ public function getRelatedObjects($object, $relatedClass, $relationName = null) { if (!$this->properties['options']->refetch) { $relatedObjs = $this->identityMap->getRelatedObjects($object, $relatedClass, $relationName); if ($relatedObjs !== null) { return $relatedObjs; } } $relatedObjs = $this->session->getRelatedObjects($object, $relatedClass, $relationName); $storedRelatedObjs = $this->identityMap->setRelatedObjects($object, $relatedObjs, $relatedClass, $relationName, $this->properties['options']->refetch); return $storedRelatedObjs; }