From 334b8d8783a1262c3b8311d6599889d82e9cc58c Mon Sep 17 00:00:00 2001 From: Jordi Boggiano Date: Wed, 18 Jul 2018 09:55:49 +0200 Subject: [PATCH] More type hints on some handler classes --- CHANGELOG.md | 2 +- src/Monolog/Formatter/HtmlFormatter.php | 6 +-- src/Monolog/Handler/AbstractSyslogHandler.php | 6 +-- src/Monolog/Handler/AmqpHandler.php | 17 ++----- .../ActivationStrategyInterface.php | 5 +- .../ChannelLevelActivationStrategy.php | 6 +-- .../ErrorLevelActivationStrategy.php | 5 +- .../Handler/FormattableHandlerTrait.php | 2 + src/Monolog/Handler/InsightOpsHandler.php | 2 +- .../Handler/ProcessableHandlerTrait.php | 5 +- src/Monolog/Handler/Slack/SlackRecord.php | 47 +++++-------------- src/Monolog/Handler/SyslogUdp/UdpSocket.php | 9 ++-- src/Monolog/Logger.php | 2 +- 13 files changed, 43 insertions(+), 71 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8c033f93..1d6770e9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ * Added ability to customize error handling at the Logger level using Logger::setExceptionHandler * Added InsightOpsHandler to migrate users of the LogEntriesHandler - * Added protection to NormalizerHandler against circular and very deep structures, it now stops normalizing at a depth of 9 + * Added protection to NormalizerFormatter against circular and very deep structures, it now stops normalizing at a depth of 9 * Added capture of stack traces to ErrorHandler when logging PHP errors * Added forwarding of context info to FluentdFormatter * Added SocketHandler::setChunkSize to override the default chunk size in case you must send large log lines to rsyslog for example diff --git a/src/Monolog/Formatter/HtmlFormatter.php b/src/Monolog/Formatter/HtmlFormatter.php index e116177d..0f8db9a7 100644 --- a/src/Monolog/Formatter/HtmlFormatter.php +++ b/src/Monolog/Formatter/HtmlFormatter.php @@ -47,9 +47,9 @@ class HtmlFormatter extends NormalizerFormatter /** * Creates an HTML table row * - * @param string $th Row header content - * @param string $td Row standard cell content - * @param bool $escapeTd false if td content must not be html escaped + * @param string $th Row header content + * @param string $td Row standard cell content + * @param bool $escapeTd false if td content must not be html escaped */ protected function addRow(string $th, string $td = ' ', bool $escapeTd = true): string { diff --git a/src/Monolog/Handler/AbstractSyslogHandler.php b/src/Monolog/Handler/AbstractSyslogHandler.php index 3428000e..9a9b5238 100644 --- a/src/Monolog/Handler/AbstractSyslogHandler.php +++ b/src/Monolog/Handler/AbstractSyslogHandler.php @@ -54,9 +54,9 @@ abstract class AbstractSyslogHandler extends AbstractProcessingHandler ]; /** - * @param mixed $facility - * @param int $level The minimum logging level at which this handler will be triggered - * @param bool $bubble Whether the messages that are handled can bubble up the stack or not + * @param mixed $facility + * @param string|int $level The minimum logging level at which this handler will be triggered + * @param bool $bubble Whether the messages that are handled can bubble up the stack or not */ public function __construct($facility = LOG_USER, $level = Logger::DEBUG, bool $bubble = true) { diff --git a/src/Monolog/Handler/AmqpHandler.php b/src/Monolog/Handler/AmqpHandler.php index 064e50a9..ba45dd51 100644 --- a/src/Monolog/Handler/AmqpHandler.php +++ b/src/Monolog/Handler/AmqpHandler.php @@ -33,10 +33,10 @@ class AmqpHandler extends AbstractProcessingHandler /** * @param AMQPExchange|AMQPChannel $exchange AMQPExchange (php AMQP ext) or PHP AMQP lib channel, ready for use * @param string $exchangeName Optional exchange name, for AMQPChannel (PhpAmqpLib) only - * @param int $level + * @param string|int $level The minimum logging level at which this handler will be triggered * @param bool $bubble Whether the messages that are handled can bubble up the stack or not */ - public function __construct($exchange, $exchangeName = null, $level = Logger::DEBUG, bool $bubble = true) + public function __construct($exchange, ?string $exchangeName = null, $level = Logger::DEBUG, bool $bubble = true) { if ($exchange instanceof AMQPChannel) { $this->exchangeName = $exchangeName; @@ -108,25 +108,18 @@ class AmqpHandler extends AbstractProcessingHandler /** * Gets the routing key for the AMQP exchange - * - * @param array $record - * @return string */ - protected function getRoutingKey(array $record) + protected function getRoutingKey(array $record): string { $routingKey = sprintf('%s.%s', $record['level_name'], $record['channel']); return strtolower($routingKey); } - /** - * @param string $data - * @return AMQPMessage - */ - private function createAmqpMessage($data) + private function createAmqpMessage(string $data): AMQPMessage { return new AMQPMessage( - (string) $data, + $data, [ 'delivery_mode' => 2, 'content_type' => 'application/json', diff --git a/src/Monolog/Handler/FingersCrossed/ActivationStrategyInterface.php b/src/Monolog/Handler/FingersCrossed/ActivationStrategyInterface.php index b73854ad..1ba99c73 100644 --- a/src/Monolog/Handler/FingersCrossed/ActivationStrategyInterface.php +++ b/src/Monolog/Handler/FingersCrossed/ActivationStrategyInterface.php @@ -20,9 +20,6 @@ interface ActivationStrategyInterface { /** * Returns whether the given record activates the handler. - * - * @param array $record - * @return bool */ - public function isHandlerActivated(array $record); + public function isHandlerActivated(array $record): bool; } diff --git a/src/Monolog/Handler/FingersCrossed/ChannelLevelActivationStrategy.php b/src/Monolog/Handler/FingersCrossed/ChannelLevelActivationStrategy.php index 63a14cb6..f92a5563 100644 --- a/src/Monolog/Handler/FingersCrossed/ChannelLevelActivationStrategy.php +++ b/src/Monolog/Handler/FingersCrossed/ChannelLevelActivationStrategy.php @@ -39,8 +39,8 @@ class ChannelLevelActivationStrategy implements ActivationStrategyInterface private $channelToActionLevel; /** - * @param int $defaultActionLevel The default action level to be used if the record's category doesn't match any - * @param array $channelToActionLevel An array that maps channel names to action levels. + * @param int|string $defaultActionLevel The default action level to be used if the record's category doesn't match any + * @param array $channelToActionLevel An array that maps channel names to action levels. */ public function __construct($defaultActionLevel, $channelToActionLevel = []) { @@ -48,7 +48,7 @@ class ChannelLevelActivationStrategy implements ActivationStrategyInterface $this->channelToActionLevel = array_map('Monolog\Logger::toMonologLevel', $channelToActionLevel); } - public function isHandlerActivated(array $record) + public function isHandlerActivated(array $record): bool { if (isset($this->channelToActionLevel[$record['channel']])) { return $record['level'] >= $this->channelToActionLevel[$record['channel']]; diff --git a/src/Monolog/Handler/FingersCrossed/ErrorLevelActivationStrategy.php b/src/Monolog/Handler/FingersCrossed/ErrorLevelActivationStrategy.php index d0ebd840..447aa053 100644 --- a/src/Monolog/Handler/FingersCrossed/ErrorLevelActivationStrategy.php +++ b/src/Monolog/Handler/FingersCrossed/ErrorLevelActivationStrategy.php @@ -22,12 +22,15 @@ class ErrorLevelActivationStrategy implements ActivationStrategyInterface { private $actionLevel; + /** + * @param int|string $actionLevel Level or name or value + */ public function __construct($actionLevel) { $this->actionLevel = Logger::toMonologLevel($actionLevel); } - public function isHandlerActivated(array $record) + public function isHandlerActivated(array $record): bool { return $record['level'] >= $this->actionLevel; } diff --git a/src/Monolog/Handler/FormattableHandlerTrait.php b/src/Monolog/Handler/FormattableHandlerTrait.php index 9acace45..b1f1b588 100644 --- a/src/Monolog/Handler/FormattableHandlerTrait.php +++ b/src/Monolog/Handler/FormattableHandlerTrait.php @@ -52,6 +52,8 @@ trait FormattableHandlerTrait /** * Gets the default formatter. * + * Overwrite this if the LineFormatter is not a good default for your handler. + * * @return FormatterInterface */ protected function getDefaultFormatter(): FormatterInterface diff --git a/src/Monolog/Handler/InsightOpsHandler.php b/src/Monolog/Handler/InsightOpsHandler.php index dfe1a9dc..e211cc75 100644 --- a/src/Monolog/Handler/InsightOpsHandler.php +++ b/src/Monolog/Handler/InsightOpsHandler.php @@ -13,7 +13,7 @@ namespace Monolog\Handler; use Monolog\Logger; - /** +/** * Inspired on LogEntriesHandler. * * @author Robert Kaufmann III diff --git a/src/Monolog/Handler/ProcessableHandlerTrait.php b/src/Monolog/Handler/ProcessableHandlerTrait.php index a78b6415..58821100 100644 --- a/src/Monolog/Handler/ProcessableHandlerTrait.php +++ b/src/Monolog/Handler/ProcessableHandlerTrait.php @@ -48,11 +48,8 @@ trait ProcessableHandlerTrait /** * Processes a record. - * - * @param array $record - * @return array */ - protected function processRecord(array $record) + protected function processRecord(array $record): array { foreach ($this->processors as $processor) { $record = $processor($record); diff --git a/src/Monolog/Handler/Slack/SlackRecord.php b/src/Monolog/Handler/Slack/SlackRecord.php index 90286e88..0fbd4ab7 100755 --- a/src/Monolog/Handler/Slack/SlackRecord.php +++ b/src/Monolog/Handler/Slack/SlackRecord.php @@ -35,19 +35,19 @@ class SlackRecord /** * Slack channel (encoded ID or name) - * @var string|null + * @var ?string */ private $channel; /** * Name of a bot - * @var string|null + * @var ?string */ private $username; /** * User icon e.g. 'ghost', 'http://example.com/user.png' - * @var string + * @var ?string */ private $userIcon; @@ -85,7 +85,7 @@ class SlackRecord */ private $normalizerFormatter; - public function __construct($channel = null, $username = null, $useAttachment = true, $userIcon = null, $useShortAttachment = false, $includeContextAndExtra = false, array $excludeFields = array(), FormatterInterface $formatter = null) + public function __construct(?string $channel = null, ?string $username = null, bool $useAttachment = true, ?string $userIcon = null, bool $useShortAttachment = false, bool $includeContextAndExtra = false, array $excludeFields = array(), FormatterInterface $formatter = null) { $this->channel = $channel; $this->username = $username; @@ -101,7 +101,7 @@ class SlackRecord } } - public function getSlackData(array $record) + public function getSlackData(array $record): array { $dataArray = array(); $record = $this->excludeFields($record); @@ -177,11 +177,8 @@ class SlackRecord /** * Returned a Slack message attachment color associated with * provided level. - * - * @param int $level - * @return string */ - public function getAttachmentColor($level) + public function getAttachmentColor(int $level): string { switch (true) { case $level >= Logger::ERROR: @@ -197,12 +194,8 @@ class SlackRecord /** * Stringifies an array of key/value pairs to be used in attachment fields - * - * @param array $fields - * - * @return string */ - public function stringify($fields) + public function stringify(array $fields): string { $normalized = $this->normalizerFormatter->format($fields); $prettyPrintFlag = defined('JSON_PRETTY_PRINT') ? JSON_PRETTY_PRINT : 128; @@ -215,25 +208,19 @@ class SlackRecord : json_encode($normalized, JSON_UNESCAPED_UNICODE); } - /** - * Sets the formatter - * - * @param FormatterInterface $formatter - */ - public function setFormatter(FormatterInterface $formatter) + public function setFormatter(FormatterInterface $formatter): self { $this->formatter = $formatter; + + return $this; } /** * Generates attachment field * - * @param string $title * @param string|array $value - * - * @return array */ - private function generateAttachmentField($title, $value) + private function generateAttachmentField(string $title, $value): array { $value = is_array($value) ? sprintf('```%s```', $this->stringify($value)) @@ -248,12 +235,8 @@ class SlackRecord /** * Generates a collection of attachment fields from array - * - * @param array $data - * - * @return array */ - private function generateAttachmentFields(array $data) + private function generateAttachmentFields(array $data): array { $fields = array(); foreach ($this->normalizerFormatter->format($data) as $key => $value) { @@ -265,12 +248,8 @@ class SlackRecord /** * Get a copy of record with fields excluded according to $this->excludeFields - * - * @param array $record - * - * @return array */ - private function excludeFields(array $record) + private function excludeFields(array $record): array { foreach ($this->excludeFields as $field) { $keys = explode('.', $field); diff --git a/src/Monolog/Handler/SyslogUdp/UdpSocket.php b/src/Monolog/Handler/SyslogUdp/UdpSocket.php index 91888ac5..17e2aef0 100644 --- a/src/Monolog/Handler/SyslogUdp/UdpSocket.php +++ b/src/Monolog/Handler/SyslogUdp/UdpSocket.php @@ -15,13 +15,14 @@ class UdpSocket { const DATAGRAM_MAX_LENGTH = 65023; + /** @var string */ protected $ip; + /** @var int */ protected $port; - /** @var resource|null */ protected $socket; - public function __construct($ip, $port = 514) + public function __construct(string $ip, int $port = 514) { $this->ip = $ip; $this->port = $port; @@ -41,7 +42,7 @@ class UdpSocket } } - protected function send($chunk) + protected function send(string $chunk): void { if (!is_resource($this->socket)) { throw new \RuntimeException('The UdpSocket to '.$this->ip.':'.$this->port.' has been closed and can not be written to anymore'); @@ -49,7 +50,7 @@ class UdpSocket socket_sendto($this->socket, $chunk, strlen($chunk), $flags = 0, $this->ip, $this->port); } - protected function assembleMessage($line, $header) + protected function assembleMessage(string $line, string $header): string { $chunkSize = self::DATAGRAM_MAX_LENGTH - strlen($header); diff --git a/src/Monolog/Logger.php b/src/Monolog/Logger.php index 876fd051..c44959f6 100644 --- a/src/Monolog/Logger.php +++ b/src/Monolog/Logger.php @@ -360,7 +360,7 @@ class Logger implements LoggerInterface /** * Converts PSR-3 levels to Monolog ones if necessary * - * @param string|int $level Level number (monolog) or name (PSR-3) + * @param string|int $level Level number (monolog) or name (PSR-3) * @throws \Psr\Log\InvalidArgumentException If level is not defined */ public static function toMonologLevel($level): int