Upgrading to ElmapiCMS v3.3

This guide will help you upgrade from ElmapiCMS v3.2 to v3.3. This is a minor version update that introduces AI-powered features and Admin API improvements while maintaining backward compatibility.

Overview

ElmapiCMS v3.3 introduces several major features:

AI Chat Assistant: A conversational AI assistant that can manage projects, collections, fields, and content entries directly from the sidebar panel
Inline AI Content Tools: Field-level AI actions including rewrite, expand, summarize, fix grammar, generate, and translate — available for text, longtext, and rich text fields
AI-Powered Entry Translation: Translate entire content entries to other locales using AI
Admin API: New REST API endpoints for managing collections and fields programmatically
Multi-Provider AI Support: Works with OpenAI (GPT), Anthropic (Claude), and Google Gemini

Important: Backup First!

Before making any changes, create a complete backup of your ElmapiCMS installation:

Backup your database
Backup your uploaded files (storage directory)
Backup your configuration file (.env)

Step 1: Download the New Files

Download the ElmapiCMS v3.3 files and extract them to a temporary folder. You'll need to replace several files and folders.

Step 2: Replace Updated Files

Replace the following files and folders with the new v3.3 versions:

.env.example
 
app/Ai/ (NEW — entire folder)
app/Http/Controllers/AiChatController.php (NEW)
app/Http/Controllers/Api/CollectionAdminController.php (NEW)
app/Http/Controllers/Api/FieldAdminController.php (NEW)
app/Http/Controllers/ContentAiController.php (NEW)
app/Http/Controllers/ContentController.php
app/Http/Controllers/Settings/AppSettingsController.php
app/Http/Middleware/HandleInertiaRequests.php
app/Http/Requests/ContentRequest.php
app/Models/AppSetting.php
app/Overrides/TextGenerationOptions.php (NEW)
app/Providers/AppServiceProvider.php
 
composer.json
composer.lock
config/ai.php (NEW)
 
database/migrations/2026_02_08_111023_create_agent_conversations_table.php (NEW)
database/migrations/2026_02_08_163855_add_ai_settings_to_app_settings_table.php (NEW)
 
package.json
package-lock.json
 
public/build/ (Replace all files in this folder)
 
resources/js/app.tsx
resources/js/components/ai-chat-panel.tsx (NEW)
resources/js/components/ai-field-button.tsx (NEW)
resources/js/components/app-shell.tsx
resources/js/components/app-sidebar-header.tsx
resources/js/components/app-sidebar.tsx
resources/js/components/editor/editor.tsx
resources/js/components/editor/plugins.tsx
resources/js/components/editor/plugins/ai-generate-plugin.tsx (NEW)
resources/js/components/editor/plugins/floating-text-format-plugin.tsx
resources/js/components/editor/plugins/toolbar/basic-toolbar.tsx
resources/js/components/ui/data-table.tsx
resources/js/components/ui/dropdown-menu.tsx
resources/js/contexts/content-ai-form-context.tsx (NEW)
resources/js/contexts/content-ai-usage-context.tsx (NEW)
resources/js/hooks/use-ai-chat.tsx (NEW)
resources/js/hooks/use-content-ai.ts (NEW)
resources/js/layouts/app/app-sidebar-layout.tsx
resources/js/layouts/settings/app-settings-layout.tsx
resources/js/pages/Collections/Fields/FieldFormModal.tsx
resources/js/pages/Content/ContentForm.tsx
resources/js/pages/Content/Fields/FieldBase.tsx
resources/js/pages/Content/Fields/LongTextField.tsx
resources/js/pages/Content/Fields/RichTextField.tsx
resources/js/pages/Content/Fields/TextField.tsx
resources/js/pages/Content/Fields/index.tsx
resources/js/pages/Projects/Settings/APIAccess.tsx
resources/js/pages/Projects/Show.tsx
resources/js/pages/dashboard.tsx
resources/js/pages/settings/ai.tsx (NEW)
resources/js/types/index.d.ts
 
routes/api.php
routes/settings.php
routes/web.php
 
stubs/agent.stub (NEW)
stubs/structured-agent.stub (NEW)
stubs/tool.stub (NEW)

Step 3: Install Dependencies

Install the new PHP dependencies (the laravel/ai package):

composer install

Then install the updated frontend dependencies:

npm install

If you don't have terminal access, upload the vendor/ folder from a local installation where you ran composer install.

Step 4: Update Environment Variables

Add the following optional variables to your .env file for AI provider API keys. You only need to add the key for the provider you plan to use:

OPENAI_API_KEY=
ANTHROPIC_API_KEY=
GEMINI_API_KEY=

Step 5: Update Database

Run the new migrations to add AI support tables and settings:

php artisan migrate

This will:

Create agent_conversations and agent_conversation_messages tables for the AI chat assistant
Add AI settings columns to the app_settings table (ai_enabled, ai_provider, ai_model, ai_show_token_usage, ai_max_conversation_messages, ai_max_tokens, ai_max_steps)
Add context column to agent_conversations for tracking project context across conversations

Manual Migration (If Needed)

If you don't have terminal access, you can manually run the SQL commands below.

For MySQL:

