Add PHPStan gubbins.

  - Add PHPStan and "phpstan-strict-rules" gubbins.
  - Address Level 9 issues raised by PHPStan in the static site
    generator code base.
  - "Taskfile.yml": Add static analysis to "ci" task.

Taskfile.yml

@@ -23,6 +23,7 @@ tasks:
       - task: 'dependencies'
       - task: 'build'
       - task: 'lint'
+      - task: 'static-analysis'
     desc: 'Run all default CI-related tasks'
 
   ci:end-to-end:
@@ -190,6 +191,21 @@ tasks:
       - task: 'ci'
     desc: 'Run all development environment setup tasks'
 
+  static-analysis:
+    cmds:
+      - task: 'static-analysis:php'
+    desc: 'Run all static-analysis-related tasks'
+
+  static-analysis:php:
+    cmds:
+      - task: 'static-analysis:php:phpstan'
+    desc: 'Run all PHP static-analysis-related tasks'
+
+  static-analysis:php:phpstan:
+    cmds:
+      - 'protected/vendor/bin/phpstan analyse --no-progress'
+    desc: 'Analyse PHP files with PHPStan'
+
   test:end-to-end:
     cmds:
       - 'protected/vendor/bin/phpunit --testdox'

composer.json

@@ -49,6 +49,8 @@
     "friendsofphp/php-cs-fixer": "^3.59.3",
     "league/commonmark": "^2.4",
     "michelf/php-smartypants": "^1.8.1",
+    "phpstan/phpstan": "^1.11",
+    "phpstan/phpstan-strict-rules": "^1.6",
     "phpunit/phpunit": "^11.2.5",
     "roave/security-advisories": "dev-latest",
     "symfony/yaml": "^7.1",

phpstan.neon.dist

@@ -0,0 +1,10 @@
+# Copyright (C) Damien Dart, <[email protected]>.
+# This file is distributed under the MIT licence. For more information,
+# please refer to the accompanying "LICENCE" file.
+
+includes:
+  - 'protected/vendor/phpstan/phpstan-strict-rules/rules.neon'
+parameters:
+  level: 9
+  paths:
+    - 'src/ssg'

src/ssg/InputFile.php

