README

这是一个 PHP 的消息容器，功能上类似于 Laravel 的 MessageBag。然而，这个库注重速度和易用性，并且没有依赖。

这个类很简单：2 个类，没有依赖，没有其他东西。你可以在任何 PHP 项目中使用它。

目标是什么？

这个库将消息（字符串）存储在不同的存储器中，每个存储器可以包含不同级别（错误、警告、信息和成功）的消息。这个库的目标

它根据 "id" 存储消息，包括严重性和消息（简单的文本）。
如果我们要读取的值不存在，这个库不会生成错误，所以我们不需要在代码中使用 isset()。它还避免了在代码中使用 count() 和 is_array()，因为这个库已经为我们做了这些。
- 如果消息不存在或没有消息，则返回空值（非 null）。
- 如果消息列表不存在，则返回空数组（非 null）。
- 如果存储器不存在，则返回空存储器（非 null）。
可以同时返回第一个错误或警告。在这种情况下，如果存储器存储了错误和警告，则返回错误（它具有优先级）。
它可以返回
- 存储在某个存储器或容器中的所有消息。
- 第一个消息（带有或没有某些级别）
- 消息的数量（对于某些级别）
- 存储器或容器是否有错误或警告。
尽可能快

这是一个使用示例，例如表单的验证（这个库不验证或显示值，它只存储信息）

在这个例子中，我们有

一个容器（表单）
多个文本框（每个文本框都是一个 存储器）
并且每个文本框（我们的存储器）可以包含一个或多个不同级别（在这种情况下，成功或错误）的消息。

如果我们使用纯 PHP，我们可以显示密码的一些消息

echo $container['password']['error'];

但是，如果密码的 id 不包含任何消息，或者没有错误？或者有多个错误呢？

所以我们可以重新定义如下：（但如果有一个以上的错误，它仍然会失败）

纯 PHP

if (isset($container['password'])) {
    if(isset($container['password']['error'])) {
        echo $container['password']['error'];
    }
}

以及我们的库

// We could show the first error (or empty if none):
echo $container->getLocker('password')->firstError(); 

// it shows all errors (or nothing if none):
foreach($container->getLocker('password')->allError() as $msg) {
    echo $msg;
}

如何使用它

use eftec\MessageContainer;
$container=new MessageContainer(); // we create the full lockers
$container->addItem('locker1','It is a message','warning');  // we store a message inside "id1"
$container->addItem('locker1','It is a message','error');  // we store another message inside "id1"

// And later, you can process it

$lastErrorsOrWarnings=$container->get('locker1')->allErrorOrWarning();
// it will not crash even if the locker2 does not exists.
$lastErrorsOrWarnings2=$container->get('locker2')->allErrorOrWarning();

定义

让我们来看一个展示 Container 每个部分的例子。

我们有 3 个空格级别。

容器。通常它是唯一的，它由我们的 MessageContainer 实例定义。
容器可以包含从零到多个存储器。每个存储器都有一个唯一的 "id"。
存储器。每次我们添加一个项时，我们都可以创建或更新一个新的容器。
每个存储器可以包含从零到多个错误、警告、信息或成功的消息，并且每个消息可以包含从零到多个消息。
我们的消息或项目分为4个等级：错误、警告、信息和成功。
每个等级可以包含一个或多个消息（或没有）

消息的等级如下

示例 #2

表单和MessageContainer的示例

examples/formexample.php

示例 #3

$container=new MessageContainer();
$container->addItem('id1','some msg 1','error');
$container->addItem('id1','some msg 2','error');
$container->addItem('id1','some msg 1','warning');

$container->addItem('id2','some msg 1','info');
$container->addItem('id2','some msg 1','success');

$container->addItem('id33','some msg 1','error');
$container->addItem('id33','some msg 2','error');
$container->addItem('id33','some msg 1','success');
$container->addItem('id33','some msg 2','success');
$container->addItem('id33','some msg 2','success');

// obtaining information per locker
$msg=$container->getLocker('id1')->firstErrorOrWarning(); // returns if the locker id1 has an error or warning
$msg2=$container->getLocker('id2')->allInfo(); // returns all info store in locker id2 ["some msg1","some msg2"]
$msg3=$container->getLocker('id3')->allInfo(); // (note this locker is not defined so it returns an empty array.
$msg4=$container->getLocker('id33')->hasError(); // returns true if there is an error.
$msg5=$container->getLocker('id33')->countError(); // returns the number of errors (or zero if none).

