PHPackages                             juhe-it-solutions/contao-openai-assistant - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. juhe-it-solutions/contao-openai-assistant

ActiveContao-bundle[Utility & Helpers](/categories/utility)

juhe-it-solutions/contao-openai-assistant
=========================================

OpenAI Assistant integration for Contao CMS

v1.1.3(2mo ago)11421[3 issues](https://github.com/juhe-it-solutions/contao-openai-assistant/issues)LGPL-3.0-or-laterPHPPHP ^8.2CI failing

Since Jul 3Pushed 2mo ago1 watchersCompare

[ Source](https://github.com/juhe-it-solutions/contao-openai-assistant)[ Packagist](https://packagist.org/packages/juhe-it-solutions/contao-openai-assistant)[ Docs](https://www.juhe-it-solutions.at)[ RSS](/packages/juhe-it-solutions-contao-openai-assistant/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (8)Versions (14)Used By (0)

Contao OpenAI Assistant Extension
=================================

[](#contao-openai-assistant-extension)

[![License: LGPL-3.0-or-later](https://camo.githubusercontent.com/e9960a4300c4eabf884238c727a3328051216e98fa4e2f4242778c5695599b87/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4c47504c253230332e302d2d6f722d2d6c617465722d626c75652e737667)](LICENSE)[![Contao](https://camo.githubusercontent.com/95181d6c879365775c6c6d19729c12a654d3a7ba59626a392392269f0da681cf/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f436f6e74616f2d352e332b2d677265656e2e737667)](https://contao.org)[![PHP](https://camo.githubusercontent.com/26bf6e41ce21eb39db7d8ace00cc112ed5be5e9d8fbd657254521fcea77983b9/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e322b2d707572706c652e737667)](https://php.net)[![Production Ready](https://camo.githubusercontent.com/89a92c97921fc83fbda1e5bc6ae0575dca897f1c6d0e8473a20e544251f62e22/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f50726f64756374696f6e2d52656164792d627269676874677265656e2e737667)](https://github.com/juhe-it-solutions/contao-openai-assistant)[![Packagist](https://camo.githubusercontent.com/f6db8b2a5449b2b889e882ec7e7a67af347e37ddc1c3286eb56f6742df0f5820/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6a7568652d69742d736f6c7574696f6e732f636f6e74616f2d6f70656e61692d617373697374616e742e737667)](https://packagist.org/packages/juhe-it-solutions/contao-openai-assistant)

About
-----

[](#about)

**juhe-it-solutions/contao-openai-assistant** is a comprehensive OpenAI Assistant integration for Contao 5.3+ providing backend management and a modern frontend chatbot. Developed and maintained by [JUHE IT-solutions](https://github.com/juhe-it-solutions), Austria.

This extension allows you to create, configure, and deploy AI assistants directly within your Contao CMS, with secure API key management, file uploads, and a customizable frontend chat widget.

🎉 A Quick Note from the Developer
---------------------------------

[](#-a-quick-note-from-the-developer)

Hey folks! 👋 This whole project is my **first attempt** at completely vibing with Contao extension development (crafted in countless nights fueled by coffee ☕ and determination 💪).

While I'm super proud of what we've built here, I gotta be honest - I don't have the bandwidth to actively maintain this project.

**Feel free to:**

- 🐛 Create issues (bugs, feature requests, whatever!)
- 🔧 Submit pull requests
- 💡 Suggest improvements
- ⭐ Give it a star if you find it useful
- ☕ [Buy me a coffee](https://buymeacoffee.com/juliuscaesar1) if this extension helps you out!

**No guarantees** that everything will be addressed immediately, but I'll take a look when time allows! Since this is open source, feel free to fork and enhance it! 🎯

🚀 Features
----------

[](#-features)

### Backend Management

[](#backend-management)

- **OpenAI Configuration Management**: Secure API key storage and validation
- **Assistant Creation & Management**: Create and configure AI assistants with custom instructions
- **File Upload & Management**: Upload and manage files for assistant knowledge base
- **Vector Store Integration**: Automatic creation and management of OpenAI vector stores
- **Model Selection**: Fast loading of all available OpenAI models with save-time validation
- **Parameter Configuration**: Fine-tune temperature, top\_p, and other assistant parameters

### Frontend Chatbot

[](#frontend-chatbot)

- **Responsive Chat Interface**: Modern, accessible chat widget
- **Theme Support**: Light and dark theme with customizable colors
- **Positioning Options**: Multiple chat widget positions (bottom-right, bottom-left, etc.)
- **Session Management**: Persistent conversation threads
- **CSRF Protection**: Built-in security with CSRF token validation
- **Accessibility**: ARIA labels and keyboard navigation support
- **Disclaimer Feature**: Configurable disclaimer text with information icon in chat header

### Security & Performance

[](#security--performance)

- **API Key Encryption**: Secure storage of OpenAI API keys
- **Rate Limiting**: Built-in protection against abuse
- **Error Handling**: Comprehensive error logging and user feedback
- **Session Management**: Thread-based conversation persistence

📋 Requirements
--------------

[](#-requirements)

- **Contao**: 5.3 or higher (tested with Contao 5.5)
- **PHP**: 8.2 or higher
- **OpenAI API Key**: Valid OpenAI API key with Assistants API access
- **Composer**: For installation and dependency management

🚀 Quick Start
-------------

[](#-quick-start)

### 🛠️ Installation using Contao Manager

[](#️-installation-using-contao-manager)

The extension can easily be installed using the Contao Manager. Just search for the extension with keywords 'openai', 'openai-assistant', 'chatbot',...

### 🛠️ Installation using composer

[](#️-installation-using-composer)

For detailed installation instructions, see [docs/installation.md](docs/installation.md).

1. **Install the extension**:

```
composer require juhe-it-solutions/contao-openai-assistant
```

2. **Run migrations and clear cache**:

```
php bin/console contao:migrate
php bin/console cache:clear
```

3. **Configure in Contao backend**:

    - Go to **AI-TOOLS → OpenAI Dashboard**
    - Create OpenAI configuration with your API key
    - Upload knowledge base files
    - Create your first assistant
4. **Add to frontend**:

    - Create AI-Chatbot module in **Layout → Modules**
    - Add module to your page layout

📚 **For detailed documentation, see the [docs/](docs/) directory.**

### Manual Installation (Alternative)

[](#manual-installation-alternative)

If you prefer manual installation:

1. **Download the extension**:

```
git clone https://github.com/juhe-it-solutions/contao-openai-assistant.git
```

2. **Copy to your Contao installation**:

```
cp -r contao-openai-assistant vendor/juhe-it-solutions/contao-openai-assistant/
```

3. **Add to composer.json** (if not using Composer):

```
{
  "autoload": {
    "psr-4": {
      "JuheItSolutions\\ContaoOpenaiAssistant\\": "vendor/juhe-it-solutions/contao-openai-assistant/src/"
    }
  }
}
```

4. **Run migrations and clear cache**:

```
php bin/console contao:migrate
php bin/console cache:clear
```

🎯 How to Setup
--------------

[](#-how-to-setup)

### Prerequisites

[](#prerequisites)

Before setting up the extension, you need:

1. **OpenAI Account**: Create an account at [platform.openai.com](https://platform.openai.com)
2. **Create Project**: e.g. Chatbot for website xyz
3. **API Key**: Generate a secret key in your OpenAI project
4. **Assistants API Access**: Ensure your account has access to the Assistants API
5. **Contao 5.3+**: Ensure you're running Contao 5.3 or higher (recommended: Contao 5.5)

### Step-by-Step Setup Guide

[](#step-by-step-setup-guide)

#### 1. Backend Configuration

[](#1-backend-configuration)

After installing the extension via Contao Manager, you will see a new entry in your Contao backend main menu: **AI-TOOLS → OpenAI Dashboard**. Click on this link to access the configuration area.

##### 1a. Create OpenAI Configuration

[](#1a-create-openai-configuration)

- Click **"New configuration"**
- Enter your OpenAI API key/Secret key and press button "Validate key"
- Save the configuration
- The system will automatically validate your API key

##### 1b. Upload Knowledge Base Files

[](#1b-upload-knowledge-base-files)

- Click the **3rd icon "File Upload"**
- Click **"New file"**
- Choose files containing website-/company information or other data on which the OpenAI assistant should rely
- Supported formats: PDF, TXT, MD, DOCX, PPTX, JSON

##### 1c. Create OpenAI Assistant

[](#1c-create-openai-assistant)

- In the overview page, click the **4th icon "Assistants"**
- Click **"Create OpenAI Assistant"**
- Configure your assistant:
    - **Name and Description**: Give your assistant a meaningful name
    - **System Instructions**: Define how the assistant should behave and respond
    - **Model Selection**: Choose from all available OpenAI models (fast loading, validation on save)
    - **Parameters**: Adjust temperature, top\_p, and other settings as needed

#### 2. Frontend Module Configuration

[](#2-frontend-module-configuration)

##### 2a. Create AI Chat Module

[](#2a-create-ai-chat-module)

- Navigate to **Themes → Frontend Modules**
- Click **"New module"**
- Select module type **"AI tools → AI-Chatbot"**

##### 2b. Configure Chatbot Settings

[](#2b-configure-chatbot-settings)

- **Chat Position**: Choose widget position (bottom-right, bottom-left, etc.)
- **Initial State**: Collapsed or expanded
- **Theme**: Light or dark mode
- **Colors**: Customize all theme colors (background, text, buttons)
- **Font Size**: Adjustable base font size (12px to 20px)
- **Messages**: Set custom titles and welcome messages for the frontend chatbot

#### 3. Integration

[](#3-integration)

##### 3a. Page Layout Integration

[](#3a-page-layout-integration)

- Go to **Layout → Page Layout**
- Select your desired page layout
- Add the newly created AI-Chatbot module to the layout

##### 3b. Content Element Integration (Alternative)

[](#3b-content-element-integration-alternative)

- Create a new content element
- Choose "Module" as the element type
- Select your AI-Chatbot module

🔄 How It Works (Real-World Process)
-----------------------------------

[](#-how-it-works-real-world-process)

### Behind the Scenes

[](#behind-the-scenes)

When you configure the extension in Contao, the following happens automatically on the OpenAI platform:

#### 1. OpenAI Project Setup

[](#1-openai-project-setup)

- **Vector Store Creation**: A vector store is automatically created in your OpenAI project under "Storage"
- **File Processing**: Uploaded files are processed and stored in the vector store
- **Assistant Creation**: An OpenAI assistant is created in the "Assistants" section with your specified configuration

#### 2. Synchronization Process

[](#2-synchronization-process)

- **One-Way Sync**: All creations, edits, and deletions flow **from Contao backend to OpenAI platform**
- **Real-Time Updates**: Changes made in Contao are immediately reflected on platform.openai.com
- **Automatic Management**: The extension handles all API calls and platform interactions

#### 3. File Management

[](#3-file-management)

- **Upload Processing**: Files uploaded in Contao are automatically sent to OpenAI
- **Vector Store Integration**: Files are indexed and made available to your assistant
- **Knowledge Base**: The assistant can reference uploaded files when responding to users

#### 4. Assistant Configuration

[](#4-assistant-configuration)

- **System Instructions**: Your defined instructions are applied to the OpenAI assistant
- **Model Selection**: The chosen model is validated and configured on the platform
- **Parameters**: Temperature, top\_p, and other settings are applied

### Important Notes

[](#important-notes)

⚠️ **One-Way Synchronization**:

- Changes made in Contao backend → Automatically sync to OpenAI platform
- Changes made directly on platform.openai.com → **NOT** synced back to Contao
- Always make changes through the Contao backend for consistency

🔒 **Security**: 🌐 **Web Root Detection**:

- The bundle resolves file system paths using the configured Contao web directory parameter `%contao.web_dir%`.
- If `%contao.web_dir%` is absolute (e.g., `/var/www/project/public`), it is used directly. If it is relative (e.g., `public`), it will be prefixed with `%kernel.project_dir%`.
- This prevents "File not found" errors on instances with custom document roots.
- API keys are securely stored and encrypted
- All communications with OpenAI use HTTPS
- No sensitive data is logged or exposed

⚙️ Configuration
----------------

[](#️-configuration)

### API Key Management

[](#api-key-management)

The extension supports multiple methods for storing OpenAI API keys:

- **Environment Variables** (Recommended): Store keys in `.env.local` or system environment
- **Encrypted Database**: Fallback with AES-256-CBC encryption
- **Real-time Validation**: Keys validated with OpenAI on save

📖 **For detailed API key management, see [docs/security/api-key-management.md](docs/security/api-key-management.md)**

### Color Customization

[](#color-customization)

The extension supports full color customization for both light and dark themes:

- **Background Colors**: Primary and secondary backgrounds
- **Text Colors**: Primary and secondary text colors
- **Toggle Icon Colors**: Custom colors for the theme toggle button
- **Font Size**: Adjustable base font size (12px to 20px)

🎨 Frontend Features
-------------------

[](#-frontend-features)

### Chat Widget

[](#chat-widget)

The frontend chat widget provides:

- **Responsive Design**: Works on all device sizes
- **Theme Toggle**: Switch between light and dark themes
- **Minimize/Maximize**: Collapsible chat interface
- **Real-time Responses**: Live AI assistant responses
- **Message History**: Persistent conversation threads
- **Loading States**: Visual feedback during processing

### Accessibility

[](#accessibility)

- **ARIA Labels**: Screen reader support
- **Keyboard Navigation**: Full keyboard accessibility
- **Focus Management**: Proper focus handling
- **High Contrast**: Support for high contrast themes

🔧 API Endpoints
---------------

[](#-api-endpoints)

The extension provides several API endpoints:

- `POST /ai-chat/send` - Send a message to the assistant
- `GET /ai-chat/history` - Retrieve conversation history
- `GET /ai-chat/token` - Get CSRF token for requests
- `POST /contao/api-key-validate` - Validate OpenAI API key

🛡️ Security Features
--------------------

[](#️-security-features)

- **CSRF Protection**: All requests protected with CSRF tokens
- **API Key Encryption**: Secure storage of sensitive data
- **Environment Variables**: Support for secure API key storage via environment variables
- **Input Validation**: Comprehensive input sanitization
- **Rate Limiting**: Protection against abuse
- **Session Security**: Secure session management
- **Template Security**: Twig templates with automatic escaping
- **Asset Security**: Static asset loading with proper paths

### 🔐 API Key Security

[](#-api-key-security)

The extension supports multiple levels of API key security:

1. **Environment Variables** (Recommended) - Store keys in `.env.local` or system environment
2. **Encrypted Database Storage** - Fallback with AES-256-CBC encryption
3. **Real-time Validation** - API keys validated with OpenAI on save

📖 **For detailed security documentation, see [docs/security/api-key-management.md](docs/security/api-key-management.md)**

🗄️ Database Tables
------------------

[](#️-database-tables)

The extension creates three main database tables:

- **`tl_openai_config`**: Stores OpenAI API configurations
- **`tl_openai_assistants`**: Stores assistant configurations
- **`tl_openai_files`**: Stores uploaded file metadata

📚 Documentation
---------------

[](#-documentation)

Comprehensive documentation is available in the [docs/](docs/) directory:

- **[Installation Guide](docs/installation.md)** - Complete setup instructions
- **[OpenAI Setup](docs/configuration/openai-setup.md)** - API configuration guide
- **[Troubleshooting](docs/development/troubleshooting.md)** - Common issues and solutions
- **[Security](docs/security/encryption.md)** - Security features and encryption
- **[Model Selection](docs/technical/model-selection.md)** - AI model compatibility
- **[API Reference](docs/development/api-reference.md)** - Backend API endpoints
- **[Frontend Guide](docs/frontend/chatbot-module.md)** - Chatbot customization

🐛 Troubleshooting
-----------------

[](#-troubleshooting)

For detailed troubleshooting information, see [docs/development/troubleshooting.md](docs/development/troubleshooting.md).

### Quick Fixes

[](#quick-fixes)

1. **API Key Issues**: Check [OpenAI Setup Guide](docs/configuration/openai-setup.md)
2. **Model Problems**: See [Model Selection Guide](docs/technical/model-selection.md)
3. **Security Concerns**: Review [Security Documentation](docs/security/encryption.md)
4. **Frontend Issues**: Check [Frontend Guide](docs/frontend/chatbot-module.md)

🤝 Contributing
--------------

[](#-contributing)

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.

### Quick Start for Contributors

[](#quick-start-for-contributors)

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Add tests if applicable
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Submit a pull request

### Development Setup

[](#development-setup)

For local development:

```
# Clone the repository
git clone https://github.com/juhe-it-solutions/contao-openai-assistant.git

# Install dependencies
composer install

# Set up your Contao development environment
# Ensure you have a valid OpenAI API key for testing
```

📄 License
---------

[](#-license)

This extension is licensed under the LGPL-3.0-or-later license. See [LICENSE](LICENSE) for details.

Security
--------

[](#security)

If you discover a security vulnerability, please report it privately via email to \[\]. Do **not** open public issues for security problems.

Maintainers
-----------

[](#maintainers)

- [JUHE IT-solutions](https://github.com/juhe-it-solutions) –

🙏 Acknowledgments
-----------------

[](#-acknowledgments)

- **Contao Team**: For the excellent CMS framework
- **OpenAI**: For the powerful Assistants API
- **Community**: For feedback and contributions

---

**Note**: This extension requires a valid OpenAI API key with Assistants API access. Please ensure you comply with OpenAI's terms of service and usage policies.

###  Health Score

39

—

LowBetter than 86% of packages

Maintenance66

Regular maintenance activity

Popularity15

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity56

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 50% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~20 days

Recently: every ~40 days

Total

13

Last Release

70d ago

PHP version history (2 changes)1.0.0PHP >=8.1

v1.0.3PHP ^8.2

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/60215157?v=4)[Jürgen Herrnegger](/maintainers/jochi44)[@jochi44](https://github.com/jochi44)

---

Top Contributors

[![jochi44](https://avatars.githubusercontent.com/u/60215157?v=4)](https://github.com/jochi44 "jochi44 (2 commits)")[![zoglo](https://avatars.githubusercontent.com/u/55794780?v=4)](https://github.com/zoglo "zoglo (2 commits)")

---

Tags

chatbotcontaocontao-extensionopenaiaiopenaicontaochatbotassistant

###  Code Quality

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/juhe-it-solutions-contao-openai-assistant/health.svg)

```
[![Health](https://phpackages.com/badges/juhe-it-solutions-contao-openai-assistant/health.svg)](https://phpackages.com/packages/juhe-it-solutions-contao-openai-assistant)
```

###  Alternatives

[cognesy/instructor-php

The complete AI toolkit for PHP: unified LLM API, structured outputs, agents, and coding agent control

310107.9k1](/packages/cognesy-instructor-php)[symfony/ai-platform

PHP library for interacting with AI platform provider.

51927.7k136](/packages/symfony-ai-platform)[symfony/ai-agent

PHP library for building agentic applications.

30536.7k44](/packages/symfony-ai-agent)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)