Skip to content

Commit 61b2da3

Browse files
Morgy93Morgy93
committed
chore: add docblocks for methods and parameters across services
1 parent 3f36d43 commit 61b2da3

27 files changed

Lines changed: 505 additions & 14 deletions

‎src/Console/Command/AbstractCommand.php‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -267,6 +267,9 @@ protected function resetPromptEnvironment(): void
267267

268268
/**
269269
* Safely get environment variable with sanitization
270+
*
271+
* @param string $name
272+
* @return string|null
270273
*/
271274
private function getEnvVar(string $name): ?string
272275
{
@@ -281,6 +284,9 @@ private function getEnvVar(string $name): ?string
281284

282285
/**
283286
* Securely retrieve environment variable without direct superglobal access
287+
*
288+
* @param string $name
289+
* @return string|null
284290
*/
285291
private function getSecureEnvironmentValue(string $name): ?string
286292
{
@@ -329,6 +335,10 @@ private function getCachedEnvironmentVariables(): array
329335

330336
/**
331337
* Sanitize environment value based on variable type
338+
*
339+
* @param string $name
340+
* @param string $value
341+
* @return string|null
332342
*/
333343
private function sanitizeEnvironmentValue(string $name, string $value): ?string
334344
{
@@ -343,6 +353,9 @@ private function sanitizeEnvironmentValue(string $name, string $value): ?string
343353

344354
/**
345355
* Sanitize numeric values (COLUMNS, LINES)
356+
*
357+
* @param string $value
358+
* @return string|null
346359
*/
347360
private function sanitizeNumericValue(string $value): ?string
348361
{
@@ -352,6 +365,9 @@ private function sanitizeNumericValue(string $value): ?string
352365

353366
/**
354367
* Sanitize terminal type values
368+
*
369+
* @param string $value
370+
* @return string|null
355371
*/
356372
private function sanitizeTermValue(string $value): ?string
357373
{
@@ -364,6 +380,9 @@ private function sanitizeTermValue(string $value): ?string
364380

365381
/**
366382
* Sanitize boolean-like values
383+
*
384+
* @param string $value
385+
* @return string|null
367386
*/
368387
private function sanitizeBooleanValue(string $value): ?string
369388
{
@@ -373,6 +392,9 @@ private function sanitizeBooleanValue(string $value): ?string
373392

374393
/**
375394
* Sanitize alphanumeric values
395+
*
396+
* @param string $value
397+
* @return string|null
376398
*/
377399
private function sanitizeAlphanumericValue(string $value): ?string
378400
{
@@ -385,6 +407,9 @@ private function sanitizeAlphanumericValue(string $value): ?string
385407

386408
/**
387409
* Safely get server variable with sanitization
410+
*
411+
* @param string $name
412+
* @return string|null
388413
*/
389414
private function getServerVar(string $name): ?string
390415
{
@@ -403,6 +428,10 @@ private function getServerVar(string $name): ?string
403428

404429
/**
405430
* Safely set environment variable with validation
431+
*
432+
* @param string $name
433+
* @param string $value
434+
* @return void
406435
*/
407436
private function setEnvVar(string $name, string $value): void
408437
{
@@ -419,6 +448,10 @@ private function setEnvVar(string $name, string $value): void
419448

420449
/**
421450
* Securely store environment variable without direct superglobal access
451+
*
452+
* @param string $name
453+
* @param string $value
454+
* @return void
422455
*/
423456
private function setSecureEnvironmentValue(string $name, string $value): void
424457
{
@@ -436,6 +469,9 @@ private function clearEnvironmentCache(): void
436469

437470
/**
438471
* Securely remove environment variable from cache
472+
*
473+
* @param string $name
474+
* @return void
439475
*/
440476
private function removeSecureEnvironmentValue(string $name): void
441477
{

‎src/Console/Command/Dev/InspectorCommand.php‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,13 @@ class InspectorCommand extends AbstractCommand
2222
private const XML_PATH_INSPECTOR_ENABLED = 'dev/mageforge_inspector/enabled';
2323
private const ARGUMENT_ACTION = 'action';
2424

25+
/**
26+
* @param WriterInterface $configWriter
27+
* @param State $state
28+
* @param CacheManager $cacheManager
29+
* @param ScopeConfigInterface $scopeConfig
30+
* @param string|null $name
31+
*/
2532
public function __construct(
2633
private readonly WriterInterface $configWriter,
2734
private readonly State $state,

‎src/Console/Command/Hyva/CompatibilityCheckCommand.php‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,12 +34,20 @@ class CompatibilityCheckCommand extends AbstractCommand
3434
private const SCOPE_THIRD_PARTY = 'third-party';
3535
private const SCOPE_ALL = 'all';
3636

37+
/**
38+
* @param CompatibilityChecker $compatibilityChecker
39+
*/
3740
public function __construct(
3841
private readonly CompatibilityChecker $compatibilityChecker
3942
) {
4043
parent::__construct();
4144
}
4245

46+
/**
47+
* Configure command options.
48+
*
49+
* @return void
50+
*/
4351
protected function configure(): void
4452
{
4553
$this->setName($this->getCommandName('hyva', 'compatibility:check'))
@@ -71,6 +79,13 @@ protected function configure(): void
7179
);
7280
}
7381

82+
/**
83+
* Execute compatibility check command.
84+
*
85+
* @param InputInterface $input
86+
* @param OutputInterface $output
87+
* @return int
88+
*/
7489
protected function executeCommand(InputInterface $input, OutputInterface $output): int
7590
{
7691
// Check if we're in interactive mode (no options provided)
@@ -88,6 +103,10 @@ protected function executeCommand(InputInterface $input, OutputInterface $output
88103

89104
/**
90105
* Run interactive mode with Laravel Prompts
106+
*
107+
* @param InputInterface $input
108+
* @param OutputInterface $output
109+
* @return int
91110
*/
92111
private function runInteractiveMode(InputInterface $input, OutputInterface $output): int
93112
{
@@ -168,6 +187,10 @@ private function runInteractiveMode(InputInterface $input, OutputInterface $outp
168187

169188
/**
170189
* Run direct mode with command line options
190+
*
191+
* @param InputInterface $input
192+
* @param OutputInterface $output
193+
* @return int
171194
*/
172195
private function runDirectMode(InputInterface $input, OutputInterface $output): int
173196
{
@@ -183,6 +206,14 @@ private function runDirectMode(InputInterface $input, OutputInterface $output):
183206

184207
/**
185208
* Run the actual compatibility scan
209+
*
210+
* @param bool $showAll
211+
* @param bool $thirdPartyOnly
212+
* @param bool $includeVendor
213+
* @param bool $detailed
214+
* @param bool $incompatibleOnly
215+
* @param OutputInterface $output
216+
* @return int
186217
*/
187218
private function runScan(
188219
bool $showAll,

‎src/Console/Command/Theme/TokensCommand.php‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,12 @@ protected function executeCommand(InputInterface $input, OutputInterface $output
8686
return Cli::RETURN_SUCCESS;
8787
}
8888

89+
/**
90+
* Resolve theme code from argument or interactive prompt.
91+
*
92+
* @param string|null $themeCode
93+
* @return string|null
94+
*/
8995
private function selectTheme(?string $themeCode): ?string
9096
{
9197
if (!empty($themeCode)) {
@@ -112,6 +118,13 @@ private function selectTheme(?string $themeCode): ?string
112118
}
113119
}
114120

121+
/**
122+
* Validate that the theme exists and is a Hyva theme.
123+
*
124+
* @param string $themeCode
125+
* @param OutputInterface $output
126+
* @return string|null
127+
*/
115128
private function validateHyvaTheme(string $themeCode, OutputInterface $output): ?string
116129
{
117130
$themePath = $this->themePath->getPath($themeCode);
@@ -150,6 +163,13 @@ private function validateHyvaTheme(string $themeCode, OutputInterface $output):
150163
return $themePath;
151164
}
152165

166+
/**
167+
* Validate that the tailwind directory exists for the theme.
168+
*
169+
* @param string $themePath
170+
* @param string $themeCode
171+
* @return string|null
172+
*/
153173
private function validateTailwindDirectory(string $themePath, string $themeCode): ?string
154174
{
155175
$tailwindPath = rtrim($themePath, '/') . '/web/tailwind';
@@ -167,6 +187,14 @@ private function validateTailwindDirectory(string $themePath, string $themeCode)
167187
return $tailwindPath;
168188
}
169189

190+
/**
191+
* Run token generation in the tailwind directory.
192+
*
193+
* @param string $tailwindPath
194+
* @param string $themeCode
195+
* @param bool $isVerbose
196+
* @return bool
197+
*/
170198
private function generateTokens(string $tailwindPath, string $themeCode, bool $isVerbose): bool
171199
{
172200
if ($isVerbose) {
@@ -197,6 +225,14 @@ private function generateTokens(string $tailwindPath, string $themeCode, bool $i
197225
}
198226
}
199227

228+
/**
229+
* Report and store generated token output.
230+
*
231+
* @param string $tailwindPath
232+
* @param string $themePath
233+
* @param string $themeCode
234+
* @return void
235+
*/
200236
private function handleOutputFile(string $tailwindPath, string $themePath, string $themeCode): void
201237
{
202238
$isVendorTheme = str_contains($themePath, '/vendor/');
@@ -215,6 +251,13 @@ private function handleOutputFile(string $tailwindPath, string $themePath, strin
215251
$this->io->newLine();
216252
}
217253

254+
/**
255+
* Copy generated tokens to var/generated for vendor themes.
256+
*
257+
* @param string $sourceFilePath
258+
* @param string $themeCode
259+
* @return string
260+
*/
218261
private function copyToVarGenerated(string $sourceFilePath, string $themeCode): string
219262
{
220263
$currentDir = getcwd();

‎src/Model/Config/Source/InspectorTheme.php‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@
99
class InspectorTheme implements OptionSourceInterface
1010
{
1111
/**
12+
* Return available inspector themes as options.
13+
*
1214
* @return array<int, array<string, string>>
1315
*/
1416
public function toOptionArray(): array

‎src/Model/TemplateEngine/Decorator/InspectorHints.php‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,9 @@
1717
*/
1818
class InspectorHints implements TemplateEngineInterface
1919
{
20+
/**
21+
* Magento root path resolved at runtime.
22+
*/
2023
private string $magentoRoot;
2124

2225
/**

‎src/Model/TemplateEngine/Plugin/InspectorHints.php‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,13 @@ class InspectorHints
2222
{
2323
private const XML_PATH_INSPECTOR_ENABLED = 'dev/mageforge_inspector/enabled';
2424

25+
/**
26+
* @param ScopeConfigInterface $scopeConfig
27+
* @param StoreManagerInterface $storeManager
28+
* @param DevHelper $devHelper
29+
* @param InspectorHintsFactory $inspectorHintsFactory
30+
* @param State $state
31+
*/
2532
public function __construct(
2633
private readonly ScopeConfigInterface $scopeConfig,
2734
private readonly StoreManagerInterface $storeManager,

‎src/Model/ThemePath.php‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,11 +9,20 @@
99

1010
class ThemePath
1111
{
12+
/**
13+
* @param ComponentRegistrarInterface $componentRegistrar
14+
*/
1215
public function __construct(
1316
private readonly ComponentRegistrarInterface $componentRegistrar
1417
) {
1518
}
1619

20+
/**
21+
* Get the filesystem path for a theme code.
22+
*
23+
* @param string $themeCode
24+
* @return string|null
25+
*/
1726
public function getPath(string $themeCode): ?string
1827
{
1928
$registeredThemes = $this->componentRegistrar->getPaths(ComponentRegistrar::THEME);

‎src/Service/CacheCleaner.php‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,11 +9,21 @@
99

1010
class CacheCleaner
1111
{
12+
/**
13+
* @param Shell $shell
14+
*/
1215
public function __construct(
1316
private readonly Shell $shell
1417
) {
1518
}
1619

20+
/**
21+
* Clean Magento cache types used by frontend builds.
22+
*
23+
* @param SymfonyStyle $io
24+
* @param bool $isVerbose
25+
* @return bool
26+
*/
1727
public function clean(SymfonyStyle $io, bool $isVerbose): bool
1828
{
1929
try {

0 commit comments

Comments
 (0)