Skip to main content
Version: Thelia 3

Breaking changes

This page lists, release by release, what a module or a theme has to change when it moves to a new Thelia 3 version. It covers constructors you instantiate yourself, methods that changed contract, and behaviors a module may have relied on. Changes that need no action from you are in the CHANGELOG.

For the update procedure itself, see Update.

Thelia 3.4​

These changes ship in a minor release, which departs from the compatibility promise. They correct a price or a stock calculation, or close an access that the promise should not protect. No official module or theme depends on them. The exact signatures are in the "Breaking changes" of CHANGELOG.md, and UPGRADE-3.4.md says what to do for each entry. The update gestures are in Updating from 3.3 to 3.4.

Constructors and signatures​

Many services take new constructor arguments, with no default (price lists, customer groups, stock reservation, product bundles, express payment). A module that builds one by hand passes them; a module that reads the service from the container has nothing to do. A subclass that overrides a method which gained an optional argument declares it too: Action\Cart::refreshCartItemPrices() (bool $bundleLinesOnly = false), ReservedSaleProductRule::visibleProductClause() (bool $defaultVisitor = false), StockDecrementer::decrement(), FilterService and Category::countAllProducts(). CouponInterface declares getPriority() and isStopProcessing(): a promotion type that extends CouponAbstract inherits them.

Classes and events​

  • ModelConfigListener is no longer readonly: a subclass declared readonly class drops the modifier.
  • RecordOrderHistoryListener::rememberStatusBeforeChange() is removed: read the previous status from OrderEvent::getPreviousStatusId().
  • The first result extension of the Propel collection provider that answers something other than null is served, in the order of getDefaultPriority(), where all ran and the last answer won.
  • CART_ADDITEM, CUSTOMER_CREATEACCOUNT, CUSTOMER_UPDATEACCOUNT and CUSTOMER_UPDATEPROFILE may throw ProductNotAvailableException or InvalidCustomerDiscountException: a module that dispatches them catches the exception. CustomerGroup::preDelete() throws DefaultCustomerGroupProtectedException for the default group.
  • Every customer row needs a group: a module or an import that inserts into customer with SQL sets customer_group_id.

Quantities, prices and totals​

  • Quantities are floats: ProductSaleElements::$quantity, CartEvent::getQuantity() and its protected property $quantity (?float instead of ?int), Product::createProductSaleElement(). A class that overrides or redeclares them follows, and a listener that compares a quantity to an integer with === changes.
  • Prices of a sale element can be null in the API when the shop does not show the price to the caller (ProductPrice::getPrice() returns ?float).
  • Totals and line amounts round half up to the cent, so an order total may differ by a cent. Code that adds up cart lines reads CartItem::getSummedTotalRealPrice().
  • Prices change for customers with a discount or a group that prices anything.
  • Paying a cart whose prices moved is refused once with a 409 Conflict; the next attempt goes through.

API​

  • GET /api/front/coupons and its two siblings answer 404; Thelia\Api\Resource\Coupon is no longer an API resource.
  • confirmationToken is removed from the customer read representation, and POST /api/front/customers no longer reads customerTitle nor a lang IRI.

Themes​

  • Update Flexy (1.4.0), back-office (1.4.0), e-mail (1.4.0) and PDF (1.5.0) together with the core: all require thelia/core ^3.4.
  • A child theme that overrides a Flexy component listed in UPGRADE-3.4.md (Summary\Checkout, NextButton\Base, Cart\Base, ProductDetails\Base) follows its new signature. The back-office search of default-twig changes the public methods of SearchRepository and SearchResultsPresenter.
  • An AI connection that reads THELIA_AI_<X>_KEY and calls a base URL of its own needs THELIA_AI_<X>_BASE_URL.

Thelia 3.3​

The update gestures (the Symfony Messenger recipe, the shared directories, the queue of the heavy jobs) are in Updating from 3.2 to 3.3. See Background jobs for the model.

Doctrine DBAL 4​

The core requires doctrine/dbal ^4.2, for the queue in the shop database (DBAL alone, no ORM). A project or a module held on DBAL 3 must move to DBAL 4 before it updates.

Back-office theme​

The default-twig back-office theme requires thelia/core ^3.3 in its composer.json. Update the core and the theme together.

Export and import handlers​

ExportHandler::export(), ImportHandler::import() and ImportHandler::validateUpload() take a new optional last argument. A module that overrides one of them has to declare it.

