README

在TYPO3后台头部渲染进度条，用于长运行任务。

安装

仅通过Composer/Packagist可用

composer require namelesscoder/typo3-cms-progressor

功能

• 使用绝对最少的配置来启动监控过程。
• 通过单行方法调用实现您自己的任务的“火速而忘记”的进度监控集成。
• 对DataHandler任务的集成，为每个后台用户创建一个进度条。
• 通过预定义的QueryBuilder实例与数据库表集成，选择“挂起”记录。

可以通过扩展配置启用DataHandler集成。其他功能需要在您的长运行任务内部或ext_localconf.php文件中编写代码，以注册QueryBuilder实例，然后自动监控有挂起记录时。

如何使用：QueryBuilder集成

要使用QueryBuilder集成监控任何表中的挂起记录，需要创建和准备QueryBuilder实例，然后将其传递给Progressor - 剩余的将由系统自动处理。

QueryBuilder实例可以在任何地方注册（只要该位置在请求过程中执行） - 例如，在您的ext_localconf.php文件中

// Example: consider all hidden records in table "pages" to be a "pending" queue item. This shows a progress bar if
// there are any hidden pages in the site and adds progress as each page gets enabled.
// Note that in order to select hidden records you do need to remove the restriction for such records.
$queryBuilder = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\TYPO3\CMS\Core\Database\ConnectionPool::class)
    ->getQueryBuilderForTable('pages');
$queryBuilder->getRestrictions()->removeByType(\TYPO3\CMS\Core\Database\Query\Restriction\HiddenRestriction::class);
$queryBuilder->select('uid')->from('pages')->where('hidden = 1');
\NamelessCoder\Progressor\Progressor::trackProgressWithQuery($queryBuilder, 60, 'Hidden Pages');

这将注册该QueryBuilder实例作为Progressor读取进度信息的方式。执行查询并计数所有行，然后将初始行数存储在短暂存储中，该存储自动过期。每次从TYPO3后台读取进度信息时，进度将基于当前挂起行数与初始挂起行数之间的比较来计算。一旦没有更多的挂起记录，进度条将在60秒后过期。

查询应该尽可能简单 - 一种方法是确保它选择尽可能少的列，并且绝对不选择*。通常存在的良好选择列是uid列。查询必须返回“挂起”的行，并且不得使用在整个请求过程中会改变动态值，因为这会导致预期的更新数偏差。除此之外，它没有其他副作用，如无法执行查询。

• 第一个参数是QueryBuilder实例。
• 第二个参数是每个“滴答”之间的预期最大时间（您应该乘以1.5以确保安全）。
• 第三个参数是进度条的标签。

如何使用：火速而忘记API

另一种使用Progressor的方式是在您自己的代码中，例如在处理大量记录或文件的循环中，每个资源进行一次迭代。通过从这些地方调用单个方法，您可以初始化并不断更新进度条。

$expectedUpdates = 123; // This can be continually updated if loop skips/appends entries along the way
\NamelessCoder\Progressor\Progressor::recordProgress('myprogress', $expectedUpdates, 'My progress');

第一次调用此方法或如果$expectedUpdates更改时，内部计数器将（重新）初始化为该新值。如果计数器已经存在，则进度增加1个单位。当循环结束时，内部计数器应该正好计数您指定的预期项目数。

与其他集成一样，在60秒后此类临时进度条将自动删除。

• recordProgress方法的第一个参数是进度条的实例的唯一名称。
• 第二个参数是可选的，可以包含预期的更新次数。
• 第三个参数是进度条的标签（在整个循环中应保持不变）。

局限性

• 进度监控器的监控相对简单，安全措施较少，但其中一项安全措施是，任何超出范围的值（例如，导致完成度超过100%）将被截断到最大逻辑值。
• 进度监控器的内存目前基于缓存框架，需要支持标签的缓存后端。不幸的是，这意味着默认实现是数据库表，会导致额外的数据库查询。