README

About

This extension is based on cabag's boiler_plate extension.

The goal of this extension is to provide a progress bar to the TYPO3 backend accessible as a toolbar item, so switching from a module to another still allows to keep track of a long running task.

The extension implementing this feature have two ways of displaying the progres:

As a progress circle, containing the progress percentage as a number in the middle
As a progress bar with an additional progress label, allowing to give additional information on a long running task which overall amount of subtasks may not be known in advance, in this case the progress bar might be used to display the progress over all tasks.

Such long running tasks have to be implemented as tasks for now but could be implemented as Websocket calls in the future.

For developers

To ease the implementation effort, a BackendProgressAwareTrait is provided by the extension.

Initialising

See examples/Command/ExampleProgressBarCommand.php for a full example

<?php

namespace Cabag\BackendProgress\Examples\Command;

use Cabag\BackendProgress\Progress\BackendProgressAwareTrait;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;

class ExampleProgressBarCommand extends Command
{
    use BackendProgressAwareTrait;

    /**
     * Configure command
     */
    public function configure()
    {
        $this->registerTaskInProgress('your_awesome_task', 3);
        parent::configure(); // TODO: Change the autogenerated stub
    }

    /**
     * @param InputInterface $input
     * @param OutputInterface $output
     * @return int|void
     */
    public function execute(InputInterface $input, OutputInterface $output)
    {
        // Start the task
        $this->startTask();

        // Go to the next step
        $this->nextStep();

        // Update the step label
        $this->updateStepLabel('Executing part one of this step');

        $array = [];
        // Do some more for find $array
        // ...

        // Update in a loop
        $amount = count($array);
        foreach ($array as $key => $value) {
            $this->updateStepLabel(sprintf('Update part %s from %d', $key, $amount));
            // Do some processing
        }
        // Go to the next step and update label
        $this->nextStep('Label for whole task (can be updated)');

        $this->nextStep('This is the last step');

        // If you execute nextStep too often, the total amount of steps will raise and the completion will stay at
        // steps-1 until endTask is called
        $this->nextStep('An additional step');

        // End the task
        $this->endTask();

        // Set up how long a task should stay in the queue after finishing (default 60 seconds)
        $this->cleanupTask(30);
        // Negative values are put into absolute values, so this is equivalent
        $this->cleanupTask(-30);
    }
}

See examples/Command for the source.

Do not forget to delete all files and folders, you do not need.

Static analysis

The Boilerplate Extension features several static code analysis tools. Currently they are:

PHPStan (https://github.com/phpstan/phpstan)
phpcs (https://github.com/squizlabs/PHP_CodeSniffer)
Gitlab SAST (https://docs.gitlab.com/ee/user/application_security/sast/)

All of them are configured to run out of the box either in your local environment or in Gitlabs CI. If you just clone the boilerplate, all tools are enabled by default. If you want to disable them in gitlab, remove the following lines (starting with - composer from gitlab-ci.yml according to the tests, you want to remove:

static_analysis:
  stage: static_analysis
  script:
    - composer phpstan
    - composer phpcs

Example: if you want to remove phpcs from analysis in the deployment, remove the line - composer phpcs

If you want to remove Gitlab SAST, remove the include - template: Security/SAST.gitlab-ci.yml (not recommended)

How to use the static analysis features in your own extension?

PHPStan

Add the following your .editorconfig file (if it does not exist already):

# neon-Files
[*.{neon,neon.dist}]
indent_style = tab
indent_size = 2

Copy the file phpstan.neon.dist to your extension
Copy the gitlab-ci.yml file (or only the required parts) if you want to integrate static analysis into the CI. If you want static analysis only on your local system, skip this step.
Make sure to delete the scripts from gitlab-ci, you do not want to fire during your deployment
Add the following your .gitignore file (if it does not exist already):

# TYPO3 and vendors
/vendor
/public
composer.lock
# Custom configuration files for testing
phpstan.neon

Add the following two sections to your composer.json file (if they do not exist already). If the sections exist, only add their contents:

	"require-dev": {
		"phpstan/phpstan": "*",
		"typo3/cms-core": "^10.4.6",
		"typo3/cms-extbase": "^10.4.6"
	},
	"scripts": {
		"phpstan": "phpstan analyse"
	}

If the core is already required in the require {} section, remove it from require-dev. To find out, which other core packages are required, scan the use statements in your classes to get an idea of the required packages from the core.

You might have to add more typo3/cms-* dependencies to require-dev if you use Core Classes in your ext (which you should!)
Do a composer update
After update is finished, you can run composer phpstan to check for errors in your extension.
Pro-Tip: Do it on your local System before you push.

phpcs

Add the following your .editorconfig file (if it does not exist already):

# xml-Files
[*.{xml,xml.dist}]
indent_style = tab

Copy the file phpcs.xml.dist to your extension
Copy the gitlab-ci.yml file (or only the required parts) if you want to integrate static analysis into the CI. If you want static analysis only on your local system, skip this step.
Make sure to delete the scripts from gitlab-ci, you do not want to fire during your deployment
Add the following your .gitignore file (if it does not exist already):

# TYPO3 and vendors
/vendor
/public
composer.lock
# Custom configuration files for testing
phpcs.xml

Add the following two sections to your composer.json file (if they do not exist already). If the sections exist, only add their contents:

	"require-dev": {
		"squizlabs/php_codesniffer": "*",
		"typo3/cms-core": "^10.4.6",
		"typo3/cms-extbase": "^10.4.6"
	},
	"scripts": {
		"phpcs": "phpcs"
	}

You might have to add more typo3/cms-* dependencies to require-dev if you use Core Classes in your ext (which you should!)
Do a composer update
After update is finished, you can run composer phpcs to check for errors in your extension. If phpcs finds errors, it might be able to fix some of them. If it suggests fixing errors, run vendor/bin/phpcbf
Pro-Tip: Do it on your local System before you push.

cabag / ext-backend-progress

Maintainers

Details