Skip to content

Commit 4c03a43

Browse files
stklcodestklcode
committed
docs: extend PHPDocs and fix some minor code style issues
1 parent c85b6cd commit 4c03a43

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

65 files changed

+1929
-106
lines changed

‎src/Admin/CommentsColumns.php

+2-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
/**
33
* Class registering columns for the "spam comments view".
44
*
5-
* @package AntispamBee\Helpers
5+
* @package AntispamBee\Admin
66
*/
77

88
namespace AntispamBee\Admin;
@@ -93,6 +93,7 @@ public static function print_plugin_column( $column, $comment_id ) {
9393
$reasons = explode( ',', $spam_reason );
9494
$reason_texts = SpamReasonTextHelper::get_texts_by_slugs( $reasons );
9595

96+
// phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- reason texts pre-sanitized.
9697
echo implode( ',<br>', $reason_texts );
9798
}
9899

‎src/Admin/DashboardWidgets.php

+6
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,12 @@ private static function get_spam_count() {
7474
return self::format_number( $count );
7575
}
7676

77+
/**
78+
* Format a number.
79+
*
80+
* @param float $number Number to format.
81+
* @return string
82+
*/
7783
private static function format_number( $number ) {
7884
return ( get_locale() === 'de_DE' ? number_format( $number, 0, '', '.' ) : number_format_i18n( $number ) );
7985
}

‎src/Admin/Fields/Checkbox.php

