Added Docusaurus, moved docs from LM-Commons, updated GH Actions

Signed-off-by: Eric Richer [email protected] <[email protected]>

.github/workflows/build_test.yml

@@ -2,7 +2,11 @@ name: Continuous Integration
 
 on:
     push:
+      paths-ignore:
+        - 'docs/**'
     pull_request:
+      paths-ignore:
+        - 'docs/**'
 
 env:
   COMPOSER_ARGS: '--no-progress'

.github/workflows/deploy-gh-pages.yml

@@ -0,0 +1,48 @@
+name: Build and Deploy to GitHub Pages
+
+defaults:
+  run:
+    shell: bash
+    working-directory: ./docs
+
+on:
+  push:
+    branches:
+      - 'master'
+    paths:
+      - 'docs/**'
+  workflow_dispatch:
+
+
+jobs:
+  deploy:
+    name: Build and Deploy to GitHub Pages
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+        working-directory: ./docs
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          cache: yarn
+          cache-dependency-path: docs/yarn.lock
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+      - name: Build website
+        run: yarn build
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          # Build output to publish to the `gh-pages` branch:
+          publish_dir: ./docs/build
+          # The following lines assign commit authorship to the official
+          # GH-Actions bot for deploys to `gh-pages` branch:
+          # https://github.com/actions/checkout/issues/13#issuecomment-724415212
+          # The GH actions bot is used by default if you didn't specify the two fields.
+          # You can swap them out with your own user credentials.
+          user_name: github-actions[bot]
+          user_email: 41898282+github-actions[bot]@users.noreply.github.com

.github/workflows/test-deploy-gh-pages.yml

@@ -0,0 +1,29 @@
+name: Build GitHub Pages on PRs No Deploy
+
+defaults:
+  run:
+    shell: bash
+    working-directory: ./docs
+
+on:
+  pull_request:
+    paths:
+      - 'docs/**'
+  push:
+    paths:
+      - 'docs/**'
+jobs:
+  test-deploy:
+    name: Build GitHub Pages
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          cache: yarn
+          cache-dependency-path: docs/yarn.lock
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+      - name: Test build website
+        run: yarn build

docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

docs/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

docs/blog/2024-04-11-New-documentation.md

@@ -0,0 +1,9 @@
+---
+slug: new-documentation
+title: New documentation
+authors: [ericr]
+tags: [laminas, PHP, LmcUser, authentication, LM-Commons]
+---
+This the new documentation site dedicated to the LmcUser module.
+
+There are no changes to the code, just improvements in the documentation.

docs/blog/authors.yml

@@ -0,0 +1,5 @@
+ericr:
+  name: Eric Richer
+  title: LM-Commons Administrator
+  url: https://github.com/visto9259
+  image_url: https://github.com/visto9259.png

docs/docs/howto/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "How-to",
+  "position": 4,
+  "link": {
+    "type": "generated-index",
+    "description": "Welcome to the LmcUser How-Tos"
+  }
+}

docs/docs/howto/how-to-change-password-and-email.md

@@ -0,0 +1,10 @@
+---
+sidebar_position: 9
+---
+# How to change password and email (not complete)
+
+http://DomainName/user/
+
+http://DomainName/user/change-email/
+
+http://DomainName/user/change-password/

docs/docs/howto/how-to-check-if-the-user-is-logged-in.md

