Upgrade PagibleAI CMS

PagibleAI CMS adheres to MAJOR.MINOR.PATCH semantic versioning (SemVer) for clear, predictable updates. MAJOR releases introduce breaking changes, MINOR releases add backward-compatible features (e.g., from 1.1.x to 1.2.x), and PATCH releases provide backward-compatible bug and security fixes. Each minor release is actively supported until the next minor release is published.

Users are strongly encouraged to keep their installations updated with the latest patch releases for security and critical fixes. For detailed changes, refer to the release notes.

Upgrade Guide

To upgrade your PagibleAI CMS installation between major/minor versions, follow these general steps:

  1. Run composer update in your project's root directory.
  2. Run php artisan migrate to apply any database schema changes.
  3. Carefully check your configuration files for any newly added lines or changes. It is recommended to compare your config/cms.php file with the original provided in the new release.
  4. If you have customized any vendor templates in ./resources/views/vendor/cms/, compare your overwritten templates to the original ones to ensure compatibility and merge any necessary updates.
  5. Similarly, compare the CSS and JavaScript files located in ./public/vendor/cms/theme/ to the original files from the new release and merge any changes as required.
  6. Check the release notes for breaking changes.

Important Changes

0.10.x -> 0.11.x

  • AI engine: The AI integration has been migrated from prism-php/prism to the aimeos/prisma library, and aimeos/pagible-mcp is now a required dependency (it was previously only suggested). Run composer update to pull in the new packages
  • GraphQL CSRF protection: The GraphQL API endpoint is now protected against cross-site request forgery. Re-run php artisan cms:install after updating to add the ValidateCsrfToken middleware to your config/lighthouse.php — the installer is idempotent and only inserts the middleware when it is missing
  • AI default models removed: The hard-coded default models (e.g. gemini-2.5-flash, whisper-1) have been removed from config/cms/ai.php. The CMS now uses each provider's own default model unless you set the corresponding CMS_AI_*_MODEL environment variable
  • Refine provider default: The refine operation now defaults to the OpenAI provider instead of Gemini. Set CMS_AI_REFINE=gemini in your .env file to keep the previous behavior
  • Schema configuration removed: The config/cms/schemas.php file has been removed. Content element schemas are now loaded from schema.json files. If you customized config/cms/schemas.php, migrate your changes to the corresponding schema.json files
  • Template slots renamed: The Blade asset stacks have been renamed to match their semantics: css is now head and js is now foot. Update any custom themes or templates using @push('css')/@stack('css') and @push('js')/@stack('js') to @push('head')/@stack('head') and @push('foot')/@stack('foot')
  • Themes moved to separate packages: The default theme is now a new, clean theme shipped in aimeos/pagible-theme. The previous design is available as a separate package aimeos/pagible-themes-pagible, alongside aimeos/pagible-themes-glass, aimeos/pagible-themes-paper and aimeos/pagible-themes-premium. Require the theme package you want to use
  • Theme CSS split: Below-the-fold styles have been moved to a new cms-lazy.css file. If you customized the theme CSS in ./public/vendor/cms/theme/, re-publish the assets and merge your changes into both cms.css and cms-lazy.css
  • Removed page section config: The cms.config block defining theme page types and sections has been removed from config/cms.php. Page section configuration is now provided by the theme packages

0.9.x -> 0.10.x

  • Permissions: The cmseditor boolean column has been replaced by a cmsperms JSON column supporting named roles (admin, editor, publisher, viewer). Run php artisan migrate to apply the migration which automatically converts existing permissions
  • Configuration renamed: cms.menu_maxdepth has been renamed to cms.navdepth and the environment variable changed from CMS_MENU_MAXDEPTH to CMS_NAVDEPTH. Also, cms.config.locales has been moved to cms.locales and is now driven by the CMS_LOCALES environment variable
  • Configuration split: The schemas section has been moved from config/cms.php into a separate config/cms/schemas.php file. If you have customized schemas, move them to the new file
  • Admin proxy configuration: The proxy config keys in config/cms/admin.php have been renamed: max-length is now maxsize and stream_timeout is now timeout. Update your .env file accordingly: CMS_PROXY_MAX_LENGTH → CMS_PROXY_MAXSIZE and CMS_PROXY_STREAM_TIMEOUT → CMS_PROXY_TIMEOUT
  • Vendor publish tag: The publish tags have changed to cms-admin, cms-config, cms-graphql and cms-theme. Use php artisan vendor:publish --tag=cms-admin tag=cms-config tag=cms-graphql tag=cms-theme to republish the admin configuration
  • Search parameter: The frontend search query parameter has been renamed from search to q. Update any custom search forms or links accordingly

0.8.x -> 0.9.x

  • UUID: The pages now use UUID values as IDs and you have to execute php artisan migrate to change the database schema and update the records
  • Configuration: The AI provider configuration has changed including the names for the keys in the .env file. Please update your ./config/cms.php file