@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
Search-related PhpDoc additions
Summary: I'm trying to understand search a bit better. As a side effect I add PhpDocs.
Test Plan: Inspect parameter and return formats, types, content while searching in Phorge.
Reviewers: O1 Blessed Committers, valerio.bozzolan
Reviewed By: O1 Blessed Committers, valerio.bozzolan
Subscribers: tobiaswiese, valerio.bozzolan, Matthew, Cigaryno
Differential Revision: https://we.phorge.it/D26033
+121
+33
src/applications/search/compiler/PhutilSearchQueryCompiler.php
+33
src/applications/search/compiler/PhutilSearchQueryCompiler.php
···
29
29
return $this;
30
30
}
31
31
32
+
/**
33
+
* @return PhutilSearchStemmer
34
+
*/
32
35
public function getStemmer() {
33
36
return $this->stemmer;
34
37
}
35
38
39
+
/**
40
+
* @param bool $enable_functions
41
+
*/
36
42
public function setEnableFunctions($enable_functions) {
37
43
$this->enableFunctions = $enable_functions;
38
44
return $this;
39
45
}
40
46
47
+
/**
48
+
* @return bool
49
+
*/
41
50
public function getEnableFunctions() {
42
51
return $this->enableFunctions;
43
52
}
44
53
54
+
/**
55
+
* @param array<PhutilSearchQueryToken> $tokens
56
+
* @return string|null
57
+
*/
45
58
public function compileQuery(array $tokens) {
46
59
assert_instances_of($tokens, 'PhutilSearchQueryToken');
47
60
···
53
66
return $this->compileRenderedTokens($result);
54
67
}
55
68
69
+
/**
70
+
* @param array<PhutilSearchQueryToken> $tokens
71
+
* @return string|null
72
+
*/
56
73
public function compileLiteralQuery(array $tokens) {
57
74
assert_instances_of($tokens, 'PhutilSearchQueryToken');
58
75
···
67
84
return $this->compileRenderedTokens($result);
68
85
}
69
86
87
+
/**
88
+
* @param array<PhutilSearchQueryToken> $tokens
89
+
* @return string|null
90
+
*/
70
91
public function compileStemmedQuery(array $tokens) {
71
92
assert_instances_of($tokens, 'PhutilSearchQueryToken');
72
93
···
81
102
return $this->compileRenderedTokens($result);
82
103
}
83
104
105
+
/**
106
+
* @return string|null
107
+
*/
84
108
private function compileRenderedTokens(array $list) {
85
109
if (!$list) {
86
110
return null;
···
90
114
return implode(' ', $list);
91
115
}
92
116
117
+
/**
118
+
* @return PhutilSearchQueryToken[]
119
+
*/
93
120
public function newTokens($query) {
94
121
$results = $this->tokenizeQuery($query);
95
122
···
101
128
return $tokens;
102
129
}
103
130
131
+
/**
132
+
* @param string $query Search string or part of the search string
133
+
* @return array<string[]> An array consisting of array elements like
134
+
* {"operator":"and","quoted":false,"value":"get","raw":"get",
135
+
* "function":null}
136
+
*/
104
137
private function tokenizeQuery($query) {
105
138
$maximum_bytes = 1024;
106
139
if ($query === null) {
+3
src/applications/search/compiler/PhutilSearchQueryToken.php
+3
src/applications/search/compiler/PhutilSearchQueryToken.php
+25
src/applications/search/compiler/PhutilSearchStemmer.php
+25
src/applications/search/compiler/PhutilSearchStemmer.php
···
3
3
final class PhutilSearchStemmer
4
4
extends Phobject {
5
5
6
+
/**
7
+
* Perform normalization and stemming on input token
8
+
* @param string $token Input token
9
+
* @return string Either stemmed token, or original input if token is too
10
+
* short (<3 characters) or if token contains certain punctuation elements
11
+
*/
6
12
public function stemToken($token) {
7
13
$token = $this->normalizeToken($token);
8
14
return $this->applyStemmer($token);
9
15
}
10
16
17
+
/**
18
+
* Perform normalization and stemming on input corpus
19
+
* @param string $corpus Input corpus
20
+
* @return string Stemmed corpus
21
+
*/
11
22
public function stemCorpus($corpus) {
12
23
$corpus = $this->normalizeCorpus($corpus);
13
24
$tokens = preg_split('/[^a-zA-Z0-9\x7F-\xFF._]+/', $corpus);
···
31
42
return implode(' ', $stems);
32
43
}
33
44
45
+
/**
46
+
* Internally convert token to lower case in a UTF8-aware way.
47
+
* @param string $token Input token.
48
+
* @return string Input token, in some semblance of lower case.
49
+
*/
34
50
private function normalizeToken($token) {
35
51
return phutil_utf8_strtolower($token);
36
52
}
37
53
54
+
/**
55
+
* Internally convert corpus to lower case in a UTF8-aware way.
56
+
* @param string $corpus Input corpus.
57
+
* @return string Input corpus, in some semblance of lower case.
58
+
*/
38
59
private function normalizeCorpus($corpus) {
39
60
return phutil_utf8_strtolower($corpus);
40
61
}
41
62
42
63
/**
64
+
* Internally pass normalized tokens to Porter to perform stemming. Or not.
65
+
* @param string $normalized_token Lower case token
66
+
* @return string Either stemmed token, or original input if token is too
67
+
* short (<3 characters) or if token contains certain punctuation elements
43
68
* @phutil-external-symbol class Porter
44
69
*/
45
70
private function applyStemmer($normalized_token) {
+3
src/applications/search/fulltextstorage/PhabricatorFerretFulltextStorageEngine.php
+3
src/applications/search/fulltextstorage/PhabricatorFerretFulltextStorageEngine.php
+6
src/applications/search/query/PhabricatorFulltextResultSet.php
+6
src/applications/search/query/PhabricatorFulltextResultSet.php
···
14
14
return $this->phids;
15
15
}
16
16
17
+
/**
18
+
* @param array<PhabricatorFulltextToken> $fulltext_tokens
19
+
*/
17
20
public function setFulltextTokens($fulltext_tokens) {
18
21
$this->fulltextTokens = $fulltext_tokens;
19
22
return $this;
20
23
}
21
24
25
+
/**
26
+
* @return array<PhabricatorFulltextToken>
27
+
*/
22
28
public function getFulltextTokens() {
23
29
return $this->fulltextTokens;
24
30
}
+3
src/applications/search/query/PhabricatorFulltextToken.php
+3
src/applications/search/query/PhabricatorFulltextToken.php
+8
src/applications/search/query/PhabricatorSearchDocumentQuery.php
+8
src/applications/search/query/PhabricatorSearchDocumentQuery.php
···
26
26
return $this->getRequiredCapabilities();
27
27
}
28
28
29
+
/**
30
+
* @return PhabricatorFulltextResultSet
31
+
*/
29
32
public function getFulltextResultSet() {
30
33
if (!$this->fulltextResultSet) {
31
34
throw new PhutilInvalidStateException('execute');
···
39
42
$this->fulltextResultSet = null;
40
43
}
41
44
45
+
/**
46
+
* Load a raw page of results.
47
+
*
48
+
* @return list PHIDs of the search result objects as array keys.
49
+
*/
42
50
protected function loadPage() {
43
51
// NOTE: The offset and limit information in the inherited properties of
44
52
// this object represent a policy-filtered offset and limit, but the
+12
src/infrastructure/cluster/search/PhabricatorElasticsearchHost.php
+12
src/infrastructure/cluster/search/PhabricatorElasticsearchHost.php
···
20
20
return $this;
21
21
}
22
22
23
+
/**
24
+
* @return string Display name of the search host: "Elasticsearch"
25
+
*/
23
26
public function getDisplayName() {
24
27
return pht('Elasticsearch');
25
28
}
26
29
30
+
/**
31
+
* @return string[] Get a list of fields to show in the status overview UI
32
+
*/
27
33
public function getStatusViewColumns() {
28
34
return array(
29
35
pht('Protocol') => $this->getProtocol(),
···
40
46
return $this;
41
47
}
42
48
49
+
/**
50
+
* @return string Search host protocol, by default "http"
51
+
*/
43
52
public function getProtocol() {
44
53
return $this->protocol;
45
54
}
···
62
71
return $this->version;
63
72
}
64
73
74
+
/**
75
+
* @return PhutilURI
76
+
*/
65
77
public function getURI($to_path = null) {
66
78
$uri = id(new PhutilURI('http://'.$this->getHost()))
67
79
->setProtocol($this->getProtocol())
+9
src/infrastructure/cluster/search/PhabricatorMySQLSearchHost.php
+9
src/infrastructure/cluster/search/PhabricatorMySQLSearchHost.php
···
9
9
return $this;
10
10
}
11
11
12
+
/**
13
+
* @return string Display name of the search host: "MySQL"
14
+
*/
12
15
public function getDisplayName() {
13
16
return 'MySQL';
14
17
}
15
18
19
+
/**
20
+
* @return string[] Get a list of fields to show in the status overview UI
21
+
*/
16
22
public function getStatusViewColumns() {
17
23
return array(
18
24
pht('Protocol') => 'mysql',
···
20
26
);
21
27
}
22
28
29
+
/**
30
+
* @return string Search host protocol: "mysql"
31
+
*/
23
32
public function getProtocol() {
24
33
return 'mysql';
25
34
}
+19
src/infrastructure/cluster/search/PhabricatorSearchService.php
+19
src/infrastructure/cluster/search/PhabricatorSearchService.php
···
26
26
27
27
/**
28
28
* @throws Exception
29
+
* @return PhabricatorSearchHost An instance of a subclass of
30
+
* PhabricatorSearchHost
29
31
*/
30
32
public function newHost($config) {
31
33
$host = clone($this->hostType);
···
35
37
return $host;
36
38
}
37
39
40
+
/**
41
+
* @return PhabricatorFulltextStorageEngine A subclass of
42
+
* PhabricatorFulltextStorageEngine
43
+
*/
38
44
public function getEngine() {
39
45
return $this->engine;
40
46
}
41
47
48
+
/**
49
+
* @return string Display name of the search host, e.g. "MySQL"
50
+
*/
42
51
public function getDisplayName() {
43
52
return $this->hostType->getDisplayName();
44
53
}
45
54
55
+
/**
56
+
* @return string[] Get a list of fields to show in the status overview UI
57
+
*/
46
58
public function getStatusViewColumns() {
47
59
return $this->hostType->getStatusViewColumns();
48
60
}
···
66
78
67
79
}
68
80
81
+
/**
82
+
* @return string[]
83
+
*/
69
84
public function getConfig() {
70
85
return $this->config;
71
86
}
···
249
264
return $result_set->getPHIDs();
250
265
}
251
266
267
+
/**
268
+
* @param PhabricatorSavedQuery $query
269
+
* @return PhabricatorFulltextResultSet
270
+
*/
252
271
public static function newResultSet(PhabricatorSavedQuery $query) {
253
272
$exceptions = array();
254
273
// try all services until one succeeds