Exception handling with AI generated solutions 

• Configuration
• Exception handler
• Console commands

Extension key

solver

Package name

eliashaeussler/typo3-solver

Version

main

Language

en

Author

Elias Häußler & contributors

License

This extension documentation is published under the CC BY-NC-SA 4.0 (Creative Commons) license.

An extension for TYPO3 CMS to solve exceptions with AI generated solutions. It uses the OpenAI PHP client to send a prompt to a configured model and uses the responded completion as solution. Several completion attributes (model, tokens, temperature, number of completions) are configurable. It also provides a console command to solve problems from command line.

Introduction 

Installation 

composer require eliashaeussler/typo3-solver

Configuration 

For the extension to work, it must be configured in some ways. The most important configuration is the OpenAI API key, otherwise requests to OpenAI won't be possible.

Learn what configuration options are generally available on the following pages:

API key 

You need an API key to perform requests at OpenAI. Once generated, the key must be configured in the extension configuration.

Follow these steps to create and use an OpenAI API key:

1. Log in with your OpenAI account

   Head over to https://platform.openai.com/account/ and log in with your OpenAI account. If you don't have an account yet, you can sign up on this page as well.

2. Create API key

   Head over to the API Keys section. You should see all your API keys listed, if you already generated ones.

   Click on the Create new secret key button to create a new API key. Copy the key to your clipboard or safe it elsewhere.

   Attention

   You won't be able to display the key again once you closed the page.

3. Add extension configuration

   Paste the generated API key in the extension configuration Extension configuration. This can either be done in the TYPO3 backend or directly in your config/system/settings.php (formerly typo3conf/ext/LocalConfiguration.php) file.

4. Keep the key secret!

   Don't share this key with anyone else! Keep in mind that everyone with access to this key will be able to perform requests with your OpenAI account. This can be very cost intensive as request are not free.

Extension configuration 

The extension currently provides the following configuration options:

Usage 

The core component of the extension is the modified debug exception handler. However, there are more different ways to get the full power out of the extension. This section describes how to properly use the extension in all possible ways.

Exception handler 

The core component of this extension is to modify the default debug exception handler from TYPO3 core. For this, the \EliasHaeussler\Typo3Solver\Error\AiSolverExceptionHandler class is shipped with the extension.

return [
    'SYS' => [
        'debugExceptionHandler' => 'EliasHaeussler\\Typo3Solver\\Error\\AiSolverExceptionHandler',
    ],
];

Types of problem solving 

Streamed solution 

New in version 0.2.0

Feature: #64 - Switch to chat completions and implement solution streams

This variant is automatically used if an exception is triggered in a stage where TYPO3 bootstrapping is already done and therefore a service container exists. In this case, the solution is provided asynchronous from an event stream by a custom middleware /tx_solver/solution.

Note

The extension provides two early-staged middlewares:

1. Ensure solution stream is possible by requesting /tx_solver/ping
2. Provide streamed solution by requesting /tx_solver/solution

Both middlewares are registered to be handled very early, ideally prior to all other middlewares. If you register additional middlewares on your own, make sure they don't conflict with the middlewares provided by this extension.

Read more at Middlewares.

Default solution 

There are cases where solution streaming is not possible. For example, if the exception to handle was triggered very early in the bootstrapping process. Those cases prevent solution streaming as it requires a functioning bootstrapping and a successfully built service container.

If solution streaming is not possible, the solution is provided synchronous. This way is less convenient because – depending on the configured attributes – requests to OpenAI may take relatively long, up to several minutes. During the request, no actions can be done as it would interrupt the request and therefore abort problem solving.

Note

You can influence long durations a little bit by modifying the attributes used for each request to OpenAI. All supported attributes can be changed in the extension configuration.

Console commands 

The extension provides the following console commands:

vendor/bin/typo3 solver:solve [<problem>] [options]

typo3/sysext/core/bin/typo3 solver:solve [<problem>] [options]

vendor/bin/typo3 solver:list-models [options]

