Documentation v3 dot-authorization

.github/workflows/unit-tests.yaml → .github/workflows/codecov.yml

@@ -1,11 +1,11 @@
 on:
   - push
 
-name: Run PHPUnit tests
+name: Run Codecov checks
 
 jobs:
-  mutation:
-    name: PHP ${{ matrix.php }}-${{ matrix.os }}
+  code-coverage:
+    name: Code Coverage
 
     runs-on: ${{ matrix.os }}
 
@@ -27,8 +27,9 @@ jobs:
         uses: shivammathur/setup-php@v2
         with:
           php-version: "${{ matrix.php }}"
+          coverage: pcov
+          ini-values: assert.exception=1, zend.assertions=1, error_reporting=-1, log_errors_max_len=0, display_errors=On
           tools: composer:v2, cs2pr
-          coverage: none
 
       - name: Determine composer cache directory
         run: echo "COMPOSER_CACHE_DIR=$(composer config cache-dir)" >> $GITHUB_ENV
@@ -44,5 +45,10 @@ jobs:
       - name: Install dependencies with composer
         run: composer install --prefer-dist --no-interaction --no-progress --optimize-autoloader --ansi
 
-      - name: Run PHPUnit tests
-        run: vendor/bin/phpunit --colors=always
+      - name: Collect code coverage with PHPUnit
+        run: vendor/bin/phpunit --colors=always --coverage-clover clover.xml
+
+      - name: Send code coverage report to Codecov.io
+        uses: codecov/codecov-action@v3
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}

.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/continuous-integration.yml@1.x

.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,14 +10,15 @@ Authorization base package defining interfaces for authorization services to be
 [![GitHub stars](https://img.shields.io/github/stars/dotkernel/dot-authorization)](https://github.com/dotkernel/dot-authorization/stargazers)
 [![GitHub license](https://img.shields.io/github/license/dotkernel/dot-authorization)](https://github.com/dotkernel/dot-authorization/blob/3.0/LICENSE.md)
 
-[![Build Static](https://github.com/dotkernel/dot-authorization/actions/workflows/static-analysis.yml/badge.svg?branch=3.0)](https://github.com/dotkernel/dot-authorization/actions/workflows/static-analysis.yml)
+[![Build Static](https://github.com/dotkernel/dot-authorization/actions/workflows/continuous-integration.yml/badge.svg?branch=3.0)](https://github.com/dotkernel/dot-authorization/actions/workflows/continuous-integration.yml)
+[![codecov](https://codecov.io/gh/dotkernel/dot-authorization/graph/badge.svg?token=ZBZDEA3LY8)](https://codecov.io/gh/dotkernel/dot-authorization)
 
 [![SymfonyInsight](https://insight.symfony.com/projects/014df510-1cf7-4876-b1a8-303fbef2f364/big.svg)](https://insight.symfony.com/projects/014df510-1cf7-4876-b1a8-303fbef2f364)
 
-
 ## Installation
 
 Run the following command in you project directory
+
 ```bash
 $ composer require dotkernel/dot-authorization
 ```
@@ -29,14 +30,17 @@ Please note that usually this pacakge will be installed as a dependency to a con
 Defines the interface that should be implemented by any authorization service, in order to work with DotKernel applications. This is a result of the fact that, by default, any DotKernel package which has to do with authorization is assuming that a service is registered in the service container using as service name this interface's FQN
 
 ### Methods
+
 ```php
 public function isGranted(string $permission, array $roles = [], $context = null): bool;
 ```
+
 * this is the only method that deals with authorization. Given a permission and a list of roles, should return a boolean value of true if at least one role has access to the requested permission. As you can see, we expect that the authorization service to be implemented as an RBAC.
 
 ## RoleInterface
 
 Defines the interface that Role objects must implement. A role object should be able to retrieve its name, so this interface has only one method defined
+
 ```php
 public function getName(): string;
 ```

SECURITY.md

@@ -0,0 +1,39 @@
+# 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-authorization/3.4.1) |
+| <= 2.x  | :x:                |                                                                                                                   |
+
+## Reporting Potential Security Issues
+
+If you have encountered a potential security vulnerability in this project,
+please report it to us at <security@dotkernel.com>. 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,3 @@
+# Configuration
+
+Please note that usually this pacakge will be installed as a dependency to a concrete implementation, so you won't need to add this to your project manually.

docs/book/v3/instalation.md

@@ -0,0 +1,5 @@
+# Installation
+
+Install `dot-authorization` by executing the following Composer command:
+
+    composer require dotkernel/dot-authorization

docs/book/v3/overview.md

@@ -0,0 +1,3 @@
+# Overview
+
+`dot-authorization` is DotKernel's authorization base package which define interfaces for authorization services to be used with DotKernel applications.

docs/book/v3/usage.md

@@ -0,0 +1,33 @@
+# Usage
+
+## AuthorizationInterface
+
+Defines the interface that should be implemented by any authorization service, in order to work with DotKernel applications. This is a result of the fact that, by default, any DotKernel package which has to do with authorization is assuming that a service is registered in the service container using as service name this interface's FQN
+
+### Methods
+
+```php
+public function isGranted(string $permission, array $roles = [], $context = null): bool;
+```
+
+* this is the only method that deals with authorization. Given a permission and a list of roles, should return a boolean value of true if at least one role has access to the requested permission. As you can see, we expect that the authorization service to be implemented as an RBAC.
+
+## RoleInterface
+
+Defines the interface that Role objects must implement. A role object should be able to retrieve its name, so this interface has only one method defined
+
+```php
+public function getName(): string;
+```
+
+## IdentityInterface
+
+Interface that needs to be implemented by entities that support roles. They should be able to retrieve their roles by defining a `getRoles()` method.
+The roles should be an array of role names or role objects
+
+This package is suitable for RBAC style authorization. Roles can be flat or hierarchical and they are assigned permissions.
+A role is granted if it has the required permission.
+
+## ForbiddenException
+
+Exception to be thrown when accessing content without having the required permissions. This can be used withing an application to trigger a forbidden error and do a custom action(like displaying a forbidden page or redirecting). This package does not define how you should handle such situations. There is a concrete authorization implementation in [dot-rbac](https://github.com/dotkernel/dot-rbac) and a forbidden exception handler in [dot-rbac-guard](https://github.com/dotkernel/dot-rbac-guard) as DotKernel default packages for authorization.

mkdocs.yml

@@ -0,0 +1,19 @@
+docs_dir: docs/book
+site_dir: docs/html
+extra:
+  project: Packages
+  current_version: v3
+  versions:
+    - v3
+nav:
+  - Home: index.md
+  - v2:
+      - Overview: v3/overview.md
+      - Installation: v3/installation.md
+      - Configuration: v3/configuration.md
+      - Usage: v3/usage.md
+site_name: dot-authorization
+site_description: "DotKernel authorization service abstractions"
+repo_url: "https://github.com/dotkernel/dot-authorization"
+plugins:
+  - search

phpunit.xml

@@ -7,4 +7,10 @@
             <directory>./test</directory>
         </testsuite>
     </testsuites>
+    <coverage/>
+    <source>
+        <include>
+            <directory suffix=".php">./src</directory>
+        </include>
+    </source>
 </phpunit>