Skip to content
This repository was archived by the owner on Jan 29, 2020. It is now read-only.

Commit 91fcda5

Browse files
committed
Rewrite section on DefaultUser and related factory
1 parent 40df2d3 commit 91fcda5

File tree

1 file changed

+34
-17
lines changed

1 file changed

+34
-17
lines changed

docs/book/v1/intro.md

Lines changed: 34 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -22,24 +22,24 @@ namespace Zend\Expressive\Authentication;
2222
interface UserInterface
2323
{
2424
/**
25-
* Get the unique user identity (id, username, email address or ...)
25+
* Get the unique user identity (id, username, email address, etc.).
2626
*/
2727
public function getIdentity() : string;
2828

2929
/**
30-
* Get all user roles
30+
* Get all user roles.
3131
*
3232
* @return string[]
3333
*/
3434
public function getRoles() : array;
3535

3636
/**
37-
* Get a detail $name if present, $default otherwise
37+
* Get the detail named $name if present; return $default otherwise.
3838
*/
3939
public function getDetail(string $name, $default = null);
4040

4141
/**
42-
* Get all the details, if any
42+
* Get all additional user details, if any.
4343
*/
4444
public function getDetails() : array;
4545
}
@@ -52,28 +52,40 @@ authorization level of a user (for this scope, it is consumed by
5252

5353
## Default User class
5454

55-
We provide a default implementation of `UserInterface` via the class `Zend\Expressive\Authentication\DefaultUser`.
56-
The class is final and immutable, in order to prevent runtime changes.
57-
We provide a factory class for generating `DefaultUser` instances via
58-
`Zend\Expressive\Authentication\DefaultUserFactory`.
55+
We provide a default implementation of `UserInterface` via the class
56+
`Zend\Expressive\Authentication\DefaultUser`. The class is final and immutable,
57+
in order to prevent runtime changes.
5958

60-
In order to set the identity and the user's role we provided a default factory
61-
class that generates a `UserInterface` object. This factory is
62-
`Zend\Expressive\Authentication\UserInterfaceFactory`. This class uses a `generate`
63-
function to create a `UserInterface` instance passing the identity and the roles
64-
(if any) of the user.
59+
Repositories will fetch user information based on the identity, including any
60+
associated roles, and optionally any additional details (full name, email,
61+
profile information, etc.). Often, user data and the objects representing them
62+
are unique to the application. As such, the default repository implementations
63+
we provide allow you to inject a _factory_ for producing the user. This factory
64+
should be a PHP callable with the following signature:
6565

66-
If you want, you can customize the `UserInterfaceFactory` using your custom
67-
`UserInterface` implementation. You need to change the service configuration as
68-
follows:
66+
```php
67+
function (string $identity, array $roles = [], array $details = []) : UserInterface
68+
```
69+
70+
In order to notify the package to use your custom factory, you will need to
71+
create a service factory that returns it, and map it to the
72+
`Zend\Expressive\Authentication\UserInterface` service.
73+
74+
We provide a service factory named `Zend\Expressive\Authentication\DefaultUserFactory`
75+
that returns a user factory that produces a `DefaultUser` instance from the
76+
arguments provided. This is mapped as follows in the service configuration:
6977

7078
```php
79+
use Zend\Expressive\Authentication\DefaultUserFactory;
80+
use Zend\Expressive\Authentication\UserInterface;
81+
7182
return [
7283
// ...
7384
'dependencies' => [
7485
'factories' => [
7586
// ...
76-
// change the DefaultUserFactory::class with your custom factory
87+
// Change the DefaultUserFactory::class with your custom service
88+
// factory that produces a user factory:
7789
UserInterface::class => DefaultUserFactory::class
7890
]
7991
]
@@ -113,6 +125,11 @@ Basic Access Authentication* adapter and the *htpasswd* file as the user
113125
repository.
114126

115127
```php
128+
use Zend\Expressive\Authentication\AuthenticationInterface;
129+
use Zend\Expressive\Authentication\Basic;
130+
use Zend\Expressive\Authentication\UserRepository;
131+
use Zend\Expressive\Authentication\UserRepositoryInterface;
132+
116133
return [
117134
// ...
118135
'dependencies' => [

0 commit comments

Comments
 (0)