README

一个用于确定进度的PHP包。

目的

在您的Web应用程序中引导用户完成过程非常重要。您希望用户知道您期望他们做什么或他们需要完成的一串要求列表。

此进度包以简单的方式实现过程的多步骤，并使用它们创建一个进度系统。您可以通过表达性和简单的API定义您的步骤，然后让此包处理繁重的工作。结果是易于使用的步骤和进度系统。

简单概述

为了保持简单，此包仅引入了2个类：Progress 和 Step。Progress 类可以接受一个或多个 Step。每个 Step 类都包含它正在评估的数据和链式方法，这些方法以真值测试格式评估数据。

此包在底层利用了 beberlei/assert 库来处理所有 Step 类用于评估包含数据的真值语句。所有 beberlei/assert 的断言方法都可以在 Step 类上链式调用。您可以在下面的文档中找到方法列表。

安装

通过composer安装

composer require mtownsend/progress

此包旨在与任何 PHP 7.4+ 应用程序一起使用。

快速入门

使用类

以下是最基本的用法示例

use Mtownsend\Progress\Progress;
use Mtownsend\Progress\Step;

$progress = (new Progress(
    (new Step(31, 'Age'))
        ->notEmpty()
        ->integer()
        ->between(18, 65)
))->get();

// Output:
[
  "total_steps" => 1
  "percentage_complete" => 100.0
  "percentage_incomplete" => 0.0
  "steps_complete" => 1
  "steps_incomplete" => 0
  "complete_step_names" => [
    0 => "Age"
  ]
  "incomplete_step_names" => []
]

Progress 类可以接受单个 Step 类或多个。

use Mtownsend\Progress\Progress;
use Mtownsend\Progress\Step;

$step1 = (new Step('https://marktownsend.rocks', 'Portfolio Site'))->url();
$step2 = (new Step(4, 'Bronze Level Developer'))->integer()->between(1, 5);
$progress = (new Progress($step1, $step2));

$progress->get();

// or an array of Steps
$steps = [
    (new Step('https://marktownsend.rocks', 'Web Site'))->url(),
    (new Step('Laravel Developer', 'Profession'))->notEmpty()->contains('Laravel'),
    (new Step(true, 'Premier Member'))->boolean()->true()
];
$progress = new Progress($steps);

$progress->get();

此外，如果您喜欢全局助手，此包自动加载了两个全局助手函数：progress() 和 step()。它们实例化每个类并接受完全相同的参数。使用全局助手可以减少您的代码行数并消除在php脚本顶部使用 Progress 和 Step 类的需要 - 但并非所有开发人员都喜欢全局助手，因此它是完全可选的。

$step = step('https://marktownsend.rocks', 'Web Site')->url();
$progress = progress($step)->get();

// or an array of Steps
$steps = [
    step('https://marktownsend.rocks', 'Web Site')->url(),
    step('Laravel Developer', 'Profession')->contains('Laravel'),
    step(true, 'Premier Member')->boolean()->true()
];
$progress = progress($steps)->get();

Progress 类的参数和方法

Progress 类包含1个可选构造函数参数

new Progress(mixed Mtownsend\Progress\Step|array $steps);

$steps 参数可以是单个 \Mtownsend\Progress\Step 实例，多个实例作为自己的参数，或 Step 类的数组。

但是，您也可以不提供任何参数来实例化 Progress 类。

方法

add(mixed $steps) 与构造函数参数完全相同。您可以传递单个 Step、数组或多个实例。

get() 获取您步骤的整体进度。一旦调用，它就简单地返回评估后的数据。如果您想再次使用此类进行更多进度计算，您需要实例化一个新的 Progress 类。

toJson() 以有效的json返回 Progress 类的结果。

toObject() 将 Progress 类的结果作为标准PHP对象返回。

魔法属性

如果您想不直接访问结果数组来访问 Progress 类的结果，您可以使用与您想要检索的结果键名相对应的魔法属性。

例如，考虑以下内容

$steps = [
    (new Step(42, 'Answer To Everything'))->integer(),
    (new Step('https://github.com/mtownsend5512', 'Github Profile'))->notEmpty()->url(),
    (new Step(10, 'Open Source Packages'))->notEmpty()->integer(),
];
$progress = new Progress($steps);
$progress->get();

