Upgrading PrestaShop is essential for security and performance, but custom code can easily turn a smooth migration into a site-breaking headache. Before hitting the upgrade button, performing a thorough audit of your overrides, custom modules, and theme modifications is critical to prevent unexpected downtime.
This guide walks you through a step-by-step framework to identify incompatible code, review deprecated functions, and test safely before launching. By auditing your codebase early, you protect your revenue, preserve custom functionality, and ensure a seamless transition to the latest version.
Why a PrestaShop Upgrade Audit Saves Your Store
Auditing custom code before a PrestaShop upgrade means inventorying every override, custom module, theme change and core file edit, then testing each one against the new PrestaShop and PHP versions in a staging copy. Skip that work and you are gambling your checkout on code nobody has looked at in years.
Failures rarely announce themselves politely. A module hooking into the order confirmation page stops rendering. An override in /override/classes/ returns a fatal error because a parent method signature changed. The front office shows a blank page while the back office still works, so nobody notices until a customer emails asking why their basket will not empty.
The financial exposure is not theoretical. Industry downtime research shows that a large majority of organisations report a single hour of downtime costing hundreds of thousands of dollars. Every hour offline during a seasonal promotion is orders you never recover, because buyers do not wait, they go to a competitor and often stay there.
A structured audit costs planned developer hours, a staging environment and a rollback plan. An emergency fix costs the same developer at out-of-hours rates, plus lost revenue, plus the reputational damage of a checkout that failed on a Saturday. One is a line item. The other is a crisis.
What you are protecting during a PrestaShop upgrade audit:
- Overrides in
/override/that silently replace core classes and break when core logic shifts - Custom and third-party modules whose hooks, controllers or templates no longer match the new architecture
- Theme template files copied from a default theme, which lose compatibility faster than the theme itself
- Direct edits to core files, which an upgrade will overwrite without warning
- Database structure changes made by modules that a new schema may reject
Each item is a place where a five-minute check now prevents a five-hour outage later. A PrestaShop upgrade is rarely just a click of an "Upgrade" button, and the rest of this guide covers the audit itself, the compatibility fixes that follow, and the modules that reduce how much custom code you carry in the first place.
An audit is cheap insurance: a couple of hours of inspection now versus an unknown bill and lost orders later.
Why PrestaShop Upgrades Break Customisations
PrestaShop's core evolves between versions, and anything that hooks into that core has to move with it. Custom code written for an older version does not automatically appreciate what changed beneath it. The most fragile areas are:
- Overrides which replace core classes and break when a method signature or path changes.
- Modules, especially those abandoned by their developer or written for an older version.
- Theme templates which reference Smarty variables and hooks that may be renamed or removed.
- Database tweaks such as custom tables populated by a module that no longer installs cleanly.
Each of these is discoverable before you touch the production store. That is the whole point of an audit: surface the risk while you still control the clock.
Quick Answer
To audit custom code before a PrestaShop upgrade, inventory every override, module and theme file against a staging copy of the store, test the target PrestaShop version there, and only promote to production once checkout, payments and catalogue behaviour pass.
What You'll Need
Assemble these before you start, because an audit that stalls halfway leaves you with a half-tested store and no clear baseline.
- Access: Back Office administrator rights with permission to install and configure modules, plus SSH or SFTP access to the server file system for the manual method.
- Environment: A staging clone of the store on separate hosting or a subdomain, with its own copy of the database, never the live one.
- Backups: A current database dump and an archive of /modules/themes and /override taken before anything is touched.
- Target versions: A written decision on the PrestaShop version and PHP version you are moving to, so compatibility checks have something to test against.
- Time: Roughly two to four hours for a store with a dozen modules and light customisation, spread over two sessions so you can re-scan after fixes.
- Difficulty: Moderate for the plugin method if you can install a module and read a report; more advanced for the manual method since it involves directory comparison and SQL queries.
How Do I Audit Custom Code Before Upgrading PrestaShop?
Work through the four stages below in order. Do not skip the staging clone, even if your customisation list looks short.
Step 1: Build a Complete Inventory of Customisations
You cannot audit what you cannot see, and most stores have forgotten half of what was bolted on over the years. Start by listing every piece of custom code before you open a single upgrade tool:
- Check /override/ in your PrestaShop root for any files that shadow core classes.
- Review the Modules list in the back office and note which are third-party, inactive, or unmaintained.
- Compare your active theme folder against a clean copy of the default theme to spot edited templates.
- Search your codebase for hardcoded hook registrations and direct database table references.
Record each item in a spreadsheet with its purpose, developer and last update date. You should now have a written list you can hand to anyone on the team.
Tip: If you cannot explain what a customisation does, treat it as risky until proven otherwise. It is safer to remove an unknown than to carry it through an upgrade.
Step 2: Check Compatibility Against Your Target Version
Once you know what is installed, you can test whether each piece survives the jump. This step prevents the classic scenario where a module silently stops working and you only notice when a customer emails about a broken checkout.
For each item on your inventory list:
- Confirm the module declares support for your target PrestaShop version.
- Check whether the module's developer has published updates or a changelog.
- Flag any module that has not been updated in a long period for a closer look.
- Note overrides that reference core methods likely to have changed between versions.
Sort your list into three buckets: safe, needs an update, and needs replacement. You should now see clearly where the money and time will actually go. When a module needs replacing, PrestaShop modules from an official PrestaShop Partner are worth prioritising, because official partners build specifically for the platform and maintain compatibility as versions advance.
Step 3: Clone to Staging and Run the Upgrade There
Testing on production is how a controlled upgrade turns into an outage. A staging clone lets you fail safely, repeatedly, and without a single customer noticing:
- Clone your live files and database to a separate environment.
- Point the staging store at a copy of your database, never the live one.
- Disable outgoing emails or payment gateways so no real order or notification fires.
- Run the upgrade on the staging clone.
Watch the process for fatal errors, and capture any that appear. You should now have a staging store running the target version with your customisations in place.
Warning: Never run an untested upgrade directly on the live store. If the staging run fails, you lose nothing but time.
Step 4: Test Critical Journeys and Log Every Failure
An upgrade that "completes" is not the same as an upgrade that works. You have to walk the customer's path yourself to know the store still sells. Test these flows on staging:
- Add a product to the cart and complete checkout.
- Process a payment in the sandbox or test mode of your gateway.
- Confirm order confirmation emails are generated (re-enable email in a safe test inbox first).
- Load product, category and account pages for layout or template errors.
- Trigger any custom functionality, such as a quote form or a bespoke shipping calculator.
Log every failure with a screenshot and the URL where it occurred. You should now have a prioritised defect list rather than a vague feeling that something might be wrong.
Method 1: Use Our PrestaShop Upgrade Audit Plugin
Manual code review works, but it is slow, and it depends on one developer remembering to check every override they ever shipped. FME Modules builds PrestaShop modules for stores that need exactly this kind of pre-upgrade visibility, and an audit module turns a week of guesswork into a report you can read in an afternoon.
The principle is straightforward: point the module at your installation, let it crawl the file system and database, then review what it found before you touch the upgrade button.
Step 1: Install the Audit Module on a Staging Copy
Never run a compatibility scan against your live store first. A staging copy gives you a safe place to trigger the audit, compare results, and roll back without affecting customer orders.
Take a full backup of the database and the /modules/themes and /override directories, then restore that backup onto your staging environment. In the PrestaShop Back Office, go to Modules -> Module Manager, upload the audit module archive, and click Install.
You should now see the audit module listed among your installed modules with a Configure button beside it.
Warning: If your staging store shares a database with production, stop and fix that first. An audit that writes to live tables can corrupt order data.
Step 2: Run the Compatibility Scan
The scan walks your installation and records everything that deviates from a clean PrestaShop release. Click Configure on the module, then select Run Audit or the equivalent scan action. The module typically inspects:
- Core overrides in /overridelisting each class that has been modified and flagging ones that conflict with the new PrestaShop version.
- Installed modules with a compatibility rating against your target PrestaShop version, so you can see which third-party modules have no confirmed release yet.
- Theme files, including .tpl templates and asset references, to catch customisations that will break when template structure changes.
- Core file modifications, meaning any file in the PrestaShop core that no longer matches the original release checksum.
You should now see a scan progress indicator, followed by a summary of findings grouped by category.
Tip: Run the scan once before any changes and once again after you update a module. The difference between the two reports tells you whether a vendor fixed their compatibility gap.
Step 3: Read the Compatibility Report
A raw list of flagged files is not useful on its own. What matters is which findings actually block your upgrade and which are cosmetic.
Open the Report or Audit Results tab. Each finding should show the affected file or module, the type of conflict, and a severity level. Sort by severity so critical overrides appear first. Cross-reference the module list against the vendor release notes for your target PrestaShop version, and mark anything without a confirmed compatible release as a blocker.
You should now see a prioritised list you can hand to a developer or work through yourself, section by section.
Step 4: Plan the Fixes and Re-Scan
For each flagged item, decide on one of three routes: update the module to a compatible release, refactor the override so it no longer clashes with core changes, or remove the customisation entirely if it is no longer needed. Record the decision next to each finding so nothing gets lost between the audit and the upgrade window.
You should now see a shorter findings list after re-running the scan, confirming that your fixes removed the conflicts you intended to remove.
Tip: Schedule the upgrade immediately after the re-scan comes back clean. Findings drift as soon as someone installs another module or edits a template.
Method 2: Manual Code Audit with File and Database Checks
Some merchants prefer not to install an auditing module and would rather inspect the store by hand. That approach works, but it is slower and relies entirely on your own discipline: every file you forget to check is a file that can break the shop on upgrade day.
Before touching anything, take a full backup of both the database and the file system, and clone the store to a staging environment. Treat the audit as forensic work: you are reconstructing what has been changed since the original installation, because PrestaShop cannot tell you that on its own.
Warning: Code changes made during a manual audit belong on the staging clone only. Working on live files without a verified backup can take the storefront offline with no way back.
Step 1: Inventory the /override Directory
The /override directory is the single most important place to start, because it tells you which core classes and controllers your shop has replaced with its own versions.
Connect to your server and list the contents recursively, then compare what you find against a clean PrestaShop package of the same version:
- Look inside /override/classes for rewritten core classes, such as Cart.php or Product.php.
- Look inside /override/controllers for both front and admin overrides.
- Check /override/modules if any module has shipped a core file replacement.
- Record each file's path and the original class it extends, so you have a written list.
PrestaShop regenerates a merged cache from these files, so an override can fail silently until the cache is cleared. You should now have a documented list of every core file your store has replaced.
Warning: Never test override removal directly on the live shop. A broken override typically produces a fatal error that takes the storefront offline immediately.
Step 2: Compare Core Files Against a Clean Package
Overrides are the visible modifications; direct edits to core files are the hidden ones, and they are the most dangerous because a PrestaShop upgrade overwrites them without warning.
Download a clean copy of the PrestaShop version you are currently running, then run a directory comparison between your store and the clean package. Any file that differs but does not belong to a third-party module is a candidate for investigation:
- Compare the /classes/controllers and /src directories first.
- Flag differences in /themes separately, since template edits are usually intentional.
- Document what each change does and whether a module or override could achieve the same result instead.
- Migrate legitimate changes into an override or a custom module, so future upgrades leave them intact.
You should now be able to say, with evidence, which files are non-standard and why.
Step 3: Check Module Hook Registrations
Modules attach themselves to hook positions, and a hook that no longer exists in the target PrestaShop version will simply stop firing, which can remove a payment option or a checkout block without any error message.
Run a query against the hook and hook_module tables to list which modules are registered where, then compare that list against the hooks available in the version you plan to move to. Pay particular attention to hooks used by payment, shipping, and checkout modules, since these sit directly in the order path.
You should now have a table of module-to-hook relationships and a shortlist of registrations that will need attention after the upgrade.
Step 4: Review Database Schema Dependencies
Custom modules often add their own tables or extra columns, and tables that duplicate core data are a common source of upgrade failures when the core schema changes.
Export the database structure and look for tables you do not recognise, especially ones absent from a clean installation. For each one, check:
- Whether it stores configuration values that could live in the core configuration table instead.
- Whether it duplicates data already held in productorders or customer.
- Whether its columns reference core column names that may be renamed or dropped.
- Whether an index or foreign key would block a schema migration during the upgrade.
You should now know exactly which custom tables must be preserved, which can be retired, and which need adjusting before the upgrade runs. Once the manual audit is complete, a purpose-built auditing module can automate the same checks on future upgrades.
Troubleshooting: Common Audit Findings and How to Fix Them
An audit rarely comes back clean. What matters is how quickly you can turn each finding into a decision: rewrite it, isolate it, or roll back. Below are the four problems that surface most often, with a practical response for each.
Deprecated or removed PHP functions in theme templates
Old themes tend to carry logic that newer PHP versions no longer accept. If create_function(), curly-brace string offsets, or each() appear in your templates, the store will throw fatal errors the moment PHP moves on. This is usually the single biggest reason an upgrade stalls.
- Flag every occurrence with the PHP version it breaks under, so you know the minimum target before you start.
- If a function is removed rather than deprecated, its replacement may behave differently, so test the rewritten template on a staging copy before pushing live.
- Rewrite each finding individually. Bulk search-and-replace across templates introduces silent breakage that only shows up when a customer hits that page.
Treat the list as a work queue rather than a single fix. Assign each item an owner and a target PrestaShop version, then check them off as the staging store runs without errors.
Conflicting overrides and duplicate modules
PrestaShop's override system lets a module replace a core method. Two modules overriding the same class is a common cause of a store that behaves correctly on the surface but fails unpredictably at checkout.
- List every file under the theme's template overrides and the module overrides directory, then group by the class each one touches.
- Where two modules touch the same class, decide which one genuinely needs the override and disable the other.
- Check for modules installed more than once under slightly different names. Duplicates load twice and cause strange front-office symptoms.
Document the decision for each conflict rather than deleting silently. A note in your audit sheet saves hours when the same question returns six months later.
Missing or changed hooks in custom code
Custom modules and template tweaks often attach to hooks by name. When a hook is renamed, deprecated, or moved in a newer PrestaShop release, the attached code simply stops running. Nothing errors, which makes this finding easy to miss.
| Finding | What It Means | Practical Fix |
|---|---|---|
| Hook no longer registered | Custom logic never fires, so a feature quietly disappears | Re-register the hook or move the logic to the current equivalent |
| Hook exists, but position changed | Output renders in the wrong place on the page | Adjust the hook position in the theme, then check the affected template |
| Module registers a removed hook | Installation warnings or a module that loads but does nothing | Update the module or replace it before upgrading |
Test each hook-dependent feature on staging by triggering the page it controls. A feature that was never reachable during normal browsing can hide a broken hook for months.
A theme built for an older PrestaShop version
Themes age faster than modules. A theme written for an earlier major release can look fine but rely on templates, asset paths, or a structure that no longer matches the core. Patching it piecemeal often costs more than a rebuild.
- Compare the theme's template folder against the current default theme to see which files diverge.
- Assess whether the customisation is cosmetic or structural. Cosmetic changes are portable; structural ones usually are not.
- Set a fixed decision point in advance: if more than a small proportion of templates need rewriting, plan a rebuild instead of an endless patch cycle.
A theme that needs constant patching during an upgrade is usually telling you the rebuild is the cheaper option.
If your store also depends on custom modules, the same principle applies. A PrestaShop module built against an outdated core will keep generating findings until it is updated or replaced, so treat module compatibility as part of the same audit.
Work through findings in this order: deprecated code first, because it blocks everything else; conflicts second, because they distort your tests; hooks third; theme last, since it depends on the other three being stable. Record each fix in the audit sheet so the next upgrade starts from a known baseline.
Conclusion
By the end of a completed audit, you have a written inventory of every override, module and theme edit, a staging store running your target version without fatal errors, and a defect list you have already worked through. The upgrade itself becomes a scheduled task rather than an emergency, because the risks were surfaced while you still controlled the clock.
Start with the plugin route on a staging copy, re-scan until the findings list comes back clean, and only then touch production.