tobento/service-message

PHP应用程序的消息。

维护者

详细信息

github.com/tobento-ch/service-message

主页

源代码

问题

安装: 98

依赖项: 6

建议者: 0

安全: 0

星星: 0

关注者: 1

分支: 0

开放问题: 0

1.0.3 2024-08-13 13:42 UTC

Requires

Requires (Dev)

Suggests

MIT 5fd9363a7520bdd8f24608b87735255695b7bf4d

packagemessagemessagestobento

This package is auto-updated.

Last update: 2024-09-13 13:47:32 UTC

README

PHP应用程序的消息。

目录

入门

使用以下命令添加运行消息服务项目的最新版本。

composer require tobento/service-message

需求

  • PHP 8.0或更高版本

亮点

  • 框架无关，适用于任何项目
  • 解耦设计

文档

消息

创建消息

use Tobento\Service\Message\Message;
use Tobento\Service\Message\MessageInterface;

$message = new Message(
    level: 'success',
    message: 'Hello :name, welcome back',
    context: ['logged_in' => 'John'],
    key: 'user.name', // null|string
    parameters: [':name' => 'John'],
    logged: false,
);

var_dump($message instanceof MessageInterface);
// bool(true)

参数说明

消息工厂

createMessage

use Tobento\Service\Message\MessageFactory;
use Tobento\Service\Message\MessageFactoryInterface;
use Tobento\Service\Message\MessageInterface;

$messageFactory = new MessageFactory();

var_dump($messageFactory instanceof MessageFactoryInterface);
// bool(true)

$message = $messageFactory->createMessage(
    level: 'error',
    message: 'Any error message',
    context: [],
    key: null,
    parameters: [],
    logged: false,
);

var_dump($message instanceof MessageInterface);
// bool(true)

createMessageFromArray

use Tobento\Service\Message\MessageFactory;
use Tobento\Service\Message\MessageFactoryInterface;
use Tobento\Service\Message\MessageInterface;

$messageFactory = new MessageFactory();

var_dump($messageFactory instanceof MessageFactoryInterface);
// bool(true)

$message = $messageFactory->createMessageFromArray([
    'level' => 'error',
    'message' => 'Any error message',
    'context' => [],
    'key' => null,
    'parameters' => [],
    'logged' => false,
]);

var_dump($message instanceof MessageInterface);
// bool(true)

消息接口

消息接口有以下方法

use Tobento\Service\Message\Message;
use Tobento\Service\Message\MessageInterface;

$message = new Message('error', 'Any error message');

var_dump($message instanceof MessageInterface);
// bool(true)

var_dump($message->level());
// string(5) "error"

var_dump($message->message());
// string(17) "Any error message"

var_dump($message->context());
// array(0) { }

var_dump($message->key());
// NULL or string if a key is set.

var_dump($message->parameters());
// array(0) { }

var_dump($message->parameter('name', 'default'));
// string(7) "default"

var_dump($message->logged());
// bool(false)

通过方法

您可以使用带前缀的方法返回一个新实例。

use Tobento\Service\Message\Message;
use Tobento\Service\Message\MessageInterface;

$message = new Message('error', 'Any error message');

var_dump($message instanceof MessageInterface);
// bool(true)

$newMessage = $message->withLevel('success');

var_dump($newMessage === $message);
// bool(false)

$newMessage = $message->withMessage('Hello :name, welcome back');

$newMessage = $message->withContext(['logged_in' => 'John']);

$newMessage = $message->withKey('user.name');

$newMessage = $message->withParameters([':name' => 'John']);

$newMessage = $message->withLogged(false);

渲染消息

use Tobento\Service\Message\Message;

$message = new Message('error', 'Any error message');

<?= $message ?>
// is escaped

<?= $message->message() ?>
// is NOT escaped

消息

创建消息

use Tobento\Service\Message\Messages;
use Tobento\Service\Message\MessagesInterface;
use Tobento\Service\Message\MessageFactoryInterface;
use Tobento\Service\Message\ModifiersInterface;
use Psr\Log\LoggerInterface;

$messages = new Messages(
    messageFactory: null, // null|MessageFactoryInterface
    modifiers: null, // null|ModifiersInterface
    logger: null, // null|LoggerInterface
);