// Outputs:
[
  "total_steps" => 3
  "percentage_complete" => 100.0
  "percentage_incomplete" => 0.0
  "steps_complete" => 3
  "steps_incomplete" => 0
  "complete_step_names" => [
    0 => "Answer To Everything"
    1 => "Github Profile"
    2 => "Open Source Packages"
  ]
  "incomplete_step_names" => []
]

// To retrieve percentage_complete you can simply do:
$progress->percentage_complete; // 100.0

Step 类的参数和方法

参数

Step 类包含 2 个构造函数参数

new Step(mixed $data, string $name);

$data 参数可以是您希望评估的任何内容 - 来自数据库的数据、表单提交或其他。

$name 是完全可选的，但可以用来跟踪步骤或步骤的标签。如果您没有为您的 Step 分配名称，它将不会出现在 complete_step_names 或 incomplete_step_names 键中，但失败或成功仍将被计算。

步骤参数和方法

方法

由于 Step 类封装了 beberlei/assert 库，因此您可以直接在 Step 类上链式调用任何 Assertion 类方法。要查看完整列表，您可以查看库的 readme，但几乎所有您可能会使用的方法都已列在下文。

$step->alnum()
->base64()
->between(mixed $lowerLimit, mixed $upperLimit)
->betweenExclusive(mixed $lowerLimit, mixed $upperLimit)
->betweenLength(int $minLength, int $maxLength)
->boolean()
->choice(array $choices)
->choicesNotEmpty(array $choices)
->classExists()
->contains(string $needle)
->count(array|Countable|ResourceBundle|SimpleXMLElement $countable, int $count)
->date(string $value, string $format)
->defined(mixed $constant)
->digit()
->directory()
->e164()
->email()
->endsWith(string $needle)
->eq(mixed $value)
->eqArraySubset(mixed $value)
->extensionLoaded()
->extensionVersion(string $extension, string $operator, mixed $version)
->false()
->file()
->float()
->greaterOrEqualThan(mixed $limit)
->greaterThan(mixed $limit)
->implementsInterface(mixed $class, string $interfaceName)
->inArray(array $choices)
->integer()
->integerish()
->interfaceExists()
->ip(int $flag = null)
->ipv4(int $flag = null)
->ipv6(int $flag = null)
->isArray()
->isArrayAccessible()
->isCallable()
->isCountable()
->isInstanceOf(string $className)
->isJsonString()
->isObject()
->isResource()
->isTraversable()
->keyExists(string|int $key)
->keyIsset(string|int $key)
->keyNotExists(string|int $key)
->length(int $length)
->lessOrEqualThan(mixed $limit)
->lessThan(mixed $limit)
->max(mixed $maxValue)
->maxCount(array|Countable|ResourceBundle|SimpleXMLElement $countable, int $count)
->maxLength(int $maxLength)
->methodExists(mixed $object)
->min(mixed $minValue)
->minCount(array|Countable|ResourceBundle|SimpleXMLElement $countable, int $count)
->minLength(int $minLength)
->noContent()
->notBlank()
->notContains(string $needle)
->notEmpty()
->notEmptyKey(string|int $key)
->notEq(mixed $value)
->notInArray(array $choices)
->notIsInstanceOf(string $className)
->notNull()
->notRegex(string $pattern)
->notSame(mixed $value)
->null()
->numeric()
->objectOrClass()
->phpVersion(string $operator, mixed $version)
->propertiesExist(array $properties)
->propertyExists(string $property)
->range(mixed $minValue, mixed $maxValue)
->readable()
->regex(string $pattern)
->same(mixed $value)
->satisfy(callable $callback)
->scalar(mixed $value)
->startsWith(string $needle)
->string()
->subclassOf(string $className)
->true()
->uniqueValues()
->url()
->uuid()
->version(string $version1, string $operator, string $version2)
->writeable();

Progress 类负责检查 Step 是否通过或失败，但如果您想手动检查 Step 是否失败，您可以调用 $step->passed()，这将返回一个布尔值。

错误处理

如果您没有向 Progress 实例提供任何 Steps 并尝试运行 ->get() 方法，将抛出 \Mtownsend\Progress\Exceptions\NoStepsException 异常。

鸣谢

• Mark Townsend
• Benjamin Eberlei 为他的 assert 库
• 所有贡献者

测试

您可以使用以下命令运行测试

./vendor/bin/phpunit

许可证

MIT 许可证 (MIT)。有关更多信息，请参阅 许可证文件。