Skip to content

Commit 6ac80f0

Browse files
ddebinddebin
committed
Adds more PHPDoc
1 parent 8fc2887 commit 6ac80f0

File tree

10 files changed

+61
-57
lines changed

10 files changed

+61
-57
lines changed

‎.github/workflows/main.yml

Lines changed: 7 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,18 @@
11
name: CI
22

33
on:
4-
push:
5-
branches: [ master, dev ]
6-
pull_request:
7-
branches: [ master, dev ]
4+
- push
5+
- pull_request
86

97
jobs:
108
tests:
11-
runs-on: ubuntu-latest
9+
runs-on: ubuntu-22.04
1210
strategy:
1311
matrix:
1412
php: ['7.1', '7.2', '7.3', '7.4', '8.0', '8.1']
15-
name: PHP ${{ matrix.php }} tests
13+
name: PHP ${{ matrix.php }}
1614
steps:
17-
- uses: actions/checkout@v2
15+
- uses: actions/checkout@v3
1816
# required for "git tag" presence for MonorepoBuilder split and ChangelogLinker git tags resolver; default is 1
1917
- run: git fetch --depth=100000 origin
2018
# see https://github.com/shivammathur/setup-php
@@ -27,9 +25,9 @@ jobs:
2725
- run: composer phpunit
2826

2927
tests_lowest_dependencies:
30-
runs-on: ubuntu-latest
28+
runs-on: ubuntu-22.04
3129
steps:
32-
- uses: actions/checkout@v2
30+
- uses: actions/checkout@v3
3331
- run: git fetch --depth=100000 origin
3432
# see https://github.com/shivammathur/setup-php
3533
- uses: shivammathur/setup-php@v2

‎.php-cs-fixer.php

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,12 +8,7 @@
88
->in(__DIR__)
99
;
1010

11-
12-
$finder = PhpCsFixer\Finder::create()
13-
->exclude('vendor')
14-
->in(__DIR__);
15-
16-
$config = new PhpCsFixer\Config();
11+
$config = new Config();
1712
return $config->setRules([
1813
'@PhpCsFixer' => true,
1914
'@PhpCsFixer:risky' => true,

‎composer.json

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -47,9 +47,9 @@
4747
}
4848
},
4949
"scripts": {
50-
"phpstan": "phpstan analyse -l max lib tests",
51-
"php-cs-fixer": "php-cs-fixer fix --allow-risky=yes",
52-
"php-cs-fixer-dry-run": "php-cs-fixer fix --dry-run --allow-risky=yes",
53-
"phpunit": "phpunit"
50+
"phpstan": "@php phpstan analyse -l max lib tests examples .php-cs-fixer.php",
51+
"php-cs-fixer": "@php php-cs-fixer fix --allow-risky=yes",
52+
"php-cs-fixer-dry-run": "@php php-cs-fixer fix --dry-run --allow-risky=yes",
53+
"phpunit": "@php phpunit"
5454
}
5555
}

‎examples/callback_fields.php

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,7 @@
88

99
require_once __DIR__.'/../vendor/autoload.php';
1010

11-
/**
12-
* @param mixed $row
13-
*/
14-
function most_common($row): ?string
11+
function most_common(array $row): ?string
1512
{
1613
$forms = ['pill', 'iud', 'condom', 'sterile_total', 'other_modern', 'traditional'];
1714
$maxForm = -1;
@@ -40,7 +37,7 @@ function most_common($row): ?string
4037
'condom' => ['field' => 'condom', 'type' => 'number'],
4138
'sterile_total' => ['field' => 'steril_total', 'type' => 'number'],
4239
'other_modern' => ['field' => 'other_modern', 'type' => 'number'],
43-
'traditional' => ['field' => 'traditional', 'type' => 'number'],
40+
'traditional' => ['field' => 'traditional', 'type' => 'number'],
4441
'most_common' => [
4542
'callback' => 'most_common',
4643
'fields' => ['pill', 'iud', 'condom', 'sterile_total', 'other_modern', 'traditional'],
@@ -51,7 +48,7 @@ function most_common($row): ?string
5148
]);
5249

5350
$vis->handleRequest();
54-
exit();
51+
exit;
5552
}
5653
?>
5754
<html lang="en">

‎examples/complete.php

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@
3434
$vis->setDefaultEntity('timeline');
3535

3636
$vis->handleRequest();
37-
exit();
37+
exit;
3838
}
3939
?>
4040
<html lang="en">

‎examples/joins.php

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@
3131
]);
3232

3333
$vis->handleRequest();
34-
exit();
34+
exit;
3535
}
3636
?>
3737
<html lang="en">

‎examples/simple.php

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121
]);
2222

2323
$vis->handleRequest();
24-
exit();
24+
exit;
2525
}
2626
?>
2727
<html>

‎lib/MC/Google/Visualization.php

