NotORM Entity

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

You can find it in branch entity: https://github.com/lichtner/notorm/tree/entity

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 
$authorEntity = new AuthorEntity($author);
echo $authorEntity->getName() . "\n";

This brings more problems:

1. It is long and ugly.
2. It moves code to template and make template more confused
3. If you use it on two or more places you need to write it on each place.

NotORM Entity solve this problems.

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 complex 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! Difference is invisible in source code 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
...

Nice, 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:

   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 converted to CamelCase. 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*

If you are not satisfied with NotORM_Entity_Mapper_Convention it is very easy write your own entity mapper implemented interface NotORM_Entity_Mapper.

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 

Clone notorm branch entity here

NotORM Entity: https://github.com/lichtner/notorm/tree/entity