Merge pull request #755 from hydephp/refactor-internal-code

emmadesilva · web-flow · commit c21571922f0b · 2022-12-14T22:43:17.000+01:00
Refactor internal code
diff --git a/packages/framework/src/Facades/Filesystem.php b/packages/framework/src/Facades/Filesystem.php
@@ -130,11 +130,6 @@ public static function putContents(string $path, string $contents, bool $lock =
         return self::put($path, $contents, $lock);
     }
 
-    protected static function qualifyPossiblePathArray(array|string $paths): array|string
-    {
-        return self::kernel()->filesystem()->qualifyPossiblePathArray($paths);
-    }
-
     protected static function filesystem(): \Illuminate\Filesystem\Filesystem
     {
         return File::getFacadeRoot();
diff --git a/packages/framework/src/Foundation/Concerns/BaseFoundationCollection.php b/packages/framework/src/Foundation/Concerns/BaseFoundationCollection.php
@@ -9,7 +9,7 @@
 use Illuminate\Support\Collection;
 
 /**
- * @internal Base class for the kernel auto-discovery collections.
+ * Base class for the kernel auto-discovery collections.
  *
  * @see \Hyde\Foundation\FileCollection
  * @see \Hyde\Foundation\PageCollection
diff --git a/packages/framework/src/Foundation/Concerns/ForwardsFilesystem.php b/packages/framework/src/Foundation/Concerns/ForwardsFilesystem.php
@@ -73,7 +73,7 @@ public function sitePath(string $path = ''): string
         return $this->filesystem->sitePath($path);
     }
 
-    public function pathToAbsolute(string $path): string
+    public function pathToAbsolute(array|string $path): array|string
     {
         return $this->filesystem->pathToAbsolute($path);
     }
diff --git a/packages/framework/src/Foundation/Filesystem.php b/packages/framework/src/Foundation/Filesystem.php
@@ -4,6 +4,7 @@
 
 namespace Hyde\Foundation;
 
+use function array_map;
 use function collect;
 use function copy;
 use Hyde\Facades\Site;
@@ -14,6 +15,7 @@
 use Hyde\Pages\MarkdownPage;
 use Hyde\Pages\MarkdownPost;
 use Illuminate\Support\Collection;
+use function is_array;
 use function is_string;
 use function str_replace;
 use function touch;
@@ -66,9 +68,15 @@ public function path(string $path = ''): string
 
     /**
      * Get an absolute file path from a supplied relative path.
+     *
+     * Input types are matched, meaning that if the input is a string so will the output be.
      */
-    public function pathToAbsolute(string $path): string
+    public function pathToAbsolute(array|string $path): array|string
     {
+        if (is_array($path)) {
+            return array_map(fn (string $path): string => $this->pathToAbsolute($path), $path);
+        }
+
         return $this->path($path);
     }
 
@@ -205,16 +213,6 @@ public function smartGlob(string $pattern, int $flags = 0): Collection
             ->map(fn (string $path): string => $this->pathToRelative($path));
     }
 
-    /** @internal */
-    public function qualifyPossiblePathArray(array|string $paths): array|string
-    {
-        if (is_array($paths)) {
-            return array_map(fn ($path) => $this->pathToAbsolute($path), $paths);
-        }
-
-        return $this->pathToAbsolute($paths);
-    }
-
     /**
      * Implode path components into a string with directory separators.
      */
diff --git a/packages/framework/src/Framework/Actions/BladeMatterParser.php b/packages/framework/src/Framework/Actions/BladeMatterParser.php
@@ -4,8 +4,16 @@
 
 namespace Hyde\Framework\Actions;
 
+use function explode;
+use function file_get_contents;
 use Hyde\Hyde;
+use function json_decode;
 use RuntimeException;
+use function strlen;
+use function strpos;
+use function substr;
+use function substr_count;
+use function trim;
 
 /**
  * Parse the front matter in a Blade file.
@@ -69,21 +77,19 @@ public function parse(): static
 
         foreach ($lines as $line) {
             if (static::lineMatchesFrontMatter($line)) {
-                $this->matter[static::extractKey($line)] = static::normalizeValue(static::extractValue($line));
+                $this->matter[static::extractKey($line)] = static::getValueWithType(static::extractValue($line));
             }
         }
 
         return $this;
     }
 
-    /** @internal */
-    public static function lineMatchesFrontMatter(string $line): bool
+    protected static function lineMatchesFrontMatter(string $line): bool
     {
         return str_starts_with($line, static::SEARCH);
     }
 
-    /** @internal */
-    public static function extractKey(string $line): string
+    protected static function extractKey(string $line): string
     {
         // Remove search prefix
         $key = substr($line, strlen(static::SEARCH));
@@ -95,8 +101,7 @@ public static function extractKey(string $line): string
         return trim($key);
     }
 
