From 151aee1b154da38eb7934a3a52b01cfb417cac7d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Frank=20Br=C3=BCckner?= Date: Wed, 19 Jun 2024 15:47:48 +0200 Subject: [PATCH] Reorganize and expand session validators documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The "Session Validators" section in the documentation has been restructured. All validators now have separate files and corresponding navigation links in the sidebar. An introduction file has been added with a brief on what the session validators are. The old 'validator.md' file has been deleted and its content redistributed amongst the newly created files. A redirect has been implemented from the old page to the new 'Introduction' page to maintain backwards compatibility. Signed-off-by: Frank Brückner --- docs/book/validator.md | 54 ------------------- docs/book/validators/httpuseragent.md | 19 +++++++ docs/book/validators/introduction.md | 16 ++++++ docs/book/validators/remoteaddr.md | 26 +++++++++ .../validators/writing-custom-validators.md | 6 +++ mkdocs.yml | 21 +++++--- 6 files changed, 81 insertions(+), 61 deletions(-) delete mode 100644 docs/book/validator.md create mode 100644 docs/book/validators/httpuseragent.md create mode 100644 docs/book/validators/introduction.md create mode 100644 docs/book/validators/remoteaddr.md create mode 100644 docs/book/validators/writing-custom-validators.md diff --git a/docs/book/validator.md b/docs/book/validator.md deleted file mode 100644 index c0e389ff..00000000 --- a/docs/book/validator.md +++ /dev/null @@ -1,54 +0,0 @@ -# Session Validators - -Session validators provide protections against session hijacking. - -## 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 -use Laminas\Session\Validator\HttpUserAgent; -use Laminas\Session\SessionManager; - -$manager = new SessionManager(); -$manager->getValidatorChain() - ->attach('session.validate', [new HttpUserAgent(), 'isValid']); -``` - -## 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. - -> ### 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 -use Laminas\Session\Validator\RemoteAddr; -use Laminas\Session\SessionManager; - -$manager = new SessionManager(); -$manager->getValidatorChain() - ->attach('session.validate', [new RemoteAddr(), 'isValid']); -``` - -## Custom Validators - -You may want to provide your own custom validators to validate against other -items from storing a token and validating a token to other various techniques. -To create a custom validator you *must* implement the validation interface -`Laminas\Session\Validator\ValidatorInterface`. diff --git a/docs/book/validators/httpuseragent.md b/docs/book/validators/httpuseragent.md new file mode 100644 index 00000000..a0b471a8 --- /dev/null +++ b/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' + ] +); +``` diff --git a/docs/book/validators/introduction.md b/docs/book/validators/introduction.md new file mode 100644 index 00000000..cacc95f6 --- /dev/null +++ b/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 +> ``` diff --git a/docs/book/validators/remoteaddr.md b/docs/book/validators/remoteaddr.md new file mode 100644 index 00000000..66c635ac --- /dev/null +++ b/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' + ] + ); +``` diff --git a/docs/book/validators/writing-custom-validators.md b/docs/book/validators/writing-custom-validators.md new file mode 100644 index 00000000..736ab136 --- /dev/null +++ b/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/). diff --git a/mkdocs.yml b/mkdocs.yml index 1ee80afe..a0facd92 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -2,13 +2,16 @@ 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 @@ -16,3 +19,7 @@ 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