// obtaining information globally (all lockers)
$msg7=$container->hasError(); // returns true if there is an error in any locker.
$msg8=$container->allErrorArray(true); // returns all errors and warnings presents in any locker.

添加新消息

要在保险柜中添加新消息，我们使用方法 addItem()

$container->addItem(<idlocker>,<message>,<level>,<context array>);

其中

idlocker 是要存储消息的保险柜的标识符。
message 是消息的字符串。
- 消息可以使用以下语法显示变量：{{variablename}}。例如："值 {{variable}} 无效"
- 可以使用以下语法显示保险柜的ID：{{_idlocker}}。例如："变量 {{_idlocker}} 为空"
level 是消息的等级。可以是错误、警告、信息和成功。默认值为 "error"
context（可选）是一个关联数组，用于显示包含变量的消息。每个 locker 只设置一次上下文。

// without context:
$container->addItem('locker1','The variable price must be higher than 200','warning');

// with context:
// The variable price must be higher than 200
$container->addItem('locker2'
                    ,'The variable {{var1}} must be higher than {{var2}}'
                    ,'warning'
                    ,['var1'=>'price','var2'=>200]);
// The variable price must be higher than 200 (not 500, the context is not updated this second time)
$container->addItem('locker2'
                    ,'The variable {{var1}} must be higher than {{var2}}'
                    ,'warning'
                    ,['var1'=>'price','var2'=>500]);
// The variable price must be higher than 200 (we use the previous context)
$container->addItem('locker2'
                    ,'The variable {{var1}} must be higher than {{var2}}'
                    ,'warning');

注意：我们可以向保险柜添加一个或多个消息。在后面的示例中，保险柜 locker2 存储了3条消息。

注意：调用方法 addItem() 时将评估消息。

获取消息

MessageContainer 存储消息保险柜的列表。它旨在方便，因此具有许多方法来以不同的方式访问信息。

消息按以下顺序排序

有时，错误和警告都被视为相等。因此，系统允许读取错误或警告。

错误始终具有优先级，然后是警告、信息成功。如果您想读取第一条消息，那么它将开始查找错误。

您可以将消息作为 MessageLocker 类型的对象数组、字符串数组或单个字符串（第一条消息）获取。

$container->get('idfield'); // container idfield
$container->get('idfield2'); // container idfield2

if($container->hasError()) {
    // Error: we do something here.
    echo "we found ".$container->errorCount()." errors in all lockers";   
}

// using messageList
if($container->hasError()) {
    // Error: we do something here.
    echo "we found ".$container->errorcount." errors in all lockers";
    
}

MessageContainer

所有保险柜的消息总数

示例

if ($container->errorcount>0) {
    // some error
}

获取所有保险柜的消息或文本

echo $container->firstErrorText(); // returns first error if any
$array=$container->allError();  // MessageLocker[]
echo $array[0]->firstError(); 
$array=$container->allErrorArray();  // string[]
echo $array[0];

特定容器的CSS

可以基于容器的当前等级或状态获取CSS类。

$cssClasses（字段）是用于与方法 cssClass() 一起使用的关联数组
cssClasses() 是返回基于容器等级类型的方法

$css=$this-messageList->cssClasses('container1');

杂项

echo $container->resetAll(); // resets all lockers
$container->addItem('containerid','it is a message','error'); // we add an error in the container with #id containerid
$array=$container->allIds(); // ['containerid']
var_dump($validation->get('containerid'));  // object MessageLocker

$array=$this-messageList->items;
var_dump($this-messageList->items['containerid']); // object MessageLocker

if($container->hasError()) { // $validation->hasError() does the same
    echo "there is an error";
}

MessageLocker

在 MessageContainer 中，我们可以有一个或多个保险柜（MessageLocker）。

获取特定容器的消息

$container->get('idfield'); // container idfield 

echo $container->firstErrorText(); // we show the first error (if any) in the container
var_dump($container->allError); // we show the all errors

类的定义

$idLocker 锁器标识（存储消息的位置）（字符串）
$message 要显示的消息。例如：'值不正确'（字符串）
$level =['error','warning','info','success'][$i]（字符串）
$context [可选] 它是一个关联数组，包含项目的值
为了优化，如果已存在另一个上下文，则不更新上下文。（数组）