@@ -0,0 +1,64 @@
+---
+sidebar_position: 8
+---
+# How to check if the user is logged in
+## Task
+Check if the user is logged in (ie: user identity widget)
+
+## Solution
+There are three ways.
+
+### View
+LmcUser provides a View Helper ([lmcUserIdentity](https://github.com/LM-Commons/LmcUser/blob/master/src/LmcUser/View/Helper/LmcUserIdentity.php)) which you can use from any view script in your application.
+
+```php
+<!-- Test if the User is connected -->
+<?php if(!$this->lmcUserIdentity()): ?>
+    <!-- display the login form -->
+    <?php echo $this->lmcUserLoginWidget(['redirect'=>'application']); ?>
+<?php else: ?>
+    <!-- display the 'display name' of the user -->
+    <?php echo $this->lmcUserIdentity()->getDisplayname(); ?>
+<?php endif?>
+```
+
+You can also get user's fields (if the user is logged in), like email:
+
+```php
+<?php echo $this->lmcUserIdentity()->getEmail(); ?>
+```
+
+### Controller
+
+LmcUser provides a Controller Plugin ([lmcUserAuthentication](https://github.com/LM-Commons/LmcUser/blob/master/src/LmcUser/Controller/Plugin/LmcUserAuthentication.php)) which you can use from any controller in your application. You can check if the user is connected and get his data:
+
+```php
+<?php
+if ($this->lmcUserAuthentication()->hasIdentity()) {
+    //get the email of the user
+    echo $this->lmcUserAuthentication()->getIdentity()->getEmail();
+    //get the user_id of the user
+    echo $this->lmcUserAuthentication()->getIdentity()->getId();
+    //get the username of the user
+    echo $this->lmcUserAuthentication()->getIdentity()->getUsername();
+    //get the display name of the user
+    echo $this->lmcUserAuthentication()->getIdentity()->getDisplayname();
+}
+?>
+```
+
+You can get the `lmcuser_auth_service` in a controller by doing:
+```php
+$authService = $this->lmcUserIdentity()->getAuthService();
+```
+### Service Manager
+
+```php
+<?php
+$sm = $app->getServiceManager();
+$auth = $sm->get('lmcuser_auth_service');
+if ($auth->hasIdentity()) {
+    echo $auth->getIdentity()->getEmail();
+}
+?>
+```

docs/docs/howto/how-to-choose-which-user-fields-are-used-during-authentication.md

@@ -0,0 +1,30 @@
+---
+sidebar_position: 6
+---
+# How to choose which user fields are used during authentication
+
+## Task
+How to specify which fields a user can use as their 'identity' when logging in.
+
+## Solution
+
+The configuration directive `auth_identity_fields` is used to control the fields used to look up user identities stored in LmcUser.  You can configure this directive (via your `config/autoload/lmcuser.global.php` override file) to one of four possible modes:
+
+1. Authenticate via email address only:
+```php
+'auth_identity_fields' => ['email'],
+```
+2. Authenticate via username only:
+```php
+'auth_identity_fields' => ['username'],
+```
+
+3. Authenticate via both methods, with username field checked first:
+```php
+'auth_identity_fields' => ['username', 'email'],
+```
+
+4. Authenticate via both methods, with email address field checked first:
+```php
+'auth_identity_fields' => ['email', 'username'],
+```

docs/docs/howto/how-to-configure-a-session-timeout.md

@@ -0,0 +1,43 @@
+---
+sidebar_position: 10
+---
+# How to configure a session timeout
+## Task
+Automatically terminate a user's session after a specific period of inactivity.
+
+## Solution
+
+1. Add [session factories and configuration](https://docs.laminas.dev/laminas-session/config/) to your application via a module config or `config/autoload` file:
+
+    ```php
+    return [
+        'service_manager' => [
+            'factories' => [
+                // Configures the default SessionManager instance
+                'Laminas\Session\ManagerInterface' => 'Laminas\Session\Service\SessionManagerFactory',
+
+                // Provides session configuration to SessionManagerFactory
+                'Laminas\Session\Config\ConfigInterface' => 'Laminas\Session\Service\SessionConfigFactory',
+            ],
+        ],
+        'session_manager' => [
+            // SessionManager config: validators, etc
+        ],
+        'session_config' => [
+            // Set the session and cookie expiries to 15 minutes
+            'cache_expire' => 900,
+            'cookie_lifetime' => 900,
+        ],
+    ];
+    ```
+
+2. In `Application\Module::onBootstrap`, pull an instance of the SessionManager.  This will inject the properly-configured SessionManager instance as the default for all new session containers.
+
+    ```php
+    public function onBootstrap(MvcEvent $e)
+    {
+        $manager = $e->getApplication()->getServiceManager()->get('Laminas\Session\ManagerInterface');
+    }
+    ```
+
+Alternatively, you could use an external module such as [`HtSession`](https://github.com/hrevert/HtSession) instead of a manual configuration.

docs/docs/howto/how-to-embed-the-login-form-on-another-page.md

@@ -0,0 +1,24 @@
+---
+sidebar_position: 2
+---
+
+# How to embed the login form on another page
+
+## Task
+Embed the login form on another page (ie: homepage login widget)
+
+## Solution
+LmcUser provides a View Helper ([LmcUserLoginWidget](https://github.com/LM-Commons/LmcUser/blob/master/src/LmcUser/View/Helper/LmcUserLoginWidget.php)) which you can use from any view script in your application.  Just add the following call to the location in your markup where you want the form to be rendered:
+
+```php
+<?php echo $this->lmcUserLoginWidget(); ?>
+```
+
+## Note
+The view helper can also __return__ the login form:
+
+```php
+<?php $form = $this->lmcUserLoginWidget(['render' => false]); ?>
+```
+
+This will return an object of type [Login](https://github.com/LM-Commons/LmcUser/blob/master/src/LmcUser/Form/Login.php) that can be used to generate a custom login form.

docs/docs/howto/how-to-modify-the-form-objects-used-by-lmcuser.md

@@ -0,0 +1,27 @@
+---
+sidebar_position: 3
+---
+# How to modify the form objects used by LmcUser
+## Task
+Modify the form objects used by LmcUser for registration and/or login.
+
+## Solution
+You can accomplish this by hooking into the `init` event of the form you wish to modify.  The simplest way to do this is pull the shared event manager and attach a listener.
+
+```php
+<?php
+public function onBootstrap($e)
+{
+    $events = $e->getApplication()->getEventManager()->getSharedManager();
+    $events->attach('LmcUser\Form\Register','init', function($e) {
+        $form = $e->getTarget();
+        // Do what you please with the form instance ($form)
+    });
+    $events->attach('LmcUser\Form\RegisterFilter','init', function($e) {
+        $filter = $e->getTarget();
+        // Do what you please with the filter instance ($filter)
+    });
+}
+```
+
+TODO: Illustrate a method that doesn't use StaticEventManager