Upgrading from OJS 3.3 to 3.4 and 3.5: Handling Breaking Schema Changes
Deep-dive architectural guide on upgrading OJS from 3.3 LTS to 3.4 and 3.5. Details schema changes, email mailable templates, and modern PHP 8.2 requirements.
Real Problem
Many journals upgrading to OJS 3.4 experience fatal errors due to incompatible third-party plugins, changed email template variables, and deprecated database abstraction calls.
Practical Solution
Follow this architectural upgrade guide to transition from OJS 3.3 LTS to 3.4 and 3.5: audit third-party plugins, convert custom themes to modern hooks, and verify Laravel-style database migrations.
The Architectural Revolution in OJS 3.4 and 3.5
With the release of OJS 3.4 and the progression toward OJS 3.5, the Public Knowledge Project initiated the most radical modernization of the OJS core codebase in a decade.
Legacy components dating back to the platform’s origins—most notably the ADOdb database abstraction layer—were retired in favor of modern, enterprise PHP standards. OJS 3.4 incorporates components from the Laravel ecosystem, including Illuminate Database (Eloquent migrations and query builder) and Illuminate Mail.
Understanding the New Laravel Schema Migrations
In OJS 3.3 and earlier, database upgrades relied on XML schema definitions parsed by ADOdb (schema.xml). In OJS 3.4, upgrades are written as standard PHP migration classes utilizing Laravel’s schema blueprint.
During upgrade execution, OJS executes dozens of granular migration files located in classes/migration/upgrade/v3_4_0/. If any single table contains unexpected data types or invalid foreign key references, the migration halts with a standard Laravel QueryException.
Handling Breaking Email Template Refactoring
In OJS 3.3, editorial emails were stored in email_templates and email_templates_data, using static strings with {$variable} placeholders.
OJS 3.4 introduces the Mailable architecture:
- Email templates are now structured classes.
- Many legacy template keys were consolidated or renamed.
- Notification emails can now be queued in the database and processed by background worker daemons rather than synchronously delaying web requests.
Third-Party Plugin Compatibility Audit
Before executing an upgrade to OJS 3.4 or 3.5, every installed plugin must be audited. Any custom or third-party plugin written for OJS 3.3 that makes direct calls to DAORegistry or uses old ADOdb query methods will cause fatal errors.
Disable unverified plugins prior to upgrading:
UPDATE plugin_settings SET setting_value = '0' WHERE setting_name = 'enabled' AND plugin_name NOT IN ('defaultTheme', 'crossref', 'doi', 'customBlockManager');
Step-by-Step Upgrade Execution Protocol
1. Prepare a staging server running PHP 8.1 or 8.2 with MariaDB 10.6+ or MySQL 8.0.
2. Extract the clean OJS 3.4 tarball.
3. Copy your public/ folder and outside-webroot files_dir.
4. Migrate config.inc.php, taking note of new [queues] and [email] configuration parameters.
5. Execute the upgrade in your terminal:
php tools/upgrade.php upgrade
Step-by-Step Action Plan
Audit Third-Party Plugin Compatibility
Check PKP plugin gallery to verify that all active generic, theme, and gateway plugins have official 3.4/3.5 releases.
Upgrade Server Runtime to PHP 8.1 or 8.2
Configure PHP 8.1 or 8.2, as OJS 3.4 strictly drops support for PHP 7.x.
Inspect Schema Migration Dependencies
Verify that database user has full ALTER, CREATE, DROP, and INDEX privileges to run Laravel migration scripts.
Execute CLI Upgrade with Debugging
Run php tools/upgrade.php upgrade with show_stacktrace enabled to catch any breaking schema exceptions.
Reconfigure Mailable Templates & Queues
Review the newly introduced email templates and configure background queue workers if running high-volume editorial queues.
Questions People Usually Ask
What is the biggest architectural change between OJS 3.3 and 3.4?
OJS 3.4 replaced the historic ADOdb database abstraction layer with Laravel’s Illuminate Database and migration system. It also overhauled the email subsystem from static templates to modern Mailables.
Will custom OJS 3.3 themes work in OJS 3.4 without changes?
Not necessarily. While basic Smarty templates remain functional, many template hooks and submission data structures were refactored. Theme developers must update template variables to match OJS 3.4 publication objects.
Does OJS 3.4 support background job queues?
Yes! OJS 3.4 introduces native job queues for sending bulk notification emails, processing metrics, and executing Crossref deposits asynchronously without blocking editorial page requests.
Ready to Upgrade to OJS 3.4 or 3.5?
AcademiaTech ensures a seamless upgrade to the latest OJS generation with complete plugin compatibility audits and zero editorial interruption.