Merge pull request #841 from kenjis/docs-reorganize-2

docs: reorganize (part 2)

Author: kenjis

docs/customization/integrating_custom_view_libs.md

@@ -1,6 +1,8 @@
 # Integrating Custom View Libraries
 
-If your application uses a different method to convert view files to HTML than CodeIgniter's built-in `view()` helper you can easily integrate your system anywhere that a view is rendered within Shield. All controllers and actions use the `CodeIgniter\Shield\Traits\Viewable` trait which provides a simple `view()` method that takes the same arguments as the `view()` helper. This allows you to extend the Action or Controller and only change the single method of rendering the view, leaving all of the logic untouched so your app will not need to maintain Shield logic when it doesn't need to change it.
+If your application uses a different method to convert view files to HTML than CodeIgniter's built-in `view()` helper, you can easily integrate your system anywhere that a view is rendered within Shield.
+
+All controllers and actions use the `CodeIgniter\Shield\Traits\Viewable` trait which provides a simple `view()` method that takes the same arguments as the `view()` helper. This allows you to extend the Action or Controller and only change the single method of rendering the view, leaving all of the logic untouched so your app will not need to maintain Shield logic when it doesn't need to change it.
 
 ```php
 use Acme\Themes\Traits\Themeable;

docs/customization/route_config.md

@@ -1,4 +1,4 @@
-# Customizing Route Configuration
+# Customizing Routes
 
 If you need to customize how any of the auth features are handled, you will likely need to update the routes to point to the correct controllers. You can still use the `service('auth')->routes()` helper, but you will need to pass the `except` option with a list of routes to customize:
 

docs/customization/table_names.md

@@ -17,4 +17,5 @@ public array $tables = [
 
 Set the table names that you want in the array values.
 
-> **Note** You must change the table names before running database migrations.
+> **Note**
+> You must change the table names before running database migrations.

docs/customization/user_provider.md

@@ -1,7 +1,7 @@
 # Customizing User Provider
 
 If you want to customize user attributes, you need to create your own
-[User Provider](../concepts.md#user-providers) class.
+[User Provider](../getting_started/concepts.md#user-providers) class.
 The only requirement is that your new class MUST extend the provided `CodeIgniter\Shield\Models\UserModel`.
 
 Shield has a CLI command to quickly create a custom `UserModel` class by running the following

docs/customization/validation_rules.md

@@ -36,7 +36,8 @@ Shield has the following rules for registration:
 ];
 ```
 
-> **Note** If you customize the table names, the table names
+> **Note**
+> If you customize the table names, the table names
 > (`users` and `auth_identities`) in the above rules will be automatically
 > changed. The rules are implemented in
 > `RegisterController::getValidationRules()`.
