| Свойства | 77 |Описание | 78 | 79 | 80 |
|---|---|
legacy_addon_id |
82 | Используется для обработки изменений идентификатора плагина при обновлении с XenForo 1 до XenForo 2. | 83 |
title |
87 | Название плагина. Оно отображается в ACP. | 88 |
description |
92 | Описние вашего плагина. Оно отображается в ACP | 93 |
version_id |
97 | Идентификатор, используемый XenForo для отслеживания обновлений вашего плагина. Он должен увеличиватся при каждом релизе. | 98 |
version_string |
102 | Человеко-читаемая версия аддона. Будет отображаться в ACP вместо свойства version_id. |
103 |
dev |
107 | Имя разработчика плагина. Оно отображается в ACP. | 108 |
dev_url |
112 | Если задано, имя разработчика будет отображаться в ACP как гиперссылка. | 113 |
faq_url |
117 | Если задано, гиперссылка "FAQ" будет отображаться в панели ACP | 118 |
support_url |
122 | Если задано, гиперссылка "поддержка" будет отображаться в ACP. | 123 |
extra_urls |
127 | Позволяет отображать другие ссылки, связанные с плагином (ссылки на сообщения об ошибках, руководство - все, что вам хочется). Массив объектов JSON, где ключ - текст ссылки, а значение - ссылка. |
128 |
require |
132 | Набор требований, которые должны быть выполнены, перед установкой плагина. Смотрите 'Свойства требований' для дополнительной информации. | 133 |
icon |
137 | TЗначок плагина. Это имя иконки FontAwesome (например, fa-shopping-bag, или путь до файла картинки.) |
138 |
| Название продукта/требования | 168 |Относится к... | 169 |Значение | 170 | 171 | 172 | 173 |
|---|---|---|
XF |
175 | Установленная версия XenForo. | 176 |Идентификатор версии XenForo, например 200010.Вы можете узнать текущую версию XenForo, проверив верхнюю часть файла /src/XF.php для определения $versionIdили напечатав значение\XF::$versionId. |
177 |
php |
181 | Версия PHP. | 182 |Версия PHP, например, 5.4.0.Рекомендуется держать это как можно ниже; Обновление версии PHP может быть довольно сложной задачей, особенно если другие плагины конфликтуют с более новыми версиями PHP. |
183 |
php-ext/(extension name) |
187 | Расширение PHP - где (extension name) это имя расширения. |
188 | Версия расширения PHP. Это проверяется с помощью функции PHP version_compareтак что это работает даже для строк версии в официальном полном формате PHP, как 7.1.19-1+ubuntu16.04.1+deb.sury.org+1. |
189 |
(any addon ID) |
193 | Плагин XenForo, такой как Demo/Addon.Если вы не уверены относительно идентификатора плагина проверьте его файл addon.json. |
194 | Идентификатор версии плагина. Вы можете обратиться к рекомендованному формату версирования для получения дополнительной информации. |
195 |
`, чтобы обеспечить сохранение пробелов при рендеринге.
159 |
160 | Альтернативой на самом деле является компонент VarDumper из проекта Symfony. Он выводит HTML, CSS и JS для создания гораздо более функционального и потенциально более легкого для чтения вывода. Он позволяет свернуть определенные разделы, а для определенных значений, которые могут выводить значительный объем данных, таких как объекты, он может автоматически свернуть эти разделы.
161 |
--------------------------------------------------------------------------------
/documentation/EntitiesFindersAndRepositories.md:
--------------------------------------------------------------------------------
1 | # Сущности, Поисковики и Репозитории
2 | There are a number of ways to interact with data within XF2. In XF1 this was mostly geared towards writing out raw SQL statements inside Model files. The approach in XF2 has moved away from this, and we have added a number of new ways in its place. We'll first look at the preferred method for performing database queries - the finder.
3 |
4 | ## Поисковики
5 |
6 | We have introduced a new "Finder" system which allows queries to be built up programmatically in a object oriented way so that raw database queries do not need to be written. The Finder system works hand in hand with the Entity system, which we talk about in more detail below. The first argument passed into the finder method is the short class name for the Entity you want to work with. Let's just convert some of the queries mentioned in the section above to use the Finder system instead. For example, to access a single user record:
7 |
8 | ```php
9 | $finder = \XF::finder('XF:User');
10 | $user = $finder->where('user_id', 1)->fetchOne();
11 | ```
12 |
13 | One of the main differences between the direct query approach and using the Finder is that the base unit of data returned by the Finder is not an array. In the case of a Finder object which calls the `fetchOne` method (which only returns a single row from the database), a single Entity object will be returned.
14 |
15 | Let's look at a slightly different approach which will return multiple rows:
16 |
17 | ```php
18 | $finder = \XF::finder('XF:User');
19 | $users = $finder->limit(10)->fetch();
20 | ```
21 |
22 | This example will query 10 records from the xf_user table, and it will return them as an `ArrayCollection` object. This is a special object which acts similarly to an array, in that it is traversable (you can loop through it) and it has some special methods that can tell you the total number of entries it has, grouping by certain values, or other array like operations such as filtering, merging, getting the first or last entry etc.
23 |
24 | Finder queries generally should be expected to retrieve all columns from a table, so there's no specific equivalent to fetch only certain values certain columns.
25 |
26 | Instead, to get a single value, you would just fetch one entity and read the value directly from that:
27 |
28 | ```php
29 | $finder = \XF::finder('XF:User');
30 | $username = $finder->where('user_id', 1)->fetchOne()->username;
31 | ```
32 |
33 | Similarly, to get an array of values from a single column, you can use the `pluckFrom` method:
34 |
35 | ```php
36 | $finder = \XF::finder('XF:User');
37 | $usernames = $finder->limit(10)->pluckFrom('username')->fetch();
38 | ```
39 |
40 | So far we've seen the Finder apply somewhat simple where and limit constraints. So let's look at the Finder in more detail, including a bit more detail about the `where` method itself.
41 |
42 |
43 | ### Метод where
44 |
45 | The `where` method can support up to three arguments. The first being the condition itself, e.g. the column you are querying. The second would ordinarily be the operator. The third is the value being searched for. If you supply only two arguments, as you have seen above, then it automatically implies the operator is `=`. Below is a list of the other operators which are valid:
46 |
47 | * `=`
48 | * `<>`
49 | * `!=`
50 | * `>`
51 | * `>=`
52 | * `<`
53 | * `<=`
54 | * `LIKE`
55 | * `BETWEEN`
56 |
57 | So, we could get a list of the valid users who registered in the last 7 days:
58 |
59 | ```php
60 | $finder = \XF::finder('XF:User');
61 | $users = $finder->where('user_state', 'valid')->where('register_date', '>=', time() - 86400 * 7)->fetch();
62 | ```
63 |
64 | As you can see you can call the `where` method as many times as you like, but in addition to that, you can choose to pass in an array as the only argument of the method, and build up your conditions in a single call. The array method supports two types, both of which we can use on the query we built above:
65 |
66 | ```php
67 | $finder = \XF::finder('XF:User');
68 | $users = $finder->where([
69 | 'user_state' => 'valid',
70 | ['register_date', '>=', time() - 86400 * 7]
71 | ])
72 | ->fetch();
73 | ```
74 |
75 | It wouldn't usually be recommended or clear to mix the usage like this, but it does demonstrate the flexibility of the method somewhat. Now that the conditions are in an array, we can either specify the column name (as the array key) and value for an implied `=` operator or we can actually define another array containing the column, operator and value.
76 |
77 |
78 | ### Метод whereOr
79 |
80 | With the above examples, both conditions need to be met, i.e. each condition is joined by the `AND` operator. However, sometimes it is necessary to only meet part of your condition, and this is possible by using the `whereOr` method. For example, if you wanted to search for users who are either not valid or have posted zero messages, you can build that as follows:
81 |
82 | ```php
83 | $finder = \XF::finder('XF:User');
84 | $users = $finder->whereOr(
85 | ['user_state', '<>', 'valid'],
86 | ['message_count', 0]
87 | )->fetch();
88 | ```
89 |
90 | Similar to the example in the previous section, as well as passing up to two conditions as separate arguments, you can also just pass an array of conditions to the first argument:
91 |
92 | ```php
93 | $finder = \XF::finder('XF:User');
94 | $users = $finder->whereOr([
95 | ['user_state', '<>', 'valid'],
96 | ['message_count', 0],
97 | ['is_banned', 1]
98 | ])->fetch();
99 | ```
100 |
101 | ### Метод with
102 |
103 | The `with` method is essentially equivalent to using the `INNER|LEFT JOIN` syntax, though it relies upon the Entity having had its "Relations" defined. We won't go into that until the next page, but this should just give you an understanding of how it works. Let's now use the Thread finder to retrieve a specific thread:
104 |
105 | ```php
106 | $finder = \XF::finder('XF:Thread');
107 | $thread = $finder->with('Forum', true)->where('thread_id', 123)->fetchOne();
108 | ```
109 |
110 | This query will fetch the Thread entity where the `thread_id = 123` but it will also do a join with the xf_forum table, behind the scenes. In terms of controlling how to do an `INNER JOIN` rather than a `LEFT JOIN`, that is what the second argument is for. In this case we've set the "must exist" argument to true, so it will flip the join syntax to using `INNER` rather than the default `LEFT`.
111 |
112 | We'll go into more detail about how to access the data fetched from this join in the next section.
113 |
114 | It's also possible to pass an array of relations into the `with` method to do multiple joins.
115 |
116 | ```php
117 | $finder = \XF::finder('XF:Thread');
118 | $thread = $finder->with(['Forum', 'User'], true)->where('thread_id', 123)->fetchOne();
119 | ```
120 |
121 | This would join to the xf_user table to get the thread author too. However, with the second argument there still being `true`, we might not need to do an `INNER` join for the user join, so, we could just chain the methods instead:
122 |
123 | ```php
124 | $finder = \XF::finder('XF:Thread');
125 | $thread = $finder->with('Forum', true)->with('User')->where('thread_id', 123)->fetchOne();
126 | ```
127 | ### Методы order, limit и limitByPage
128 |
129 | ### Метод order
130 |
131 | This method allows you to modify your query so the results are fetched in a specific order. It takes two arguments, the first is the column name, and the second is, optionally, the direction of the sort. So, if you wanted to list the 10 users who have the most messages, you could build the query like this:
132 |
133 | ```php
134 | $finder = \XF::finder('XF:User');
135 | $users = $finder->order('message_count', 'DESC')->limit(10);
136 | ```
137 |
138 | !!! Примечание
139 | Now is probably a good time to mention that finder methods can mostly be called in any order. For example: `$threads = $finder->limit(10)->where('thread_id', '>', 123)->order('post_date')->with('User')->fetch();`
140 | Although if you wrote a MySQL query in that order you'd certainly encounter some syntax issues, the Finder system will still build it all in the correct order and the above code, although odd looking and probably not recommended, is perfectly valid.
141 |
142 | As with a standard MySQL query, it is possible to order a result set on multiple columns. To do that, you can just call the order method again. It's also possible to pass multiple order clauses into the order method using an array.
143 |
144 | ```php
145 | $finder = \XF::finder('XF:User');
146 | $users = $finder->order('message_count', 'DESC')->order('register_date')->limit(10);
147 | ```
148 | ### Метод limit
149 |
150 | We've already seen how to limit a query to a specific number of records being returned:
151 |
152 | ```php
153 | $finder = \XF::finder('XF:User');
154 | $users = $finder->limit(10)->fetch();
155 | ```
156 |
157 | However, there's actually an alternative to calling the limit method directly:
158 |
159 | ```php
160 | $finder = \XF::finder('XF:User');
161 | $users = $finder->fetch(10);
162 | ```
163 |
164 | It's possible to pass your limit directly into the `fetch()` method. It's also worth noting that the `limit` (and `fetch`) method supports two arguments. The first obviously being the limit, the second being the offset.
165 |
166 | ```php
167 | $finder = \XF::finder('XF:User');
168 | $users = $finder->limit(10, 100)->fetch();
169 | ```
170 |
171 | The offset value here essentially means the first 100 results will be discarded, and the first 10 after that will be returned. This kind of approach is useful for providing paginated results, though we actually also have an easier way to do that...
172 |
173 | ### Метод limitByPage
174 |
175 | This method is a sort of helper method which ultimately sets the appropriate limit and offset based on the "page" you're currently viewing and how many "per page" you require.
176 |
177 | ```php
178 | $finder = \XF::finder('XF:User');
179 | $users = $finder->limitByPage(3, 20);
180 | ```
181 |
182 | In this case, the limit is going to be set to 20 (which is our per page value) and the offset is going to be set to 40 because we're starting on page 3.
183 |
184 | Occasionally, it is necessary for us to grab additional more data than the limit. Over-fetching can be useful to help detect whether you have additional data to display after the current page, or if you have a need to filter the initial result set down based on permissions. We can do that with the third argument:
185 |
186 | ```php
187 | $finder = \XF::finder('XF:User');
188 | $users = $finder->limitByPage(3, 20, 1);
189 | ```
190 |
191 | This will get a total of up to **21** users (20 + 1) starting at page 3.
192 |
193 |
194 | ### Метод getQuery
195 |
196 | When you first start working with the finder, as intuitive as it is, you may occasionally wonder whether you're using it correctly, and whether it is going to build the query you expect it to. We have a method named `getQuery` which can tell us the current query that will be built with the current finder object. For example:
197 |
198 | ```php
199 | $finder = \XF::finder('XF:User')
200 | ->where('user_id', 1);
201 |
202 | \XF::dumpSimple($finder->getQuery());
203 | ```
204 |
205 | This will output something similar to:
206 |
207 | ```plain
208 | string(67) "SELECT `xf_user`.*
209 | FROM `xf_user`
210 | WHERE (`xf_user`.`user_id` = 1)"
211 | ```
212 |
213 | You probably won't need it very often, but it can be useful if the finder isn't quite returning the results you expected. Read more about the `dumpSimple` method in the [Dump a variable](/documentation/DevelopmentTools.md#part20) section.
214 |
215 | ### Расширение методов поисковика
216 |
217 | So far we have seen the finder object get setup with an argument similar to `XF:User` and `XF:Thread`. For the most part, this identifies the Entity class the finder is working with and will resolve to, for example, `XF\Entity\User`. However, it can additionally represent a finder class. Finder classes are optional, but they serve as a way to add custom finder methods to specific finder types. To see this in action, let's look at the finder class that relates to `XF:User` which can be found in the `XF\Finder\User` class.
218 |
219 | Here's an example finder method from that class:
220 |
221 | ```php
222 | public function isRecentlyActive($days = 180)
223 | {
224 | $this->where('last_activity', '>', time() - ($days * 86400));
225 | return $this;
226 | }
227 | ```
228 |
229 | What this allows us to do is to now call that method on any User finder object. So if we take an example earlier:
230 |
231 | ```php
232 | $finder = \XF::finder('XF:User');
233 | $users = $finder->isRecentlyActive(20)->order('message_count', 'DESC')->limit(10);
234 | ```
235 |
236 | This query, which earlier just returned 10 users in descending message count order, will now return the 10 users in that order who have been recently active in the last 20 days.
237 |
238 | Even though for a lot of entity types a finder class doesn't exist, it is still possible to extend these non existent classes in the same way as mentioned in the [Extending classes](/documentation/GeneralConcepts.md#part6) section.
239 |
240 | ## Система сущностей
241 |
242 | If you're familiar with XF1, you may be familiar with some of the concepts behind Entities because they have ultimately derived from the DataWriter system there. In case you're not so familiar with them, the following section should give you some idea.
243 |
244 | ### Структура сущностей
245 |
246 | The `Structure` object consists of a number of properties which define the structure of the Entity and the database table it relates to. The structure object itself is setup inside the entity it relates to. Let's look at some of the common properties from the User entity:
247 |
248 | #### Таблица
249 | ```php
250 | $structure->table = 'xf_user';
251 | ```
252 | This tells the Entity which database table to use when updating and inserting records, and also tells the Finder which table to read from when building queries to execute. Additionally, it plays a part in knowing which other tables your query needs to join to.
253 |
254 |
255 | #### Короткое имя
256 | ```php
257 | $structure->shortName = 'XF:User';
258 | ```
259 | This is the just the short class name of both the Entity itself and the Finder class (if applicable).
260 |
261 | #### Тип контента
262 | ```php
263 | $structure->contentType = 'user';
264 | ```
265 | This defines what content type this Entity represents. This will not be needed in most entity structures. It is used to connect to specific things used by the "content type" system (which will be covered in another section).
266 |
267 | #### Основной ключ
268 | ```php
269 | $structure->primaryKey = 'user_id';
270 | ```
271 | Defines the column which represents the primary key in the database table. If a table supports more than a single column as a primary key, then this can be defined as an array.
272 |
273 | #### Колонки
274 | ```php
275 | $structure->columns = [
276 | 'user_id' => ['type' => self::UINT, 'autoIncrement' => true, 'nullable' => true, 'changeLog' => false],
277 | 'username' => ['type' => self::STR, 'maxLength' => 50,
278 | 'required' => 'please_enter_valid_name'
279 | ]
280 | // and many more columns ...
281 | ];
282 | ```
283 | This is a key part of the configuration of the entity as this goes into a lot of detail to explain the specifics of each database column that the Entity is responsible for. This tells us the type of data that is expected, whether a value is required, what format it should match, whether it should be a unique value, what its default value is, and much more.
284 |
285 | Based on the `type`, the entity manager knows whether to encode or decode a value in a certain way. This may be a somewhat simple process of casting a value to a string or an integer, or slightly more complicated such as using `json_encode()` on an array when writing to the database or using `json_decode()` on a JSON string when reading from the database so that the value is correctly returned to the entity object as an array without us needing to manually do that. It can also support comma separated values being encoded/decoded appropriately.
286 |
287 | Occasionally it is necessary to do some additional verification or modification of a value before it is written. As an example, in the User entity, look at the `verifyStyleId()` method. When a value is set on the `style_id` field, we automatically check to see if a method named `verifyStyleId()` exists, and if it does, we run the value through that first.
288 |
289 | #### Поведения
290 | ```php
291 | $structure->behaviors = [
292 | 'XF:ChangeLoggable' => []
293 | ];
294 | ```
295 | This is an array of behavior classes which should be used by this entity. Behavior classes are a way of allowing certain code to be reused generically across multiple entity types (only when the entity changes, not on reads). A good example of this is the `XF:Likeable` behavior which is able to automatically execute certain actions on entities which support content which can be "liked". This includes automatically recalculating counts when visibility changes occur within the content and automatically deleting likes when the content is deleted.
296 |
297 | #### Геттеры
298 | ```php
299 | $structure->getters = [
300 | 'is_super_admin' => true,
301 | 'last_activity' => true
302 | ];
303 | ```
304 | Getter methods are automatically called when the named fields are called. For example, if we request `is_super_admin` from a User entity, this will automatically check for, and use the `getIsSuperAdmin()` method. The interesting thing to note about this is that the xf_user table doesn't actually have a field named `is_super_admin`. This actually exists on the Admin entity, but we have added it as a getter method as a shorthand way of accessing that value. Getter methods can also be used to override the values of existing fields directly, which is the case for the `last_activity` value here. `last_activity` is actually a cached value which is updated usually when a user logs out. However, we store the user's latest activity date in the xf_session_activity table, so we can use this `getLastActivity` method to return that value instead of the cached last activity value. Should you ever have a need to bypass the getter method entirely, and just get the true entity value, just suffix the column name with an underscore, e.g. `$user->last_activity_`.
305 |
306 | Because an entity is just like any other PHP object, you can add more methods to them. A common use case for this is for adding things like permission check methods that can be called on the entity itself.
307 |
308 | #### Связи
309 | ```php
310 | $structure->relations = [
311 | 'Admin' => [
312 | 'entity' => 'XF:Admin',
313 | 'type' => self::TO_ONE,
314 | 'conditions' => 'user_id',
315 | 'primary' => true
316 | ]
317 | ];
318 | ```
319 | This is how Relations are defined. What are relations? They define the relationship between entities which can be used to perform join queries to other tables or fetch records associated to an entity on the fly. If we remember the `with` method on the finder, if we wanted to fetch a specific user and preemptively fetch the user's Admin record (if it exists) then we would do something like the following:
320 |
321 | ```php
322 | $finder = \XF::finder('XF:User');
323 | $user = $finder->where('user_id', 1)->with('Admin')->fetchOne();
324 | ```
325 |
326 | This will use the information defined in the user entity for the `Admin` relation and the details of the `XF:Admin` entity structure to know that this user query should perform a `LEFT JOIN` on the xf_admin table and the `user_id` column. To access the admin last login date from the user entity:
327 |
328 | ```php
329 | $lastLogin = $user->Admin->last_login; // returns timestamp of the last admin login
330 | ```
331 |
332 | However, it's not always necessary to do a join in a finder to get related information for an entity. For example, if we take the above example without the `with` method call:
333 |
334 | ```php
335 | $finder = \XF::finder('XF:User');
336 | $user = $finder->where('user_id', 1)->fetchOne();
337 | $lastLogin = $user->Admin->last_login; // returns timestamp of the last admin login
338 | ```
339 |
340 | We still get the `last_login` value here. It does this by performing the additional query to get the Admin entity on the fly.
341 |
342 | The example above uses the `TO_ONE` type, and this relation, therefore, relates one entity to one other entity. We also have a `TO_MANY` type.
343 |
344 | It is not possible to fetch an entire `TO_MANY` relation (e.g. with a join / `with` method on the finder), but at the cost of a query it is possible to read that at any time on the fly, such as in the final `last_login` example above.
345 |
346 | One such relation that is defined on the User entity is the `ConnectedAccounts` relation:
347 |
348 | ```php
349 | $structure->relations = [
350 | 'ConnectedAccounts' => [
351 | 'entity' => 'XF:UserConnectedAccount',
352 | 'type' => self::TO_MANY,
353 | 'conditions' => 'user_id',
354 | 'key' => 'provider'
355 | ]
356 | ];
357 | ```
358 |
359 | This relation is able to return the records from the xf_user_connected_account table that match the current user ID as a `FinderCollection`. This is similar to the `ArrayCollection` object we mentioned in [The Finder](#the-finder) section above. The relation definition specifies that the collection should be keyed by the `provider` field.
360 |
361 | Although it isn't possible to fetch multiple records while performing a finder query, it is possible to use a `TO_MANY` relation to fetch a **single** record from that relation. As an example, if we wanted to see if the user was associated to a specific connected account provider, we can at least fetch that while querying:
362 |
363 | ```php
364 | $finder = \XF::finder('XF:User');
365 | $user = $finder->where('user_id', 1)->with('ConnectedAccounts|facebook')->fetchOne();
366 | ```
367 |
368 | #### Опции
369 | ```php
370 | $structure->options = [
371 | 'custom_title_disallowed' => preg_split('/\r?\n/', $options->disallowedCustomTitles),
372 | 'admin_edit' => false,
373 | 'skip_email_confirm' => false
374 | ];
375 | ```
376 | Entity options are a way of modifying the behavior of the entity under certain conditions. For example, if we set `admin_edit` to true (which is the case when editing a user in the Admin CP), then certain checks will be skipped such as to allow a user's email address to be empty.
377 |
378 | ### Жизненный цикл сущностей
379 |
380 | The Entity plays a significant job in terms of managing the life cycle of a record within the database. As well as reading values from it, and writing values to it, the Entity can be used to delete records and trigger certain events when all of these actions occur so that certain tasks can be performed, or certain associated records can be updated as well. Let's look at some of these events that happen when an entity is saving:
381 |
382 | * `_preSave()` - This happens before the save process begins, and is primarily used to perform any additional pre-save validations or to set additional data before the save happens.
383 | * `_postSave()` - After the data has been saved, but before any transactions are committed, this method is called and you can use it to perform any additional work that should trigger after an entity has been saved.
384 |
385 | There are additionally `_preDelete()` and `_postDelete()` which work in a similar way, but when a delete is happening.
386 |
387 | The Entity is also able to give information on its current state. For example, there is an `isInsert()` and `isUpdate()` method so you can detect whether this is a new record being inserted or an existing record being updated. There is an `isChanged()` method which can tell you whether a specific field has changed since the last save.
388 |
389 | Let's look at some real examples of these methods in action, in the User entity.
390 |
391 | ```php
392 | protected function _preSave()
393 | {
394 | if ($this->isChanged('user_group_id') || $this->isChanged('secondary_group_ids'))
395 | {
396 | $groupRepo = $this->getUserGroupRepo();
397 | $this->display_style_group_id = $groupRepo->getDisplayGroupIdForUser($this);
398 | }
399 |
400 | // ...
401 | }
402 |
403 | protected function _postSave()
404 | {
405 | // ...
406 |
407 | if ($this->isUpdate() && $this->isChanged('username') && $this->getExistingValue('username') != null)
408 | {
409 | $this->app()->jobManager()->enqueue('XF:UserRenameCleanUp', [
410 | 'originalUserId' => $this->user_id,
411 | 'originalUserName' => $this->getExistingValue('username'),
412 | 'newUserName' => $this->username
413 | ]);
414 | }
415 |
416 | // ...
417 | ```
418 |
419 | In the `_preSave()` example we fetch and cache the new display group ID for a user based on their changed user groups. In the `_postSave()` example, we trigger a job to run after a user's name has been changed.
420 |
421 | ## Репозитории
422 |
423 | Repositories are a new concept for XF2, but you might not be blamed for comparing them to the "Model" objects from XF1. We don't have a model object in XF2 because we have much better places and ways to fetch and write data to the database. So, rather than having a massive class which contains all of the queries your add-on needs, and all of the various different ways to manipulate those queries, we have the finder which adds a lot more flexibility.
424 |
425 | It's also worth bearing in mind that in XF1 the Model objects were a bit of a "dumping ground" for so many things. Many of which are now redundant. For example, in XF1 all of the permission rebuilding code was in the permission model. In XF2, we have specific services and objects which handle this.
426 |
427 | So, what are Repositories? They correspond with an entity and a finder and hold methods which generally return a finder object setup for a specific purpose. Why not just return the result of the finder query? Well, if we return the finder object itself then it serves as a useful extension point for add-ons to extend that and modify the finder object before the entity or collection is returned.
428 |
429 | Repositories may also contain some specific methods for things like cache rebuilding.
--------------------------------------------------------------------------------
/documentation/GeneralConcepts.md:
--------------------------------------------------------------------------------
1 |
2 | # Общие понятия
3 | В следующих разделах подробно рассказывается о некоторых общих системах и концепциях, с которыми вы столкнетесь при разработке дополнения XenForo. Если вы знакомы с разработкой XenForo 1.x, то многие из этих концепций будут вам знакомы, хотя стоит их рассмотреть, так как есть несколько отличных новых инструментов и функций, которые помогут вам разрабатывать надстройки.
4 |
5 | ## Компоненты поставщика
6 | XF2 не разработан на каком-то конкретном фреймворке, как XF1, однако, мы использовали популярные, хорошо протестированных пакеты с открытым исходным кодом, для решения конкретных задач. Например, мы используем проект SwiftMailer для отправки электронной почты и проект с именем Guzzle в качестве HTTP-клиента. Все сторонние проекты загружаются из каталога `src/vendor`.
7 |
8 | В настоящее время разработчики дополнений не могут добавлять свои собственные зависимости к этому местоположению.
9 |
10 | ## Интегрированная среда разработки (IDE)
11 | Прежде чем приступать к работе над разработкой XF2, вы можете потратить некоторое время на оценку приложения, с которым вы действительно будете создавать и редактировать файлы PHP. Это обычно называют IDE. Существует ряд вариантов, начиная от базового Блокнота и заканчивая чем-то вроде Sublime Text, который может быть расширен, чтобы иметь лучшую поддержку PHP с дополнениями, вплоть до среды разработки, такой как PhpStorm. Внутри мы в основном используем PhpStorm. Это премиальный и коммерческий продукт, но могут быть доступны свободные альтернативы. В любом случае, никто не может вам указывать, какую IDE вам использовать и вам придется потратить некоторое время, чтобы подобрать наиболее удобную среду.
12 |
13 | ## Автозагрузчик
14 | XF2 использует автозагрузчик, который автоматически генерирует Composer. Это позволяет автоматически загружать весь код XF, сторонний код и любой код разработчика дополнений для всего проекта без необходимости `include/require` ваши классы вручную.
15 |
16 | Корень автозагрузки для всех дополнений XF является каталогом `src/addons`. Это означает, что все ваши имена классов будут относиться к этому базовому местоположению. Также стоит отметить, что XF2 использует строгий шаблон «один класс - один файл». Каждый файл должен содержать только один класс, а имя этого класса должно определять точное местоположение файла PHP класса в файловой системе.
17 |
18 | Например, если вы хотите создать новый класс в файле с именем `src/addons/Demo/Setup.php` (где `Demo` - ваш дополнительный код), этот класс будет называться `Demo\Setup`. И наоборот, если бы у вас был класс с именем `Demo\Entity\Thing`, вы узнаете, что файл для этого класса находится в пути `src/addons/Demo/Entity/Thing.php`.
19 |
20 | ## Пространства имён
21 | Всюду по XF мы используем [пространства имён](http://php.net/manual/en/language.namespaces.rationale.php) так что мы можем более кратко ссылаться на классы в одном и том же пространстве имен. Рекомендуется, чтобы все плагины также использовали пространства имен. В приведенном выше примере мы говорили о классе с именем `Demo\Setup`. Используя пространства имен, класс фактически будет называться просто «Setup», но пространство имен будет установлено в `Demo`. В качестве более конкретного примера мы также говорили выше о классе с именем `Demo\Entity\Thing`. Давайте посмотрим, как будет выглядеть код PHP для этого класса:
22 | ```
23 | Короткие имена классов
35 | В некоторых местах, в XF мы сокращаем имена классов. Например, если вы хотите вызвать сущность `User` (подробнее о сущностях мы расскажем ниже), вы можете сослаться на неё по короткому имени - `XF:User`. Использование коротких имен классов и полного имени класса полностью зависит от контекста. Поэтому в контексте вызова сущности короткое имя класса будет указывать на полное имя - `XF\Entity\User`. Часть `XF` указывает путь к файлу (на основе ID дополнения), часть `Entity` подразумевает вызов сущности, а часть `User` указывает на конкретную сущность. Аналогично, когда вы начинаете создавать свои собственные классы, вы также будете использовать короткие имена классов для ссылки на свои собственные классы. Например, если вам нужно создать новую сущность `Thing` для вашего дополнения `Demo`, вы должны написать следующее:
36 | ```php
37 | \XF::em()->create('Demo:Thing');
38 | ```
39 | Это вызвало бы класс `Demo\Entity\Thing`. Аналогичным образом, если вы хотите получить доступ к репозиторию `Thing`, вы должны написать его следующим образом:
40 | ```php
41 | \XF::repository('Demo:Thing');
42 | ```
43 | Обратите внимание, что короткие имена классов идентичны. Вызов репозитория фактически вызовет `Demo\Repository\Thing`.
44 |
45 | ## Расширение классов
46 | Большое количество классов в XF2 является расширяемым, что позволяет разработчикам расширять и переопределять основной код без необходимости его прямого редактирования. Если вы знакомы с разработкой XF1, вы будете знакомы со следующим процессом:
47 |
48 | 1. Создание PHP-файла Listener
49 | 2. Создайть класс, который в конечном итоге расширит исходный класс
50 | 3. Написать функцию, которая соответствует ожидаемой сигнатуре вызова для одного из событий `load_class` и добавляет имя вашего расширенного класса
51 | 4. Добавить в ACP «обработчик событий», который определяет класс и имя обработчика для функции, упомянутой выше, и необязательно указать подсказку, какой класс будет расширен
52 |
53 | В XF2 мы удалили эти события в пользу определенной системы под названием «Расширения класса». Процесс выглядит следующим образом:
54 |
55 | 1. Создайте класс, который в конечном итоге расширит исходный класс
56 | 2. Добавьте «расширение класса» в ACP, которое указывает имя расширяемого класса и имя класса, который его расширяет
57 | 3. Это явно сокращает часть шаблона, требуемого для расширения классов, а также предоставляет специальный пользовательский интерфейс для просмотра и управления этими расширениями. Давайте посмотрим на процесс, расширив публичный контроллер `Member` и добавив новое действие, которое отображает простое сообщение.
58 |
59 | Первое, что нужно сделать, это создать дополнение. Мы ранее [описывали](/documentation/DevelopmentTools.md#part5), как это сделать, используя команду `xf-addon:create`. В этом примере мы предположим, что вы создали дополнение с идентификатором и названием «Demo».
60 |
61 | Теперь у вас будет файл addon.json для этого дополнения в следующем расположении `src/addons/Demo/addon.json`.
62 |
63 | > **Примечание**
64 | > Хотя, строго говоря, вы можете размещать свои расширенные классы везде, где захотите, в своем дополнительном каталоге, рекомендуется поместить расширенные классы в каталог, который легко идентифицирует: a) дополнение, коорому принадлежит класс b) тип расширяемого класса и c) название расширяемого класса. В следующих примерах мы расширяем публичный контроллер XF - Member, поэтому мы разместим наш расширенный класс по следующему пути: `src/addons/Demo/XF/Pub/Controller/Member.php`.
65 |
66 | Расширенный класс должен существовать до того, как мы добавим расширение класса в ACP. Итак, следуйте следующим инструкциям:
67 |
68 | 1. Создайте новый каталог с именем `XF` внутри `src/addons/Demo`
69 | 2. Создайте новый каталог с именем `Pub` внутри `src/addons/Demo/XF`
70 | 3. Создайте новый каталог с именем `Controller` внутри `src/addons/Demo/XF/Pub`
71 | 4. Создайте новый файл с именем `Member.php` внутри `src/addons/Demo/XF/Pub/Controller`.
72 |
73 | Для начала, содержимое вашего файла должно быть таким:
74 | ```php
75 | Development > Class > Add` class extension.
87 |
88 | Все, что вам нужно сделать, это ввести имя базового класса (`XF\Pub\Controller\Member`) в первом поле и имя расширенного класса (которое вы только что создали) во втором поле (`Demo\XF\Pub\Controller\Member`) и нажмите кнопку «Сохранить».
89 |
90 | Расширение вашего класса теперь должно быть активным, но в настоящее время оно ничего не делает. Чтобы что-то произошло, нам необходимо либо переопределить существующий метод в этом классе, создав метод с тем же именем, что и существующий, либо полностью добавив новый метод. Давайте сделаем последнее:
91 | ```php
92 | message('Hello world!');
101 | }
102 | }
103 | ```
104 | Мы больше говорим о контроллерах, действиях и ответах на странице [Основы контроллеров](/documentation/ControllerBasics.md#part0), поэтому не беспокойтесь об этом прямо сейчас.
105 |
106 | Теперь мы добавили некоторый код в наш расширенный контроллер, давайте посмотрим его в действии. Просто введите следующий URL-адрес (относительно URL-адреса вашей доски): `index.php?members/hello-world`. Теперь вы должны увидеть сообщение «Hello world!»!
107 |
108 | Как упоминалось ранее, также возможно переопределить существующие методы внутри класса. Например, если мы изменим `actionHelloWorld()` на `actionIndex()`, вместо списка «Полезные пользователи», отобразится «Hello world!». Это не совсем правильный способ расширения существующего действия контроллера (или любого метода класса), но мы подробно рассмотрим это в [Изменение ответа действие контроллера (правильно)](/documentation/ControllerBasics.md#part7).
109 |
110 | ## Типовые подсказки
111 | Многие объекты в XF создаются с помощью методов XF. Например, если мы хотим создать экземпляр конкретного репозитория, мы напишем следующее:
112 | ```php
113 | $repo = \XF::repository('Demo:Thing');
114 | ```
115 | Это очень удобный способ создания объекта. Мы знаем, только посмотрев на него, какой объект будет создан. Полученный код в этом методе знает, как вернуть правильный объект для того, что мы запросили.
116 |
117 | Однако, к сожалению, ваша IDE, вероятно, не имеет понятия (по крайней мере, по умолчанию). Что касается IDE, этот метод вернет экземпляр объекта `XF\Mvc\Entity\Repository`. Это полезно в определенной степени, но существует множество методов, доступных в конкретном объекте `Demo\Repository\Thing`, о которых ваша IDE не знает. Это в конечном итоге означает, что, когда вы попытаетесь использовать свой объект `$repo` в коде, ваша среда IDE не сможет делать предложения или автоматически заполнять имена методов и требуемые аргументы.
118 |
119 | В таких случаях будет полезен тайп-хинтинг, такой синтаксис должен поддерживаться большинством IDE, и текстоыми редакторами, которые "знакомы" с PHP. Мы просто изменим вызов репозитория следующим образом:
120 | ```php
121 | /** @var \Demo\Repository\Thing $repo */
122 | $repo = \XF::repository('Demo:Thing');
123 | ```
124 | Такая подсказка сообщает IDE, что `$repo` относится к объекту, представленному классом `Demo\Repository\Thing`, а не к объекту, который он автоматически выводил изначально.
125 |
126 | Тайп-хинтинг так же очень полезен при расширении классов. Потенциальная проблема с нашими методами расширения класса заключается в том, что по существу ваши классы не расширяют исходный класс, который вы хотите расширить, но вместо этого проксируется через класс, который фактически не существует, например. `XFCP_Member`, как в [пример выше] (/documentation/GeneralConcepts.md#part6).
127 |
128 | Чтобы исправить эту проблему, мы автоматически создаем файл с именем `extension_hint.php` и сохраняем его в вашем каталоге` _output`.
129 |
130 | Таким образом, создается ссылка, которую видит ваша IDE. Когда вы будете использовать `$this` в любом из методов в расширенном классе, ваша IDE предложит автодополнение методов и свойств доступных в контроллере Member, или его родителях.
--------------------------------------------------------------------------------
/documentation/GettingStarted.md:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | # Начало работы
5 |
6 | Эта документация предназначена для ознакомления вас с разработкой под XenForo 2.0. Предполагается, что перед началом работы с этой документацией вы уже знакомы с базовыми вещами, вроде PHP и MySQL. Опыт работы с предыдущими версиями XenForo не требуется, но предоставит ряд преимуществ.
7 |
8 | На последующих страницах документации мы расскажем об установке локального сервера, подготовке к установке и самом процессе чистой установки XenForo 2.0 и объясним некоторые базовые концепции разработки под XF2.
9 |
10 | ## Что нового для разработчиков?
11 |
12 | Хотя XenForo 2.0 добавляет много улучшений для ваших форумов и его участников, значительные усилия были направлены на улучшение базовой структуры XenForo. Вы можете прочитать дополнительную информацию об этих изменениях в следующих темах:
13 |
14 | [Что нового для разработчиков в XenForo 2 (часть 1)](https://xf2demo.xenforo.com/threads/whats-new-for-developers-in-xenforo-2-part-1.1297/)1
15 |
16 | [Что нового для разработчиков в XenForo 2 (часть 2)](https://xf2demo.xenforo.com/threads/whats-new-for-developers-in-xenforo-2-part-2.1409/)1
17 | ## Начало работы
18 | Начать разработку на XF легко. Вам просто нужно загрузить файлы, выгрузить их на веб-сервер и запустить установку.
19 |
20 | Если у вас еще нет веб-сервера, не беспокойтесь, вы легко сможете настроить его в локальном окружении.
21 |
22 | ## Загрузка XF 2.0
23 | Для загрузки XF 2.0, просто зайдите в [Customer Area] (https://xenforo.com/customers) и войдите в учетную запись как обычно. Найдите правильную лицензию и нажмите ссылку «Загрузить XenForo». Выберите версию, которую вы хотите загрузить, тип пакета и принять лицензионное соглашение. Наконец, нажмите кнопку «Загрузить», чтобы загрузить файлы.
24 |
25 | ## Системные требования XF 2.0
26 | Требования к запуску XF 2.0 изменились с XF 1.5. Рекомендуемые требования:
27 |
28 | * PHP: 5.4.0+
29 | * MySQL: 5.5+
30 | * PHP расширения: MySQLi, GD (with JPEG support), PCRE, SPL, SimpleXML, DOM, JSON, iconv, ctype, cURL
31 |
32 | [Загрузить скрипт проверки требований.](https://xenforo.com/xf2-docs/dev/files/xenforo2-requirements-test.zip)
33 |
34 | ## Настройка локального сервера
35 | Часто более удобно настраивать локальный веб-сервер для разработки. Как правило, для этого существуют два подхода:
36 |
37 | * Установка Apache (или nginx), MySQL (или MariaDB) и сам PHP.
38 | * Установка [предварительно построенной виртуальной машины](/documentation/GettingStarted.md#part6).
39 | * Установка [готовых сборок](/documentation/GettingStarted.md#part7).
40 |
41 | Локальная установка сама по себе может быть сложной, но, как правило, дает вам больше контроля, над тем, как всё настроено.
42 |
43 | ### Предварительно построенная виртуальная машина
44 | В Интернете есть множество готовых виртуальных машин, которые обеспечивают наличия почти всех необходимых сервисов для запуска XenForo, аккуратно упакованного в одно место, без необходимости их установки и обслуживания непосредственно на вашем собственном компьютере.
45 |
46 | Некоторые из разработчиков XenForo используют виртуальную машину под названием [Scotch Box](https://box.scotch.io/), которая включает в себя все необходимое для запуска XenForo с настройками по умолчанию. У нас есть [Пошаговое руководство](https://github.com/spark108/XenForo-2.0-Russian-Documentation/blob/master/documentation/AppendixScotchBox.md) для запуска сервера разработки XenForo - вы получите рабочий виртуальный веб-сервер и сервер баз данных выполня всего несколько команд.
47 |
48 | [Установка Scotch Box для использования с XenForo](https://xenforo.com/xf2-docs/dev/scotchbox/)
49 |
50 | ### Готовые сборки
51 | Существует много готовых сборок, и они могут различаться в наборе функций, производительности и надежности. Bitnami поддерживает несколько сборок, включая [LAMP](https://bitnami.com/stack/lamp), [MAMP](https://bitnami.com/stack/mamp) и [WAMP](https:// bitnami.com/stack/wamp) для использования в Linux, Mac и Windows соответственно. Все они включают полностью настроенную установку Apache, MySQL и PHP, а так же PhpMyAdmin для управления MySQL.
52 |
53 | ## Загрузка
54 | Чтобы установить XF 2.0, вам просто нужно извлечь ZIP-файл, загруженный ранее, и выгрузить некоторые из файлов и каталогов на ваш сервер.
55 |
56 | После извлечения вы увидите каталог с именем `upload`. Вам нужно зайти в этот каталог и загрузить файлы и каталоги в корневой каталог вашего сервера. Обычно это каталог с именем `public_html`,` htdocs` или `www`.
57 |
58 | ## Создание src/config.php
59 | Если вы используете CLI для установки XF 2.0, вам нужно будет создать файл `config.php` вручную. Для этого войдите каталог `src` в файлах XF 2.0, загруженные на ваш сервер. Создайте новый файл с именем `config.php` и заполните его именем хоста, порта, имени пользователя, пароля и базы данных для вашего сервера MySQL.
60 | > **Примечание**
61 | >
62 | > Убедитесь, что вы создали файл конфигурации в каталоге `src`. Каталог `library` используется только для устаревших целей.
63 |
64 | После этого он должен выглядеть следующим образом:
65 | ```php
66 | Замечание по правам доступа к файлам
82 | Во время работы, XenForo записывает файлы в разные места. При нормальной работе это ограничивается каталогами `data` и` internal_data` (и их подкаталогами). Эти записи файлов будут инициироваться такими приложениями, например, вложения, поэтому они, как правило, запускаются пользователем PHP на вашем веб-сервере. Поэтому необходимо обеспечить, чтобы в этих каталогах были установлены разрешения, чтобы веб-сервер мог изменять их. Вам нужно будет сделать это до начала установки.
83 |
84 | Когда CLI задействован, эта ситуация становится более сложной, так как теперь есть потенциально два пользователя, которые должны иметь возможность записывать файлы. Таким образом, важно принять меры, чтобы избежать проблем с записью этих файлов. Вот несколько вариантов.
85 |
86 | 1. Используйте одного и того же пользователя для CLI и веб-сервера. Это значит, что вы должны переключится на пользователя веб-сервера перед запуском любой команды установки или обновления (или любого другого, который будет записывать файлы).
87 | 2. Если доступно, рассмотрите возможность применения ACL к каталогам `data` и` internal_data`. 2. Эта концепция зависит от ОС и конфигурации, но общая идея описывается [здесь](http://symfony.com/doc/current/setup/file_permissions.html).
88 | 3. Принудительная установка разрешения на то, что установлено PHP. Это можно сделать через файл `src/config.php` с такой строкой: `$config['chmodWritableValue'] = 0666;` Этот подход потенциально является самым простым в целях развития.
89 |
90 | Обратите внимание: если вы разрабатываете плагины, могут быть другие местоположения, которые должны быть доступны для записи пользователям CLI и веб-сервером. Примечательно, что это включает в себя каталог `_output` внутри плагина. В этой ситуации, когда ваш веб-сервер работает как пользователь CLI, может возникнуть наименьшее число проблем. Если вы будете использовать любые другие адреса, вам может потребоваться обеспечить, чтобы ваш веб-сервер мог вести запись во все расположения вашей установки XenForo; это не рекомендуется в производстве.
91 |
92 | ## Установка
93 | Текущий способ установки XF 2.0 - это новая система CLI. Многие процессы разработки могут выполняться только с помощью CLI, поэтому давайте закрепим знания о нем, чтобы установить XF 2.0. Чтобы выполнить эти команды, вам понадобится доступ к терминалу/оболочке, команде php и текущему рабочему каталогу, которым должен быть корневой каталог, куда вы загружали файлы XF 2.0.
94 |
95 | > **Предупреждение**
96 | > Чтобы устранить проблемы с разрешениеми файлов, мы рекомендуем запускать установщик как тот же пользователь, что и PHP, как через ваш веб-сервер. Если вы этого не сделаете, вы должны предпринять шаги для обеспечения правильной установки разрешений. См. Выше раздел для более подробной информации.
97 |
98 | Для начала установки используйте следующюю команду:
99 |
100 | $ php cmd.php xf:install
101 |
102 | Вам будет задан ряд вопросов, таких как `имя пользователя`, `пароль администратора`, `название сайта` и т.д.. После этого будут импортированы таблицы базы данных XF 2.0 и настройка основных данныъ.
103 |
104 | XF 2.0 теперь установлен!
105 |
106 | ## Переустановка
107 | Иногда может потребоваться переустановка XF2. Это особенно актуально на этапе предварительного просмотра разработки, который не поддерживает обновление. Если вы готовы сделать переустановку, загрузите новые файлы (если возможно) в соответствии с разделом [Загрузка XF 2.0](/documentation/GettingStarted.md#part8) выше. Как правило, достаточно просто загрузить новые файлы и перезаписать существующие. Если вы делаете полную чистую переустановку, вы можете сохранить копию файла `config.php` или заново создать его в соответствии с инструкциями в [Создание src/config.php](/documentation/GettingStarted.md#part9).
108 | Перед загрузкой новых файлов необходимо удалить содержимое каталогов `data` и `internal_data`.
109 |
110 | Наконец, вам просто нужно будет начать установку, как описано выше. Вам нужно будет использовать опцию `--clear`, которая удалит все существующие таблицы `xf_`.
111 |
112 | $ php cmd.php xf:install --clear
113 |
114 | Как только переустановка завершена, вы можете снова войти в систему.
115 |
116 | Если вы разрабатывали плагины, и вы решили сохранить или создать резервную копию существующего каталога `src/addons`, вы можете восстановить свои данные плагинов с помощью команды [Импорт вывода разработки](https://xenforo.com/xf2-docs/dev/development-tools/#import-development-output).
117 |
118 | > **Предупреждение**
119 | > Будьте осторожны, если вы решите создать резервную копию и восстановить каталог `src/addons`. Каталог `XF` внутри содержит основные данные XF и не может быть восстановлен из резервной копии, чтобы гарантировать, что у вас всегда самая последняя версия файлов.
120 | >
121 | > Выполнение переустановки таким образом является деструктивной операцией и приведет к удалению всех данных, которые вы создали. Кроме того, имейте в виду, что только таблицы с префиксом `xf_` очищаются. Это является существенной причиной для рекомендации, что все таблицы, даже для плагинов, должны иметь префикс `xf_`.
122 |
123 | ## Провека целостности файлов
124 | Когда вы устанавливаете XF2, мы выполняем проверку целостности файла при установке. Если необходимо, но нет возможности выполнить проверку через АСР, вы можете использовать CLI для выполнения этой проверки.
125 |
126 | $ php cmd.php xf:file-check [addon_id]
127 |
128 | Если вы хотите выполнить проверку целостности всех файллв, включая файлы XF, просто опустите аргумент `[addon_id]`. Только для XF просто используйте `XF` вместо аргумента или для определенного дополнения, просто укажите идентификатор плагина, который вы хотите проверить.
129 |
130 | ## Команды управления плагинами
131 | В дополнение к вышеприведенным командам для установки XF2 есть также несколько команд для управления плагинами.
132 |
133 | ### Установка
134 | $ php cmd.php xf:addon-install [addon_id]
135 |
136 | Устанавливает указанное дополнение, если оно доступно, и производит проверку работоспособности файлов. Если выход разработки доступен, вам будет предложено подтвердить, хотите ли вы использовать его для установки вместо экспортированных XML-файлов данных.
137 |
138 | ### Обновление
139 | $ php cmd.php xf:addon-upgrade [addon_id]
140 |
141 | Обновляет указанное дополнение, если его можно обновить, и производит проверку работоспособности файлов. Может произвольно выполнять импорт из вывода разработки.
142 |
143 | ### Перестроение
144 | $ php cmd.php xf:addon-rebuild [addon_id]
145 |
146 | Перестраивает основные данные для указанного плагина и производит проверку работоспособности файла. Данная операция повторно импортирует данные плагина. Может опционально выполнять импорт из вывода разработки.
147 |
148 | ### Удаление
149 | $ php cmd.php xf:addon-uninstall [addon_id]
150 |
151 | Удаляет указанное дополнение, если его можно удалить.
152 |
153 | # Примечание
154 | 1. Не рабочие ссылки так и указаны в документации. Если поправят - сообщите.
155 |
--------------------------------------------------------------------------------
/documentation/RestAPI.md:
--------------------------------------------------------------------------------
1 | # REST API
2 | In XenForo 2.1, a REST API was added. This allows you to programmatically interact with many areas of a XenForo installation.
3 |
4 | Accessing the API requires generating a key via the admin control panel. There is no unauthenticated access to the API and users cannot generate their own keys to access the API at this time.
5 |
6 | The API for a specific XenForo installation is accessible at `/api/`. All endpoints are prefixed by this URL. For example, if XenForo is installed at `https://example.com/community/`, then the API URLs will start with `https://example.com/community/api/`. In this example, accessing a list of threads would be done via `https://example.com/community/api/threads/`.
7 |
8 | The API is enabled by default. If necessary, all API access can quickly be disabled by adding the following to src/config.php:
9 |
10 | ```php
11 | $config['enableApi'] = false;
12 | ```
13 |
14 | ### API keys
15 | API keys are created via the admin control panel by going to **Setup > API keys**. As generating API keys can allow access to highly privileged data, only super administrators may access this system. All super admins will receive an email when an API key is generated to ensure that the request is valid.
16 |
17 | When a key is created, a random string will be generated and this will be used to authenticate yourself with the API. It is important that this key is kept secret. If you believe an API key has been compromised, you should immediately regenerate the key and update any code using the old key.
--------------------------------------------------------------------------------
/documentation/RoutingBasics.md:
--------------------------------------------------------------------------------
1 | # Основы маршрутизации
2 | В PHP-приложении, таком как XF2, нам нужен способ принять запрос определенного URL-адреса от пользователя, понять, какой контроллер, метод и данные использует этот URL-адрес, чтобы предоставить соответствующий ответ пользователю. Концепция преобразования URL-адреса в местоположение в коде известна как "маршрутизация"(routing).
3 |
4 | В XF2 маршрутизация почти полностью управляется из Админ-панели(далее ACP). Найти его можно по пути `ACP > Development > Routes`. Маршруты делятся на два типа, Публичный(далее Public) и Админ(далее Admin) они обеспечивают маршрутизацию запросов в приложениях соответственно.
5 |
6 | # Простой пример
7 | На странице маршрутов (см. выше), найдите маршрут `account/`. Это Public маршрут, обеспечивающий маршрутизацию запросов к URL-адресу `index.php?account/`. Этот маршрут простой; он состоит из небольшого количества конфигураций. Он состоит из "префикса маршрута"(Route prefix), "контекста раздела"(section context) и класса контроллера(controller class). Давайте разберемся в этом более подробно:
8 |
9 | ### Префикс маршрута
10 |
11 | Префикс маршрута идёт после `index.php?` и перед первым `/`. Это первый шаг в определении контроллера, к которому идёт запрос.
12 |
13 | ### Раздел контекста
14 |
15 | Контекст раздела сообщает навигационным системам в XF, какая вкладка навигации должна быть выбрана, когда посетитель просматривает страницу, по этому маршруту. Для `Public` маршрутов контекст раздела должен быть идентификатором вкладки верхнего уровня. Для маршрутов `Admin` должен обратиться к идентификатору самой вкладки навигации в ACP(независимо от глубины).
16 |
17 | В случае с маршрутом `index.php?account/`, контекст раздела не обязателен, поскольку у нас нет вкладки навигации "account". Чтобы увидеть это в действии, просто измените значение "контекст раздела" на "forums", сохраните изменения и перейдите в свою учетную запись `index.php?account/`. Теперь вы должны увидеть, что выбрана вкладка навигации "Форумы"!
18 |
19 | ### Контроллер
20 |
21 | Это имя класса контроллера, которое должно быть вызвано, когда запрос совпадает с этим маршрутом. В случае с маршрутом "account/", у нас есть `XF:Account`. Это загрузит контроллер учетной записи. (Смотрите [Короткие имена классов](/documentation/GeneralConcepts.md#part5) для дополнительной информации). Код этого контроллера располагается по этому пути `src/XF/Pub/Controller/Account.php`. Обратите внимание, как короткие имена классов могут преобразовываться в «инфикс», а также в префикс (XF) и суффикс (Account). В этом случае инфикс для этого контроллера (Pub) выводится из типа маршрута учетной записи (public).
22 |
23 | ### Экшен контроллера
24 |
25 | Выше мы объяснили, как маршрут сопоставляется с определенным контроллером, но мы еще не знаем, как вызывается определенный метод в этом контроллере. Контроллеры являются классами, которые содержат ряд методов, часть URL после [префикса маршрута](/documentation/RoutingBasics.md#part2) указывает на метод контроллера. Данный URL `index.php?account/account-details`, обращается к классу контроллера `XF\Pub\Controller\Account` с именем метода `actionAccountDetails()`. Если маршрут ничего не указывает, то вызывается метод `actionIndex()`.
26 |
27 | Вы можете больше узнать о контроллерах в разделе [Основы контроллера](/documentation/ControllerBasics.md#part0).
28 |
29 | ### Более продвинутый пример (форматы маршрута)
30 |
31 | Давайте посмотрим на маршрут `members/`. Этот маршрут простой, также как и маршрут `account/`, но у него есть заполненное поле; "формат маршрута"(Route format). Чтобы понять, как это работает, посмотрите на свой профиль. URL этого профиля будет выглядеть примерно так `index.php?members/your-name.1`. Обратите внимание на `your-name.1`. Это та часть, которую мы пытаемся сопоставить, используя "формат маршрута".
32 |
33 | "Формат маршрута" позволяет нам извлекать данные из URL запроса, так мы можем передать данные в действие контроллера, чтобы оно могло загрузить определенную информацию; в этом случае загружается профиль запрошенного пользователя. Это также помогает нам создавать ссылки из передаваемых данных. Вот синтаксис:
34 | ```
35 | :int/:page
36 | ```
37 |
38 | Интересно отметить, что важной частью URL-адреса профиля для поиска профиля является не `your-name`, а идентификатор пользователя (`1`). Чтобы продемонстрировать это, измените часть URL `your-name` на `not-your-name`.Вы увидите, что правильный профиль найден, и перенаправление выполнено к правильному URL.
39 |
40 | Приведенный выше формат указывает, что это целочисленный параметр. Для построения исходящей ссылки мы извлекаем целое число из ключа `user_id` . Если ключ имени пользователя передается в данные, он будет "слагифицирован" и добавлен к целочисленному идентификатору, как вы видите в URL-адресе вашего профиля. Для сопоставления входящего URL-адреса это преобразуется в регулярное выражение, соответствующее целочисленному формату параметра.
41 |
42 | `:page` это ярлык для генерации части ссылки на странице - 123. В этом случае он ищет страницу в параметрах ссылки. Если он найден, он помещается в URL-адрес, а затем удаляется из параметров. Для входящего парсинга, если он совпадает (он может быть пустым), добавит номер страницы к параметрам, передаваемым в контроллер.
43 |
44 | ### Параметры маршрута
45 |
46 | Когда маршрут совпадает с определенным контроллером и методом, любые параметры в URL-адресе обернуты в специальный объект, который мы назвали `ParameterBag`. Этот объект специально разработан, чтобы отделить обычные параметры URL с теми, которые прибывают из соответствия маршрута. Объект `ParameterBag` передается в каждое действие контроллера и используется следующим образом:
47 | ```
48 | $userId = $params->user_id;
49 | ```
50 |
51 | ### Суб-имена
52 |
53 | Также можно разделять маршруты на дополнительные суб-имена. Вы можете увидеть это в действии, глядя на маршрут `members/following`. В этом примере, `following` является суб-именем маршрута `members`. Обычно URL-адрес выглядит следующим образом `index.php?members/following`, где часть `following` будет указывать на действие и просто соответствовать нормальному маршруту `members/`. Однако, если есть маршрут, который соответствует префиксу «members» и «sub-name», указанному ниже, он будет использоваться вместо `members/following`. Это верно, поэтому он создает ссылку, как показано ниже:
54 | ```
55 | members/:int/following/:page
56 | ```
57 |
58 | Для сопоставления входящего маршрута, этот маршрут будет проверен перед `members`; если он совпадает, он будет использоваться.
59 |
60 | Эта система суб-имён позволяет изменять поведение, например, изменять положение параметров или подгруппировать маршруты на разных контроллерах или с разными параметрами. Пример последнего можно увидеть в менеджере ресурсов и надстройках Media Gallery.
61 |
--------------------------------------------------------------------------------
/documentation/SchemaManagement.md:
--------------------------------------------------------------------------------
1 |
2 | # Управление схемой
3 | Мы рассмотрели некоторые новые подходы, доступные для взаимодействия с данными. Конечно, существуют конкретные обстоятельства, при которых взаимодействие с базой данных может быть непосредственно необходимым.
4 |
5 | ## Адаптер базы данных
6 | Адаптер базы данных по умолчанию в XF2 основан на расширении MySQL и PHP mysqli. Конфигурируемый адаптер базы данных доступен в любом классе XF, используя следующее:
7 |
8 | $db = \XF::db();
9 | Адаптер имеет несколько доступных методов, которые будут выполнять SQL-запрос, а затем форматировать результаты в массив. Например, для доступа к одной записи пользователя:
10 |
11 | $db = \XF::db();
12 | $user = $db->fetchRow('SELECT * FROM xf_user WHERE user_id = ?', 1);
13 | Теперь переменная `$ user` будет содержать массив всех значений из первой строки, найденной в результате запроса. Чтобы получить одно значение из этого запроса, например, имя пользователя, вы можете сделать следующее:
14 |
15 | $username = $user['username'];
16 |
17 | > **Предупреждение**
18 | > Запросы базы данных, написанные напрямую и переданные в адаптер базы данных, не являются автоматически «безопасными». Таким образом увеличивается риск подвергнутся SQL-инъекции, если пользовательский ввод будет передан без предварительной проверки. Способ сделать это правильно - это использовать подготовленные операторы, как в приведенном выше примере. Параметры представлены в самом запросе с использованием `?` заполнителя. Затем эти заполнители заменяются значениями в следующем аргументе после того, как они были соответствующим образом экранированы. Если вам нужно использовать более одного параметра, это должно быть передано в метод в виде массива. Если возникнет такая необходимость, вы можете избежать значений котировки напрямую, используя `$db->quote($value)`.
19 | >
20 | > Вы можете найти дополнительную информацию о подготовленных запросах [тут](http://php.net/manual/ru/mysqli.quickstart.prepared-statements.php).
21 |
22 | Также можно запросить одно значение из записи. Например:
23 |
24 | $db = \XF::db();
25 | $username = $db->fetchOne('SELECT username FROM xf_user WHERE user_id = ?', 1);
26 | Если у вас есть запрос, который должен возвращать несколько строк, вы можете использовать либо `fetchAll`:
27 |
28 | $db = \XF::db();
29 | $users = $db->fetchAll('SELECT * FROM xf_user LIMIT 10');
30 | либо `fetchAllKeyed`:
31 |
32 | $db = \XF::db();
33 | $users = $db->fetchAllKeyed('SELECT * FROM xf_user LIMIT 10', 'user_id');
34 | Оба этих метода возвращают многомерный массив, который представляет каждую пользовательскую запись. Разница между методами `fetchAll` и `fetchAllKeyed` заключается в том, что возвращаемый массив будет вводиться по-разному. С помощью `fetchAll` массив будет вводиться с числовыми последовательными целыми числами. С помощью `fetchAllKeyed` массив будет зависеть от имени поля, указанного во втором аргументе.
35 |
36 | > **Примечание**
37 | > Если вы используете `fetchAllKeyed` обратите внимание, что вторым аргументом является поле для ввода массива, но ** третий ** аргумент - это то, где вы передаете значения параметра, соответствующие совпадениям `?`.
38 |
39 | Существуют и другие методы типа выборки, включая `fetchAllColumn` для захвата массива значений определенного столбца из всех возвращенных строк:
40 |
41 | $db = \XF::db();
42 | $usernames = $db->fetchAllColumn('SELECT username FROM xf_user LIMIT 10');
43 | В приведенном выше примере будет возвращен массив из 10 имен пользователей, найденных из полученного запроса.
44 |
45 | Наконец, вам более не нужные какие-либо данные. В этом случае вы можете просто выполнить простой запрос:
46 |
47 | $db = \XF::db();
48 | $db->query('DELETE FROM xf_user WHERE user_id = ?', 1);
49 | ## Управление схемой
50 | XF2 включает в себя все новые способы управления схемой базы данных, которая использует объектно-ориентированный подход для выполнения определенных операций с таблицами. Давайте сначала рассмотрим традиционный `Alter`, используя адаптер базы данных, как мы уже говорили выше:
51 |
52 | $db = \XF::db();
53 | $db->query("
54 | ALTER TABLE xf_some_existing_table
55 | ADD COLUMN new_column INT(10) UNSIGNED NOT NULL DEFAULT 0,
56 | MODIFY COLUMN some_existing_column varchar(250) NOT NULL DEFAULT ''
57 | ");
58 | А также рассмотрим типичный запрос создания таблицы:
59 |
60 | $db = \XF::db();
61 | $sm = $db->getSchemaManager();
62 |
63 | $defaultTableConfig = $sm->getTableConfigSql();
64 |
65 | $db->query("
66 | CREATE TABLE xf_some_table (
67 | some_id INT(10) UNSIGNED NOT NULL AUTO_INCREMENT,
68 | some_name VARCHAR(50) NOT NULL,
69 | PRIMARY KEY (user_id)
70 | ) {$defaultTableConfig}
71 | ");
72 | Альтернативный и предпочтительный подход в XF2 использует новый объект `SchemaManager`. Давайте посмотрим на оба этих запроса, как это делает диспетчер схем, начиная с `Alter`:
73 |
74 | $sm = \XF::db()->getSchemaManager();
75 | $sm->alterTable('xf_some_existing_table', function(\XF\Db\Schema\Alter $table)
76 | {
77 | $table->addColumn('new_column', 'int')->setDefault(0);
78 | $table->changeColumn('some_existing_column')->length(250);
79 | });
80 | И создание таблицы:
81 |
82 | $sm = \XF::db()->getSchemaManager();
83 | $sm->createTable('xf_some_table', function(\XF\Db\Schema\Create $table)
84 | {
85 | $table->addColumn('some_id', 'int')->autoIncrement();
86 | $table->addColumn('some_name', 'varchar', 50);
87 | });
88 |
89 | !!! warning
90 | When you alter the existing XenForo tables, or create your own tables, you **MUST** specify a default value otherwise you will encounter problems when querying the table.
91 |
92 |
93 | Оба этих примера дают тот же самый результаты, что и их более прямые аналоги. Хотя вы можете заметить, что некоторые вещи (намеренно) отсутствуют. Например, ни один из примеров не указывает длину для полей `int`. Это просто потому, что, опуская это, MySQL предоставит ему значение по умолчанию, которое равно `10` для целых чисел без знака. Говоря об этом, мы также не указываем, что столбец `some_id` не имеет знака. Использование целых чисел без знака в XF является наиболее распространенным вариантом , поэтому он автоматически добавляется. Если вам действительно нужна поддержка отрицательных целых чисел, вы можете отменить это с помощью метода `->unsigned(false)`. Другое упущение - отсутствие определения «NOT NULL для всего». Опять же, это применяется автоматически, но вы можете отменить это с помощью `->nullable (true)`.
94 |
95 | Это может быть непонятно из приведенного примера, но при изменении существующих полей существующее определение поля автоматически сохраняется. Это означает, что вместо того, чтобы указывать полное определение столбца, включая все биты, которые на самом деле не были изменены, вы можете просто указать части, которые хотите изменить.
96 |
97 | Существует и другой автоматический вывод, который происходит в отношении первичных ключей. Вы можете явно определить первичный ключ (или любой другой тип ключа), если хотите, но часто автоматически увеличиваются поля, которые обычно являются вашим основным ключом для таблицы. Поэтому в примере создания таблицы поле «some_id» автоматически назначается в качестве первичного ключа для этой таблицы.
98 |
99 | Наконец, для подхода `create table` мы можем автоматически добавить правильную конфигурацию таблицы для указанного механизма хранения (который по умолчанию относится к `InnoDB`, но может быть легко изменен для других типов двигателей).
100 |
--------------------------------------------------------------------------------
/documentation/TemplateSyntax.md:
--------------------------------------------------------------------------------
1 | The XenForo 2 template syntax is a powerful tool for both developers and forum administrators, giving you complete control over the layout of your XenForo pages.
2 |
3 | ## Best practices
4 | - XenForo tags, by convention, are `lowercase`.
5 | - All XenForo tags are prefixed with the `xf:` namespace.
6 |
7 | ## Useful information
8 |
9 | ### Commenting up your templates
10 | If you want to comment out some template code (or an inspirational message) that you don't want viewable in the final page source, you can use the `xf:comment` tag.
11 |
12 | ```html
13 |
14 | If you stop seeing the world in terms of what you like
15 | and what you dislike and saw things for what they truly are in themselves,
16 | you will find a great deal more peace in your life.
17 |
18 | ```
19 |
20 | ### Including another template in a template
21 |
22 | The `xf:include` tag allows you to include a different template in your current template.
23 |
24 | ```html
25 |
45 |
46 |
47 |
48 |
49 | ```
50 | At its simplest, a macro can be defined with a `name` attribute and the content you want repeated inside the macro tag.
51 |
52 | !!! note
53 | When you're using a macro in multiple files, it's best practice to put the macro in it's own template.
54 |
55 | #### Macro arguments
56 | ```html
57 |
60 |
61 | Message
62 | {$message}
63 |
64 |
65 | ```
66 | In this example, a macro is defined with a default value for `arg-message` (`My amazing macro message!`).
67 | This value would be overridden if the macro was called with the message argument.
68 |
69 | Sometimes it's necessary to mark an argument as required. This can be done by setting the argument value to `!` in the macro definition.
70 |
71 | ### Including & using macros
72 | ```html
73 |
103 |
104 |
105 | ```
106 |
107 | The if tag takes the following attributes:
108 |
109 | - `is` - The condition which, when met, the tags contents should be shown.
110 |
111 | #### Conditions
112 |
113 | The `is` attribute supports a few logical operators:
114 |
115 | - `OR` - Used to link alternative conditions. (Alternatives: `||`)
116 | - `AND` - Used to link additional conditions. (Alternatives: `&&`)
117 | - `!` - Place before a condition to invert it. (Known as: 'not')
118 | - `XOR` - Returns true if only one of two conditions is true. (Known as: Exclusive OR)
119 |
120 | ### Else/Else-If tag
121 |
122 | The else and else-if tags are used in conjunction with the if tag to conditionally display HTML in the way that the name suggests.
123 |
124 | **Example usage of else:**
125 |
126 | ```html
127 |
128 |
129 |
132 | ```
133 |
134 | **Example usage of else-if:**
135 |
136 | ```html
137 |
138 |
139 |
140 |
141 |
152 | ```
153 |
154 | As you can see, once a condition has been met, the rest of the if statement is ignored. (So, in this case, if the user is an Administrator, the top `xf:if` section is run but then the rest of the if statement is ignored.)
155 |
156 | ### For-each tag
157 |
158 | The for-each tag allows you to loop over an array of items, printing a block of HTML for each item.
159 |
160 | ```html
161 |
164 | Hello there, {$name}. This is name number {$i}. Array key of this element: {$key}
165 |
166 | ```
167 |
168 | The for-each tag takes the following attributes:
169 |
170 | - `loop` - The array to loop over.
171 | - `key` - A variable name to use in the loop to get current element's array key. Can be integer (ordinary array) or string (associative array).
172 | - `value` - A variable name to use within the loop, containing the current array item.
173 | - `i` - A variable name to use in the loop for the current index.
174 |
175 | #### Example Output
176 |
177 | > Hello there, Patrick. This is name number 1.
178 | >
179 | > Hello there, Theresa. This is name number 2.
180 | >
181 | > Hello there, Kimball. This is name number 3.
182 | >
183 | > Hello there, Wayne. This is name number 4.
184 | >
185 | > Hello there, Grace. This is name number 5.
186 |
187 | ## Template tags
188 |
189 | ### Avatar tag
190 |
191 | Inserts a user's avatar in the page.
192 |
193 | ```html
194 | {{ phrase('my_page_name') }}
221 | ```
222 | The breadcrumb tag takes the following attributes:
223 |
224 | - `href` - The link to set for the final element in the breadcrumb.
225 |
226 | The value of the tag can be used to set the name of the final element in the breadcrumb.
227 |
228 | #### Alternative uses
229 | ```html
230 |
353 | html, body {
354 | font-family: "Roboto", sans-serif;
355 | }
356 |
357 | ```
358 | If the CSS tag is not empty, anything in the tag will be converted into inline CSS.
359 |
360 | #### Further notes
361 |
362 | > For [CSS], forget about calling them as files. Copy and paste them into new templates.
363 |
364 | Chris D, XenForo developer **Source**: [https://xenforo.com/community/threads/including-external-library-js-and-css.136153/post-1185631](https://xenforo.com/community/threads/including-external-library-js-and-css.136153/post-1185631)
365 |
366 | ### JS tag
367 |
368 | Includes a JavaScript file.
369 | ```html
370 |
386 | alert("The truth hurts, I know. It's biologically based actually.");
387 |
388 | ```
389 | If the JS tag is not empty, anything in the tag will be converted to inline JS.
390 |
391 | #### Further notes
392 |
393 | JavaScript files are served relative to the `/js` directory. Although not recommended, you can also include external resources with this tag.
394 |
395 | A good example of this tag is in the `editor` template.
396 |
397 | ### Set tag
398 |
399 | The set tag allows you to create a reference to another variable or create a new variable. You should use the set tag anywhere you would use a variable in a programming language.
400 | ```html
401 |
418 | My Variable Value!
419 | This could be a callback, or simply a group of phrases.
420 |
421 | ```
422 | When the `value` attribute is not provided, and the tag is not empty, the variable value will be set to the contents of the tag.
423 |
424 | !!! warning
425 | When you use the Set tag in this form, the value will be escaped and the resulting value will be a string.
426 | The `value` attribute, whilst not supporting HTML or HTML-like tags does not have this limitation.
427 |
428 | ### Likes tag
429 |
430 | Displays the number of likes on a post and a few of the users who've liked the post.
431 |
432 | ```html
433 | {{ phrase('my_page_title') }}
460 | ```
461 | #### Further notes
462 |
463 | Whilst the title can, of course, be hardcoded, it is **highly recommended** that you use a phrase, both for internationalization and for the added customizability on the site administrator's end.
464 |
465 | ### Widget tag
466 |
467 | Includes a widget in the page, or adds a widget to a widget position.
468 | ```html
469 |
563 | My Magical Sidebar!
564 |
565 | ```
566 | #### Common attributes
567 |
568 | - `mode` - The mode of the modification. (See Modification modes)
569 |
570 | #### Modification modes
571 |
572 | By default, the modification mode is `replace`. (i.e. if the attribute is not specified.)
573 |
574 | - `prepend` - Places the contents of the tag at the beginning of the element's HTML.
575 | - `append` - Places the contents of the tag at the end of the element's HTML.
576 | - `replace` - Replaces the element's HTML with the contents of the tag.
577 |
--------------------------------------------------------------------------------