Skip to content

Commit 716a8af

Browse files
edgebaledgebal
committed
(doc): classes and methods annotations, and small tweaks
\Helpers
1 parent e08c694 commit 716a8af

File tree

11 files changed

+186
-98
lines changed

11 files changed

+186
-98
lines changed

‎Helpers/Analytics.php

Lines changed: 16 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -5,16 +5,17 @@
55
use Minds\Core\Data;
66

77
/**
8-
* A helper class to provide request metrics
8+
* Helper to provide request metrics
9+
* @todo Avoid static and use proper DI
910
*/
1011
class Analytics
1112
{
1213
/**
1314
* Get MAU or DAU
14-
* @param $metric
15-
* @param $reference - eg. daily, monthly
16-
* @param int $ts
17-
* @return int - the count
15+
* @param string $metric
16+
* @param string $reference - eg. daily, monthly
17+
* @param int $ts - timestamp
18+
* @return int
1819
*/
1920
public static function get($metric = "active", $reference = "day", $ts = null)
2021
{
@@ -24,7 +25,11 @@ public static function get($metric = "active", $reference = "day", $ts = null)
2425
}
2526

2627
/**
27-
* @return void
28+
* Increments a metric
29+
* @param string $metric
30+
* @param int $ts - timestamp
31+
* @param mixed|null $user_guid - acting user. Null for current.
32+
* @return null
2833
*/
2934
public static function increment($metric = "active", $ts = null, $user_guid = null)
3035
{
@@ -39,7 +44,11 @@ public static function increment($metric = "active", $ts = null, $user_guid = nu
3944
}
4045

4146
/**
42-
* Get timestamp to nearest 5 minutes
47+
* Gets a timestamp based on a string, and optionally on the
48+
* passed timestamp.
49+
* @param string $reference
50+
* @param int|null $ts - timestamp. Null for current time.
51+
* @return int
4352
*/
4453
public static function buildTS($reference = "day", $ts = null)
4554
{

‎Helpers/Campaigns/DailyRewards.php

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,16 @@
44
use Minds\Core;
55
use Minds\Helpers;
66

7+
/**
8+
* Helper for daily rewards
9+
* @todo Avoid static method and user proper DI.
10+
*/
711
class DailyRewards
812
{
13+
/**
14+
* Grants daily reward and sends notification to current user
15+
* @return boolean|null
16+
*/
917
public static function reward()
1018
{
1119
if (!Core\Session::isLoggedin()) {

‎Helpers/Campaigns/EmailRewards.php

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,18 @@
55
use Minds\Helpers;
66
use Minds\Entities;
77

8+
/**
9+
* Helper for Email Rewards
10+
* @todo Avoid static and use proper DI
11+
*/
812
class EmailRewards
913
{
14+
/**
15+
* Grants an email reward to an user
16+
* @param string $campaign
17+
* @param mixed $user_guid
18+
* @return null
19+
*/
1020
public static function reward($campaign, $user_guid)
1121
{
1222
if (!is_numeric($user_guid)) {

‎Helpers/Counters.php

Lines changed: 31 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,20 @@
11
<?php
2-
/**
3-
* Counters
4-
*/
52
namespace Minds\Helpers;
63

74
use Minds\Core;
85

6+
/**
7+
* Helper for metric counters
8+
* @todo Avoid static and use proper DI (check $client at methods)
9+
*/
910
class Counters
1011
{
1112
/**
12-
* Increment a count
13-
*
14-
* @param mixed Entity or number - $entity
15-
* @param string $metric
16-
* @param int $value - defaults to 1
13+
* Increment a metric count
14+
* @param Entity|number $entity
15+
* @param string $metric
16+
* @param int $value - Value to increment. Defaults to 1.
17+
* @param Data\Client $client - Database. Defaults to Cassandra.
1718
* @return void
1819
*/
1920
public static function increment($entity, $metric, $value = 1, $client = null)
@@ -42,10 +43,11 @@ public static function increment($entity, $metric, $value = 1, $client = null)
4243
}
4344

4445
/**
45-
* Decrement a count
46-
*
47-
* @param mixed Entity or number - $entity
48-
* @param string $metric
46+
* Decrements a metric count
47+
* @param Entity|number $entity
48+
* @param string $metric
49+
* @param int $value - Value to increment. Defaults to 1.
50+
* @param Data\Client $client - Database. Defaults to Cassandra.
4951
* @return void
5052
*/
5153
public static function decrement($entity, $metric, $value = 1, $client = null)
@@ -70,8 +72,12 @@ public static function decrement($entity, $metric, $value = 1, $client = null)
7072
}
7173

7274
/**
73-
* Increment a batch
74-
* @return $this
75+
* Increment metric count on several entities
76+
* @param array $entities
77+
* @param string $metric
78+
* @param int $value - Value to increment. Defaults to 1.
79+
* @param Data\Client $client - Database. Defaults to Cassandra.
80+
* @return void
7581
*/
7682
public static function incrementBatch($entities, $metric, $value = 1, $client = null)
7783
{
@@ -102,9 +108,11 @@ public static function incrementBatch($entities, $metric, $value = 1, $client =
102108
}
103109

104110
/**
105-
* Return the count for a single entity/metric
106-
* @param mixed Entity or number - $entity
107-
* @param string $metric
111+
* Returns the count for a single metric on an entity
112+
* @param Entity|number $entity
113+
* @param string $metric
114+
* @param boolean $cache - use a cache for result?
115+
* @param Data\Client $client - Database. Defaults to Cassandra.
108116
* @return int
109117
*/
110118
public static function get($entity, $metric, $cache = true, $client = null)
@@ -138,11 +146,12 @@ public static function get($entity, $metric, $cache = true, $client = null)
138146
}
139147

140148
/**
141-
* Reset a counter
142-
* @param mixed - Entity or number $entity
143-
* @param string $metric
144-
* @param int $value (optional)
145-
* @return void;
149+
* Resets a metric counter for an entity
150+
* @param Entity|number $entity
151+
* @param string $metric
152+
* @param number $value - Resetted value. Defaults to 0.
153+
* @param Data\Client $client - Database. Defaults to Cassandra.
154+
* @return int
146155
*/
147156
public static function clear($entity, $metric, $value = 0, $client = null)
148157
{

‎Helpers/Entities.php

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,16 @@
11
<?php
2-
/**
3-
* Entities helper
4-
*/
52
namespace Minds\Helpers;
63

4+
/**
5+
* Helper for entities operations
6+
*/
77
class Entities
88
{
9+
/**
10+
* Builds setter method name for a certain underscore-named field
11+
* @param string $key
12+
* @return string
13+
*/
914
public static function buildSetter($key)
1015
{
1116
$parts = explode('_', $key);
@@ -16,6 +21,11 @@ public static function buildSetter($key)
1621
return $method;
1722
}
1823

24+
/**
25+
* Builds getter method name for a certain underscore-named field
26+
* @param string $key
27+
* @return string
28+
*/
1929
public static function buildGetter($key)
2030
{
2131
$parts = explode('_', $key);

‎Helpers/Export.php

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,15 @@
44
use Minds\Core;
55

66
/**
7-
* Helper for exporting
7+
* Helper for exporting API responses
88
*/
99
class Export
1010
{
11+
/**
12+
* Recursively sanitizes an array of data.
13+
* @param array $array
14+
* @return array
15+
*/
1116
public static function sanitize($array)
1217
{
1318
$return = array();

‎Helpers/OpenSSL.php

Lines changed: 13 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,13 @@
11
<?php
2-
/**
3-
* Minds OpenSSL helper class
4-
*/
5-
62
namespace Minds\Helpers;
73

4+
/**
5+
* Helper for OpenSSL operations
6+
*/
87
class OpenSSL
98
{
109
/**
11-
* Returns a new keypair
12-
*
10+
* Returns a new SSL keypair
1311
* @param string $password
1412
* @return array - Public & Private
1513
*/
@@ -21,48 +19,46 @@ public static function newKeypair($password = null)
2119
"private_key_type" => OPENSSL_KEYTYPE_RSA,
2220
'encrypt_key' => true
2321
);
24-
22+
2523
$res = openssl_pkey_new($config);
26-
24+
2725
//private key
2826
openssl_pkey_export($res, $privKey, $password);
29-
27+
3028
//public key
3129
$pubKey = openssl_pkey_get_details($res);
3230
$pubKey = $pubKey["key"];
33-
31+
3432
return array(
3533
'public' => $pubKey,
3634
'private' => $privKey
3735
);
3836
}
39-
37+
4038
/**
4139
* Encrypts data
42-
*
4340
* @param string $data
4441
* @param string $public_key
4542
* @return string
4643
*/
4744
public static function encrypt($data, $public_key)
4845
{
4946
openssl_public_encrypt($data, $encrypted, $public_key);
50-
47+
5148
return $encrypted;
5249
}
53-
50+
5451
/**
5552
* Decrypt data
56-
*
5753
* @param string $encrypted
5854
* @param string $private_key
59-
* @param string @password - default = ''
55+
* @param string $password - encryption password (secret). Default ''
6056
* @return string
6157
*/
6258
public static function decrypt($encrypted, $private_key, $password = null)
6359
{
6460
openssl_private_decrypt($encrypted, $decrypted, openssl_get_privatekey($private_key, $password));
65-
61+
6662
return $decrypted;
6763
}
6864
}

‎Helpers/RequestMetrics.php

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,17 @@
55
use Minds\Core\Data;
66

77
/**
8-
* A helper class to provide request metrics
8+
* Helper for request metric counters
9+
* @todo Avoid static and use proper DI (check $client at methods)
10+
* @todo Perhaps this can inherit methods from Helpers\Analytics
911
*/
1012
class RequestMetrics
1113
{
1214
private static $namespace = "requestmetrics";
15+
1316
/**
14-
* Increment
15-
* @param $metric
17+
* Increments a request counter metric
18+
* @param $metric
1619
* @return void
1720
*/
1821
public static function increment($metric = "all")
@@ -22,10 +25,10 @@ public static function increment($metric = "all")
2225
}
2326

2427
/**
25-
* Get request metrics
26-
* @param $metric
27-
* @param int $ts
28-
* @return int - the count
28+
* Gets a request metric counter
29+
* @param string $metric
30+
* @param int $ts
31+
* @return int
2932
*/
3033
public static function get($metric = "all", $ts = null)
3134
{
@@ -47,7 +50,9 @@ public static function get($metric = "all", $ts = null)
4750
}
4851

4952
/**
50-
* Get timestamp to nearest 5 minutes
53+
* Gets a 5-minute rounded timestamp
54+
* @param int|null $ts - timestamp. Null for current time.
55+
* @return int
5156
*/
5257
public static function buildTS($ts = null)
5358
{

0 commit comments

Comments
 (0)