MethodNew last argument
Thelia\Domain\DataTransfer\ExportHandler::export()?\Closure $onProgress = null, told the rows written
Thelia\Domain\DataTransfer\ImportHandler::import()?\Closure $onProgress = null, told the rows read
Thelia\Domain\DataTransfer\ImportHandler::validateUpload()?File $file = null, the uploaded file whose content is checked

processExport() and processImport() keep their signature. ImportHandler::import() now extracts an archive through a private method, so an override of extractArchive() is no longer called by it.

ImportHandler takes a fourth constructor argument, Thelia\Domain\DataTransfer\ArchiveInspector: a module that builds or extends it passes it. AbstractArchiver implements the new Thelia\Core\Archiver\ClosableArchiverInterface (close(): bool, discard(): void): an archiver of a module that declares either method with another signature must align it.

Mails​

  • The order history line email_sent is written once the mail server has taken the mail, by Thelia\Mailer\EventListener\OrderEmailHistoryListener on the Symfony Mailer SentMessageEvent, and no longer by MailerFactory right after handing the mail over. Without a queue this happens in the same request; with one, it is the worker that writes it, later, and the author of the line is system.
  • MailerFactory names the order in two headers of the mail, X-Thelia-Order-Id and X-Thelia-Message-Code, and gives every mail an identifier in X-Thelia-Mail-Id. They travel through the queue and are removed right before the mail is handed to the mail server. A worker keeps the identifiers of the mails the server accepted for a week, and does not send a mail whose identifier it kept: the queue may hand a job out twice when a worker stopped before acknowledging it.
  • MailerFactory no longer takes an OrderHistoryRecorder. Its fourth constructor argument is now the required Symfony\Component\Mailer\Transport\TransportInterface (the mailer.transports service), used by sendNow(). A module that builds it with new and still passes the recorder gets a TypeError.
  • With a queue, sendEmailMessageOrFail() and the methods built on it only throw when the mail could not be built or queued. A delivery failure no longer reaches the caller: the mail goes to the failure transport, failed.
  • A TemplatedEmail that is not rendered yet is refused when it is queued, with a LogicException: the worker renders nothing. Render it before sending it (BodyRenderer), or send it without a queue.

Messenger configuration​

The core configures Messenger for the whole application: its serializer, its bus, its failure_transport and the routing of its messages come before the configuration of the project. An application or a module that already queued messages of its own (App\Message\…) gets a LogicException on dispatch until their classes are listed in the thelia.messenger.allowed_message_classes parameter, or live in the namespace of an active module and have a handler. See Which classes a queue accepts.

Import right​

Launching an import from the back office takes the UPDATE right on admin.import. The VIEW right used to be enough; it now only shows the imports and their jobs. Review the profiles of the administrators who import.

Thelia 3.2​

A class you read from the container needs nothing when its constructor gains arguments. The "has to pass" cases below concern a module that builds the class with new.

Smarty back office removed​

The Smarty back office (thelia/backoffice-default-template) is no longer required nor activated. default-twig is the only back office the core installs, and the Smarty one is not maintained in 3.x.

BeforeAfter
Installed back officedefault-twig, or the Smarty default side by sidedefault-twig only
thelia/hook-admin-home-module (dashboard of default-twig)Came with the Smarty back officeRequired by the root package
thelia/smarty-module, thelia/web-profiler-moduleInstalled in developmentNot installed. The Symfony profiler stays; the Thelia panels it added (Smarty among them) go away

The update script switches a shop whose active-admin-template is still default to default-twig, and turns off TheliaSmarty and VirtualProductControl, which only came with it.

A shop that still runs the Smarty back office has to:

  1. require thelia/backoffice-default-template itself;
  2. register BackOfficeDefaultBundle\BackOfficeDefaultBundle in config/bundles.php;
  3. set active-admin-template back to default;
  4. activate TheliaSmarty again.

Classes that moved with it:

  • Thelia\Form\Lang\LangUrlEvent ships with the core, under the same name.
  • CouponAbstract::COUPON_FORM_NAME names the coupon form the coupon fields are posted under. It replaces Thelia\Form\CouponCreationForm::COUPON_CREATION_FORM_NAME; the value is the same, thelia_coupon_creation.
  • Every other class of Thelia\Controller\Admin and Thelia\Form that came with the Smarty back office goes away. A module that extends one of them stops loading. This includes the versions of EasyProductManager and EasyCustomerManager written before their Thelia 3 port (they extend Thelia\Controller\Admin\ProductController) and Dealer up to 4.0.0 (Thelia\Controller\Admin\FileController). EasyProductManager 4.0.0, EasyCustomerManager 3.0.0 and Dealer 4.0.7 onwards no longer use them.
  • CustomerFamily reads the form name thelia_product_creation only, which default-twig builds too.

