Upgrading to ElmapiCMS v3.1
This guide will help you upgrade from ElmapiCMS v3.0 to v3.1. This is a minor version update that includes significant new features and improvements while maintaining backward compatibility.
Overview
ElmapiCMS v3.1 introduces several major improvements:
- New Rich Text Editor: Complete replacement of TinyMCE with a modern Lexical-based editor
- App Settings Management: New centralized settings system for branding and configuration
- OpenAPI Documentation: Complete API documentation with Swagger UI
- Enhanced API Features: New parameters and improved functionality
- UI/UX Improvements: Better user experience and responsive design
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-by-Step Upgrade Process
Step 1: Download the New Files
Download the ElmapiCMS v3.1 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.1 versions:
app/Http/Controllers/Api/AssetController.php
app/Http/Controllers/Api/CollectionController.php
app/Http/Controllers/Api/ContentController.php
app/Http/Controllers/Api/OpenApiController.php
app/Http/Controllers/Api/ProjectController.php
app/Http/Controllers/ContentController.php
app/Http/Controllers/Settings/AppSettingsController.php
app/Http/Controllers/UserManagement/PermissionController.php
app/Http/Middleware/HandleInertiaRequests.php
app/Http/Resources/ContentEntryResource.php
app/Http/Resources/ProjectResource.php
app/Models/AppSetting.php
composer.json
composer.lock
config/openapi.php
database/factories/ProjectFactory.php
database/migrations/2025_08_08_120000_create_app_settings_table.php
package-lock.json
package.json
public/build/ //Replace all files in this folder
public/js/tinymce/ //Delete this folder
resources/data/project_templates.json
resources/js/app.tsx
resources/js/components/app-logo-icon.tsx
resources/js/components/app-logo.tsx
resources/js/components/editor/ //New folder
resources/js/components/editors/ //Delete this folder
resources/js/components/ui/relation-entries-table.tsx
resources/js/components/user-menu-content.tsx
resources/js/hooks/use-appearance.tsx
resources/js/layouts/settings/app-settings-layout.tsx
resources/js/pages/Collections/Fields/FieldFormModal.tsx
resources/js/pages/Content/ContentList.tsx
resources/js/pages/Content/Fields/RelationModal.tsx
resources/js/pages/Content/Fields/RichTextField.tsx
resources/js/pages/UserManagement/Permissions.tsx
resources/js/pages/auth/login.tsx
resources/js/pages/settings/app.tsx
resources/js/types/index.d.ts
resources/views/app.blade.php
resources/views/swagger-ui.blade.php
routes/api.php
routes/settings.php
tests/Feature/API/APIProjectTest.php
tests/Feature/PermissionAccess/PermissionsTest.phpStep 3: Update Database
Option 1: Run Migrations
php artisan migrateOption 2: Manually Create the Table
If you don't have terminal access, you can manually create the new table.
CREATE TABLE app_settings (
id INT AUTO_INCREMENT PRIMARY KEY,
app_name VARCHAR(255) NULL,
logo_file VARCHAR(255) NULL,
favicon_file VARCHAR(255) NULL,
created_at TIMESTAMP NULL,
updated_at TIMESTAMP NULL
);Step 4: Clear Application Cache (Optional)
If you don't see any changes, you can try to clear the application cache.
-
Delete cache files manually:
- Delete all files in
bootstrap/cache/(except.gitignore) - Delete all files in
storage/framework/cache/ - Delete all files in
storage/framework/views/
- Delete all files in
-
Clear cache with command:
php artisan optimize:clear
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.