Merge pull request #221 from aedart/update-docs

Update docs for version 9.x

CHANGELOG_v9x.md

@@ -35,6 +35,7 @@ TODO: Temporary changelog file for the upcoming major version `9.x`.
 * "Split Packages" GitHub workflow no longer triggered in pull requests.
 * Class constants now have [types](https://php.watch/versions/8.3/typed-constants) declared.
 * `\Aedart\Console\Commands\PirateTalkCommand` now uses `\Aedart\Utils\Arr::randomizer()->value()` to pick random sentence.
+* Simplified the "Available Helpers" (_Laravel "Aware-of" helpers_) documentation.
 
 ### Fixed
 

docs/.vuepress/archive/Version9x.ts

@@ -75,10 +75,18 @@ export default PagesCollection.make('v9.x', '/v9x', [
                 children: [
                     'auth/fortify/', // Prerequisites
                     {
-                        text: 'Actions',
+                        text: 'Exceptions',
                         collapsible: true,
                         children: [
-                            'auth/fortify/actions/rehash-password',
+                            'auth/fortify/exceptions/failed-login-attempt',
+                            'auth/fortify/exceptions/pass-reset-link-failure',
+                        ]
+                    },
+                    {
+                        text: 'Responses',
+                        collapsible: true,
+                        children: [
+                            'auth/fortify/responses/failed-pass-reset-link',
                         ]
                     },
                 ]
@@ -590,6 +598,7 @@ export default PagesCollection.make('v9.x', '/v9x', [
                     'support/laravel/available-helpers',
                 ]
             },
+            'support/env-file',
             {
                 text: 'Aware-of Properties',
                 collapsible: true,

docs/.vuepress/archive/index.ts

@@ -9,20 +9,21 @@ import Version6x from "./Version6x";
 import Version7x from "./Version7x";
 import Version8x from "./Version8x";
 import Version9x from "./Version9x";
+import Version10x from "./Version10x";
 
 /**
  * The "current" version
  *
  * @type {PagesCollection}
  */
-const CURRENT: PagesCollection = Version8x;
+const CURRENT: PagesCollection = Version9x;
 
 /**
  * The "next" version
  *
  * @type {PagesCollection}
  */
-const NEXT: PagesCollection = Version9x;
+const NEXT: PagesCollection = Version10x;
 
 /**
  * List of versions
@@ -32,6 +33,7 @@ const NEXT: PagesCollection = Version9x;
 const VERSIONS: PagesCollection[] = [
     NEXT,
     CURRENT,
+    Version8x,
     Version7x,
     Version6x,
     Version5x,

docs/archive/current/README.md

@@ -9,13 +9,14 @@ sidebarDepth: 0
 
 ## Support Policy
 
-Athenaeum attempts to follow a release cycle that matches closely to that of [Laravel](https://laravel.com/docs/11.x/releases).
+Athenaeum attempts to follow a release cycle that matches closely to that of [Laravel](https://laravel.com/docs/12.x/releases).
 However, due to limited amount of project maintainers, no guarantees can be provided. 
 
 | Version | PHP         | Laravel | Release              | Security Fixes Until |
 |---------|-------------|---------|----------------------|----------------------|
-| `9.x`   | `8.3 - ?`   | `v12.x` | _~1st Quarter 2025_  | _TBD_                |
-| `8.x`*  | `8.2 - 8.3` | `v11.x` | Match 18th, 2024     | February 2025        |
+| `10.x`  | `8.4 - ?`   | `v13.x` | _~1st Quarter 2026_  | _TBD_                |
+| `9.x`*  | `8.3 - 8.4` | `v12.x` | _~1st Quarter 2025_  | February 2026        |
+| `8.x`   | `8.2 - 8.3` | `v11.x` | Match 18th, 2024     | February 2025        |
 | `7.x`   | `8.1 - 8.2` | `v10.x` | February 16th, 2023  | March 2024           |
 | `6.x`   | `8.0 - 8.1` | `v9.x`  | April 5th, 2022      | February 2023        |
 | `< 6.x` | _-_         | _-_     | _See `CHANGELOG.md`_ | _N/A_                |
@@ -24,40 +25,51 @@ _*: current supported version._
 
 _TBD: "To be decided"._
 
-## `v8.x` Highlights
+## `v9.x` Highlights
 
 These are the highlights of the latest major version of Athenaeum.
 
-### PHP `v8.2` and Laravel `v11.x`
+### PHP `v8.3` and Laravel `v12.x`
 
-PHP version `v8.2` is now the minimum required version for Athenaeum.
-[Laravel `v10.x`](https://laravel.com/docs/11.x/releases) packages are now used.
+PHP version `v8.3` is now the minimum required version for Athenaeum.
+[Laravel `v12.x`](https://laravel.com/docs/12.x/releases) packages are now used.
 
-### Randomizers
+### Randomizer `float()`, `nextFloat()` and `bytesFromString()`
 
-`Math`, `Str` and `Arr` now offer a `randomizer()` method that returns an adapter for PHP's [`Random\Randomizer`](https://www.php.net/manual/en/class.random-randomizer.php).
+`NumericRandomizer` now supports generating random floats via [`float()`](./utils/math.md#float)
+and [`nextFloat()`](./utils/math.md#nextfloat). Additionally, the `StringRandomizer` now offers a
+[`bytesFromString()`](./utils/string.md#bytesfromstring) method.
 
-```php
-use Aedart\Utils\Arr;
+### Environment File utility
 
-$arr = [ 'a' => 1, 'b' => 2, 'c' => 3, 'd' => 4, 'e' => 5 ];
+The `EnvFile` can be used for replacing the value of an existing key, or appending a new key-value pair, in the
+application's environment file.
 
-Arr::randomizer()->values($arr, 2); // [ 5, 2 ]
-```
+See [Support package documentation](./support/env-file.md) for details.
 
-See [`Math::randomizer()`](./utils/math.md#randomizer), [`Str::randomizer()`](./utils/string.md#randomizer) and [`Arr::randomizer()`](./utils/array.md#randomizer) for additional information.
+### Auth Exceptions and Responses
 
-### Memory Snapshot
+The Auth package has received a few new components, intended to be used in combination with for Laravel Fortify.
+Among them are a few predefined exceptions and response helpers.
 
-The [`Memory::snapshot()`](./utils/memory.md#snapshot) method returns the current memory usage.
+See [Auth Fortify documentation](./auth/fortify/README.md) for details.
 
-```php
-use Aedart\Utils\Memory;
+### TOML version 1.0.0 Supported
 
-$snapshot = Memory::snapshot();
+The [configuration loader](./config/README.md) now supports [toml](https://github.com/toml-lang/toml) version `1.0.0` format.
 
-echo $snapshot->bytes(); // 544812
-```
+Please see the [upgrade guide](./upgrade-guide.md) for details.
+
+### Additional parameters for `Json::isValid()`  
+
+The `Json::isValid()` now accepts `$depth` and `$options` as optional parameters.
+
+See [documentation](./utils/json.md#validation) for details.
+
+### Deprecation of "Aware-of" Properties
+
+The ["aware-of" properties](support/properties/available-helpers.md) have been deprecated. These have served their purpose in the past, but are now no longer
+relevant. The components will be removed in the next major version. There are no plans to offer any alternatives.
 
 ## Changelog
 

docs/archive/current/acl/cache.md

@@ -77,6 +77,6 @@ class RolesController extends Controller
 ### No auto-flush offered
 
 The current ACL package does not offer any automatic way of flushing the cached permissions & roles.
-Should you require such logic, then you may accomplish this via Eloquent's [events](https://laravel.com/docs/11.x/eloquent#events) and [event observers](https://laravel.com/docs/11.x/eloquent#observers).
+Should you require such logic, then you may accomplish this via Eloquent's [events](https://laravel.com/docs/12.x/eloquent#events) and [event observers](https://laravel.com/docs/12.x/eloquent#observers).
 
 

docs/archive/current/acl/permissions.md

@@ -118,7 +118,7 @@ From the above example, the following permission slug is inserted into the datab
 ::: tip How should you name your permissions?
 If you find yourself wondering how you should name your permission slugs, perhaps you can use the same names as for your routes.
 
-See Laravel's [resource routes](https://laravel.com/docs/11.x/controllers#actions-handled-by-resource-controller) documentation for inspiration.
+See Laravel's [resource routes](https://laravel.com/docs/12.x/controllers#actions-handled-by-resource-controller) documentation for inspiration.
 :::
 
 ## Find or create behaviour

docs/archive/current/acl/roles.md

@@ -22,7 +22,7 @@ $manager = Role::create([
 ]);
 ```
 
-See Laravel's [documentation](https://laravel.com/docs/11.x/eloquent#inserting-and-updating-models) for additional information on how to create new records.
+See Laravel's [documentation](https://laravel.com/docs/12.x/eloquent#inserting-and-updating-models) for additional information on how to create new records.
 
 ### New role with permissions
 
@@ -97,7 +97,7 @@ $role->syncPermissions([
 ]);
 ```
 
-For additional information about relations synchronisation, please review Laravel's [documentation](https://laravel.com/docs/11.x/eloquent-relationships#syncing-associations).
+For additional information about relations synchronisation, please review Laravel's [documentation](https://laravel.com/docs/12.x/eloquent-relationships#syncing-associations).
 
 ## Update role with permissions
 

docs/archive/current/acl/setup.md

@@ -4,7 +4,7 @@ description: How to setup ACL
 
 # Setup
 
-In this section, setup of the ACL package is covered. It goes without saying, you should have some prior knowledge about how to work with Laravel's [Authorization](https://laravel.com/docs/11.x/authorization), before attempting to use this package's components.
+In this section, setup of the ACL package is covered. It goes without saying, you should have some prior knowledge about how to work with Laravel's [Authorization](https://laravel.com/docs/12.x/authorization), before attempting to use this package's components.
 
 [[TOC]]
 

docs/archive/current/acl/users.md

@@ -68,7 +68,7 @@ $user->syncRoles([
 ]);
 ```
 
-For additional information about relations synchronisation, please review Laravel's [documentation](https://laravel.com/docs/11.x/eloquent-relationships#syncing-associations).
+For additional information about relations synchronisation, please review Laravel's [documentation](https://laravel.com/docs/12.x/eloquent-relationships#syncing-associations).
 
 ## Check user's roles
 
@@ -102,7 +102,7 @@ echo $user->hasAnyRoles([ 'editor', 'reviewer' ]); // e.g. true (1)
 
 ## Check user's permissions
 
-During runtime, if you have defined permissions in the `AuthServiceProvider` (See [setup](./setup.md)), you can use [Laravel's builtin mechanisms](https://laravel.com/docs/11.x/authorization#authorizing-actions-using-policies) to check a user's permissions.
+During runtime, if you have defined permissions in the `AuthServiceProvider` (See [setup](./setup.md)), you can use [Laravel's builtin mechanisms](https://laravel.com/docs/12.x/authorization#authorizing-actions-using-policies) to check a user's permissions.
 
 ```php
 <?php

docs/archive/current/antivirus/usage.md

@@ -78,7 +78,7 @@ Array
 The `scan()` method accepts the following types as it's file argument: 
 
 * `string` path to file.
-* `SplFileInfo` uploaded file (_e.g. Laravel's [`UploadedFile` instance](https://laravel.com/docs/11.x/http-tests#testing-file-uploads)_).
+* `SplFileInfo` uploaded file (_e.g. Laravel's [`UploadedFile` instance](https://laravel.com/docs/12.x/http-tests#testing-file-uploads)_).
 * `FileStream` [file stream](../streams/README.md).
 * `UploadedFileInterface` [PSR-7 uploaded file](https://www.php-fig.org/psr/psr-7/#36-psrhttpmessageuploadedfileinterface) instance.
 * `StreamInterface` [PSR-7 stream](https://www.php-fig.org/psr/psr-7/#34-psrhttpmessagestreaminterface) instance.
@@ -149,7 +149,7 @@ if ($scanner->scan('contacts.txt')->isOk()) {
 
 ## Facade
 
-An alternative way of performing file scans, is by using the  `Antivirus` [Facade](https://laravel.com/docs/11.x/facades).
+An alternative way of performing file scans, is by using the  `Antivirus` [Facade](https://laravel.com/docs/12.x/facades).
 It allows you to perform a scan directly.
 
 ```php
@@ -171,7 +171,7 @@ $scanner = Antivirus::profile('my-scanner-profile');
 
 ## Validation Rule
 
-This package also comes with a custom [validation rule](https://laravel.com/docs/11.x/validation#custom-validation-rules), which can prevent upload of infected files.
+This package also comes with a custom [validation rule](https://laravel.com/docs/12.x/validation#custom-validation-rules), which can prevent upload of infected files.
 
 ```php
 use Aedart\Antivirus\Validation\Rules\InfectionFreeFile;

docs/archive/current/audit/record-changes.md

@@ -26,7 +26,7 @@ Whenever you change the model's attributes and save the changes, a new audit tra
 
 ## Retrieve Audit Trail
 
-To retrieve an audit trail, for your model, you can use the `recordedChanges()` [relationship method](https://laravel.com/docs/11.x/eloquent-relationships).
+To retrieve an audit trail, for your model, you can use the `recordedChanges()` [relationship method](https://laravel.com/docs/12.x/eloquent-relationships).
 
 ```php
 $changes = $category

docs/archive/current/auth/fortify/README.md

@@ -5,5 +5,5 @@ sidebarDepth: 0
 
 # Prerequisites
 
-To use the [Laravel Fortify](https://laravel.com/docs/11.x/fortify) utilities, you must first have Laravel Fortify installed.
-Please follow the [official installation guide](https://laravel.com/docs/11.x/fortify#installation).
+To use the [Laravel Fortify](https://laravel.com/docs/12.x/fortify) utilities, you must first have Laravel Fortify installed.
+Please follow the [official installation guide](https://laravel.com/docs/12.x/fortify#installation).

docs/archive/current/auth/fortify/exceptions/failed-login-attempt.md

@@ -0,0 +1,45 @@
+---
+description: Failed Login Attempt Exception
+sidebarDepth: 0
+---
+
+# Failed Login Attempt
+
+The `FailedLoginAttempt` exception is an alternative to Laravel's default validation exception that is thrown, on
+unsuccessful login attempts. The custom exception ensures that an HTTP
+["401 Unauthorized"](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401) response is sent back to a client,
+instead of a ["422 Unprocessable Content"](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422). 
+
+The exception can be used in combination with a custom "attempt to authenticate" action (_see example below_).
+
+```php
+use Aedart\Auth\Fortify\Exceptions\FailedLoginAttempt;
+use Laravel\Fortify\Actions\AttemptToAuthenticate as BaseAttemptToAuthenticate;
+use Laravel\Fortify\Fortify;
+
+class AttemptToAuthenticate extends BaseAttemptToAuthenticate
+{
+    protected function throwFailedAuthenticationException($request)
+    {
+        $this->limiter->increment($request);
+
+        throw FailedLoginAttempt::withMessages([
+            Fortify::username() => [trans('auth.failed')],
+        ]);
+    }
+}
+```
+
+To use such an action, you will have to modify Laravel Fortify's default
+[authentication pipeline](https://laravel.com/docs/12.x/fortify#customizing-the-authentication-pipeline).
+
+```php
+Fortify::authenticateThrough(function (Request $request) {
+    return array_filter([
+        // ...previous actions not shown...
+
+        AttemptToAuthenticate::class,
+        PrepareAuthenticatedSession::class,
+    ]);
+});
+```

docs/archive/current/auth/fortify/exceptions/pass-reset-link-failure.md

@@ -0,0 +1,18 @@
+---
+description: Password Reset Link Failure Exception
+sidebarDepth: 0
+---
+
+# Password Reset Link Failure
+
+The `PasswordResetLinkFailure`¹ exception can be used as an alternative to Laravel Fortify's default validation exception,
+in situations [requesting a password reset link](https://laravel.com/docs/12.x/fortify#requesting-a-password-reset-link)
+fails, e.g. due to invalid user credential.
+
+The exception results in an HTTP ["200 Ok"](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200) response, rather
+than the default ["422 Unprocessable Content"](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422) response.
+Doing so can reduce the chance, that an attacker is able to guess whether a user account exists or not.
+For more information about such, please see the custom
+["failed password reset link" API response](../responses/failed-pass-reset-link.md).
+
+¹: _Full namespace: `\Aedart\Auth\Fortify\Exceptions\PasswordResetLinkFailure`._

docs/archive/current/auth/fortify/responses/failed-pass-reset-link.md

@@ -0,0 +1,61 @@
+---
+title: Failed Password Reset Link 
+description: Failed Password Reset Link API Response
+sidebarDepth: 0
+---
+
+# Failed Password Reset Link (API Response)
+
+In an edge case scenario, a ["forgot password"](https://laravel.com/docs/12.x/fortify#requesting-a-password-reset-link)
+mechanism can potentially be misused to guess if a user account exists or not. Most commonly, this is done so by
+requesting a password reset, to a specified email. When your application responds with a
+[successful response](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#successful_responses) for a valid email,
+attackers will know that an account exists and proceed to exploitation attempts.  
+
+::: tip Note
+The above described edge case scenario is **NOT** specifically tied to Laravel Fortify. Any kind of "reset password"
+functionality _can be_ subject to such, if end-users are able to request a reset password link.
+
+See [Testing for Account Enumeration and Guessable User Account](https://owasp.org/www-project-web-security-testing-guide/stable/4-Web_Application_Security_Testing/03-Identity_Management_Testing/04-Testing_for_Account_Enumeration_and_Guessable_User_Account.html)
+for additional details.
+:::
+
+To reduce the chances of revealing the existence of a user account, when requesting a reset link, the
+`FailedPasswordResetLinkApiResponse` can be used. Whenever the requested username, e.g. email, does not exist, the
+component throws a ["password reset link failure"](../exceptions/pass-reset-link-failure.md) exception, which results in
+an HTTP ["200 Ok"](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200) response. An attacker will then no
+longer be able to tell the difference between a valid or invalid username.
+
+::: warning Limitations
+The `FailedPasswordResetLinkApiResponse` is intended for API driven login mechanisms, e.g. when your "request reset
+password" functionality is implemented via a JSON based API.
+:::
+
+## How to use
+
+To use the custom API response, register a singleton binding for the `FailedPasswordResetLinkRequestResponse` interface.
+
+```php
+namespace App\Providers;
+
+use Aedart\Auth\Fortify\Responses\FailedPasswordResetLinkApiResponse;
+use Illuminate\Foundation\Support\Providers\AuthServiceProvider as ServiceProvider;
+use Laravel\Fortify\Contracts\FailedPasswordResetLinkRequestResponse;
+
+class AuthServiceProvider extends ServiceProvider
+{
+    public function boot()
+    {
+        $this->app->singleton(
+            FailedPasswordResetLinkRequestResponse::class,
+            FailedPasswordResetLinkApiResponse::class
+        );
+    }
+}
+```
+
+## Additional Reading
+
+* [Forgot Password Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Forgot_Password_Cheat_Sheet.html).
+* [Exploring Password Reset Vulnerabilities and Security Best Practices](https://www.vaadata.com/blog/exploring-password-reset-vulnerabilities-and-security-best-practices/)
+* [Exploring Reset Password Vulnerabilities: Risks, Exploits, and Prevention Strategies](https://medium.com/@cuncis/exploring-reset-password-vulnerabilities-risks-exploits-and-prevention-strategies-87745b65dd66)