Updates & Maintenance

Overview

Keeping ValPress CMS updated is a critical task for ensuring the security, performance, and stability of your application. The update process involves the core CMS, plugins, and themes, each requiring a tailored approach. ValPress 0.6 introduces the Update Center — a staged verify/apply pipeline with transparent reports, snapshots, and repair actions for core, plugin, and theme updates.

Why It Matters

A well-maintained CMS is less vulnerable to security exploits and benefits from the latest performance optimizations and developer APIs. Updates also ensure compatibility with evolving infrastructure (e.g., new PHP versions) and third-party integrations. Without a structured update and maintenance strategy, sites risk data loss, broken functionality, and "White Screen of Death" (WSoD) scenarios during transition periods.

How It Works

ValPress follows a decoupled update architecture. While the core application resides in app/Core, user-specific content and extensions are stored in public/plugins, public/themes, and storage/. This separation allows the core to be replaced or patched without destroying site data.

New installations use the Web Installer downloaded from https://valpress.net. The installer is not used to update an existing site.

Existing installations use the Update Center (Admin > Updates). ValPress contacts api.valpress.net to check for updates, then runs a staged verify and apply pipeline with structured JSON reports, exportable logs, and optional file snapshots before core apply.

The admin UpdateController is a thin HTTP adapter — it validates request input, delegates to UpdateCheckService, UpdatePipeline, RepairService, and SnapshotService, and returns JSON for the Update Center UI. All verify and apply logic lives in pipeline stages and dedicated services under app/Update/, not in the controller.

The update lifecycle typically involves:

  1. Quiescing: Putting the application into maintenance mode.
  2. Verification: Downloading the update and running staged checks against an isolated copy on a dedicated test database.
  3. Synchronization: Replacing core or extension files with the verified release.
  4. Database Evolution: Running migrations to align the schema with the new code.
  5. Optimization: Re-caching routes, configurations, and views for the new environment.

Usage

Update Center (recommended)

For production sites managed through the admin panel, use Admin > Updates (Update Center). ValPress can:

  1. Check for core, plugin, and theme updates from the ValPress API
  2. Run compatibility checks (PHP, disk space, writable paths, and more)
  3. Verify the update in an isolated copy against a dedicated test database (configured under Settings → Test Database)
  4. Apply the update in stepped stages with maintenance mode and structured logs
  5. Create a core file snapshot before apply and restore from the Update Center if needed
  6. Suggest repair actions when checks fail (cache clears, plugin migrations, settings links)
  7. Update plugins and themes through the same pipeline from the Update Center or from the Plugins/Themes admin screens

Automatic update checks run daily when Enable automatic updates is on (Settings → General), and from the dashboard when no check has run in 24 hours.

Dismiss the dashboard update banner to hide it until new updates are detected.

See also (recommended reading order):

General Update Principles

Before any update, always perform the following steps:

  1. Backup: Export your database and archive the storage/, public/uploads/, and .env files.
  2. Maintenance Mode: Prevent user interaction during the update to avoid data corruption. 
    php artisan down --render=errors::503
  3. Review Release Notes: Check for breaking changes that might affect custom hooks or specific plugins.
  4. Configure a test database: Core verify requires a dedicated test database. Never point verification at your production database. See Testing.

Core Updates (Update Center)

  1. Log in to the ValPress Admin and open Updates.
  2. Click Check for Updates. ValPress queries api.valpress.net for core, plugin, and theme releases.
  3. Configure a dedicated test database under Settings → Test Database (required for verification).
  4. Run Verify Update. The pipeline steps through download, extract, migrations, PHPUnit, health checks, and extension compatibility. Review the stage report for each step.
  5. If verification succeeds, run Apply Update. Core apply creates a snapshot, copies files, runs migrations, rebuilds caches, and runs post-update verification.
  6. Export the report JSON if you need an audit trail (GET /admin/updates/export-report).
  7. Disable maintenance mode if it was enabled manually: 
    php artisan up

Note: The Web Installer is for new installations only. To update an existing site, always use the Update Center.

Core Updates (Developer / Source Deployments)

For sites deployed from a Git repository or managed with Composer on the server:

  1. Enter maintenance mode: php artisan down.
  2. Pull the latest changes or deploy the new release artifact.
  3. Update dependencies: composer install --no-dev --optimize-autoloader.
  4. Run migrations: php artisan migrate --force.
  5. Rebuild caches: php artisan config:cache && php artisan route:cache && php artisan view:cache.
  6. Exit maintenance mode: php artisan up.

Plugin & Theme Updates

From the Update Center or the Plugins / Themes admin screens:

  1. Check for updates and run Verify then Apply for the extension.
  2. The extension pipeline downloads, validates (ValidatesUpdate), migrates, and deploys to public/plugins/{slug} or public/themes/{slug}.