方法 allIds()

它获取所有锁器的所有 ID。

方法 get()

getMessage() 的别名

参数

$idLocker 锁器 ID（字符串）

方法 getLocker()

它返回一个包含锁器的 MessageLocker 对象。
如果锁器不存在，则返回一个空对象（非 null）

参数

$idLocker 锁器 ID（字符串）

方法 cssClass()

它返回与锁器内错误类型关联的 CSS 类
如果锁器包含多条消息，则使用最严重的一条（错误、警告等）
该方法使用 $this->cssClasses 字段，因此您可以更改 CSS 类。

$this->clsssClasses=['error'=>'class-red','warning'=>'class-yellow','info'=>'class-green','success'=>'class-blue'];
$css=$this->cssClass('customerId');

参数

$idLocker 锁器 ID（字符串）

方法 firstErrorOrWarning()

它返回第一个错误消息或为空如果没有
如果没有，则返回第一个警告消息或为空如果没有

参数

$default 如果没有找到消息，则返回此值（字符串）

方法 firstErrorText()

它返回第一个错误消息或为空如果没有

参数

$default 如果没有找到消息，则返回此值（字符串）
$includeWarning 如果为真，则还包括警告，但任何错误都有优先级（布尔值）

方法 firstWarningText()

它返回第一个警告消息或为空如果没有

参数

$default 如果没有找到消息，则返回此值（字符串）

方法 firstInfoText()

它返回第一个信息消息或为空如果没有

参数

$default 如果没有找到消息，则返回此值（字符串）

方法 firstSuccessText()

它返回第一个成功消息或为空如果没有

参数

$default 如果没有找到消息，则返回此值（字符串）

方法 lastErrorOrWarning()

它返回最后一个错误消息或为空如果没有
如果没有，则返回最后一个警告消息或为空如果没有

参数

$default 如果没有找到消息，则返回此值（字符串）

方法 lastErrorText()

它返回最后一个错误消息或为空如果没有

参数

$default 如果没有找到消息，则返回此值（字符串）
$includeWarning 如果为真，则还包括警告，但任何错误都有优先级（布尔值）

方法 lastWarningText()

它返回最后一个警告消息或为空如果没有

参数

$default 如果没有找到消息，则返回此值（字符串）

方法 lastInfoText()

它返回最后一个信息消息或为空如果没有

参数

$default 如果没有找到消息，则返回此值（字符串）

方法 lastSuccessText()

它返回最后一个成功消息或为空如果没有

参数

$default 如果没有找到消息，则返回此值（字符串）

方法 allArray()

它返回包含所有锁器所有类型的所有消息的数组

参数

$level =[null,'error','warning','errorwarning','info','success'][$i] 要显示的级别。
空值表示显示所有错误（null|string）

方法 allErrorArray()

它返回包含所有锁器错误的所有消息的数组。

参数

$includeWarning 如果为真，则还包括警告（布尔值）

方法 allWarningArray()

它返回包含所有锁器警告的所有消息的数组。

方法 allErrorOrWarningArray()

它返回包含所有锁器错误和警告的所有消息的数组。

方法 allInfoArray()

它返回包含所有锁器信息消息的数组。

方法 allSuccessArray()

它返回包含所有锁器成功消息的数组。

方法 allAssocArray()

它返回一个关联数组，其形式为

[
['id'=>'', // id of the locker
'level'=>'' // level of message (error, warning, info or success)
'msg'=>'' // the message to show
]
]

参数

$level 参数 null|string $level（null|string）

方法 hasError()

如果有错误（或错误和警告），则返回 true。

参数

$includeWarning 如果为真，则还返回是否有警告（布尔值）

MessageLocker

类 MessageLocker

方法 __construct()

MessageLocker 构造函数。

参数

$idLocker 参数 null|string $idLocker（null|string）
$context 参数数组|null $context (数组|null)

方法 setContext()

只有当前上下文为null时，我们才设置上下文。

参数

$context 新的上下文。 (数组|null)

方法 addError()

它向锁器添加一个错误。

参数

$msg 要存储的消息 (mixed)

方法 replaceCurlyVariable()

