docs update

Author: michalsn

docs/basic_usage.md

@@ -34,6 +34,35 @@ model(UserModel::class)->with('profile')->findAll();
 
 This will perform two queries. One for all users, and one to fetch all the profiles for these users.
 
+!!! note
+
+    You can still use your model as usual. If you omit the `with()` part, your model will work like a normal model.
+
+### Writing with relation
+
+For simple relations like `hasOne` or `hasMany`, you can also save the entire object that contains relations inside.
+
+So this is also possible:
+
+```php
+$userModel = model(UserModel::class);
+$user      = $userModel->with('profile')->find(1);
+
+$user->profile->favorite_pet = 'Cat';
+
+$userModel->with('profile')->save($user);
+```
+
+!!! note
+
+    If you use validation in the model, you should use a `useTransactions()` method to make sure that if something goes wrong, all changes are rolled back.
+
+    ```php
+    $userModel->with('profile')->useTransactions()->save($user);
+    ```
+
+    In general, if you are saving an object with a relation, you should always use this method.
+
 ## Lazy loading
 
 Here we also have to specify our relations, just like in eager loading. The only difference is that we are required to use an `Entity` for our `$returnType`. That's because the entity will be responsible for triggering the relation request.

docs/configuration.md

@@ -24,4 +24,4 @@ This library relies on traits.
 
 ### Entities
 
-- Every entity should use `HasLazyRelations` trait.
+- Every entity should use `HasLazyRelations` trait - of course only if we want to use lazy loading.

docs/relations.md

@@ -188,11 +188,23 @@ class UserModel extends Model
 
     public function address(): Relation
     {
-        return $this->hasOneThrough(AddressModel::class, CompanyModel::class);
+        return $this->hasOneThrough(
+            AddressModel::class,
+            CompanyModel::class,
+            'address_id', // foreignKey - AddressModel
+            'id', // foreignKey - CompanyModel
+            'id', // primaryKey - AddressModel
+            'company_id', // primaryKey - CompanyModel
+        );
     }
 }
 ```
 
+In this case we have to specify custom `$foreignKey` and `$primaryKey` for `CompanyModel` which will have the value of `id` and `company_id` respectively.
+
+!!! note
+    We can assign custom keys for all relations.
+
 ### Usage
 
 ```php