]> git.mxchange.org Git - friendica.git/blob - doc/Developer-Domain-Driven-Design.md
Merge pull request #13146 from MrPetovan/bug/deprecated
[friendica.git] / doc / Developer-Domain-Driven-Design.md
1 Domain-Driven-Design
2 ==============
3
4 * [Home](help)
5   * [Developer Intro](help/Developers-Intro)
6
7 Friendica uses class structures inspired by Domain-Driven-Design programming patterns.
8 This page is meant to explain what it means in practical terms for Friendica development.
9
10 ## Inspiration
11
12 - https://designpatternsphp.readthedocs.io/en/latest/Structural/DependencyInjection/README.html
13 - https://designpatternsphp.readthedocs.io/en/latest/Creational/SimpleFactory/README.html
14 - https://designpatternsphp.readthedocs.io/en/latest/More/Repository/README.html
15 - https://designpatternsphp.readthedocs.io/en/latest/Creational/FactoryMethod/README.html
16 - https://designpatternsphp.readthedocs.io/en/latest/Creational/Prototype/README.html
17
18 ## Core concepts
19
20 ### Models and Collections
21
22 Instead of anonymous arrays of arrays of database field values, we have Models and collections to take full advantage of PHP type hints.
23
24 Before:
25 ```php
26 function doSomething(array $intros)
27 {
28     foreach ($intros as $intro) {
29         $introId = $intro['id'];
30     }
31 }
32
33 $intros = \Friendica\Database\DBA::selectToArray('intros', [], ['uid' => Session::getLocalUser()]);
34
35 doSomething($intros);
36 ```
37
38 After:
39
40 ```php
41 function doSomething(\Friendica\Contact\Introductions\Collection\Introductions $intros)
42 {
43     foreach ($intros as $intro) {
44         /** @var $intro \Friendica\Contact\Introductions\Entity\Introduction */
45         $introId = $intro->id;
46     }
47 }
48
49 /** @var $intros \Friendica\Contact\Introductions\Collection\Introductions */
50 $intros = \Friendica\DI::intro()->selectForUser(Session::getLocalUser());
51
52 doSomething($intros);
53 ```
54
55 ### Dependency Injection
56
57 Under this concept, we want class objects to carry with them the dependencies they will use.
58 Instead of calling global/static function/methods, objects use their own class members.
59
60 Before:
61 ```php
62 class Model
63 {
64     public $id;
65
66     function save()
67     {
68         return \Friendica\Database\DBA::update('table', get_object_vars($this), ['id' => $this->id]);
69     }
70 }
71 ```
72
73 After:
74 ```php
75 class Model
76 {
77     /**
78      * @var \Friendica\Database\Database
79      */
80     protected $dba;
81
82     public $id;
83
84     function __construct(\Friendica\Database\Database $dba)
85     {
86         $this->dba = $dba;
87     }
88     
89     function save()
90     {
91         return $this->dba->update('table', get_object_vars($this), ['id' => $this->id]);
92     }
93 }
94 ```
95
96 The main advantage is testability.
97 Another one is avoiding dependency circles and avoid implicit initializing.
98 In the first example the method `save()` has to be tested with the `DBA::update()` method, which may or may not have dependencies itself.
99
100 In the second example we can mock `\Friendica\Database\Database`, e.g. overload the class by replacing its methods by placeholders, which allows us to test only `Model::save()` and nothing else implicitly.
101
102 The main drawback is lengthy constructors for dependency-heavy classes.
103 To alleviate this issue we are using [DiCe](https://r.je/dice) to simplify the instantiation of the higher level objects Friendica uses.
104
105 We also added a convenience factory named `\Friendica\DI` that creates some of the most common objects used in modules.
106
107 ### Factories
108
109 Since we added a bunch of parameters to class constructors, instantiating objects has become cumbersome.
110 To keep it simple, we are using Factories.
111 Factories are classes used to generate other objects, centralizing the dependencies required in their constructor.
112 Factories encapsulate more or less complex creation of objects and create them redundancy free.
113
114 Before:
115 ```php
116 $model = new Model(\Friendica\DI::dba());
117 $model->id = 1;
118 $model->key = 'value';
119
120 $model->save();
121 ```
122
123 After:
124 ```php
125 class Factory
126 {
127     /**
128      * @var \Friendica\Database\Database
129      */
130     protected $dba;
131
132     function __construct(\Friendica\Database\Database $dba)
133     {
134         $this->dba;
135     }
136
137     public function create()
138     {
139         return new Model($this->dba);    
140     }
141 }
142
143 $model = \Friendica\DI::factory()->create();
144 $model->id = 1;
145 $model->key = 'value';
146
147 $model->save();
148 ```
149
150 Here, `DI::factory()` returns an instance of `Factory` that can then be used to create a `Model` object without having to care about its dependencies.
151
152 ### Repositories
153
154 Last building block of our code architecture, repositories are meant as the interface between models and how they are stored.
155 In Friendica they are stored in a relational database but repositories allow models not to have to care about it.
156 Repositories also act as factories for the Model they are managing.
157
158 Before:
159 ```php
160 class Model
161 {
162     /**
163      * @var \Friendica\Database\Database
164      */
165     protected $dba;
166
167     public $id;
168
169     function __construct(\Friendica\Database\Database $dba)
170     {
171         $this->dba = $dba;
172     }
173     
174     function save()
175     {
176         return $this->dba->update('table', get_object_vars($this), ['id' => $this->id]);
177     }
178 }
179
180 class Factory
181 {
182     /**
183      * @var \Friendica\Database\Database
184      */
185     protected $dba;
186
187     function __construct(\Friendica\Database\Database $dba)
188     {
189         $this->dba;
190     }
191
192     public function create()
193     {
194         return new Model($this->dba);    
195     }
196 }
197
198
199 $model = \Friendica\DI::factory()->create();
200 $model->id = 1;
201 $model->key = 'value';
202
203 $model->save();
204 ```
205
206 After:
207 ```php
208 class Model {
209     public $id;
210 }
211
212 class Repository extends Factory
213 {
214     /**
215      * @var \Friendica\Database\Database
216      */
217     protected $dba;
218
219     function __construct(\Friendica\Database\Database $dba)
220     {
221         $this->dba;
222     }
223
224     public function create()
225     {
226         return new Model($this->dba);    
227     }
228
229     public function save(Model $model)
230     {
231         return $this->dba->update('table', get_object_vars($model), ['id' => $model->id]);
232     }
233 }
234
235 $model = \Friendica\DI::repository()->create();
236 $model->id = 1;
237 $model->key = 'value';
238
239 \Friendica\DI::repository()->save($model);
240 ```