Add reference

hereldar · Jun 25, 2023 · 6a4ef26 · 6a4ef26
1 parent 81c68bd
commit 6a4ef26
Show file tree

Hide file tree

Showing 11 changed files with 1,087 additions and 479 deletions.
diff --git a/README.md b/README.md
@@ -3,40 +3,40 @@ Results
 
 [![PHP][php-badge]][php-url]
 [![Code Coverage][codecov-badge]][codecov-url]
-[![Type Coverage][shepherd-badge]][shepherd-url]
-[![License][license-badge]][license-url]
+[![Type Coverage][shepherd-coverage-badge]][shepherd-url]
+[![Psalm Level][shepherd-level-badge]][shepherd-url]
 [![Packagist][packagist-version-badge]][packagist-url]
-[![Downloads][packagist-downloads-badge]][packagist-url]
+[![License][license-badge]][license-url]
 
 [php-badge]: https://img.shields.io/badge/php-8.1%20to%208.2-777bb3.svg
 [php-url]: https://coveralls.io/github/hereldar/php-results
 [codecov-badge]: https://img.shields.io/codecov/c/github/hereldar/php-results
 [codecov-url]: https://app.codecov.io/gh/hereldar/php-results
 [coveralls-badge]: https://img.shields.io/coverallsCoverage/github/hereldar/php-results
 [coveralls-url]: https://coveralls.io/github/hereldar/php-results
-[shepherd-badge]: https://shepherd.dev/github/hereldar/php-results/coverage.svg
+[shepherd-coverage-badge]: https://shepherd.dev/github/hereldar/php-results/coverage.svg
+[shepherd-level-badge]: https://shepherd.dev/github/hereldar/php-results/level.svg
 [shepherd-url]: https://shepherd.dev/github/hereldar/php-results
-[license-badge]: https://img.shields.io/badge/license-MIT-brightgreen.svg
-[license-url]: LICENSE
 [packagist-version-badge]: https://img.shields.io/packagist/v/hereldar/results.svg
 [packagist-downloads-badge]: https://img.shields.io/packagist/dt/hereldar/results.svg
 [packagist-url]: https://packagist.org/packages/hereldar/results
+[license-badge]: https://img.shields.io/badge/license-MIT-brightgreen.svg
+[license-url]: LICENSE
 
-This package includes an opinionated version of the `Result` type of Rust. It is 
-not intended to replicate the original type one-to-one, but to allow developers 
-to handle the results in any way they choose.
+This package includes an opinionated version of the `Result` type of 
+Rust. It is not intended to replicate the original type one-to-one, 
+but to allow developers to handle the results in any way they choose.
 
 Use examples
 ------------
 
-This version of the `Result` type allows ignoring errors without a try-catch 
-block:
+This `Result` type allows ignoring errors without a try-catch block:
 
 ```php
-$value = getValue()->or(false);
+$value = getValue()->or($default);
 ```
 
-Also allows throwing the error as a regular exception:
+It also allows throwing the error as a regular exception:
 
 ```php
 doSomething()->orFail();
@@ -60,17 +60,50 @@ $record = fetchRecord()
 And much more:
 
 ```php
