References allow to define foreign key constraints. They must have a name. The foreign class defines which Entity is referenced. onDelete and onUpdate can define the constraint behaviour. The referenceMapping element allows to map a local attribute (labelId) against a foreign attribute(id)

    <entity name="Artist" namespace="SiestaTest\End2End\Reference\Generated" table="Artist">
        <attribute name="id" type="int" dbType="INT" primaryKey="true" autoValue="autoincrement"/>
        <attribute name="name" type="string" dbType="VARCHAR(100)"/>
        <attribute name="labelId" dbName="fk_label" type="string" dbType="VARCHAR(100)"/>

        <reference name="label" foreignTable="LabelEntity" onDelete="set null" onUpdate="set null">
             <referenceMapping localAttribute="labelId" foreignAttribute="id">
        </reference>
    </entity>

    <entity name="Label" namespace="SiestaTest\End2End\Reference\Generated" table="Label">
        <attribute name="id" type="int" dbType="INT" primaryKey="true" autoValue="autoincrement"/>
        <attribute name="name" type="string" dbType="VARCHAR(100)"/>
        <attribute name="city" type="string" dbType="VARCHAR(100)"/>
    </entity>

The relationship will generate these methods into the ArtistEntity. getLabel allows to retrieve the referenced object. A reload from the database can be enforced by the $forceReload parameter.

    /**
     * @param bool $forceReload
     *
     * @return Label|null
     */
    public function getLabel(bool $forceReload = false) { ... }

    /**
     * @param Label $entity
     *
     * @return void
     */
    public function setLabel(Label $entity = null) { ... }

                        

Example:
Reference Test, Reference Schema Sample

A One to Many Collector will collect all entities that reference the own entity. The following example shows that the CartItem references 0 or 1 Cartobjects. The Cart defines a collector with the name cartItem that collects CartItem objects. It defines its foreign class and the name of the reference.

    <entity name="Cart" namespace="SiestaTest\End2End\Collection\Generated" table="Cart" targetPath="Generated">

        <attribute name="id" type="int" dbType="INT" primaryKey="true" required="true" autoValue="autoincrement"/>
        <attribute name="name" type="string" dbType="VARCHAR(100)"/>

        <collection name="cartItem" foreignTable="CartItem" foreignReferenceName="cart"/>

    </entity>

    <entity name="CartItem" namespace="SiestaTest\End2End\Collection\Generated" table="CartItem" targetPath="Generated">

        <attribute name="id" type="int" dbType="INT" primaryKey="true" required="true" autoValue="autoincrement"/>
        <attribute name="name" type="string" dbType="VARCHAR(100)"/>

        <attribute name="cartId" dbName="fk_cart" type="int" dbType="INT"/>

        <reference name="cart" foreignTable="Cart" onDelete="set null" onUpdate="set null">
            <referenceMapping localAttribute="cartId" foreignAttribute="id"/>
        </reference>
    </entity>

The following methods will be generated in the Cart class. They allow to collect all CartItem, that reference the Cart. Furthermore all CartItem Object referencing this Cart can be deleted or a CartItem object can be added to the list.

    /**
     * @param bool $forceReload
     * @param string $connectionName
     *
     * @return CartItem[]
     */
    public function getCartItem(bool $forceReload = false, string $connectionName = null) : array { ... }

    /**
     * @param string $connectionName
     *
     * @return void
     */
    public function deleteAllCartItem(string $connectionName = null) { ... }

    /**
     * @param CartItem $entity
     *
     * @return void
     */
    public function addToCartItem(CartItem $entity) { ... }

                        

Example:
Collection test, Collection Schema sample,

The following example shows a many 2 many relationships. A Student can participate in 0..n exams and an Exam can have 0..n students. Therefore the 2 entities student and exam are defined. Furthermore a mapping table is needed (StudentExam) The mapping table references both entities and both Student and Exam define a collectionMany2Many element that defines the name of the many 2 many collection the foreign table and the mapping table.

    <entity name="Student" namespace="SiestaTest\End2End\CollectionMany\Generated" table="Student" targetPath="Generated">
        <attribute name="id" type="int" dbType="INT" primaryKey="true" required="true" autoValue="autoincrement"/>
        <attribute name="name" type="string" dbType="VARCHAR(30)"/>
        <collectionMany2Many name="examList" foreignTable="Exam"  mappingTable="StudentExam"/>
    </entity>

    <entity name="Exam" namespace="SiestaTest\End2End\CollectionMany\Generated" table="Exam" targetPath="Generated">
        <attribute name="id" type="int" dbType="INT" primaryKey="true" required="true" autoValue="autoincrement"/>
        <attribute name="name" type="string" dbType="VARCHAR(30)"/>
        <collectionMany2Many name="studentList" foreignTable="Student" mappingTable="StudentExam"/>
    </entity>

    <!-- Mapping Entity -->
    <entity name="StudentExam" namespace="SiestaTest\End2End\CollectionMany\Generated" table="StudentExam" targetPath="Generated">
        <attribute name="studentId" dbName="FK_Student" type="int" dbType="INT"/>
        <attribute name="examId" dbName="FK_Exam" type="int" dbType="INT"/>

        <reference name="StudentReference" foreignTable="Student" onDelete="cascade">
            <referenceMapping localAttribute="studentId" foreignAttribute="id"/>
        </reference>

        <reference name="ExamReference" foreignTable="Exam" onDelete="cascade">
            <referenceMapping localAttribute="examId" foreignAttribute="id" />
        </reference>
    </entity>

The following methods will be generated into the Student class. getExamList will return all exmas a student participates in. The method addToExamList allows to add an additional exam.
The method deleteFromExamList allows to either delete all mapping entires i.e. all exam participations or just a specific one. If you do not pass a examId ($id) all exam participations will be deleted. If you pass an examId only the participation of this exam will be deleted.
The method deleteAssignedExam() allows to either delete all exams or just a specific one. Same here if you do not pass an examId ($id) all assigned exams will be deleted and if you pass a specific examId only this assigned exam will be deleted.

    /**
     * @param bool $forceReload
     * @param string $connectionName
     *
     * @return Exam[]
     */
    public function getExamList(bool $forceReload = false, string $connectionName = null) : array { ... }


    /**
     * @param Exam $entity
     *
     * @return void
     */
    public function addToExamList(Exam $entity) { ... }


    /**
     * @param int $id
     * @param string $connectionName
     *
     * @return void
     */
    public function deleteFromExamList(int $id = null, string $connectionName = null) { ... }


    /**
     * @param int $id
     * @param string $connectionName
     *
     * @return void
     */
    public function deleteAssignedExam(int $id = null, string $connectionName = null)


                        

Example:
Collection Many 2 Many test, Collection Schema sample,