typo3/sysext/core/bin/typo3 solver:list-models [options]

vendor/bin/typo3 solver:cache:flush [<identifier>]

typo3/sysext/core/bin/typo3 solver:cache:flush [<identifier>]

Using the API 

Besides the usage via the modified debug exception handler and the console commands, there is also a public PHP API. It can be used to solve problems directly in PHP code.

class Solver

Fully qualified name

\EliasHaeussler\Typo3Solver\ProblemSolving\Solver

Core component to solve problems by a given exception.

solve ( $exception)

Provide solution for given exception and format it according to the configured formatter. If a cached solution exists, the provider does not request a new solution.

Note

This method is basically described at Default solution.

param Throwable $exception

Exception for which a solution is to provide.

returntype

string|null

solveStreamed ( $exception)

Provide formatted solution for given exception, but use a solution stream for each solution delta. This basically mimics the behavior of ChatGPT, where the solution is provided asynchronous.

Note

This method is basically described at Streamed solution.

param Throwable $exception

Exception for which a solution is to provide.

returntype

Traversable<string>

use EliasHaeussler\Typo3Solver;
use TYPO3\CMS\Core;

$configuration = Core\Utility\GeneralUtility::makeInstance(
    Typo3Solver\Configuration\Configuration::class,
);

// Use any supported formatter and provider
$formatter = Core\Utility\GeneralUtility::makeInstance(
    Typo3Solver\Formatter\WebFormatter::class,
);
$solutionProvider = Core\Utility\GeneralUtility::makeInstance(
    Typo3Solver\ProblemSolving\Solution\Provider\OpenAISolutionProvider::class,
);

$solver = new Typo3Solver\ProblemSolving\Solver(
    $configuration,
    $formatter,
    $solutionProvider,
);

$formattedSolution = $solver->solve($exception);

foreach ($solver->solveStreamed($exception) as $solutionDelta) {
    echo $solutionDelta;
}

Developer corner 

This section provides an insight into which development options are available and how these can be integrated into exception handling.

Solution providers 

The most relevant components when it comes to the actual problem solving are solution providers. Each solution provider describes a way to solve a given problem.

interface SolutionProvider

Fully qualified name

\EliasHaeussler\Typo3Solver\ProblemSolving\Solution\Provider\SolutionProvider

Interface for solution providers used to provide a solution for a given problem. Solution providers can be combined with \EliasHaeussler\Typo3Solver\ProblemSolving\Solution\Provider\CacheSolutionProvider if they are cacheable.

static create ( )

Create a new instance of the solution provider. This is mainly used on a low level basis where dependency injection is not available.

returns

An instance of the current solution provider.

getSolution ( $problem)

Provide a solution for the given problem.

param EliasHaeussler\Typo3Solver\ProblemSolving\Problem\Problem $problem

The problem to be solved

returntype

EliasHaeussler\Typo3Solver\ProblemSolving\Solution\Solution

throws

EliasHaeussler\Typo3Solver\Exception\UnableToSolveException

canBeUsed ( $exception)

Define whether the solution provider can handle the given exception. This is especially useful to skip problem solving for some exceptions whose solution is already known or is too specific to solve.

param Throwable $exception

The exception to test for compatibility

returntype

bool

isCacheable ( )

Define whether solutions provided by this solution provider should be cached when using the solution provider in combination with \EliasHaeussler\Typo3Solver\ProblemSolving\Solution\Provider\CacheSolutionProvider.

returntype

bool

listModels ( $includeUnsupported = false)

List all AI models by the underlying AI provider. By default, only supported models are returned.

param bool $includeUnsupported

Define whether to return unsupported models as well

returntype

list<EliasHaeussler\Typo3Solver\ProblemSolving\Solution\Provider\Model\AiModel>

interface StreamedSolutionProvider

Fully qualified name

\EliasHaeussler\Typo3Solver\ProblemSolving\Solution\Provider\StreamedSolutionProvider

Extended interface for solution providers that are able to stream solutions. Read more about a practical use case of this interface at Streamed solution.

