Updating from 3.2 to 3.3
This page lists what is specific to the move from Thelia 3.2 to 3.3. The procedure itself (backup, Composer, database script, cache, assets, modules) is on Update; the steps below come on top of it. If you start from 3.1, apply Updating from 3.1 to 3.2 first.
Thelia 3.3 ships Symfony Messenger and the background jobs.
Nothing waits for a worker after the update: MESSENGER_TRANSPORT_DSN stays empty and every job
runs at once, as before, until you name a queue.
Symfony recipes
- The core requires
symfony/messenger. When Composer applies the Symfony recipe of that package instead of the Thelia one, it writesconfig/packages/messenger.yamland addsMESSENGER_TRANSPORT_DSN=doctrine://default?auto_setup=0to.env, and every mail then waits for a worker. Delete theconfig/packages/messenger.yamlthe Symfony recipe wrote: the core configures Messenger itself. Amessenger.yamlof your own, such as one that routes a module message, stays. Unless a worker runs, also delete that line, soasyncstays synchronous. - The Symfony recipe of
symfony/schedulerwritessrc/Schedule.php. Delete it too: the core declares its owntheliaschedule.
Queues and workers
- Going back from a queue to no queue leaves the jobs still waiting in
messenger_messages. Let a worker empty the queues before you emptyMESSENGER_TRANSPORT_DSN. - The core configures Messenger for the whole application: its serializer, its bus, its
failure_transportand the routing of its messages come before the configuration of the project. An application that already queued messages of its own (App\Message\…) gets aLogicExceptionon dispatch until their classes are listed in thethelia.messenger.allowed_message_classesparameter. A module message is accepted when it lives in the namespace of an active module and has a handler. - With a queue, the web servers and the workers must share
var/data-transfer/import/andvar/cache/export/, and a deployment must not empty them while jobs wait. See Running the workers. - On an AMQP queue, set
MESSENGER_HEAVY_TRANSPORT_DSN: otherwise the exports and imports share the queue ofasync, are read by its worker and tried again three times like its jobs.
Rights
- Launching an import from the back office takes the
UPDATEright onadmin.import;VIEWnow only shows the imports and their jobs. Review the profiles of the administrators who import. - The new screen Configuration > System > Background jobs answers to the resource
admin.configuration.background-jobs, which the update gives to no profile: grant it to the profiles that follow the jobs. Until then, only super-administrators see it.
Dependencies
- The core requires
doctrine/dbal ^4.2: a project or a module held on DBAL 3 moves to DBAL 4.
The database script
php local/setup/update.php runs setup/update/sql/3.3.0.sql. It creates the tables of the new
features (the AI layer, the queue table messenger_messages, sale units, delivery dates and
slots, postal code rules on delivery zones, payment parts), adds the rights and the settings they
need, and converts or completes some existing data:
- The promotional price of an order line becomes a
DECIMAL(16,6)on a shop that came from Thelia 2. Orders placed before the conversion keep the total of their invoice. - Missing country titles and the German titles of the four checkout steps are filled in. A title an administrator edited is kept.
- The availability, customer rating and price facets become visible on every category listing that already shows facets. A merchant who does not want one hides it in the "Filters" section of the category or of the template.
- The settings
shared_cache_mode(disabled) andshared_cache_ttlarrive. An update changes nothing until you set them: see Reverse proxy cache.
The AI layer
The AI layer stays off after the update: no model is called until an administrator adds a connection and a module declares a usage that needs it. See AI settings and MCP and Calling an AI model from a module.
- The script creates nine tables (
ai_connection,ai_model,ai_tier_assignment,ai_usage_setting,ai_usage_log,ai_budget_reservation,ai_tool_token,ai_tool_approval,ai_tool_call_log), the rightsadmin.configuration.aiandadmin.configuration.ai-mcp, and the settingsai_enabled,ai_monthly_cap,ai_eu_only,ai_log_retention_days,ai_mcp_enabled,ai_tool_approval_ttl_hoursandai_tool_token_max_days. A setting the shop already holds is left alone. - The core requires
symfony/ai-platform, the bridgessymfony/ai-anthropic-platform,symfony/ai-generic-platform,symfony/ai-mistral-platform,symfony/ai-ollama-platformandsymfony/ai-open-ai-platform(all^0.15),symfony/mcp-bundle(^0.15) andnyholm/psr7(^1.8). A project that pins one of them must allow these versions. - Composer may apply the Symfony recipes of these packages and write
config/packages/ai_*_platform.yamlandconfig/packages/mcp.yaml. They do no harm and you can delete them: the shop reads its connections from the database, and the core registers its own MCP server. - The MCP server on
/api/mcpis off (ai_mcp_enabledis0) until an administrator switches it on and creates tokens. If the shop is served on a host other thanurl_site, setTHELIA_MCP_ALLOWED_HOSTSto the host names the endpoint must accept. - The key of a connection is read from a
THELIA_AI_*_KEYorTHELIA_AI_*_TOKENvariable, or from the usual variable of the provider when the connection points at that provider's own address. A connection saved before with another variable name is refused. - The embedded price list no longer holds models the providers do not serve (13 Mistral names and
six OpenAI entries). A range or a usage that points at one keeps working from its row in
ai_model; choose another model when the provider says the model does not exist. Scaleway models are listed without the vendor prefix (llama-3.3-70b-instruct): choose the model again on a range that used a prefixed name. - OpenAI is now sent
store: false. A connection to the European region (https://eu.api.openai.com) needs dated model names such asgpt-5.4-nano-2026-03-17.
Back-office theme
The default-twig theme requires thelia/core ^3.3: update both together. The screens of the AI
layer, the background jobs and the new features ship with the theme.
Behaviour changes
- Returns on the front API. An order that does not exist, or a line that does not belong to the order, answers 422 instead of 400. A return on an order that is cancelled, refunded or not paid yet answers with a message that says so, where it used to say the return window had closed. A client that reads the status or the message follows.
- A loop given a
langargument that names no language throws anInvalidArgumentExceptioninstead of reading the language of the session. A template that passes a misspelled or removed language fails on its next render. - With
default_lang_without_translationset to0, the front loops andattr()no longer return the items and texts that have no translation in the requested language. - An import is one transaction. A row its rules refuse is reported and the import goes on. A row
the database cannot save cancels the whole import. The rows written stay locked until the end,
so run a large stock or price import outside trading hours. A listener of
IMPORT_BEGIN,IMPORT_FINISHEDorIMPORT_SUCCESSruns inside that transaction: what it writes is cancelled with the import, what it sends (a mail, a file, a job queued in the shop database) is not. - An uploaded import is checked by its content as well as its name. An archive is refused when it holds more than 1000 entries, more than 512 MB once extracted, a link, or a name outside its folder.
maintenance:purgealso deletes the failed jobs older than 30 days.- A combination saved with a new
ean_codethat is not a GTIN is refused: a 422 oneanCodefrom the admin API, a refused row from the stock import. Spaces and hyphens are removed. Codes already stored stay as they are until they change. - The name of a cached image rendition covers all its options, so each rendition is generated
again once, on its first request. The old files stay until
image-cache:clearorthelia:cache:clearempties the cache. - The messages
customer_account_createdandcustomer_account_changedno longer receive the customer's password. The templates of the default e-mail theme keep rendering without it. A template or a module that readspasswordfrom these messages gets nothing. - Delivery. An order whose delivery address was moved to another country, state, postal code or
city after the cart copied it is refused with
delivery-address-moveduntil the address is chosen again. A cart whose carrier the postal code rules of its zones refuse is refused when the order is placed. A zone without a rule takes every postal code, as before. - A mail written in the order history (
email_sent) is now recorded once the mail server has taken the mail. With a queue, that is the worker, later, and the author of the line issystem.
Exports and imports files
Exports, their archives and uploaded imports are created with mode 0640, in folders made with
mode 0770. A folder made before keeps its mode. When the web server and the workers run under two
users of one group, check var/data-transfer/import and the export folder of the cache, and give
them chmod 0770 if needed. Run any crontab or deployment script that exports or runs
maintenance:purge under the same system user as the web server, or under users that share a
group.
Mails and queues
- Send the mails of a module through
MailerFactory. It gives each mail an identifier that guards against a second delivery. A mail sent with the Symfony mailer directly carries none, and is sent again if the queue hands its job out a second time. - A failed job replayed from the back office and with
messenger:failed:retryat the same moment may be sent twice. Replay a job from one place at a time. - A Redis or AMQP queue is read by the workers as the shop's own. Whoever can write to it can send mails through the mail server of the shop and replay exports and imports. Keep such a server private.
For module and theme developers
The full list, with the exact signatures, is in the 3.3.0 section of
CHANGELOG.md. In short:
- Many services gain a constructor argument without a default:
ImportHandler,MailerFactory,ResourceService,CartGuard,OrderFacade,CheckoutSelectionProcessor,DeliveryModuleResourceBuilder,DeliveryModuleEligibilityChecker,CheckoutValidationService,Action\Module,Action\Customerand the return processors, among others. A module that builds one by hand passes the new argument. A module that reads it from the container has nothing to do. PostageEstimator::estimatePostageForCountry()andAreaDeliveryModuleQuery::findByCountryAndModule()take a last argument?string $zipCode = null. A class that overrides one declares it too.ExportHandler::export(),ImportHandler::import()andImportHandler::validateUpload()take a new optional last argument.AbstractArchiverimplements the newClosableArchiverInterface.ReservedSaleVisibilityhands over toProductVisibility. A subclass that overrode its methods declares aProductVisibilityRuleInterfaceinstead.CART_SET_PAYMENT_MODULEalso resets the stored payment method of the cart unless the event names one.- In the
default-twigtheme,ExportImportControlleris gone. Its routes are served byExportController,ImportController,DataTransferListController,ExportJobControllerandImportJobController. Three controllers (MailingSystemController,MessagePreviewController,PasswordResetController) take new constructor arguments. - In Flexy, the
Delivery,InvoiceandPaymentorganisms andCheckoutController::payAction()take new arguments. A child theme that overrides one declares them and passes them on. DELETE /api/admin/customers/{id}runs the same deletion as the back office and answers 409 for a customer who has orders, where it used to fail with a 500.