-    /** @internal */
-    public static function extractValue(string $line): string
+    protected static function extractValue(string $line): string
     {
         // Trim any trailing spaces and newlines
         $key = trim($line);
@@ -114,8 +119,7 @@ public static function extractValue(string $line): string
         return trim($key);
     }
 
-    /** @internal Return the proper type for the string */
-    public static function normalizeValue(string $value): mixed
+    protected static function getValueWithType(string $value): mixed
     {
         $value = trim($value);
 
@@ -132,8 +136,7 @@ public static function normalizeValue(string $value): mixed
         return json_decode($value) ?? $value;
     }
 
-    /** @internal */
-    public static function parseArrayString(string $string): array
+    protected static function parseArrayString(string $string): array
     {
         $array = [];
 
@@ -153,7 +156,7 @@ public static function parseArrayString(string $string): array
         // Remove opening and closing brackets
         $string = substr($string, 1, strlen($string) - 2);
 
-        // tokenize string between commas
+        // Tokenize string between commas
         $tokens = explode(',', $string);
 
         // Parse each token
@@ -162,7 +165,7 @@ public static function parseArrayString(string $string): array
             $pair = explode('=>', $entry);
 
             // Add key/value pair to array
-            $array[static::normalizeValue(trim(trim($pair[0]), "'"))] = static::normalizeValue(trim(trim($pair[1]), "'"));
+            $array[static::getValueWithType(trim(trim($pair[0]), "'"))] = static::getValueWithType(trim(trim($pair[1]), "'"));
         }
 
         return $array;
diff --git a/packages/framework/src/Framework/Concerns/Internal/ForwardsIlluminateFilesystem.php b/packages/framework/src/Framework/Concerns/Internal/ForwardsIlluminateFilesystem.php
@@ -9,7 +9,7 @@
 /**
  * Forwards calls to the Laravel File facade to the HydePHP Filesystem Facade.
  *
- * @interal
+ * @interal This trait is not covered by the backward compatibility promise.
  *
  * @see \Hyde\Facades\Filesystem
  */
@@ -102,7 +102,7 @@ public static function chmod(string $path, int $mode = null): mixed
     /** @inheritDoc */
     public static function delete(array|string $paths): bool
     {
-        return self::filesystem()->delete(self::qualifyPossiblePathArray($paths));
+        return self::filesystem()->delete(self::kernel()->filesystem()->pathToAbsolute($paths));
     }
 
     /** @inheritDoc */
diff --git a/packages/framework/src/Framework/Concerns/Internal/MockableFeatures.php b/packages/framework/src/Framework/Concerns/Internal/MockableFeatures.php
@@ -5,7 +5,11 @@
 namespace Hyde\Framework\Concerns\Internal;
 
 /**
- * @internal
+ * Allows the Features class to be mocked.
+ *
+ * @internal This trait is not covered by the backward compatibility promise.
+ *
+ * @see \Hyde\Facades\Features
  */
 trait MockableFeatures
 {
diff --git a/packages/framework/src/Framework/Concerns/Internal/SetsUpMarkdownConverter.php b/packages/framework/src/Framework/Concerns/Internal/SetsUpMarkdownConverter.php
@@ -10,7 +10,9 @@
 use Torchlight\Commonmark\V2\TorchlightExtension;
 
 /**
- * @internal Sets up the Markdown converter for the Markdown service.
+ * Sets up the Markdown converter for the Markdown service.
+ *
+ * @internal This trait is not covered by the backward compatibility promise.
  *
  * @see \Hyde\Framework\Services\MarkdownService
  */
diff --git a/packages/framework/src/Framework/Features/BuildTasks/PostBuildTasks/GenerateSearch.php b/packages/framework/src/Framework/Features/BuildTasks/PostBuildTasks/GenerateSearch.php
@@ -36,8 +36,10 @@ public function then(): void
         $this->createdSiteFile(DocumentationSearchService::$filePath)->withExecutionTime();
     }
 
-    /** @internal Estimated processing time per file in ms */
-    public static float $guesstimationFactor = 52.5;
+    /**
+     * Estimated processing time per file in ms.
+     */
+    protected static float $guesstimationFactor = 52.5;
 
     protected function guesstimateGenerationTime(): int|float
     {
diff --git a/packages/framework/src/Framework/Features/Documentation/SemanticDocumentationArticle.php b/packages/framework/src/Framework/Features/Documentation/SemanticDocumentationArticle.php
@@ -59,7 +59,6 @@ public function renderFooter(): HtmlString
         return new HtmlString($this->footer);
     }
 