Manual replacement remains supported:

  1. Replace the directory in public/plugins/{slug} or public/themes/{slug}.
  2. If the plugin includes migrations, run them: php artisan migrate --force.
  3. Clear the view cache if the theme update modifies Blade files: php artisan view:clear.

Plugin and theme updates from the ValPress Marketplace are distributed as ZIP packages.

Code Examples

Implementing an Update Hook in a Plugin

Plugins can hook into the update process to perform data migrations or cleanup.

// In public/plugins/my-plugin/plugin.php

add_action('update_plugin_my-plugin', function ($old_version, $new_version) {
    if (version_compare($old_version, '2.0.0', '<')) {
        DB::table('my_plugin_settings')->update(['legacy_mode' => false]);
    }

    Log::info("MyPlugin updated from {$old_version} to {$new_version}");
});

Themes can use the symmetric update_theme_{slug} action with the same $old_version and $new_version arguments.

Both per-slug actions and the generic valpress_extension_updated action are fired from ExtensionUpdateService during the extension apply finalize stage.

Validating a Core Update from a Plugin or Theme

Extensions can block or warn on core updates by implementing ValidatesUpdate on src/Plugin.php or src/Theme.php. See Plugin Update Validation for the full contract, scaffold command, and reference example.

// public/plugins/my-plugin/src/Plugin.php

use App\Update\Contracts\ValidatesUpdate;
use App\Update\Pipeline\UpdateContext;
use App\Update\Reports\CheckResult;
use App\Update\Reports\RepairAction;
use App\Update\Reports\StageReport;
use Illuminate\Support\Facades\Schema;

class Plugin implements ValidatesUpdate
{
    public function validateUpdate(UpdateContext $context): StageReport
    {
        if (!Schema::hasTable('my_plugin_queue')) {
            return new StageReport(
                stage: 'my-plugin',
                status: StageReport::FAIL,
                label: 'My Plugin',
                checks: [
                    CheckResult::fail('queue_table', 'Queue table not found'),
                ],
                actions: [
                    RepairAction::route('Open plugin settings', 'admin.plugins.index'),
                ],
                message: 'Run plugin migrations before updating ValPress.',
            );
        }

        return new StageReport(
            stage: 'my-plugin',
            status: StageReport::PASS,
            label: 'My Plugin',
            checks: [
                CheckResult::pass('queue_table', 'Queue table exists'),
            ],
        );
    }
}

Scaffold a validator for an existing plugin:

php artisan vp:make-plugin-validation my-plugin

Automation via Deployment Script

A realistic deploy.sh for a ValPress production site deployed from source.

#!/bin/bash
set -e

echo "Starting ValPress update..."

php artisan down --secret="development-only-token"
git pull origin main
composer install --no-dev --optimize-autoloader --no-interaction
php artisan migrate --force
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan up

echo "Update complete!"

Advanced Usage

Semantic Versioning (SemVer)

ValPress core and official extensions strictly follow SemVer:

  • Major (x.0.0): Might contain breaking changes. Manual code review and theme adjustments may be required.
  • Minor (0.x.0): New features, fully backward compatible.
  • Patch (0.0.x): Bug fixes and security patches. Safe for automated updates.

Staging Environment Rollout

Never update production directly. Always test the update on a staging environment that mirrors production:

  1. Clone the production database to staging.
  2. Sync public/uploads and storage/.
  3. Apply the update and run automated tests (php artisan test).
  4. Smoke-test critical paths (Post creation, Admin login, API endpoints).

Test Database for Core Updates

Core verify requires a dedicated test database configured under Settings → Test Database. Settings keys: test_db_connection, test_db_host, test_db_database, test_db_username, test_db_password. TestingEnvironment blocks production database names during verification.

Best Practices

  • Use the Update Center for standard installations rather than manually replacing core files.
  • Use Version Control: Keep your entire project (minus vendor and .env) in Git for developer deployments.
  • Automate Migrations: Always use php artisan migrate --force in deployment scripts.
  • Monitor Logs: Check storage/logs/laravel.log and export Update Center reports after each run.
  • Use Snapshots: Let the pipeline create a core snapshot before apply; test restore on staging first.

Common Mistakes

  • Re-running the Web Installer on an existing site: The installer is for new installations. Use Admin > Updates.
  • Using the production database for verification: The verifier requires a separate test database. Pointing it at production risks data loss.
  • Ignoring extension validation failures: Active plugins and themes (including child + parent themes) can block core verify. Fix reported issues or use repair actions.
  • Skipping Backups: Always back up before apply, even when snapshots are enabled.
  • Direct Core Modification: Modifying files in app/Core will be overwritten on the next update. Use hooks instead.

Summary

Maintaining a ValPress installation requires a disciplined approach to backups, staging, and execution. New sites are installed with the Web Installer from https://valpress.net; existing sites are updated through the Update Center, which runs a transparent staged pipeline with test-database verification, snapshots, repair actions, and support for core, plugin, and theme updates. Always remember: Backup, Test, Migrate, and Cache.