[CLEANUP] Streamline Avatar-related code in EXT:backend 08/51908/4
authorBenni Mack <benni@typo3.org>
Tue, 28 Feb 2017 19:54:22 +0000 (20:54 +0100)
committerBenni Mack <benni@typo3.org>
Fri, 3 Mar 2017 07:58:51 +0000 (08:58 +0100)
- Add proper comments to all PHP code, remove all unnecessary
comments (e.g. "get height" for getHeight() method).
- Move Icon functionality to ViewHelpers instead of doing everything
in PHP.

Resolves: #80066
Releases: master
Change-Id: I5c814824f57112e9603f5994e051f7eb6dd85e45
Reviewed-on: https://review.typo3.org/51908
Reviewed-by: Daniel Goerz <ervaude@gmail.com>
Tested-by: Daniel Goerz <ervaude@gmail.com>
Tested-by: TYPO3com <no-reply@typo3.com>
Reviewed-by: Georg Ringer <georg.ringer@gmail.com>
Tested-by: Georg Ringer <georg.ringer@gmail.com>
Reviewed-by: Benni Mack <benni@typo3.org>
Tested-by: Benni Mack <benni@typo3.org>
typo3/sysext/backend/Classes/Backend/Avatar/Avatar.php
typo3/sysext/backend/Classes/Backend/Avatar/AvatarProviderInterface.php
typo3/sysext/backend/Classes/Backend/Avatar/DefaultAvatarProvider.php
typo3/sysext/backend/Classes/Backend/Avatar/Image.php
typo3/sysext/backend/Classes/ViewHelpers/AvatarViewHelper.php
typo3/sysext/backend/Resources/Private/Templates/Avatar/Main.html

index c4ee1a5..98fb169 100644 (file)
@@ -14,29 +14,32 @@ namespace TYPO3\CMS\Backend\Backend\Avatar;
  * The TYPO3 project - inspiring people to share!
  */
 
+use TYPO3\CMS\Core\Authentication\BackendUserAuthentication;
 use TYPO3\CMS\Core\Cache\CacheManager;