-    /** @internal */
     protected function process(): self
     {
         $this->tokenize();
diff --git a/packages/framework/src/Framework/Features/Session/Session.php b/packages/framework/src/Framework/Features/Session/Session.php
@@ -10,7 +10,8 @@
  * Adds a simple session handler, arguably most useful to defer messages, for example,
  * to asynchronously add warnings to be used at a later point in the request lifecycle.
  *
- * @internal This class is currently experimental and should not be relied upon outside the framework.
+ * @internal This class is currently experimental and should not be relied upon outside the framework as it may change at any time.
+ * @experimental
  * @codeCoverageIgnore
  *
  * It's bound into the service container as a singleton and is not persisted.
diff --git a/packages/framework/src/Framework/Features/Templates/Homepages.php b/packages/framework/src/Framework/Features/Templates/Homepages.php
@@ -6,7 +6,10 @@
 
 use Illuminate\Support\Collection;
 
-/** @internal */
+/**
+ * @internal This class is currently experimental and should not be relied upon outside the framework as it may change at any time.
+ * @experimental
+ */
 final class Homepages
 {
     public static function options(): Collection
diff --git a/packages/framework/src/Pages/Concerns/UsesFlattenedOutputPaths.php b/packages/framework/src/Pages/Concerns/UsesFlattenedOutputPaths.php
@@ -8,7 +8,8 @@
 use function unslash;
 
 /**
- * @internal This trait is currently experimental and should not be relied upon outside of Hyde.
+ * @internal This trait is currently experimental and should not be relied upon outside of Hyde as it may change at any time.
+ * @experimental
  *
  * This trait is used to flatten the output path of a page. This is only used for the documentation pages,
  * where all pages are output to the same directory, but where putting the page in a subdirectory will
diff --git a/packages/framework/tests/Feature/BladeMatterParserTest.php b/packages/framework/tests/Feature/BladeMatterParserTest.php
diff --git a/packages/framework/tests/Feature/Commands/BuildSearchCommandTest.php b/packages/framework/tests/Feature/Commands/BuildSearchCommandTest.php
diff --git a/packages/framework/tests/Feature/Foundation/FilesystemTest.php b/packages/framework/tests/Feature/Foundation/FilesystemTest.php
diff --git a/packages/testing/src/ResetsApplication.php b/packages/testing/src/ResetsApplication.php
diff --git a/packages/testing/src/TestCase.php b/packages/testing/src/TestCase.php

Original file line number	Diff line number	Diff line change
`@@ -130,11 +130,6 @@ public static function putContents(string $path, string $contents, bool $lock =`
`130`	`130`	`return self::put($path, $contents, $lock);`
`131`	`131`	`}`
`132`	`132`
`133`		`- protected static function qualifyPossiblePathArray(array\|string $paths): array\|string`
`134`		`- {`
`135`		`- return self::kernel()->filesystem()->qualifyPossiblePathArray($paths);`
`136`		`- }`
`137`		`-`
`138`	`133`	`protected static function filesystem(): \Illuminate\Filesystem\Filesystem`
`139`	`134`	`{`
`140`	`135`	`return File::getFacadeRoot();`
Original file line number	Diff line number	Diff line change
`@@ -9,7 +9,7 @@`
`9`	`9`	`use Illuminate\Support\Collection;`
`10`	`10`
`11`	`11`	`/**`
`12`		`- * @internal Base class for the kernel auto-discovery collections.`
	`12`	`+ * Base class for the kernel auto-discovery collections.`
`13`	`13`	`*`
`14`	`14`	`* @see \Hyde\Foundation\FileCollection`
`15`	`15`	`* @see \Hyde\Foundation\PageCollection`
Original file line number	Diff line number	Diff line change
`@@ -73,7 +73,7 @@ public function sitePath(string $path = ''): string`
`73`	`73`	`return $this->filesystem->sitePath($path);`
`74`	`74`	`}`
`75`	`75`
`76`		`- public function pathToAbsolute(string $path): string`
	`76`	`+ public function pathToAbsolute(array\|string $path): array\|string`
`77`	`77`	`{`
`78`	`78`	`return $this->filesystem->pathToAbsolute($path);`
`79`	`79`	`}`
Original file line number	Diff line number	Diff line change
`@@ -4,8 +4,16 @@`
`4`	`4`
`5`	`5`	`namespace Hyde\Framework\Actions;`
`6`	`6`
	`7`	`+use function explode;`
	`8`	`+use function file_get_contents;`
`7`	`9`	`use Hyde\Hyde;`
	`10`	`+use function json_decode;`
`8`	`11`	`use RuntimeException;`
	`12`	`+use function strlen;`
	`13`	`+use function strpos;`
	`14`	`+use function substr;`
	`15`	`+use function substr_count;`
	`16`	`+use function trim;`
`9`	`17`
`10`	`18`	`/**`
`11`	`19`	`* Parse the front matter in a Blade file.`
`@@ -69,21 +77,19 @@ public function parse(): static`
`69`	`77`
`70`	`78`	`foreach ($lines as $line) {`
`71`	`79`	`if (static::lineMatchesFrontMatter($line)) {`
`72`		`- $this->matter[static::extractKey($line)] = static::normalizeValue(static::extractValue($line));`
	`80`	`+ $this->matter[static::extractKey($line)] = static::getValueWithType(static::extractValue($line));`
`73`	`81`	`}`
`74`	`82`	`}`
`75`	`83`
`76`	`84`	`return $this;`
`77`	`85`	`}`
`78`	`86`
`79`		`- /** @internal */`
`80`		`- public static function lineMatchesFrontMatter(string $line): bool`
	`87`	`+ protected static function lineMatchesFrontMatter(string $line): bool`
`81`	`88`	`{`
`82`	`89`	`return str_starts_with($line, static::SEARCH);`
`83`	`90`	`}`
`84`	`91`
`85`		`- /** @internal */`
`86`		`- public static function extractKey(string $line): string`
	`92`	`+ protected static function extractKey(string $line): string`
`87`	`93`	`{`
`88`	`94`	`// Remove search prefix`
`89`	`95`	`$key = substr($line, strlen(static::SEARCH));`
`@@ -95,8 +101,7 @@ public static function extractKey(string $line): string`
`95`	`101`	`return trim($key);`
`96`	`102`	`}`
`97`	`103`
`98`		`- /** @internal */`
`99`		`- public static function extractValue(string $line): string`
	`104`	`+ protected static function extractValue(string $line): string`
`100`	`105`	`{`
`101`	`106`	`// Trim any trailing spaces and newlines`
`102`	`107`	`$key = trim($line);`
`@@ -114,8 +119,7 @@ public static function extractValue(string $line): string`
`114`	`119`	`return trim($key);`
`115`	`120`	`}`
`116`	`121`
`117`		`- /** @internal Return the proper type for the string */`
`118`		`- public static function normalizeValue(string $value): mixed`
	`122`	`+ protected static function getValueWithType(string $value): mixed`
`119`	`123`	`{`
`120`	`124`	`$value = trim($value);`
`121`	`125`
`@@ -132,8 +136,7 @@ public static function normalizeValue(string $value): mixed`
`132`	`136`	`return json_decode($value) ?? $value;`
`133`	`137`	`}`
`134`	`138`
`135`		`- /** @internal */`
`136`		`- public static function parseArrayString(string $string): array`
	`139`	`+ protected static function parseArrayString(string $string): array`
`137`	`140`	`{`
`138`	`141`	`$array = [];`
`139`	`142`
`@@ -153,7 +156,7 @@ public static function parseArrayString(string $string): array`
`153`	`156`	`// Remove opening and closing brackets`
`154`	`157`	`$string = substr($string, 1, strlen($string) - 2);`
`155`	`158`
`156`		`- // tokenize string between commas`
	`159`	`+ // Tokenize string between commas`
`157`	`160`	`$tokens = explode(',', $string);`
`158`	`161`
`159`	`162`	`// Parse each token`
`@@ -162,7 +165,7 @@ public static function parseArrayString(string $string): array`
`162`	`165`	`$pair = explode('=>', $entry);`
`163`	`166`
`164`	`167`	`// Add key/value pair to array`
`165`		`- $array[static::normalizeValue(trim(trim($pair[0]), "'"))] = static::normalizeValue(trim(trim($pair[1]), "'"));`
	`168`	`+ $array[static::getValueWithType(trim(trim($pair[0]), "'"))] = static::getValueWithType(trim(trim($pair[1]), "'"));`
`166`	`169`	`}`
`167`	`170`
`168`	`171`	`return $array;`
Original file line number	Diff line number	Diff line change
`@@ -36,8 +36,10 @@ public function then(): void`
`36`	`36`	`$this->createdSiteFile(DocumentationSearchService::$filePath)->withExecutionTime();`
`37`	`37`	`}`
`38`	`38`
`39`		`- /** @internal Estimated processing time per file in ms */`
`40`		`- public static float $guesstimationFactor = 52.5;`
	`39`	`+ /**`
	`40`	`+ * Estimated processing time per file in ms.`
	`41`	`+ */`
	`42`	`+ protected static float $guesstimationFactor = 52.5;`
`41`	`43`
`42`	`44`	`protected function guesstimateGenerationTime(): int\|float`
`43`	`45`	`{`
Original file line number	Diff line number	Diff line change
`@@ -59,7 +59,6 @@ public function renderFooter(): HtmlString`
`59`	`59`	`return new HtmlString($this->footer);`
`60`	`60`	`}`
`61`	`61`
`62`		`- /** @internal */`
`63`	`62`	`protected function process(): self`
`64`	`63`	`{`
`65`	`64`	`$this->tokenize();`