phalcon/cphalcon — pull request #2917 by golovanov (2014-10-17 11:25:55+00:00)
Title: MVC: Entity

# MVC: Entity

MVC: Entity (Entity Managment) - this is a common functionality for ORM (Models) and ODM (Mongo Collections).
Using this feature you can implement your own ODM/ORM (eg. ODM for CouchDB).

!!! IMPORTANT !!! This feature has full backward compatibility!

This is very handy if you want to write a module that can work with different databases.
Eg.
```php
interface UserInterface extends \Phalcon\Mvc\EntityInterface
{
// some additional code here
}
```
Implements as collection:
```php
class UserCollection extends \Phalcon\Mvc\Collection implements UserInterface
{
// some additional code here
}
```

Implements as model:
```php
class UserModel extends \Phalcon\Mvc\Model implements UserInterface
{
// some additional code here
}
```

Using #1:

```php

$user = DI::getDefault()->get('newuserinstance');
// i don't know the $user is model or collection or something else.
if ($user instanceof \Phalcon\Mvc\EntityInterface) {
// i can do it :)
$user->writeAttribute('name', 10);
$name = $user->readAttribute('name');
$user->create();
$user->update();
$user->save();
$user->delete();
}

if ($user instanceof \Phalcon\Mvc\StaticFinderInterface) {
$users = $user::find(['limit' => 10]);
}

```

Using #2:
```php
class Example
{
public function deleteUser(UserInterface $user)
{
// I do not care, it is a model or a collection, or something else. I need to remove! :)
$status = $user->delete();

echo $status? 'ok' : 'not deleted';
}
}

$example = new Example();
$dbUser = UserModel::findFirst();
$mongoUser = UserCollection::findFirst();

$example->deleteUser($dbUser); // ok
$example->deleteUser($mongoUser); // ok
```

In the EM have been created the following general components:

Phalcon\Mvc\EntityInterface
Phalcon\Mvc\Entity
Phalcon\Mvc\Entity\ManagerInterface
Phalcon\Mvc\Entity\Manager
Phalcon\Mvc\Entity\Exception
Phalcon\Mvc\Entity\MessageInterface
Phalcon\Mvc\Entity\Message
Phalcon\Mvc\Entity\BehaviorInterface
Phalcon\Mvc\Entity\Behavior
Phalcon\Mvc\Entity\ResultsetInterface
Phalcon\Mvc\Entity\StaticFinderInterface
Phalcon\Mvc\Entity\ValidatorInterface
Phalcon\Mvc\Entity\Validator
Phalcon\Mvc\Entity\Validator\Email
Phalcon\Mvc\Entity\Validator\Exclusionin
Phalcon\Mvc\Entity\Validator\Inclusionin
Phalcon\Mvc\Entity\Validator\Numericality
Phalcon\Mvc\Entity\Validator\PresenceOf
Phalcon\Mvc\Entity\Validator\Regex
Phalcon\Mvc\Entity\Validator\StringLength
Phalcon\Mvc\Entity\Validator\Url
Phalcon\Mvc\Entity\Behavior\SoftDelete
Phalcon\Mvc\Entity\Behavior\Timestampable

Was implemented new inheritance hierarchy in the classes and interfaces:

- Phalcon\Mvc\CollectionInterface extends from Phalcon\Mvc\EntityInterface
- Phalcon\Mvc\Collection extends from Phalcon\Mvc\Entity and implements Phalcon\Mvc\CollectionInterface
- Phalcon\Mvc\Collection\Exception extends from Phalcon\Mvc\Entity\Exception
- Phalcon\Mvc\Collection\ManagerInterface extends from Phalcon\Mvc\Entity\ManagerInterface
- Phalcon\Mvc\Collection\Manager extends from Phalcon\Mvc\Entity\Manager and implements Phalcon\Mvc\Collection\ManagerInterface

- Phalcon\Mvc\ModelInterface extends from Phalcon\Mvc\EntityInterface
- Phalcon\Mvc\Model extends from Phalcon\Mvc\Entity and implements Phalcon\Mvc\ModelInterface
- Phalcon\Mvc\Model\Exception extends from Phalcon\Mvc\Entity\Exception
- Phalcon\Mvc\Model\ManagerInterface extends from Phalcon\Mvc\Entity\ManagerInterface
- Phalcon\Mvc\Model\Manager extends from Phalcon\Mvc\Entity\Manager and implements Phalcon\Mvc\Model\ManagerInterface
- Phalcon\Mvc\Model\ResultsetInterface extends from Phalcon\Mvc\Entity\ResultsetInterface

For backward compatibility were left dummy classes and interfaces:

- Phalcon\Mvc\Model\MessageInterface
- Phalcon\Mvc\Model\Message
- Phalcon\Mvc\Model\BehaviorInterface
- Phalcon\Mvc\Model\Behavior
- Phalcon\Mvc\Model\ValidatorInterface
- Phalcon\Mvc\Model\Validator
- Phalcon\Mvc\Model\Validator\Email
- Phalcon\Mvc\Model\Validator\Exclusionin
- Phalcon\Mvc\Model\Validator\Inclusionin
- Phalcon\Mvc\Model\Validator\Numericality
- Phalcon\Mvc\Model\Validator\PresenceOf
- Phalcon\Mvc\Model\Validator\Regex
- Phalcon\Mvc\Model\Validator\StringLength
- Phalcon\Mvc\Model\Validator\Url
- Phalcon\Mvc\Model\Behavior\SoftDelete
- Phalcon\Mvc\Model\Behavior\Timestampable

General of them have hierarchy:

- Phalcon\Mvc\Model\MessageInterface extends from Phalcon\Mvc\Entity\MessageInterface
- Phalcon\Mvc\Model\Message extends from Phalcon\Mvc\Entity\Message and implements Phalcon\Mvc\Model\MessageInterface
- Phalcon\Mvc\Model\BehaviorInterface extends from Phalcon\Mvc\Entity\BehaviorInterface
- Phalcon\Mvc\Model\Behavior extends from Phalcon\Mvc\Entity\Behavior and implements Phalcon\Mvc\Model\BehaviorInterface
- Phalcon\Mvc\Model\ValidatorInterface extends from Phalcon\Mvc\Entity\ValidatorInterface
- Phalcon\Mvc\Model\Validator extends from Phalcon\Mvc\Entity\Validator and implements Phalcon\Mvc\Model\ValidatorInterface

To the entity were moved the next general methods:

- fireEvent();
- fireEventCancel();
- appendMessage();
- validationHasFailed();
- getMessages();
- assign();
- setDirtyState();
- getDirtyState();
- readAttribute();
- writeAttribute();
- save();
- create();
- update();
- delete();
- setSnapshotData();
- skipOperation();
- getOperationMade();

To the entity manager were moved the next general methods:

- initialize();
- isInitialized();
- getLastInitialized();
- addBehavior();
- notifyEvent();
- missingMethod();
- load();
- keepSnapshots();
- isKeepingSnapshots();
- useDynamicUpdate();
- isUsingDynamicUpdate();

Also in the Phalcon\Mvc\Entity and Phalcon\Mvc\Entity\Manager have been moved/implemented common functional for Models/Collections.