将所有在{{ }}之间定义的变量替换为值字典中的变量。
示例
replaceCurlyVariable('hello={{var}}',['var'=>'world']) // hello=world
replaceCurlyVariable('hello={{var}}',['varx'=>'world']) // hello=
replaceCurlyVariable('hello={{var}}',['varx'=>'world'],true) // hello={{var}}

参数

$string 输入值。它可能包含定义为 {{namevar}} 的变量 (字符串)

方法 addWarning()

它向锁器添加一个警告。

参数

$msg 要存储的消息 (mixed)

方法 addInfo()

它向锁器添加一条信息。

参数

$msg 要存储的消息 (mixed)

方法 addSuccess()

它向锁器添加一条成功消息。

参数

$msg 要存储的消息 (mixed)

方法 countErrorOrWarning()

它返回锁器中包含的错误或警告的数量

方法 countError()

它返回锁器中错误的数量

方法 countWarning()

它返回锁器中警告的数量

方法 countInfo()

它返回锁器中信息的数量

方法 countSuccess()

它返回锁器中成功的数量

方法 first()

它返回任何类型的第一个消息。
如果错误，则返回错误的第一条消息
如果没有，如果警告，则返回警告的第一条消息
如果没有，那么显示第一条信息消息（如果有）
如果没有，那么显示第一条成功消息（如果有）
如果没有，那么显示默认消息。

参数

$defaultMsg 参数字符串 $defaultMsg (字符串)
$level =[null,'error','warning','errorwarning','info','success'][$i] 要显示的级别（默认情况下，它显示任何级别的第一条消息，从错误开始） (null|string)

方法 firstError()

如果有错误，则返回错误的第一条消息。否则，返回默认值

参数

$default 参数字符串 $default (字符串)

方法 firstWarning()

如果有警告，则返回警告的第一条消息。否则，返回默认值

参数

$default 参数字符串 $default (字符串)

方法 firstErrorOrWarning()

如果有错误或警告（按此顺序），则返回错误或警告的第一条消息。否则，返回默认值

参数

$default 参数字符串 $default (字符串)

方法 firstInfo()

如果有信息，则返回信息的第一条消息。否则，返回默认值

参数

$default 参数字符串 $default (字符串)

方法 firstSuccess()

如果有成功，则返回成功的第一条消息。否则，返回默认值

参数

$default 参数字符串 $default (字符串)

方法 last()

它返回任何类型的最后一条消息。
如果有错误，则返回错误的最后一条消息
如果没有，如果警告，则返回警告的最后一条消息
如果没有，那么显示最后一条信息消息（如果有）
如果没有，那么显示最后一条成功消息（如果有）
如果没有，那么显示默认消息。

参数

$defaultMsg 参数字符串 $defaultMsg (字符串)
$level =[null,'error','warning','errorwarning','info','success'][$i] 要显示的级别（默认情况下，它显示任何级别的最后一条消息，从错误开始） (null|string)

方法 lastError()

如果有错误，则返回错误的最后一条消息。否则，返回默认值

参数

$default 参数字符串 $default (字符串)

方法 lastWarning()

如果有警告，则返回警告的最后一条消息。否则，返回默认值

参数

$default 参数字符串 $default (字符串)

方法 lastErrorOrWarning()

如果有错误或警告（按此顺序），则返回错误或警告的最后一条消息。否则，返回默认值

参数

$default 参数字符串 $default (字符串)

方法 lastInfo()

如果有信息，则返回信息的第一条消息。否则，返回默认值

参数

$default 参数字符串 $default (字符串)

方法 lastSuccess()

如果有成功，则返回成功的第一条消息。否则，返回默认值

参数

$default 参数字符串 $default (字符串)

方法 all()

返回所有消息或空数组（如果没有）。

参数

$level =[null,'error','warning','errorwarning','info','success'][$i] 要显示的级别。空值表示显示所有错误（null|string）

方法 allError()

返回错误的所有消息（作为字符串数组），如果没有，则返回空数组。

方法 allWarning()

返回警告的所有消息，如果没有，则返回空数组。

方法 allErrorOrWarning()

返回错误或警告的所有消息（按此顺序），如果没有，则返回空数组

方法 allInfo()

返回信息的所有消息，如果没有，则返回空数组。

方法 allSuccess()

返回成功消息的所有消息，如果没有，则返回空数组。

方法 allAssocArray()

它返回一个关联数组，其形式为

[
['id'=>'', // id of the locker
'level'=>'' // level of message (error, warning, info or success)
'msg'=>'' // the message to show
]
]

