1 <?php

     2 /*

     3  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS

     4  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT

     5  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR

     6  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT

     7  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,

     8  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT

     9  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,

    10  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY

    11  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT

    12  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE

    13  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

    14  *

    15  * This software consists of voluntary contributions made by many individuals

    16  * and is licensed under the LGPL. For more information, see

    17  * <http://www.doctrine-project.org>.

    18  */

    19 

    20 namespace Doctrine\ORM\Mapping;

    21 

    22 use Doctrine\Common\Persistence\Mapping\ClassMetadata;

    23 use ReflectionClass;

    24 

    25 /**

    26  * A <tt>ClassMetadata</tt> instance holds all the object-relational mapping metadata

    27  * of an entity and it's associations.

    28  *

    29  * Once populated, ClassMetadata instances are usually cached in a serialized form.

    30  *

    31  * <b>IMPORTANT NOTE:</b>

    32  *

    33  * The fields of this class are only public for 2 reasons:

    34  * 1) To allow fast READ access.

    35  * 2) To drastically reduce the size of a serialized instance (private/protected members

    36  *    get the whole class name, namespace inclusive, prepended to every property in

    37  *    the serialized representation).

    38  *

    39  * @author Roman Borschel <roman@code-factory.org>

    40  * @author Jonathan H. Wage <jonwage@gmail.com>

    41  * @since 2.0

    42  */

    43 class ClassMetadataInfo implements ClassMetadata

    44 {

    45     /* The inheritance mapping types */

    46     /**

    47      * NONE means the class does not participate in an inheritance hierarchy

    48      * and therefore does not need an inheritance mapping type.

    49      */

    50     const INHERITANCE_TYPE_NONE = 1;

    51     /**

    52      * JOINED means the class will be persisted according to the rules of

    53      * <tt>Class Table Inheritance</tt>.

    54      */

    55     const INHERITANCE_TYPE_JOINED = 2;

    56     /**

    57      * SINGLE_TABLE means the class will be persisted according to the rules of

    58      * <tt>Single Table Inheritance</tt>.

    59      */

    60     const INHERITANCE_TYPE_SINGLE_TABLE = 3;

    61     /**

    62      * TABLE_PER_CLASS means the class will be persisted according to the rules

    63      * of <tt>Concrete Table Inheritance</tt>.

    64      */

    65     const INHERITANCE_TYPE_TABLE_PER_CLASS = 4;

    66 

    67     /* The Id generator types. */

    68     /**

    69      * AUTO means the generator type will depend on what the used platform prefers.

    70      * Offers full portability.

    71      */

    72     const GENERATOR_TYPE_AUTO = 1;

    73     /**

    74      * SEQUENCE means a separate sequence object will be used. Platforms that do

    75      * not have native sequence support may emulate it. Full portability is currently

    76      * not guaranteed.

    77      */

    78     const GENERATOR_TYPE_SEQUENCE = 2;

    79     /**

    80      * TABLE means a separate table is used for id generation.

    81      * Offers full portability.

    82      */

    83     const GENERATOR_TYPE_TABLE = 3;

    84     /**

    85      * IDENTITY means an identity column is used for id generation. The database

    86      * will fill in the id column on insertion. Platforms that do not support

    87      * native identity columns may emulate them. Full portability is currently

    88      * not guaranteed.

    89      */

    90     const GENERATOR_TYPE_IDENTITY = 4;

    91     /**

    92      * NONE means the class does not have a generated id. That means the class

    93      * must have a natural, manually assigned id.

    94      */

    95     const GENERATOR_TYPE_NONE = 5;

    96     /**

    97      * DEFERRED_IMPLICIT means that changes of entities are calculated at commit-time

    98      * by doing a property-by-property comparison with the original data. This will

    99      * be done for all entities that are in MANAGED state at commit-time.

   100      *

   101      * This is the default change tracking policy.

   102      */

   103     const CHANGETRACKING_DEFERRED_IMPLICIT = 1;

   104     /**

   105      * DEFERRED_EXPLICIT means that changes of entities are calculated at commit-time

   106      * by doing a property-by-property comparison with the original data. This will

   107      * be done only for entities that were explicitly saved (through persist() or a cascade).

   108      */

   109     const CHANGETRACKING_DEFERRED_EXPLICIT = 2;

   110     /**

   111      * NOTIFY means that Doctrine relies on the entities sending out notifications

   112      * when their properties change. Such entity classes must implement

   113      * the <tt>NotifyPropertyChanged</tt> interface.

   114      */

   115     const CHANGETRACKING_NOTIFY = 3;

   116     /**

   117      * Specifies that an association is to be fetched when it is first accessed.

   118      */

   119     const FETCH_LAZY = 2;

   120     /**

   121      * Specifies that an association is to be fetched when the owner of the

   122      * association is fetched. 

   123      */

   124     const FETCH_EAGER = 3;

   125     /**

   126      * Specifies that an association is to be fetched lazy (on first access) and that

   127      * commands such as Collection#count, Collection#slice are issued directly against

   128      * the database if the collection is not yet initialized.

   129      */

   130     const FETCH_EXTRA_LAZY = 4;

   131     /**

   132      * Identifies a one-to-one association.

   133      */

   134     const ONE_TO_ONE = 1;

   135     /**

   136      * Identifies a many-to-one association.

   137      */

   138     const MANY_TO_ONE = 2;

   139     /**

   140      * Combined bitmask for to-one (single-valued) associations.

   141      */

   142     const TO_ONE = 3;

   143     /**

   144      * Identifies a one-to-many association.

   145      */

   146     const ONE_TO_MANY = 4;

   147     /**

   148      * Identifies a many-to-many association.

   149      */

   150     const MANY_TO_MANY = 8;

   151     /**

   152      * Combined bitmask for to-many (collection-valued) associations.

   153      */

   154     const TO_MANY = 12;

   155 

   156     /**

   157      * READ-ONLY: The name of the entity class.

   158      */

   159     public $name;

   160 

   161     /**

   162      * READ-ONLY: The namespace the entity class is contained in.

   163      *

   164      * @var string

   165      * @todo Not really needed. Usage could be localized.

   166      */

   167     public $namespace;

   168 

   169     /**

   170      * READ-ONLY: The name of the entity class that is at the root of the mapped entity inheritance

   171      * hierarchy. If the entity is not part of a mapped inheritance hierarchy this is the same

   172      * as {@link $entityName}.

   173      *

   174      * @var string

   175      */

   176     public $rootEntityName;

   177 

   178     /**

   179      * The name of the custom repository class used for the entity class.

   180      * (Optional).

   181      *

   182      * @var string

   183      */

   184     public $customRepositoryClassName;

   185 

   186     /**

   187      * READ-ONLY: Whether this class describes the mapping of a mapped superclass.

   188      *

   189      * @var boolean

   190      */

   191     public $isMappedSuperclass = false;

   192 

   193     /**

   194      * READ-ONLY: The names of the parent classes (ancestors).

   195      *

   196      * @var array

   197      */

   198     public $parentClasses = array();

   199 

   200     /**

   201      * READ-ONLY: The names of all subclasses (descendants).

   202      *

   203      * @var array

   204      */

   205     public $subClasses = array();

   206 

   207     /**

   208      * READ-ONLY: The named queries allowed to be called directly from Repository.

   209      * 

   210      * @var array

   211      */

   212     public $namedQueries = array();

   213 

   214     /**

   215      * READ-ONLY: The field names of all fields that are part of the identifier/primary key

   216      * of the mapped entity class.

   217      *

   218      * @var array

   219      */

   220     public $identifier = array();

   221 

   222     /**

   223      * READ-ONLY: The inheritance mapping type used by the class.

   224      *

   225      * @var integer

   226      */

   227     public $inheritanceType = self::INHERITANCE_TYPE_NONE;

   228 

   229     /**

   230      * READ-ONLY: The Id generator type used by the class.

   231      *

   232      * @var string

   233      */

   234     public $generatorType = self::GENERATOR_TYPE_NONE;

   235 

   236     /**

   237      * READ-ONLY: The field mappings of the class.

   238      * Keys are field names and values are mapping definitions.

   239      *

   240      * The mapping definition array has the following values:

   241      *

   242      * - <b>fieldName</b> (string)

   243      * The name of the field in the Entity.

   244      *

   245      * - <b>type</b> (string)

   246      * The type name of the mapped field. Can be one of Doctrine's mapping types

   247      * or a custom mapping type.

   248      *

   249      * - <b>columnName</b> (string, optional)

   250      * The column name. Optional. Defaults to the field name.

   251      *

   252      * - <b>length</b> (integer, optional)

   253      * The database length of the column. Optional. Default value taken from

   254      * the type.

   255      *

   256      * - <b>id</b> (boolean, optional)

   257      * Marks the field as the primary key of the entity. Multiple fields of an

   258      * entity can have the id attribute, forming a composite key.

   259      *

   260      * - <b>nullable</b> (boolean, optional)

   261      * Whether the column is nullable. Defaults to FALSE.

   262      *

   263      * - <b>columnDefinition</b> (string, optional, schema-only)

   264      * The SQL fragment that is used when generating the DDL for the column.

   265      *

   266      * - <b>precision</b> (integer, optional, schema-only)

   267      * The precision of a decimal column. Only valid if the column type is decimal.

   268      *

   269      * - <b>scale</b> (integer, optional, schema-only)

   270      * The scale of a decimal column. Only valid if the column type is decimal.

   271      *

   272      [* - <b>'unique'] (string, optional, schema-only)</b>

   273      * Whether a unique constraint should be generated for the column.

   274      *

   275      * @var array

   276      */

   277     public $fieldMappings = array();

   278 

   279     /**

   280      * READ-ONLY: An array of field names. Used to look up field names from column names.

   281      * Keys are column names and values are field names.

   282      * This is the reverse lookup map of $_columnNames.

   283      *

   284      * @var array

   285      */

   286     public $fieldNames = array();

   287 

   288     /**

   289      * READ-ONLY: A map of field names to column names. Keys are field names and values column names.

   290      * Used to look up column names from field names.

   291      * This is the reverse lookup map of $_fieldNames.

   292      *

   293      * @var array

   294      * @todo We could get rid of this array by just using $fieldMappings[$fieldName]['columnName'].

   295      */

   296     public $columnNames = array();

   297 

   298     /**

   299      * READ-ONLY: The discriminator value of this class.

   300      *

   301      * <b>This does only apply to the JOINED and SINGLE_TABLE inheritance mapping strategies

   302      * where a discriminator column is used.</b>

   303      *

   304      * @var mixed

   305      * @see discriminatorColumn

   306      */

   307     public $discriminatorValue;

   308 

   309     /**

   310      * READ-ONLY: The discriminator map of all mapped classes in the hierarchy.

   311      *

   312      * <b>This does only apply to the JOINED and SINGLE_TABLE inheritance mapping strategies

   313      * where a discriminator column is used.</b>

   314      *

   315      * @var mixed

   316      * @see discriminatorColumn

   317      */

   318     public $discriminatorMap = array();

   319 

   320     /**

   321      * READ-ONLY: The definition of the descriminator column used in JOINED and SINGLE_TABLE

   322      * inheritance mappings.

   323      *

   324      * @var array

   325      */

   326     public $discriminatorColumn;

   327 

   328     /**

   329      * READ-ONLY: The primary table definition. The definition is an array with the

   330      * following entries:

   331      *

   332      * name => <tableName>

   333      * schema => <schemaName>

   334      * indexes => array

   335      * uniqueConstraints => array

   336      *

   337      * @var array

   338      */

   339     public $table;

   340 

   341     /**

   342      * READ-ONLY: The registered lifecycle callbacks for entities of this class.

   343      *

   344      * @var array

   345      */

   346     public $lifecycleCallbacks = array();

   347 

   348     /**

   349      * READ-ONLY: The association mappings of this class.

   350      *

   351      * The mapping definition array supports the following keys:

   352      *

   353      * - <b>fieldName</b> (string)

   354      * The name of the field in the entity the association is mapped to.

   355      *

   356      * - <b>targetEntity</b> (string)

   357      * The class name of the target entity. If it is fully-qualified it is used as is.

   358      * If it is a simple, unqualified class name the namespace is assumed to be the same

   359      * as the namespace of the source entity.

   360      *

   361      * - <b>mappedBy</b> (string, required for bidirectional associations)

   362      * The name of the field that completes the bidirectional association on the owning side.

   363      * This key must be specified on the inverse side of a bidirectional association.

   364      * 

   365      * - <b>inversedBy</b> (string, required for bidirectional associations)

   366      * The name of the field that completes the bidirectional association on the inverse side.

   367      * This key must be specified on the owning side of a bidirectional association.

   368      *

   369      * - <b>cascade</b> (array, optional)

   370      * The names of persistence operations to cascade on the association. The set of possible

   371      * values are: "persist", "remove", "detach", "merge", "refresh", "all" (implies all others).

   372      *

   373      * - <b>orderBy</b> (array, one-to-many/many-to-many only)

   374      * A map of field names (of the target entity) to sorting directions (ASC/DESC).

   375      * Example: array('priority' => 'desc')

   376      *

   377      * - <b>fetch</b> (integer, optional)

   378      * The fetching strategy to use for the association, usually defaults to FETCH_LAZY.

   379      * Possible values are: ClassMetadata::FETCH_EAGER, ClassMetadata::FETCH_LAZY.

   380      *

   381      * - <b>joinTable</b> (array, optional, many-to-many only)

   382      * Specification of the join table and its join columns (foreign keys).

   383      * Only valid for many-to-many mappings. Note that one-to-many associations can be mapped

   384      * through a join table by simply mapping the association as many-to-many with a unique

   385      * constraint on the join table.

   386      *

   387      * - <b>indexBy</b> (string, optional, to-many only)

   388      * Specification of a field on target-entity that is used to index the collection by.

   389      * This field HAS to be either the primary key or a unique column. Otherwise the collection

   390      * does not contain all the entities that are actually related.

   391      * 

   392      * A join table definition has the following structure:

   393      * <pre>

   394      * array(

   395      *     'name' => <join table name>,

   396      *      'joinColumns' => array(<join column mapping from join table to source table>),

   397      *      'inverseJoinColumns' => array(<join column mapping from join table to target table>)

   398      * )

   399      * </pre>

   400      *

   401      *

   402      * @var array

   403      */

   404     public $associationMappings = array();

   405 

   406     /**

   407      * READ-ONLY: Flag indicating whether the identifier/primary key of the class is composite.

   408      *

   409      * @var boolean

   410      */

   411     public $isIdentifierComposite = false;

   412 

   413     /**

   414      * READ-ONLY: Flag indicating wheather the identifier/primary key contains at least one foreign key association.

   415      *

   416      * This flag is necessary because some code blocks require special treatment of this cases.

   417      *

   418      * @var boolean

   419      */

   420     public $containsForeignIdentifier = false;

   421 

   422     /**

   423      * READ-ONLY: The ID generator used for generating IDs for this class.

   424      *

   425      * @var AbstractIdGenerator

   426      * @todo Remove!

   427      */

   428     public $idGenerator;

   429 

   430     /**

   431      * READ-ONLY: The definition of the sequence generator of this class. Only used for the

   432      * SEQUENCE generation strategy.

   433      * 

   434      * The definition has the following structure:

   435      * <code>

   436      * array(

   437      *     'sequenceName' => 'name',

   438      *     'allocationSize' => 20,

   439      *     'initialValue' => 1

   440      * )

   441      * </code>

   442      *

   443      * @var array

   444      * @todo Merge with tableGeneratorDefinition into generic generatorDefinition

   445      */

   446     public $sequenceGeneratorDefinition;

   447 

   448     /**

   449      * READ-ONLY: The definition of the table generator of this class. Only used for the

   450      * TABLE generation strategy.

   451      *

   452      * @var array

   453      * @todo Merge with tableGeneratorDefinition into generic generatorDefinition

   454      */

   455     public $tableGeneratorDefinition;

   456 

   457     /**

   458      * READ-ONLY: The policy used for change-tracking on entities of this class.

   459      *

   460      * @var integer

   461      */

   462     public $changeTrackingPolicy = self::CHANGETRACKING_DEFERRED_IMPLICIT;

   463 

   464     /**

   465      * READ-ONLY: A flag for whether or not instances of this class are to be versioned

   466      * with optimistic locking.

   467      *

   468      * @var boolean $isVersioned

   469      */

   470     public $isVersioned;

   471 

   472     /**

   473      * READ-ONLY: The name of the field which is used for versioning in optimistic locking (if any).

   474      *

   475      * @var mixed $versionField

   476      */

   477     public $versionField;

   478 

   479     /**

   480      * The ReflectionClass instance of the mapped class.

   481      *

   482      * @var ReflectionClass

   483      */

   484     public $reflClass;

   485 

   486     /**

   487      * Is this entity marked as "read-only"?

   488      *

   489      * That means it is never considered for change-tracking in the UnitOfWork. It is a very helpful performance

   490      * optimization for entities that are immutable, either in your domain or through the relation database

   491      * (coming from a view, or a history table for example).

   492      *

   493      * @var bool

   494      */

   495     public $isReadOnly = false;

   496 

   497     /**

   498      * Initializes a new ClassMetadata instance that will hold the object-relational mapping

   499      * metadata of the class with the given name.

   500      *

   501      * @param string $entityName The name of the entity class the new instance is used for.

   502      */

   503     public function __construct($entityName)

   504     {

   505         $this->name = $entityName;

   506         $this->rootEntityName = $entityName;

   507     }

   508 

   509     /**

   510      * Gets the ReflectionClass instance of the mapped class.

   511      *

   512      * @return ReflectionClass

   513      */

   514     public function getReflectionClass()

   515     {

   516         if ( ! $this->reflClass) {

   517             $this->reflClass = new ReflectionClass($this->name);

   518         }

   519         return $this->reflClass;

   520     }

   521 

   522     /**

   523      * Sets the change tracking policy used by this class.

   524      *

   525      * @param integer $policy

   526      */

   527     public function setChangeTrackingPolicy($policy)

   528     {

   529         $this->changeTrackingPolicy = $policy;

   530     }

   531 

   532     /**

   533      * Whether the change tracking policy of this class is "deferred explicit".

   534      *

   535      * @return boolean

   536      */

   537     public function isChangeTrackingDeferredExplicit()

   538     {

   539         return $this->changeTrackingPolicy == self::CHANGETRACKING_DEFERRED_EXPLICIT;

   540     }

   541 

   542     /**

   543      * Whether the change tracking policy of this class is "deferred implicit".

   544      *

   545      * @return boolean

   546      */

   547     public function isChangeTrackingDeferredImplicit()

   548     {

   549         return $this->changeTrackingPolicy == self::CHANGETRACKING_DEFERRED_IMPLICIT;

   550     }

   551 

   552     /**

   553      * Whether the change tracking policy of this class is "notify".

   554      *

   555      * @return boolean

   556      */

   557     public function isChangeTrackingNotify()

   558     {

   559         return $this->changeTrackingPolicy == self::CHANGETRACKING_NOTIFY;

   560     }

   561 

   562     /**

   563      * Checks whether a field is part of the identifier/primary key field(s).

   564      *

   565      * @param string $fieldName  The field name

   566      * @return boolean  TRUE if the field is part of the table identifier/primary key field(s),

   567      *                  FALSE otherwise.

   568      */

   569     public function isIdentifier($fieldName)

   570     {

   571         if ( ! $this->isIdentifierComposite) {

   572             return $fieldName === $this->identifier[0];

   573         }

   574         return in_array($fieldName, $this->identifier);

   575     }

   576 

   577     /**

   578      * Check if the field is unique.

   579      *

   580      * @param string $fieldName  The field name

   581      * @return boolean  TRUE if the field is unique, FALSE otherwise.

   582      */

   583     public function isUniqueField($fieldName)

   584     {

   585         $mapping = $this->getFieldMapping($fieldName);

   586         if ($mapping !== false) {

   587             return isset($mapping['unique']) && $mapping['unique'] == true;

   588         }

   589         return false;

   590     }

   591 

   592     /**

   593      * Check if the field is not null.

   594      *

   595      * @param string $fieldName  The field name

   596      * @return boolean  TRUE if the field is not null, FALSE otherwise.

   597      */

   598     public function isNullable($fieldName)

   599     {

   600         $mapping = $this->getFieldMapping($fieldName);

   601         if ($mapping !== false) {

   602             return isset($mapping['nullable']) && $mapping['nullable'] == true;

   603         }

   604         return false;

   605     }

   606 

   607     /**

   608      * Gets a column name for a field name.

   609      * If the column name for the field cannot be found, the given field name

   610      * is returned.

   611      *

   612      * @param string $fieldName The field name.

   613      * @return string  The column name.

   614      */

   615     public function getColumnName($fieldName)

   616     {

   617         return isset($this->columnNames[$fieldName]) ?

   618                 $this->columnNames[$fieldName] : $fieldName;

   619     }

   620 

   621     /**

   622      * Gets the mapping of a (regular) field that holds some data but not a

   623      * reference to another object.

   624      *

   625      * @param string $fieldName  The field name.

   626      * @return array  The field mapping.

   627      */

   628     public function getFieldMapping($fieldName)

   629     {

   630         if ( ! isset($this->fieldMappings[$fieldName])) {

   631             throw MappingException::mappingNotFound($this->name, $fieldName);

   632         }

   633         return $this->fieldMappings[$fieldName];

   634     }

   635 

   636     /**

   637      * Gets the mapping of an association.

   638      *

   639      * @see ClassMetadataInfo::$associationMappings

   640      * @param string $fieldName  The field name that represents the association in

   641      *                           the object model.

   642      * @return array The mapping.

   643      */

   644     public function getAssociationMapping($fieldName)

   645     {

   646         if ( ! isset($this->associationMappings[$fieldName])) {

   647             throw MappingException::mappingNotFound($this->name, $fieldName);

   648         }

   649         return $this->associationMappings[$fieldName];

   650     }

   651 

   652     /**

   653      * Gets all association mappings of the class.

   654      *

   655      * @return array

   656      */

   657     public function getAssociationMappings()

   658     {

   659         return $this->associationMappings;

   660     }

   661 

   662     /**

   663      * Gets the field name for a column name.

   664      * If no field name can be found the column name is returned.

   665      *

   666      * @param string $columnName    column name

   667      * @return string               column alias

   668      */

   669     public function getFieldName($columnName)

   670     {

   671         return isset($this->fieldNames[$columnName]) ?

   672                 $this->fieldNames[$columnName] : $columnName;

   673     }

   674 

   675     /**

   676      * Gets the named query.

   677      *

   678      * @see ClassMetadataInfo::$namedQueries

   679      * @throws MappingException

   680      * @param string $queryName The query name

   681      * @return string

   682      */

   683     public function getNamedQuery($queryName)

   684     {

   685         if ( ! isset($this->namedQueries[$queryName])) {

   686             throw MappingException::queryNotFound($this->name, $queryName);

   687         }

   688         return $this->namedQueries[$queryName];

   689     }

   690 

   691     /**

   692      * Gets all named queries of the class.

   693      *

   694      * @return array

   695      */

   696     public function getNamedQueries()

   697     {

   698         return $this->namedQueries;

   699     }

   700 

   701     /**

   702      * Validates & completes the given field mapping.

   703      *

   704      * @param array $mapping  The field mapping to validated & complete.

   705      * @return array  The validated and completed field mapping.

   706      */

   707     protected function _validateAndCompleteFieldMapping(array &$mapping)

   708     {

   709         // Check mandatory fields

   710         if ( ! isset($mapping['fieldName']) || strlen($mapping['fieldName']) == 0) {

   711             throw MappingException::missingFieldName($this->name);

   712         }

   713         if ( ! isset($mapping['type'])) {

   714             // Default to string

   715             $mapping['type'] = 'string';

   716         }

   717 

   718         // Complete fieldName and columnName mapping

   719         if ( ! isset($mapping['columnName'])) {

   720             $mapping['columnName'] = $mapping['fieldName'];

   721         } else {

   722             if ($mapping['columnName'][0] == '`') {

   723                 $mapping['columnName'] = trim($mapping['columnName'], '`');

   724                 $mapping['quoted'] = true;

   725             }

   726         }

   727 

   728         $this->columnNames[$mapping['fieldName']] = $mapping['columnName'];

   729         if (isset($this->fieldNames[$mapping['columnName']]) || ($this->discriminatorColumn != null && $this->discriminatorColumn['name'] == $mapping['columnName'])) {

   730             throw MappingException::duplicateColumnName($this->name, $mapping['columnName']);

   731         }

   732 

   733         $this->fieldNames[$mapping['columnName']] = $mapping['fieldName'];

   734 

   735         // Complete id mapping

   736         if (isset($mapping['id']) && $mapping['id'] === true) {

   737             if ($this->versionField == $mapping['fieldName']) {

   738                 throw MappingException::cannotVersionIdField($this->name, $mapping['fieldName']);

   739             }

   740 

   741             if ( ! in_array($mapping['fieldName'], $this->identifier)) {

   742                 $this->identifier[] = $mapping['fieldName'];

   743             }

   744             // Check for composite key

   745             if ( ! $this->isIdentifierComposite && count($this->identifier) > 1) {

   746                 $this->isIdentifierComposite = true;

   747             }

   748         }

   749     }

   750 

   751     /**

   752      * Validates & completes the basic mapping information that is common to all

   753      * association mappings (one-to-one, many-ot-one, one-to-many, many-to-many).

   754      *

   755      * @param array $mapping The mapping.

   756      * @return array The updated mapping.

   757      * @throws MappingException If something is wrong with the mapping.

   758      */

   759     protected function _validateAndCompleteAssociationMapping(array $mapping)

   760     {

   761         if ( ! isset($mapping['mappedBy'])) {

   762             $mapping['mappedBy'] = null;

   763         }

   764         if ( ! isset($mapping['inversedBy'])) {

   765             $mapping['inversedBy'] = null;

   766         }

   767         $mapping['isOwningSide'] = true; // assume owning side until we hit mappedBy

   768 

   769         // unset optional indexBy attribute if its empty

   770         if (!isset($mapping['indexBy']) || !$mapping['indexBy']) {

   771             unset($mapping['indexBy']);

   772         }

   773 

   774         // If targetEntity is unqualified, assume it is in the same namespace as

   775         // the sourceEntity.

   776         $mapping['sourceEntity'] = $this->name;

   777         if (isset($mapping['targetEntity']) && strpos($mapping['targetEntity'], '\\') === false

   778                 && strlen($this->namespace) > 0) {

   779             $mapping['targetEntity'] = $this->namespace . '\\' . $mapping['targetEntity'];

   780         }

   781 

   782         // Complete id mapping

   783         if (isset($mapping['id']) && $mapping['id'] === true) {

   784             if (isset($mapping['orphanRemoval']) && $mapping['orphanRemoval'] == true) {

   785                 throw MappingException::illegalOrphanRemovalOnIdentifierAssociation($this->name, $mapping['fieldName']);

   786             }

   787 

   788             if ( ! in_array($mapping['fieldName'], $this->identifier)) {

   789                 if (count($mapping['joinColumns']) >= 2) {

   790                     throw MappingException::cannotMapCompositePrimaryKeyEntitiesAsForeignId(

   791                         $mapping['targetEntity'], $this->name, $mapping['fieldName']

   792                     );

   793                 }

   794 

   795                 $this->identifier[] = $mapping['fieldName'];

   796                 $this->containsForeignIdentifier = true;

   797             }

   798             // Check for composite key

   799             if ( ! $this->isIdentifierComposite && count($this->identifier) > 1) {

   800                 $this->isIdentifierComposite = true;

   801             }

   802         }

   803 

   804         // Mandatory attributes for both sides

   805         // Mandatory: fieldName, targetEntity

   806         if ( ! isset($mapping['fieldName']) || strlen($mapping['fieldName']) == 0) {

   807             throw MappingException::missingFieldName($this->name);

   808         }

   809         if ( ! isset($mapping['targetEntity'])) {

   810             throw MappingException::missingTargetEntity($mapping['fieldName']);

   811         }

   812         

   813         // Mandatory and optional attributes for either side

   814         if ( ! $mapping['mappedBy']) {

   815             if (isset($mapping['joinTable']) && $mapping['joinTable']) {

   816                 if (isset($mapping['joinTable']['name']) && $mapping['joinTable']['name'][0] == '`') {

   817                     $mapping['joinTable']['name'] = trim($mapping['joinTable']['name'], '`');

   818                     $mapping['joinTable']['quoted'] = true;

   819                 }

   820             }

   821         } else {

   822             $mapping['isOwningSide'] = false;

   823         }

   824 

   825         if (isset($mapping['id']) && $mapping['id'] === true && $mapping['type'] & self::TO_MANY) {

   826             throw MappingException::illegalToManyIdentifierAssoaction($this->name, $mapping['fieldName']);

   827         }

   828         

   829         // Fetch mode. Default fetch mode to LAZY, if not set.

   830         if ( ! isset($mapping['fetch'])) {

   831             $mapping['fetch'] = self::FETCH_LAZY;

   832         }

   833 

   834         // Cascades

   835         $cascades = isset($mapping['cascade']) ? array_map('strtolower', $mapping['cascade']) : array();

   836         if (in_array('all', $cascades)) {

   837             $cascades = array(

   838                'remove',

   839                'persist',

   840                'refresh',

   841                'merge',

   842                'detach'

   843             );

   844         }

   845         $mapping['cascade'] = $cascades;

   846         $mapping['isCascadeRemove'] = in_array('remove',  $cascades);

   847         $mapping['isCascadePersist'] = in_array('persist',  $cascades);

   848         $mapping['isCascadeRefresh'] = in_array('refresh',  $cascades);

   849         $mapping['isCascadeMerge'] = in_array('merge',  $cascades);

   850         $mapping['isCascadeDetach'] = in_array('detach',  $cascades);

   851         

   852         return $mapping;

   853     }

   854 

   855     /**

   856      * Validates & completes a one-to-one association mapping.

   857      *

   858      * @param array $mapping  The mapping to validate & complete.

   859      * @return array The validated & completed mapping.

   860      * @override

   861      */

   862     protected function _validateAndCompleteOneToOneMapping(array $mapping)

   863     {

   864         $mapping = $this->_validateAndCompleteAssociationMapping($mapping);

   865         

   866         if (isset($mapping['joinColumns']) && $mapping['joinColumns']) {

   867             $mapping['isOwningSide'] = true;

   868         }

   869         

   870         if ($mapping['isOwningSide']) {

   871             if ( ! isset($mapping['joinColumns']) || ! $mapping['joinColumns']) {

   872                 // Apply default join column

   873                 $mapping['joinColumns'] = array(array(

   874                     'name' => $mapping['fieldName'] . '_id',

   875                     'referencedColumnName' => 'id'

   876                 ));

   877             }

   878 

   879             $uniqueContraintColumns = array();

   880             foreach ($mapping['joinColumns'] as $key => &$joinColumn) {

   881                 if ($mapping['type'] === self::ONE_TO_ONE) {

   882                     if (count($mapping['joinColumns']) == 1) {

   883                         $joinColumn['unique'] = true;

   884                     } else {

   885                         $uniqueContraintColumns[] = $joinColumn['name'];

   886                     }

   887                 }

   888                 if (empty($joinColumn['name'])) {

   889                     $joinColumn['name'] = $mapping['fieldName'] . '_id';

   890                 }

   891                 if (empty($joinColumn['referencedColumnName'])) {

   892                     $joinColumn['referencedColumnName'] = 'id';

   893                 }

   894                 $mapping['sourceToTargetKeyColumns'][$joinColumn['name']] = $joinColumn['referencedColumnName'];

   895                 $mapping['joinColumnFieldNames'][$joinColumn['name']] = isset($joinColumn['fieldName'])

   896                         ? $joinColumn['fieldName'] : $joinColumn['name'];

   897             }

   898 

   899             if ($uniqueContraintColumns) {

   900                 if (!$this->table) {

   901                     throw new \RuntimeException("ClassMetadataInfo::setTable() has to be called before defining a one to one relationship.");

   902                 }

   903                 $this->table['uniqueConstraints'][$mapping['fieldName']."_uniq"] = array(

   904                     'columns' => $uniqueContraintColumns

   905                 );

   906             }

   907 

   908             $mapping['targetToSourceKeyColumns'] = array_flip($mapping['sourceToTargetKeyColumns']);

   909         }

   910 

   911         //TODO: if orphanRemoval, cascade=remove is implicit!

   912         $mapping['orphanRemoval'] = isset($mapping['orphanRemoval']) ?

   913                 (bool) $mapping['orphanRemoval'] : false;

   914 

   915         if (isset($mapping['id']) && $mapping['id'] === true && !$mapping['isOwningSide']) {

   916             throw MappingException::illegalInverseIdentifierAssocation($this->name, $mapping['fieldName']);

   917         }

   918 

   919         return $mapping;

   920     }

   921 

   922     /**

   923      * Validates and completes the mapping.

   924      *

   925      * @param array $mapping The mapping to validate and complete.

   926      * @return array The validated and completed mapping.

   927      * @override

   928      */

   929     protected function _validateAndCompleteOneToManyMapping(array $mapping)

   930     {

   931         $mapping = $this->_validateAndCompleteAssociationMapping($mapping);

   932 

   933         // OneToMany-side MUST be inverse (must have mappedBy)

   934         if ( ! isset($mapping['mappedBy'])) {

   935             throw MappingException::oneToManyRequiresMappedBy($mapping['fieldName']);

   936         }

   937         

   938         //TODO: if orphanRemoval, cascade=remove is implicit!

   939         $mapping['orphanRemoval'] = isset($mapping['orphanRemoval']) ?

   940                 (bool) $mapping['orphanRemoval'] : false;

   941 

   942         if (isset($mapping['orderBy'])) {

   943             if ( ! is_array($mapping['orderBy'])) {

   944                 throw new \InvalidArgumentException("'orderBy' is expected to be an array, not ".gettype($mapping['orderBy']));

   945             }

   946         }

   947         

   948         return $mapping;

   949     }

   950 

   951     protected function _validateAndCompleteManyToManyMapping(array $mapping)

   952     {

   953         $mapping = $this->_validateAndCompleteAssociationMapping($mapping);

   954         if ($mapping['isOwningSide']) {

   955             if (strpos($mapping['sourceEntity'], '\\') !== false) {

   956                 $sourceShortName = strtolower(substr($mapping['sourceEntity'], strrpos($mapping['sourceEntity'], '\\') + 1));

   957             } else {

   958                 $sourceShortName = strtolower($mapping['sourceEntity']);

   959             }

   960             if (strpos($mapping['targetEntity'], '\\') !== false) {

   961                 $targetShortName = strtolower(substr($mapping['targetEntity'], strrpos($mapping['targetEntity'], '\\') + 1));

   962             } else {

   963                 $targetShortName = strtolower($mapping['targetEntity']);

   964             }

   965             

   966             // owning side MUST have a join table

   967             if ( ! isset($mapping['joinTable']['name'])) {

   968                 $mapping['joinTable']['name'] = $sourceShortName .'_' . $targetShortName;

   969             }

   970             if ( ! isset($mapping['joinTable']['joinColumns'])) {

   971                 $mapping['joinTable']['joinColumns'] = array(array(

   972                         'name' => $sourceShortName . '_id',

   973                         'referencedColumnName' => 'id',

   974                         'onDelete' => 'CASCADE'));

   975             }

   976             if ( ! isset($mapping['joinTable']['inverseJoinColumns'])) {

   977                 $mapping['joinTable']['inverseJoinColumns'] = array(array(

   978                         'name' => $targetShortName . '_id',

   979                         'referencedColumnName' => 'id',

   980                         'onDelete' => 'CASCADE'));

   981             }

   982 

   983             foreach ($mapping['joinTable']['joinColumns'] as &$joinColumn) {

   984                 if (empty($joinColumn['name'])) {

   985                     $joinColumn['name'] = $sourceShortName . '_id';

   986                 }

   987                 if (empty($joinColumn['referencedColumnName'])) {

   988                     $joinColumn['referencedColumnName'] = 'id';

   989                 }

   990                 if (isset($joinColumn['onDelete']) && strtolower($joinColumn['onDelete']) == 'cascade') {

   991                     $mapping['isOnDeleteCascade'] = true;

   992                 }

   993                 $mapping['relationToSourceKeyColumns'][$joinColumn['name']] = $joinColumn['referencedColumnName'];

   994                 $mapping['joinTableColumns'][] = $joinColumn['name'];

   995             }

   996 

   997             foreach ($mapping['joinTable']['inverseJoinColumns'] as &$inverseJoinColumn) {

   998                 if (empty($inverseJoinColumn['name'])) {

   999                     $inverseJoinColumn['name'] = $targetShortName . '_id';

  1000                 }

  1001                 if (empty($inverseJoinColumn['referencedColumnName'])) {

  1002                     $inverseJoinColumn['referencedColumnName'] = 'id';

  1003                 }

  1004                 if (isset($inverseJoinColumn['onDelete']) && strtolower($inverseJoinColumn['onDelete']) == 'cascade') {

  1005                     $mapping['isOnDeleteCascade'] = true;

  1006                 }

  1007                 $mapping['relationToTargetKeyColumns'][$inverseJoinColumn['name']] = $inverseJoinColumn['referencedColumnName'];

  1008                 $mapping['joinTableColumns'][] = $inverseJoinColumn['name'];

  1009             }

  1010         }

  1011 

  1012         if (isset($mapping['orderBy'])) {

  1013             if ( ! is_array($mapping['orderBy'])) {

  1014                 throw new \InvalidArgumentException("'orderBy' is expected to be an array, not ".gettype($mapping['orderBy']));

  1015             }

  1016         }

  1017 

  1018         return $mapping;

  1019     }

  1020 

  1021     /**

  1022      * Gets the identifier (primary key) field names of the class.

  1023      *

  1024      * @return mixed

  1025      */

  1026     public function getIdentifierFieldNames()

  1027     {

  1028         return $this->identifier;

  1029     }

  1030 

  1031     /**

  1032      * Gets the name of the single id field. Note that this only works on

  1033      * entity classes that have a single-field pk.

  1034      *

  1035      * @return string

  1036      * @throws MappingException If the class has a composite primary key.

  1037      */

  1038     public function getSingleIdentifierFieldName()

  1039     {

  1040         if ($this->isIdentifierComposite) {

  1041             throw MappingException::singleIdNotAllowedOnCompositePrimaryKey($this->name);

  1042         }

  1043         return $this->identifier[0];

  1044     }

  1045 

  1046     /**

  1047      * Gets the column name of the single id column. Note that this only works on

  1048      * entity classes that have a single-field pk.

  1049      *

  1050      * @return string

  1051      * @throws MappingException If the class has a composite primary key.

  1052      */

  1053     public function getSingleIdentifierColumnName()

  1054     {

  1055         return $this->getColumnName($this->getSingleIdentifierFieldName());

  1056     }

  1057 

  1058     /**

  1059      * INTERNAL:

  1060      * Sets the mapped identifier/primary key fields of this class.

  1061      * Mainly used by the ClassMetadataFactory to assign inherited identifiers.

  1062      *

  1063      * @param array $identifier

  1064      */

  1065     public function setIdentifier(array $identifier)

  1066     {

  1067         $this->identifier = $identifier;

  1068         $this->isIdentifierComposite = (count($this->identifier) > 1);

  1069     }

  1070 

  1071     /**

  1072      * Gets the mapped identifier field of this class.

  1073      *

  1074      * @return string $identifier

  1075      */

  1076     public function getIdentifier()

  1077     {

  1078         return $this->identifier;

  1079     }

  1080 

  1081     /**

  1082      * Checks whether the class has a (mapped) field with a certain name.

  1083      *

  1084      * @return boolean

  1085      */

  1086     public function hasField($fieldName)

  1087     {

  1088         return isset($this->fieldMappings[$fieldName]);

  1089     }

  1090 

  1091     /**

  1092      * Gets an array containing all the column names.

  1093      *

  1094      * @return array

  1095      */

  1096     public function getColumnNames(array $fieldNames = null)

  1097     {

  1098         if ($fieldNames === null) {

  1099             return array_keys($this->fieldNames);

  1100         } else {

  1101             $columnNames = array();

  1102             foreach ($fieldNames as $fieldName) {

  1103                 $columnNames[] = $this->getColumnName($fieldName);

  1104             }

  1105             return $columnNames;

  1106         }

  1107     }

  1108 

  1109     /**

  1110      * Returns an array with all the identifier column names.

  1111      *

  1112      * @return array

  1113      */

  1114     public function getIdentifierColumnNames()

  1115     {

  1116         if ($this->isIdentifierComposite) {

  1117             $columnNames = array();

  1118             foreach ($this->identifier as $idField) {

  1119                 if (isset($this->associationMappings[$idField])) {

  1120                     // no composite pk as fk entity assumption:

  1121                     $columnNames[] = $this->associationMappings[$idField]['joinColumns'][0]['name'];

  1122                 } else {

  1123                     $columnNames[] = $this->fieldMappings[$idField]['columnName'];

  1124                 }

  1125             }

  1126             return $columnNames;

  1127         } else if(isset($this->fieldMappings[$this->identifier[0]])) {

  1128             return array($this->fieldMappings[$this->identifier[0]]['columnName']);

  1129         } else {

  1130             // no composite pk as fk entity assumption:

  1131             return array($this->associationMappings[$this->identifier[0]]['joinColumns'][0]['name']);

  1132         }

  1133     }

  1134 

  1135     /**

  1136      * Sets the type of Id generator to use for the mapped class.