@@ -14,6 +14,7 @@
 {
     private ?string $modifiedContent;
 
+    /** @param mixed[] $metadata */
     public function __construct(
         public string $source,
         public string $outputPath,
@@ -35,10 +36,16 @@ public function getContent(): string
 
     private function getOriginalContent(): string
     {
-        // TODO: Handle false return.
-        return file_get_contents($this->source);
+        $content = file_get_contents($this->source);
+
+        // Errors are converted into exceptions by the custom error
+        // handler, so "file_get_contents" will always return a string.
+        \assert(\is_string($content));
+
+        return $content;
     }
 
+    /** @param mixed[] $metadata */
     public function withAdditionalMetadata(array $metadata): self
     {
         return $this->withMetadata(
@@ -66,6 +73,7 @@ public function withOutputPath(string $outputPath): self
         );
     }
 
+    /** @param mixed[] $metadata */
     public function withMetadata(array $metadata): self
     {
         return new self(

src/ssg/Pipeline.php

@@ -14,6 +14,7 @@
 
 final readonly class Pipeline implements StepInterface
 {
+    /** @var StepInterface[] */
     private array $steps;
 
     public function __construct(StepInterface ...$steps)

src/ssg/StaticSiteGenerator.php

@@ -56,6 +56,7 @@ public function run(): int
         return 0;
     }
 
+    /** @return InputFile[] */
     private function getInputFiles(): array
     {
         $files = new \RecursiveCallbackFilterIterator(
@@ -70,6 +71,8 @@ private function getInputFiles(): array
         $inputDirectory = realpath($this->inputDirectory);
         $inputFiles = [];
 
+        \assert(\is_string($inputDirectory));
+
         /** @var \SplFileInfo $file */
         foreach (new \RecursiveIteratorIterator($files) as $file) {
             $inputFiles[] = new InputFile(

src/ssg/Steps/GenerateSlugsStep.php

@@ -10,7 +10,7 @@
 
 namespace StaticSiteGenerator\Steps;
 
-use StaticSiteGenerator\Inputfile;
+use StaticSiteGenerator\InputFile;
 
 final class GenerateSlugsStep extends AbstractStep
 {
@@ -23,7 +23,7 @@ final class GenerateSlugsStep extends AbstractStep
     /** @var string[] */
     private const TEMPLATE_EXTENSIONS = ['twig'];
 
-    protected function process(Inputfile $inputFile): Inputfile
+    protected function process(InputFile $inputFile): InputFile
     {
         return $inputFile->withAdditionalMetadata(
             ['slug' => $this->slugify($inputFile->outputPath)],

src/ssg/Steps/MinifyHtmlStep.php

@@ -10,7 +10,7 @@
 
 namespace StaticSiteGenerator\Steps;
 
-use StaticSiteGenerator\Inputfile;
+use StaticSiteGenerator\InputFile;
 use voku\helper\HtmlMin;
 
 final class MinifyHtmlStep extends AbstractStep
@@ -27,7 +27,7 @@ public function __construct()
             ->doMakeSameDomainsLinksRelative(['www.robotinaponcho.net']);
     }
 
-    protected function process(Inputfile $inputFile): Inputfile
+    protected function process(InputFile $inputFile): InputFile
     {
         if (! str_ends_with($inputFile->outputPath, 'html')) {
             return $inputFile;
@@ -85,12 +85,14 @@ private function processContent(string $content): string
         $content = $this->minifier->minify($content);
 
         // HTMLMin adds superfluous whitespace between block elements.
-        $content = preg_replace(
+        // Errors are converted into exceptions by the custom error
+        // handler, so "preg_replace" will always return a string.
+        $content = (string) preg_replace(
             "/({$elementRegexGroup})>\\s</",
             '$1><',
             $content,
         );
-        $content = preg_replace(
+        $content = (string) preg_replace(
             "#>\\s<(/?({$elementRegexGroup}))#",
             '><$1',
             $content,
@@ -100,14 +102,17 @@ private function processContent(string $content): string
             // Add the scheme and domain name back to canonical link
             // URLs to prevent any future shenanigans (if the site gets
             // mirrored, for example).
-            $content = preg_replace(
+            $content = (string) preg_replace(
                 '/<link href=(\S+) rel=canonical>/',
                 '<link href=https://www.robotinaponcho.net$1 rel=canonical>',
                 $content,
             );
         }
 
-        return preg_replace_callback(
+        // Errors are converted into exceptions by the custom error
+        // handler, so "preg_replace_callback" will always return a
+        // string in this instance.
+        return (string) preg_replace_callback(
             '/(&#\d+;)/',
             static function ($match): string {
                 return mb_convert_encoding(

src/ssg/Steps/ProcessFrontMatterStep.php

@@ -10,7 +10,7 @@
 
 namespace StaticSiteGenerator\Steps;
 
-use StaticSiteGenerator\Inputfile;
+use StaticSiteGenerator\InputFile;
 use StaticSiteGenerator\ValueObjects\GitMetadata;
 use Symfony\Component\Yaml\Parser;
 
@@ -25,7 +25,7 @@ public function __construct(
         private readonly Parser $yamlParser,
     ) {}
 
-    protected function process(Inputfile $inputFile): Inputfile
+    protected function process(InputFile $inputFile): InputFile
     {
         foreach (self::FRONT_MATTER_REGEXES as $regex) {
             if (
@@ -34,7 +34,7 @@ protected function process(Inputfile $inputFile): Inputfile
             ) {
                 $content = str_replace($matches[0], '', $inputFile->getContent());
 
-                /** @var array{array-key, mixed} $metadata */
+                /** @var mixed[] $metadata */
                 $metadata = $this->yamlParser->parse($matches[1]) ?? [];
 
                 if (\array_key_exists('git', $metadata)) {
@@ -59,8 +59,8 @@ private function parseGitMetadataKeyword(string $keyword): GitMetadata
         }
 
         return new GitMetadata(
-            \DateTimeImmutable::createFromFormat('U', $parts[2]),
-            \DateTimeImmutable::createFromFormat('U', $parts[4]),
+            new \DateTimeImmutable('@' . $parts[2]),
+            new \DateTimeImmutable('@' . $parts[4]),
             $parts[1],
             $parts[3],
         );

src/ssg/Steps/ProcessMarkdownStep.php

@@ -44,7 +44,10 @@ private function extractTitle(InputFile $inputFile): InputFile
         ) {
             return $inputFile
                 ->withContent(
-                    preg_replace(
+                    // Errors are converted into exceptions by the
+                    // custom error handler, so "preg_replace" will
+                    // always return a string.
+                    (string) preg_replace(
                         "/{$headings[1]}\n=+\n/",
                         '',
                         $content,

src/ssg/Steps/StepInterface.php

@@ -10,10 +10,10 @@
 
 namespace StaticSiteGenerator\Steps;
 
-use StaticSiteGenerator\Inputfile;
+use StaticSiteGenerator\InputFile;
 
 interface StepInterface
 {
     /** @return InputFile[] */
-    public function run(Inputfile ...$inputFiles): array;
+    public function run(InputFile ...$inputFiles): array;
 }

src/ssg/Support/TwigEnvironmentFactory.php

@@ -59,7 +59,10 @@ static function (?string $string): string {
                         return $string;
                     }
 
-                    return preg_replace(
+                    // Errors are converted into exceptions by the
+                    // custom error handler, so "preg_replace" will
+                    // always return a string.
+                    return (string) preg_replace(
                         '/\s+(\S+)$/',
                         ' $1',
                         rtrim($string),