var_dump($messages instanceof MessagesInterface);
// bool(true)

参数说明

withMessageFactory

use Tobento\Service\Message\Messages;
use Tobento\Service\Message\MessageFactory;
use Tobento\Service\Message\MessageFactoryInterface;

$messages = new Messages();

$newMessages = $messages->withMessageFactory(
    messageFactory: new MessageFactory()
);

var_dump($newMessages->messageFactory() instanceof MessageFactoryInterface);
// bool(true)

withModifiers

use Tobento\Service\Message\Messages;
use Tobento\Service\Message\Modifiers;
use Tobento\Service\Message\ModifiersInterface;

$messages = new Messages();

$newMessages = $messages->withModifiers(
    modifiers: new Modifiers()
);

var_dump($newMessages->modifiers() instanceof ModifiersInterface);
// bool(true)

withLogger

use Tobento\Service\Message\Messages;
use Psr\Log\LoggerInterface;

$messages = new Messages();

$newMessages = $messages->withLogger(
    logger: null // null|LoggerInterface
);

var_dump($newMessages->logger() instanceof LoggerInterface);
// bool(false) as null

消息工厂

您可能想使用消息工厂来创建消息。

use Tobento\Service\Message\MessagesFactory;
use Tobento\Service\Message\MessagesFactoryInterface;
use Tobento\Service\Message\MessageFactoryInterface;
use Tobento\Service\Message\MessagesInterface;
use Tobento\Service\Message\ModifiersInterface;
use Psr\Log\LoggerInterface;

$messagesFactory = new MessagesFactory(
    messageFactory: null, // null|MessageFactoryInterface
    modifiers: null, // null|ModifiersInterface
    logger: null, // null|LoggerInterface
);

var_dump($messagesFactory instanceof MessagesFactoryInterface);
// bool(true)

$messages = $messagesFactory->createMessages();

var_dump($messages instanceof MessagesInterface);
// bool(true)

添加消息

通过使用 addMessage 方法

use Tobento\Service\Message\Messages;
use Tobento\Service\Message\Message;

$messages = new Messages();

$messages->addMessage(
    message: new Message('error', 'Error message'),
    log: false,
);

通过使用 add 方法

use Tobento\Service\Message\Messages;

$messages = new Messages();

$messages->add(
    level: 'error',
    message: 'Error message',
    context: [],
    key: null, // null|string
    parameters: [],
    log: false,
);

通过使用 push 方法

use Tobento\Service\Message\Messages;
use Tobento\Service\Message\MessagesInterface;

$someMessages = new Messages();
$someMessages->add('error', 'Error message');

$messages = new Messages();
$messages->add('success', 'Success message');

$messages->push(
    messages: $someMessages // array|MessagesInterface
);

$messages->push(
    messages: [
        ['level' => 'info', 'message' => 'Some info'],
    ]
);

通过使用 withMessage 方法返回一个新实例

use Tobento\Service\Message\Messages;
use Tobento\Service\Message\MessageInterface;

$someMessages = new Messages();
$someMessages->add('error', 'Error message');

$messages = new Messages();
$messages->add('success', 'Success message');

$newMessages = $messages->withMessage(
    ...$someMessages // MessageInterface
);

过滤消息

过滤方法总是返回一个新实例。

filter

use Tobento\Service\Message\Messages;
use Tobento\Service\Message\MessageInterface;

$messages = new Messages();
$messages->add('success', 'Success message');
$messages->add('error', 'Error message');

$messages = $messages->filter(
    fn(MessageInterface $m): bool => $m->level() === 'error'
);

key

按其键过滤消息

use Tobento\Service\Message\Messages;

$messages = new Messages();
$messages->add(level: 'success', message: 'Success message', key: 'foo');
$messages->add('error', 'Error message');

$messages = $messages->key('foo');

only

仅按指定的级别过滤消息

use Tobento\Service\Message\Messages;

$messages = new Messages();
$messages->add('success', 'Success message');
$messages->add('error', 'Error message');
$messages->add('info', 'Info message');

$messages = $messages->only(levels: ['info', 'success']);

except

除指定的级别之外过滤消息

use Tobento\Service\Message\Messages;

