itzbund/gsb-solr

GSB solr. This is Part of the Goverment Site Build (GSB) 11. Der GSB 11 ist eine Maßnahme der Dienstekonsolidierung Bund (DKB) des Bundesministeriums des Innern und für Heimat (BMI) und wird im Auftrag des Informationstechnikzentrums Bund (ITZBund) durchgeführt.

v1.9.0 2024-11-05 11:33 UTC

Requires

• php: ^8.1
• apache-solr-for-typo3/solr: ^12.0
• typo3/cms-core: ^12.4
• typo3/cms-frontend: ^12.4
• typo3/cms-install: ^12.4

Requires (Dev)

• captainhook/captainhook-phar: ^5.21
• codeception/codeception: *
• codeception/module-asserts: *
• codeception/module-db: *
• doctrine/dbal: ^3.3
• ergebnis/composer-normalize: ^2.28
• friendsofphp/php-cs-fixer: ^3.14
• helmich/typo3-typoscript-lint: 3.1.0 || 3.2.0 || 3.2.1
• itzbund/captainhook-hooks: ^1.0
• michielroos/typo3scan: ^1.7
• mockery/mockery: ^1.6
• php-coveralls/php-coveralls: ^2.5
• phpmd/phpmd: ^2.13
• phpstan/extension-installer: ^1.2
• phpstan/phpstan: ^1.10
• phpstan/phpstan-phpunit: ^1.3
• phpstan/phpstan-strict-rules: ^1.5
• phpunit/phpunit: ^10.0
• ramsey/conventional-commits: ^1.5
• saschaegerer/phpstan-typo3: ^1.8
• sbuerk/typo3-cmscomposerinstallers-testingframework-bridge: ^0.1.2
• seld/jsonlint: ^1.9
• squizlabs/php_codesniffer: ^3.7
• ssch/typo3-rector: ^1.1
• symfony/yaml: ^6.1
• typo3/coding-standards: ^0.7 || ^0.8
• typo3/testing-framework: ^8.1

Suggests

• ext-redis: *

GPL-3.0-or-later

• Patrick Schriner
• Willi Wehmeier

README

GSB 11 Extension gsb_solr

About

The extension gsb_solr extends the standard solr extension to make it work in the context of gsb11.

It provides a custom PageIndexerRequest object that does not use an external http request to fill the solr index. This is necessary due to limitations in the hosting environment. also the TitleTagSearchViewHelper adds te Searchword to the title tag.

Learn more about the GSB 11.

Installation

The best way to install this extension is to start with the GSB Sitepackage Kickstarter extension.

Quick installation without GSB Sitepackage Kickstarter

In a composer-based TYPO3 installation you can install the extension EXT:gsb_solr via composer:

composer config -g gitlab-domains gitlab.opencode.de && \
composer config -g repositories.gsb-solr vcs https://gitlab.opencode.de/bmi/government-site-builder-11/extensions/gsb_solr.git

composer require itzbund/gsb-solr

Configuration

Typoscript: allowedSites

To set up the TypoScript configuration with sane defaults include the GSB Solr Package TypoScript record in your websites root Template Record, or activate the ITZBUNDPHP-3878 feature flag.

If your site is being served on different domains for backend and frontend it's best to add the frontend domain explicitly to the root plugin.tx_solr.search.query.allowedSite typoscript configuration, e.g.:

plugin.tx_solr.search.query.allowedSites = frontend.domain.de

otherwise if indexing for frontend.domain.de the index will not be available to users of the backend domain. This is due to EXT:solr siteHash mechanism and the default value __current_site. If you add both the backend and the frontend domain you might see duplicate results, depending on how the indexing was triggered (backend vs cli/task).

⚠️ Warning: if allowedSites are not configured properly solr will seem eratic: you might see no search results, ever,you might see search results that don't change when content is changed. You cannot delete any index in the solr server from the backend except for the index for (primary) frontend domains either.

Scheduler Tasks

For the solr to work properly in TYPO3 you need to set up at least one scheduler task (Index Queue Worker and Force Re-Indexing of a site).

Take a good look at the scheduler task documentation for solr.

⚠️ Warning: The worker should only be configured to index 5-10 documents per run. This is due to our indexer needing a lot of memory as everything is processed in the same request context.

Extension configuration: Indexer modes

This extension provides three indexer modes, which can be configured in the extension settings

⚠️ Note: on readonly systems this can only be configured via environment variables

Indexer mode	Description
use_internal_subrequests	default in GSB11 context: uses lots of memory, because no real HTTP request is ever used. Instead subrequests are used, similar to the error handler of the TYPO3 core.
use_self_with_host_header	similar to the 'default' implementation, but doesn't use DNS resolution and will always go against 127.0.0.1. Has some benefits in restricted environments because DNS can be flacky; will only work if the current (usually CLI) system also has the web server running (which it might not)
default	the default EXT:solr implementation

Usage

Nothing to do.

Feature Flags in gsb_solr

This document explains how to use feature flags. Feature flags allow you to enable or disable specific features in your installation. This is of particular importance to not use features that have not passed the approval process.

Configuration

Feature flags are configured in the .env or the local-dev/.ddev/docker-compose.environment.yaml file on ddev machine. To add a feature flag, use the following syntax:

# Feature flag for the specific tickets. Set them to true to activate the features.
- TYPO3__SYS__features__ITZBUNDPHP-749=%const(bool:true)%

In this example, the feature flag ITZBUNDPHP-749 is set to true. To disable the feature, change the value to false or delete the setting.

Feature Flag Truth Table

This table illustrates the behavior of feature flags in various states.

Feature Flag State	Evaluated Value	Description
featureFlag = true	true	The feature is explicitly enabled.
featureFlag = false	false	The feature is explicitly disabled.
featureFlag = ''	false	An empty value is treated as false.
featureFlag not exist	false	A non-existent flag defaults to false.

Curent feature flags of gsb_core

Feature flag	Description
ITZBUNDPHP-749	Enables the autosuggest feature for the search input field
ITZBUNDPHP-3878	Autoconfigures allowedSites
ITZBUNDPHP-4079	Adds a wizard that automatically adds missing typoscript includes and scheduler tasks needed by this extension

Usage in PHP Code

To use a feature flag in your PHP code, you can check the flag's value in the global TYPO3 configuration. Here's an example:

if (GeneralUtility::makeInstance(Features::class)->isFeatureEnabled('ITZBUNDPHP-749')) {
    // Only if the feature flag is set to true the feature is activated
    // Feature-specific code goes here
}

In this example, the feature-specific code will only execute if the feature flag ITZBUNDPHP-749 is set to true.

Usage in Fluid Templates

You can also use feature flags in your Fluid templates with a custom ViewHelper. First, ensure you include the namespace for the ViewHelper:

{namespace gsb=ITZBund\GsbCore\ViewHelpers}

Then, use the featureFlag ViewHelper to conditionally render content based on the feature flag:

<f:if condition="{gsb:featureFlag(featureKey: 'ITZBUNDPHP-749')}">
    <!-- Feature-specific content goes here -->
</f:if>

In this example, the content inside the <f:if> tag will always be rendered if the feature flag ITZBUNDPHP-749 is not set to false.

Further Reading

For more information about feature flags in TYPO3, please refer to the TYPO3 Documentation on Feature Flags.

Contribute

As with TYPO3, we encourage you to join the project by submitting changes. Development of the GSB 11 happens mainly in the GSB 11 TYPO3 extension repositories.

To get started, have a look at our detailed contribution walkthrough.