From f7b14410507a8fca6ad91bfafe8f8fe122ae61b1 Mon Sep 17 00:00:00 2001
From: Yuri Kuznetsov <yurikuzn@users.noreply.github.com>
Date: Sat, 27 Jun 2020 23:51:29 +0300
Subject: [PATCH] comments and datime type hint

---
 .../Core/Utils/AdminNotificationManager.php   |  3 ++
 application/Espo/Core/Utils/Auth.php          |  3 ++
 application/Espo/Core/Utils/ClassFinder.php   |  7 ++-
 application/Espo/Core/Utils/ClientManager.php |  3 ++
 application/Espo/Core/Utils/Config.php        |  4 +-
 application/Espo/Core/Utils/DataUtil.php      |  3 +-
 application/Espo/Core/Utils/DateTime.php      | 48 ++++++++++---------
 .../Espo/Core/Utils/EmailFilterManager.php    | 11 ++++-
 application/Espo/Core/Utils/EntityManager.php |  3 ++
 application/Espo/Core/Utils/FieldManager.php  |  3 ++
 .../Espo/Core/Utils/FieldManagerUtil.php      |  3 ++
 11 files changed, 63 insertions(+), 28 deletions(-)

diff --git a/application/Espo/Core/Utils/AdminNotificationManager.php b/application/Espo/Core/Utils/AdminNotificationManager.php
index 5723119186..f47ac5b68b 100644
--- a/application/Espo/Core/Utils/AdminNotificationManager.php
+++ b/application/Espo/Core/Utils/AdminNotificationManager.php
@@ -32,6 +32,9 @@ namespace Espo\Core\Utils;
 use Espo\Core\Exceptions\NotFound;
 use Espo\Core\Utils\Util;
 