See Back-office for the Twig conventions to port to.

Payment modules​

BeforeAfter
Cart during MODULE_PAYEmptied before the module is called: pay() read an empty cartKept until the payment is confirmed: pay() reads the cart the shopper filled. AbstractPaymentModule::cartItemCount() still answers 0 without a session
getCurrentOrderTotalAmount($with_tax, $with_discount, $with_postage)Read the postage off the session order, which nothing in 3.x writes to: the amount never included the deliveryCounts the postage of the cart when $with_postage is true, as its signature always said
Cart that method pricesThe session cartThe cart carried by MODULE_PAYMENT_IS_VALID while the module is asked whether it accepts the payment, the cart the order is built from while it is asked to pay (held by PaymentCartContext), the session cart only when no payment is under way. Taxed in the country of the delivery address, or of the customer's default address. Answers 0 outside any request instead of throwing
New attempt on the same cartAnother order was placedDepends on supportsPaymentRetry(), see below

What to do:

  • A module that compares getCurrentOrderTotalAmount() to a minimum or a maximum now compares the amount the order will carry. FreeOrder, which accepted a free cart whose delivery is charged, now refuses it.
  • Thelia\Module\PaymentModuleInterface declares supportsPaymentRetry(): bool. AbstractPaymentModule answers false, so a module extending it has nothing to do. A module implementing the interface directly has to declare the method. Say true only when the provider reference varies at each attempt and the notification finds the order back by the order's own reference.
  • A module that relied on the cart being empty during pay() has to stop doing so.
  • ORDER_CART_CLEAR stays declared and listened to, but Thelia\Action\Order::create() no longer raises it. A module that raises it itself still empties the cart and still retires the guest.

See Payment modules for the retry rules.

Constructors that take new arguments​

A module that instantiates one of these classes with new has to pass the new arguments. A module that reads the service from the container has nothing to do.

ClassNew or replaced arguments
Thelia\Action\Order::__construct()PaymentCartContext
Thelia\Action\Payment::__construct()PaymentCartContext
Thelia\Domain\Checkout\Service\CheckoutPaymentService::__construct()OrderFacade, OrderFingerprint and PaymentCartContext, on top of what it took
Thelia\Controller\Admin\SessionController::__construct()AdminTwoFactorManager and TwoFactorChallenge
Thelia\Core\HttpFoundation\Session\SessionManager::__construct()AdminTwoFactorManager and TwoFactorChallenge
RefreshTokenController::__construct()AdminTwoFactorManager
AuthenticationSuccessSubscriber::__construct()AdminTwoFactorManager
Thelia\Core\Template\Loop\ProductEffectivePriceCatalog and PricingActivityChecker, in place of ReservedSalePriceCatalog
Thelia\Core\Template\Loop\ProductSaleElements and ProductSaleElementsAccessServiceEffectivePriceCatalog, in place of ReservedSalePriceCatalog
Thelia\Action\CartEffectivePriceResolver and PricingActivityChecker, in place of ReservedSalePriceResolver and SaleAudienceChecker
Thelia\Domain\Media\MediaFacade::__construct()FileProcessorService and ProductMediaOrder, on top of what it took
BackOfficeDefaultTwigBundle\Service\Dashboard\DashboardStatsProvider::__construct()PeriodOptions, which now builds the period presets the dashboard and the reports share

DashboardStatsProvider belongs to the default-twig back-office theme, not to the core.

Orders​

  • Thelia\Model\Order::setCancelled() takes the event dispatcher and goes through ORDER_UPDATE_STATUS instead of writing the status on the row.

    // Before
    $order->setCancelled();

    // After
    $order->setCancelled($dispatcher); // Symfony\Contracts\EventDispatcher\EventDispatcherInterface

    A caller that cancelled an order by hand has to pass the dispatcher. It gets the restocking and the status listeners it did not have before.

  • A stock shortage while an order is being written is raised as Thelia\Domain\Order\Exception\StockShortageException, which names the product, rather than as a plain TheliaProcessException. The class extends TheliaProcessException, so existing catch blocks still match. Code that matched the wording of the message to tell a shortage from another failure can match the class instead.

  • A cart is turned into an order once, and the database is what says so: the order transaction locks the cart and refuses a second order for it. The guard covers every path that writes an order, ORDER_CREATE_MANUAL included. A cancelled order does not count. A shop running on more than one node should point LOCK_DSN at a store its nodes share; the shipped default, flock, is a file on the local disk.

  • An order that carries a currency or a language when ORDER_PAY is raised is frozen with them, and the session is only read for what the order leaves unsaid. A module that set a currency on the order and relied on the session overriding it now gets the one it set.