-$result = myFunction();
-
-if ($result->isError()) {
-    handleFailure($result->message());
-} else {
-    handleSuccess($result->value());
-}
-
-return match (true) {
-    $result instanceof Ok => $result->value(),
-    $result instanceof MyError => false,
-    default => throw new MyException(),
-}
+doSomething()
+    ->onFailure(logFailure(...))
+    ->onSuccess(logSuccess(...))
+    ->onSuccess(doSomethingElse(...));
 ```
+
+Installation
+------------
+
+Via Composer:
+
+```bash
+composer require hereldar/results
+```
+
+Testing
+-------
+
+Run the following command from the project folder:
+
+```bash
+composer test
+```
+
+To execute:
+
+- A [PHPUnit](https://phpunit.de) test suite.
+- [PHPStan](https://phpstan.org/) and [Psalm](https://psalm.dev/) for
+  static code analysis.
+- [PHP CS Fixer](https://github.com/PHP-CS-Fixer/PHP-CS-Fixer) to fix
+  coding standards.
+
+Documentation
+-------------
+
+- [Guide](https://hereldar.github.io/php-results/)
+- [Reference](https://hereldar.github.io/php-results/reference/)
+
+Credits
+-------
+
+- [Samuel Maudo](https://github.com/samuelmaudo)
+
+License
+-------
+
+The MIT License (MIT). Please see [LICENSE](LICENSE) for more information.
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -2,23 +2,17 @@ import { defineConfig } from 'vitepress'
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
-  title: "PHP Results",
-  description: "An opinionated result type for PHP",
+  lang: 'en-US',
+  title: "Hereldar\\Results",
+  description: "An opinionated result type to manage the results in any way you choose",
   themeConfig: {
     // https://vitepress.dev/reference/default-theme-config
-    nav: [
-      { text: 'Home', link: '/' },
-      { text: 'Examples', link: '/markdown-examples' }
-    ],
-    sidebar: [
-      {
-        text: 'Examples',
-        items: [
-          { text: 'Markdown Examples', link: '/markdown-examples' },
-          { text: 'Runtime API Examples', link: '/api-examples' }
-        ]
-      }
-    ],
+    nav: nav(),
+    sidebar: {
+      '/': sidebarGuide(),
+      '/reference/': sidebarReference()
+    },
+    outline: [2, 3],
     search: {
       provider: 'local'
     },
@@ -28,3 +22,41 @@ export default defineConfig({
   },
   base: '/php-results/'
 })
+
+function nav() {
+  return [
+    {
+      text: 'Guide',
+      items: [
+        {text: 'Getting Started', link: '/'}
+      ]
+    },
+    {
+      text: 'Reference',
+      activeMatch: '/reference/',
+      items: [
+        { text: 'Ok', link: '/reference/ok' },
+        { text: 'Error', link: '/reference/error' }
+      ]
+    }
+  ]
+}
+
+function sidebarGuide() {
+  return [
+    {text: 'Getting Started', link: '/'}
+  ]
+}
+
+function sidebarReference() {
+  return [
+    {
+      text: 'Reference',
+      link: '/reference/',
+      items: [
+        { text: 'Ok', link: '/reference/ok' },
+        { text: 'Error', link: '/reference/error' }
+      ]
+    }
+  ]
+}
diff --git a/docs/index.md b/docs/index.md
@@ -1,19 +1,18 @@
 
-PHP Results
-===========
+Getting Started
+===============
 
-This package includes an opinionated version of the `Result` type of Rust. It is
-not intended to replicate the original type one-to-one, but to allow developers
-to handle the results in any way they choose.
+`Hereldar\Results` includes an opinionated version of the `Result` type of Rust.
+It is not intended to replicate the original type one-to-one, but to allow
+developers to handle the results in any way they choose.
 
 Use examples
 ------------
 
-This `Result` type allows ignoring errors without a try-catch
-block:
+This `Result` type allows ignoring errors without a try-catch block:
 
 ```php
-$value = getValue()->or(false);
+$value = getValue()->or($default);
 ```
 
 It also allows throwing the error as a regular exception:
@@ -40,18 +39,34 @@ $record = fetchRecord()
 And much more:
 
 ```php
-$result = myFunction();
-
-if ($result->isError()) {
-    handleFailure($result->message());
-} else {
-    handleSuccess($result->value());
-}
-
-return match (true) {
-    $result instanceof Ok => $result->value(),
-    $result instanceof MyError => false,
-    default => throw new MyException(),
-}
+doSomething()
+    ->onFailure(logFailure(...))
+    ->onSuccess(logSuccess(...))
+    ->onSuccess(doSomethingElse(...));
 ```
 
+Installation
+------------
+
+Via Composer:
+
+```bash
+composer require hereldar/date-times
+```
+
+Testing
+-------
+
+Run the following command from the project folder:
+
+```bash
+composer test
+```
+
+To execute:
+
+- A [PHPUnit](https://phpunit.de) test suite.
+- [PHPStan](https://phpstan.org/) and [Psalm](https://psalm.dev/) for
+  static code analysis.
+- [PHP CS Fixer](https://github.com/PHP-CS-Fixer/PHP-CS-Fixer) to fix
+  coding standards.