Skip to content

Commit

Permalink
Merge pull request #272 from cakephp/3.x-docs
Browse files Browse the repository at this point in the history 
3.x: adjust docs for user entity implements IdentityInterface
  • Loading branch information
@markstory
markstory authored Jan 6, 2024
2 parents abd8f07 + beb1561 commit a516b4b
Show file tree
Hide file tree
Showing 4 changed files with 54 additions and 50 deletions.
42 changes: 21 additions & 21 deletions docs/en/middleware.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -80,33 +80,33 @@ implementing the ``Authorization\IdentityInterface`` and using the
class User extends Entity implements IdentityInterface
{
/**
* Authorization\IdentityInterface method
* @inheritDoc
*/
public function can($action, $resource): bool
public function can(string $action, mixed $resource): bool
{
return $this->authorization->can($this, $action, $resource);
}

/**
* Authorization\IdentityInterface method
* @inheritDoc
*/
public function canResult($action, $resource): ResultInterface
public function canResult(string $action, mixed $resource): ResultInterface
{
return $this->authorization->canResult($this, $action, $resource);
}

/**
* Authorization\IdentityInterface method
* @inheritDoc
*/
public function applyScope($action, $resource)
public function applyScope(string $action, mixed $resource, mixed ...$optionalArgs): mixed
{
return $this->authorization->applyScope($this, $action, $resource);
return $this->authorization->applyScope($this, $action, $resource, ...$optionalArgs);
}

/**
* Authorization\IdentityInterface method
* @inheritDoc
*/
public function getOriginalData()
public function getOriginalData(): \ArrayAccess|array
{
return $this;
}
Expand Down Expand Up @@ -147,7 +147,7 @@ If you also use the Authentication plugin make sure to implement both interfaces
class User extends Entity implements AuthorizationIdentity, AuthenticationIdentity
{
...

/**
* Authentication\IdentityInterface method
*
Expand All @@ -157,7 +157,7 @@ If you also use the Authentication plugin make sure to implement both interfaces
{
return $this->id;
}

...
}

Expand Down Expand Up @@ -202,7 +202,7 @@ Both redirect handlers share the same configuration options:
For example::

use Authorization\Exception\MissingIdentityException;

$middlewareQueue->add(new AuthorizationMiddleware($this, [
'unauthorizedHandler' => [
'className' => 'Authorization.Redirect',
Expand All @@ -214,14 +214,14 @@ For example::
],
],
]));

All handlers get the thrown exception object given as a parameter.
This exception will always be an instance of ``Authorization\Exception\Exception``.
In this example the ``Authorization.Redirect`` handler just gives you the option to
In this example the ``Authorization.Redirect`` handler just gives you the option to
specify which exceptions you want to listen to.

So in this example where we use the ``Authorization.Redirect`` handler we can
add other ``Authorization\Exception\Exception`` based exceptions to the
add other ``Authorization\Exception\Exception`` based exceptions to the
``execeptions`` array if we want to handle them gracefully::

'exceptions' => [
Expand All @@ -239,7 +239,7 @@ Add a flash message after being redirected by an unauthorized request

Currently there is no straightforward way to add a flash message to the unauthorized redirect.

Therefore you need to create your own Handler which adds the flash message (or any
Therefore you need to create your own Handler which adds the flash message (or any
other logic you want to happen on redirect)

How to create a custom UnauthorizedHandler
Expand Down Expand Up @@ -268,10 +268,10 @@ How to create a custom UnauthorizedHandler
#. Tell the AuthorizationMiddleware that it should use your new custom Handler::

// in your src/Application.php

use Authorization\Exception\MissingIdentityException;
use Authorization\Exception\ForbiddenException;

$middlewareQueue->add(new AuthorizationMiddleware($this, [
'unauthorizedHandler' => [
'className' => 'CustomRedirect', // <--- see here
Expand All @@ -284,12 +284,12 @@ How to create a custom UnauthorizedHandler
'custom_param' => true,
],
]));

As you can see you still have the same config parameters as if we are using ``Authorization.Redirect`` as a className.

This is, because we extend our handler based on the RedirectHandler present in the plugin. Therefore all that functionality is present + our own funtionality in the ``handle()`` function.

The ``custom_param`` appears in the ``$options`` array given to you in the ``handle()`` function inside your ``CustomRedirectHandler`` if you wish to add some more config parameters to your functionality.

You can look at `CakeRedirectHandler <https://github.com/cakephp/authorization/blob/2.next/src/Middleware/UnauthorizedHandler/CakeRedirectHandler.php>`__ or `RedirectHandler <https://github.com/cakephp/authorization/blob/2.next/src/Middleware/UnauthorizedHandler/RedirectHandler.php>`__
You can look at `CakeRedirectHandler <https://github.com/cakephp/authorization/blob/2.next/src/Middleware/UnauthorizedHandler/CakeRedirectHandler.php>`__ or `RedirectHandler <https://github.com/cakephp/authorization/blob/2.next/src/Middleware/UnauthorizedHandler/RedirectHandler.php>`__
how such a Handler can/should look like.
32 changes: 16 additions & 16 deletions docs/fr/middleware.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -84,39 +84,39 @@ utilisant l'option ``identityDecorator`` du middleware. Pour commencer, mettons
class User extends Entity implements IdentityInterface
{
/**
* Méthode Authorization\IdentityInterface
* @inheritDoc
*/
public function can($action, $resource): bool
public function can(string $action, mixed $resource): bool
{
return $this->authorization->can($this, $action, $resource);
}

/**
* Méthode Authorization\IdentityInterface
* @inheritDoc
*/
public function canResult($action, $resource): ResultInterface
public function canResult(string $action, mixed $resource): ResultInterface
{
return $this->authorization->canResult($this, $action, $resource);
}

/**
* Méthode Authorization\IdentityInterface
* @inheritDoc
*/
public function applyScope($action, $resource)
public function applyScope(string $action, mixed $resource, mixed ...$optionalArgs): mixed
{
return $this->authorization->applyScope($this, $action, $resource);
return $this->authorization->applyScope($this, $action, $resource, ...$optionalArgs);
}

/**
* Méthode Authorization\IdentityInterface
* @inheritDoc
*/
public function getOriginalData()
public function getOriginalData(): \ArrayAccess|array
{
return $this;
}

/**
* Setter utilisé par le middleware.
* Setter to be used by the middleware.
*/
public function setAuthorization(AuthorizationServiceInterface $service)
{
Expand Down Expand Up @@ -152,7 +152,7 @@ deux interfaces.::
class User extends Entity implements AuthorizationIdentity, AuthenticationIdentity
{
...

/**
* Méthode Authentication\IdentityInterface
*
Expand All @@ -162,7 +162,7 @@ deux interfaces.::
{
return $this->id;
}

...
}

Expand Down Expand Up @@ -209,7 +209,7 @@ configuration:
à un paramètre query de l'URL de redirection (par défaut ``redirect``).
* ``statusCode`` - le code de statut HTTP d'une redirection, par défaut ``302``.

Par exemple::
Par exemple::

use Authorization\Exception\MissingIdentityException;

Expand All @@ -235,7 +235,7 @@ Ainsi, dans cet exemple où nous utilisons le gestionnaire
``Authorization.Redirect``, nous pouvons ajouter au tableau ``exceptions``
d'autres exceptions basées sur ``Authorization\Exception\Exception`` si nous
voulons qu'elles soient traitées convenablement::

'exceptions' => [
MissingIdentityException::class,
ForbiddenException::class
Expand Down Expand Up @@ -286,7 +286,7 @@ Comment créer un UnauthorizedHandler personnalisé

use Authorization\Exception\MissingIdentityException;
use Authorization\Exception\ForbiddenException;

$middlewareQueue->add(new AuthorizationMiddleware($this, [
'unauthorizedHandler' => [
'className' => 'CustomRedirect', // <--- c'est ici !
Expand All @@ -312,5 +312,5 @@ dans la fonction ``handle()`` à l'intérieur de votre ``CustomRedirectHandler``
si vous souhaitez ajouter quelques paramètres de configuration supplémentaires à
vos fonctionnalités personnalisées.

Vous pouvez consulter les classes `CakeRedirectHandler <https://github.com/cakephp/authorization/blob/2.next/src/Middleware/UnauthorizedHandler/CakeRedirectHandler.php>`__ ou `RedirectHandler <https://github.com/cakephp/authorization/blob/2.next/src/Middleware/UnauthorizedHandler/RedirectHandler.php>`__
Vous pouvez consulter les classes `CakeRedirectHandler <https://github.com/cakephp/authorization/blob/2.next/src/Middleware/UnauthorizedHandler/CakeRedirectHandler.php>`__ ou `RedirectHandler <https://github.com/cakephp/authorization/blob/2.next/src/Middleware/UnauthorizedHandler/RedirectHandler.php>`__
pour voir à quoi un Handler pourrait/devrait ressembler.
26 changes: 15 additions & 11 deletions docs/ja/middleware.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -67,33 +67,37 @@ Userクラスを識別子として使用する
class User extends Entity implements IdentityInterface
{
/**
* Authorization\IdentityInterface method
* @inheritDoc
*/
public function can($action, $resource): bool
public function can(string $action, mixed $resource): bool
{
return $this->authorization->can($this, $action, $resource);
}

/**
* Authorization\IdentityInterface method
* @inheritDoc
*/
public function canResult($action, $resource): ResultInterface
public function canResult(string $action, mixed $resource): ResultInterface
{
return $this->authorization->canResult($this, $action, $resource);
}

/**
* Authorization\IdentityInterface method
* @inheritDoc
*/
public function applyScope($action, $resource)
public function applyScope(string $action, mixed $resource, mixed ...$optionalArgs): mixed
{
return $this->authorization->applyScope($this, $action, $resource);
return $this->authorization->applyScope($this, $action, $resource, ...$optionalArgs);
}

/**
* Authorization\IdentityInterface method
* @inheritDoc
*/
public function getOriginalData()
public function getOriginalData(): \ArrayAccess|array
{
return $this;
}

/**
* Setter to be used by the middleware.
*/
Expand Down Expand Up @@ -123,7 +127,7 @@ Authentication(認証)プラグインを使っているなら、両方のイン
class User extends Entity implements AuthorizationIdentity, AuthenticationIdentity
{
...

/**
* Authentication\IdentityInterface method
*
Expand Down Expand Up @@ -249,4 +253,4 @@ Authentication(認証)プラグインを使っているなら、両方のイン
これは、プラグインに存在する RedirectHandler をベースに私たちのハンドラを拡張しているからです。したがって、すべての機能は ``handle()`` 関数内に存在し、私たち自身の機能は ``handle()`` 内に存在します。

カスタムパラメータを追加したい場合は、 ``CustomRedirectHandler`` 内の ``handle()`` 関数で指定した ``$options`` 配列に ``custom_param`` が含まれます。
こちらもご覧ください `CakeRedirectHandler <https://github.com/cakephp/authorization/blob/2.next/src/Middleware/UnauthorizedHandler/CakeRedirectHandler.php>`__ or `RedirectHandler <https://github.com/cakephp/authorization/blob/2.next/src/Middleware/UnauthorizedHandler/RedirectHandler.php>`__
こちらもご覧ください `CakeRedirectHandler <https://github.com/cakephp/authorization/blob/2.next/src/Middleware/UnauthorizedHandler/CakeRedirectHandler.php>`__ or `RedirectHandler <https://github.com/cakephp/authorization/blob/2.next/src/Middleware/UnauthorizedHandler/RedirectHandler.php>`__
4 changes: 2 additions & 2 deletions src/IdentityDecorator.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -60,15 +60,15 @@ public function __construct(AuthorizationServiceInterface $service, ArrayAccess|
/**
* @inheritDoc
*/
public function can(string $action, $resource): bool
public function can(string $action, mixed $resource): bool
{
return $this->authorization->can($this, $action, $resource);
}

/**
* @inheritDoc
*/
public function canResult(string $action, $resource): ResultInterface
public function canResult(string $action, mixed $resource): ResultInterface
{
return $this->authorization->canResult($this, $action, $resource);
}
Expand Down

0 comments on commit a516b4b

Please sign in to comment.