Skip to content

Commit

Permalink
Merge pull request #14 from poprazvan17/3.0
Browse files Browse the repository at this point in the history
Documentation v3 dot-authorization
  • Loading branch information
alexmerlin authored May 3, 2024
2 parents 95640f3 + bfc7379 commit 41fa86c
Show file tree
Hide file tree
Showing 14 changed files with 154 additions and 102 deletions.
Original file line number Diff line number Diff line change
@@ -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 }}

Expand All @@ -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
Expand All @@ -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 }}
11 changes: 11 additions & 0 deletions .github/workflows/continuous-integration.yml
Original file line number Diff line number Diff line change
@@ -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
47 changes: 0 additions & 47 deletions .github/workflows/cs-tests.yml

This file was deleted.

16 changes: 16 additions & 0 deletions .github/workflows/docs-build.yml
Original file line number Diff line number Diff line change
@@ -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 }}
47 changes: 0 additions & 47 deletions .github/workflows/static-analysis.yml

This file was deleted.

8 changes: 6 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
Expand All @@ -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;
```
Expand Down
39 changes: 39 additions & 0 deletions SECURITY.md
Original file line number Diff line number Diff line change
@@ -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.

1 change: 1 addition & 0 deletions docs/book/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
../../README.md
3 changes: 3 additions & 0 deletions docs/book/v3/configuration.md
Original file line number Diff line number Diff line change
@@ -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.
5 changes: 5 additions & 0 deletions docs/book/v3/instalation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# Installation

Install `dot-authorization` by executing the following Composer command:

composer require dotkernel/dot-authorization
3 changes: 3 additions & 0 deletions docs/book/v3/overview.md
Original file line number Diff line number Diff line change
@@ -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.
33 changes: 33 additions & 0 deletions docs/book/v3/usage.md
Original file line number Diff line number Diff line change
@@ -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.
19 changes: 19 additions & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
@@ -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
6 changes: 6 additions & 0 deletions phpunit.xml
Original file line number Diff line number Diff line change
Expand Up @@ -7,4 +7,10 @@
<directory>./test</directory>
</testsuite>
</testsuites>
<coverage/>
<source>
<include>
<directory suffix=".php">./src</directory>
</include>
</source>
</phpunit>

0 comments on commit 41fa86c

Please sign in to comment.