Merge pull request #43 from dotkernel/issue-40

Issue 40

.github/workflows/continuous-integration.yml

@@ -0,0 +1,11 @@
+name: "Continuous Integration"
+
+on:
+  pull_request:
+  push:
+    branches:
+    tags:
+
+jobs:
+  ci:
+    uses: laminas/workflow-continuous-integration/.github/workflows/[email protected]

.github/workflows/docs-build.yml

@@ -0,0 +1,16 @@
+name: docs-build
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Build Docs
+        uses: dotkernel/documentation-theme/github-actions/docs@main
+        env:
+          DEPLOY_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -10,7 +10,7 @@ DotKernel component providing twig extensions and customizations.
 [![GitHub stars](https://img.shields.io/github/stars/dotkernel/dot-twigrenderer)](https://github.com/dotkernel/dot-twigrenderer/stargazers)
 [![GitHub license](https://img.shields.io/github/license/dotkernel/dot-twigrenderer)](https://github.com/dotkernel/dot-twigrenderer/blob/3.0/LICENSE.md)
 
-[![Build Static](https://github.com/dotkernel/dot-twigrenderer/actions/workflows/static-analysis.yml/badge.svg?branch=3.0)](https://github.com/dotkernel/dot-twigrenderer/actions/workflows/static-analysis.yml)
+[![Build Static](https://github.com/dotkernel/dot-twigrenderer/actions/workflows/continuous-integration.yml/badge.svg?branch=3.0)](https://github.com/dotkernel/dot-twigrenderer/actions/workflows/continuous-integration.yml)
 [![codecov](https://codecov.io/gh/dotkernel/dot-twigrenderer/graph/badge.svg?token=M2WTS4DCKX)](https://codecov.io/gh/dotkernel/dot-twigrenderer)
 
 [![SymfonyInsight](https://insight.symfony.com/projects/b9a7d75d-d00a-44a9-b1c0-aea8670681cc/big.svg)](https://insight.symfony.com/projects/b9a7d75d-d00a-44a9-b1c0-aea8670681cc)

SECURITY.md

@@ -0,0 +1,40 @@
+# Security Policy
+
+## Supported Versions
+
+
+| Version | Supported          | PHP Version                                                                                                      |
+|---------|--------------------|------------------------------------------------------------------------------------------------------------------|
+| 3.x     | :white_check_mark: | ![PHP from Packagist (specify version)](https://img.shields.io/packagist/php-v/dotkernel/dot-twigrenderer/3.4.3) |
+| <= 2.x  | :x:                |                                                                                                                  |
+
+
+## Reporting Potential Security Issues
+
+If you have encountered a potential security vulnerability in this project,
+please report it to us at <[email protected]>. We will work with you to
+verify the vulnerability and patch it.
+
+When reporting issues, please provide the following information:
+
+- Component(s) affected
+- A description indicating how to reproduce the issue
+- A summary of the security vulnerability and impact
+
+We request that you contact us via the email address above and give the
+project contributors a chance to resolve the vulnerability and issue a new
+release prior to any public exposure; this helps protect the project's
+users, and provides them with a chance to upgrade and/or update in order to
+protect their applications.
+
+
+## Policy
+
+If we verify a reported security vulnerability, our policy is:
+
+- We will patch the current release branch, as well as the immediate prior minor
+  release branch.
+
+- After patching the release branches, we will immediately issue new security
+  fix releases for each patched release branch.
+

docs/book/index.md

@@ -0,0 +1 @@
+../../README.md

docs/book/v3/configuration.md

@@ -0,0 +1,5 @@
+# Configuration
+
+Register `dot-twigrenderer`'s ConfigProvider in your application's configurations by adding the following line to `config/config.php`:
+
+    \Dot\Twig\ConfigProvider::class,

docs/book/v3/examples.md

@@ -0,0 +1,9 @@
+# Examples
+
+* [Authentication Extension](examples/example-authentication-ext.md)
+* [Authorization Extension](examples/example-authorization-ext.md)
+* [Date Extension](examples/example-date-ext.md)
+* [Flash Messenger Extension](examples/example-flash-messenger-ext.md)
+* [Form Elements Extension](examples/example-form-elements-ext.md)
+* [Navigation Extension](examples/example-navigation-ext.md)
+* [Translation Extension](examples/example-translation-ext.md)

docs/book/v3/examples/example-authentication-ext.md

@@ -0,0 +1,19 @@
+# Using the authentication extension
+
+Dot-twigrenderer extends Twig with functions that use functionality from [laminas/laminas-authentication](https://github.com/laminas/laminas-authentication) to check if the user is authenticated and to get the authenticated identity object respectively.
+
+```php
+public function hasIdentity(): bool;
+
+public function getIdentity(): ?IdentityInterface;
+```
+
+## Example usage
+
+```twig
+{% if hasIdentity() %}
+
+    Welcome, {% getIdentity().username %}!
+
+{% endif %}
+```

docs/book/v3/examples/example-authorization-ext.md

@@ -0,0 +1,25 @@
+# Using the authorization extension
+
+Dot-twigrenderer extends Twig with a function that uses functionality from [dotkernel/dot-authorization](https://github.com/dotkernel/dot-authorization) to check if a logged user is authorized to access a particular resource.
+
+```php
+public function isGranted(string $permission = ''): bool;
+```
+
+The function returns a boolean value of true if the logged user has access to the requested permission.
+
+## Example usage
+
+Expanding on the example from the authentication extension:
+
+```twig
+{% if hasIdentity() %}
+
+    Welcome, {% getIdentity().username %}!
+    
+    {% if isGranted({{ role }}) %}
+        {# your code #}
+    {% endif %}
+
+{% endif %}
+```

docs/book/v3/examples/example-date-ext.md

@@ -0,0 +1,31 @@
+# Using the date extension
+
+Dot-twigrenderer extends Twig with a function that calculates the difference between two dates. The function converts dates to a time ago string like Facebook and Twitter has. If `null` is passed as the second or third parameters, the current time will be used.
+
+```php
+public function diff(
+        Environment $env,
+        string|DateTimeInterface|null $date,
+        string|DateTimeZone|null $now = null
+    ): string;
+```
+
+## Example usage
+
+Pass Twig's Environment to the template
+
+```php
+$loader = new \Twig\Loader\FilesystemLoader(__DIR__ . '/../../templates/page');
+$twigEnv = new \Twig\Environment($loader);
+
+$this->template->render('page::templateName', [
+                "env" => $twigEnv,
+                #other parameters
+                ]); 
+```
+
+This enables the use of the `diff` function:
+
+```twig
+{{ diff(env, '2024-02-20', '2024-02-18') }}
+```

docs/book/v3/examples/example-flash-messenger-ext.md

@@ -0,0 +1,30 @@
+# Using the flash messenger extension
+
+Dot-twigrenderer extends Twig with functions that use functionality from [dotkernel/dot-flashMessenger](https://github.com/dotkernel/dot-flashMessenger) to list messages or partial messages.
+
+```php
+public function renderMessages(
+        ?string $type = null,
+        string $channel = FlashMessengerInterface::DEFAULT_CHANNEL
+    ): string; // empty response
+
+public function function renderMessagesPartial(
+        string $partial,
+        array $params = [],
+        ?string $type = null,
+        string $channel = FlashMessengerInterface::DEFAULT_CHANNEL
+    ): string;
+```
+
+`renderMessagesPartial` returns messages previously passed to `dot-flashMessenger`. The last 3 parameters can be omitted to list all messages sent to FlashMessenger.
+
+* `$partial` is the template file name
+* `$params` is an optional array of items (key-value) passed to the template file
+* `$type` is an optional item that identifies a subkey of FlashMessenger's channel array
+* `$channel` is an optional item that identifies FlashMessenger's channel
+
+## Example usage
+
+```twig
+{{ renderMessagesPartial('page:partial') }}
+```

docs/book/v3/examples/example-form-elements-ext.md

@@ -0,0 +1,17 @@
+# Using the form elements extension
+
+Dot-twigrenderer extends Twig with a function based on `TwigTest` that checks if each `Form` element is an instance of its class.
+
+```php
+public function getTests(): array;
+```
+
+## Example usage
+
+```twig
+{% if false not in getTests() %}
+    
+    {# your code #}
+
+{% endif %}
+```

docs/book/v3/examples/example-navigation-ext.md

@@ -0,0 +1,18 @@
+# Using the navigation extension
+
+Dot-twigrenderer extends Twig with functions that use functionality from [dotkernel/dot-navigation](https://github.com/dotkernel/dot-navigation) to easily parse a menu and to display escaped HTML inside a template.
+
+```php
+public function htmlAttributes(Page $page): string;
+
+public function renderMenu(NavigationContainer|string $container): string; //incomplete?
+
+public function renderMenuPartial(
+        NavigationContainer|string $container,
+        string $partial,
+        array $params = []
+    ): string;
+```
+
+* `$partial` is the template file name
+* `$params` is an optional array of items (key-value) passed to the template file