Merge pull request #1732 from hydephp/2x-datacollections-improvements

[2.x] DataCollections improvements

RELEASE_NOTES.md

@@ -12,20 +12,23 @@ This serves two purposes:
 ### Added
 - You can now specify navigation priorities by adding a numeric prefix to the source file names in https://github.com/hydephp/develop/pull/1709
 - Added a new `\Hyde\Framework\Actions\PreBuildTasks\TransferMediaAssets` build task handle media assets transfers for site builds.
+- Added a new `\Hyde\Framework\Exceptions\ParseException` exception class to handle parsing exceptions in data collection files in https://github.com/hydephp/develop/pull/1732
 - The `\Hyde\Facades\Features` class is no longer marked as internal, and is now thus part of the public API.
 
 ### Changed
 - **Breaking:** The internals of the navigation system has been rewritten into a new Navigation API. This change is breaking for custom navigation implementations. For more information, see below.
 - **Breaking:** The `hyde.features` configuration format has changed to use Enums instead of static method calls. For more information, see below.
+- **Breaking:** Renamed class `DataCollections` to `DataCollection`. For more information, see below.
 - Minor: Navigation menu items are now no longer filtered by duplicates (meaning two items with the same label can now exist in the same menu) in https://github.com/hydephp/develop/pull/1573
 - Minor: Due to changes in the navigation system, it is possible that existing configuration files will need to be adjusted in order for menus to look the same (in terms of ordering etc.)
 - Minor: The documentation article component now supports disabling the semantic rendering using a falsy value in https://github.com/hydephp/develop/pull/1566
 - Minor: Changed the default build task message to make it more concise in https://github.com/hydephp/develop/pull/1659
+- Minor: Data collection files are now validated for syntax errors during discovery in https://github.com/hydephp/develop/pull/1732
 - The `hasFeature` method on the Hyde facade and HydeKernel now only accepts a Feature enum value instead of a string for its parameter.
 - Changed how the documentation search is generated, to be an `InMemoryPage` instead of a post-build task.
 - Media asset files are now copied using the new build task instead of the deprecated `BuildService::transferMediaAssets()` method.
 - Calling the `Include::path()` method will no longer create the includes directory in https://github.com/hydephp/develop/pull/1707
-
+- Calling the `DataCollection` methods will no longer create the data collections directory in https://github.com/hydephp/develop/pull/1732
 
 ### Deprecated
 - for soon-to-be removed features.
@@ -173,6 +176,7 @@ Due to the scope of the rewrite, the easiest and fastest way to upgrade your cod
 
 - For a full comparison of the changes, you may see the PR that introduced the new API: https://github.com/hydephp/develop/pull/1568/files
 - For information on how to use the new Navigation API, see the documentation: https://hydephp.com/docs/2.x/navigation-api
+- If you use DataCollections, you should read the upgrade path below as there are breaking changes to the DataCollection API.
 
 ### HTML ID changes
 