$messages = new Messages();
$messages->add('success', 'Success message');
$messages->add('error', 'Error message');
$messages->add('info', 'Info message');

$messages = $messages->except(levels: ['info', 'success']);

获取消息

all

use Tobento\Service\Message\Messages;
use Tobento\Service\Message\MessageInterface;

$messages = new Messages();
$messages->add('success', 'Success message');
$messages->add('error', 'Error message');

foreach($messages->all() as $message) {
    var_dump($message instanceof MessageInterface);
    //bool(true)
}

// or just
foreach($messages as $message) {
    var_dump($message instanceof MessageInterface);
    //bool(true)
}

first

获取第一条消息

use Tobento\Service\Message\Messages;
use Tobento\Service\Message\MessageInterface;

$messages = new Messages();
$messages->add('success', 'Success message');
$messages->add('error', 'Error message');

var_dump($messages->first() instanceof MessageInterface);
// bool(true)

last

获取最后一条消息

use Tobento\Service\Message\Messages;
use Tobento\Service\Message\MessageInterface;

$messages = new Messages();
$messages->add('success', 'Success message');
$messages->add('error', 'Error message');

var_dump($messages->last() instanceof MessageInterface);
// bool(true)

column

use Tobento\Service\Message\Messages;

$messages = new Messages();
$messages->add('success', 'Success message');
$messages->add('error', 'Error message');

$values = $messages->column(
    column: 'message',
    index: 'key',
);

var_dump($values);
// array(2) { [0]=> string(15) "Success message" [1]=> string(13) "Error message" }

has

use Tobento\Service\Message\Messages;

$messages = new Messages();
$messages->add('success', 'Success message');
$messages->add('error', 'Error message');

var_dump($messages->has());
// bool(true)

var_dump($messages->has(levels: ['error', 'success']));
// bool(true)

var_dump($messages->has(levels: ['error', 'info']));
// bool(false)

消息感知

您可能通过使用 HasMessages 特性来支持任何类中的消息。

use Tobento\Service\Message\HasMessages;
use Tobento\Service\Message\MessagesAware;
use Tobento\Service\Message\MessagesInterface;

class Foo implements MessagesAware
{
    use HasMessages;
}

$foo = new Foo();

var_dump($foo->messages() instanceof MessagesInterface);
// bool(true)

修改器

修改器可用于修改消息，例如翻译。

创建修改器

use Tobento\Service\Message\Modifiers;
use Tobento\Service\Message\ModifiersInterface;
use Tobento\Service\Message\Modifier;

$modifiers = new Modifiers(
    new Modifier\ParameterReplacer(),
);

var_dump($modifiers instanceof ModifiersInterface);
// bool(true)

添加修改器

use Tobento\Service\Message\Modifiers;
use Tobento\Service\Message\Modifier;

$modifiers = new Modifiers();

$modifiers->add(new Modifier\ParameterReplacer());

前置修改器

将修改器添加到开头。

use Tobento\Service\Message\Modifiers;
use Tobento\Service\Message\Modifier;

$modifiers = new Modifiers();

$modifiers->add(new Modifier\ParameterReplacer());

$modifiers->prepend(new Modifier\Pluralization());

修改消息

use Tobento\Service\Message\Modifiers;
use Tobento\Service\Message\Modifier;
use Tobento\Service\Message\Message;

$modifiers = new Modifiers(
    new Modifier\ParameterReplacer(),
);

$message = new Message(
    level: 'success',
    message: 'Hello :name, welcome back',
    parameters: [':name' => 'John'],
);

$newMessage = $modifiers->modify($message);

var_dump($newMessage->message());
// string(24) "Hello John, welcome back"

var_dump($newMessage === $message);
// bool(false)

获取修改器

use Tobento\Service\Message\Modifiers;
use Tobento\Service\Message\ModifierInterface;
use Tobento\Service\Message\Modifier;

$modifiers = new Modifiers(
    new Modifier\ParameterReplacer(),
);

foreach($modifiers->all() as $modifier) {
    var_dump($modifier instanceof ModifierInterface);
    // bool(true)
}

修改器

复数化

