update the documentation

docs/entities.md

@@ -138,3 +138,29 @@ class User extends ORM\Entity
 
 **\*** The methods have to follow `OPT_NAMING_SCHEME_METHODS`. So if you use `set_some_var` you should set the naming
 scheme to `snake_lower`.
+
+### Creating entities and working in transactions
+
+To create a new entity you can use the `new` keyword. This will create a new entity with the default values from the
+entity definition. You can then modify the entity and save it to the database.
+
+```php
+$user = new User();
+$user->email = '[email protected]';
+$user->save();
+```
+
+To work in a transaction you can use the `EntityManager::beginTransaction()` method. This will start a transaction or 
+create a savepoint if a transaction is already started. You can then commit or rollback the transaction.
+
+```php
+$entityManager->beginTransaction();
+$user = new User();
+$user->email = '[email protected]';
+$user->save();
+$activation = new UserActivation();
+$activation->setRelated('user', $user);
+$activation->code($code = bin2hex(random_bytes(8)));
+$activation->save();
+$entityManager->commit();
+```

docs/reference.md

@@ -2282,11 +2282,14 @@ in the manual under [https://tflori.github.io/orm/entityDefinition.html](Entity
 * [__construct](#ormentity__construct) Constructor
 * [__get](#ormentity__get) 
 * [__isset](#ormentity__isset) Check if a column is defined
+* [__serialize](#ormentity__serialize) 
 * [__set](#ormentity__set) 
+* [__unserialize](#ormentity__unserialize) 
 * [addRelated](#ormentityaddrelated) Add relations for $relation to $entities
 * [boot](#ormentityboot) Boot the class
 * [bootIfNotBooted](#ormentitybootifnotbooted) Boot the class if it not already booted
 * [bootTraits](#ormentityboottraits) Boot the traits of the class
+* [delete](#ormentitydelete) Delete the entity
 * [deleteRelated](#ormentitydeleterelated) Delete relations for $relation to $entities
 * [describe](#ormentitydescribe) Get a description for this table.
 * [detachObserver](#ormentitydetachobserver) Stop observing the class by $observer
@@ -2419,6 +2422,21 @@ public function __isset( $attribute ): boolean
 
 
 
+#### ORM\Entity::__serialize
+
+```php
+public function __serialize()
+```
+
+
+
+
+**Visibility:** this method is **public**.
+<br />
+
+
+
+
 #### ORM\Entity::__set
 
 ```php
@@ -2444,6 +2462,27 @@ public function __set( string $attribute, $value )
 **See Also:**
 
 * self::getAttribute 
+#### ORM\Entity::__unserialize
+
+```php
+public function __unserialize( array $data )
+```
+
+
+
+
+**Visibility:** this method is **public**.
+<br />
+
+
+##### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `$data` | **array**  |  |
+
+
+
 #### ORM\Entity::addRelated
 
 ```php
@@ -2522,6 +2561,23 @@ protected static function bootTraits()
 
 
 
+#### ORM\Entity::delete
+
+```php
+public function delete(): $this
+```
+
+##### Delete the entity
+
+> You might want to implement soft deletes by overriding this method.
+
+**Visibility:** this method is **public**.
+<br />
+ **Returns**: this method returns **$this**
+<br />
+
+
+
 #### ORM\Entity::deleteRelated
 
 ```php
@@ -3398,7 +3454,7 @@ Helpful to reduce the size of serializations of the object (for caching, or toAr
 #### ORM\Entity::save
 
 ```php
-public function save(): ORM\Entity
+public function save(): $this
 ```
 
 ##### Save the entity to EntityManager
@@ -3407,7 +3463,7 @@ public function save(): ORM\Entity
 
 **Visibility:** this method is **public**.
 <br />
- **Returns**: this method returns **\ORM\Entity**
+ **Returns**: this method returns **$this**
 <br />**Throws:** this method may throw **\ORM\Exception\IncompletePrimaryKey**<br />
 
 

docs/relations.md

@@ -94,7 +94,7 @@ if ($article = $em->fetch(Article::class, 1)) {
 // Example - create an article
 /** @var User $user */
 if ($user = @$_SESSION['user']) {
-    $em->getConnection()->beginTransaction();
+    $em->beginTransaction();
 
     $article = new Article();
     $article->title = 'An amazing title that points out nothing';
@@ -107,7 +107,7 @@ if ($user = @$_SESSION['user']) {
     $additional->setRelated('article', $article);
     $additional->save();
 
-    $em->getConnection()->commit();
+    $em->commit();
 }
 
 // Example - update categories
@@ -117,10 +117,10 @@ if ($article = $em->fetch(Article::class, 1)) {
     $categoryKeys = $_POST['categories'];
     $newCategories = $em->fetch(Category::class)->where('key', $categoryKeys)->all();
 
-    $em->getConnection()->beginTransaction();
+    $em->beginTransaction();
     $article->deleteRelated(array_diff($currentCategories, $newCategories));
     $article->addRelated(array_diff($newCategories, $currentCategories));
-    $em->getConnection()->commit();
+    $em->commit();
 }
 ```