参数

$level = [null, 'error', 'warning', 'errorwarning', 'info', 'success'][$i] 显示的级别。null表示显示所有消息，无论级别如何（从error开始）（null|string）

方法 hasError()

如果有错误（或错误和警告），则返回 true。

参数

$includeWarning 如果为真，则还返回是否有警告（布尔值）

方法 throwOnError()

如果存储错误，则也会抛出PHP异常。

参数

$throwOnError 如果为true（默认），则在存储错误时每次都抛出异常。
$includeWarning 如果为true，则还包括警告。

更改日志

2.9 2024-03-02 * 更新依赖到PHP 7.4。PHP 7.2的扩展支持已于3年前结束。
- 在代码中添加了更多类型提示。
2.8 2023-01-28
- [new] 函数 getLog(), setLogFilename(), backupLog(), restoreLog()
2.7 2023-01-28
- 现在，在错误、警告、info或成功时都可以记录每条消息。
- [new] 函数 setLog(), log(), getLogFilename() 和 count()
2.6 2023-01-26
- 修正了一些拼写错误。
2.5 2022-03-22
- [new] 向库中添加了类型提示
- [fix] 向 composer.json 添加了描述
2.4 2022-02-06
- [new] [container] 新方法 resetLocker() 和 hasLocker()
- [new] [locker] 新方法 resetAll()
2.3 2022-02-05
- 在文档中添加了正确版本。没有其他更改。
2.2 2022-02-05
- [new] 现在可以在容器和锁中读取最后一条消息（错误、警告、info、所有）
- [new] MessageLocker不再将第一条消息作为私有字段存储，现在每次都会计算。
- [new] 方法 logOnError() 在生成错误或警告时调用 error_log()
  - [new] 方法 ::instance() 允许获取容器的实例（单例），如果没有，则创建。
  - [new] 默认构造函数替换实例，但是您可以将其设置为不替换。如果您想有多个实例，这很有用。
2.1 2022-02-05
- [fix] 更新依赖。现在，它只与PHP 7.2及以上版本兼容。它还针对PHP 8.1进行了测试
- [fix] 更新PHPUnit依赖
- [new] 现在方法具有类型提示（返回值）
2.0.1 2022-01-29
- [fix] 一些清理
- [new] 添加了 throwOnError() 方法。因此，在存储错误和/或警告时可以抛出异常。
  - 只有当错误或警告通过容器抛出时才会抛出。
2.0 2022-01-15
- 弃用PHP 5.X。现在它需要PHP 7.1或更高版本
1.2 2021-03-21 添加了新方法。
- 可选地，消息可以使用从上下文中获得的变量。上下文是针对锁的。例如 "it is a {{variable}}"
1.1 2021-03-17 一些清理
1.0 2021-03-17 第一个版本

eftec / messagecontainer

维护者

详细信息

README

目标是什么？

如何使用它

定义

添加新消息

获取消息

MessageContainer

所有保险柜的消息总数

获取所有保险柜的消息或文本

特定容器的CSS

杂项

MessageLocker

获取特定容器的消息

类的定义

目录

MessageContainer

字段 items（MessageLocker[]）

字段 errorCount（int）

字段 warningCount（int）

字段 errorOrWarningCount（int）

字段 infoCount（int）

字段 successCount（int）

字段 cssClasses（string[]）

方法 __construct()

方法 resetAll()

方法 addItem()

参数

方法 allIds()

方法 get()

参数

方法 getLocker()

参数

方法 cssClass()

参数

方法 firstErrorOrWarning()

参数

方法 firstErrorText()

参数

方法 firstWarningText()

参数

方法 firstInfoText()

参数

方法 firstSuccessText()

参数

方法 lastErrorOrWarning()

参数

方法 lastErrorText()

参数

方法 lastWarningText()

参数

方法 lastInfoText()

参数

方法 lastSuccessText()

参数

方法 allArray()

参数

方法 allErrorArray()

参数

方法 allWarningArray()

方法 allErrorOrWarningArray()

方法 allInfoArray()

方法 allSuccessArray()

方法 allAssocArray()

参数

方法 hasError()

参数

MessageLocker

方法 __construct()

参数

方法 setContext()

参数

方法 addError()

参数

方法 replaceCurlyVariable()

参数

方法 addWarning()

参数