Merge pull request #490 from codeigniter4/develop

Prep for Beta 3

Author: MGatner

.editorconfig

@@ -11,5 +11,5 @@ end_of_line = lf
 insert_final_newline = true
 trim_trailing_whitespace = true
 
-[*.yml]
+[*.{yml,yaml}]
 indent_size = 2

.github/release.yml

@@ -0,0 +1,23 @@
+changelog:
+  exclude:
+    authors:
+      - dependabot
+  categories:
+    - title: Breaking Changes
+      labels:
+        - 'breaking change'
+    - title: Fixed Bugs
+      labels:
+        - bug
+    - title: New Features
+      labels:
+        - 'new feature'
+    - title: Enhancements
+      labels:
+        - enhancement
+    - title: Refactoring
+      labels:
+        - refactor
+    - title: Others (Only for checking. Remove this category)
+      labels:
+        - "*"

.github/workflows/phpunit.yml

@@ -20,14 +20,84 @@ on:
 
 jobs:
   main:
-    name: PHP ${{ matrix.php-versions }} Unit Tests
+    name: PHP ${{ matrix.php-versions }} - ${{ matrix.db-platforms }}
     runs-on: ubuntu-latest
     if: "!contains(github.event.head_commit.message, '[ci skip]')"
     strategy:
       matrix:
         php-versions: ['7.4', '8.0', '8.1']
+        db-platforms: ['MySQLi', 'Postgre', 'SQLite3', 'SQLSRV', 'OCI8']
+        mysql-versions: [ '5.7' ]
+        include:
+          - php-versions: '7.4'
+            db-platforms: MySQLi
+            mysql-versions: '8.0'
+
+    services:
+      mysql:
+        image: mysql:${{ matrix.mysql-versions }}
+        env:
+          MYSQL_ALLOW_EMPTY_PASSWORD: yes
+          MYSQL_DATABASE: test
+        ports:
+          - 3306:3306
+        options: --health-cmd="mysqladmin ping" --health-interval=10s --health-timeout=5s --health-retries=3
+
+      postgres:
+        image: postgres
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: test
+        ports:
+          - 5432:5432
+        options: --health-cmd=pg_isready --health-interval=10s --health-timeout=5s --health-retries=3
+
+      mssql:
+        image: mcr.microsoft.com/mssql/server:2019-CU10-ubuntu-20.04
+        env:
+          SA_PASSWORD: 1Secure*Password1
+          ACCEPT_EULA: Y
+          MSSQL_PID: Developer
+        ports:
+          - 1433:1433
+        options: --health-cmd="/opt/mssql-tools/bin/sqlcmd -S 127.0.0.1 -U sa -P 1Secure*Password1 -Q 'SELECT @@VERSION'" --health-interval=10s --health-timeout=5s --health-retries=3
+
+      oracle:
+        image: quillbuilduser/oracle-18-xe
+        env:
+          ORACLE_ALLOW_REMOTE: true
+        ports:
+          - 1521:1521
+        options: --health-cmd="/opt/oracle/product/18c/dbhomeXE/bin/sqlplus -s sys/Oracle18@oracledbxe/XE as sysdba <<< 'SELECT 1 FROM DUAL'" --health-interval=10s --health-timeout=5s --health-retries=3
 
     steps:
