Merge pull request #87 from froschdesign/hotfix/docs/validators

Reorganize and expand session validators documentation

docs/book/validators/httpuseragent.md

@@ -0,0 +1,19 @@
+# Http User Agent
+
+`Laminas\Session\Validator\HttpUserAgent` provides a validator to check the session
+against the originally stored `$_SERVER['HTTP_USER_AGENT']` variable. Validation
+will fail in the event that this does not match and throws an exception in
+`Laminas\Session\SessionManager` after `session_start()` has been called.
+
+## Basic Usage
+
+```php
+$manager = new Laminas\Session\SessionManager();
+$manager->getValidatorChain()->attach(
+    'session.validate',
+    [
+        new Laminas\Session\Validator\HttpUserAgent(),
+        'isValid'
+    ]
+);
+```

docs/book/validators/introduction.md

@@ -0,0 +1,16 @@
+# Introduction
+
+laminas-session provides a set of validators that provide protections against session hijacking and against unauthorized requests.
+
+- [Http User Agent](httpuseragent.md)
+- [Remote Addr](remoteaddr.md)
+- [Writing Custom Validators](writing-custom-validators.md)
+
+These validators are based on Laminas component for validation of data and files: [laminas-validator](https://docs.laminas.dev/laminas-validator/).
+
+> MISSING: **Installation Requirements**
+> The validation support of laminas-session depends on the [laminas-validator](https://docs.laminas.dev/laminas-validator/) component, so be sure to have it installed before getting started:
+>
+> ```bash
+> $ composer require laminas/laminas-validator
+> ```

docs/book/validators/remoteaddr.md

@@ -0,0 +1,26 @@
+# Remote Addr
+
+`Laminas\Session\Validator\RemoteAddr` provides a validator to check the session
+against the originally stored `$_SERVER['REMOTE_ADDR']` variable. Validation
+will fail in the event that this does not match and throws an exception in
+`Laminas\Session\SessionManager` after `session_start()` has been called.
+
+> MISSING: **Installation Requirements**
+> The validation of the IP address depends on the [laminas-http](https://docs.laminas.dev/laminas-http/) component, so be sure to have it installed before getting started:
+>
+> ```bash
+> $ composer require laminas/laminas-http
+> ```
+
+## Basic Usage
+
+```php
+$manager = new Laminas\Session\SessionManager();
+$manager->getValidatorChain()->attach(
+    'session.validate',
+    [
+        new Laminas\Session\Validator\RemoteAddr(),
+        'isValid'
+    ]
+  );
+```

docs/book/validators/writing-custom-validators.md

@@ -0,0 +1,6 @@
+# Writing Custom Validators
+
+Own custom validators can be provided to validate against other items from storing a token and validating a token to other various techniques.
+To create a custom validator, the validation interface `Laminas\Session\Validator\ValidatorInterface` _must_ be implemented.
+
+More information on how to create custom validators can be found in the [laminas-validator documentation](https://docs.laminas.dev/laminas-validator/writing-validators/).

mkdocs.yml

@@ -2,17 +2,24 @@ docs_dir: docs/book
 site_dir: docs/html
 nav:
     - Home: index.md
-    - Reference:
-        - "Session Config": config.md
-        - "Session Container": container.md
-        - "Session Manager": manager.md
-        - "Session Save Handlers": save-handler.md
-        - "Session Storage": storage.md
-        - "Session Validators": validator.md
+    - "Session Config": config.md
+    - "Session Container": container.md
+    - "Session Manager": manager.md
+    - "Session Save Handlers": save-handler.md
+    - "Session Storage": storage.md
+    - Validators:
+        - Introduction: validators/introduction.md
+        - "Http User Agent": validators/httpuseragent.md
+        - "Remote Address": validators/remoteaddr.md
+        - "Writing Custom Validators": validators/writing-custom-validators.md
     - "Application Integration":
         - "Usage in a laminas-mvc application": application-integration/usage-in-a-laminas-mvc-application.md
 site_name: laminas-session
 site_description: 'Object-oriented interface to PHP sessions and storage.'
 repo_url: 'https://github.com/laminas/laminas-session'
 extra:
     project: Components
+plugins:
+    - redirects:
+          redirect_maps:
+              validator.md: validators/introduction.md