+/**
+ * Notifications on the admin panel.
+ */
 class AdminNotificationManager
 {
     private $container;
diff --git a/application/Espo/Core/Utils/Auth.php b/application/Espo/Core/Utils/Auth.php
index ec034c634b..7409b795c3 100644
--- a/application/Espo/Core/Utils/Auth.php
+++ b/application/Espo/Core/Utils/Auth.php
@@ -44,6 +44,9 @@ use Espo\Core\Utils\Authentication\TwoFA\CodeInterface as TwoFACodeInterface;
 
 use Espo\Core\Container;
 
+/**
+ * Handles authentication. The entry point of the auth process.
+ */
 class Auth
 {
     protected $allowAnyAccess;
diff --git a/application/Espo/Core/Utils/ClassFinder.php b/application/Espo/Core/Utils/ClassFinder.php
index 51f355c573..b2686f049b 100644
--- a/application/Espo/Core/Utils/ClassFinder.php
+++ b/application/Espo/Core/Utils/ClassFinder.php
@@ -29,6 +29,11 @@
 
 namespace Espo\Core\Utils;
 
+/**
+ * Finds classes of a specific category. Category examples: Services, Controllers.
+ * First it checks ib the custom folder, then modules, then the internal folder.
+ * Available as 'classFinder' service.
+ */
 class ClassFinder
 {
     protected $classParser;
@@ -47,7 +52,7 @@ class ClassFinder
     }
 
     /**
-     * Find class name by category (e.g. Controllers, Services) and name.
+     * Find class name by a category and name.
      */
     public function find(string $category, string $name, bool $subDirs = false) : ?string
     {
diff --git a/application/Espo/Core/Utils/ClientManager.php b/application/Espo/Core/Utils/ClientManager.php
index 32aee81dfa..06ae3bd828 100644
--- a/application/Espo/Core/Utils/ClientManager.php
+++ b/application/Espo/Core/Utils/ClientManager.php
@@ -29,6 +29,9 @@
 
 namespace Espo\Core\Utils;
 
+/**
+ * Renders the main HTML page.
+ */
 class ClientManager
 {
     private $themeManager;
diff --git a/application/Espo/Core/Utils/Config.php b/application/Espo/Core/Utils/Config.php
index 338703c24d..d99f335d66 100644
--- a/application/Espo/Core/Utils/Config.php
+++ b/application/Espo/Core/Utils/Config.php
@@ -31,6 +31,9 @@ namespace Espo\Core\Utils;
 
 use Espo\Core\Exceptions\Error;
 
+/**
+ * Reads and writes the main config file.
+ */
 class Config
 {
     private $defaultConfigPath = 'application/Espo/Core/defaults/config.php';
@@ -50,7 +53,6 @@ class Config
         'defaultPermissions',
     ];
 
-
     private $data;
 
     private $changedData = [];
diff --git a/application/Espo/Core/Utils/DataUtil.php b/application/Espo/Core/Utils/DataUtil.php
index 33daf6fb39..199a7bc8a9 100644
--- a/application/Espo/Core/Utils/DataUtil.php
+++ b/application/Espo/Core/Utils/DataUtil.php
@@ -29,7 +29,7 @@
 
 namespace Espo\Core\Utils;
 
-use \Espo\Core\Exceptions\Error;
+use Espo\Core\Exceptions\Error;
 
 class DataUtil
 {
@@ -167,4 +167,3 @@ class DataUtil
         }
     }
 }
-
diff --git a/application/Espo/Core/Utils/DateTime.php b/application/Espo/Core/Utils/DateTime.php
index b1e1b78bb6..aeec9d165d 100644
--- a/application/Espo/Core/Utils/DateTime.php
+++ b/application/Espo/Core/Utils/DateTime.php
@@ -31,6 +31,10 @@ namespace Espo\Core\Utils;
 
 use Carbon\Carbon;
 
+/**
+ * Util for a date-time formatting and convetion.
+ * Available as 'dateTime' service.
+ */
 class DateTime
 {
     protected $dateFormat;
@@ -68,55 +72,54 @@ class DateTime
         ?string $timeFormat = 'HH:mm',
         ?string $timeZone = 'UTC',
         ?string $language = 'en_US'
-    )
-    {
+    ) {
         $this->dateFormat = $dateFormat ?? 'YYYY-MM-DD';
         $this->timeFormat = $timeFormat ?? 'HH:mm';
         $this->timezone = new \DateTimeZone($timeZone ?? 'UTC');
         $this->language = $language ?? 'en_US';
     }
 
-    public function getDateFormat()
+    public function getDateFormat() : string
     {
         return $this->dateFormat;
     }
 
-    public function getDateTimeFormat()
+    public function getDateTimeFormat() : string
     {
         return $this->dateFormat . ' ' . $this->timeFormat;
     }
 
-    public function getInternalDateTimeFormat()
+    public function getInternalDateTimeFormat() : string
     {
         return $this->internalDateTimeFormat;
     }
 
-    public function getInternalDateFormat()
+    public function getInternalDateFormat() : string
     {
         return $this->internalDateFormat;
     }
 
-    protected function getPhpDateFormat()
+    protected function getPhpDateFormat() : string
     {
         return $this->dateFormats[$this->dateFormat];
     }
 
-    protected function getPhpDateTimeFormat()
+    protected function getPhpDateTimeFormat() : string
     {
         return $this->dateFormats[$this->dateFormat] . ' ' . $this->timeFormats[$this->timeFormat];
     }
 
-    public function convertSystemDateToGlobal($string)
+    public function convertSystemDateToGlobal($string) : ?string
     {
         return $this->convertSystemDate($string);
     }
 
-    public function convertSystemDateTimeToGlobal($string)
+    public function convertSystemDateTimeToGlobal(string $string) : ?string
     {
         return $this->convertSystemDateTime($string);
     }
 
-    public function convertSystemDate(string $string, ?string $format = null, ?string $language = null)
+    public function convertSystemDate(string $string, ?string $format = null, ?string $language = null) : ?string
     {
         $dateTime = \DateTime::createFromFormat('Y-m-d', $string);
         if ($dateTime) {
@@ -128,8 +131,9 @@ class DateTime
         return null;
     }
 
-    public function convertSystemDateTime(string $string, ?string $timezone = null, ?string $format = null, ?string $language = null)
-    {
+    public function convertSystemDateTime(
+        string $string, ?string $timezone = null, ?string $format = null, ?string $language = null
+    ) : ?string {
         if (is_string($string) && strlen($string) === 16) {
             $string .= ':00';
         }
@@ -150,22 +154,22 @@ class DateTime
         return null;
     }
 
-    public function setTimezone($timezone)
+    public function setTimezone(string $timezone)
     {
         $this->timezone = new \DateTimeZone($timezone);
     }
 
-    public function getInternalNowString()
+    public function getInternalNowString() : string
     {
         return date($this->getInternalDateTimeFormat());
     }
 
-    public function getInternalTodayString()
+    public function getInternalTodayString() : string
     {
         return date($this->getInternalDateFormat());
     }
 
-    public function getTodayString(?string $timezone = null, ?string $format = null)
+    public function getTodayString(?string $timezone = null, ?string $format = null) : string
     {
         if ($timezone) {
             $tz = new \DateTimeZone($timezone);
@@ -184,7 +188,7 @@ class DateTime
         return $carbon->isoFormat($format);
     }
 
-    public function getNowString(?string $timezone = null, ?string $format = null)
+    public function getNowString(?string $timezone = null, ?string $format = null) : string
     {
         if ($timezone) {
             $tz = new \DateTimeZone($timezone);
@@ -203,18 +207,18 @@ class DateTime
         return $carbon->isoFormat($format);
     }
 
-    public static function isAfterThreshold($value, $period)
+    public static function isAfterThreshold($value, string $period) : bool
     {
         if (is_string($value)) {
             try {
                 $dt = new \DateTime($value);
             } catch (\Exception $e) {
-                return;
+                return false;
             }
         } else if ($value instanceof \DateTime) {
             $dt = clone $value;
         } else {
-            return;
+            return false;
         }
         $dt->modify($period);
 
@@ -227,7 +231,7 @@ class DateTime
         return false;
     }
 
-    public static function getSystemNowString()
+    public static function getSystemNowString() : string
     {
         return date(self::$systemDateTimeFormat);
     }
diff --git a/application/Espo/Core/Utils/EmailFilterManager.php b/application/Espo/Core/Utils/EmailFilterManager.php
index 80f26a8c10..91e1470074 100644
--- a/application/Espo/Core/Utils/EmailFilterManager.php
+++ b/application/Espo/Core/Utils/EmailFilterManager.php
@@ -31,7 +31,13 @@ namespace Espo\Core\Utils;
 
 use Espo\Core\ORM\EntityManager;
 use Espo\Entities\Email;
+use Espo\Entities\EmailFilter;
 
+use Espo\Core\Mail\FiltersMatcher;
+
+/**
+ * Looks for any matching Email Filter for a given email and user.
+ */
 class EmailFilterManager
 {
     private $entityManager;
@@ -53,12 +59,12 @@ class EmailFilterManager
     protected function getFiltersMatcher()
     {
         if (!$this->filtersMatcher) {
-            $this->filtersMatcher = new \Espo\Core\Mail\FiltersMatcher();
+            $this->filtersMatcher = new FiltersMatcher();
         }
         return $this->filtersMatcher;
     }
 
-    public function getMatchingFilter(Email $email, $userId)
+    public function getMatchingFilter(Email $email, string $userId) : ?EmailFilter
     {
         if (!array_key_exists($userId, $this->data)) {
             $emailFilterList = $this->getEntityManager()->getRepository('EmailFilter')->where([
@@ -72,5 +78,6 @@ class EmailFilterManager
                 return $emailFilter;
             }
         }
+        return null;
     }
 }
diff --git a/application/Espo/Core/Utils/EntityManager.php b/application/Espo/Core/Utils/EntityManager.php
index 0f1060f096..200ed33620 100644
--- a/application/Espo/Core/Utils/EntityManager.php
+++ b/application/Espo/Core/Utils/EntityManager.php
@@ -39,6 +39,9 @@ use Espo\Core\Container;
 
 use Espo\Core\Utils\Metadata\Helper as MetadataHelper;
 
+/**
+ * Administration > Entity Manager.
+ */
 class EntityManager
 {
     private $metadata;
diff --git a/application/Espo/Core/Utils/FieldManager.php b/application/Espo/Core/Utils/FieldManager.php
index b082000e84..94f60cc6f6 100644
--- a/application/Espo/Core/Utils/FieldManager.php
+++ b/application/Espo/Core/Utils/FieldManager.php
@@ -33,6 +33,9 @@ use Espo\Core\Exceptions\Error;
 use Espo\Core\Exceptions\Conflict;
 use Espo\Core\Container;
 
+/**
+ * Administration > Entity Manager > fields.
+ */
 class FieldManager
 {
     private $metadata;
diff --git a/application/Espo/Core/Utils/FieldManagerUtil.php b/application/Espo/Core/Utils/FieldManagerUtil.php
index ddda94ed0a..59fcb1b260 100644
--- a/application/Espo/Core/Utils/FieldManagerUtil.php
+++ b/application/Espo/Core/Utils/FieldManagerUtil.php
@@ -29,6 +29,9 @@
 
 namespace Espo\Core\Utils;
 
+/**
+ * Available as 'fieldManagerUtil' service.
+ */
 class FieldManagerUtil
 {
     private $metadata;