Note

This interface extends the default \EliasHaeussler\Typo3Solver\ProblemSolving\Solution\Provider\SolutionProvider.

getStreamedSolution ( $problem)

Provide a solution stream for the given problem. The stream is returned as an instance of \Traversable, while each traversed item is an instance of \EliasHaeussler\Typo3Solver\ProblemSolving\Solution\Solution.

param EliasHaeussler\Typo3Solver\ProblemSolving\Problem\Problem $problem

The problem to be solved

returntype

Traversable<EliasHaeussler\Typo3Solver\ProblemSolving\Solution\Solution>

throws

EliasHaeussler\Typo3Solver\Exception\UnableToSolveException

Prompts 

AI models must be prompted to provide a solution for a given problem. For this, the extension provides a basic abstraction to implement such prompts.

interface Prompt

Fully qualified name

\EliasHaeussler\Typo3Solver\ProblemSolving\Solution\Prompt\Prompt

Basic abstraction to generate prompts for a given problem. Ideally, prompts are developed to match a specific model.

static create ( )

Create a new instance of the prompt generator. This is mainly used on a low level basis where dependency injection is not available.

returns

An instance of the current prompt generator.

generate ( $exception)

Generate a prompt to provide a solution for the given exception.

param Throwable $exception

The exception to generate a prompt for

returntype

string

Formatters 

Formatters are used to make a generated solution visible to the user.

interface Formatter

Fully qualified name

\EliasHaeussler\Typo3Solver\Formatter\Formatter

Interface for formatters that convert a given problem and its solution into a readable format.

format ( $problem, $solution)

Format given problem and solution to string.

param EliasHaeussler\Typo3Solver\ProblemSolving\Problem\Problem $problem

The problem to be formatted

param EliasHaeussler\Typo3Solver\ProblemSolving\Solution\Solution $solution

The solution to be formatted

returntype

string

Template rendering 

Since exception handling may happen on a very low level where TYPO3 bootstrapping is not completed yet, this extension ships with a very generic template renderer.

class TemplateRenderer

Fully qualified name

\EliasHaeussler\Typo3Solver\View\TemplateRenderer

Generic low-level renderer for Fluid templates shipped with EXT:solver. This class is not intended for use anywhere else than in the extension itself.

render ( $templatePath, $variables = [])

Render a given template with optional variables. The template path must be relative to EXT:solver/Resources/Private/Templates.

param string $exception

Path to the template to be rendered

param array $variables

Optional template variables

returntype

string

Caching 

Generated solutions can be cached if the solution provider in use is cacheable (see \EliasHaeussler\Typo3Solver\ProblemSolving\Solution\Provider\SolutionProvider::isCacheable). For this, a filesystem-based solution cache is implemented. In addition, an exception cache is provided which stores exceptions when solution streaming is active.

class ExceptionsCache

Fully qualified name

\EliasHaeussler\Typo3Solver\Cache\ExceptionsCache

Low-level cache manager for exceptions. This class is only used in combination with solution streaming.

Note

This cache writes to var/cache/data/tx_solver/exceptions.php.

get ( $entryIdentifier)

Get exception by cache identifier. If no cache with the given identifier exists, null is returned.

param string $entryIdentifier

Cache identifier of the exception to look up

returntype

Throwable|null

getIdentifier ( $exception)

Get calculated exception identifier of the given exception.

param Throwable $exception

Exception to calculate a cache identifier

returntype

string

set ( $exception)

Add the given exception to the exceptions cache and return the associated cache identifier.

param Throwable $exception

The exception to be cached

returntype

string

flush ( )

Remove all cached exceptions.

class SolutionsCache

Fully qualified name

\EliasHaeussler\Typo3Solver\Cache\SolutionsCache

Low-level cache manager for solutions. This class is used in combination with \EliasHaeussler\Typo3Solver\ProblemSolving\Solution\Provider\CacheSolutionProvider.

Note

This cache writes to var/cache/data/tx_solver/solutions.php.