@@ -78,7 +79,8 @@ If you need a different set of rules for registration, you can specify them in y
     ];
 ```
 
-> **Note** If you customize the table names, set the correct table names in the
+> **Note**
+> If you customize the table names, set the correct table names in the
 > rules.
 
 ## Login

docs/getting_started/authenticators.md

@@ -0,0 +1,16 @@
+# Authenticators
+
+## Authenticator List
+
+Shield provides the following Authenticators:
+
+- **Session** authenticator provides traditional ID/Password authentication.
+  It uses username/email/password to authenticate against and stores the user
+  information in the session. See [Using Session Authenticator](../quick_start_guide/using_session_auth.md) for usage.
+- **AccessTokens** authenticator provides stateless authentication using Personal
+  Access Tokens passed in the HTTP headers.
+  See [Protecting an API with Access Tokens](../guides/api_tokens.md) for usage.
+- **HmacSha256** authenticator provides stateless authentication using HMAC Keys.
+  See [Protecting an API with HMAC Keys](../guides/api_hmac_keys.md) for usage.
+- **JWT** authenticator provides stateless authentication using JSON Web Token. To use this,
+  you need additional setup. See [JWT Authentication](../addons/jwt.md).

docs/concepts.md renamed to docs/getting_started/concepts.md

@@ -21,7 +21,7 @@ on the standard Config class if nothing is found in the database.
 Shield has a model to handle user persistence. Shield calls this the "User Provider" class.
 A default model is provided for you by the `CodeIgniter\Shield\Models\UserModel` class.
 
-You can use your own model to customize user attributes. See [Customizing User Provider](./customization/user_provider.md) for details.
+You can use your own model to customize user attributes. See [Customizing User Provider](../customization/user_provider.md) for details.
 
 ## User Identities
 

docs/getting_started/configuration.md

@@ -0,0 +1,27 @@
+# Configuration
+
+## Config files
+
+Shield has a lot of Config items. Change the default values as needed.
+
+If you have completed the setup according to this documentation, you will have
+the following configuration files:
+
+- **app/Config/Auth.php**
+- **app/Config/AuthGroups.php** - For Authorization
+- **app/Config/AuthToken.php** - For AccessTokens and HmacSha256 Authentication
+- **app/Config/AuthJWT.php** - For JWT Authentication
+
+Note that you do not need to have configuration files for features you do not use.
+
+This section describes the major Config items that are not described elsewhere.
+
+## AccessTokens Authenticator
+
+### Access Token Lifetime
+
+By default, Access Tokens can be used for 1 year since the last use. This can be easily modified in the **app/Config/Auth.php** config file.
+
+```php
+public int $unusedTokenLifetime = YEAR;
+```

docs/getting_started/install.md

@@ -0,0 +1,182 @@
+# Installation
+
+These instructions assume that you have already [installed the CodeIgniter 4 app starter](https://codeigniter.com/user_guide/installation/installing_composer.html) as the basis for your new project, set up your **.env** file, and created a database that you can access via the Spark CLI script.
+
+## Requirements
+
+- [Composer](https://getcomposer.org)
+- Codeigniter **v4.2.7** or later
+- A created database that you can access via the Spark CLI script
+  - InnoDB (not MyISAM) is required if MySQL is used.
+
+## Composer Installation
+
+Installation is done through [Composer](https://getcomposer.org). The example assumes you have it installed globally.
+If you have it installed as a phar, or otherwise you will need to adjust the way you call composer itself.
+
+```console
+composer require codeigniter4/shield
+```
+
+### Troubleshooting
+
+#### IMPORTANT: composer error
+
+If you get the following error:
+
+```console
+Could not find a version of package codeigniter4/shield matching your minimum-stability (stable).
+Require it with an explicit version constraint allowing its desired stability.
+```
+
+1. Run the following commands to change your [minimum-stability](https://getcomposer.org/doc/articles/versions.md#minimum-stability) in your project `composer.json`:
+
+    ```console
+    composer config minimum-stability dev
+    composer config prefer-stable true
+    ```
+
+2. Or specify an explicit version:
+
+    ```console
+    composer require codeigniter4/shield:dev-develop
+    ```
+
+    The above specifies `develop` branch.
+    See <https://getcomposer.org/doc/articles/versions.md#branches>
+
+    ```console
+    composer require codeigniter4/shield:^1.0.0-beta
+    ```
+
+    The above specifies `v1.0.0-beta` or later and before `v2.0.0`.
+    See <https://getcomposer.org/doc/articles/versions.md#caret-version-range->
+
+## Initial Setup
+
+### Command Setup
+
+1. Run the following command. This command handles steps 1-5 of *Manual Setup* and runs the migrations.
+
+    ```console
+    php spark shield:setup
+    ```
+
+    > **Note**
+    > If you want to customize table names, you must change the table names
+    > before running database migrations.
+    > See [Customizing Table Names](../customization/table_names.md).
+
+2. Configure **app/Config/Email.php** to allow Shield to send emails with the [Email Class](https://codeigniter.com/user_guide/libraries/email.html).
+
+    ```php
+    <?php
+
+    namespace Config;
+
+    use CodeIgniter\Config\BaseConfig;
+
+    class Email extends BaseConfig
+    {
+        /**
+         * @var string
+         */
+        public $fromEmail = 'your_mail@example.com';
+
+        /**
+         * @var string
+         */
+        public $fromName = 'your name';
+
+        // ...
+    }
+    ```
+
+### Manual Setup
+
+There are a few setup items to do before you can start using Shield in
+your project.
+
+1. Copy the **Auth.php**, **AuthGroups.php**, and **AuthToken.php** from **vendor/codeigniter4/shield/src/Config/** into your project's config folder and update the namespace to `Config`. You will also need to have these classes extend the original classes. See the example below. These files contain all the settings, group, and permission information for your application and will need to be modified to meet the needs of your site.
+
+    ```php
+    // new file - app/Config/Auth.php
+    <?php
+
+    declare(strict_types=1);
+
+    namespace Config;
+
+    // ...
+    use CodeIgniter\Shield\Config\Auth as ShieldAuth;
+
+    class Auth extends ShieldAuth
+    {
+        // ...
+    }
+    ```
+
+2. **Helper Setup** The `setting` helper needs to be included in almost every page. The simplest way to do this is to add it to the `BaseController::initController()` method:
+
+    ```php
+    public function initController(RequestInterface $request, ResponseInterface $response, LoggerInterface $logger)
+    {
+        $this->helpers = array_merge($this->helpers, ['setting']);
+
+        // Do Not Edit This Line
+        parent::initController($request, $response, $logger);
+    }
+    ```
+
+    This requires that all of your controllers extend the `BaseController`, but that's a good practice anyway.
+
+3. **Routes Setup** The default auth routes can be setup with a single call in **app/Config/Routes.php**:
+
+    ```php
+    service('auth')->routes($routes);
+    ```
+
+4. **Security Setup** Set `Config\Security::$csrfProtection` to `'session'` (or set `security.csrfProtection = session` in your **.env** file) for security reasons, if you use Session Authenticator.
+
+5. **Migration** Run the migrations.
+
+    > **Note**
+    > If you want to customize table names, you must change the table names
+    > before running database migrations.
+    > See [Customizing Table Names](../customization/table_names.md).
+
+    ```console
+    php spark migrate --all
+    ```
+
+    #### Note: migration error
+
+    When you run `spark migrate --all`, if you get `Class "SQLite3" not found` error:
+
+    1. Remove sample migration files in **tests/_support/Database/Migrations/**
+    2. Or install `sqlite3` php extension
+
+6. Configure **app/Config/Email.php** to allow Shield to send emails.
+
+    ```php
+    <?php
+
+    namespace Config;
+
+    use CodeIgniter\Config\BaseConfig;
+
+    class Email extends BaseConfig
+    {
+        /**
+         * @var string
+         */
+        public $fromEmail = 'your_mail@example.com';
+
+        /**
+         * @var string
+         */
+        public $fromName = 'your name';
+
+        // ...
+    }
+    ```

docs/guides/api_tokens.md

@@ -2,7 +2,8 @@
 
 Access Tokens can be used to authenticate users for your own site, or when allowing third-party developers to access your API. When making requests using access tokens, the token should be included in the `Authorization` header as a `Bearer` token.
 
-> **Note**  By default, `$authenticatorHeader['tokens']` is set to `Authorization`. You can change this value by setting the `$authenticatorHeader['tokens']` value in the **app/Config/Auth.php** config file.
+> **Note**
+> By default, `$authenticatorHeader['tokens']` is set to `Authorization`. You can change this value by setting the `$authenticatorHeader['tokens']` value in the **app/Config/Auth.php** config file.
 
 Tokens are issued with the `generateAccessToken()` method on the user. This returns a `CodeIgniter\Shield\Entities\AccessToken` instance. Tokens are hashed using a SHA-256 algorithm before being saved to the database. The access token returned when you generate it will include a `raw_token` field that contains the plain-text, un-hashed, token. You should display this to your user at once so they have a chance to copy it somewhere safe, as this is the only time this will be available. After this request, there is no way to get the raw token.