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();

定义

让我们看一个示例，展示容器中的每个部分。

我们有3个级别的空格。

容器。通常它是唯一的，由我们的MessageContainer实例定义。
容器可以包含从0到多个保险箱。每个保险箱都有一个唯一的“id”。
保险箱。每次添加项时，我们都可以创建或更新一个新容器。
每个保险箱可以包含从0到多个错误、警告、信息或成功的消息，每个消息可以包含从0到多个消息。
我们的消息或条目分为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（可选）是一个关联数组，用于显示带变量的消息。每个锁仅设置一次上下文。

// 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()

别名 $this->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 如果为 true，则包括警告，但任何错误都有优先级（布尔值）

方法 firstWarningText()

它返回警告的第一条消息，如果没有则返回空

参数

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

方法 firstInfoText()

它返回信息的第一条消息，如果没有则返回空

参数

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

方法 firstSuccessText()

它返回成功的第一条消息，如果没有则返回空

参数

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

方法 lastErrorOrWarning()

它返回错误的第一条消息，如果没有则返回空
如果没有，则返回警告的第一条消息，如果没有则返回空

参数

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

方法 lastErrorText()

它返回错误的第一条消息，如果没有则返回空

参数

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

方法 lastWarningText()

它返回警告的第一条消息，如果没有则返回空

参数

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

方法 lastInfoText()

它返回信息的第一条消息，如果没有则返回空

参数

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

方法 lastSuccessText()

它返回成功的第一条消息，如果没有则返回空

参数

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

方法 allArray()

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

参数

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

方法 allErrorArray()

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

参数

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

方法 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 如果为 true，则还返回是否有警告（布尔值）

MessageLocker

类 MessageLocker

方法 __construct()

MessageLocker 构造函数。

参数

$idLocker 参数 null|string $idLocker（null|string）
$context 参数 array|null $context（数组|null）

方法 setContext()

仅在当前上下文为null时设置上下文。

参数

$context 新上下文。（数组|null）

方法 addError()

向锁器中添加错误。

参数

$msg 要存储的消息（混合类型）

方法 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 要存储的消息（混合类型）

方法 addInfo()

向锁器中添加信息。

参数

$msg 要存储的消息（混合类型）

方法 addSuccess()

向锁器中添加成功。

参数

$msg 要存储的消息（混合类型）

方法 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表示显示所有错误（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 如果为 true，则还返回是否有警告（布尔值）

方法 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
- 现在可以记录每个错误、警告、信息或成功的消息。
- [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] 现在可以在容器和锁器中读取最后一条消息（错误、警告、信息、全部）
- [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 添加了新方法。
- 可选地，消息可以使用从上下文中获取的变量。上下文是针对每个锁器的。例如 "这是一个 {{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()

参数