mediawiki-extensions-Echo/includes/formatters/NotificationFormatter.php
James D. Forrester 42e2764494 build: Enable phpcs rule 'PSR2.Methods.MethodDeclaration.AbstractAfterVisibility' and make pass
Change-Id: I316d30e5474646cfc7a8a03b540c09741cd7fdc6
2015-10-29 13:06:43 +01:00

192 lines
5.4 KiB
PHP

<?php
/**
* Abstract class for constructing a notification message, this class includes
* only the most generic formatting functionality as it may be extended by
* notification formatters for other extensions with unique content or
* requirements.
*/
abstract class EchoNotificationFormatter {
/**
* List of valid output format
* @var array
*/
protected $validOutputFormats = array( 'text', 'flyout', 'html', 'email', 'htmlemail' );
/**
* List of valid distribution type
*/
protected $validDistributionType = array( 'web', 'email', 'emaildigest', 'emailsubject' );
/**
* Current output format, default is 'text'
* @var string
*/
protected $outputFormat = 'text';
/**
* Distribution type, default is 'web'
* @var string
*/
protected $distributionType = 'web';
/**
* List of parameters for constructing messages
* @var array
*/
protected $parameters;
/**
* Creates an instance of the given class with the given parameters.
* @param $parameters array Associative array of parameters
* @throws MWException
*/
public function __construct( array $parameters ) {
$this->parameters = $parameters;
}
/**
* Shows a notification in human-readable format.
* @param $event EchoEvent being notified about.
* @param $user User being notified.
* @param $type string The notification type (e.g. notify, email)
* @return Mixed; depends on output format
* @see EchoNotificationFormatter::setOutputFormat
*/
abstract public function format( $event, $user, $type );
/**
* Set the output format that the notification will be displayed in.
* @param $format string A valid output format (by default, 'text', 'html', 'flyout', and 'email' are allowed)
* @throws InvalidArgumentException
*/
public function setOutputFormat( $format ) {
if ( !in_array( $format, $this->validOutputFormats, true ) ) {
throw new InvalidArgumentException( "Invalid output format $format" );
}
$this->outputFormat = $format;
}
public function setDistributionType( $type ) {
if ( !in_array( $type, $this->validDistributionType, true ) ) {
throw new InvalidArgumentException( "Invalid distribution type $type" );
}
$this->distributionType = $type;
}
/**
* Create an EchoNotificationFormatter for the given type.
* @param string $type
* Select the class of formatter to use with the 'formatter-class' field.
* For other parameters, see the appropriate class' constructor.
* @throws RuntimeException
* @return EchoNotificationFormatter object.
*/
public static function factory( $type ) {
global $wgEchoNotifications;
if ( !isset( $wgEchoNotifications[$type] ) ) {
throw new InvalidArgumentException( "The notification type '$type' is not registered" );
}
$parameters = $wgEchoNotifications[$type];
if ( isset( $parameters['formatter-class'] ) ) {
$class = $parameters['formatter-class'];
} else {
$class = 'EchoBasicFormatter';
}
if ( !class_exists( $class ) ) {
throw new RuntimeException( "Class $class does not exist" );
}
return new $class( $parameters );
}
/**
* Returns a link to a title, or the title itself.
* @param $title Title object
* @return string Text suitable for output format
*/
protected function formatTitle( Title $title ) {
return $title->getPrefixedText();
}
/**
* Formats a timestamp in a human-readable format
* @param $ts string Timestamp in some format compatible with wfTimestamp()
* @return string Human-readable timestamp
*/
protected function formatTimestamp( $ts ) {
$timestamp = new MWTimestamp( $ts );
$ts = $timestamp->getHumanTimestamp();
return $ts;
}
/**
* @todo this shouldn't be static
* @param string $icon Name of icon as registered in BeforeCreateEchoEvent hook
* @param string $dir either 'ltr' or 'rtl'
* @return string
*/
public static function getIconUrl( $icon, $dir ) {
global $wgEchoNotificationIcons, $wgExtensionAssetsPath;
if ( !isset( $wgEchoNotificationIcons[$icon] ) ) {
throw new InvalidArgumentException( "The $icon icon is not registered" );
}
$iconInfo = $wgEchoNotificationIcons[$icon];
$needsPrefixing = true;
// Now we need to check it has a valid url/path
if ( isset( $iconInfo['url'] ) && $iconInfo['url'] ) {
$iconUrl = $iconInfo['url'];
$needsPrefixing = false;
} elseif ( isset( $iconInfo['path'] ) && $iconInfo['path'] ) {
$iconUrl = $iconInfo['path'];
} else {
// Fallback to hardcoded 'placeholder'. This is used if someone
// doesn't configure the 'site' icon for example.
$icon = 'placeholder';
$iconUrl = $wgEchoNotificationIcons['placeholder']['path'];
}
// Might be an array with different icons for ltr/rtl
if ( is_array( $iconUrl ) ) {
if ( !isset( $iconUrl[$dir] ) ) {
throw new UnexpectedValueException( "Icon type $icon doesn't have an icon for $dir directionality" );
}
$iconUrl = $iconUrl[$dir];
}
// And if it was a 'path', stick the assets path in front
if ( $needsPrefixing ) {
$iconUrl = "$wgExtensionAssetsPath/$iconUrl";
}
return $iconUrl;
}
/**
* Returns a revision snippet
* @param EchoEvent $event The event that the notification is for.
* @param User $user The user to format the notification for.
* @return String The revision snippet (or empty string)
*/
public function getRevisionSnippet( $event, $user ) {
$extra = $event->getExtra();
if ( !isset( $extra['section-text'] ) || !$event->userCan( Revision::DELETED_TEXT, $user ) ) {
return '';
}
$snippet = trim( $extra['section-text'] );
return $snippet;
}
}