Lines changed: 37 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,8 @@
2121
* Visualizations can be found here: http://code.google.com/apis/visualization/documentation/querylanguage.html.
2222
*
2323
* @see \Tests\VisualizationTest
24+
*
25+
* @phpstan-type FieldSpec array{callback?:callable,field?:string,extra?:array,fields?:string[],sort_field?:string,type?:string,join?:string}
2426
*/
2527
class Visualization
2628
{
@@ -82,9 +84,11 @@ class Visualization
8284
* @param null|PDO $db the database connection to use
8385
* @param string $dialect the SQL dialect to use - one of "mysql", "postgres", or "sqlite"
8486
*
87+
* @phpstan-param 'mysql'|'postgres'|'sqlite' $dialect
88+
*
8589
* @throws Visualization_Error
8690
*/
87-
public function __construct(PDO $db = null, string $dialect = 'mysql')
91+
public function __construct(?PDO $db = null, string $dialect = 'mysql')
8892
{
8993
if (!function_exists('json_encode')) {
9094
throw new Visualization_Error('You must include the PHP json extension installed to use the MC Google Visualization Server');
@@ -99,7 +103,7 @@ public function __construct(PDO $db = null, string $dialect = 'mysql')
99103
*
100104
* @param null|PDO $db the database connection to use - or null if you want to handle your own queries
101105
*/
102-
public function setDB(PDO $db = null): void
106+
public function setDB(?PDO $db = null): void
103107
{
104108
if (null !== $db) {
105109
$db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
@@ -113,6 +117,8 @@ public function setDB(PDO $db = null): void
113117
*
114118
* @param string $dialect one of "mysql", "postgres", or "sqlite"
115119
*
120+
* @phpstan-param 'mysql'|'postgres'|'sqlite' $dialect
121+
*
116122
* @throws Visualization_Error
117123
*/
118124
public function setSqlDialect(string $dialect): void
@@ -127,7 +133,10 @@ public function setSqlDialect(string $dialect): void
127133
/**
128134
* Change the default format string to use for a particular data type.
129135
*
130-
* @param string $type the data type to change - one of "date", "datetime", "time", "boolean", or "number"
136+
* @param string $type the data type to change - one of "date", "datetime", "time", "boolean", or "number"
137+
*
138+
* @phpstan-param 'date'|'datetime'|'time'|'boolean'|'number' $type
139+
*
131140
* @param string $format the format string to use for the data type
132141
*
133142
* @throws Visualization_Error
@@ -150,11 +159,11 @@ public function setDefaultFormat(string $type, string $format): void
150159
* @param bool $echo print response and set header
151160
* @param null|array $queryParams query parameters
152161
*
153-
* @throws Visualization_Error
154-
*
155162
* @return string the javascript response
163+
*
164+
* @throws Visualization_Error
156165
*/
157-
public function handleRequest(bool $echo = true, array $queryParams = null): string
166+
public function handleRequest(bool $echo = true, ?array $queryParams = null): string
158167
{
159168
if (null === $queryParams) {
160169
$queryParams = $_GET;
@@ -201,7 +210,7 @@ public function handleQuery(string $query, array $params): string
201210
$response = '';
202211

203212
try {
204-
if (!($this->db instanceof PDO)) {
213+
if (!$this->db instanceof PDO) {
205214
throw new Visualization_Error('You must pass a PDO connection to the MC Google Visualization Server if you want to let the server handle the entire request');
206215
}
207216

@@ -244,10 +253,10 @@ public function handleQuery(string $query, array $params): string
244253
*
245254
* @param array $query the visualization query broken up into sections
246255
*
256+
* @return array the metadata array from merging the query with the entity table definitions
257+
*
247258
* @throws Visualization_QueryError
248259
* @throws Visualization_Error
249-
*
250-
* @return array the metadata array from merging the query with the entity table definitions
251260
*/
252261
public function generateMetadata(array $query): array
253262
{
@@ -410,6 +419,8 @@ public function generateMetadata(array $query): array
410419
* @param string $name the name of the entity - should be used in the "from" clause of visualization queries
411420
* @param array $spec optional spec array with keys "fields", "joins", "table", and "where" to define the mapping between visualization queries and SQL queries
412421
*
422+
* @phpstan-param array{table?: string, fields?: array<string, FieldSpec>, joins?: array<string, string>, where?: string} $spec
423+
*
413424
* @throws Visualization_Error
414425
*/
415426
public function addEntity(string $name, array $spec = []): void
@@ -441,7 +452,7 @@ public function addEntity(string $name, array $spec = []): void
441452
*
442453
* @throws Visualization_Error
443454
*/
444-
public function setDefaultEntity(string $default = null): void
455+
public function setDefaultEntity(?string $default = null): void
445456
{
446457
if (null !== $default && !isset($this->entities[$default])) {
447458
throw new Visualization_Error('No entity exists with name "'.$default.'"');
@@ -456,9 +467,9 @@ public function setDefaultEntity(string $default = null): void
456467
* @param array $row the row values as an array
457468
* @param array $meta the metadata for the query (use generateMetadata())
458469
*
459-
* @throws Visualization_Error
460-
*
461470
* @return string the string fragment to include in the results back to the javascript client
471+
*
472+
* @throws Visualization_Error
462473
*/
463474
public function getRowValues(array $row, array $meta): string
464475
{
@@ -510,8 +521,8 @@ public function getRowValues(array $row, array $meta): string
510521
$val = (float) $val;
511522
if (1 === preg_match('#^num:(\d+)(.*)$#i', $format, $matches)) {
512523
$digits = (int) $matches[1];
513-
$extras = $matches[2];
514-
if (is_array($extras) && (2 === count($extras))) {
524+
$extras = str_split($matches[2]);
525+
if (2 === count($extras)) {
515526
$formatted = number_format($val, $digits, $extras[0], $extras[1]);
516527
} else {
517528
$formatted = number_format($val, $digits);
@@ -605,12 +616,12 @@ public function getRowValues(array $row, array $meta): string
605616
*
606617
* @param string $query the visualization query to run
607618
*
619+
* @return string the SQL that should be sent to the database
620+
*
608621
* @throws Visualization_QueryError
609622
* @throws Visualization_Error
610623
* @throws ParseError
611624
* @throws DefError
612-
*
613-
* @return string the SQL that should be sent to the database
614625
*/
615626
public function getSQL(string $query): string
616627
{
@@ -623,9 +634,9 @@ public function getSQL(string $query): string
623634
/**
624635
* Use MC_Parser to generate a grammar that matches the query language specified here: http://code.google.com/apis/visualization/documentation/querylanguage.html.
625636
*
626-
* @throws DefError
627-
*
628637
* @return Def the grammar for the query language
638+
*
639+
* @throws DefError
629640
*/
630641
public function getGrammar(): Def
631642
{
@@ -693,11 +704,11 @@ public function getGrammar(): Def
693704
*
694705
* @param string $str the query string to parse
695706
*
707+
* @return array the parsed query as an array, keyed by each part of the query (select, from, where, groupby, pivot, orderby, limit, offset, label, format, options
708+
*
696709
* @throws ParseError
697710
* @throws Visualization_QueryError
698711
* @throws Parser\DefError
699-
*
700-
* @return array the parsed query as an array, keyed by each part of the query (select, from, where, groupby, pivot, orderby, limit, offset, label, format, options
701712
*/
702713
public function parseQuery(string $str): array
703714
{
@@ -857,6 +868,8 @@ protected function handleError(int $reqid, string $detailMsg, string $handler =
857868
* @param string $field the name of the field
858869
* @param array $spec the metadata for the field as a set of key-value pairs - allowed keys are "field", "callback", "fields", "extra", "sort_field", "type", and "join"
859870
*
871+
* @phpstan-param FieldSpec $spec
872+
*
860873
* @throws Visualization_Error
861874
*/
862875
protected function addEntityField(string $entity, string $field, array $spec): void
@@ -916,9 +929,9 @@ protected function setEntityWhere(string $entity, string $where): void
916929
*
917930
* @param array $meta the results of generateMetadata() on the parsed visualization query
918931
*
919-
* @throws Visualization_QueryError
920-
*
921932
* @return string the SQL version of the visualization query
933+
*
934+
* @throws Visualization_QueryError
922935
*/
923936
protected function generateSQL(array &$meta): string
924937
{
@@ -1083,9 +1096,9 @@ protected function generateSQL(array &$meta): string
10831096
*
10841097
* @param array $meta the metadata for the query - generally generated by MC_Google_Visualization::generateMetadata
10851098
*
1086-
* @throws Visualization_Error
1087-
*
10881099
* @return string the initial output string for a successful query
1100+
*
1101+
* @throws Visualization_Error
10891102
*/
10901103
protected function getSuccessInit(array $meta): string
10911104
{

‎lib/MC/Parser/Def.php

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -38,9 +38,9 @@ public function parse(string $str): Token
3838
/**
3939
* Parse a string, cleaning up whitespace when we're done.
4040
*
41-
* @throws ParseError
42-
*
4341
* @return array A two-item array of the string location where parsing stopped, and the MC_Token instance that matches the grammar conditions
42+
*
43+
* @throws ParseError
4444
*/
4545
public function parsePart(string $str, int $loc): array
4646
{
@@ -61,9 +61,9 @@ public function parsePart(string $str, int $loc): array
6161
* @param string $str the string to parse
6262
* @param int $loc the index to start parsing
6363
*
64-
* @throws ParseError
65-
*
6664
* @return array A two-item array of the string location where parsing stopped, and the MC_Token instance that matches the grammar conditions
65+
*
66+
* @throws ParseError
6767
*/
6868
abstract public function _parse(string $str, int $loc): array;
6969

‎phpstan.neon

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,5 @@ includes:
44
- vendor/phpstan/phpstan-strict-rules/rules.neon
55
parameters:
66
checkMissingIterableValueType: false
7-
reportUnmatchedIgnoredErrors: false
7+
reportUnmatchedIgnoredErrors: false
8+
treatPhpDocTypesAsCertain: false

0 commit comments

Comments
 (0)