CREATE TABLE `agent_conversations` (
    `id` VARCHAR(36) NOT NULL,
    `user_id` BIGINT UNSIGNED NOT NULL,
    `title` VARCHAR(255) NOT NULL,
    `context` JSON NULL,
    `created_at` TIMESTAMP NULL,
    `updated_at` TIMESTAMP NULL,
    PRIMARY KEY (`id`),
    KEY `agent_conversations_user_id_updated_at_index` (`user_id`, `updated_at`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
 
CREATE TABLE `agent_conversation_messages` (
    `id` VARCHAR(36) NOT NULL,
    `conversation_id` VARCHAR(36) NOT NULL,
    `user_id` BIGINT UNSIGNED NOT NULL,
    `agent` VARCHAR(255) NOT NULL,
    `role` VARCHAR(25) NOT NULL,
    `content` TEXT NOT NULL,
    `attachments` TEXT NOT NULL,
    `tool_calls` TEXT NOT NULL,
    `tool_results` TEXT NOT NULL,
    `usage` TEXT NOT NULL,
    `meta` TEXT NOT NULL,
    `created_at` TIMESTAMP NULL,
    `updated_at` TIMESTAMP NULL,
    PRIMARY KEY (`id`),
    KEY `conversation_index` (`conversation_id`, `user_id`, `updated_at`),
    KEY `agent_conversation_messages_user_id_index` (`user_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
 
ALTER TABLE `app_settings` ADD COLUMN `ai_enabled` TINYINT(1) NOT NULL DEFAULT 0;
ALTER TABLE `app_settings` ADD COLUMN `ai_provider` VARCHAR(255) NOT NULL DEFAULT 'anthropic';
ALTER TABLE `app_settings` ADD COLUMN `ai_model` VARCHAR(255) NULL;
ALTER TABLE `app_settings` ADD COLUMN `ai_show_token_usage` TINYINT(1) NOT NULL DEFAULT 0;
ALTER TABLE `app_settings` ADD COLUMN `ai_max_conversation_messages` SMALLINT UNSIGNED NOT NULL DEFAULT 10;
ALTER TABLE `app_settings` ADD COLUMN `ai_max_tokens` INT UNSIGNED NOT NULL DEFAULT 4096;
ALTER TABLE `app_settings` ADD COLUMN `ai_max_steps` SMALLINT UNSIGNED NOT NULL DEFAULT 8;

For SQLite:

CREATE TABLE "agent_conversations" (
    "id" varchar(36) NOT NULL PRIMARY KEY,
    "user_id" integer NOT NULL,
    "title" varchar(255) NOT NULL,
    "context" text,
    "created_at" datetime,
    "updated_at" datetime
);
CREATE INDEX "agent_conversations_user_id_updated_at_index" ON "agent_conversations" ("user_id", "updated_at");
 
CREATE TABLE "agent_conversation_messages" (
    "id" varchar(36) NOT NULL PRIMARY KEY,
    "conversation_id" varchar(36) NOT NULL,
    "user_id" integer NOT NULL,
    "agent" varchar(255) NOT NULL,
    "role" varchar(25) NOT NULL,
    "content" text NOT NULL,
    "attachments" text NOT NULL,
    "tool_calls" text NOT NULL,
    "tool_results" text NOT NULL,
    "usage" text NOT NULL,
    "meta" text NOT NULL,
    "created_at" datetime,
    "updated_at" datetime
);
CREATE INDEX "conversation_index" ON "agent_conversation_messages" ("conversation_id", "user_id", "updated_at");
CREATE INDEX "agent_conversation_messages_user_id_index" ON "agent_conversation_messages" ("user_id");
 
ALTER TABLE "app_settings" ADD COLUMN "ai_enabled" tinyint(1) NOT NULL DEFAULT 0;
ALTER TABLE "app_settings" ADD COLUMN "ai_provider" varchar(255) NOT NULL DEFAULT 'anthropic';
ALTER TABLE "app_settings" ADD COLUMN "ai_model" varchar(255);
ALTER TABLE "app_settings" ADD COLUMN "ai_show_token_usage" tinyint(1) NOT NULL DEFAULT 0;
ALTER TABLE "app_settings" ADD COLUMN "ai_max_conversation_messages" integer NOT NULL DEFAULT 10;
ALTER TABLE "app_settings" ADD COLUMN "ai_max_tokens" integer NOT NULL DEFAULT 4096;
ALTER TABLE "app_settings" ADD COLUMN "ai_max_steps" integer NOT NULL DEFAULT 8;

Step 6: Enable AI Features (Optional)

AI features are disabled by default. To enable them:

Add your AI provider API key to the .env file (e.g., ANTHROPIC_API_KEY=sk-...)
Go to App Settings > AI in the admin panel
Toggle Enable AI Assistant on
Select your preferred AI provider and model
Configure additional settings (token usage display, max tokens, conversation length)

Step 7: Clear Application Cache

Clear all caches to ensure the new features work correctly:

php artisan optimize:clear

Or manually delete cache files:

Delete all files in bootstrap/cache/ (except .gitignore)
Delete all files in storage/framework/cache/
Delete all files in storage/framework/views/

New Features Guide

AI Chat Assistant

Once enabled, the AI assistant is accessible from the sparkle icon in the sidebar header. It can create projects, manage collections and fields, create and update content entries, and navigate you to the right pages.

Inline AI Content Tools

When editing content, text, longtext, and rich text fields display a sparkle icon with AI actions: Improve (with tone options), Fix Grammar, Expand, Summarize, Rewrite as..., Generate..., and Translate.

Admin API

New API endpoints for managing collections and fields programmatically. See the API documentation for details.

Support

If you encounter any issues, you can refer to the Troubleshooting Guide for help.

If you don't find your issue here, feel free to reach out via the channels described in the Getting Help & Support page.

Upgrading to ElmapiCMS v3.3

Upgrading to ElmapiCMS v3.3

Overview

Important: Backup First!

Step 1: Download the New Files

Step 2: Replace Updated Files

Step 3: Install Dependencies

Step 4: Update Environment Variables

Step 5: Update Database

Manual Migration (If Needed)

Step 6: Enable AI Features (Optional)

Step 7: Clear Application Cache

New Features Guide

AI Chat Assistant

Inline AI Content Tools

Admin API

Support

Search documentation