Skip to content

Commit 0ce8c45

Browse files
imantskimantsk
committed
phpcs: enhance documentation for Snippet_Files class with detailed PHPDoc comments
1 parent 2966921 commit 0ce8c45

File tree

1 file changed

+209
-1
lines changed

1 file changed

+209
-1
lines changed

‎src/php/flat-files/classes/class-snippet-files.php‎

Lines changed: 209 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,19 +2,47 @@
22

33
namespace Code_Snippets;
44

5+
/**
6+
* Manage file-based snippet execution.
7+
*
8+
* Responsible for writing snippet code to disk, maintaining per-table config indexes,
9+
* and retrieving the active snippet list from those config files.
10+
*/
511
class Snippet_Files {
612

713
/**
814
* Flag file name that indicates flat files are enabled.
915
*/
1016
private const ENABLED_FLAG_FILE = 'flat-files-enabled.flag';
1117

18+
/**
19+
* Snippet handler registry.
20+
*
21+
* @var Snippet_Handler_Registry
22+
*/
1223
private Snippet_Handler_Registry $handler_registry;
1324

25+
/**
26+
* File system adapter.
27+
*
28+
* @var File_System_Interface
29+
*/
1430
private File_System_Interface $fs;
1531

32+
/**
33+
* Config repository.
34+
*
35+
* @var Snippet_Config_Repository_Interface
36+
*/
1637
private Snippet_Config_Repository_Interface $config_repo;
1738

39+
/**
40+
* Constructor.
41+
*
42+
* @param Snippet_Handler_Registry $handler_registry Handler registry instance.
43+
* @param File_System_Interface $fs File system adapter.
44+
* @param Snippet_Config_Repository_Interface $config_repo Config repository instance.
45+
*/
1846
public function __construct(
1947
Snippet_Handler_Registry $handler_registry,
2048
File_System_Interface $fs,
@@ -36,10 +64,22 @@ public static function is_active(): bool {
3664
return file_exists( $flag_file_path );
3765
}
3866

67+
/**
68+
* Get the full path to the flat-file enabled flag.
69+
*
70+
* @return string
71+
*/
3972
private static function get_flag_file_path(): string {
4073
return self::get_base_dir() . '/' . self::ENABLED_FLAG_FILE;
4174
}
4275

76+
/**
77+
* Create or delete the enabled flag file.
78+
*
79+
* @param bool $enabled Whether file-based execution is enabled.
80+
*
81+
* @return void
82+
*/
4383
private function handle_enabled_file_flag( bool $enabled ): void {
4484
$flag_file_path = self::get_flag_file_path();
4585

@@ -53,6 +93,11 @@ private function handle_enabled_file_flag( bool $enabled ): void {
5393
}
5494
}
5595

96+
/**
97+
* Register WordPress hooks used by file-based execution.
98+
*
99+
* @return void
100+
*/
56101
public function register_hooks(): void {
57102
if ( ! $this->fs->is_writable( WP_CONTENT_DIR ) ) {
58103
return;
@@ -75,13 +120,29 @@ public function register_hooks(): void {
75120
add_action( 'code_snippets/settings_updated', [ $this, 'create_all_flat_files' ], 10, 2 );
76121
}
77122

123+
/**
124+
* Activate multiple snippets and regenerate their flat files.
125+
*
126+
* @param Snippet[] $valid_snippets Snippets to activate.
127+
* @param string $table Table name.
128+
*
129+
* @return void
130+
*/
78131
public function activate_snippets( $valid_snippets, $table ): void {
79132
foreach ( $valid_snippets as $snippet ) {
80133
$snippet->active = true;
81134
$this->handle_snippet( $snippet, $table );
82135
}
83136
}
84137

138+
/**
139+
* Write a snippet file and update its config index entry.
140+
*
141+
* @param Snippet $snippet Snippet object.
142+
* @param string $table Table name.
143+
*
144+
* @return void
145+
*/
85146
public function handle_snippet( Snippet $snippet, string $table ): void {
86147
if ( 0 === $snippet->id ) {
87148
return;
@@ -106,6 +167,14 @@ public function handle_snippet( Snippet $snippet, string $table ): void {
106167
$this->config_repo->update( $base_dir, $snippet );
107168
}
108169

170+
/**
171+
* Delete a snippet file and remove it from the config index.
172+
*
173+
* @param Snippet $snippet Snippet object.
174+
* @param bool $network Whether the snippet is network-wide.
175+
*
176+
* @return void
177+
*/
109178
public function delete_snippet( Snippet $snippet, bool $network ): void {
110179
$handler = $this->handler_registry->get_handler( $snippet->type );
111180

@@ -122,6 +191,13 @@ public function delete_snippet( Snippet $snippet, bool $network ): void {
122191
$this->config_repo->update( $base_dir, $snippet, true );
123192
}
124193

194+
/**
195+
* Activate a snippet by writing its code file and updating config.
196+
*
197+
* @param Snippet $snippet Snippet object.
198+
*
199+
* @return void
200+
*/
125201
public function activate_snippet( Snippet $snippet ): void {
126202
$snippet = get_snippet( $snippet->id, $snippet->network );
127203
$handler = $this->handler_registry->get_handler( $snippet->type );
@@ -144,6 +220,14 @@ public function activate_snippet( Snippet $snippet ): void {
144220
$this->config_repo->update( $base_dir, $snippet );
145221
}
146222

223+
/**
224+
* Deactivate a snippet by updating its config entry.
225+
*
226+
* @param int $snippet_id Snippet ID.
227+
* @param bool $network Whether the snippet is network-wide.
228+
*
229+
* @return void
230+
*/
147231
public function deactivate_snippet( int $snippet_id, bool $network ): void {
148232
$snippet = get_snippet( $snippet_id, $network );
149233
$handler = $this->handler_registry->get_handler( $snippet->type );
@@ -158,6 +242,14 @@ public function deactivate_snippet( int $snippet_id, bool $network ): void {
158242
$this->config_repo->update( $base_dir, $snippet );
159243
}
160244

245+
/**
246+
* Get the base directory for flat files.
247+
*
248+
* @param string $table Optional hashed table name.
249+
* @param string $snippet_type Optional snippet type directory.
250+
*
251+
* @return string
252+
*/
161253
public static function get_base_dir( string $table = '', string $snippet_type = '' ): string {
162254
$base_dir = WP_CONTENT_DIR . '/code-snippets';
163255

@@ -172,6 +264,14 @@ public static function get_base_dir( string $table = '', string $snippet_type =
172264
return $base_dir;
173265
}
174266

267+
/**
268+
* Get the base URL for flat files.
269+
*
270+
* @param string $table Optional hashed table name.
271+
* @param string $snippet_type Optional snippet type directory.
272+
*
273+
* @return string
274+
*/
175275
public static function get_base_url( string $table = '', string $snippet_type = '' ): string {
176276
$base_url = WP_CONTENT_URL . '/code-snippets';
177277

@@ -186,6 +286,13 @@ public static function get_base_url( string $table = '', string $snippet_type =
186286
return $base_url;
187287
}
188288

289+
/**
290+
* Create a directory if it does not exist.
291+
*
292+
* @param string $dir Directory path.
293+
*
294+
* @return void
295+
*/
189296
private function maybe_create_directory( string $dir ): void {
190297
if ( ! $this->fs->is_dir( $dir ) ) {
191298
$result = wp_mkdir_p( $dir );
@@ -196,16 +303,41 @@ private function maybe_create_directory( string $dir ): void {
196303
}
197304
}
198305

306+
/**
307+
* Build the file path for a snippet's code file.
308+
*
309+
* @param string $base_dir Base directory path.
310+
* @param int $snippet_id Snippet ID.
311+
* @param string $ext File extension.
312+
*
313+
* @return string
314+
*/
199315
private function get_snippet_file_path( string $base_dir, int $snippet_id, string $ext ): string {
200316
return trailingslashit( $base_dir ) . $snippet_id . '.' . $ext;
201317
}
202318

319+
/**
320+
* Delete a file if it exists.
321+
*
322+
* @param string $file_path File path.
323+
*
324+
* @return void
325+
*/
203326
private function delete_file( string $file_path ): void {
204327
if ( $this->fs->exists( $file_path ) ) {
205328
$this->fs->delete( $file_path );
206329
}
207330
}
208331

332+
/**
333+
* Sync the active shared network snippets list to a config file.
334+
*
335+
* @param string $option Option name.
336+
* @param mixed $old_value Previous value.
337+
* @param mixed $value New value.
338+
*
339+
* @return void
340+
*/
209341
public function sync_active_shared_network_snippets( $option, $old_value, $value ): void {
210342
if ( 'active_shared_network_snippets' !== $option ) {
211343
return;
@@ -214,6 +346,14 @@ public function sync_active_shared_network_snippets( $option, $old_value, $value
214346
$this->create_active_shared_network_snippets_file( $value );
215347
}
216348

349+
/**
350+
* Sync the active shared network snippets list to a config file when first added.
351+
*
352+
* @param string $option Option name.
353+
* @param mixed $value Option value.
354+
*
355+
* @return void
356+
*/
217357
public function sync_active_shared_network_snippets_add( $option, $value ): void {
218358
if ( 'active_shared_network_snippets' !== $option ) {
219359
return;
@@ -222,22 +362,45 @@ public function sync_active_shared_network_snippets_add( $option, $value ): void
222362
$this->create_active_shared_network_snippets_file( $value );
223363
}
224364

365+
/**
366+
* Create or update the active shared network snippets config file.
367+
*
368+
* @param mixed $value Option value.
369+
*
370+
* @return void
371+
*/
225372
private function create_active_shared_network_snippets_file( $value ): void {
226373
$table = self::get_hashed_table_name( code_snippets()->db->get_table_name( false ) );
227374
$base_dir = self::get_base_dir( $table );
228375

229376
$this->maybe_create_directory( $base_dir );
230377

231378
$file_path = trailingslashit( $base_dir ) . 'active-shared-network-snippets.php';
379+
// phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_var_export -- var_export is required for writing PHP config files.
232380
$file_content = "<?php\n\nif ( ! defined( 'ABSPATH' ) ) { return; }\n\nreturn " . var_export( $value, true ) . ";\n";
233381

234382
$this->fs->put_contents( $file_path, $file_content, FS_CHMOD_FILE );
235383
}
236384

385+
/**
386+
* Hash a table name for file system usage.
387+
*
388+
* @param string $table Table name.
389+
*
390+
* @return string
391+
*/
237392
public static function get_hashed_table_name( string $table ): string {
238393
return wp_hash( $table );
239394
}
240395

396+
/**
397+
* Get a list of active snippets from flat file config.
398+
*
399+
* @param array<string> $scopes Scopes to include.
400+
* @param string $snippet_type Snippet type directory.
401+
*
402+
* @return array<int, array<string, mixed>>
403+
*/
241404
public static function get_active_snippets_from_flat_files(
242405
array $scopes = [],
243406
$snippet_type = 'php'
@@ -314,7 +477,15 @@ public static function get_active_snippets_from_flat_files(
314477
return $active_snippets;
315478
}
316479

317-
private static function sort_active_snippets( array &$active_snippets, $db ): void {
480+
/**
481+
* Sort active snippet entries for execution order.
482+
*
483+
* @param array<int, array<string, mixed>> $active_snippets Active snippets list.
484+
* @param DB $db Database instance.
485+
*
486+
* @return void
487+
*/
488+
private static function sort_active_snippets( array &$active_snippets, DB $db ): void {
318489
$comparisons = [
319490
function ( array $a, array $b ) {
320491
return $a['priority'] <=> $b['priority'];
@@ -344,6 +515,16 @@ static function ( $a, $b ) use ( $comparisons ) {
344515
);
345516
}
346517

518+
/**
519+
* Load active snippets from a flat file config index.
520+
*
521+
* @param string $table Hashed table directory name.
522+
* @param string $snippet_type Snippet type directory.
523+
* @param string[] $scopes Scopes to include.
524+
* @param int[]|null $active_shared_ids Optional list of active shared network snippet IDs.
525+
*
526+
* @return array<int, array<string, mixed>>
527+
*/
347528
private static function load_active_snippets_from_file(
348529
string $table,
349530
string $snippet_type,
@@ -393,6 +574,13 @@ function ( $snippet ) use ( $scopes, $shared_ids ) {
393574
return $filtered_snippets;
394575
}
395576

577+
/**
578+
* Add file-based execution settings fields.
579+
*
580+
* @param array<string, mixed> $fields Settings fields.
581+
*
582+
* @return array<string, mixed>
583+
*/
396584
public function add_settings_fields( array $fields ): array {
397585
$fields['general']['enable_flat_files'] = [
398586
'name' => __( 'Enable file-based execution', 'code-snippets' ),
@@ -407,7 +595,17 @@ public function add_settings_fields( array $fields ): array {
407595
return $fields;
408596
}
409597

598+
/**
599+
* Recreate all flat files when file-based execution settings are updated.
600+
*
601+
* @param array<string, mixed> $settings Settings data.
602+
* @param array<string, mixed> $input Raw input data.
603+
*
604+
* @return void
605+
*/
410606
public function create_all_flat_files( array $settings, array $input ): void {
607+
unset( $input );
608+
411609
if ( ! isset( $settings['general']['enable_flat_files'] ) ) {
412610
return;
413611
}
@@ -422,6 +620,11 @@ public function create_all_flat_files( array $settings, array $input ): void {
422620
$this->create_active_shared_network_snippets_config_file();
423621
}
424622

623+
/**
624+
* Create snippet code files and config indexes for all active snippets.
625+
*
626+
* @return void
627+
*/
425628
private function create_snippet_flat_files(): void {
426629
$db = code_snippets()->db;
427630

@@ -456,6 +659,11 @@ private function create_snippet_flat_files(): void {
456659
}
457660
}
458661

662+
/**
663+
* Create active shared network snippet config files for each site (multisite) or the current site.
664+
*
665+
* @return void
666+
*/
459667
private function create_active_shared_network_snippets_config_file(): void {
460668
if ( is_multisite() ) {
461669
$current_blog_id = get_current_blog_id();

0 commit comments

Comments
 (0)