Update docs for v12.3.0 (#97)

docs/architecture-concepts/porto.md

@@ -61,17 +61,14 @@ app
 │   │       ├── Providers
 │   │       ├── Tasks
 │   │       ├── Tests
-│   │       │   └── Unit
 │   │       ├── Traits
 │   │       └── UI
 │   │           ├── API
 │   │           │   ├── Controllers
 │   │           │   ├── Requests
 │   │           │   ├── Routes
-│   │           │   ├── Tests
-│   │           │   │   └── Functional
 │   │           │   └── Transformers
-│   │           └── WEB
+│   │           ├── WEB
 │   │           │   ├── Controllers
 │   │           │   ├── Requests
 │   │           │   ├── Routes

docs/components/main-components/transformers.md

@@ -307,30 +307,6 @@ class UserTransformer extends ParentTransformer
 
 ## Helper Methods
 
-### ifAdmin
-
-The `ifAdmin` method is used
-to merge the normal client response with additional or modified results intended for admin users.
-
-```php
-public function transform(Model $model)
-{
-    $response = [
-        'object' => $model->getResourceKey(),
-        'id' => $model->getHashedKey(),
-        'another_field' => $model->anotherField,
-    ];
-
-    return $this->ifAdmin([
-        'real_id' => $model->id,
-        'created_at' => $model->created_at,
-        'updated_at' => $model->updated_at,
-        'readable_created_at' => $model->created_at->diffForHumans(),
-        'readable_updated_at' => $model->updated_at->diffForHumans(),
-    ], $response);
-}
-```
-
 ### nullableItem
 
 The `nullableItem` method returns an item if the model has a specific relationship, otherwise, it returns `null`.

docs/components/optional-components/repository/repositories.md

@@ -12,8 +12,8 @@ tags:
 
 Apiato provides a powerful repository pattern implementation based on the [L5 Repository](https://github.com/andersao/l5-repository) package.
 
-> To prevent overlap with the L5 Repository documentation, this page 
-> exclusively delves into Apiato distinct features and configurations, 
+> To prevent overlap with the L5 Repository documentation, this page
+> exclusively delves into Apiato distinct features and configurations,
 > offering only a limited set of examples.
 > To learn more about the L5 Repository package,
 > please refer to its [documentation](https://github.com/andersao/l5-repository).
@@ -230,7 +230,7 @@ Here's an example of how to use RequestCriteria:
 use App\Containers\AppSection\User\Data\Repositories\UserRepository;
 use App\Ship\Parents\Tasks\Task as ParentTask;
 
-class GetAllUsersTask extends ParentTask
+class ListUsersTask extends ParentTask
 {
     public function __construct(
         protected readonly UserRepository $repository
@@ -429,3 +429,28 @@ You can skip the cache for a specific request by adding the `?skipCache=true` qu
 ```
 
 > It's not recommended to skip the cache, but it's useful for testing purposes.
+
+## Additional Methods
+
+Apiato extends the L5 Repository package by adding a few more methods to the repository class.
+
+[pushCriteriaWith](#pushcriteriawith)  
+[findById](#findbyid)  
+[getById](#getbyid)  
+[findMany](#findmany)
+
+#### pushCriteriaWith
+
+This method is a wrapper around the `pushCriteria` method. It accepts data to be passed to the criteria class and allows for easier testing.
+
+#### findById
+
+This method is a wrapper around the `find` method. But it returns `null` if the record is not found.
+
+#### getById
+
+This method is a wrapper around the `find` method. But it throws a `NotFoundException` if the record is not found.
+
+#### findMany
+
+This method is a wrapper around the `find` method. But it returns an empty collection if no records are found.

docs/components/optional-components/tests.md

@@ -39,23 +39,29 @@ These types of tests provide the most confidence that your system as a whole is
 
 ## Rules
 
-- All container-specific Unit tests:
-  - MUST be placed in the `app/Containers/{Section}/{Container}/Tests/Unit` directory.
-  - MUST extend the `App\Containers\{Section}\{Container}\Tests\UnitTestCase` class.
+- All container-specific tests:
+  - MUST be placed in the `app/Containers/{Section}/{Container}/Tests` directory.
+  - Functional tests:
+    - MUST be placed in the `app/Containers/{Section}/{Container}/Tests/Functional` directory.
+    - API tests:
+      - MUST be placed in the `app/Containers/{Section}/{Container}/Tests/Functional/API` directory.
+      - MUST extend the `App\Containers\{Section}\{Container}\Tests\Functional\ApiTestCase` class.
+        - MUST extend the `App\Containers\{Section}\{Container}\Tests\FunctionalTestCase` class.
+          - MUST extend the `App\Containers\{Section}\{Container}\Tests\ContainerTestCase` class.
+    - CLI tests:
+      - MUST be placed in the `app/Containers/{Section}/{Container}/Tests/Functional/CLI` directory.
+      - MUST extend the `App\Containers\{Section}\{Container}\Tests\Functional\CliTestCase` class.
+        - MUST extend the `App\Containers\{Section}\{Container}\Tests\FunctionalTestCase` class.
+          - MUST extend the `App\Containers\{Section}\{Container}\Tests\ContainerTestCase` class.
+  - Unit tests:
+    - MUST be placed in the `app/Containers/{Section}/{Container}/Tests/Unit` directory.
+    - MUST extend the `App\Containers\{Section}\{Container}\Tests\UnitTestCase` class.
+      - MUST extend the `App\Containers\{Section}\{Container}\Tests\ContainerTestCase` class.
+    - Directory structure MUST exactly match the Container's directory structure.
 - All `Ship` Unit tests:
   - MUST be placed in the `app/Ship/Tests/Unit` directory.
-  - MUST extend the `App\Ship\Tests\TestCase` class.
-- All API Functional tests:
-  - MUST be placed in the `app/Containers/{Section}/{Container}/UI/API/Tests/Functional` directory.
-  - MUST extend the `App\Containers\{Section}\{Container}\UI\API\Tests\ApiTestCase` class.
-- All WEB Functional tests:
-  - MUST be placed in the `app/Containers/{Section}/{Container}/UI/WEB/Tests/Functional` directory.
-  - MUST extend the `App\Containers\{Section}\{Container}\UI\WEB\Tests\WebTestCase` class.
-- All TestCases MUST extend the `App\Ship\Parents\Tests\PhpUnit\TestCase` class. e.g.:
-  - `App\Ship\Tests\TestCase`
-  - `App\Containers\{Section}\{Container}\Tests\UnitTestCase`
-  - `App\Containers\{Section}\{Container}\UI\API\Tests\ApiTestCase`
-  - `App\Containers\{Section}\{Container}\UI\WEB\Tests\WebTestCase`
+  - MUST extend the `App\Ship\Tests\ShipTestCase` class.
+- All `ContainerTestCases` & `ShipTestCase` MUST extend the `App\Ship\Parents\Tests\PhpUnit\TestCase` class.
   - The parent extension SHOULD be aliased as `ParentTestCase`.
 
 ## Folder Structure
@@ -65,33 +71,43 @@ app
 ├── Containers
 │   └── Section
 │       └── Container
-│           ├── Tests
-│           │   ├── Unit
-│           │   │   ├── CreateUserActionTest.php
-│           │   │   ├── DeleteUserTaskTest.php
-│           │   │   └── ...
-│           │   └── UnitTestCase.php
-│           └── UI
-│               ├── API
-│               │   └── Tests
-│               │       ├── Functional
-│               │       │   ├── CreateUserTest.php
-│               │       │   ├── DeleteUserTest.php
+│           └── Tests
+│               ├── Functional
+│               │   ├── API
+│               │   │   ├── CreateUserTest.php
+│               │   │   └── ...
+│               │   ├── CLI
+│               │   │   ├── CreateAdminCommandTest.php
+│               │   │   └── ...
+│               │   ├── ApiTestCase.php
+│               │   └── CliTestCase.php
+│               ├── Unit 
+│               │   ├── Actions
+│               │   │   ├── CreateUserActionTest.php
+│               │   │   └── ...
+│               │   ├── AnotherDirectory
+│               │   │   ├── ...
+│               │   │   └── ...
+│               │   └── UI
+│               │       ├── API
+│               │       │   ├── Controllers
+│               │       │   ├── Requests
+│               │       │   ├── Transformers
 │               │       │   └── ...
-│               │       └── ApiTestCase.php
-│               └── WEB
-│                   └── Tests
-│                       ├── Functional
-│                       │   ├── LoginTest.php
-│                       │   ├── LogoutTest.php
-│                       │   └── ...
-│                       └── WebTestCase.php
+│               │       └── WEB
+│               │           ├── Controllers
+│               │           ├── Requests
+│               │           ├── Transformers
+│               │           └── ...
+│               ├── ContainerTestCase.php
+│               ├── FunctionalTestCase.php
+│               └── UnitTestCase.php
 └── Ship
     └── Tests
         ├── Unit
         │   ├── UrlRuleTest.php
         │   └── ...
-        └── TestCase.php
+        └── ShipTestCase.php
 ```
 
 ## Writing Tests
@@ -101,15 +117,16 @@ However, Functional tests follow a distinct approach.
 Here's an example of how to write functional tests:
 
 ```php
-namespace App\Containers\AppSection\User\UI\API\Tests\Functional;
+namespace App\Containers\AppSection\User\Tests\Functional\API;
 
-use App\Containers\AppSection\User\UI\API\Tests\ApiTestCase;
+use App\Containers\AppSection\User\Data\Factories\UserFactory;
+use App\Containers\AppSection\User\Tests\Functional\ApiTestCase;
 use Illuminate\Testing\Fluent\AssertableJson;
+use PHPUnit\Framework\Attributes\CoversNothing;
+use PHPUnit\Framework\Attributes\Group;
 
-/**
- * @group user
- * @group api
- */
+#[Group('user')]
+#[CoversNothing]
 class FindUserByIdTest extends ApiTestCase
 {
     protected string $endpoint = 'get@v1/users/{id}';
@@ -147,7 +164,7 @@ Certain test helper methods access properties defined in your test class to exec
 Below, we will explore these properties and their corresponding methods:
 
 ---
-#### endpoint {#endpoint}
+#### endpoint
 
 The `$endpoint` property is used
 to define the endpoints you want to access when making a call using the `makeCall` method.
@@ -175,7 +192,7 @@ class FindUserByIdTest extends ApiTestCase
 ```
 
 ---
-#### auth {#auth}
+#### auth
 
 The `$auth` property is used to determine whether the endpoint being called requires authentication or not in your test class.
 If you do not explicitly define the `$auth` property in your test class, it will be defaulted to `true` automatically.
@@ -245,10 +262,10 @@ class DeleteUserTest extends ApiTestCase
 
 [makeCall](#makecall)  
 [injectId](#injectid)  
-[getTestingUser](#getTestingUser)  
-[getTestingUserWithoutAccess](#getTestingUserWithoutAccess)  
-[endpoint](#endpoint)  
-[auth](#auth)
+[getTestingUser](#gettestinguser)  
+[getTestingUserWithoutAccess](#gettestinguserwithoutaccess)  
+[endpoint](#endpoint-method)  
+[auth](#auth-method)  
 
 ---
 #### makeCall
@@ -369,7 +386,7 @@ $user = $this->getTestingUserWithoutAccess();
 ```
 
 ---
-#### endpoint
+#### endpoint {#method}
 
 The `endpoint` method allows you to specify the endpoint you want to test within your functional tests.
 This method is especially useful
@@ -387,7 +404,7 @@ or else `injectId` will not replace the ID in the overridden endpoint.
 :::
 
 ---
-#### auth
+#### auth {#method}
 
 The `auth` method allows you
 to specify the authentication status of the endpoint you want to test within your functional tests.

docs/getting-started/best-practices.md

@@ -148,7 +148,7 @@ Common error HTTP status codes include:
 
 ## Naming Conventions For [Routes](../components/main-components/routes.md) & [Actions](../components/main-components/actions.md) {#naming-conventions-for-routes-and-actions}
 
-- **GetAllResources**: to fetch all resources.
+- **ListResources**: to fetch all resources.
 - **FindResourceByID**: to search for a single resource by its unique identifier.
 - **CreateResource**: to create a new resource.
 - **UpdateResource**: to update/edit existing resource.

docs/pacakges/localization.md

@@ -54,10 +54,10 @@ Place language files inside the `/Languages` folder of your container. For examp
 You can also place general language files in `app/Ship/Languages`.
 
 :::note  
-Just create the `Languages` folder if it does not exist.  
+Just create the `Languages` folder if it does not exist in your container or `app/Ship` folder.  
 :::
 
-Example languages files are included at `\lang`. (default Laravel translations)
+You can still use the default Laravel translations by placing language files in `/lang` folder.
 
 ## Support new languages{#support-new-languages}
 

docs/pacakges/readme.md

@@ -16,7 +16,7 @@ For example, your `/composer.json` file may look something like this:
 ```json
 {
   "require": {
-    "apiato/welcome-container": "^2.0.1"
+    "apiato/some-container": "^2.0.1"
   }
 }
 ```

docs/security/authentication.mdx

@@ -123,7 +123,7 @@ You must manually extract the client credentials from the database
 and update your `.env` file with the appropriate credentials for each client.
 :::
 
-### Requesting Tokens With Custom Attributes {#requesting-tokens-with-custom-attributes}
+### Requesting Tokens With Custom Fields
 
 By default, Apiato enables users to request an access token using their email address.
 However,
@@ -145,17 +145,17 @@ so ensure that you make the necessary adjustments there as well.
 1. Locate the `appSection-authentication` configuration file.
 It is typically found at `App\Containers\AppSection\Authentication\Configs\appSection-authentication`.
 
-2. Open the `appSection-authentication` configuration file and search for the `login.attributes` parameter.
-This parameter allows you to configure the login attributes based on your requirements.
+2. Open the `appSection-authentication` configuration file and search for the `login.fields` parameter.
+This parameter allows you to configure the login fields based on your requirements.
 
-3. Modify the `login.attributes` parameter according to your needs.
-You can specify the login attributes that should be considered during the authentication process.
+3. Modify the `login.fields` parameter according to your needs.
+You can specify the login fields that should be considered during the authentication process.
 For example, if you want to allow users to log in using their `email` and `phone`,
-update the `login.attributes` parameter as follows:
+update the `login.fields` parameter as follows:
 
 ```php
 'login' => [
-    'attributes' => [
+    'fields' => [
         'email' => ['email'],
         'phone' => ['string', 'min:6', 'max:25'],
     ],