get ( $problem)

Get cached solution for the given problem. If no solution exists in cache, null is returned.

param EliasHaeussler\Typo3Solver\ProblemSolving\Problem\Problem $problem

Problem to get a cached solution for

returntype

EliasHaeussler\Typo3Solver\ProblemSolving\Solution\Solution|null

set ( $problem, $solution)

Add the given solution to the solutions cache and use the given problem to generate the cache identifier.

param EliasHaeussler\Typo3Solver\ProblemSolving\Problem\Problem $problem

The problem of the solution to be cached

param EliasHaeussler\Typo3Solver\ProblemSolving\Solution\Solution $solution

The solution to be cached

flush ( )

Remove all cached solutions.

Configuration API 

In order to access the extension configuration, a slim PHP API exists. Each configuration option is accessible by an appropriate class method.

class Configuration

Fully qualified name

\EliasHaeussler\Typo3Solver\Configuration\Configuration

API to access all available extension configuration options.

getAPIKey ( )

Get the configured OpenAI API key.

returntype

string|null

getModel ( )

Get the configured OpenAI model.

returntype

string

getMaxTokens ( )

Get the configured maximum number of tokens.

returntype

int

getTemperature ( )

Get the configured temperature.

returntype

float

getNumberOfCompletions ( )

Get the configured number of completions.

returntype

int

getCacheLifetime ( )

Get the configured cache lifetime.

returntype

int

isCacheEnabled ( )

Check whether solution caching is currently enabled. The cache is enabled if the configured cache lifetime is greater than 0.

returntype

bool

getProvider ( )

Get the configured solution provider.

returntype

\EliasHaeussler\Typo3Solver\ProblemSolving\Solution\Provider\SolutionProvider

getPrompt ( )

Get the configured prompt.

returntype

\EliasHaeussler\Typo3Solver\ProblemSolving\Solution\Prompt\Prompt

getIgnoredCodes ( )

Get the configured list of exception codes to ignore.

returntype

array

Middlewares 

The extension provides two middlewares to achieve solution streaming. Both middlewares are registered for execution prior to all other middlewares. This allows to keep execution times during exception handling as low as possible.

Migration 

This section lists required migration steps for upgrades between major versions.

Contributing 

Thanks for considering contributing to this extension! Since it is an open source product, its successful further development depends largely on improving and optimizing it together.

The development of this extension follows the official TYPO3 coding standards. To ensure the stability and cleanliness of the code, various code quality tools are used and most components are covered with test cases. In addition, we use DDEV for local development. Make sure to set it up as described below. For continuous integration, we use GitHub Actions.

git clone https://github.com/eliashaeussler/typo3-solver.git
cd typo3-solver

ddev start

ddev composer install
ddev frontend install

# All analyzers
ddev cgl analyze

# Specific analyzers
ddev cgl analyze:dependencies

# All linters
ddev cgl lint

# Specific linters
ddev cgl lint:composer
ddev cgl lint:editorconfig
ddev cgl lint:php

# Fix all CGL issues
ddev cgl fix

# Fix specific CGL issues
ddev cgl fix:composer
ddev cgl fix:editorconfig
ddev cgl fix:php

# All static code analyzers
ddev cgl sca

# Specific static code analyzers
ddev cgl sca:php

# All linters
ddev frontend run lint

# Specific linters
ddev frontend run lint:scss
ddev frontend run lint:ts

# Fix all CGL issues
ddev frontend run fix

# Fix specific CGL issues
ddev frontend run fix:scss
ddev frontend run fix:ts

# All tests
ddev test

# Specific tests
ddev test functional
ddev test unit

# All tests with code coverage
ddev test coverage

# Specific tests with code coverage
ddev test coverage:functional
ddev test coverage:unit

# Merge code coverage of all test suites
ddev test coverage:merge

open .build/coverage/html/_merged/index.html

# Rebuild and open documentation
composer docs

# Build documentation (from cache)
composer docs:build

# Open rendered documentation
composer docs:open

Sitemap