Merge pull request #110 from musimana/11.x

11.8.2

.docs/INSTALL.md

@@ -1,5 +1,9 @@
 # INSTALLING THE PROJECT
 
+These instructions cover set-up for a local environment, for details about other environments see the [release docs](RELEASE.md).
+
+All commands listed should be run from the local repo's root directory.
+
 ## Requirements
 
 * [Composer](https://getcomposer.org/download)
@@ -15,6 +19,8 @@ The recommended options for this are [Laragon](https://laragon.org/download/inde
 
 ## Installation
 
+### Dependencies
+
 Once the repo is forked and then cloned to a local repository, install the project's dependencies by running the following:
 
 ```sh
@@ -25,12 +31,7 @@ $ npm i
 # up to date, audited... // Exact message depends on the state of the local environment
 ```
 
-Set-up the app's database with the default content found in the [seeds directory](../storage/app/seeds/) with:
-
-```sh
-$ php artisan migrate --seed
-# INFO  Preparing database...
-```
+### Environment Configuration
 
 Then create the local [Dotenv](./.env) with:
 
@@ -41,6 +42,22 @@ $ cp .env.example .env && php artisan key:generate
 
 Review the properties in the local [Dotenv](./.env) to ensure they are set-up to match the desired environment.
 
+### Database Initialisation
+
+Ensure a local database file exists with:
+
+```sh
+$ touch database/database.sqlite
+# ... {creates the file if it doesn't exist}
+```
+
+Set-up the app's database with the default content found in the [seeds directory](../storage/app/seeds/) with:
+
+```sh
+$ php artisan migrate --seed
+# INFO  Preparing database...
+```
+
 ---
 
 |                                                                                                                                          Next|

.docs/RELEASE.md

@@ -1,9 +1,63 @@
 # RELEASE PROCESS
 
+## Versioning Policy
+
 New versions are named in accordance with the [SemVer](http://semver.org/) conventions, and are identified by tagged releases on the repository.
-A new tag is created for each release with the new tag and the title of the release in the format `v1.0.0`, where the digits indicate the SemVer version.
+A new tag is created for each release, with the new tag and the title of the release in the format `v1.0.0`, where the digits indicate the SemVer version.
 The convention is to use the generated release notes feature, with pre-releases marked as appropriate.
 
+Each merge to main should tagged as a new version on the repo.
+
+### Major Versions & Breaking Changes
+
+Major versions for this OS repo are tied to the major version of Laravel used for the framework and the PHP versions supported by that Laravel version.
+
+Minor versions of this template intentionally include changes to things like the directory structure and available namespaces;
+method names, parameters & return types; and front-end templates.
+Each minor version is tested to ensure it's stability but no support is provided for updating an existing instance of the template to a later version of it.
+The template is provided as is, but without restrictions on how you can use it.
+
+## Production Environment Installation
+
+The specifics of the following depend on your hosting provider but are provided as a loose checklist.
+
+Check correct version of PHP is installed -> see the Laravel deployment docs for standard PHP extensions.
+
+Also check that `Git`, `Composer`; `Node.js`, `npm`, `rsync`; are installed with a sufficient version.
+
+### Installing NVM
+
+Node versions on Linux distributions should be normally be managed with [NVM](https://github.com/nvm-sh/nvm?tab=readme-ov-file#installing-and-updating).
+
+### Environment Configuration
+
+#### DotEnv First Time Steps
+
+* `cp .env.example .env` -> `vim .env` and then update all values, `APP_ENV` must be `production` before next step
+* `php artisan key:generate`
+
+### Dependency Installation
+
+* `cd` into the newly created directory and run `composer install --no-dev --optimize-autoloader`
+* Install the node packages with `npm install --only=prod`
+
+### Database Set-Up
+
+#### Database First Time Steps
+
+* Create the database with `touch database/database.sqlite`
+* Run the migrations with `php artisan migrate --force --seed`
+
+#### Database Standard Steps
+
+* Run any new migrations with `php artisan migrate --force`
+
+### Optimisation
+
+* Run `php artisan optimize`
+* Restart workers
+* Restart FPM
+
 ---
 
 |Prev                                                                                                                                          |

.docs/TESTING.md

@@ -34,15 +34,6 @@ Whether the tests use Dark Mode is dependent on the relevant OS settings.
 
 ## One Time Set-Up
 
-### Unit Tests Set-Up
-
-Run the following to create a `database.sqlite` file for unit tests:
-
-```sh
-$ touch database/database.sqlite
-# ... {creates the database}
-```
-
 ### Integraion Tests Set-Up
 
 Make sure the `APP_URL` variable in the [DotEnv](/.env) file matches the URL used to access the app in a browser locally.

README.md

@@ -30,7 +30,16 @@ See the [testing docs](.docs/TESTING.md) for info on running the project's test
 
 ## Releases
 
-See the [release instructions](.docs/RELEASE.md) for info on running deployments.
+See the [release instructions](.docs/RELEASE.md) for info on releases & running deployments.
+
+### Backwards Compatibility
+
+Since the repo is offered as a template, it is offered on the basis that once an instance of it has been generated,
+there will be no attempts to maintain backwards compatibility between the instance and this repo.
+This means you are free to use the generated instance however you wish,
+but that there is no native mechanism for updating any given instance to match later versions of this template repository.
+
+For more info on this see the [Versioning Policy](.docs/RELEASE.md#versioning-policy).
 
 ## License
 

app/Http/Resources/Models/UserModelResource.php

@@ -11,8 +11,7 @@ final class UserModelResource implements UserStorableInterface
     /** Instantiate the resource. */
     public function __construct(
         protected User $user = new User
-    ) {
-    }
+    ) {}
 
     /** Get the user model. */
     public function getItem(): User

app/Http/Resources/Views/Admin/Blocks/AdminBlockResource.php

@@ -11,8 +11,7 @@ final class AdminBlockResource implements ConstantItemInterface
     /** Instantiate the resource. */
     public function __construct(
         protected Block $block = new Block
-    ) {
-    }
+    ) {}
 
     /**
      * Get the content array for the resource's block.

app/Http/Resources/Views/MetadataViewResource.php

@@ -6,6 +6,7 @@
 use App\Http\Resources\Views\Navbars\DesktopNavbarResource;
 use App\Http\Resources\Views\Navbars\MobileNavbarResource;
 use App\Interfaces\Resources\Items\ArrayToItemInterface;
+use App\Models\Navbar;
 use Illuminate\Support\Facades\Route;
 
 final class MetadataViewResource implements ArrayToItemInterface
@@ -20,6 +21,8 @@ final class MetadataViewResource implements ArrayToItemInterface
      */
     public function getItem(array $metadata): array
     {
+        $navbar = Navbar::with('items')->first();
+
         $standard_metadata = [
             'appName' => config('app.name'),
             'canLogin' => Route::has('login'),
@@ -28,8 +31,8 @@ public function getItem(array $metadata): array
             'copyright' => (new CopyrightFormatterResource)->getValue(),
             'description' => config('metadata.description'),
             'links' => config('metadata.social_links'),
-            'navbarDesktop' => (new DesktopNavbarResource)->getItems(),
-            'navbarMobile' => (new MobileNavbarResource)->getItems(),
+            'navbarDesktop' => $navbar ? (new DesktopNavbarResource($navbar))->getItems() : [],
+            'navbarMobile' => $navbar ? (new MobileNavbarResource($navbar))->getItems() : [],
             'title' => config('app.name'),
         ];
 

app/Http/Resources/Views/Navbars/DesktopNavbarResource.php

@@ -7,17 +7,27 @@
 
 final class DesktopNavbarResource implements ConstantIndexInterface
 {
+    /** Instantiate the resource. */
+    public function __construct(
+        protected Navbar $navbar = new Navbar
+    ) {}
+
     /**
      * Get the items for the main public navbar.
      *
-     * @return array<int, array<string, array<int, array<string, string>>|string>>
+     * @return array<int, array{
+     *  title: string,
+     *  url: string,
+     *  subItems: array<int, array{title: string, url: string}>
+     * }>
      */
     public function getItems(): array
     {
-        $navbar_items = Navbar::first()?->items ?? collect();
-
-        return $navbar_items
-            ->map(fn ($page) => (new ItemLinksNavbarResource)->getItem($page))
-            ->toArray();
+        return array_filter(
+            $this->navbar->items
+                ->map(fn ($navbar_item) => (new ItemLinksNavbarResource($navbar_item))->getItem())
+                ->toArray(),
+            fn ($navbar_item) => $navbar_item !== []
+        );
     }
 }

app/Http/Resources/Views/Navbars/ItemLinksNavbarResource.php

@@ -2,38 +2,48 @@
 
 namespace App\Http\Resources\Views\Navbars;
 
-use App\Interfaces\Resources\Items\NavbarItemInterface;
+use App\Interfaces\Resources\Items\ConstantItemInterface;
 use App\Models\NavbarItem;
 
-final class ItemLinksNavbarResource implements NavbarItemInterface
+final class ItemLinksNavbarResource implements ConstantItemInterface
 {
+    /** Instantiate the resource. */
+    public function __construct(
+        protected NavbarItem $navbar_item = new NavbarItem
+    ) {}
+
     /**
      * Get the content array for the given page's public link.
      *
-     * @return array<string, null|string|array<string, null|string>>
+     * @return array{}|array{
+     *  title: string,
+     *  url: string|null,
+     *  subItems: array<int, array{title: string, url: string}>
+     * }
      */
-    public function getItem(NavbarItem $navbar_item): array
+    public function getItem(): array
     {
-        $title = $navbar_item->getTitle();
+        $title = $this->navbar_item->getTitle();
+        $url = $this->navbar_item->getUrl();
 
         if (!$title) {
             return [];
         }
 
         $sub_items = array_filter(
-            $navbar_item->children->map(fn ($subitem) => self::getItem($subitem))->toArray(),
-            fn ($subitem) => $subitem !== []
+            $this->navbar_item->children->map(
+                fn ($sub_item) => [
+                    'title' => $sub_item->getTitle(),
+                    'url' => $sub_item->getUrl(),
+                ]
+            )->toArray(),
+            fn ($sub_item) => $sub_item['title'] && $sub_item['url']
         );
 
-        return $sub_items
-            ? [
-                'title' => $title,
-                'url' => $navbar_item->getUrl(),
-                'subItems' => $sub_items,
-            ]
-            : [
-                'title' => $title,
-                'url' => $navbar_item->getUrl(),
-            ];
+        return [
+            'title' => $title,
+            'url' => $url,
+            'subItems' => $sub_items,
+        ];
     }
 }

app/Http/Resources/Views/Navbars/MobileNavbarResource.php

@@ -7,17 +7,25 @@
 
 final class MobileNavbarResource implements ConstantIndexInterface
 {
+    /** Instantiate the resource. */
+    public function __construct(
+        protected Navbar $navbar = new Navbar
+    ) {}
+
     /**
      * Get the items for the main public navbar.
      *
-     * @return array<int, array<string, string>>
+     * @return array<int, array{
+     *  title: string,
+     *  url: string,
+     * }>
      */
     public function getItems(): array
     {
-        $navbar_items = Navbar::first()?->items ?? collect();
-        $navbar_items = $navbar_items
-            ->map(fn ($page) => (new ItemLinksNavbarResource)->getItem($page))
+        $navbar_items = $this->navbar->items
+            ->map(fn ($navbar_item) => (new ItemLinksNavbarResource($navbar_item))->getItem())
             ->toArray();
+
         $navbar_items_filtered = [];
 
         foreach ($navbar_items as $navbar_item) {
@@ -29,7 +37,6 @@ public function getItems(): array
             }
 
             if ($navbar_item['subItems'] ?? false) {
-                /** @var array<int, array<string, string>> $navbar_items_filtered */
                 $navbar_items_filtered = [
                     ...$navbar_items_filtered,
                     ...$navbar_item['subItems'],

app/Http/Resources/Views/Public/Blocks/BlockResource.php

@@ -10,8 +10,7 @@ final class BlockResource implements ConstantItemInterface
     /** Instantiate the resource. */
     public function __construct(
         protected Block $block = new Block
-    ) {
-    }
+    ) {}
 
     /**
      * Get the content array for the resource's block.

app/Models/Navbar.php

@@ -21,13 +21,17 @@ final class Navbar extends Model
         'title',
     ];
 
-    /** Get the subtitle for the page. */
+    /** Get the title for the navbar. */
     public function getTitle(): string
     {
         return $this->title ?? '';
     }
 
-    /** The relationship for the navbar's items. */
+    /**
+     * The relationship for the navbar's items.
+     *
+     * @return HasMany<NavbarItem>
+     */
     public function items(): HasMany
     {
         return $this->hasMany(NavbarItem::class)