Pricing​

  • Thelia\Api\EventListener\ReservedSalePriceListener is now EffectivePriceListener: it serves the rule price as well as the reserved one.
  • Thelia\Api\Service\API\ResourceCache reads thelia.api.data_access.cache.visitor_dependent_price_prefixes and asks PricingActivityChecker. The former reserved_sale_sensitive_prefixes parameter is kept as an alias of the new one.
  • The front ProductSaleElements resource carries displayInitialPrice, null unless a rule or a reserved operation priced the sale element on that read.

API persist and remove processors​

The API persist and remove processors dispatch Thelia\Api\Bridge\Propel\Event\ResourcePersistedEvent after a write, and the collection provider dispatches CollectionModelsLoadedEvent before transforming a page. Nothing listens to them but the core; a module may.

Image files are stored per language​

The file column of the *_image tables (product_image, category_image, content_image, folder_image, brand_image, module_image) is dropped. The file now lives in *_image_i18n.file, nullable, so that each language of an image may show its own file.

BeforeAfter
Where the file is storedproduct_image.fileproduct_image_i18n.file (same for the five other image types)
getFile() on an image modelThe column of the rowThe file of the current locale. A language without a file of its own shows the file of the default language when the shop replaces missing translations (default_lang_without_translation), and an empty string otherwise

The model classes use Thelia\Model\Tools\LocalizedFileTrait, which also offers getOwnFile() (the file of the current locale, or null), getStoredFiles() and isFileUsedByAnotherLocale().

What to do:

  • Read the file through the model (getFile()), not through SQL or a query on the image table: ProductImageQuery no longer has filterByFile(). Query the *_image_i18n table (or join it with joinWithI18n()) when you need to filter on the file. setFile() on an image model writes the file of its current locale.
  • A module that creates image rows with its own SQL must write the file into the translation.
  • The update script setup/update/sql/3.2.0.sql copies the file into every translation of each image, gives the default language a translation when it had none, then drops the column. A shop that came from Thelia 2.6 already holds the files in the translations: they are kept as they are. An empty file name is stored as NULL.

Back-office list actions and CSRF token​

  • The toggle and position actions of Thelia\Controller\Admin\AbstractCrudController (setToggleVisibilityAction(), updatePositionAction(), genericUpdatePositionAction()) answer 403 to a request without the session token. A module whose back-office list toggles or reorders rows through them has to send _token.

  • Thelia\Tools\TokenProvider::checkRequestToken() reads the token from the _token body field, then from the X-CSRF-Token header, then from the query string.

    Token sent in3.2
    Request body (_token)Accepted. Use a POST request
    X-CSRF-Token headerAccepted
    Query stringStill accepted, with a deprecation. The same applies to a value a caller read from the URL itself and handed to checkToken()

    A token in the URL leaks through access logs, browser history and Referer headers. Move the action to a POST request that carries the token in the body. Setting the thelia.token.accept_query_string parameter to false refuses a token in the URL; a later version will make that the default (3.3).

    # config/services.yaml of the project, to test your module before the default changes
    parameters:
    thelia.token.accept_query_string: false

Product media positions​

The images and the videos of a product share one sequence of positions. Moving a product image up or down swaps it with the medium right before or after it, whichever table that medium lives in, and deleting one closes the gap in both tables. A module reading product_image.position alone may find gaps where the videos sit.

Admin log and request dump​

Thelia\Core\HttpFoundation\Request::toString() leaves the Cookie and Authorization headers out, and the PHP_AUTH_USER, PHP_AUTH_PW and PHP_AUTH_DIGEST values Symfony copies into the headers. A module reading these from the dump, for instance in a custom log, no longer finds them.

API Platform pinned to 4.3​

thelia/core declares a Composer conflict with api-platform/symfony and the split packages documentation, http-cache, hydra, json-schema, jsonld, metadata, openapi, serializer, state and validator from 4.4.0 (>=4.4.0 <5.0). The line stays on API Platform 4.3.x: the upgrade command of 4.4 breaks the console in a project that does not use Doctrine. A project or a module that requires API Platform 4.4 or later cannot be installed next to Thelia 3.2.