Why does ORM persist() functionality use references to populate insert_id and not return?

Question

My understanding of how ORM persist works:

//ORM "persist" oversimplification
function persist(&$entity)
{
    ...
    $insertId = api_actual_db_insert(...);
    $entity->setId($insertId);
}

//usage of ORM later ...
$this->getEntityManager()->persist($entity);
print $entity->getId();  //prints ID of newly inserted record

But why not ..

function persist($entity)
{
    ...
    $insertId = api_actual_db_insert(...);
    return $insertId;
}

//later ...
$insertId = $this->getEntityManager()->persist($entity);
$entity->setId($insertId);
print $entity->getId();

Both ways work. My issue is with "references". I can perhaps see a little bit why and what the reasoning is behind why ORMs work this way .., but my question stems from writing my own similar domain specific functionality that I have decided to mimic after the ORM concepts and I am having "issues" with using references. Not technical issues but moral and computer sciency-issues as far as reasoning and rationale for using them in this context.

To be precise, examining Doctrine's own code (my choice of ORM), I did not see an explicit Entity reference being passed, so the mechanics of an ORM may use some other different technique. My question will stand though regardless of the method. What's of interest to me is that Entity is populated with the insert_id, and insert_id is not returned explicitly.

My code

I have a concept of Selection object that contains a lot of stuff. Maybe later it may become a true Entity, but right now it's not (lots of refactoring work to be done before it is ready), so I have to manage it manually, without ORM backing. I wrote my own persist function that is similar and my question is basically what I've already stated above. I may understand why an ORM works this way but I do not understand if I should implement my own storage the same way or not.

Question

To be explicit ... is there any particular or specific reason why an ORM would use this specific technique of populating Entity with insert_id without an explicit return statement, opposed to returning insert_id explicitly via return statement to the caller? If I do choose to return insert_id explicitly, what will I be missing/breaking?

Answer 1

You are running up against the challenges inherent to an ORM. ORM's are by definition leaky abstractions. Martin Fowler has an excellent article addressing your "moral and computer-sciency issues". http://martinfowler.com/bliki/OrmHate.html

The truth is, ORM's are a pain and never feel right, especially for purists. This is because quite simply they are not pure. By definition, they are not a pure abstraction (persisting/syncing data to an external store), but an implementation detail (specifically, persisting/syncing data to some relational data store).

As to your concern "if I should implement my own storage the same way or not", Fowler's basic point is that at some point, in order to program against a database well, you have to realize the relational database is actually part of the domain, and so it must be reflected in the domain model. The sooner you can come to terms with this concept the sooner your path forward will make sense.

With all of that said, it is simply more code to write:

id = perist(entity);
entity.id = id;
print entity.id;

than to write

persist(entity);
print entity.id;

And the second is more clear and more readable. If there is anything you are missing it will be clarity.