@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
Update the translations document
Summary:
Fixes T8616. The rules for contributors have come up a few times recently, so update this document to give more complete advice.
Also try to do a better job with "adding new classes" (previously: libphutil libraries blah blah no one cares).
Test Plan: Read documents.
Reviewers: btrahan, joshuaspence
Reviewed By: btrahan, joshuaspence
Subscribers: joshuaspence, epriestley
Maniphest Tasks: T8616
Differential Revision: https://secure.phabricator.com/D13358
+609
-195
+1
-1
src/docs/book/contributor.book
+1
-1
src/docs/book/contributor.book
···
2
2
"name": "phabcontrib",
3
3
"title": "Phabricator Contributor Documentation",
4
4
"short": "Phabricator Contributor Docs",
5
-
"preface": "Information for Phabricator contributors.",
5
+
"preface": "Information for Phabricator contributors and developers.",
6
6
"root": "../../../",
7
7
"uri.source":
8
8
"https://secure.phabricator.com/diffusion/P/browse/master/%f$%l",
+1
-1
src/docs/book/phabricator.book
+1
-1
src/docs/book/phabricator.book
···
2
2
"name": "phabdev",
3
3
"title": "Phabricator Technical Documentation",
4
4
"short": "Phabricator Tech Docs",
5
-
"preface": "Technical documentation intended for Phabricator developers.",
5
+
"preface": "Technical reference material for Phabricator developers.",
6
6
"root": "../../../",
7
7
"uri.source":
8
8
"https://secure.phabricator.com/diffusion/P/browse/master/%f$%l",
+256
src/docs/contributor/adding_new_classes.diviner
+256
src/docs/contributor/adding_new_classes.diviner
···
1
+
@title Adding New Classes
2
+
@group developer
3
+
4
+
Guide to adding new classes to extend Phabricator.
5
+
6
+
Overview
7
+
========
8
+
9
+
Phabricator is highly modular, and many parts of it can be extended by adding
10
+
new classes. This document explains how to write new classes to change or
11
+
expand the behavior of Phabricator.
12
+
13
+
IMPORTANT: The upstream does not offer support with extension development.
14
+
15
+
Fundamentals
16
+
============
17
+
18
+
Phabricator primarily discovers functionality by looking at concrete subclasses
19
+
of some base class. For example, Phabricator determines which applications are
20
+
available by looking at all of the subclasses of
21
+
@{class@phabricator:PhabricatorApplication}. It
22
+
discovers available workflows in `arc` by looking at all of the subclasses of
23
+
@{class@arcanist:ArcanistWorkflow}. It discovers available locales
24
+
by looking at all of the subclasses of @{class@libphutil:PhutilLocale}.
25
+
26
+
This pattern holds in many cases, so you can often add functionality by adding
27
+
new classes with no other work. Phabricator will automatically discover and
28
+
integrate the new capabilities or features at runtime.
29
+
30
+
There are two main ways to add classes:
31
+
32
+
- **Extensions Directory**: This is a simple way to add new code. It is
33
+
less powerful, but takes a lot less work. This is good for quick changes,
34
+
testing and development, or getting started on a larger project.
35
+
- **Creating Libraries**: This is a more advanced and powerful way to
36
+
organize extension code. This is better for larger or longer-lived
37
+
projects, or any code which you plan to distribute.
38
+
39
+
The next sections walk through these approaches in greater detail.
40
+
41
+
42
+
Extensions Directory
43
+
====================
44
+
45
+
The easiest way to extend Phabricator by adding new classes is to drop them
46
+
into the extensions directory, at `phabricator/src/extensions/`.
47
+
48
+
This is intended as a quick way to add small pieces of functionality, test new
49
+
features, or get started on a larger project. Extending Phabricator like this
50
+
imposes a small performance penalty compared to using a library.
51
+
52
+
This directory exists in all libphutil libraries, so you can find similar
53
+
directories in `arcanist/src/extensions/` and `libphutil/src/extensions/`.
54
+
55
+
For example, to add a new application, create a file like this one and add it
56
+
to `phabricator/src/extensions/`.
57
+
58
+
```name=phabricator/src/extensions/ExampleApplication.php, lang=php
59
+
<?php
60
+
61
+
final class ExampleApplication extends PhabricatorApplication {
62
+
63
+
public function getName() {
64
+
return pht('Example');
65
+
}
66
+
67
+
}
68
+
```
69
+
70
+
If you load {nav Applications} in the web UI, you should now see your new
71
+
application in the list. It won't do anything yet since you haven't defined
72
+
any interesting behavior, but this is the basic building block of Phabricator
73
+
extensions.
74
+
75
+
76
+
Creating Libraries
77
+
==================
78
+
79
+
A more powerful (but more complicated) way to extend Phabricator is to create
80
+
a libphutil library. Libraries can organize a larger amount of code, are easier
81
+
to work with and distribute, and have slightly better performance than loose
82
+
source files in the extensions directory.
83
+
84
+
In general, you'll perform these one-time setup steps to create a library:
85
+
86
+
- Create a new directory.
87
+
- Use `arc liberate` to initialize and name the library.
88
+
- Configure Phabricator or Arcanist to load the library.
89
+
90
+
Then, to add new code, you do this:
91
+
92
+
- Write or update classes.
93
+
- Update the library metadata by running `arc liberate` again.
94
+
95
+
Initializing a Library
96
+
======================
97
+
98
+
To create a new libphutil library, create a directory for it and run
99
+
`arc liberate` on the directory. This documentation will use a conventional
100
+
directory layout, which is recommended, but you are free to deviate from this.
101
+
102
+
```
103
+
$ mkdir libcustom/
104
+
$ cd libcustom/
105
+
libcustom/ $ arc liberate src/
106
+
```
107
+
108
+
Now you'll get a prompt like this:
109
+
110
+
```lang=txt
111
+
No library currently exists at that path...
112
+
The directory '/some/path/libcustom/src' does not exist.
113
+
114
+
Do you want to create it? [y/N] y
115
+
Creating new libphutil library in '/some/path/libcustom/src'.
116
+
Choose a name for the new library.
117
+
118
+
What do you want to name this library?
119
+
```
120
+
121
+
Choose a library name (in this case, "libcustom" would be appropriate) and it
122
+
you should get some details about the library initialization:
123
+
124
+
```lang=txt
125
+
Writing '__phutil_library_init__.php' to
126
+
'/some/path/libcustom/src/__phutil_library_init__.php'...
127
+
Using library root at 'src'...
128
+
Mapping library...
129
+
Verifying library...
130
+
Finalizing library map...
131
+
OKAY Library updated.
132
+
```
133
+
134
+
This will write three files:
135
+
136
+
- `src/.phutil_module_cache` This is a cache which makes "arc liberate"
137
+
faster when you run it to update the library. You can safely remove it at
138
+
any time. If you check your library into version control, you can add this
139
+
file to ignore rules (like `.gitignore`).
140
+
- `src/__phutil_library_init__.php` This records the name of the library and
141
+
tells libphutil that a library exists here.
142
+
- `src/__phutil_library_map__.php` This is a map of all the symbols
143
+
(functions and classes) in the library, which allows them to be autoloaded
144
+
at runtime and dependencies to be statically managed by `arc liberate`.
145
+
146
+
Linking with Phabricator
147
+
========================
148
+
149
+
If you aren't using this library with Phabricator (e.g., you are only using it
150
+
with Arcanist or are building something else on libphutil) you can skip this
151
+
step.
152
+
153
+
But, if you intend to use this library with Phabricator, you need to define its
154
+
dependency on Phabricator by creating a `.arcconfig` file which points at
155
+
Phabricator. For example, you might write this file to
156
+
`libcustom/.arcconfig`:
157
+
158
+
```lang=json
159
+
{
160
+
"load": [
161
+
"phabricator/src/"
162
+
]
163
+
}
164
+
```
165
+
166
+
For details on creating a `.arcconfig`, see
167
+
@{article:Arcanist User Guide: Configuring a New Project}. In general, this
168
+
tells `arc liberate` that it should look for symbols in Phabricator when
169
+
performing static analysis.
170
+
171
+
NOTE: If Phabricator isn't located next to your custom library, specify a
172
+
path which actually points to the `phabricator/` directory.
173
+
174
+
You do not need to declare dependencies on `arcanist` or `libphutil`,
175
+
since `arc liberate` automatically loads them.
176
+
177
+
Finally, edit your Phabricator config to tell it to load your library at
178
+
runtime, by adding it to `load-libraries`:
179
+
180
+
```lang=json
181
+
...
182
+
'load-libraries' => array(
183
+
'libcustom' => 'libcustom/src/',
184
+
),
185
+
...
186
+
```
187
+
188
+
Now, Phabricator will be able to load classes from your custom library.
189
+
190
+
191
+
Writing Classes
192
+
===============
193
+
194
+
To actually write classes, create a new module and put code in it:
195
+
196
+
libcustom/ $ mkdir src/example/
197
+
libcustom/ $ nano src/example/ExampleClass.php # Edit some code.
198
+
199
+
Now, run `arc liberate` to regenerate the static resource map:
200
+
201
+
libcustom/ $ arc liberate src/
202
+
203
+
This will automatically regenerate the static map of the library.
204
+
205
+
206
+
What You Can Extend And Invoke
207
+
==============================
208
+
209
+
libphutil, Arcanist and Phabricator are strict about extensibility of classes
210
+
and visibility of methods and properties. Most classes are marked `final`, and
211
+
methods have the minimum required visibility (protected or private). The goal
212
+
of this strictness is to make it clear what you can safely extend, access, and
213
+
invoke, so your code will keep working as the upstream changes.
214
+
215
+
IMPORTANT: We'll still break APIs frequently. The upstream does not support
216
+
extension development, and none of these APIs are stable.
217
+
218
+
When developing libraries to work with libphutil, Arcanist and Phabricator, you
219
+
should respect method and property visibility.
220
+
221
+
If you want to add features but can't figure out how to do it without changing
222
+
Phabricator code, here are some approaches you may be able to take:
223
+
224
+
- {icon check, color=green} **Use Composition**: If possible, use composition
225
+
rather than extension to build your feature.
226
+
- {icon check, color=green} **Find Another Approach**: Check the
227
+
documentation for a better way to accomplish what you're trying to do.
228
+
- {icon check, color=green} **File a Feature Request**: Let us know what your
229
+
use case is so we can make the class tree more flexible or configurable, or
230
+
point you at the right way to do whatever you're trying to do, or explain
231
+
why we don't let you do it. Note that we **do not support** extension
232
+
development so you may have mixed luck with this one.
233
+
234
+
These approaches are **discouraged**, but also possible:
235
+
236
+
- {icon times, color=red} **Fork**: Create an ad-hoc local fork and remove
237
+
`final` in your copy of the code. This will make it more difficult for you
238
+
to upgrade in the future, although it may be the only real way forward
239
+
depending on what you're trying to do.
240
+
- {icon times, color=red} **Use Reflection**: You can use
241
+
[[ http://php.net/manual/en/book.reflection.php | Reflection ]] to remove
242
+
modifiers at runtime. This is fragile and discouraged, but technically
243
+
possible.
244
+
- {icon times, color=red} **Remove Modifiers**: Send us a patch removing
245
+
`final` (or turning `protected` or `private` into `public`). We will almost
246
+
never accept these patches unless there's a very good reason that the
247
+
current behavior is wrong.
248
+
249
+
250
+
Next Steps
251
+
==========
252
+
253
+
Continue by:
254
+
255
+
- visiting the [[ https://secure.phabricator.com/w/community_resources/ |
256
+
Community Resources ]] page to find or share extensions and libraries.
+344
-31
src/docs/contributor/internationalization.diviner
+344
-31
src/docs/contributor/internationalization.diviner
···
9
9
Phabricator partially supports internationalization, but many of the tools
10
10
are missing or in a prototype state.
11
11
12
-
This document very briefly summarizes some of what exists today.
12
+
This document describes what tools exist today, how to add new translations,
13
+
and how to use the translation tools to make a codebase translatable.
14
+
15
+
16
+
Adding a New Locale
17
+
===================
18
+
19
+
To add a new locale, subclass @{class:PhutilLocale}. This allows you to
20
+
introduce a new locale, like "German" or "Klingon".
21
+
22
+
Once you've created a locale, applications can add translations for that
23
+
locale.
24
+
25
+
For instructions on adding new classes, see @{article:Adding New Classes}.
26
+
27
+
28
+
Adding Translations to Locale
29
+
=============================
30
+
31
+
To translate strings, subclass @{class:PhutilTranslation}. Translations need
32
+
to belong to a locale: the locale defines an available language, and each
33
+
translation subclass provides strings for it.
34
+
35
+
Translations are separated from locales so that third-party applications can
36
+
provide translations into different locales without needing to define those
37
+
locales themselves.
38
+
39
+
For instructions on adding new classes, see @{article:Adding New Classes}.
40
+
13
41
14
42
Writing Translatable Code
15
-
========
43
+
=========================
16
44
17
45
Strings are marked for translation with @{function@libphutil:pht}.
18
46
19
-
Adding a New Locale
20
-
=========
47
+
The `pht()` function takes a string (and possibly some parameters) and returns
48
+
the translated version of that string in the current viewer's locale, if a
49
+
translation is available.
50
+
51
+
If text strings will ultimately be read by humans, they should essentially
52
+
always be wrapped in `pht()`. For example:
53
+
54
+
```lang=php
55
+
$dialog->appendParagraph(pht('This is an example.'));
56
+
```
57
+
58
+
This allows the code to return the correct Spanish or German or Russian
59
+
version of the text, if the viewer is using Phabricator in one of those
60
+
languages and a translation is available.
61
+
62
+
Using `pht()` properly so that strings are translatable can be tricky. Briefly,
63
+
the major rules are:
64
+
65
+
- Only pass static strings as the first parameter to `pht()`.
66
+
- Use parameters to create strings containing user names, object names, etc.
67
+
- Translate full sentences, not sentence fragments.
68
+
- Let the translation framework handle plural rules.
69
+
- Use @{class@libphutil:PhutilNumber} for numbers.
70
+
- Let the translation framework handle subject gender rules.
71
+
- Translate all human-readable text, even exceptions and error messages.
72
+
73
+
See the next few sections for details on these rules.
74
+
75
+
76
+
Use Static Strings
77
+
==================
78
+
79
+
The first parameter to `pht()` must always be a static string. Broadly, this
80
+
means it should not contain variables or function or method calls (it's OK to
81
+
split it across multiple lines and concatenate the parts together).
82
+
83
+
These are good:
84
+
85
+
```lang=php
86
+
pht('The night is dark.');
87
+
pht(
88
+
'Two roads diverged in a yellow wood, '.
89
+
'and sorry I could not travel both '.
90
+
'and be one traveler, long I stood.');
91
+
92
+
```
93
+
94
+
These won't work (they might appear to work, but are wrong):
95
+
96
+
```lang=php, counterexample
97
+
pht(some_function());
98
+
pht('The duck says, '.$quack);
99
+
pht($string);
100
+
```
101
+
102
+
The first argument must be a static string so it can be extracted by static
103
+
analysis tools and dumped in a big file for translators. If it contains
104
+
functions or variables, it can't be extracted, so translators won't be able to
105
+
translate it.
106
+
107
+
Lint will warn you about problems with use of static strings in calls to
108
+
`pht()`.
109
+
110
+
111
+
Parameters
112
+
==========
113
+
114
+
You can provide parameters to a translation string by using `sprintf()`-style
115
+
patterns in the input string. For example:
116
+
117
+
```lang=php
118
+
pht('%s earned an award.', $actor);
119
+
pht('%s closed %s.', $actor, $task);
120
+
```
121
+
122
+
This is primarily appropriate for usernames, object names, counts, and
123
+
untranslatable strings like URIs or instructions to run commands from the CLI.
124
+
125
+
Parameters normally should not be used to combine two pieces of translated
126
+
text: see the next section for guidance.
127
+
128
+
Sentence Fragments
129
+
==================
130
+
131
+
You should almost always pass the largest block of text to `pht()` that you
132
+
can. Particularly, it's important to pass complete sentences, not try to build
133
+
a translation by stringing together sentence fragments.
134
+
135
+
There are several reasons for this:
136
+
137
+
- It gives translators more context, so they can be more confident they are
138
+
producing a satisfying, natural-sounding translation which will make sense
139
+
and sound good to native speakers.
140
+
- In some languages, one fragment may need to translate differently depending
141
+
on what the other fragment says.
142
+
- In some languages, the most natural-sounding translation may change the
143
+
order of words in the sentence.
144
+
145
+
For example, suppose we want to translate these sentence to give the user some
146
+
instructions about how to use an interface:
147
+
148
+
> Turn the switch to the right.
149
+
150
+
> Turn the switch to the left.
151
+
152
+
> Turn the dial to the right.
153
+
154
+
> Turn the dial to the left.
155
+
156
+
Maybe we have a function like this:
157
+
158
+
```
159
+
function get_string($is_switch, $is_right) {
160
+
// ...
161
+
}
162
+
```
163
+
164
+
One way to write the function body would be like this:
165
+
166
+
```lang=php, counterexample
167
+
$what = $is_switch ? pht('switch') : pht('dial');
168
+
$dir = $is_right ? pht('right') : pht('left');
169
+
170
+
return pht('Turn the ').$what.pht(' to the ').$dir.pht('.');
171
+
```
172
+
173
+
This will work fine in English, but won't work well in other languages.
174
+
175
+
One problem with doing this is handling gendered nouns. Languages like Spanish
176
+
have gendered nouns, where some nouns are "masculine" and others are
177
+
"feminine". The gender of a noun affects which article (in English, the word
178
+
"the" is an article) should be used with it.
179
+
180
+
In English, we say "**the** knob" and "**the** switch", but a Spanish speaker
181
+
would say "**la** perilla" and "**el** interruptor", because the noun for
182
+
"knob" in Spanish is feminine (so it is used with the article "la") while the
183
+
noun for "switch" is masculine (so it is used with the article "el").
184
+
185
+
A Spanish speaker can not translate the string "Turn the" correctly without
186
+
knowing which gender the noun has. Spanish has //two// translations for this
187
+
string ("Gira el", "Gira la"), and the form depends on which noun is being
188
+
used.
189
+
190
+
Another problem is that this reduces flexibility. Translating fragments like
191
+
this locks translators into a specific word order, when rearranging the words
192
+
might make the sentence sound much more natural to a native speaker.
193
+
194
+
For example, if the string read "The knob, to the right, turn it.", it
195
+
would technically be English and most English readers would understand the
196
+
meaning, but no native English speaker would speak or write like this.
197
+
198
+
However, some languages have different subject-verb order rules or
199
+
colloquisalisms, and a word order which transliterates like this may sound more
200
+
natural to a native speaker. By translating fragments instead of complete
201
+
sentences, you lock translators into English word order.
202
+
203
+
Finally, the last fragment is just a period. If a translator is presented with
204
+
this string in an interface without much context, they have no hope of guessing
205
+
how it is used in the software (it could be an end-of-sentence marker, or a
206
+
decimal point, or a date separator, or a currency separator, all of which have
207
+
very different translations in many locales). It will also conflict with all
208
+
other translations of the same string in the codebase, so even if they are
209
+
given context they can't translate it without technical problems.
21
210
22
-
To add a new locale, subclass @{class:PhutilLocale}.
211
+
To avoid these issues, provide complete sentences for translation. This almost
212
+
always takes the form of writing out alternatives in full. This is a good way
213
+
to implement the example function:
214
+
215
+
```lang=php
216
+
if ($is_switch) {
217
+
if ($is_right) {
218
+
return pht('Turn the switch to the right.');
219
+
} else {
220
+
return pht('Turn the switch to the left.');
221
+
}
222
+
} else {
223
+
if ($is_right) {
224
+
return pht('Turn the dial to the right.');
225
+
} else {
226
+
return pht('Turn the dial to the left.');
227
+
}
228
+
}
229
+
```
23
230
24
-
Translating Strings
25
-
========
231
+
Although this is more verbose, translators can now get genders correct,
232
+
rearrange word order, and have far more context when translating. This enables
233
+
better, natural-sounding translations which are more satisfying to native
234
+
speakers.
26
235
27
-
To translate strings, subclass @{class:PhutilTranslation}.
28
236
29
237
Singular and Plural
30
-
========
238
+
===================
239
+
240
+
Different languages have various rules for plural nouns.
241
+
242
+
In English there are usually two plural noun forms: for one thing, and any
243
+
other number of things. For example, we say that one chair is a "chair" and any
244
+
other number of chairs are "chairs": "0 chairs", "1 chair", "2 chairs", etc.
31
245
32
-
Different languages have various rules for using singular and plural. All you
33
-
need to do is to call @{function@libphutil:pht} with a text that is suitable for
34
-
both forms. Example:
246
+
In other languages, there are different (and, in some cases, more) plural
247
+
forms. For example, in Czech, there are separate forms for "one", "several",
248
+
and "many".
249
+
250
+
Because plural noun rules depend on the language, you should not write code
251
+
which hard-codes English rules. For example, this won't translate well:
252
+
253
+
```lang=php, counterexample
254
+
if ($count == 1) {
255
+
return pht('This will take an hour.');
256
+
} else {
257
+
return pht('This will take hours.');
258
+
}
259
+
```
260
+
261
+
This code is hard-coding the English rule for plural nouns. In languages like
262
+
Czech, the correct word for "hours" may be different if the count is 2 or 15,
263
+
but a translator won't be able to provide the correct translation if the string
264
+
is written like this.
265
+
266
+
Instead, pass a generic string to the translation engine which //includes// the
267
+
number of objects, and let it handle plural nouns. This is the correct way to
268
+
write the translation:
269
+
270
+
```lang=php
271
+
return pht('This will take %s hour(s).', new PhutilNumber($count));
272
+
```
273
+
274
+
If you now load the web UI, you'll see "hour(s)" literally in the UI. To fix
275
+
this so the translation sounds better in English, provide translations for this
276
+
string in the @{class@phabricator:PhabricatorUSEnglishTranslation} file:
277
+
278
+
```lang=php
279
+
'This will take %s hour(s).' => array(
280
+
'This will take an hour.',
281
+
'This will take hours.',
282
+
),
283
+
```
284
+
285
+
The string will then sound natural in English, but non-English translators will
286
+
also be able to produce a natural translation.
287
+
288
+
Note that the translations don't actually include the number in this case. The
289
+
number is being passed from the code, but that just lets the translation engine
290
+
get the rules right: the number does not need to appear in the final
291
+
translations shown to the user.
292
+
293
+
Using PhutilNumber
294
+
==================
35
295
36
-
pht('%d beer(s)', $count);
296
+
When translating numbers, you should almost always use `%s` and wrap the count
297
+
or number in `new PhutilNumber($count)`. For example:
37
298
38
-
Translators will translate this text for all different forms the language uses:
299
+
```lang=php
300
+
pht('You have %s experience point(s).', new PhutilNumber($xp));
301
+
```
39
302
40
-
// English translation
41
-
array('%d beer', '%d beers');
303
+
This will let the translation engine handle plural noun rules correctly, and
304
+
also format large numbers correctly in a locale-aware way with proper unit and
305
+
decimal separators (for example, `1000000` may be printed as "1,000,000",
306
+
with commas for readability).
42
307
43
-
// Czech translation
44
-
array('%d pivo', '%d piva', '%d piv');
308
+
The exception to this rule is IDs which should not be written with unit
309
+
separators. For example, this is correct for an object ID:
45
310
46
-
The ugly identifier passed to @{function@libphutil:pht} will remain in the text
47
-
only if the translation doesn't exist.
311
+
```lang=php
312
+
pht('This diff has ID %d.', $diff->getID());
313
+
```
48
314
49
315
Male and Female
50
-
========
316
+
===============
317
+
318
+
Different languages also use different words for talking about subjects who are
319
+
male, female or have an unknown gender. In English this is mostly just
320
+
pronouns (like "he" and "she") but there are more complex rules in other
321
+
languages, and languages like Czech also require verb agreement.
322
+
323
+
When a parameter refers to a gendered person, pass an object which implements
324
+
@{interface@libphutil:PhutilPerson} to `pht()` so translators can provide
325
+
gendered translation variants.
326
+
327
+
```lang=php
328
+
pht('%s wrote', $actor);
329
+
```
330
+
331
+
Translators will create these translations:
332
+
333
+
```lang=php
334
+
// English translation
335
+
'%s wrote';
336
+
337
+
// Czech translation
338
+
array('%s napsal', '%s napsala');
339
+
```
51
340
52
-
Different languages use different words for talking about males, females and
53
-
unknown genders. Callsites have to call @{function@libphutil:pht} passing
54
-
@{class:PhabricatorUser} (or other implementation of
55
-
@{interface@libphutil:PhutilPerson}) if talking about the user. Example:
341
+
(You usually don't need to worry very much about this rule, it is difficult to
342
+
get wrong in standard code.)
56
343
57
-
pht('%s wrote', $actor);
58
344
59
-
Translators will create this translations:
345
+
Exceptions and Errors
346
+
=====================
60
347
61
-
// English translation
62
-
'%s wrote';
348
+
You should translate all human-readable text, even exceptions and error
349
+
messages. This is primarily a rule of convenience which is straightforward
350
+
and easy to follow, not a technical rule.
63
351
64
-
// Czech translation
65
-
array('%s napsal', '%s napsala');
352
+
Some exceptions and error messages don't //technically// need to be translated,
353
+
as they will never be shown to a user, but many exceptions and error messages
354
+
are (or will become) user-facing on some way. When writing a message, there is
355
+
often no clear and objective way to determine which type of message you are
356
+
writing. Rather than try to distinguish which are which, we simply translate
357
+
all human-readable text. This rule is unambiguous and easy to follow.
358
+
359
+
In cases where similar error or exception text is often repeated, it is
360
+
probably appropriate to define an exception for that category of error rather
361
+
than write the text out repeatedly, anyway. Two examples are
362
+
@{class@libphutil:PhutilInvalidStateException} and
363
+
@{class@libphutil:PhutilMethodNotImplementedException}, which mostly exist to
364
+
produce a consistent message about a common error state in a convenient way.
365
+
366
+
There are a handful of error strings in the codebase which may be used before
367
+
the translation framework is loaded, or may be used during handling other
368
+
errors, possibly rasised from within the translation framework. This handful
369
+
of special cases are left untranslated to prevent fatals and cycles in the
370
+
error handler.
371
+
372
+
373
+
Next Steps
374
+
==========
375
+
376
+
Continue by:
377
+
378
+
- adding a new locale or translation file with @{article:Adding New Classes}.
+1
-1
src/docs/user/configuration/custom_fields.diviner
+1
-1
src/docs/user/configuration/custom_fields.diviner
+2
-2
src/docs/user/configuration/managing_daemons.diviner
+2
-2
src/docs/user/configuration/managing_daemons.diviner
···
109
109
just those started with `phd start`. If you're writing a restart script,
110
110
have it launch any custom daemons explicitly after `phd restart`.
111
111
- You can write your own daemons and manage them with `phd` by extending
112
-
@{class:PhabricatorDaemon}. See @{article:libphutil Libraries User Guide}.
112
+
@{class:PhabricatorDaemon}. See {article@contributor:Adding New Classes}.
113
113
- See @{article:Diffusion User Guide} for details about tuning the repository
114
114
daemon.
115
115
···
137
137
138
138
- learning about the repository daemon with @{article:Diffusion User Guide};
139
139
or
140
-
- writing your own daemons with @{article:libphutil Libraries User Guide}.
140
+
- writing your own daemons with {article@contributor:Adding New Classes}.
+1
-1
src/docs/user/userguide/arcanist_lint_unit.diviner
+1
-1
src/docs/user/userguide/arcanist_lint_unit.diviner
···
38
38
39
39
If you haven't created a library for the class to live in yet, you need to do
40
40
that first. Follow the instructions in
41
-
@{article:libphutil Libraries User Guide}, then make the library loadable by
41
+
@{article@contributor:Adding New Classes}, then make the library loadable by
42
42
adding it to your `.arcconfig` like this:
43
43
44
44
{
+1
-1
src/docs/user/userguide/arcanist_new_project.diviner
+1
-1
src/docs/user/userguide/arcanist_new_project.diviner
···
47
47
48
48
- **load**: list of additional Phutil libraries to load at startup.
49
49
See below for details about path resolution, or see
50
-
@{article:libphutil Libraries User Guide} for a general introduction to
50
+
@{article@contributor:Adding New Classes} for a general introduction to
51
51
libphutil libraries.
52
52
- **https.cabundle**: specifies the path to an alternate certificate bundle
53
53
for use when making HTTPS connections.
+2
-2
src/docs/user/userguide/events.diviner
+2
-2
src/docs/user/userguide/events.diviner
···
21
21
22
22
- Write a listener class which extends @{class@libphutil:PhutilEventListener}.
23
23
- Add it to a libphutil library, or create a new library (for instructions,
24
-
see @{article:libphutil Libraries User Guide}.
24
+
see @{article@contributor:Adding New Classes}.
25
25
- Configure Phabricator to load the library by adding it to `load-libraries`
26
26
in the Phabricator config.
27
27
- Configure Phabricator to install the event listener by adding the class
···
38
38
39
39
- Write a listener class which extends @{class@libphutil:PhutilEventListener}.
40
40
- Add it to a libphutil library, or create a new library (for instructions,
41
-
see @{article:libphutil Libraries User Guide}.
41
+
see @{article@contributor:Adding New Classes}.
42
42
- Configure Phabricator to load the library by adding it to `load`
43
43
in the Arcanist config (e.g., `.arcconfig`, or user/global config).
44
44
- Configure Arcanist to install the event listener by adding the class
-155
src/docs/user/userguide/libraries.diviner
-155
src/docs/user/userguide/libraries.diviner
···
1
-
@title libphutil Libraries User Guide
2
-
@group userguide
3
-
4
-
Guide to creating and managing libphutil libraries.
5
-
6
-
= Overview =
7
-
8
-
libphutil includes a library system which organizes PHP classes and functions
9
-
into modules. Some extensions and customizations of Arcanist and Phabricator
10
-
require you to make code available to Phabricator by providing it in a libphutil
11
-
library.
12
-
13
-
For example, if you want to store files in some kind of custom storage engine,
14
-
you need to write a class which can interact with that engine and then tell
15
-
Phabricator to load it.
16
-
17
-
In general, you perform these one-time setup steps:
18
-
19
-
- Create a new directory.
20
-
- Use `arc liberate` to initialize and name the library.
21
-
- Add a dependency on Phabricator if necessary.
22
-
- Add the library to your Phabricator config or `.arcconfig` so it will be
23
-
loaded at runtime.
24
-
25
-
Then, to add new code, you do this:
26
-
27
-
- Write or update classes.
28
-
- Update the library metadata by running `arc liberate` again.
29
-
30
-
= Creating a New Library =
31
-
32
-
To **create a new libphutil library**:
33
-
34
-
$ mkdir libcustom/
35
-
$ cd libcustom/
36
-
libcustom/ $ arc liberate src/
37
-
38
-
Now you'll get a prompt like this:
39
-
40
-
lang=txt
41
-
No library currently exists at that path...
42
-
The directory '/some/path/libcustom/src' does not exist.
43
-
44
-
Do you want to create it? [y/N] y
45
-
Creating new libphutil library in '/some/path/libcustom/src'.
46
-
Choose a name for the new library.
47
-
48
-
What do you want to name this library?
49
-
50
-
Choose a library name (in this case, "libcustom" would be appropriate) and it
51
-
you should get some details about the library initialization:
52
-
53
-
lang=txt
54
-
Writing '__phutil_library_init__.php' to
55
-
'/some/path/libcustom/src/__phutil_library_init__.php'...
56
-
Using library root at 'src'...
57
-
Mapping library...
58
-
Verifying library...
59
-
Finalizing library map...
60
-
OKAY Library updated.
61
-
62
-
This will write three files:
63
-
64
-
- `src/.phutil_module_cache` This is a cache which makes "arc liberate"
65
-
faster when you run it to update the library. You can safely remove it at
66
-
any time. If you check your library into version control, you can add this
67
-
file to ignore rules (like .gitignore).
68
-
- `src/__phutil_library_init__.php` This records the name of the library and
69
-
tells libphutil that a library exists here.
70
-
- `src/__phutil_library_map__.php` This is a map of all the symbols
71
-
(functions and classes) in the library, which allows them to be autoloaded
72
-
at runtime and dependencies to be statically managed by "arc liberate".
73
-
74
-
= Linking with Phabricator =
75
-
76
-
If you aren't using this library with Phabricator (e.g., you are only using it
77
-
with Arcanist or are building something else on libphutil) you can skip this
78
-
step.
79
-
80
-
But, if you intend to use this library with Phabricator, you need to define its
81
-
dependency on Phabricator by creating a `.arcconfig` file which points at
82
-
Phabricator. For example, you might write this file to
83
-
`libcustom/.arcconfig`:
84
-
85
-
{
86
-
"load": [
87
-
"phabricator/src/"
88
-
]
89
-
}
90
-
91
-
For details on creating a `.arcconfig`, see
92
-
@{article:Arcanist User Guide: Configuring a New Project}. In general, this
93
-
tells `arc liberate` that it should look for symbols in Phabricator when
94
-
performing static analysis.
95
-
96
-
NOTE: If Phabricator isn't located next to your custom library, specify a
97
-
path which actually points to the `phabricator/` directory.
98
-
99
-
You do not need to declare dependencies on `arcanist` or `libphutil`,
100
-
since `arc liberate` automatically loads them.
101
-
102
-
Finally, edit your Phabricator config to tell it to load your library at
103
-
runtime, by adding it to `load-libraries`:
104
-
105
-
...
106
-
'load-libraries' => array(
107
-
'libcustom' => 'libcustom/src/',
108
-
),
109
-
...
110
-
111
-
Now, Phabricator will be able to load classes from your custom library.
112
-
113
-
= Writing Classes =
114
-
115
-
To actually write classes, create a new module and put code in it:
116
-
117
-
libcustom/ $ mkdir src/example/
118
-
libcustom/ $ nano src/example/ExampleClass.php # Edit some code.
119
-
120
-
Now, run `arc liberate` to regenerate the static resource map:
121
-
122
-
libcustom/ $ arc liberate src/
123
-
124
-
This will automatically regenerate the static map of the library.
125
-
126
-
= What You Can Extend And Invoke =
127
-
128
-
libphutil, Arcanist and Phabricator are strict about extensibility of classes
129
-
and visibility of methods and properties. Most classes are marked `final`, and
130
-
methods have the minimum required visibility (protected or private). The goal of
131
-
this strictness is to make it clear what you can safely extend, access, and
132
-
invoke, so your code will keep working as the upstream changes.
133
-
134
-
When developing libraries to work with libphutil, Arcanist and Phabricator, you
135
-
should respect method and property visibility and extend only classes marked
136
-
`@stable`. They are rendered with a large callout in the documentation (for
137
-
example: @{class@libphutil:AbstractDirectedGraph}). These classes are external
138
-
interfaces intended for extension.
139
-
140
-
If you want to extend a class but it is not marked `@stable`, here are some
141
-
approaches you can take:
142
-
143
-
- Good: If possible, use composition rather than extension to build your
144
-
feature.
145
-
- Good: Check the documentation for a better way to accomplish what you're
146
-
trying to do.
147
-
- Good: Let us know what your use case is so we can make the class tree more
148
-
flexible or configurable, or point you at the right way to do whatever
149
-
you're trying to do, or explain why we don't let you do it.
150
-
- Discouraged: Send us a patch removing "final" (or turning "protected" or
151
-
"private" into "public"). We generally will not accept these patches, unless
152
-
there's a good reason that the current behavior is wrong.
153
-
- Discouraged: Create an ad-hoc local fork and remove "final" in your copy of
154
-
the code. This will make it more difficult for you to upgrade in the future.
155
-
- Discouraged: Use Reflection to violate visibility keywords.