NotORM Entity

NotORM Entity extends NotORM library and added features for working with entities.

Why NotORM Entity?

See next example:
(in all examples I use NotORM example database "software" in file tests/software.sql)

$software = new NotORM($pdo);
foreach ($software->author() as $author) {
    echo "$author[name]\n";
}

$author[name] get raw data from database. If you want to do some modification you need add some helper e.g.:

echo author_title_helper($author['name']) . "\n"; 
// or e.g...
$authorEntity = new AuthorEntity($author);
echo $authorEntity->getName() . "\n";

This brings more problems:

1. It is very long and ugly.
2. If you use it on two or more places you need to write it on each place.

NotORM Entity solve this problems with minimum code modifications.

How looks NotORM Entity usage?

For example we want to use this entities:

abstract class Entity {
    protected $row;
    function __construct($row) {
        $this->row = $row;
    }
}

class Author extend Entity {
    function getName() {
        return 'author: ' . $this->row['name'];
    }
}

class Application extend Entity {
    function getTitle() {
        return 'app: ' . $this->row['title'];
    }
}

class Tag extend Entity {
    function getName() {
        return 'tag: ' . $this->row['name'];
    }
}

If you want to use it with origin NotORM you can do:

foreach ($software->author() as $author) {
    $authorEntity = new Author($author);
    echo $authorEntity->getName() . "\n";
}

in more difficult example it is very complicated code and absolutely not sufficient for templates:

foreach ($software->application()->order("title") as $application) {
    $applicationEntity = new Application($application); 
    echo $applicationEntity->getTitle() . ' - '; 
    $authorEntity = new Author($application->author);
    echo $authorEntity->getName() . "\n";
    foreach ($application->application_tag() as $application_tag) {
       $tagEntity = new Tag($application_tag->tag);
       echo $tagEntity->getName() . "\n";
    }
}

IMHO this is the reason why many guys don't want to use NotORM in bigger projects which need entities.

How could be written previous example with NotORM Entity?

foreach ($software->application()->order("title") as $application) {
    echo "$application[title] - " . $application->author['name'] . "\n"; 
    foreach ($application->application_tag() as $application_tag) {
       echo " - " . $application_tag->tag['name'] . "\n";
    }
}

Yes, this is same syntax as plain NotORM library but if you use NotORM Entity then $application, $application->author and $application_tag->tag will not be NotORM_Row instances but applicable entities (Application, Author and Tag) and result will be:

app: software_title - author: author_name
 - tag: tag_name1
 - tag: tag_name2
...

Really interesting, isn't it?

How can I setup NotORM Entity?

You need to do only two steps:

1. Create entity mapper which map table from database to entities:

   $entityMapper = new NotORM_Entity_Mapper_Convention; $software = new NotORM($connection, null, null, $entityMapper);

2. Extends your entities by NotORM_Entity e.g.:

   class Author extends NotORM_Entity { function getName() { return 'author: ' . $this->row['name']; } }

This is all. For tables which doesn't set entity will be used default NotORM_Row. Column which doesn't set getter you get raw data from database.

Of course you can set setters:

class Author extends NotORM_Entity {
    function getName() {
        return 'author: ' . $this->row['name'];
    }
    function setPassword($value) {
        $this->row['password'] = md5($value);
    }
}

Customization of NotORM_Entity_Mapper_Convention

You can customize NotORM_Entity_Mapper_Convention by parameters namespace, prefix or suffix or mapper array.

If your entities are in namespace use:

$entityMapper = new NotORM_Entity_Mapper_Convention('App\\Entity\\');

if you use suffix or prefix use second parameter:

$entityMapper = new NotORM_Entity_Mapper_Convention('', '%s_Entity');

%s will be replaced by table. For non conventional entity use third parameter:

$entityMapper = new NotORM_Entity_Mapper_Convention('', '%s', array('author' => 'UserModel'));

and you can use it all together.

For more example usage see tests/entity*

Important notice

While creating and building SQL code with NotORM Entity you are working only with tables not with entities like in doctrine 2. Only result will be Entity! E.g. if you have entity:

class Author_Entity {
...
}

You never write:

$software->Author_Entity()->...  // bad 

always you use only tables:

 $software->author()->...        // good