Adjust private properties writeup, move it

Author: samdark

guide/en/concept/di-container.md

@@ -68,23 +68,6 @@ final readonly class CachedWidget
 We've avoided unnecessary inheritance and used interface to reduce coupling. You can replace cache
 implementation without changing `CachedWidget` so it's becoming more stable.
 
-### Why use private properties <span id="why-private-properties"></span>
-
-In the composition example above, note that the `$cache` property is declared as `private`. This design choice 
-supports composition by providing several benefits:
-
-- **Encapsulation**: Private properties with getters/setters allow you to control access and make future changes 
-  without breaking existing code.
-- **Data integrity**: Setters can validate, normalize, or format values before storing them, ensuring properties 
-  contain valid data.
-- **Immutability**: Private properties enable immutable object patterns where setters return new instances rather 
-  than modifying the current one.
-- **Flexibility**: You can easily create read-only or write-only properties, or add additional logic to property 
-  access later.
-
-This approach embraces composition by ensuring objects have well-defined interfaces for interaction rather than 
-direct property access, making the code more maintainable and less prone to certain types of mistakes.
-
 The `CacheInterface` here is a dependency: an object another object depends on.
 The process of putting an instance of dependency into an object (`CachedWidget`) is called dependency injection.
 There are many ways to perform it:
@@ -93,21 +76,38 @@ There are many ways to perform it:
 - Method injection. Best for optional dependencies.
 - Property injection. Better to be avoided in PHP except maybe data transfer objects.
 
+### Why use private properties <span id="why-private-properties"></span>
+
+In the composition example above, note that the `$cache` property is declared as `private`.
+
+This approach embraces composition by ensuring objects have well-defined interfaces for interaction rather than
+direct property access, making the code more maintainable and less prone to certain types of mistakes.
+
+This design choice provides several benefits:
+
+- **Encapsulation**: Private properties with getters/setters allow you to control access and make future changes
+  without breaking existing code.
+- **Data integrity**: Setters can validate, normalize, or format values before storing them, ensuring properties
+  contain valid data.
+- **Immutability**: Private properties enable immutable object patterns where setter `with*()` methods return
+  new instances rather than modifying the current one.
+- **Flexibility**: You can create read-only or write-only properties or add additional logic to property access later.
+
 
 ## DI container <span id="di-container"></span>
 
-Injecting basic dependencies is simple and easy. You're choosing a place where you don't care about dependencies,
+Injecting basic dependencies is straightforward. You're choosing a place where you don't care about dependencies,
 which is usually an action handler, which you aren't going to unit-test ever, create instances of dependencies needed
 and pass these to dependent classes.
 
-It works well when there aren't many dependencies overall and when there are no nested dependencies. When there are
+It works well when there are few dependencies overall and when there are no nested dependencies. When there are
 many and each dependency has dependencies itself, instantiating the whole hierarchy becomes a tedious process, which
-requires lots of code and may lead to hard to debug mistakes.
+requires lots of code and may lead to hardly debuggable mistakes.
 
-Additionally, lots of dependencies, such as certain third party API wrapper, are the same for any class using it.
+Additionally, lots of dependencies, such as certain third-party API wrappers, are the same for any class using it.
 So it makes sense to:
 
-- Define how to instantiate such API wrapper once.
+- Define how to instantiate such an API wrapper.
 - Instantiate it when required and only once per request.
 
 That's what dependency containers are for.
@@ -187,9 +187,10 @@ return [
 
 ### Injecting dependencies <span id="injecting-dependencies"></span>
 
-Directly referencing container in a class is a bad idea since the code becomes non-generic, coupled to container interface
-and, what's worse, dependencies are becoming hidden. Because of that, Yii inverts the control by automatically injecting
-objects from a container in some constructors and methods based on method argument types.
+Directly referencing a container in a class is a bad idea since the code becomes non-generic,
+coupled to the container interface and, what's worse, dependencies are becoming hidden. 
+Because of that, Yii inverts the control by automatically injecting objects from a container in some constructors
+and methods based on method argument types.
 
 This is primarily done in constructor and handing method of action handlers:
 
@@ -219,9 +220,9 @@ final readonly class MyController
 ```
 
 Since it's [yiisoft/injector](https://github.com/yiisoft/injector) that instantiates and calls action handler, it
-checks the constructor and method argument types, get dependencies of these types from a container and pass them as
+checks the constructor and method argument types, gets dependencies of these types from a container and passes them as
 arguments. That's usually called auto-wiring. It happens for sub-dependencies as well, that's if you don't give dependency
-explicitly, container would check if it has such a dependency first.
+explicitly, the container would check if it has such a dependency first.
 It's enough to declare a dependency you need, and it would be got from a container automatically.