@@ -216,3 +220,33 @@ For example, if you triggered the media transfer with a build service method cal
 
 (new TransferMediaAssets())->run();
 ```
+
+### DataCollection API changes
+
+The DataCollection feature has been reworked to improve the developer experience and make it more consistent with the rest of the API.
+
+Unfortunately, this means that existing setups may need to be adjusted to work with the new API.
+
+#### Upgrade guide
+
+- The `DataCollections` class has been renamed to `DataCollection`. If you have used the `DataCollections` class in your code, you will need to update your code to use the new class name.
+
+#### Changes
+
+- Calling the `DataCollection` methods will no longer create the data collections directory automatically.
+- The `DataCollection` class now validates the syntax of all data collection files during discovery, and throws a `ParseException` if the syntax is invalid.
+
+#### Issues that may arise
+
+If you start getting a `ParseException` when using the `DataCollection` class, it may be due to malformed data collection files.
+Starting from this version, we validate the syntax of JSON and YAML in data files during discovery, including any front matter in Markdown data files. 
+We do this to help you catch errors early. See https://github.com/hydephp/develop/issues/1736 for more information.
+
+For example, an empty or malformed JSON file will now throw an exception like this:
+
+```php
+\Hyde\Framework\Exceptions\ParseException: Invalid JSON in file: 'foo/baz.json' (Syntax error)
+```
+
+In order to normalize the thrown exceptions, we now rethrow the `ParseException` from `Symfony/Yaml` as our custom `ParseException` to match the JSON and Markdown validation.
+Additionally, an exception will be thrown if a data file is empty, as this is unlikely to be intentional. Markdown files can have an empty body if front matter is present.

_ide_helper.php

@@ -40,7 +40,7 @@ class Features extends \Hyde\Facades\Features {}
 class Config extends \Hyde\Facades\Config {}
 /** @mixin \Illuminate\Filesystem\Filesystem */
 class Filesystem extends \Hyde\Facades\Filesystem {}
-class DataCollections extends \Hyde\Support\DataCollections {}
+class DataCollection extends \Hyde\Support\DataCollection {}
 class Includes extends \Hyde\Support\Includes {}
 /** @mixin \Hyde\Foundation\Kernel\RouteCollection */
 class Routes extends \Hyde\Foundation\Facades\Routes {}

app/config.php

@@ -103,7 +103,7 @@
         'MarkdownPage' => \Hyde\Pages\MarkdownPage::class,
         'MarkdownPost' => \Hyde\Pages\MarkdownPost::class,
         'DocumentationPage' => \Hyde\Pages\DocumentationPage::class,
-        'DataCollections' => \Hyde\Support\DataCollections::class,
+        'DataCollection' => \Hyde\Support\DataCollection::class,
         'Includes' => \Hyde\Support\Includes::class,
         'Feature' => \Hyde\Enums\Feature::class,
     ],

docs/digging-deeper/collections.md

@@ -8,7 +8,7 @@ navigation:
 
 ## Introduction to Hyde Data Collections
 
-Hyde provides `DataCollections`, a subset of [Laravel Collections](https://laravel.com/docs/10.x/collections) giving you a similar developer experience to working with Eloquent Collections.
+Hyde provides `DataCollection`, a subset of [Laravel Collections](https://laravel.com/docs/10.x/collections) giving you a similar developer experience to working with Eloquent Collections.
 However, instead of accessing a database, it's all entirely file-based using static data files such as Markdown, Yaml, and JSON files which get
 parsed into objects that you can easily work with.
 
@@ -24,15 +24,14 @@ In short, HydePHP finds files in the specified directory, turns each file into a
 To make collections easy to use and understand, Hyde makes a few assumptions about the structure of your collections.
 Follow these conventions and creating dynamic static sites will be a breeze.
 
-1. Collections are accessed through static methods in the `DataCollections` class.
+1. Collections are accessed through static methods in the `DataCollection` class.
 2. Collections are stored as files in subdirectories of the `resources/collections` directory.
 3. To get a collection, specify name of the subdirectory the files are stored in.
 4. Data will be parsed into differing objects depending on which facade method you use. See the table below.
 5. The class is aliased so that you can use it in Blade files without having to include the namespace.
 6. While not enforced, each subdirectory should probably only have the same filetype to prevent developer confusion.
 7. Unlike source files for pages, files starting with underscores are not ignored.
 8. You can customize the source directory for collections through a service provider.
-9. If the base source directory does not exist, it will be created for you.
 
 
 ## Available Collection Types
@@ -42,9 +41,9 @@ Follow these conventions and creating dynamic static sites will be a breeze.
 The following facade methods for creating data collections are available:
 
 ```php
-\Hyde\Support\DataCollections::markdown(string $name);
-\Hyde\Support\DataCollections::yaml(string $name);
-\Hyde\Support\DataCollections::json(string $name, bool $asArray = false);
+\Hyde\Support\DataCollection::markdown(string $name);
+\Hyde\Support\DataCollection::yaml(string $name);
+\Hyde\Support\DataCollection::json(string $name, bool $asArray = false);
 ```
 
 ### Quick Reference Table
@@ -61,15 +60,15 @@ The following facade methods for creating data collections are available:
 ### Usage
 
 ```php
-$collection = \Hyde\Support\DataCollections::markdown('name');
+$collection = \Hyde\Support\DataCollection::markdown('name');
 ```
 
 ### Example returns
 
 Here is an approximation of the data types contained by the variable created above:
 
 ```php
