Fix #137: Add explanation of private properties benefits in DI container guide

Co-authored-by: Alexander Makarov <[email protected]>

Author: Copilot

guide/en/concept/di-container.md

@@ -76,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.
@@ -170,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:
 
@@ -202,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.
 
 

guide/po/concept_di-container.md/concept_di-container.md.pot

@@ -7,7 +7,7 @@
 msgid ""
 msgstr ""
 "Project-Id-Version: PACKAGE VERSION\n"
-"POT-Creation-Date: 2025-09-04 07:37+0500\n"
+"POT-Creation-Date: 2025-09-05 12:06+0000\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <[email protected]>\n"
@@ -146,6 +146,61 @@ msgid ""
 "objects."
 msgstr ""
 
+#. type: Title ###
+#: en/concept/di-container.md
+#, no-wrap
+msgid "Why use private properties <span id=\"why-private-properties\"></span>"
+msgstr ""
+
+#. type: Plain text
+#: en/concept/di-container.md
+msgid ""
+"In the composition example above, note that the `$cache` property is "
+"declared as `private`."
+msgstr ""
+
+#. type: Plain text
+#: en/concept/di-container.md
+msgid ""
+"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."
+msgstr ""
+
+#. type: Plain text
+#: en/concept/di-container.md
+msgid "This design choice provides several benefits:"
+msgstr ""
+
+#. type: Bullet: '- '
+#: en/concept/di-container.md
+msgid ""
+"**Encapsulation**: Private properties with getters/setters allow you to "
+"control access and make future changes without breaking existing code."
+msgstr ""
+
+#. type: Bullet: '- '
+#: en/concept/di-container.md
+msgid ""
+"**Data integrity**: Setters can validate, normalize, or format values before "
+"storing them, ensuring properties contain valid data."
+msgstr ""
+
+#. type: Bullet: '- '
+#: en/concept/di-container.md
+msgid ""
+"**Immutability**: Private properties enable immutable object patterns where "
+"setter `with*()` methods return new instances rather than modifying the "
+"current one."
+msgstr ""
+
+#. type: Bullet: '- '
+#: en/concept/di-container.md
+msgid ""
+"**Flexibility**: You can create read-only or write-only properties or add "
+"additional logic to property access later."
+msgstr ""
+
 #. type: Title ##
 #: en/concept/di-container.md
 #, no-wrap
@@ -155,7 +210,7 @@ msgstr ""
 #. type: Plain text
 #: en/concept/di-container.md
 msgid ""
-"Injecting basic dependencies is simple and easy. You're choosing a place "
+"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."
@@ -164,22 +219,23 @@ msgstr ""
 #. type: Plain text
 #: en/concept/di-container.md
 msgid ""
-"It works well when there aren't many dependencies overall and when there are "
-"no nested dependencies. When there are many and each dependency has "
+"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."
+"process, which requires lots of code and may lead to hardly debuggable "
+"mistakes."
 msgstr ""
 
 #. type: Plain text
 #: en/concept/di-container.md
 msgid ""
-"Additionally, lots of dependencies, such as certain third party API wrapper, "
-"are the same for any class using it.  So it makes sense to:"
+"Additionally, lots of dependencies, such as certain third-party API "
+"wrappers, are the same for any class using it.  So it makes sense to:"
 msgstr ""
 
 #. type: Bullet: '- '
 #: en/concept/di-container.md
-msgid "Define how to instantiate such API wrapper once."
+msgid "Define how to instantiate such an API wrapper."
 msgstr ""
 
 #. type: Bullet: '- '
@@ -315,9 +371,9 @@ msgstr ""
 #. type: Plain text
 #: en/concept/di-container.md
 msgid ""
-"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 "
+"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."
 msgstr ""
@@ -361,9 +417,9 @@ msgstr ""
 msgid ""
 "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 "
+"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, "
+"dependencies as well, that's if you don't give dependency 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."

guide/po/concept_di-container.md/ru/concept_di-container.md.ru.po

@@ -6,7 +6,7 @@
 msgid ""
 msgstr ""
 "Project-Id-Version: \n"
-"POT-Creation-Date: 2025-09-04 07:37+0500\n"
+"POT-Creation-Date: 2025-09-05 12:06+0000\n"
 "PO-Revision-Date: 2025-09-04 07:50+0500\n"
 "Last-Translator: Automatically generated\n"
 "Language-Team: none\n"
@@ -189,6 +189,48 @@ msgstr "Через метод. Лучше использовать для нео
 msgid "Property injection. Better to be avoided in PHP except maybe data transfer objects."
 msgstr "Через свойство. Лучше избегать использования в PHP, за исключением, может быть, объектов передачи данных (DTO)"
 