+      - name: Create database for MSSQL Server
+        if: matrix.db-platforms == 'SQLSRV'
+        run: sqlcmd -S 127.0.0.1 -U sa -P 1Secure*Password1 -Q "CREATE DATABASE test"
+
+      - name: Install Oracle InstantClient
+        if: matrix.db-platforms == 'OCI8'
+        run: |
+          sudo apt-get install wget libaio1 alien
+          sudo wget https://download.oracle.com/otn_software/linux/instantclient/185000/oracle-instantclient18.5-basic-18.5.0.0.0-3.x86_64.rpm
+          sudo wget https://download.oracle.com/otn_software/linux/instantclient/185000/oracle-instantclient18.5-devel-18.5.0.0.0-3.x86_64.rpm
+          sudo wget https://download.oracle.com/otn_software/linux/instantclient/185000/oracle-instantclient18.5-sqlplus-18.5.0.0.0-3.x86_64.rpm
+          sudo alien oracle-instantclient18.5-basic-18.5.0.0.0-3.x86_64.rpm
+          sudo alien oracle-instantclient18.5-devel-18.5.0.0.0-3.x86_64.rpm
+          sudo alien oracle-instantclient18.5-sqlplus-18.5.0.0.0-3.x86_64.rpm
+          sudo dpkg -i oracle-instantclient18.5-basic_18.5.0.0.0-4_amd64.deb oracle-instantclient18.5-devel_18.5.0.0.0-4_amd64.deb oracle-instantclient18.5-sqlplus_18.5.0.0.0-4_amd64.deb
+          echo "LD_LIBRARY_PATH=/lib/oracle/18.5/client64/lib/" >> $GITHUB_ENV
+          echo "NLS_LANG=AMERICAN_AMERICA.UTF8" >> $GITHUB_ENV
+          echo "C_INCLUDE_PATH=/usr/include/oracle/18.5/client64" >> $GITHUB_ENV
+          echo 'NLS_DATE_FORMAT=YYYY-MM-DD HH24:MI:SS' >> $GITHUB_ENV
+          echo 'NLS_TIMESTAMP_FORMAT=YYYY-MM-DD HH24:MI:SS' >> $GITHUB_ENV
+          echo 'NLS_TIMESTAMP_TZ_FORMAT=YYYY-MM-DD HH24:MI:SS' >> $GITHUB_ENV
+
+      - name: Create database for Oracle Database
+        if: matrix.db-platforms == 'OCI8'
+        run: echo -e "ALTER SESSION SET CONTAINER = XEPDB1;\nCREATE BIGFILE TABLESPACE \"TEST\" DATAFILE '/opt/oracle/product/18c/dbhomeXE/dbs/TEST' SIZE 10M AUTOEXTEND ON MAXSIZE UNLIMITED SEGMENT SPACE MANAGEMENT AUTO EXTENT MANAGEMENT LOCAL AUTOALLOCATE;\nCREATE USER \"ORACLE\" IDENTIFIED BY \"ORACLE\" DEFAULT TABLESPACE \"TEST\" TEMPORARY TABLESPACE TEMP QUOTA UNLIMITED ON \"TEST\";\nGRANT CONNECT,RESOURCE TO \"ORACLE\";\nexit;" | /lib/oracle/18.5/client64/bin/sqlplus -s sys/Oracle18@localhost:1521/XE as sysdba
+
       - name: Checkout
         uses: actions/checkout@v3
 
@@ -36,7 +106,7 @@ jobs:
         with:
           php-version: ${{ matrix.php-versions }}
           tools: composer, phive, phpunit
-          extensions: intl, json, mbstring, gd, xdebug, xml, sqlite3
+          extensions: intl, json, mbstring, gd, xdebug, xml, sqlite3, sqlsrv, oci8, pgsql
           coverage: xdebug
         env:
           COMPOSER_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -63,6 +133,7 @@ jobs:
       - name: Test with PHPUnit
         run: vendor/bin/phpunit --verbose --coverage-text --testsuite main
         env:
+          DB: ${{ matrix.db-platforms }}
           TERM: xterm-256color
           TACHYCARDIA_MONITOR_GA: enabled
 
@@ -75,7 +146,7 @@ jobs:
         env:
           COVERALLS_REPO_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           COVERALLS_PARALLEL: true
-          COVERALLS_FLAG_NAME: PHP ${{ matrix.php-versions }}
+          COVERALLS_FLAG_NAME: PHP ${{ matrix.php-versions }} - ${{ matrix.db-platforms }}
 
   coveralls:
     needs: [main]

.php-cs-fixer.dist.php

@@ -1,5 +1,7 @@
 <?php
 
+declare(strict_types=1);
+
 use CodeIgniter\CodingStandard\CodeIgniter4;
 use Nexus\CsConfig\Factory;
 use PhpCsFixer\Finder;
@@ -13,7 +15,10 @@
     ->exclude('build')
     ->append([__FILE__]);
 