-\Hyde\Support\DataCollections {
+\Hyde\Support\DataCollection {
     "testimonials/1.md" => Hyde\Markdown\Models\MarkdownDocument
     "testimonials/2.md" => Hyde\Markdown\Models\MarkdownDocument
     "testimonials/3.md" => Hyde\Markdown\Models\MarkdownDocument
@@ -108,15 +107,15 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit...
 ### Usage
 
 ```php
-$collection = \Hyde\Support\DataCollections::yaml('name');
+$collection = \Hyde\Support\DataCollection::yaml('name');
 ```
 
 ### Example returns
 
 Here is an approximation of the data types contained by the variable created above:
 
 ```php
-\Hyde\Support\DataCollections {
+\Hyde\Support\DataCollection {
   "authors/1.yaml" => Hyde\Markdown\Models\FrontMatter {
     +data: array:1 [
       "name" => "John Doe",
@@ -129,26 +128,22 @@ Here is an approximation of the data types contained by the variable created abo
 Assuming the Yaml document looks like this:
 
 ```yaml
----
 name: "John Doe"
 email: "[email protected]"
 ```
 
->warning Note that the Yaml file should start with `---` to be parsed correctly.
-
-
 ## Json Collections
 
 ### Usage
 
 ```php
-$collection = \Hyde\Support\DataCollections::json('name');
+$collection = \Hyde\Support\DataCollection::json('name');
 ```
 
 By default, the entries will be returned as `stdClass` objects. If you want to return an associative array instead, pass `true` as the second parameter:
 
 ```php
-$collection = \Hyde\Support\DataCollections::json('name', true);
+$collection = \Hyde\Support\DataCollection::json('name', true);
 ```
 
 Since both return values use native PHP types, there are no example returns added here, as I'm sure you can imagine what they look like.
@@ -191,18 +186,18 @@ resources/collections
 
 #### Using the Facade to Access the Collections
 
-Now for the fun part! We will use the `DataCollections::markdown()` to access all our files into a convenient object.
+Now for the fun part! We will use the `DataCollection::markdown()` to access all our files into a convenient object.
 The class is registered with an alias, so you don't need to include any namespaces when in a Blade file.
 
 The general syntax to use the facade is as follows:
 
 ```blade
-DataCollections::markdown('subdirectory_name')
+DataCollection::markdown('subdirectory_name')
 ```
 
-This will return a Hyde DataCollections object, containing our Markdown files as MarkdownDocument objects. Here is a quick look at the object the facade returns:
+This will return a Hyde DataCollection object, containing our Markdown files as MarkdownDocument objects. Here is a quick look at the object the facade returns:
 
-<pre style="display: block; white-space: pre-wrap; padding: 1rem 1.5rem; overflow: initial !important; background-color: rgb(24, 23, 27); color: rgb(255, 132, 0); font: 400 12px Menlo, Monaco, Consolas, monospace; overflow-wrap: break-word; position: relative; z-index: 99999; word-break: break-all; letter-spacing: normal; orphans: 2; text-align: start; text-indent: 0px; text-transform: none; widows: 2; word-spacing: 0px; -webkit-text-stroke-width: 0px; text-decoration-thickness: initial; text-decoration-style: initial; text-decoration-color: initial;"><span class="sf-dump-default" style="display: inline; background-color: rgb(24, 23, 27); color: rgb(255, 132, 0); font: 12px Menlo, Monaco, Consolas, monospace; overflow-wrap: break-word; white-space: pre-wrap; position: relative; z-index: 99999; word-break: break-all;">^</span><span class="sf-dump-default" style="display: inline; background-color: rgb(24, 23, 27); color: rgb(255, 132, 0); font: 12px Menlo, Monaco, Consolas, monospace; overflow-wrap: break-word; white-space: pre-wrap; position: relative; z-index: 99999; word-break: break-all;"> </span><span style="display: inline; color: rgb(18, 153, 218);">Hyde\Support\DataCollections</span> {<span style="text-decoration: none; border: 0px; outline: none; color: rgb(160, 160, 160);">#651 <span style="display: inline;">▼</span></span><samp>
+<pre style="display: block; white-space: pre-wrap; padding: 1rem 1.5rem; overflow: initial !important; background-color: rgb(24, 23, 27); color: rgb(255, 132, 0); font: 400 12px Menlo, Monaco, Consolas, monospace; overflow-wrap: break-word; position: relative; z-index: 99999; word-break: break-all; letter-spacing: normal; orphans: 2; text-align: start; text-indent: 0px; text-transform: none; widows: 2; word-spacing: 0px; -webkit-text-stroke-width: 0px; text-decoration-thickness: initial; text-decoration-style: initial; text-decoration-color: initial;"><span class="sf-dump-default" style="display: inline; background-color: rgb(24, 23, 27); color: rgb(255, 132, 0); font: 12px Menlo, Monaco, Consolas, monospace; overflow-wrap: break-word; white-space: pre-wrap; position: relative; z-index: 99999; word-break: break-all;">^</span><span class="sf-dump-default" style="display: inline; background-color: rgb(24, 23, 27); color: rgb(255, 132, 0); font: 12px Menlo, Monaco, Consolas, monospace; overflow-wrap: break-word; white-space: pre-wrap; position: relative; z-index: 99999; word-break: break-all;"> </span><span style="display: inline; color: rgb(18, 153, 218);">Hyde\Support\DataCollection</span> {<span style="text-decoration: none; border: 0px; outline: none; color: rgb(160, 160, 160);">#651 <span style="display: inline;">▼</span></span><samp>
   #<span style="display: inline; color: rgb(255, 255, 255);">items</span>: <span style="display: inline; color: rgb(18, 153, 218);">array:3</span> [<span style="text-decoration: none; border: 0px; outline: none; color: rgb(160, 160, 160);"><span style="display: inline;">▼</span></span><samp>
     "<span style="display: inline; color: rgb(86, 219, 58);">testimonials/1.md</span>" =&gt; <span style="display: inline; color: rgb(18, 153, 218);"><span>Hyde\Markdown\Models</span><span style="display: inline-block; text-overflow: ellipsis; max-width: none; white-space: nowrap; overflow: hidden; vertical-align: top; color: rgb(18, 153, 218);">\</span>MarkdownDocument</span> {<span style="text-decoration: none; border: 0px; outline: none; color: rgb(160, 160, 160);">#653 <span style="display: inline;">▼</span></span><samp>
       +<span style="display: inline; color: rgb(255, 255, 255);">matter</span>: <span style="display: inline; color: rgb(18, 153, 218);"><span>Hyde\Markdown\Models</span><span style="display: inline-block; text-overflow: ellipsis; max-width: none; white-space: nowrap; overflow: hidden; vertical-align: top; color: rgb(18, 153, 218);">\</span>FrontMatter</span> {<span style="text-decoration: none; border: 0px; outline: none; color: rgb(160, 160, 160);">#652 <span style="display: inline;">▶</span></span>}
@@ -227,7 +222,7 @@ we are able to get the author from the front matter, and the content from the bo
 
 ```blade
 // filepath _pages/testimonials.blade.php
-@foreach(DataCollections::markdown('testimonials') as $testimonial)
+@foreach(DataCollection::markdown('testimonials') as $testimonial)
     <blockquote>
         <p>{{ $testimonial->body }}</p>
         <small>{{ $testimonial->matter['author'] }}</small>

docs/digging-deeper/helpers.md

@@ -14,20 +14,20 @@ Note that these helpers targets those who write custom code and Blade templates,
 
 ## File-based Collections
 
-Hyde provides `DataCollections`, a subset of [Laravel Collections](https://laravel.com/docs/10.x/collections) giving you a similar developer experience to working with Eloquent Collections. However, instead of accessing a database,
+Hyde provides `DataCollection`, a subset of [Laravel Collections](https://laravel.com/docs/10.x/collections) giving you a similar developer experience to working with Eloquent Collections. However, instead of accessing a database,
 it's all entirely file-based using static data files such as Markdown, Yaml, and JSON files which get parsed into objects that you can easily work with.
 
 ```php
-use Hyde\Support\DataCollections;
+use Hyde\Support\DataCollection;
 
 // Gets all Markdown files in resources/collections/$name directory
-DataCollections::markdown(string $name);
+DataCollection::markdown(string $name);
 
 // Gets all YAML files in resources/collections/$name directory
-DataCollections::yaml(string $name);
+DataCollection::yaml(string $name);
 
 // Gets all JSON files in resources/collections/$name directory
-DataCollections::json(string $name, bool $asArray = false);
+DataCollection::json(string $name, bool $asArray = false);
 ```
 
 See the [File-based Collections](collections) documentation for the full details.

packages/framework/src/Framework/Exceptions/ParseException.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hyde\Framework\Exceptions;
+
+use Throwable;
+use RuntimeException;
+use Illuminate\Support\Arr;
+
+use function rtrim;
+use function sprintf;
+use function explode;
+
+/** @experimental This class may change significantly before its release. */
+class ParseException extends RuntimeException
+{
+    /** @var int */
+    protected $code = 422;
+
+    public function __construct(string $file = '', ?Throwable $previous = null)
+    {
+        parent::__construct($this->formatMessage($file, $previous), previous: $previous);
+    }
+
+    protected function formatMessage(string $file, ?Throwable $previous): string
+    {
+        return rtrim(sprintf('Invalid %s in file%s %s', $this->getTypeLabel($file), $this->getFileLabel($file), $this->getContext($previous)));
+    }
+
+    protected function getTypeLabel(string $file): string
+    {
+        return match (Arr::last(explode('.', $file))) {
+            'md' => 'Markdown',
+            'yaml', 'yml' => 'Yaml',
+            'json' => 'Json',
+            default => 'data',
+        };
+    }
+
+    protected function getFileLabel(string $file): string
+    {
+        return $file ? sprintf(": '%s'", $file) : '';
+    }
+
+    protected function getContext(?Throwable $previous): string
+    {
+        return ($previous && $previous->getMessage()) ? sprintf('(%s)', rtrim($previous->getMessage(), '.')) : '';
+    }
+}