use Tobento\Service\Message\Modifier\Pluralization;
use Tobento\Service\Message\ModifierInterface;
use Tobento\Service\Message\Message;

$modifier = new Pluralization(key: 'count');

var_dump($modifier instanceof ModifierInterface);
// bool(true)

$message = new Message(
    level: 'success',
    message: 'One item created|Many items created',
    parameters: ['count' => 5],
);

$newMessage = $modifier->modify($message);

var_dump($newMessage->message());
// string(18) "Many items created"

var_dump($newMessage === $message);
// bool(false)

参数替换器

use Tobento\Service\Message\Modifier\ParameterReplacer;
use Tobento\Service\Message\ModifierInterface;
use Tobento\Service\Message\Message;

$modifier = new ParameterReplacer();

var_dump($modifier instanceof ModifierInterface);
// bool(true)

$message = new Message(
    level: 'success',
    message: 'Hello :name, welcome back',
    parameters: [':name' => 'John'],
);

$newMessage = $modifier->modify($message);

var_dump($newMessage->message());
// string(24) "Hello John, welcome back"

var_dump($newMessage === $message);
// bool(false)

限制长度

use Tobento\Service\Message\Modifier\LimitLength;
use Tobento\Service\Message\ModifierInterface;
use Tobento\Service\Message\Message;

$modifier = new LimitLength(
    length: 15,
    parameterKey: 'limit_length',
);

var_dump($modifier instanceof ModifierInterface);
// bool(true)

$message = new Message(
    level: 'success',
    message: 'Some very long message',
    parameters: [
        // used instead of default if set.
        'limit_length' => 10,
    ],
);

$newMessage = $modifier->modify($message);

var_dump($newMessage->message());
// string(10) "Some ve..."

var_dump($newMessage === $message);
// bool(false)

翻译器

有关翻译器的更多信息，请参阅翻译服务文档。

use Tobento\Service\Translation;
use Tobento\Service\Message\Modifier\Translator;
use Tobento\Service\Message\ModifierInterface;
use Tobento\Service\Message\Message;

$translator = new Translation\Translator(
    new Translation\Resources(
        new Translation\Resource('*', 'en', [
            'Some error occured' => 'Some error occured',
        ]),
        new Translation\Resource('*', 'de', [
            'Some error occured' => 'Ein Fehler is passiert',
        ]),
    ),
    new Translation\Modifiers(
        new Translation\Modifier\Pluralization(),        
        new Translation\Modifier\ParameterReplacer(),
    ),
    new Translation\MissingTranslationHandler(),
    'de',
);

$modifier = new Translator(
    translator: $translator,
    src: '*',
);

var_dump($modifier instanceof ModifierInterface);
// bool(true)

$message = new Message(
    level: 'error',
    message: 'Some error occured',
);

$newMessage = $modifier->modify($message);

var_dump($newMessage->message());
// string(22) "Ein Fehler is passiert"

var_dump($newMessage === $message);
// bool(false)

参数翻译器

有时您可能需要翻译消息参数

use Tobento\Service\Translation;
use Tobento\Service\Message\Modifier\ParameterTranslator;
use Tobento\Service\Message\ModifierInterface;
use Tobento\Service\Message\Message;

$translator = new Translation\Translator(
    new Translation\Resources(
        new Translation\Resource('*', 'en', [
            'title' => 'title',
        ]),
        new Translation\Resource('*', 'de', [
            'title' => 'Titel',
        ]),
    ),
    new Translation\Modifiers(
        new Translation\Modifier\Pluralization(),        
        new Translation\Modifier\ParameterReplacer(),
    ),
    new Translation\MissingTranslationHandler(),
    'de',
);

$modifier = new ParameterTranslator(
    parameters: [':attribute'],
    translator: $translator,
    src: '*',
);

var_dump($modifier instanceof ModifierInterface);
// bool(true)

$message = new Message(
    level: 'error',
    message: 'The :attribute is invalid.',
    parameters: [
        ':attribute' => 'title',
    ],
);

$newMessage = $modifier->modify($message);

var_dump($newMessage->parameters()[':attribute']);
// string(5) "Titel"

var_dump($newMessage->message());
// string(26) "The :attribute is invalid."

var_dump($newMessage === $message);
// bool(false)

鸣谢