README

License: GNU GPL, Version 3

Repository: https://gitlab.sgalinski.de/sg-ai/sg_ai

Please report bugs here: https://gitlab.sgalinski.de/sg-ai/sg_ai/-/work_items

Overview

sg_ai brings AI-assisted editorial workflows directly into TYPO3 backend forms and modules.

The extension covers:

Alt text generation for images (sys_file_reference and sys_file_metadata)
AI image generation in file fields (including automatic file reference creation)
AI text generation in configured text fields
SEO title/description generation for pages and social meta fields
Technical SEO, content SEO, and accessibility recommendations
Queue-based background processing for long-running operations
Backend history views for queued/generated AI results
Prompt persistence for image generation (including image settings block)
Automatic SEO-friendly image filename generation based on alt text

For end-user focused documentation, see:

docs/End-User/README.md

Requirements

TYPO3 v13 LTS (13.4)
PHP >= 8.3
Valid SG AI API key

Installation

Install extension:

composer require sgalinski/sg_ai

Activate extension in Extension Manager.
Run database schema updates in TYPO3 Install Tool / Admin Tools.
Configure extension settings (see next section).

Configuration

Open:

Admin Tools > Settings > Extension Configuration > sg_ai

Available extension settings (ext_conf_template.txt):

apiKey
useImageAnalysis
useBase64Encoding
useContextForAltText
language

Recommended API key setup:

Preferred: provide SG_AI_API_KEY as environment variable (for example in .env.local)
Alternative: set apiKey directly in extension configuration

Required Queue Setup (2.x)

Queue processing must be active for asynchronous tasks.

Required scheduler command:

vendor/bin/typo3 sg_ai:process-queue

Recommended execution interval:

every 5 minutes (*/5 * * * *)

Setup options:

Backend shortcut:
- Open module AI Page Insights
- Click Create scheduler task now if inactive warning is shown
Upgrade wizard:

vendor/bin/typo3 upgrade:run tx_sgai_configure_queue_scheduler_task

The wizard creates/updates an enabled scheduler task for sg_ai:process-queue in scheduler group SG_AI and enforces a safe queue limit.

Backend Usage

Modules

AI Page Insights (/module/web/sg-ai)
- Run URL checks, trigger recommendation tasks, monitor active queue work
AI History (/module/web/sg-ai-history)
- Browse and reuse generated results from queue/history
SEO History (action in main module)
- Filtered history view for SEO/accessibility recommendation types

Field Controls

Depending on TCA configuration and field type, backend forms can show:

Generate alt text button
Generate image button
Generate text button
Generate SEO title/description buttons
Generate technical/content/a11y recommendation buttons

Generated images are marked as AI-generated in TYPO3 metadata/reference flags (tx_sgai_is_ai_generated) and receive automatic alt text handling.

Queue and History Behavior

Long-running tasks are enqueued and processed asynchronously.
Queue records are persisted in tx_sgai_queue.
Results/history are persisted in tx_sgai_url_check.
Remote background processing (HTTP 202/message ID) is supported and finalized via queue polling.
Queue entries store cloud tracking metadata (remote_message_id, remote_status) for remote runs.
History views support search, sorting, pagination, and result preview via View action.
If the cloud API rate limits (HTTP 429), processing is deferred and retried safely.

Image Generation Behavior

The last image prompt is persisted and reused per record/field (tx_sgai_last_image_prompt).
Prompt persistence keeps the image settings comment block, including image_size and output_format.
Generated images are automatically marked as AI-generated (tx_sgai_is_ai_generated).
Generated images can be renamed from alt text to SEO-friendly slugs.
Renamed files are capped at 60 characters total (including hash suffix and extension).

TCA Configuration Example (AI Image Generation)

'images' => [
	'config' => [
		'sg_ai' => [
			'promptProvider' => 'Vendor\\Extension\\PromptProvider\\CustomPromptProvider',
			'promptTemplate' => 'Generate an image for ###title### with ###category### theme',
			'disabled' => true,
			'image_size' => 'landscape_16_9',
			'output_format' => 'png',
		],
		'type' => 'file',
	],
],

Supported image size presets:

square_hd
square
portrait_4_3
portrait_16_9
landscape_4_3
landscape_16_9

You can also pass custom dimensions:

['width' => 1280, 'height' => 720]

CLI Commands

Alt text generation

vendor/bin/typo3 sg_ai:generate-alt-texts

Options:

--limit
--dry-run

SEO meta generation

vendor/bin/typo3 sg_ai:generate-seo-meta [page-uid]

Options include:

--force
--title-only
--description-only
--limit
--exclude-hidden
--exclude-deleted

AI recommendations generation

vendor/bin/typo3 sg_ai:generate-ai-recommendations [page-uid]

Options include:

--force
--accessibility-only
--content-seo-only
--technical-seo-only
--limit
--exclude-hidden
--exclude-deleted

Queue operations

Process queue:

vendor/bin/typo3 sg_ai:process-queue

List queue:

vendor/bin/typo3 sg_ai:list-queue

Cleanup queue/results:

vendor/bin/typo3 sg_ai:cleanup-queue

Troubleshooting

Tasks stay pending:
- verify scheduler task exists and is enabled
- run one manual queue cycle: vendor/bin/typo3 sg_ai:process-queue --limit=5
API key error:
- check SG_AI_API_KEY / extension configuration
URL/page checks fail:
- ensure target pages are publicly reachable for checks that require rendered output

Testing

Run extension checks from the project root:

composer phpunit vendor/sgalinski/sg-ai
composer phpstan vendor/sgalinski/sg-ai
composer ecs vendor/sgalinski/sg-ai

sgalinski / sg-ai

Maintainers

Package info

Statistics

Security