README

FGTCLB: Environment State Manager

Description

TYPO3 CMS extension providing an environment builder and a state manager. It allows code to build and apply a fully featured TYPO3 environment (request, controller context, ServerRequest, TypoScript, language and visibility aspects, …) for a given page and to safely back up and restore the global state around such an operation.

Note: Currently only frontend environment handling is implemented. Backend environment handling is planned to be added later. The API is designed around an application type, so backend support can be added without breaking the public interfaces.

This functionality was extracted from fgtclb/academic-base into a dedicated, reusable extension.

Over the time there has been multiple extensions to allow the creation of the TypoScriptFrontendController (TSFE) but missed all the other handling and state in various places. They further lacked all a proper state management and build when used in FE or BE web-requests and did not returned to the previous state leaving the context in a populated (broken) state, something this extension tries to handle more properly over the different TYPO3 versions.

It ca be used in tasks, commands, schedulers, frontend requests, backend requests and also within functional tests to properly build the more global state.

Features

• EnvironmentBuilderFactory returning a TYPO3 core version compatible environment builder (TYPO3 v12 and v13). A FrontendEnvironmentBuilder is shipped today; a backend environment builder is planned.
• StateManager to build, apply and restore an environment state, emitting StateApplyEvent and StateBackupEvent PSR-14 events.

Compatibility

Installation

composer require fgtclb/environment-state-manager

Development

Tip

This extension uses the Build/Scripts/runTests.sh script dispatcher known from TYPO3 Core Development and also from a long list of public extensions adopting it for extension development. Every tool or test execution is dispatched through this wrapper script making it the same in every environment.

This requires at docker or podman to be installed on the system.

Tests and code quality checks are executed through the container based test runner:

# Prepare dependencies for a TYPO3 version
Build/Scripts/runTests.sh -t 13 -p 8.2 -s composerUpdate

# Coding guidelines (php-cs-fixer)
Build/Scripts/runTests.sh -s cgl

# Static analysis
Build/Scripts/runTests.sh -t 13 -s phpstan

# Unit / functional tests
Build/Scripts/runTests.sh -t 13 -s unit
Build/Scripts/runTests.sh -t 13 -s functional

See Build/Scripts/runTests.sh -h for all options.

Tests

The test suite combines feature tests for the extracted functionality with a set of tests adopted from the fgtclb/academic-* extension family.

Documentation

The extension documentation is based on ReStructured TEXT (ReST) and the TYPO3 render-guides can be used to render the documentation locally using the Build/Scripts/runTests.sh dispatcher.

Build/Scripts/runTests.sh -s renderDocumentation

The implementation follows the recommendation from the TYPO3 Documentation team except not using the Makefile or Github Action approach in favour of the centralized runTests.sh wrapper approach.

Adding the Makefile will be declined due to our own policies.

Feature tests

• Tests/Unit/EnvironmentBuilderFactoryTest.php and Tests/Functional/EnvironmentBuilderFactoryTest.php cover the EnvironmentBuilderFactory, including the TYPO3 core version specific service resolution.
• Tests/Functional/Core12 and Tests/Functional/Core13 hold the StateManager functional tests, gated per TYPO3 version through the not-core-12 / not-core-13 PHPUnit groups.

Adopted tests

These tests were adopted from fgtclb/academic-persons. Because a standalone extension can not depend on the monorepo-only fgtclb/academics-monorepo-testing-helper package, the underlying traits are adopted into this repository under Tests/FunctionalTestCase/ (namespace FGTCLB\EnvironmentStateManager\Tests\FunctionalTestCase):

• Tests/Unit/VersionCompatTest.php and Tests/Functional/VersionCompatTest.php use ExtensionCoreVersionCompatTestsTrait to assert the supported TYPO3 v12 and v13 major versions, as a unit and a functional test respectively.
• Tests/Functional/ExtensionLoadedTest.php uses ExtensionsLoadedTestsTrait to verify the extension is registered both by its composer package name (fgtclb/environment-state-manager) and its extension key (environment_state_manager). The academic extension chain of the original test is reduced to this extension only.

Create a release (maintainers only)

Prerequisites:

• git binary
• ssh key allowed to push new branches to the repository
• GitHub command line tool gh installed and configured with user having permission to create pull requests.

Create release

Set RELEASE_BRANCH to branch release should happen, for example: 'main'. Set RELEASE_VERSION to release version working on, for example: '1.0.0'.

Important

Requires GitHub cli tool with personal token and maintainer permission on the extension repository.

echo '>> Create release' ; \
  RELEASE_BRANCH='main' ; \
  RELEASE_VERSION='1.0.0' ; \
  DEV_VERSION='1.0.1' ; \
  echo ">> Checkout branches" && \
  git checkout master && \
  git fetch --all && \
  git pull --rebase && \
  git checkout ${RELEASE_BRANCH} && \
  git pull --rebase && \
  echo ">> Create release ${RELEASE_VERSION}" && \
  git checkout -b release-${RELEASE_VERSION} && \
  sed -i "s/^COMPOSER_ROOT_VERSION.*/COMPOSER_ROOT_VERSION=\"${RELEASE_VERSION}\"/" Build/Scripts/runTests.sh && \
  sed -i "s/^  RELEASE_VERSION.*/  RELEASE_VERSION='${RELEASE_VERSION}' ; \\\\/" README.md && \
  sed -i "s/^  DEV_VERSION.*/  DEV_VERSION='${DEV_VERSION}' ; \\\\/" README.md && \
  tailor set-version ${RELEASE_VERSION} && \
  composer config "extra"."typo3/cms"."version" "${RELEASE_VERSION}" && \
  echo "${RELEASE_VERSION}" > VERSION && \
  git add . && \
  git commit -m "[RELEASE] ${RELEASE_VERSION}" && \
  git push --set-upstream origin release-${RELEASE_VERSION} && \
  gh pr create --fill --base ${RELEASE_BRANCH} --title "[RELEASE] ${RELEASE_VERSION}" && \
  sleep 10 && \
  gh pr checks --watch --interval 2 && \
  sleep 10 && \
  gh pr merge -rd --admin && \
  git remote prune origin && \
  git tag ${RELEASE_VERSION} && \
  git push origin ${RELEASE_VERSION} && \
  echo ">> Post-release - set dev version: ${DEV_VRESION}-dev" && \
  git checkout -b set-dev-version-${DEV_VERSION} && \
  sed -i "s/^COMPOSER_ROOT_VERSION.*/COMPOSER_ROOT_VERSION=\"${DEV_VERSION}-dev\"/" Build/Scripts/runTests.sh && \
  tailor set-version ${DEV_VERSION} && \
  composer config "extra"."typo3/cms"."version" "${DEV_VERSION}-dev" && \
  echo "${DEV_VERSION}-dev" > VERSION && \
  git add . && \
  git commit -m "[TASK] Set dev version ${DEV_VERSION}" && \
  git push --set-upstream origin set-dev-version-${DEV_VERSION} && \
  gh pr create --fill --base ${RELEASE_BRANCH} --title "[TASK] Set dev version \"${DEV_VERSION}-dev\"" && \
  sleep 10 && \
  gh pr checks --watch --interval 2 && \
  sleep 10 && \
  gh pr merge -rd --admin && \
  git remote prune origin

This triggers the on push tags workflow (publish.yml) which creates the upload package,

License

GPL-2.0-or-later. See LICENSE.