docs: add runtime-check-bundle doc

sitepark · Jun 18, 2024 · 12f3b55 · 12f3b55
1 parent ad71daf
commit 12f3b55
Show file tree

Hide file tree

Showing 5 changed files with 92 additions and 2 deletions.
diff --git a/docs/develop/bundles/deployment.md b/docs/develop/bundles/deployment.md
@@ -1,5 +1,7 @@
 # Deployment Bundle
 
+Symfony bundle to react to the deploy and undeploy of a project.
+
 ## Sources
 
 The sources can be accessed via the GibHub project [https://github.com/sitepark/atoolo-deployment-bundle](https://github.com/sitepark/atoolo-deployment-bundle){:target="\_blank"}.

diff --git a/docs/develop/bundles/index.md b/docs/develop/bundles/index.md
@@ -16,7 +16,8 @@ composer require atoolo/[bundle]
 | <div style="width:15em">Name</div>                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | [`atoolo/deployment-bundle`](deployment.md)         | Symfony bundle to react to the deploy and undeploy of a project.                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| [`atoolo/resource-bundle`](resource.md)             | In the Atoolo context, resources from IES (Sitepark's content management system) are aggregated data that can be handled through this library.                                                                                                                                                                                                                                                                                                                                   |
+| [`atoolo/runtime-check-bundle`](runtime-check.md)   | Symfony bundle to react to the deploy and undeploy of a project.                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| [`atoolo/resource-bundle`](resource.md)             | Symfony bundle which contains tools that can be used to check whether the current runtime environment is set up as expected.                                                                                                                                                                                                                                                                                                                                                     |
 | [`atoolo/search-bundle`](search/index.md)           | Provides services with which a Solr index can be filled and searched for [resources](resource.md) via this index.                                                                                                                                                                                                                                                                                                                                                                |
 | [`atoolo/graphql-search-bundle`](graphql-search.md) | This bundle extends the GraphQL interface with a [search](../graphql/search/index.md).                                                                                                                                                                                                                                                                                                                                                                                           |
 | [`atoolo/citygov-bundle`](citygov.md)               | CityGov is a product of Sitepark. The main areas of application of CityGov are the Internet presences of municipalities and district administrations as well as their employee portals on the intranet.                                                                                                                                                                                                                                                                          |

diff --git a/docs/develop/bundles/runtime-check.md b/docs/develop/bundles/runtime-check.md
@@ -0,0 +1,86 @@
+# Runtime Check Bundle
+
+Symfony bundle which contains tools that can be used to check whether the current runtime environment is set up as expected.
+
+## Sources
+
+The sources can be accessed via the GibHub project [https://github.com/sitepark/runtime-check-bundle](https://github.com/sitepark/atoolo-runtime-check-bundle){:target="\_blank"}.
+
+## Installation
+
+Use [Composer](https://getcomposer.org/){:target="\_blank"} to install this component in your PHP project:
+
+```sh
+composer require atoolo/runtime-check-bundle
+```
+
+## Motivation
+
+The bundle is an addition to the [Runtime component](../components/runtime.md). Unlike the [Runtime component](../components/runtime.md), the checks are not carried out each time they are called, but must be triggered explicitly. This can be done via a command line command or via an HTTP request. The aim is to provide a possibility to check the project for its executability. It should support PHP updates by allowing the checks to be carried out before the new PHP version is activated.
+
+Furthermore, the project or other bundles should be able to extend the checks. The checks are also intended to be executed regularly by a monitoring system.
+
+## Usage
+
+The use of the bundle is described under [Operate / Runtime check](../../operate/runtime-check.md).
+
+## Custom Checks
+
+The bundle provides an interface `Atoolo\Runtime\Check\Service\Checker\Checker`, which can be used to implement your own checks.
+
+Here is an example for your own check:
+
+```php
+declare(strict_types=1);
+
+namespace Example\Service\Checker;
+
+use Atoolo\Runtime\Check\Service\Checker;
+use Atoolo\Runtime\Check\Service\CheckStatus;
+
+class MyChecker implements Checker
+{
+    public function getScope(): string
+    {
+        return "myscope";
+    }
+
+    public function check(): CheckStatus
+    {
+
+        $success = ... // check if the check is successful
+
+        if (!$success) {
+          $status = CheckStatus::createFailure();
+          $status->addReport($this->getScope(), [
+            'myfield' => 'myvalue'
+            // any other data
+          ]);
+          $status->addMessage($this->getScope(), "My error message");
+          return $status;
+        }
+
+        $status = CheckStatus::createSuccess();
+        $status->addReport($this->getScope(), [
+          'myfield' => 'myvalue'
+          // any other data
+        ]);
+
+        return $status;
+    }
+}
+```
+
+If the check is successful, a status is created with `CheckStatus::createSuccess()`. If the check fails, the status is created with `CheckStatus::createFailure()`. Report data can be added in both cases. In the event of an error, at least one error message should be added with `$status->addMessage()`.
+
+The scope is any name that is assigned to the check. The checks can be grouped via the scope.
+
+The check must still be registered as a service:
+
+`services.yaml`
+
+```yaml
+Example\Service\Checker\MyChecker:
+  tags:
+    - { name: "atoolo_runtime_check.checker" }
+```
diff --git a/docs/operate/runtime-checks.md → docs/operate/runtime-check.md b/docs/operate/runtime-checks.md → docs/operate/runtime-check.md
@@ -1,4 +1,4 @@
-# Runtime checks
+# Runtime check
 
 Atoolo provides a set of runtime checks to ensure that the application is running as expected. These checks can be used to monitor the application's health and to detect potential issues early on.
 

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -19,6 +19,7 @@ nav:
       - Bundle:
           - develop/bundles/index.md
           - Deployment: develop/bundles/deployment.md
+          - Runtime check: develop/bundles/runtime-check.md
           - Resource: develop/bundles/resource.md
           - Search: develop/bundles/search/index.md
           - Security: develop/bundles/security.md