NOTICE: This is a work in progress, it may contain content that is not in sync with latest released versions of Grav 1.7 or 1.8 beta
Grav 1.8 introduces significant improvements including PHP 8.3 requirement, updated dependencies, and a new safe upgrade system. Here are a few highlights:
IMPORTANT: Grav 1.8 requires PHP 8.3 or later version. This is a major change from Grav 1.7's PHP 7.3.6+ requirement. Always take a backup of your site and test the upgrade in a testing environment before upgrading your live site, or use 'safe-upgrade' which automatically creates a restorable snapshot of Grav core.
Issue: Custom plugins/themes using deprecated PHP features fail to work Solution: Update code to be PHP 8.3 compatible
Issue: Site breaks after upgrade due to removed cache drivers Solution:
apcu, memcached, redis, array, etc.) to their Symfony Cache equivalents during upgrade.filesystem cache to keep the site running.system.yaml cache configuration to the desired adapter for clarity:
system:
cache:
driver: apcu # instead of apc
# or
driver: memcached # instead of memcacheIssue: Custom logging code may break with Monolog 2.3/3.x Solution: Update logging calls:
// Old
$this->grav['log']->addInfo($message);
$this->grav['log']->addError($message);
...
// New (compatible with both Monolog 2.x and 3.x)
$this->grav['log']->info($message);
$this->grav['log']->error($message);
...Issue: Plugins or themes that ship their own vendor/ folder or composer.json and pin psr/log to an older 1.x release force Composer to install an incompatible version. This breaks Grav's Monolog 3 handler expectations and triggers errors like Return type must be compatible with Psr\Log\LoggerInterface.
Solution:
psr/log requirement from your extension, orreplace block to your composer.json:
"replace": {
"psr/log": "*"
}vendor/ directory after updating composer.json.bin/gpm preflight command surfaces this issue under PSR/log compatibility warnings—resolve them before upgrading.Issue: Errors due to removed system.umask_fix setting
Solution: Remove this setting from your system.yaml as it's been removed for security reasons
Grav 1.8 requires PHP 8.3 or later version. The recommended version is the latest PHP 8.4 release.
The following unsupported cache drivers have been removed. Supported adapters (APCu, Memcached, Redis, Array, Filesystem, etc.) are handled by Symfony Cache with the same names, and Grav falls back to filesystem if it cannot resolve a custom adapter:
APC (use apcu instead)WinCacheXCacheMemcache (use memcached instead)system.umask_fix setting removed for security reasonsGrav 1.8 introduces a comprehensive safe upgrade system:
Run compatibility checks before upgrading:
bin/grav preflightThe preflight command checks for:
The new upgrade system includes:
strict_mode.twig2_compat and strict_mode.twig3_compat settingsThe compatibility toggles rewrite a handful of Twig 1/2 constructs on the fly, but you should update templates permanently to avoid runtime transforms.
Loop guards: Replace legacy for loops with inline if guards ({% for page in collection if page.published %}) by filtering the sequence first.
{# Legacy #}
{% for page in collection if page.published %}
{{ page.title }}
{% endfor %}
{# Twig 3 friendly #}
{% for page in collection|filter(page => page.published) %}
{{ page.title }}
{% endfor %}spaceless and filter blocks: Twig 3 removed {% spaceless %} and {% filter %} blocks; switch them to {% apply %}.
{# Legacy #}
{% spaceless %}
<div>{{ content|raw }}</div>
{% endspaceless %}
{# Twig 3 #}
{% apply spaceless %}
<div>{{ content|raw }}</div>
{% endapply %}sameas test: Use is same as instead of is sameas.
{% if theme is same as('my-theme') %}replace filter signature: Twig 3 expects a map instead of two string arguments.
{{ title|replace({'_': ' '}) }}After fixing templates, disable system.strict_mode.twig2_compat and system.strict_mode.twig3_compat and clear the cache to confirm everything renders without the compatibility layer.
system:
strict_mode:
twig2_compat: true # Enable Twig 2 compatibility mode
twig3_compat: true # Enable Twig 3 compatibility modebin/grav preflight# Perform Grav safe upgrade
bin/gpm self-upgrade --safe
# Monitor for any issues
bin/grav logviewer# Backup first
bin/grav backup
# Run manual preflight checks
bin/gpm preflight
# Update all packages
bin/gpm update -f
# Update Grav with old upgrade system
bin/gpm self-upgrade --legacy
# Clear all cache
bin/grav clear-cache --all
# Check cache configuration
cat user/config/system.yaml | grep -A 5 cache:# Check log permissions
ls -la logs/
# Test logging
bin/grav log --level=debug# List all plugins
bin/plugin list
# Check for updates
bin/gpm update --list-only/recovery URL with recovery token# Recovery with prompt to pick from latest snapshots
bin/restore
# List snapshots
bin/restore list
# Rollback to previous snapshot version
bin/restore apply <version>
# Command Help
bin/restore -h
# Get recovery status
bin/restore recovery status
# Clear recovery status
bin/restore recovery clear1.8.0-beta.10) could miss dotfiles during safe upgrades. If you upgraded with those builds, double-check your project root for files such as .htaccess and re-run the latest safe-upgrade flow if anything is missing.1.8.0-beta.16 restores executable permissions on the bin/* scripts after upgrades. If CLI tools stop working (permission denied), run chmod +x bin/* to align with the expected state.1.8.0-beta.5 through beta.7 introduced new public YamlUpdater::get(), set(), and exists() helpers. Update any automation or plugins that interact with YAML updates to call these methods instead of relying on private internals.When reporting issues, include:
If upgrading a development site:
⚠️ Important: Always test upgrades in a staging environment before applying to production. The new safe upgrade system provides rollback capabilities, but prevention is better than recovery.
Found errors? Think you can improve this documentation? Simply click the Edit link at the top of the page, and then the icon on Github to make your changes.
Powered by Grav + with by Trilby Media.