+2
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,8 @@ class Checkbox extends Field implements RenderElement {
1717
* Get HTML.
1818
*/
1919
public function render() {
20+
// phpcs:disable WordPress.Security.EscapeOutput.OutputNotEscaped
21+
2022
$label = ! empty( $this->get_label() ) ? sprintf(
2123
'<label for="%s">%s</label>',
2224
esc_attr( $this->get_name() ),

‎src/Admin/Fields/CheckboxGroup.php

+10-1
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,25 @@
11
<?php
2+
/**
3+
* The Checkbox Field group for the admin UI.
4+
*
5+
* @package AntispamBee\Admin\Fields
6+
*/
27

38
namespace AntispamBee\Admin\Fields;
49

510
use AntispamBee\Admin\RenderElement;
611
use AntispamBee\Helpers\Settings;
712

813
/**
9-
* Checkbox field.
14+
* Checkbox group.
1015
*/
1116
class CheckboxGroup extends Field implements RenderElement {
1217
/**
1318
* Render HTML.
1419
*/
1520
public function render() {
21+
// phpcs:disable WordPress.Security.EscapeOutput.OutputNotEscaped
22+
1623
$options = isset( $this->option['options'] ) ? $this->option['options'] : [];
1724
if ( ! is_array( $options ) ) {
1825
return;
@@ -38,6 +45,8 @@ public function render() {
3845
/**
3946
* Get Value.
4047
*
48+
* @param string $key Option key.
49+
*
4150
* @return mixed Value stored in database.
4251
*/
4352
protected function get_custom_value( $key ) {

‎src/Admin/Fields/Field.php

+3-1
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,8 @@ abstract class Field {
3030

3131
/**
3232
* Type of controllable.
33+
*
34+
* @var string
3335
*/
3436
protected $controllable_option_name;
3537

@@ -123,7 +125,7 @@ protected function maybe_show_description() {
123125
/**
124126
* Get HTML for field.
125127
*
126-
* @return string Elment HTML.
128+
* @return string Element HTML.
127129
*/
128130
abstract public function render();
129131
}

‎src/Admin/Fields/Inline.php

+15
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,27 @@
11
<?php
2+
/**
3+
* The inline input field for the admin UI.
4+
*
5+
* @package AntispamBee\Admin\Fields
6+
*/
27

38
namespace AntispamBee\Admin\Fields;
49

510
use AntispamBee\Admin\RenderElement;
611

12+
/**
13+
* Inline input field.
14+
*/
715
class Inline extends Field implements RenderElement {
816

17+
/**
18+
* Get HTML for field.
19+
*
20+
* @return string Element HTML.
21+
*/
922
public function render() {
23+
// phpcs:disable WordPress.Security.EscapeOutput.OutputNotEscaped
24+
1025
if ( ! $this->option['input'] instanceof Field ) {
1126
echo '';
1227

‎src/Admin/Fields/Select.php

+7
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,9 @@
11
<?php
2+
/**
3+
* The Select Field for the admin UI.
4+
*
5+
* @package AntispamBee\Admin\Fields
6+
*/
27

38
namespace AntispamBee\Admin\Fields;
49

@@ -13,6 +18,8 @@ class Select extends Field implements RenderElement {
1318
* Get HTML.
1419
*/
1520
public function render() {
21+
// phpcs:disable WordPress.Security.EscapeOutput.OutputNotEscaped
22+
1623
$name = $this->get_name();
1724
$multiple = isset( $this->option['multiple'] ) && $this->option['multiple'] ? 'multiple' : '';
1825
echo "<select name='$name' $multiple>";

‎src/Admin/Fields/Text.php

+27
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,18 @@
1414
*/
1515
class Text extends Field implements RenderElement {
1616

17+
/**
18+
* Placeholder string.
19+
*
20+
* @var string
21+
*/
1722
protected $placeholder;
1823

24+
/**
25+
* Get placeholder.
26+
*
27+
* @return string
28+
*/
1929
public function get_placeholder() {
2030
return $this->placeholder;
2131
}
@@ -24,6 +34,8 @@ public function get_placeholder() {
2434
* Get HTML.
2535
*/
2636
public function render() {
37+
// phpcs:disable WordPress.Security.EscapeOutput.OutputNotEscaped
38+
2739
printf(
2840
'<p><label for="%s">%s</label></p><p>%s</p>',
2941
esc_attr( $this->get_name() ),
@@ -33,6 +45,11 @@ public function render() {
3345
$this->maybe_show_description();
3446
}
3547

48+
/**
49+
* Get HTML markup for the actual input field.
50+
*
51+
* @return string
52+
*/
3653
public function get_injectable_markup() {
3754
return sprintf(
3855
'<input type="%1$s" id="%2$s" name="%2$s" value="%3$s" class="%4$s" placeholder="%5$s">',
@@ -44,6 +61,11 @@ public function get_injectable_markup() {
4461
);
4562
}
4663

64+
/**
65+
* Get element class(es).
66+
*
67+
* @return string
68+
*/
4769
protected function get_class() {
4870
$classes = [
4971
'small' => 'small-text',
@@ -58,6 +80,11 @@ protected function get_class() {
5880
return 'regular-text';
5981
}
6082

83+
/**
84+
* Get type of input field.
85+
*
86+
* @return string
87+
*/
6188
protected function get_type() {
6289
return isset( $this->option['input_type'] ) ? $this->option['input_type'] : 'text';
6390
}

‎src/Admin/Fields/Textarea.php

+2
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,8 @@ class Textarea extends Field implements RenderElement {
1717
* Render HTML.
1818
*/
1919
public function render() {
20+
// phpcs:disable WordPress.Security.EscapeOutput.OutputNotEscaped
21+
2022
printf(
2123
'<p><label for="%1$s">%2$s</label></p><p><textarea name="%1$s" id="%1$s" placeholder="%4$s">%3$s</textarea></p>',
2224
esc_attr( $this->get_name() ),

‎src/Admin/Section.php

+22-8
Original file line numberDiff line numberDiff line change
@@ -55,11 +55,6 @@ class Section {
5555
*/
5656
private $type;
5757

58-
/**
59-
*
60-
* @var Controllable[]
61-
*/
62-
private $controllables;
6358

6459
/**
6560
* Initializing Tab.
@@ -76,12 +71,24 @@ public function __construct( $slug, $title, $description = '', $type = null ) {
7671
$this->type = $type;
7772
}
7873

74+
/**
75+
* Add controllable items to section.
76+
*
77+
* @param array|null $controllables List of controllable items to add.
78+
* @return void
79+
*/
7980
public function add_controllables( $controllables ) {
8081
if ( ! empty( $controllables ) ) {
8182
$this->generate_fields( $controllables );
8283
}
8384
}
8485

86+
/**
87+
* Generate settings fields for a list of controllable items.
88+
*
89+
* @param Controllable[] $controllables List of controllable items to add.
90+
* @return void
91+
*/
8592
private function generate_fields( $controllables ) {
8693
foreach ( $controllables as $controllable ) {
8794
$label = $controllable::get_label();
@@ -103,7 +110,7 @@ private function generate_fields( $controllables ) {
103110
if ( ! empty( $options ) ) {
104111
foreach ( $options as $option ) {
105112
$valid_for = isset( $option['valid_for'] ) ? $option['valid_for'] : null;
106-
if ( $valid_for !== null && $this->type !== $valid_for ) {
113+
if ( null !== $valid_for && $this->type !== $valid_for ) {
107114
continue;
108115
}
109116
$fields[] = $this->generate_field( $option, $controllable );
@@ -117,6 +124,13 @@ private function generate_fields( $controllables ) {
117124
}
118125
}
119126

127+
/**
128+
* Generate field for a controllable item's option.
129+
*
130+
* @param array $option Option name.
131+
* @param Controllable $controllable Controllable item.
132+
* @return Checkbox|CheckboxGroup|Inline|Select|Text|Textarea|null
133+
*/
120134
private function generate_field( $option, $controllable ) {
121135
switch ( $option['type'] ) {
122136
case 'input':
@@ -215,14 +229,14 @@ function () use ( $row ) {
215229
/**
216230
* Renders the fields for a row.
217231
*
218-
* @param array $row
232+
* @param array $row Row of fields.
219233
*/
220234
protected function render_row_fields( $row ) {
221235
foreach ( $row['fields'] as $key => $field ) {
222236
$field->render();
223237

224238
// Add linebreak after field if not (last and not checkbox without label).
225-
if ( $key !== count( $row['fields'] ) - 1 ) {
239+
if ( ( count( $row['fields'] ) - 1 ) !== $key ) {
226240
if ( $field instanceof Checkbox && empty( $field->get_label() ) ) {
227241
continue;
228242
}

‎src/Admin/SettingsPage.php

+15-4
Original file line numberDiff line numberDiff line change
@@ -35,11 +35,15 @@ class SettingsPage {
3535
private $tabs = [];
3636

3737
/**
38+
* List of controllable rules.
39+
*
3840
* @var Rules[]
3941
*/
4042
private $rules = [];
4143

4244
/**
45+
* List of controllable post processors
46+
*
4347
* @var PostProcessors[]
4448
*/
4549
private $post_processors = [];
@@ -59,7 +63,7 @@ public function init() {
5963
add_action( 'admin_init', [ $this, 'setup_settings' ] );
6064

6165
// phpcs:ignore WordPress.Security.NonceVerification.Recommended
62-
$this->active_tab = isset( $_GET['tab'] ) ? $_GET['tab'] : 'general';
66+
$this->active_tab = isset( $_GET['tab'] ) ? sanitize_key( wp_unslash( $_GET['tab'] ) ) : 'general';
6367
}
6468

6569
/**
@@ -79,14 +83,16 @@ public function add_menu() {
7983
* Setup tabs content.
8084
*/
8185
public function setup_settings() {
82-
// Todo: Add a way to build rows and fields with a fluent interface? (Nice-to-have)
86+
// Todo: Add a way to build rows and fields with a fluent interface? (Nice-to-have).
87+
8388
/*
8489
* Todo: Instead of using an array to pass options to a function, one could introduce a class that contains
8590
* these options as class attributes. You instantiate an object of this class and pass it to the
8691
* Components::filter() method. For frequently used options, one could also use blueprints for options.
8792
* This would make refactoring easier, but would slightly increase the complexity. (nice-to-have).
8893
*/
89-
// Todo: Fix the confusing naming. We have a lot of type e.g. (Nice-to-have)
94+
95+
// Todo: Fix the confusing naming. We have a lot of type e.g. (Nice-to-have).
9096

9197
$tabs['general'] = new Tab(
9298
'general',
@@ -114,7 +120,7 @@ public function setup_settings() {
114120

115121
$this->populate_tabs();
116122

117-
// Register option setting
123+
// Register option setting.
118124
foreach ( $this->tabs as $tab ) {
119125
foreach ( $tab->get_sections() as $section ) {
120126
if ( $tab->get_slug() !== $this->active_tab ) {
@@ -134,6 +140,11 @@ public function setup_settings() {
134140
);
135141
}
136142

143+
/**
144+
* Populate settings tabs.
145+
*
146+
* @return void
147+
*/
137148
protected function populate_tabs() {
138149
$type = $this->active_tab;
139150

‎src/Admin/Tab.php

+13-2
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,9 @@
11
<?php
2+
/**
3+
* Settings tab model.
4+
*
5+
* @package AntispamBee\Admin
6+
*/
27

38
namespace AntispamBee\Admin;
49

@@ -30,8 +35,8 @@ class Tab {
3035
/**
3136
* Initialize the tab.
3237
*
33-
* @param string $slug Title for tab
34-
* @param string $title Title for tab
38+
* @param string $slug Title for tab.
39+
* @param string $title Title for tab.
3540
* @param Section[] $sections Sections object array.
3641
*/
3742
public function __construct( $slug, $title, $sections = [] ) {
@@ -67,6 +72,12 @@ public function get_sections() {
6772
return $this->sections;
6873
}
6974

75+
/**
76+
* Add a section to the settings tab.
77+
*
78+
* @param Section $section Section to add.
79+
* @return void
80+
*/
7081
public function add_section( Section $section ) {
7182
$this->sections[] = $section;
7283
}

0 commit comments

Comments
 (0)