Version Review and compatibility messages
Version Review is a migration tool for stores upgraded from a pre-10 version of CartThrob. It does not appear on a fresh CartThrob 10 installation. Open it at CartThrob → Version Review after the updater completes.
Legacy compatibility mode
During a pre-10 upgrade, CartThrob normally adds cartthrob_legacy_custom_js_checkout and cartthrob_legacy_download_sources to ExpressionEngine’s config.php with a value of true. While either setting remains enabled, that area uses its temporary legacy behavior and CartThrob displays the compatibility notice. Completing a scan or marking an item Reviewed does not disable legacy mode.
After resolving and testing the reported checkout and download issues, set both settings to false or remove them. The compatibility notice remains if either setting is still enabled; it disappears only after both are false or absent. Strict mode is then active, while Version Review remains available as an upgrade checklist.
The page evaluates CartThrob 10 rules even while a temporary checkout or download bridge is enabled. It does not edit templates, content, or configuration. Results are cached for up to 24 hours and refresh when inspected templates, settings, mapped values, or relevant extension registrations change.
Reading the overview
| Message or state | Meaning | What to do |
|---|---|---|
| Checking | The scan is still running. | Leave the page open or rerun the CLI check. Do not treat a partial result as approval. |
| Review items found | CartThrob found a definite migration or something it cannot prove safe automatically. | Open the area, use Details, make the change or complete the manual test, then rerun. |
| Enable strict mode now | A complete, current area scan found no unresolved relevant items. | Test the area, then set its bridge to false or remove the setting. CartThrob never changes it automatically. |
| Strict compatibility mode | Both temporary bridges are off or absent. | Resolve any remaining warnings and complete release testing. |
| Could not complete, stopped, storage unavailable, or more items need manual review | The scan is incomplete, capped, or could not save progress. | Follow the displayed repair/CLI instruction. An incomplete scan cannot establish readiness. |
| Reviewed | An administrator recorded a manual review, with member ID, date, and optional note. | Use this as checklist evidence only. It does not change runtime behavior or configuration. |
| Pass | The specific static item meets the rule the scanner could verify. | Still complete an end-to-end storefront test; a static pass cannot prove a provider, file, or extension works. |
Form Reviews
Standard native CartThrob forms already create the CartThrob 10 protection. Findings here focus on custom forms, ambiguous product scope, dynamic values, PHP, and extensions.
| Detail message | What it means | Resolution |
|---|---|---|
| Custom protected field needs updating | A template builds an internal CartThrob authority field by hand. | Move the controls into the matching native CartThrob form tag and remove the hand-built field. |
| Product tax or shipping setting needs updating | A multi-add form posts pNTX or pNSH. |
Remove the field; map Tax Exempt or Shipping Exempt in Product Channel settings and save the decision on the product. |
| Choose which product this form can add | A single add-to-cart form grants product-specific authority without trusted product scope. | Put entry_id on add_to_cart_form, or use on_the_fly="yes" for a genuine entry-less product. |
| List the products this form can add | A catalog multi-add form grants product-specific authority without a trusted product list. | Add server-rendered, pipe-delimited authorized_entry_ids containing exactly the displayed products. |
| Form parameter value needs review | A variable changes a protected product, shipping, gateway, member, or saved-payment setting. | Test every value the template can produce; prefer an explicit trusted value; then mark reviewed. |
| Custom template form needs review | External or custom syntax prevented reliable parsing. | Inspect the final HTML, confirm a native CartThrob form owns the action, and test it. |
| PHP-built form needs review | PHP can alter the form after static inspection. | Inspect every rendered variant and remove any code that manufactures or copies protected internal fields. |
| Form or cart extension needs review | A registered extension can alter form, cart, rate, Vault, checkout, or product behavior. | Review the callback, preserve the authenticated context, test every affected action, and record the result. |
| More extensions need manual review | The safe automatic scan limit was reached. | Review the remaining relevant ExpressionEngine extensions manually or use the complete CLI scan. |
See Updating custom forms for CartThrob 10 for contrasting old and new code.
Checkout Review
| Detail message | What it means | Resolution |
|---|---|---|
| Custom checkout JavaScript needs review | A selectable Stripe Payments, PayPal Standard, or PayPal Advanced path may prepare payment outside the built-in finalized-quote flow. | Finalize and submit the quote after the last cart/gateway change; test success, decline, and gateway switching. |
| Checkout parameter value needs review | A variable or PHP can change the gateway or checkout path. | Test every possible configuration, especially every selectable quote-required gateway. |
| Check this extension for pricing changes | A late checkout hook may change price, discounts, shipping, or tax after quote preparation. | Move quote-affecting work earlier or use deterministic cartthrob_checkout_quote_options; test the final provider and Order totals. |
| Hosted payment fields may be replaced unsafely | Template JavaScript appears to replace only gateway-field HTML. | Reload or rebuild the complete checkout when the gateway changes so provider state and handlers initialize together. |
| Cart update form needs manual review | Dynamic or incomplete template syntax prevented the scanner from pairing an update_cart_form with its closing tag. |
Inspect the rendered form for editable price, shipping, and weight fields; remove them or add the matching permission on that native tag. |
| CartThrob will ignore this editable cart value | The form posts editable price, shipping, or weight data without the corresponding allow_user_* permission. |
Remove the input or add the intentional allow_user_price, allow_user_shipping, or allow_user_weight parameter to that update_cart_form. |
| Subscription gateway capability is unknown | CartThrob cannot prove the selected gateway supports token creation and charging. | Verify the installed gateway implements both operations and test a sandbox subscription and renewal. |
| Gateway cannot process CartThrob subscriptions | The selected gateway lacks required token operations. | Select a supported subscription gateway or remove the subscription request. |
| Required checkout action is missing | An ExpressionEngine action used by quotes or hosted payment preparation is not registered. | Run the CartThrob updater, confirm the action exists, and rerun the review. |
| Checkout quotes cannot be signed | ExpressionEngine has no stable encryption key. | Configure a strong, stable encryption_key, clear caches, and rerun. |
The checkout bridge applies only to eligible upgraded forms rendered with custom_js="yes". It does not bypass amount, currency, ownership, duplicate-reference, quote-binding, or replay checks.
Download Review: tag results
For the complete setup and authorization model, see Downloadable products and CartThrob Download fieldtype.
The Tag Review checks get_download_link, download_file_form, and other detected download use. The Field Review checks stored values in configured fields.
| Result | Meaning | Resolution |
|---|---|---|
| Download tag passes the strict configuration check (Pass) | The identified field or static source is allowed by current strict configuration. | Test a real purchased download. A pass does not prove the file exists or the full access flow succeeds. |
| Download tag needs strict-mode configuration | It works through the temporary legacy bridge but its field, root, or origin is not approved for strict mode. | Approve the exact field/root/origin or move to an automatically allowed managed field. |
| Download tag cannot resolve its field | The short name is missing, unassigned, or wrong. | Correct the tag or field assignment, or remove an obsolete tag. |
| Download tag contains an unusable source | The static source is invalid, unreadable, malformed, or blocked in every mode. | Correct/restore the source or use a valid managed file; configuration cannot approve a broken value. |
| Download tag needs review | A variable, PHP, custom syntax, or incomplete parameters prevent exhaustive inspection. | Enumerate every possible field/path/URL, validate all of them, and test each rendered route. |
Download Review: detail messages
These findings explain why a tag or field could not receive a simple result.
| Detail message | Resolution |
|---|---|
| Referenced download field does not exist | Correct the short name/channel assignment or remove the obsolete tag. |
| More download fields need manual review | The automatic field cap was reached; run the complete CLI review or inspect every remaining field manually. |
| Download field storage could not be read | Repair the field/table storage problem, confirm both legacy and split field storage if applicable, and rerun. |
| Download field is not approved for strict mode | Move the value to an ExpressionEngine File or CartThrob Download field, or add only that exact channel/field ID to cartthrob_download_fields. |
| Download extension needs review | Review the registered download hook callback for source and authorization changes, test it, and record the manual result. |
| Download source is not allowed in strict mode | Use a managed file or add only the specifically reported root/origin required by the intended source. |
| Download field parameter needs review | Enumerate every short name a variable can produce and verify that each field is assigned and approved. |
| Download source parameter needs review | Enumerate every path/URL a variable can produce and validate every result; prefer a managed product field. |
| Custom template syntax needs review | Inspect the rendered tag/output because external syntax prevented reliable static parsing. |
| Managed download needs review | Confirm the file exists in File Manager. For remote adapters, complete a real entitled-customer download, then mark reviewed. |
Download Review: stored-value messages
| Detail message | Resolution |
|---|---|
| Two stored download values need review | Open the entry, choose the intended value, remove the conflicting stored value through the proper field or migration, and rescan. |
| Stored download value contains a template variable | Replace it with a specific managed-file reference, URL, or absolute local path. Stored field values are not parsed as templates. |
| Private or internal URL is blocked | Use a public download host or managed file. Adding an origin does not override private, loopback, link-local, metadata, or reserved-address blocking. |
| External download domain is not approved | Add the exact public HTTP(S) origin to cartthrob_download_origins, or move the file. |
| Local download path is outside the approved roots | Add the narrowest suitable parent directory to cartthrob_download_roots, or move the file to an approved/managed location. |
| Local development URL is blocked | For local development only, enable cartthrob_download_allow_local_site_url for this installation’s exact configured origin. |
| Local file is unavailable | Correct the path, restore the readable file, or replace it with a managed file. A root setting cannot make a missing file valid. |
| Managed file reference is unavailable | Select an existing ExpressionEngine file or replace the stale reference. |
| Download URL is malformed | Correct the HTTP(S) URL or use a managed file. |
| Download value has an unsupported format | Replace it with a supported managed-file reference, absolute local path, or HTTP(S) URL. |
| Download value does not meet strict-mode rules | Correct the stored value. Change configuration only when the specific result calls for a root, origin, or exact local-development exception. |
S means the value fails strict mode. S/L means it fails both strict and temporary legacy mode.
Installation Checks and other advisories
| Detail message | Resolution |
|---|---|
| Checkout CAPTCHA is not ready | Correct ExpressionEngine’s local CAPTCHA path/URL, writable directory, PHP GD, and incompatible reCAPTCHA settings; then complete a guest checkout test. |
| Compatibility progress cannot be saved | Restore a working ExpressionEngine cache driver and writable cache storage. |
| Compatibility review stopped unexpectedly | Check the developer log, repair the environment/database error, and rerun the complete review. |
| Order notification template is missing | Select an existing template or disable the unused notification, then verify a test notification. |
| Order Manager field mappings are incomplete | Map the listed Order fields and verify the affected reports. |
| PayPal Advanced currency needs review | Test the configured non-USD currency in the PayPal sandbox and compare provider and saved Order evidence. |
| Product tax or shipping exemption needs review | Inspect mapped product values and test taxable, shippable, and exempt products. |
| Equivalent country codes have conflicting shipping rules | Per Location Rates uses the first matching row. Consolidate equivalent-country rows or give the aliases the same rule, then test that destination. |
| Equivalent country codes have different shipping rules | Threshold shipping prioritizes an exact code. Confirm the difference is intentional or consolidate the aliases, then test that destination. |
| More exemption values need manual review | Inspect the mapped product exemption values beyond the automatic cap and test exempt/non-exempt products. |
| Product exemption values could not be read | Repair the mapped field storage, confirm its values, and rerun. |
Scanner and template-review messages
These can appear in more than one review area.
| Detail message | Resolution |
|---|---|
| Template PHP needs review / PHP-built form needs review | Inspect every rendered PHP branch, remove hand-built protected fields, and test each relevant form/download/checkout output. |
| Template exceeds the automatic review limit | Inspect the oversized template manually or split it into inspectable components, then record the review. |
| Template file could not be inspected | Restore read access and keep the file within the scanner limits, or inspect it manually. |
| File-based template directory is unavailable | Correct ExpressionEngine’s template-file path and permissions before relying on the scan. |
| More template fragments need manual review | Review the remaining snippets/global variables or use the complete CLI scan. |
| More extensions need manual review | Review every remaining relevant registration or use the complete CLI scan. |
| Custom template syntax needs review / Custom template form needs review | Inspect the final rendered output because the parser could not establish the tag/form behavior. |
| Compatibility progress cannot be saved | Restore the ExpressionEngine cache driver/storage and rerun; an unsaved scan cannot establish readiness. |
| Compatibility review stopped unexpectedly | Check the developer log, repair the environment/database error, and rerun the complete review. |
The required Compatibility review database tables check means the three review/evidence tables must exist. If it fails, run the CartThrob updater before trying to save manual reviews.
Configuration reference
Put public migration settings in ExpressionEngine’s system/user/config/config.php. For MSM, each bridge may be a site-ID map such as [1 => false, 2 => true]; an omitted site is strict.
The two cartthrob_legacy_* settings below are temporary upgrade bridges and intentionally do not appear in the normal configuration reference. The four durable download-policy settings are also documented in Configuration Overrides.
| Setting | Purpose |
|---|---|
cartthrob_legacy_custom_js_checkout |
Temporary upgraded-site bridge for eligible custom JavaScript checkout flows. Set false or remove after migration. |
cartthrob_legacy_download_sources |
Temporary upgraded-site bridge for eligible legacy download fields/sources. Set false or remove after migration. |
cartthrob_download_fields |
Strict allowlist in site → channel → field IDs form, or channel → field IDs on a single-site configuration. Native ExpressionEngine File and CartThrob Download fields are allowed automatically. |
cartthrob_download_roots |
Narrow absolute directories allowed for intentional raw local downloads. Do not approve the web root broadly. |
cartthrob_download_origins |
Exact allowed public HTTP(S) origins, including a nondefault port. This is not a wildcard or URL-prefix list. |
cartthrob_download_allow_local_site_url |
Local-development exception for this installation’s exact configured site origin. Leave disabled in normal production use. |
$config['cartthrob_legacy_custom_js_checkout'] = false;
$config['cartthrob_legacy_download_sources'] = false;
$config['cartthrob_download_fields'] = [
7 => [42, 43],
];
$config['cartthrob_download_roots'] = [
'/srv/private-downloads',
];
$config['cartthrob_download_origins'] = [
'https://downloads.example.com',
];
Do not copy or manufacture CartThrob’s internal upgrade-eligibility settings. They are maintained by the installer/updater and are not public configuration switches.