+#. type: Title ###
+#: en/concept/di-container.md
+#, fuzzy, no-wrap
+#| msgid "References <span id=\"references\"></span>"
+msgid "Why use private properties <span id=\"why-private-properties\"></span>"
+msgstr "Полезные ссылки <span id=\"references\"></span>"
+
+#. type: Plain text
+#: en/concept/di-container.md
+msgid "In the composition example above, note that the `$cache` property is declared as `private`."
+msgstr ""
+
+#. type: Plain text
+#: en/concept/di-container.md
+msgid "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."
+msgstr ""
+
+#. type: Plain text
+#: en/concept/di-container.md
+msgid "This design choice provides several benefits:"
+msgstr ""
+
+#. type: Bullet: '- '
+#: en/concept/di-container.md
+msgid "**Encapsulation**: Private properties with getters/setters allow you to control access and make future changes without breaking existing code."
+msgstr ""
+
+#. type: Bullet: '- '
+#: en/concept/di-container.md
+msgid "**Data integrity**: Setters can validate, normalize, or format values before storing them, ensuring properties contain valid data."
+msgstr ""
+
+#. type: Bullet: '- '
+#: en/concept/di-container.md
+msgid "**Immutability**: Private properties enable immutable object patterns where setter `with*()` methods return new instances rather than modifying the current one."
+msgstr ""
+
+#. type: Bullet: '- '
+#: en/concept/di-container.md
+msgid "**Flexibility**: You can create read-only or write-only properties or add additional logic to property access later."
+msgstr ""
+
 #. type: Title ##
 #: en/concept/di-container.md
 #, no-wrap
@@ -197,28 +239,36 @@ msgstr "Контейнер внедрения зависимостей <span id=
 
 #. type: Plain text
 #: en/concept/di-container.md
-msgid "Injecting basic dependencies is simple and easy. 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."
+#, fuzzy
+#| msgid "Injecting basic dependencies is simple and easy. 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."
+msgid "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."
 msgstr ""
 "Внедрять базовые зависимости просто и легко.\n"
 "Вы выбираете место, где вас не волнуют зависимости, которые обычно являются обработчиками действий и которые вы не собираетесь тестировать, создаете экземпляры необходимых зависимостей и передаете их в зависимые классы."
 
 #. type: Plain text
 #: en/concept/di-container.md
-msgid "It works well when there aren't many 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."
+#, fuzzy
+#| msgid "It works well when there aren't many 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."
+msgid "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 hardly debuggable mistakes."
 msgstr ""
 "Это хорошо работает, когда в целом зависимостей немного и нет вложенных зависимостей.\n"
 "Когда их много, и каждая зависимость сама имеет зависимости, создание всей иерархии становится утомительным процессом, который требует большого количества кода и может привести к трудно отлаживаемым ошибкам."
 
 #. type: Plain text
 #: en/concept/di-container.md
-msgid "Additionally, lots of dependencies, such as certain third party API wrapper, are the same for any class using it.  So it makes sense to:"
+#, fuzzy
+#| msgid "Additionally, lots of dependencies, such as certain third party API wrapper, are the same for any class using it.  So it makes sense to:"
+msgid "Additionally, lots of dependencies, such as certain third-party API wrappers, are the same for any class using it.  So it makes sense to:"
 msgstr ""
 "Кроме того, многие зависимости, такие как некоторые сторонние обертки API, одинаковы для любого класса, использующего его.\n"
 "Поэтому имеет смысл:"
 
 #. type: Bullet: '- '
 #: en/concept/di-container.md
-msgid "Define how to instantiate such API wrapper once."
+#, fuzzy
+#| msgid "Define how to instantiate such API wrapper once."
+msgid "Define how to instantiate such an API wrapper."
 msgstr "Определить, как создать экземпляр такой обертки API один раз."
 
 #. type: Bullet: '- '
@@ -390,7 +440,9 @@ msgstr "Внедрение зависимостей <span id=\"injecting-depende
 
 #. type: Plain text
 #: en/concept/di-container.md
-msgid "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."
+#, fuzzy
+#| msgid "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."
+msgid "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."
 msgstr "Непосредственное обращение к контейнеру в классе — плохая идея, так как код становится не универсальным, сопряжен с интерфейсом контейнера и, что еще хуже, зависимости становятся скрытыми. Поэтому Yii инвертирует управление, автоматически вводя объекты из контейнера в конструкторы и методы, основываясь на типах аргументов."
 
 #. type: Plain text
@@ -449,7 +501,9 @@ msgstr ""
 
 #. type: Plain text
 #: en/concept/di-container.md
-msgid "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 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.  It's enough to declare a dependency you need, and it would be got from a container automatically."
+#, fuzzy
+#| msgid "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 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.  It's enough to declare a dependency you need, and it would be got from a container automatically."
+msgid "Since it's [yiisoft/injector](https://github.com/yiisoft/injector) that instantiates and calls action handler, it 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, 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."
 msgstr ""
 "Поскольку именно [yiisoft/injector](https://github.com/yiisoft/injector) создает экземпляр и вызывает обработчик действий - он проверяет типы аргументов конструктора и метода, получает зависимости этих типов из контейнера и передает их как аргументы.\n"
 "Обычно это называется автоматическим разрешением зависимостей.\n"