El componente EntityManager es usado internamente por el framework y principalmente por ActiveRecord y Controller para administrar las entidades, sus relaciones de asociación, relaciones de integridad y generadores de tal forma que el acceso a ellas sea consistente y uniforme.

La clase EntityManager es una clase abstracta en la que sus métodos solo pueden ser invocados estáticamente, de esta forma se asegura que los datos de entidades y sus relaciones existan solo una vez por proceso de negocio.

Cada vez que se llama el constructor de una clase de ActiveRecord se ejecutan procedimientos internos como la inicialización del modelo, tals como la localización del data source, la definición de las relaciones con otros modelos y en algunos casos se trata de volcar los meta-datos de la tabla si estos no se encuentran disponibles para la aplicación.

El componente EntityManager proporciona el método getEntityInstance(string $instanceName) que permite obtener una instancia de la entidad ya inicializada mejorando el rendimiento de un proceso de negocio.

En el siguiente ejemplo se muestra como se reemplaza el instanciamiento mediante new por el método de obtener instancias ya inicializadas en blanco:

Ejemplo: Obtener instancias de modelos en forma eficiente

<?php

try {
     $transaction = TransactionManager::getUserTransaction();     
     $this->Movement->setTransaction($transaction);
     $this->Cart->setTransaction($transaction);
     $conditions = "sellDate = '".Date::getCurrentDate()."'";
     foreach($this->Movement->find($conditions) as $movement){
          $productSt = EntityManager::getEntityInstance("ProductStatistics");
          $productSt->setTransaction($transaction);
          $productSt->setProductId($movement->getProductId());
          $productSt->setCantidad($movement->getQuantity());
          if($productSt->save()==false){
               foreach($productSt->getMessages() as $message){
                    Flash::error($message->getMessage());
               }
               $transaction->rollback();
          }
     }
     $transaction->commit();
}
catch(TransactionFailed $e){
     Flash::error($e->getMessage());
}

Nota: Podría obtener un error como "Fatal error: Cannot redeclare class Products in /path/to/application/instance/apps/default/models/products.php on line 230" si no establece el parámetro de getEntityInstance usando el nombre de la clase modelo tal y como fué definida en el archivo del modelo.

El desarrollador no debería interactuar directamente con este componente ya que ActiveRecord y sus subcomponentes son los encargados de utilizar este API para administrar las relaciones y la información de las entidades. La siguiente API es presentada buscando ayudar a extender el core del framework ó reemplazar este componente.

static function array getEntities()
Obtiene un vector con todas las entidades inicializadas en la petición actual.

static function void setAutoInitialize(boolean $autoInitialize)
Establece si los modelos son auto-inializados ó no.

static function boolean getAutoInitialize()
Indica si los modelos están siendo auto-inicializados ó no.

static function void setModelsDirectory(string $modelsDir)
Establece el directorio desde donde deben ser cargados los modelos.

static function mixed getEntityInstance(string $entityName, boolean $newInstance=true)
Obtiene una instancia de una clase de un modelo. Si se pasa false en el segundo parámetro se obtiene una instancia existente.

static function void initModelBase(string $modelsDir)
Carga la clase ActiveRecord ubicada en el directorio de modelos de la aplicación.

static function void initModels(string $modelsDir)
Inicializa el directorio de modelos cargandolos e inicializandolos.

static function boolean isEntity(string $entityName)
Permite consultar si existe un determinado modelo en la petición actual.

static function boolean isModel(string $modelName)
Es un alias del método isEntity.

static function string getEntityName(string $model)
Obtiene el nombre de una entidad de acuerdo a su origen de datos (tabla).

static function void addEntityByClass(string $entityClass)
Inicializa un dinámicamente modelo por el nombre de su clase.

static function boolean existsBelongsTo(string $entityName, string $relationRequested)
Permite consultar si una entidad está relacionada con otra mediante una relación tipo belongsTo (muchos a 1) al menos unidireccionalmente.

static function boolean existsHasMany(string $entityName, string $relationRequested)
Permite consultar si una entidad está relacionada con otra mediante una relación tipo hasMany (1 a muchos) al menos unidireccionalmente.

static function boolean existsHasOne(string $entityName, string $relationRequested)
Permite consultar si una entidad está relacionada con otra mediante una relación tipo hasOne (1 a 1) al menos unidireccionalmente.

static function boolean getBelongsToRecords(string $entityName, string $relationRequested, ActiveRecord $record)
Obtiene un resultado de los registros relacionados mediante una relación de multiplicidad belongsTo. El parámetro $record es la instancia de un modelo utilizada para efectuar la operación.

static function boolean getHasOneRecords(string $entityName, string $relationRequested, ActiveRecord $record)
Obtiene un resultado de los registros relacionados mediante una relación de multiplicidad hasOne. El parámetro $record es la instancia de un modelo utilizada para efectuar la operación.

static function boolean getHasManyRecords(string $entityName, string $relationRequested, ActiveRecord $record)
Obtiene un resultado de los registros relacionados mediante una relación de multiplicidad hasMany. El parámetro $record es la instancia de un modelo utilizada para efectuar la operación.

static function void addBelongsTo(string $entityName, string $fields='', string $referenceTable='', string $referencedFields='', string $relationName='')
Agrega una relación belongsTo al administrador de entidades en forma programacional.

static function void addHasMany(string $entityName, mixed $fields='', string $referenceTable='', mixed $referencedFields='')
Agrega una relación belongsTo al administrador de entidades en forma programacional.

static function void addHasOne(string $entityName, mixed $fields='', string $referenceTable='', mixed $referencedFields='')
Agrega una relación hasOne al administrador de entidades en forma programacional.

static function void addTrasientAttribute(string $entityName, string $attribute)
Agrega un atributo de una entidad que no debe ser persistido.

static function array getRelationsOf(string $entityName)
Obtiene un array con las relaciones que han sido definidas para una determinada entidad.

static function boolean existsTemporaryEntity(string $entityName)
Permite consultar si una entidad temporal ya ha sido definida.

static function void addTemporaryEntity(string $entityName)
Agrega una entidad temporal al administrador de entidades.

static function void destroyTemporaryEntity(string $entityName)
Destruye una entidad temporal del administrador de entidades.

static function boolean isCreatedTemporaryEntity(DbBase $connection, string $entityName)
Consulta si una entidad temporal ya ha sido creada en una determinada conexión.

static function string getSourceName(string $entityName)
Obtiene el origen de datos (tabla) de una determinada entidad

static function void setEntityGenerator(string $entityName, string $adapter, string $column, array $options)
Establece el generador de una determinada entidad.

static function boolean hasGenerator(string $entityName)
Indica si una entidad tiene definido algun generador.

static function ActiveRecordGenerator getEntityGenerator(string $entityName)
Obtiene el generador de una determinada entidad.

static function array getAllCreatedGenerators()
Obtiene todos los generadores definidos en la petición actual.

static function void addForeignKey(string $entityName, array $fields='', string $referenceTable='', array $referencedFields='', array $options=array())
Establece una llave foránea virtual en una entidad.

static function array getForeignKeys(string $entityName)
Obtiene las llaves foráneas virtuales definidas para una entidad.

static function boolean hasForeignKeys(string $entityName)
Permite consultar una entidad tiene llaves foráneas virtuales definidas.