-use TYPO3\CMS\Core\Cache\Frontend\VariableFrontend;
-use TYPO3\CMS\Core\Imaging\Icon;
-use TYPO3\CMS\Core\Imaging\IconFactory;
+use TYPO3\CMS\Core\Cache\Frontend\FrontendInterface;
 use TYPO3\CMS\Core\Service\DependencyOrderingService;
 use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;
 use TYPO3\CMS\Core\Utility\GeneralUtility;
 use TYPO3\CMS\Fluid\View\StandaloneView;
 
 /**
- * Avatar renderer class
+ * Main class to render an avatar image of a certain Backend user, resolving any avatar provider
+ * that takes care of fetching the image.
+ *
+ * See render() and getImgTag() as main entry points
  */
 class Avatar
 {
     /**
-     * Array of sorted and initiated avatar providers
+     * Array of sorted and initialized avatar providers
      *
      * @var AvatarProviderInterface[]
      */
     protected $avatarProviders = [];
 
     /**
-     * Render avatar tag
+     * Renders an avatar based on a Fluid template which contains some base wrapper classes and does
+     * a simple caching functionality, used in Avatar ViewHelper for instance
      *
      * @param array $backendUser be_users record
      * @param int $size width and height of the image
@@ -60,21 +63,11 @@ class Avatar
             $this->validateSortAndInitiateAvatarProviders();
             $view = $this->getFluidTemplateObject();
 
-            // Icon
-            $icon = '';
-            if ($showIcon) {
-                $iconFactory = GeneralUtility::makeInstance(IconFactory::class);
-                $icon = $iconFactory->getIconForRecord('be_users', $backendUser, Icon::SIZE_SMALL)->render();
-            }
-
-            $image = $this->getImgTag($backendUser, $size);
-
-            $view->assignMultiple(
-                [
-                    'image' => $image,
-                    'icon' => $icon
-                ]
-            );
+            $view->assignMultiple([
+                'image' => $this->getImgTag($backendUser, $size),
+                'showIcon' => $showIcon,
+                'backendUser' => $backendUser
+            ]);
             $avatar = $view->render();
             static::getCache()->set($cacheId, $avatar);
         }
@@ -83,7 +76,7 @@ class Avatar
     }
 
     /**
-     * Get avatar img tag
+     * Returns an HTML <img> tag for the avatar
      *
      * @param array $backendUser be_users record
      * @param int $size
@@ -159,7 +152,7 @@ class Avatar
 
         $orderedProviders = GeneralUtility::makeInstance(DependencyOrderingService::class)->orderByDependencies($providers);
 
-        // Initiate providers
+        // Initializes providers
         foreach ($orderedProviders as $configuration) {
             $this->avatarProviders[] = GeneralUtility::makeInstance($configuration['provider']);
         }
@@ -168,7 +161,7 @@ class Avatar
     /**
      * Returns the current BE user.
      *
-     * @return \TYPO3\CMS\Core\Authentication\BackendUserAuthentication
+     * @return BackendUserAuthentication
      */
     protected function getBackendUser()
     {
@@ -179,18 +172,16 @@ class Avatar
      * Returns a new standalone view, shorthand function
      *
      * @param string $filename Which templateFile should be used.
-     *
      * @return StandaloneView
      */
-    protected function getFluidTemplateObject(string $filename = null):StandaloneView
+    protected function getFluidTemplateObject(string $filename = null): StandaloneView
     {
-        /** @var StandaloneView $view */
         $view = GeneralUtility::makeInstance(StandaloneView::class);
         $view->setLayoutRootPaths([GeneralUtility::getFileAbsFileName('EXT:backend/Resources/Private/Layouts')]);
         $view->setPartialRootPaths([GeneralUtility::getFileAbsFileName('EXT:backend/Resources/Private/Partials')]);
         $view->setTemplateRootPaths([GeneralUtility::getFileAbsFileName('EXT:backend/Resources/Private/Templates')]);
 
-        if (is_null($filename)) {
+        if ($filename === null) {
             $filename = 'Main.html';
         }
 
@@ -201,12 +192,10 @@ class Avatar
     }
 
     /**
-     * @return VariableFrontend
+     * @return FrontendInterface
      */
     protected function getCache()
     {
-        /** @var CacheManager $manager */
-        $manager = GeneralUtility::makeInstance(CacheManager::class);
-        return $manager->getCache('cache_runtime');
+        return GeneralUtility::makeInstance(CacheManager::class)->getCache('cache_runtime');
     }
 }
index 8b8ff43..cbc2208 100644 (file)
@@ -15,12 +15,12 @@ namespace TYPO3\CMS\Backend\Backend\Avatar;
  */
 
 /**
- * Class AvatarProviderInterface
+ * Contract for avatar providers that ensure how an avater should be rendered for a given Backend User
  */
 interface AvatarProviderInterface
 {
     /**
-     * Get Image
+     * Returns an Image object, prepared for output, based on a given be_users record
      *
      * @param array $backendUser be_users record
      * @param int $size
index c3054e0..05ec2ca 100644 (file)
@@ -13,6 +13,7 @@ namespace TYPO3\CMS\Backend\Backend\Avatar;
  *
  * The TYPO3 project - inspiring people to share!
  */
+
 use TYPO3\CMS\Core\Database\ConnectionPool;
 use TYPO3\CMS\Core\Resource\Exception\FileDoesNotExistException;
 use TYPO3\CMS\Core\Resource\ProcessedFile;
@@ -20,12 +21,13 @@ use TYPO3\CMS\Core\Resource\ResourceFactory;
 use TYPO3\CMS\Core\Utility\GeneralUtility;
 
 /**
- * Class DefaultAvatarProvider
+ * Avatar Provider used for rendering avatars based on local files (based on FAL), stored in the be_users.avatar
+ * relation field with sys_file_reference.
  */
 class DefaultAvatarProvider implements AvatarProviderInterface
 {
     /**
-     * Get Image
+     * Return an Image object for rendering the avatar, based on a FAL-based file
      *
      * @param array $backendUser be_users record
      * @param int $size
@@ -58,15 +60,15 @@ class DefaultAvatarProvider implements AvatarProviderInterface
     }
 
     /**
-     * Get Avatar fileUid
+     * Get the sys_file UID of the avatar of the given backend user ID
      *
-     * @param int $beUserId
-     * @return int
+     * @param int $backendUserId the UID of the be_users record
+     * @return int the sys_file UID or 0 if none found
      */
-    protected function getAvatarFileUid($beUserId)
+    protected function getAvatarFileUid($backendUserId)
     {
         $queryBuilder = GeneralUtility::makeInstance(ConnectionPool::class)->getQueryBuilderForTable('sys_file_reference');
-        $file = $queryBuilder
+        $fileUid = $queryBuilder
             ->select('uid_local')
             ->from('sys_file_reference')
             ->where(
@@ -84,12 +86,12 @@ class DefaultAvatarProvider implements AvatarProviderInterface
                 ),
                 $queryBuilder->expr()->eq(
                     'uid_foreign',
-                    $queryBuilder->createNamedParameter($beUserId, \PDO::PARAM_INT)
+                    $queryBuilder->createNamedParameter((int)$backendUserId, \PDO::PARAM_INT)
                 )
             )
             ->execute()
             ->fetchColumn();
 
-        return (int)$file;
+        return (int)$fileUid;
     }
 }
index b87b0e7..db16af7 100644 (file)
@@ -13,12 +13,12 @@ namespace TYPO3\CMS\Backend\Backend\Avatar;
  *
  * The TYPO3 project - inspiring people to share!
  */
+
 use TYPO3\CMS\Core\Utility\GeneralUtility;
 use TYPO3\CMS\Core\Utility\PathUtility;
 
 /**
- * Class Image
- *
+ * Acts as a pseudo model for holding all information of an avatar image
  * Holds url + dimensions of avatar image
  */
 class Image
@@ -41,8 +41,6 @@ class Image
     protected $height;
 
     /**
-     * Constructor
-     *
      * @param string $url url of image. Needs to be relative to the website root or an absolute URL.
      * @param int $width width of image
      * @param int $height height of image
@@ -55,7 +53,7 @@ class Image
     }
 
     /**
-     * Get url
+     * Fetches the URL to the the avatar image
      *
      * @param bool $relativeToCurrentScript Determines whether the URL returned should be relative to the current script, in case it is relative at all.
      * @return string
@@ -74,8 +72,6 @@ class Image
     }
 
     /**
-     * Get width
-     *
      * @return int
      */
     public function getWidth()
@@ -84,8 +80,6 @@ class Image
     }
 
     /**
-     * Get height
-     *
      * @return int
      */
     public function getHeight()
index 70aa038..ec31d92 100644 (file)
@@ -13,6 +13,7 @@ namespace TYPO3\CMS\Backend\ViewHelpers;
  *
  * The TYPO3 project - inspiring people to share!
  */
+
 use TYPO3\CMS\Backend\Backend\Avatar\Avatar;
 use TYPO3\CMS\Core\Database\ConnectionPool;
 use TYPO3\CMS\Core\Utility\GeneralUtility;
@@ -21,7 +22,7 @@ use TYPO3Fluid\Fluid\Core\Rendering\RenderingContextInterface;
 use TYPO3Fluid\Fluid\Core\ViewHelper\Traits\CompileWithRenderStatic;
 
 /**
- * Get avatar for backend user
+ * Render the avatar img tag for a given backend user
  */
 class AvatarViewHelper extends AbstractViewHelper
 {
@@ -40,13 +41,13 @@ class AvatarViewHelper extends AbstractViewHelper
     public function initializeArguments()
     {
         parent::initializeArguments();
-        $this->registerArgument('backendUser', 'int', 'Uid of the user', false, 0);
+        $this->registerArgument('backendUser', 'int', 'uid of the backend user', false, 0);
         $this->registerArgument('size', 'int', 'width and height of the image', false, 32);
-        $this->registerArgument('showIcon', 'bool', 'show the record icon', false, false);
+        $this->registerArgument('showIcon', 'bool', 'show the record icon as well', false, false);
     }
 
     /**
-     * Resolve user avatar from backend user id.
+     * Resolve user avatar from a given backend user id.
      *
      * @param array $arguments
      * @param \Closure $renderChildrenClosure
@@ -76,7 +77,6 @@ class AvatarViewHelper extends AbstractViewHelper
             // no BE user can be retrieved from DB, probably deleted
             return '';
         }
-        /** @var Avatar $avatar */
         $avatar = GeneralUtility::makeInstance(Avatar::class);
         return $avatar->render($backendUser, $arguments['size'], $arguments['showIcon']);
     }
index dac008f..bf3eed7 100644 (file)
@@ -1,10 +1,10 @@
-    <span class="avatar">
-    <span class="avatar-image">
-        {image -> f:format.raw()}
-    </span>
-    <f:if condition="{icon}">
-    <span class="avatar-icon">
-        {icon -> f:format.raw()}
-    </span>
-    </f:if>
-</span>
\ No newline at end of file
+<span class="avatar">
+       <span class="avatar-image">
+               {image -> f:format.raw()}
+       </span>
+       <f:if condition="{showIcon}">
+               <span class="avatar-icon">
+                       <core:iconForRecord table="be_users" row="{backendUser}" size="small" />
+               </span>
+       </f:if>
+</span>