-$overrides = [];
+$overrides = [
+    'declare_strict_types' => true,
+    'void_return'          => true,
+];
 
 $options = [
     'finder'    => $finder,

CONTRIBUTING.md

@@ -0,0 +1,10 @@
+# Contributing to CodeIgniter Shield
+
+CodeIgniter is a community driven project and accepts contributions of
+code and documentation from the community.
+
+If you'd like to contribute, please read [Contributing to CodeIgniter](https://github.com/codeigniter4/CodeIgniter4/blob/develop/contributing/README.md)
+in the [main repository](https://github.com/codeigniter4/CodeIgniter4).
+
+If you are going to contribute to this repository, please [report bugs](https://github.com/codeigniter4/shield/issues/new?assignees=&labels=bug&template=bug_report.yml&title=Bug%3A+) or [send PRs](https://github.com/codeigniter4/shield/compare)
+to this repository instead of the main repository.

README.md

@@ -1,8 +1,8 @@
 # CodeIgniter Shield
 
-[![Unit Tests](https://github.com/codeigniter4/shield/workflows/PHPUnit/badge.svg)](https://github.com/codeigniter4/shield/actions/workflows/test.yml)
-[![Static Analysis](https://github.com/codeigniter4/shield/workflows/PHPStan/badge.svg)](https://github.com/codeigniter4/shield/actions/workflows/analyze.yml)
-[![Architecture](https://github.com/codeigniter4/shield/workflows/Deptrac/badge.svg)](https://github.com/codeigniter4/shield/actions/workflows/inspect.yml)
+[![Unit Tests](https://github.com/codeigniter4/shield/workflows/PHPUnit/badge.svg)](https://github.com/codeigniter4/shield/actions/workflows/phpunit.yml)
+[![Static Analysis](https://github.com/codeigniter4/shield/workflows/PHPStan/badge.svg)](https://github.com/codeigniter4/shield/actions/workflows/phpstan.yml)
+[![Architecture](https://github.com/codeigniter4/shield/workflows/Deptrac/badge.svg)](https://github.com/codeigniter4/shield/actions/workflows/deptrac.yml)
 [![Coverage Status](https://coveralls.io/repos/github/codeigniter4/shield/badge.svg?branch=develop)](https://coveralls.io/github/codeigniter4/shield?branch=develop)
 
 Shield is an authentication and authorization framework for CodeIgniter 4. While it does provide a base set of tools
@@ -29,6 +29,18 @@ These are much like the access codes that GitHub uses, where they are unique to
 can have more than one. This can be used for API authentication of third-party users, and even for allowing
 access for a mobile application that you build.
 
+## Some Important Features
+
+* Session-based authentication (traditional email/password with remember me)
+* Stateless authentication using Personal Access Tokens
+* Optional Email verification on account registration
+* Optional Email-based Two Factor Authentication after login
+* Magic Login Links when a user forgets their password
+* Flexible groups-based access control (think roles, but more flexible)
+* Users can be granted additional permissions
+
+See the [An Official Auth Library](https://codeigniter.com/news/shield) for more Info.
+
 ## Getting Started
 
 ### Prerequisites

composer.json

@@ -37,6 +37,10 @@
         },
         "exclude-from-classmap": [
             "**/Database/Migrations/**"
+        ],
+        "files": [
+            "src/Helpers/auth_helper.php",
+            "src/Helpers/email_helper.php"
         ]
     },
     "autoload-dev": {
@@ -54,25 +58,33 @@
         "post-update-cmd": [
             "bash admin/setup.sh"
         ],
-        "analyze": "phpstan analyze",
+        "analyze": [
+            "phpstan analyze",
+            "psalm",
+            "rector process --dry-run"
+        ],
+        "sa": "@analyze",
         "ci": [
             "Composer\\Config::disableProcessTimeout",
+            "@cs",
             "@deduplicate",
-            "@sa",
-            "@test",
             "@inspect",
-            "rector process",
-            "@style"
+            "@analyze",
+            "@test"
         ],
-        "deduplicate": "phpcpd app/ src/",
+        "cs": "php-cs-fixer fix --ansi --verbose --dry-run --diff",
+        "cs-fix": "php-cs-fixer fix --ansi --verbose --diff",
+        "deduplicate": "phpcpd app/ src/ --exclude src/Database/Migrations/2020-12-28-223112_create_auth_tables.php",
         "inspect": "deptrac analyze --cache-file=build/deptrac.cache",
         "mutate": "infection --threads=2 --skip-initial-tests --coverage=build/phpunit",
-        "sa": [
-            "phpstan analyze",
-            "psalm"
-        ],
-        "cs-fix": "php-cs-fixer fix --ansi --verbose --diff --using-cache=yes",
         "style": "@cs-fix",
         "test": "phpunit"
+    },
+    "support": {
+        "forum": "https://github.com/codeigniter4/shield/discussions",
+        "slack": "https://codeigniterchat.slack.com",
+        "source": "https://github.com/codeigniter4/shield",
+        "issues": "https://github.com/codeigniter4/shield/issues",
+        "docs": "https://github.com/codeigniter4/shield/blob/develop/docs/index.md"
     }
 }

docs/auth_actions.md

@@ -7,32 +7,35 @@
 Authentication Actions are a way to group actions that can happen after login or registration.
 Shield ships with two actions you can use, and makes it simple for you to define your own.
 
-1. **Email-based Two Factor Authentication** (Email2FA) will send a 6-digit code to the user's
+1. **Email-based Account Activation** (EmailActivate) confirms a new user's email address by
+   sending them an email with a link they must follow in order to have their account activated.
+2. **Email-based Two Factor Authentication** (Email2FA) will send a 6-digit code to the user's
     email address that they must confirm before they can continue.
-2. **Email-based Account Activation** (EmailActivate) confirms a new user's email address by
-    sending them an email with a link they must follow in order to have their account activated.
 
 ## Configuring Actions
 
 Actions are setup in the `Auth` config file, with the `$actions` variable.
 
 ```php
 public $actions = [
-    'login'    => null,
     'register' => null,
+    'login'    => null,
 ];
 ```
 
 To define an action to happen you will specify the class name as the value for the appropriate task:
 
 ```php
 public $actions = [
-    'login'    => 'CodeIgniter\Shield\Authentication\Actions\Email2FA',
     'register' => 'CodeIgniter\Shield\Authentication\Actions\EmailActivator',
+    'login'    => 'CodeIgniter\Shield\Authentication\Actions\Email2FA',
 ];
 ```
 
-Once configured, everything should work out of the box. The routes are added with the basic `auth()->routes($routes)`
+You must register actions in the order of the actions to be performed.
+Once configured, everything should work out of the box.
+
+The routes are added with the basic `auth()->routes($routes)`
 call, but can be manually added if you choose not to use this helper method.
 
 ```php
@@ -49,9 +52,9 @@ Views for all of these pages are defined in the `Auth` config file, with the `$v
     public $views = [
         'action_email_2fa'            => '\CodeIgniter\Shield\Views\email_2fa_show',
         'action_email_2fa_verify'     => '\CodeIgniter\Shield\Views\email_2fa_verify',
-        'action_email_2fa_email'      => '\CodeIgniter\Shield\Views\email_2fa_email',
-        'action_email_activate_email' => '\CodeIgniter\Shield\Views\email_activate_email',
+        'action_email_2fa_email'      => '\CodeIgniter\Shield\Views\Email\email_2fa_email',
         'action_email_activate_show'  => '\CodeIgniter\Shield\Views\email_activate_show',
+        'action_email_activate_email' => '\CodeIgniter\Shield\Views\Email\email_activate_email',
     ];
 ```
 
@@ -61,7 +64,7 @@ While the provided email-based activation and 2FA will work for many sites, othe
 needs, like using SMS to verify or something completely different. Actions have only one requirement:
 they must implement `CodeIgniter\Shield\Authentication\Actions\ActionInterface`.
 
-The interface defines three methods:
+The interface defines three methods for `ActionController`:
 
 **show()** should display the initial page the user lands on immediately after the authentication task,
 like login. It will typically display instructions to the user and provide an action to take, like
@@ -77,4 +80,4 @@ and provides feedback. In the `Email2FA` class, it verifies the code against wha
 database and either sends them back to the previous form to try again or redirects the user to the
 page that a `login` task would have redirected them to anyway.
 
-All methods should return either a `RedirectResponse` or a view string (e.g. using the `view()` function).
+All methods should return either a `Response` or a view string (e.g. using the `view()` function).

docs/authentication.md

@@ -54,8 +54,6 @@ helper method provides the `auth()` command which returns a convenient interface
 used functionality within the auth libraries. This must be loaded before it can be used.
 
 ```php
-helper('auth');
-
 // get the current user
 auth()->user();
 
@@ -65,6 +63,10 @@ auth()->id();
 user_id();
 ```
 
+> **Note**
+> The `auth_helper` is autoloaded by Composer. If you want to *override* the functions,
+> you need to define them in `app/Common.php`.
+
 ## Authenticator Responses
 
 Many of the authenticator methods will return a `CodeIgniter\Shield\Result` class. This provides a consistent
@@ -144,11 +146,11 @@ $credentials = [
 $validCreds = auth()->check($credentials);
 
 if (! $validCreds->isOK()) {
-    return redirect()->back()->with('error', $loginAttempt->reason());
+    return redirect()->back()->with('error', $validCreds->reason());
 }
 ```
 
-The Result instance returned contains the logged in user as `extraInfo()`.
+The Result instance returned contains the valid user as `extraInfo()`.
 
 ### loggedIn()
 
@@ -238,7 +240,7 @@ token, you would need to get the user's access tokens and delete them manually.
 You can revoke all access tokens with the `revokeAllAccessTokens()` method.
 
 ```php
-$user->revokeAllAccessTokens($token);
+$user->revokeAllAccessTokens();
 ```
 
 ### Retrieving Access Tokens

docs/concepts.md

@@ -88,3 +88,17 @@ public $passwordValidators = [
     //'CodeIgniter\Shield\Authentication\Passwords\PwnedValidator',
 ];
 ```
+
+You use `strong_password` rule for password validation explained above.
+
+> **Note**
+> The `strong_password` rule only supports use cases to check the user's own password.
+> It fetches the authenticated user's data for **NothingPersonalValidator**
+> if the visitor is authenticated.
+>
+> If you want to have use cases that set and check another user's password,
+> you can't use `strong_password`. You need to use `service('passwords')` directly
+> to check the password.
+>
+> But remember, it is not good practice to set passwords for other users.
+> This is because the password should be known only by that user.