[FEATURE] Introduce AvatarProvider
[Packages/TYPO3.CMS.git] / typo3 / sysext / core / Documentation / Changelog / master / Feature-68429-IntroducedAvatarProviderAPI.rst
1 ===============================================
2 Feature: #68429 - Introduced AvatarProvider API
3 ===============================================
4
5 Description
6 ===========
7
8 To make providing a avatar image for BE users more flexible a API it introduced so you can register AvatarProviders.
9 The core provides the ``ImageProvider`` by default.
10
11 When an avatar is rendered in the BE the available AvatarProviders are asked if they can provide an
12 ``TYPO3\CMS\Backend\Backend\Image`` for given ``be_user`` and requested size. The first ``TYPO3\CMS\Backend\Backend\Image``
13 that gets returned is used.
14
15 Registering a avatar provider
16 -----------------------------
17
18 A avatar provider can be registered within your ``ext_localconf.php`` file like this:
19
20 .. code-block:: php
21
22 $GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['backend']['avatarProviders']['myCustomProvider'] = [
23 'provider' => \MyVendor\MyExtension\AvatarProvider\CompanyAvatarProvider::class,
24 'before' => ['imageProvider']
25 ];
26
27 The settings are defined as:
28
29 * ``provider``: The avatar provider class name, which must implement ``TYPO3\CMS\Backend\Backend\AvatarProviderInterface``.
30 * ``before``/``after``: You can define the ordering how providers are executed. This is order is used as fallback of the avatar providers. Each property must be an array of provider names.
31
32
33 For a new avatar provider you have to register a **new key** in ``$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['backend']['avatarProviders']``.
34 If your avatar provider extends another one, you may only overwrite necessary settings. An example would be to
35 extend an existing provider and replace its registered 'provider' class with your new class name.
36
37 .. code-block:: php
38
39 $GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['backend']['avatarProviders']['imageProvider']['provider'] = \MyVendor\MyExtension\AvatarProvider\CustomImageProvider::class
40
41
42 AvatarProviderInterface
43 -----------------------
44
45 The AvatarProviderInterface contains only one method:
46
47 ``public function getImage(array $backendUser, $size);``
48
49 The parameters are defined as:
50
51 * ``$backendUser``: The record of from ``be_user`` database table.
52 * ``$size``: The requested size of the avatar image.
53
54 The return value of the method is expected to be and ``TYPO3\CMS\Backend\Backend\Image`` instance or NULL when the
55 provider can not provide an image.
56
57 An ``TYPO3\CMS\Backend\Backend\Image`` object holds 3 properties:
58
59 * ``$url``: Url of avatar image. Needs to be relative to the /typo3/ folder or an absolute URL.
60 * ``$width``: The width of the image.
61 * ``$height``: The height of the image.