The 2023.10 version of the Aimeos e-commerce framework for Laravel and TYPO3 is available now! Especially developers will love the 2023 version because it contains a lot of simplifications and fully supports scaleable cloud setups like Kubernetes natively. The most important updates in 2023 are:

• Laravel 10 distributions
• TYPO3 12 support
• Kubernetes/Serverless support
• Create managers easily
• Merged order and order base
• Stored basket panel
• DB-based translations for type names
• VueJS and GraphQL in backend

Laravel 10 distributions

Since the Laravel 10 release in February 2023, Aimeos fully supports the latest Laravel version and since 2023.04, the Aimeos headless and full stack distribution are based on Laravel 10. You can bootstrap your own Aimeos application in less than five minutes using those distributions and get a fully working Laravel 10 application. This also includes pre-configured authentication setup for both, the full stack and the headless distribution.

TYPO3 12 support

Also, Aimeos 2023.x fully supports TYPO3 12.4 since it’s release in April. Many changes has happened in v12 compared to v11, especially a lot of deprecated code has been removed. This made it very hard to make Aimeos 2023.x available for TYPO3 v11 too so we’ve decided to support v12 only in that release. Therefore, if you need a feature from Aimeos 2023.x or want to upgrade after two years of free support, you must upgrade to the latest TYPO3 v12 too.

Kubernetes/Serverless support

We are proud to announce that Aimeos 2023+ is the first cloud-native e-commerce solution for Laravel. Everything including file imports can be distributed across any cloud environment like Kubernetes, AWS, Google Cloud, Azure or so called serverless environments now. Aimeos for Laravel is cloud-ready since the beginning and images/CSS/JS files can be stored in S3 or similar cloud storage services but files were read only from a local file system. This this year, you can store files for importing products, categories, users, etc. from any remote server regardless if they are in CSV or XML format.

We also moved our complete server infrastructure from traditional hosting to a private Kubernetes cloud beginning this year including the web sites, demo setups and private package repository.

Create managers easily

Extending existing managers is extremely simply but writing new managers for own data domains or extending existing data domains required a lot of boilerplate code in the past. Since 2023.10, creating new managers is as easy as extending managers now.

First of all, create a setup task for the database migration as before:

namespace Aimeos\Upscheme\Task;

class Test extends Base
{
    public function up()
    {
        $this->info( 'Creating test schema', 'v' );

        $this->db( 'db-test' )->table( $name, function( $table ) {
            $table->engine = 'InnoDB';

             $table->id()->primary( 'pk_mstes_id' );
             $table->string( 'siteid' );
             $table->string( 'label' )->default( '' );
             $table->int( 'position' )->default( 0 );
             $table->smallint( 'status' )->default( 1 );
             $table->meta();
         } );
    }
}

Then, create the manager for the new domain named “test”:

namespace Aimeos\MShop\Test\Manager;

class Standard
    extends \Aimeos\MShop\Common\Manager\Base
    implements \Aimeos\MShop\Common\Manager\Iface
{
    public function getSaveAttributes() : array
    {
        return $this->createAttributes( [
            'label' => [
            ],
            'status' => [
                'type' => 'int',
            ],
            'position' => [
                'type' => 'int',
                'label' => 'Position for sorting'
            ],
        ] );
    }
}

That’s all! You can work with your new manager like with any other manager from the Aimeos core:

$manager = \Aimeos\MShop::create( $this->context(), 'test' )

$item = $manager->create()
    ->set( 'label', 'test label' )
    ->set( 'position', 2 )
    ->set( 'status', 1 );

$item = $manager->save( $item );

$label = $item->label;
// or using get() with default value
$label = $item->get( 'label', 'default value' );

For more information, there’s an article about creating new managers in the Aimeos documentation.

Merged order and order base

The biggest architectural change since the beginning is simplifying the order data domain by merging the order and order base tables/managers/items. The initial idea behind was that we can have several invoice/refund entries for each stored order base item (=basket) but that turned out to not work well over the years and complicated handling orders a lot. Thus, the data is all stored in the order record now.

That leads to some consequences, especially for the JSON:API as this change isn’t backward compatible! An application using the JSON:API doesn’t need to use the order endpoint any more to create an order item because the basket endpoint did that already. Furthermore, the property names in the basket changed and “.base” has to be removed.

The JSON:API has been backward compatible for six years (2017-2022) and we want to keep v2 stable for the next 5-10 years now.

Stored basket panel

Customer baskets are stored in the database during some time and now, the admin backend contains a new “Sales > Baskets” Panel in the admin backend. Administrators and editors can check saved and abandoned baskets of the customers and it’s also possible to send emails to 3rd party applications for reminding customers about their abandoned carts.

DB-based translations for type names

Before, translations for attribute types were only possible by translating them statically the Gettext translation files or in the Aimeos configuration. Thus, only developers were able to update these translations and it was difficult to update translations if they have been delivered by ERP systems.

Now, type translations are saved in the database along with the types and can be edited in the admin backend and updated easily by ERP systems. This is available for all types, not only attribute types.

VueJS and GraphQL in backend

Several panels have been rewritten in the admin backend to use VueJS components now. This lead to better code quality and is another step forward to remove all jQuery-related code in the next versions. Also, VueJS components for which no VueJS 3 version is available has been replaced by better supported ones, namely the combo box select components which have been replaced by Vue Multiselect now. Finally, this will make the upgrade to VueJS 3 possible in the next versions.

Furthermore, requests to the JSON admin API has been replaced by requests to the new GraphQL API where possible. We will continue to extend the GraphQL API and replace existing JSON admin API requests until we completely phased out the JSON admin API. In 2024.x, the JSON admin API will be also marked as deprecated. The frontend JSON:API will never be replaced and will be the only way for frontends to interact with Aimeos servers as GraphQL is not suited well for read-heavy applications like e-commerce apps.

The 2021.10 release of the Aimeos e-commerce framework with long term support is available for Laravel, Symfony and TYPO3. It contains a lot of small features repeatedly requested by developers and users and which improve user experience, usability for editors and security. The most important improvements are:

• Laravel 8 distribution and TYPO3 11
• Radius search and maps
• “Price on request” feature
• Product video support
• Improved backend usability
• Custom invoice numbers
• Warehouse management
• PDF with SEPA QR-code and images
• Strict CSP and other improvements

Laravel 8 distribution and TYPO3 11

After Laravel 9 has been postponed to next year, we’ve decided to update the Aimeos standalone shop distribution to Laravel 8 in the meantime. Up to now, the Aimeos distribution was based on Laravel 6 LTS for maximum stability and we will upgrade to Laravel 9 LTS beginning with Aimeos 2022.04+ releases.

Despite of that, the Aimeos Laravel package is available for Laravel 8 since it was released and will be also available for Laravel 9 immediately after its release.

The Aimeos TYPO3 extension is the most widely used e-commerce extension for TYPO3 and even surpassed tt_products this year according to the TER download numbers!

The Aimeos 21.10 LTS release contains full support for TYPO3 11 and also the 1-click Aimeos TYPO3 distribution is available for TYPO3 11.5 LTS since its release.

Radius search and maps

The Aimeos admin backend contains world maps in the customer and supplier panels now, so editors can select or update the coordinates the addresses belong to. Then, supplier coordinates are added to the product index to enable users searching product within a given radius.

The maps in the backend are generated by Leaflet.js and OpenStreetMap and can be used by anyone without fees.

Price on request

One of the most often requested features, especially in the B2B area, is the ability to create a request for the products in the basket without displaying a price. Then, the price is caculated by different factors and printed at the offer sent to the customer.

If editors add prices with empty values to products, the frontend will display “on request” now. Customers can add those products to the basket and can complete the order as normal but the products without a price will be treated like having a price of 0.00.

Mixing products with a regular price and products with prices “on request” is no problem and the payment at the end of the checkout process will be done for the products with a regular price only.

Product video support

The release also includes support for product videos in MP4/WebM format. You can upload one or more videos in the product media panel of the admin backend and a preview image is generated automatically based on the video content.

The videos are shown like regular product thumbnails in the catalog detail component of the HTML frontend but if users switch to the video, it starts playing automatically without sound.

Improved backend usability

To ease daily work for editors, all media panels now support uploading multiple files at once when clicking on the “+” button and each file will create a new card automatically. Before, only the card was added and you had to upload a file for each card. Also, the new release improves cropping and scaling of uploaded images.

In the text panels, CKEditor 5 is now used for editing and styling the text content. The new version also added new features like table and video support within texts which is now available out of the box.

Custom invoice numbers

Many shop owners want to customize the invoice numbers for many reasons but this was hardly possible in the past. Now, developers can register custom functions for generating invoice numbers that are used in the HTML frontend, the e-mails or PDFs, e.g.:

use \Aimeos\MShop\Order\Item\Standard as Order;
 
Order::method( 'ordernumber', function( \Aimeos\MShop\Order\Item\Iface $order ) {
    return 'RE-' . date( 'Y' ) . '-' . $order->getId();
} );

Warehouse management

To improve order and warehouse management in Aimeos, there’s a new payment status for each ordered product. Thus, you can now mark single products as refunded or use any other payment status.

To display the additional information, the product section of the order detail panel has been rewritten. It’s fully responsive now and easy to use in combination with mobile phones.

For the 2022.x version, you can expect some bigger changes in the Aimeos order domain.

PDF with SEPA QR-code and images

The template for the PDF attached to the payment related e-mails contains a QR-code for European IBAN payments. Mobile users whose bank supports scanning these QR-codes can pay invoices within seconds and 100% error free.

In addition, the template also contains example code how to add a background image to the PDF files. Then, companies can send order confirmations including PDFs that look exactly like their well-designed letter papers.

Strict CSP and other improvements

Starting with 2021.10 LTS, a strict Content Security Policy has been implemented for the Aimeos backend and for the Laravel frontend. This effectively prevents Cross-Site-Scripting (XSS) where foreign Javascript code is executed in the context of the page loaded by the users’ browser and which is a common source of security incidents.

This also means that inline Javascript in any templates is ignored by browsers now and scripts, CSS, images, videos, etc. are only loaded from well-defined sources. To allow a new URL for any of those objects, you have to overwrite the frontend or backend page template and add the URL there:

• Laravel frontend
• Laravel backend
• TYPO3 backend

To allow Javascript required by e.g. payment gateways like Stripe, a “nonce” is available to mark JS code within script tags as trusted. Other security improvements include hardening against potential CSRF attacks and SVG images are now sanitized when uploaded, so they doesn’t contain any Javascript or external URLs.

To improve internationalization, it’s now possible to translate all error messages with placeholders from the core, even those that are only logged. Furthermore, all log messages has been categorized to filter messages by their source effectively.

Last but not least, the catalog detail component can be configured to return a HTTP 404 status instead of displaying an error message that the product could not be found.

The second stable release in 2021 of the Aimeos e-commerce framework is now available. The fantastic new default theme is the most notable change for sure but this release contains many more improvements, especially for multi-site environements. The most important points are:

• New default theme
• New settings panel in backend
• Send order notification emails
• Extended order management
• Multi-site improvements
• Improved security
• Upgrade notes

New default theme

The first you will notice after installing Aimeos will be the new default theme. It has a very pleasant look and feel and is also great for non-fashion online shops even if the used images create a great experience for an example fashion shopping web site.

The content below the main image is completely created by using the powerful Aimeos content management extension. You can not only add texts, images and videos in a custom column layout but also insert product lists in between. This allows full content commerce in content pages with custom page URLs which you can add in addition.

Also, the new theme fully supports right to left languages like Arabic as the previous theme did. Colors can be customized easily by using the defined CSS variables and you can adapt the theme totally to your needs. It’s also fully optimized to receive top scores at Google Lighthouse.

Admin settings panel

There’s a new panel in the admin backend available for adding configuration options per site including images, shop and theme related settings with is available in “Configuration > Settings”. It’s especially useful in multi-site environments because it allows site admins (shop owners) to configure basic settings themselves and also to choose one of the available themes.

If you use Laravel and the Aimeos installation is configured as multi-site setup with custom domains, shop owners can also set their custom domain name in that panel.

You can extend this panel by custom subparts like any other panel, so site admins can configure any settings they should be able to in a convenient way. There will be more subparts in the future included in Aimeos.

Send order notification emails

Up to now it was only possible to push the order confirmation e-mails sent to customers also to the shop owner using a BCC e-mail address. This can cause a lot of e-mails because each order is immediately sent in a separate e-mail.

In the new version, there’s an “Email” delivery service provider available which sends e-mails including the order data in a custom e-mail. These e-mails can also contain serveral orders at once and they are sent when the “order/service/delivery” job controller is executed. Thus, you can send the e-mails, once a day, every hour or immediately depending on the clients need.

The e-mail content itself as well as the attached file with the orders can be fully customized using the delivery service provider templates located in the Aimeos core.

Extended order management

In the new release, the detail view of the Aimeos order panel has been extended and contains warehouse management related fields now.

In addition to the already available status and “Delivery in” fields, it’s possible to handle partial deliveries in Aimeos now if e.g. only one product is available for some reasons but two has been ordered. By tracking which and how many products you’ve already sent to the customer, you get lean warehouse management functionality in case you don’t have a specialized system for that kind of task.

In the new notes field, you can add an arbitrary text that isn’t shown to the customer while the content of the “Delivery in” field is displayed in the customers’ order history.

Additional improvements

Many additionall improvements have been implemented in the new version for multi-site and market place setups. The most noteable is the new scheme for storing uploaded file, including preview images. Before, all files have been stored in two main directories (“files” and “previews”) and it was almost impossible to find out which file belongs to which site. Now, all files are stored by site ID, e.g. the files for the first site are placed at “./1./files” and the previews in “./1./previews”. If a merchant decides to close the shop, it’s now easy to remove all the files that belong to that shop.

Another major improvement affecting security is the activation of the Content Security Policy (CSP) by default. Frontend (where possible) and admin backend are now protected by a set of rules which allows CSS, Javascript, images and other code and objects only from a very limited set of domains. This prevents cross site scripting and stops executing hazardous content from malicious customers and editors in the browser – in case someone forgot to escape output properly. Thus, the CSP rules are an additional security layer to avoid security related problems like session hijacking, information disclosure and others.

Now, we are preparing for the 2021.10 LTS release and there will be additional polishing and we plan tighten security rules even futher.

Upgrade notes

Since 2021.07, installing Aimeos via composer requires composer 2.1+ and the official Aimeos extensions prefixed with “ai-” must be removed from the “./ext/” directory. Instead, they are installed into “./vendor/aimeos/” now. If you don’t remove them with

rm -rf ./ext/ai-*

from your installation after upgrading, you will get an error about these extensions are available twice (once in “./ext” and once in “./vendor/aimeos/”). Your custom extensions can still be placed in the ./ext directory to make development easier.

Due to splitting uploaded files by site, the directory structure changed and those file are now stored in subdirectories named by the site ID, e.g. “./1./files/”. New uploaded files use that new structure automatically, old files stay where they are and are still found – at least in TYPO3 installations. In Laravel and Symfony installations, the uploaded files will be stored in an additional sub-directory named “aimeos” in “./public”. The old paths were:

• ./public/files/…
• ./public/previews/…

In 2021.07+, the new paths are:

• ./public/aimeos/1./files/…
• ./public/aimeos/1./previews/…
• ./public/aimeos/2./files/…
• ./public/aimeos/2./previews/…

Thus, old uploaded files will be only found if you move the old paths to the new “./public/aimeos” sub-directory:

mv ./public/files/ ./public/aimeos/files
mv ./public/previews/ ./public/aimeos/previews

Furthermore, the themes directory for Laravel installation has changed from “./public/packages/shop” to “./public/vendor/shop” to comply to Laravel standards.

New admin backend

The design of the admin interface has been completely reworked to resemble a modern, card based interface and includes a lot of eye candy. Compared to backends backends of other e-commerce applications, this is the most modern interface available!

Also included is a cool new dark mode for people prefering dark interfaces and which is much more eye pleasing during the night. You can activate it by clicking on the moon symbol in the upper right corner and once activated it will be used during the whole browser session.

body {
  --bs-primary: #f12711;
  --bs-primary-alt: #f5af19;
}

As you may have already noticed, the admin dashboard has additional panels for a quick overview for orders and customers and the change compared to the last seven days.

Furthermore, there’s a new panel for orders by countries including a world map to see immediately where your customers are coming from. All panels are lazy loaded if you scroll down to reduce the number of requests.

RTL support

Starting which this release, Aimeos has built-in support for right-to-left languages like Arabic, Hebrew and other languages which are written from right to left contrary to languages based on e.g. Latin which are written from left to right.

Besides the text direction this also includes placing of components, menus as well as paddings and margins.

The front-end and back-end of Aimeos is automatically and fully mirrored if an RTL language is selected.

You can try yourself by chosing e.g. Arabic in the language selector of the back-end or add Arabic to the available locales in the front-end. The rest is now automatically done by Aimeos if you use the latest templates.

Full mobile optimization

In addition to the mobile optimizations in previous releases, all menus and the small basket in the front-end are now implemented as offscreen menus. This ensures that even on very small mobile screens down to 320px width, there’s always enough space for the content. Moreover, this adapts the design patterns from mobile apps so smartphone users feel like home.

Rule based dynamic pricing

Shop owners are now able to change the prices for products dynamically e.g. based on which categories the products are in. Thus, it’s possible to change prices for a group of products within a limited period of time and/or depending on the logged in customer without the need to create a new or adapt the existing prices.

The new Aimeos rule system is extremely flexible and not only allows prices to be adapted dynamically. It’s also possible to adapt any product content like images, texts, etc. dynamically based on the rules created.

Extensible CMS extension

Beginning with 2021.04, there a Aimeos content management extension available based on GrapesJS, a Javascript CMS framework for managing page content.

Contrary to CKEditor, the HTML editor used for product related and other texts, it’s a component based content editor offering building blocks like headlines, paragraphs, images, grids, forms and other building blocks. It’s a bit like the editor used by WordPress 5.

As you expect from Aimeos, you can fully extend the editor and add new components for your own purpose. Each block is defined by a few lines of HTML for the structure and the Javascript code to allow the editor to customize the component.

Supplier detail component

For those who want to show customers their more details abount the brands, producers or manufacturers of the products, a new supplier detail component is now available.

It will display all information your are entering for the supplier items in the admin backend including images, texts and addresses. Additionally, you can add a catalog list component to the page to list all products that belong to this supplier including sorting and pagination.

Simplified config and breaking changes

Last but not least, some breaking changes has been made compared to the 2020.10 LTS version to simplify working with Aimeos even more for shop owners and developers alike. The most notable is that the configuration settings which contained “standard” in their config keys has been shortend and the “standard” part is removed now:

// 2020.10 and before
client/html/catalog/filter/standard/subparts

// 2021.04 and later
client/html/catalog/filter/subparts

Another important change for developers is related to the connection between the stock and product domain. Instead of the product code, now the product ID is used in all stock items to refer to the product item the stock level is associated to. This removes several problems when changing product codes and selecting the right stock level for product in marketplaces.

The full list of breaking changes are available in the Aimeos documentation.

The new 2020.10 release with long term support contains a lot of polishing and some features users and developers have been asking for. But one of the most important changes is related to the documentation, which has been greatly improved! Feature-wise, the most important additions are:

• Complete product rating and review system incl. JSON API
• Home page component
• Price facet filter
• Date/time range filter in admin backend
• Simplified getter in context
• Better log entries for SQL statements
• Official Laravel 8 support
• Full AWS support

New documentation

As you may have already noticed, the old documentation Wiki has been retired and a well structured Aimeos documentation welcomes developers and users alike.

Due to the clear structure, it should be much easier now to find the documentation you are looking for. If not, you can use the Algolia based full text search at the top to find matching articles very quickly. Tip: The more words you type, the more accurate the found pages will be.

The documentation is based on the Markdown syntax most developers are already familiar with. Everyone can contribute to the new documentation repository and is invited to do so to improve the documentation further.

Reviews and rating

Aimeos is getting closer to feature completeness by offering a first-class product rating and review system in the new version. This was one of the last big missing features but not any more!

It’s design and feature set is similar to Amazon’s review implementation including the possibility for a vendor response but much nicer in terms of layout and it scales extremely well for very large sites too.

The implementation consists of a new, separate data domain for reviews and ratings. The ratings will be automatically updated when new ones are added and approved. A frontend controller, HTML clients and JSON REST API “review” and “customer/review” endpoints for managing the reviews are part of the release.

New HTML components

For the HTML frontend the new “catalog home” component is available, which creates a nice start page by displaying category information from the root and first level as well as the promotional products assigned to these categories.

The output consists of the stage image from the “home” category (if it exists) and the stage images from its direct sub-categories including their short descriptions. If either the image or the description is missing, the available content uses the available space so the layout adapts to your content in a very flexible way.

Also, the catalog filter component contains a new price filter subpart now:

It enables users to limit products by their price using a native HTML5 slider element connected to the input field for the upper price value. Users can also enforce a minimum price if they want to. The upper price is automatically calculated from the product selection limited by the already applied categories or filter facets.

Admin backend improvements

Thanks to the flatpickr Vue.js component and the range expression support in the Aimeos core, you can now filter items in the list views by date ranges. This applies to all date or date/time columns in all list panels and is extremely useful in the order panel to show all order of e.g. the last month and export them afterwards.

Also, the detail views use the new component too for all date/time fields. There, you can not only select a date but also the time, e.g. for the start and end dates. Thus, a convenient way of selecting dates and times is available for users of the Safari browsers now, which is the only major browser that doesn’t support date/time input fields natively.

Developer support

For developers, the new release offers shorter methods for accessing data in the “Context” dependency container, continuing the introduction of short methods for managers in the last version. Thus, you can write now for example:

• getDatabaseManager() => db()
• getFileSystem( ‘name’ ) => fs( ‘name’ )

Furthermore, the debug log entries aren’t JSON-encoded any more, so you can copy e.g. logged SQL statements directly from the log panel in the admin interface and paste them into any database client without the need to remove all that additional JSON characters any more.

Laravel and AWS

Aimeos supports the new Laravel 8 release from day one and 2020.10 is the first Aimeos LTS version which is fully working with this major Laravel version. The Aimeos Laravel package now supports Laravel 6, 7 and 8.

Last but not least, deploying Aimeos on AWS using MySQL works like a charm now by passing additional MySQL configuration down to the PDO driver. More concrete, MySQL on AWS requires a certificate configuration that is now supported by custom driver options.

The new Aimeos feature release contains some long-awaited new stuff for developers and customers alike. What you get by using the 2020.07 release among various minor improvements and bugfixes is:

• PDF invoice in order confirmation e-mail
• Supplier CSV import
• Improved admin backend for mobile phones
• Better full text search and URL segments
• Official TYPO3 10 support
• Simplified manager and criteria filter methods

PDF invoice in confirmation e-mail

One of the most often requested features is now part of the Aimeos core: A nice looking template which can be easily adapted to the clients requirements and corporate design. The full source code for the invoice PDFs was contributed by the Aimeos GmbH.

The PDF document is generated from a HTML template and automatically attached to the e-mails sent to customers when the order has been paid. You can change the content and the layout of the PDF by adapting the template only, including header and footer sections repeated on each page.

Internally, the TCPDF library is used for creating the PDF from the HTML template, which also supports splitting long content to several pages automatically. In composer based setups, TCPDF is automatically added and installed as dependency. For TYPO3 integrators who still download packages from TER, there’s a new dependency the pdfviewhelpers extension due to the size of the TCPDF libary.

Supplier CSV import

Up to version 2020.07, you have been able to import several entities via configurable CSV files:

• attributes
• categories
• coupon codes
• products
• stock levels

Now, you can also import supplier data including addresses, images, texts and references to other domains like products. Also, you can add supplier references in the product CSV import too.

This part of the new release was a big contribution by Alexey, an Aimeos developer and freelancer who offers his expertise for custom projects.

Improved admin backend for mobile phones

Thanks to Robert, who did an amazing job improving the backend styles, the Aimeos admin interface is much better usable by mobile phone users regardless of their display size. Even with an old iPhones which only have 320px width, managing the items is fully possible now.

Header texts which are too long fade out, the size of the buttons has been adapted to the smallest supported viewport size and all tables gets a scollbar if their columns are bigger than the screen.

Additionally, the left navigation menu got some love and displays the names of the navigation items when clicking on the bottom arrow button. Thus, mobile phone users can see what their meaning is if they can’t remember.

Better full text search and URL segments

The results of the full text search offered by MySQL, PostgreSQL and SQL Server has been refined to return more relevant results. Especially for phrases with several words, stop words and special characters, it yields much better results now.

Optimized URL segments can be added as text to products and categories, but generating URL segments from labels led to a loss of characters if special characters not covered by the ASCII character set was used. Thanks to the “voku/portable-ascii” library, these characters are now transliterated to the best matching ASCII character or to several characters like for “ä -> ae”.

Official TYPO3 10 support

Three month after TYPO3 10 LTS has been released, the Aimeos TYPO3 extension officially supports the new TYPO3 major release. It took some time until the static_info_tables extension was available for TYPO3 10, which Aimeos depends on.

The Aimeos 20.7.x extension supports TYPO3 v9 and v10 only because it removes all methods deprecated by v9 and dropped in v10 to clean up the code base. Furthermore, it uses the new APIs if applicable and offers it’s own panel for all Aimeos plugin elements with icons and descriptions to support new users.

Simplified manager and criteria filter methods

Working with Aimeos should be fun and even you can do the most complex things in e-commerce using Aimeos, the code you have to write should be as small as possible. Therefore, the manager methods have been shorted to:

Also, building filter criteria for the search() method is now much easier. Instead of:

$search = $manager->createSearch( true )->slice( 0, 100 );
$search->setConditions( $search->combine( '&&', [
    $search->compare( '==', 'product.type', 'default' ),
    $search->compare( '==', 'product.dataset', 'shirt' ),
    $search->compare( '>', 'product.datestart', '2020-01-01' ),
    $search->getConditions()
] ) );
$search->setSortations( [
    $search->sort( '-', 'product.label' ),
    $search->sort( '+', 'product.id' )
] );

You can now write using the new 2020.07 release:

$f = $manager->filter( true )->slice( 0, 100 )
    ->add( ['product.type' => 'default', 'product.dataset' => 'shirt'] )
    ->add( 'product.datestart', '>', '2020-01-01' )
    ->sort( ['-product.label', 'product.id'] );

This will cover 95% of all use cases. A more complex example including mixed AND and OR operators:

$f->add( $f->and( [
    $f->or( [
        $f->is( 'product.datestart', '<', '2000-01-01' ),
        $f->is( 'product.datestart', '==', null ), ]
    ),
    $f->or( [
        $f->is( 'product.dateend', '>', '2000-01-01' ),
        $f->is( 'product.dateend', '==', null )
    ] ),
] );

You can use the NOT operator for negating all conditions:

$f->add( $f->not( $f->and( [
    $f->is( 'product.type', '==', 'default' ),
    $f->is( 'product.status', '==', 0 ),
] ) ) );

Creating search functions to pass parameters as part of the search key are also much easier to use now:

$f->add( $f->make( 'product:has', ['attribute', 'default', 123] ), '!=', null );

Finally, you can parse a complete condition block like before:

$f->parse( ['||' => [
    [
        '<' => ['product.datestart' => '2000-01-01'],
        '==' => ['product.datestart' => null]
    ], [
        '>' => ['product.dateend' => '2000-01-01'],
        '==' => ['product.dateend' => null]
    ]
] ] );

The old manager and criteria API is still available so all extensions developed from 2020.x will continue to work without problems, but the old APIs are deprecated and will be removed in the future.

More about Aimeos

• Web site: https://aimeos.org
• Github: https://github.com/aimeos
• TYPO3 TER: https://extensions.typo3.org/extension/aimeos/

• Facebook: https://facebook.com/Aimeos
• Twitter: https://twitter.com/Aimeos
• YouTube: https://youtube.com/c/aimeos

2020.04 is the first stable release this year which contains a lot of changes and improvements. The most important one are:

• Slick and clean frontend theme
• Better admin interface usability
• Major performance improvement when using MySQL
• SEO improvements and support for fractional quantities
• Cleaned up templates for the HTML client
• Full SQL Server support
• Requires PHP 7.1 and PHP Map object
• Retrieve related items more easily

Slick and clean frontend theme

Thanks to our partner business unicorns who created a new design for Aimeos, the default frontend theme is now much more pleasing. From the technical point of view, it’s using CSS3 variables for the colors so it’s extremely easy to apply your own CI colors to the theme. Only include a CSS file before the Aimeos CSS which contains your own colors in:

.aimeos {
  --ai-primary: #FFA840;
  --ai-primary-light: #FFB850;
  --ai-secondary: #555;
  --ai-light: #D0D0D0;
  --ai-bg: #FFF;
}

Better admin interface usability

Especially the product panel had a lot of tabs and fields visible by default even if they are not necessary for the the majority of editors. They are reduced to the essential parts used in 80% of all cases like shown in the screenshot. Especially first time users now know exactly which fields and tabs are important to create their first products.

The advanced tabs and fields are still available but only after clicking on the drop-down icon in the tab list or below the shown form fields. This does also work using a smart phone, even if the tabs are then placed horizontally above the form fields.

Major performance improvement

When using the ai-sites extension from the Aimeos company in market place mode, MySQL stopped using indexes when the number of site IDs in the queries where more than a few. This led to a major performance decrease when market places had hundreds of vendors and a lot of products.

In 2020.04, the site IDs contains the parent site IDs too and form a path to the site in the site tree, e.g. “1.2.5.”. Now, retrieving all products for all vendors is simple for MySQL because the site ID just has to start with the parent site, e.g. “1.”. Thus, the existing indexes are always used by MySQL. Other database servers like PostgreSQL were not affected but will profit from the simpler queries too.

SEO and fractional quantities

For the URL segment of product URLs either the language dependent texts of type “url-segment” added by the editor where used or the sanitized label. Now it’a also possible to define a language indepented URL segment that is different from the label in the product panel. This does also apply to the categories.

Selling non-standard products where customers can also buy pieces is now possible without custom code. The “quantity scale” of each product defines the minimum amount a customer can buy, e.g. 100g if the standard price is per kilogram or 0,25m² for areal sized products. It’s also possible to define quantity scales larger than one.

HTML client templates

One often heard critisism about Aimeos was that the HTML templates contained not only HTML code and a few statements for conditions and loops to generate the final output but also PHP code to transform the data from the items to the requirements of the templates.

This code is now part of the client classes or has been moved to view helpers. Therefore the templates itself are now much cleaner and contain much less code so they are simpler to understand for integrators and frontend developers.

Full SQL Server support

Besides MySQL/MariaDB and PostgreSQL, Microsoft SQL Server is now the third relational database management system fully supported by Aimeos. You can use both, SQL Server 2015+ installed on-premise or the variant available in the Azure cloud.

All Aimeos feature are available including ultra-fast full text search, provided the Microsoft full text search plugin is installed. Otherwise, only the slow LIKE based search is available, which isn’t suitable for several thousand products and more.

PHP 7.1 and PHP Map object

Version 2020.04 and later requires at least PHP 7.1 because the Aimeos code base now makes full use of scalar type hints as well as return type checking for all methods. Thus, the PHP interpreter can throw type exceptions much earlier which simplifies debugging for developers.

Also Aimeos uses the Map object from the aimeos/map package instead of arrays as return value of searchItems() and whenever it simplifies the code. Instead of:

$list = [['id' => 'one', 'value' => 'value1'], ['id' => 'two', 'value' => 'value2'], null];
 
$list[] = ['id' => 'three', 'value' => 'value3'];    // add element
unset( $list[0] );                                   // remove element
$list = array_filter( $list );                       // remove empty values
sort( $list );                                       // sort elements
$pairs = array_column( $list, 'value', 'id' );       // create ['three' => 'value3']
$value = reset( $pairs ) ?: null;                    // return first value

You can now write:

$list = [['id' => 'one', 'value' => 'value1'], ['id' => 'two', 'value' => 'value2'], null];
 
$value = map( $list )                                // create Map
    ->push( ['id' => 'three', 'value' => 'value3'] ) // add element
    ->remove( 0 )                                    // remove element
    ->filter()                                       // remove empty values
    ->sort()                                         // sort elements
    ->col( 'value', 'id' )                           // create ['three' => 'value3']
    ->first();                                       // return first value

That saved some hundred lines of code in the current code base compared to 2019.x and before.

Retrieve related items more easily

Last but not least, several methods for retrieving related items are available now. This simplifies custom code because instead of writing code to fetch categories, suppliers, stocks and order base data yourself, you can now simply tell searchItems() what you need:

$products = $manager->searchItems( $filter, ['catalog', 'stock', 'supplier'] );
foreach( $products as $product )
{
    $product->getCatalogItems();
    $product->getSupplierItems();
    $product->getStockItems();
}

The same works in the order domain where you can order items including their base items, ordered products, address data, used coupons and delivery/payment service data:

$domains = ['order/base', 'order/base/address', 'order/base/coupon', 'order/base/product', 'order/base/service'];
$orders = $manager->searchItems( $filter, $domains );
foreach( $orders as $order )
{
    $basket = $order->getOrderBaseItem();
    $basket->getAddresses();
    $basket->getCoupons();
    $basket->getProducts();
    $basket->getServices();
}

Final words

All breaking changes between 2019.10 and 2020.04 are available in the changelog. If you want to upgrade from an earlier version, please check the list carefully and adapt your code. In custom code, you especially need to care about changed method signatures due to the the PHP 7.1 type hints.

The new 2019.10 branch of the Aimeos e-commerce framework with long term support (LTS) contains lots of helpful improvements. The most important ones are:

• AI-based translation of texts with DeepL
• Customizable product datasets
• Manage multiple tax rates
• Watermarks for images
• Bulk delete and reorder items
• Bulk order form for B2B and B2C
• Add new columns/properties to managers/items easily

AI-based text translation

Translations based on machine learning algorithms are quite good now. DeepL is the best translation service currently available and it supports all major western languages. To use it, you need a DeepL API account for developers and configure the DeepL base URL and the authentication key:

admin/jqadm/api/translate/url = 'https://api.deepl.com/v2'
admin/jqadm/api/translate/key = '<your-deepl-auth-key>'

Customizable product datasets

Other shops offer customizable attribute sets where you can define for e.g. a T-Shirt product which attribute types are required (most likely color and size in that case) but Aimeos now offers much more! Instead of attribute sets only, you can create a product template for almost all panels in the admin interface.

For example, a product template can automatically add a required category or related product drop-down, a media download item as well as pre-configured text and price items, stock and so on. Anything that should be entered can be automatically shown by the product template, e.g.

'admin' => ['jqadm' => ['dataset' => ['product' => [
    'T-Shirt' => [
        'characteristic' => ['variant' => [['attribute.type' => 'color'], ['attribute.type' => 'size']]],
        'catalog' => ['default' => [[]]],
        'related' => ['suggest' => [[]]],
        'media' => [['media.type' => 'download']],
        'price' => [['price.currencyid' => 'EUR', 'price.taxrate' => '19.00']],
        'text' => [['text.type' => 'name'], ['text.type' => 'short', 'text.languageid' => 'de']],
        'stock' => [['stock.type' => 'default']],
    ]]],
],

Manage multiple tax rates

For countries having multiple tax rates for single products (e.g. state and local tax), you can configure the available tax types in the admin interface including the associated tax rates that will be prefilled.

To define additonal GST and PST tax rates for example, add this settings to your configuration:

admin/tax/gst = 8.50
admin/tax/pst = 7.25

Then, the tax types can also be translated using “taxgst” and “taxpst” in the “client/code” translation domain.

Watermarks for images

Protecting your images from being used in other shops or web sites can be useful if you put a lot of work into creating them. Aimeos can combine every preview image with a configured watermark image. This image should be a PNG image with a transparent background and a translucent water mark. For best result use the “Imagick” media class:

controller/common/media/standard/options/image/watermark = /path/to/image.png
controller/common/media/standard/options/image/name = Imagick

Bulk order form for B2B and B2C

There’s a new HTML client component available for adding multiple articles to the basket quickly. This bulk order component is located above the basket by default but can be placed anywhere.

It supports finding products by name as well as by their SKU which makes it equally useful for B2B and B2C customers.

Bulk delete and reorder items

Deleteing several items at once in the list view is extremely useful for clean ups. Like seen in various other backends, you can select multiple items by clicking on the check boxes on the left. You can also select all visible items at once in the list and delete them with one click at the cross symbol in the header of the table.

The modal dialog which opens now informs you also about the names of the items that are going to be deleted to avoid deleting items you don’t want to remove.

Another useful capability for editors is to modify the order of attributes, media, prices and texts in their panels. Therefore, it’s not necessary any more to remove and add items again to enforce a certain order of the items.

To move items around, simply drag them by using the “move” handle (arrowed cross) and drop them at the position where they should be placed. It’s available for all saved items but not for new ones due to restrictions in the browsers (file uploads are read only for example).

Extend managers/items easily

Before 2019.10, you had to extend both, manager and item and overwrite several methods in these classes. By extending the classes it was hard to combine 3rd party extensions and own code. This is gone now! Instead of extending managers and items, you can stack manager decorators that care about saving and searching additional column values. Addionally, all items contain generic get() and set() methods so there’s no need to extend the items any more.

For more information, there’s an article explaining how to add own columns easily.

The most important changes in the Aimeos 2019.07 release are:

• Responsive images
• Responsive e-mails with MJML
• Multiple tax rates per price
• Customizable XML order export
• Address management in user profile

Responsive images

Finally, Aimeos contains support for responsive images of several sizes using the “srcset” attribute supported by the <img> tag in HTML5. By default, the Aimeos media controller creates three different preview images with 240px, 720px and 2160px width for each uploaded or imported and resized image. The original file is left unscaled if not configured otherwise and is used as source if images need to be rescaled to different sizes. In the frontend, those images are used in the list and details views like this:

<img src="/path/to/preview1" srcset="/path/to/preview1 240w, /path/to/preview2 720w, /path/to/preview3 2160w" />

The smallest preview is always used as fallback if the browser doesn’t support image srcsets (like IE 11). You should configure different images sizes depending on your frontend layout and the images widths that are required using the controller/common/media/standard/previews setting. Aimeos also supports cropping images exactly to the configured size automatically when you add the ‘fit’=>true setting for each preview image configuration.

Responsive e-mails with MJML

E-mails in Aimeos have been responsive since the beginning but e-mail clients displayed them very differently due to various built-in limitations in the clients. Now, we use the MJML framework for responsive e-mails that generates HTML code from a custom markup language that looks very similar in all major e-mail clients. The new order confirmation e-mail is now displayed like this in the clients (click for full size):

If you would like to know more about responsive e-mails in Aimeos and how to adapt them to your own project, please have a look into our Aimeos MJML article.

Multiple tax rates

For countries where federal and local taxes apply to product prices, Aimeos now supports multiple tax rates per price item. Those tax rates and their calculated tax values will be listed separately in the basket, checkout and the e-mails:

Each tax rate contains of a code and the tax rate value stored within each price item and the custom tax codes can be translated for the frontend.

Customizable XML order export

All who need exports of Aimeos orders including all details in XML format can use the new Aimeos Xml delivery service provider. It generates one local file at the configured location when the order/service/delivery job controller is executed. All orders created since the last run are then part of each file. A stripped example of the XML is:

<orders>
    <orderitem>
        <invoice>...</invoice>
        <base>...</base>
        <address>
            <addressitem>...</addressitem>
        </address>
        <product>
            <productitem>...</productitem>
        </product>
        <service>
            <serviceitem>...</serviceitem>
        </service>
        <coupon>
            <couponitem>...</couponitem>
        </coupon>
    </orderitem>
</orders>

The provider uses two templates to generate the XML files so you are able to create a custom XML file by simply overwriting these template files.

User address management

Up to now, users have been able to change their addresses only during the checkout process. Their changes are stored automatically and this is still the prefered way because it’s most user friendly. As alternative, the Aimeos user page can contain the account/profile component which offers managing billing and delivery addresses too:

The new release also contains a lot of minor improvements and fixes you can find in the commit history of the repositories. Updated packages are available for TYPO3, Laravel, Symfony, SlimPHP and Flow.

The stable 2019.04 release contains some major improvements:

• Improved core APIs and rewritten frontend controllers
• XML importer for attributes, categories, customers, products and suppliers
• Increased performance for complex queries
• More SEO friendly URLs

Improved APIs

The Aimeos core already offered an easy to learn API for working with managers, items and providers. All methods are now supporting fluent interfaces if possible so method calls can be chained like:

$item = $manager->createItem()->fromArray( $map )
    ->setType( 'default' )->addPropertyItem( $propItem );

Additionally, the frontend controller API for working with the shop objects efficiently in the HTML clients and the JSON REST API has been completely overhauled. All objects contain simple, fluent methods that can be concatenated like in the core library. Implementing your own product list in the frontend is now only a matter of a few easy to understand calls:

$products = \Aimeos\Controller\Frontend::create( $context, 'product' )
   ->uses( ['text', 'price', 'media' )->category( 123 )->text( 'sneaker' )
   ->sort( 'name' )->slice( 0, 48 )->search();

This statement would retrieve the first 48 products with texts, prices and images that are in category “123” and contain the text “sneaker” sorted by their names. In Laravel, facades simplify working with the frontend controller even more:

$products = Product::uses( ['text', 'price', 'media' )->category( 123 )
   ->text( 'sneaker' )->sort( 'name' )->slice( 0, 48 )->search();

XML importer

It’s now possible to import attributes, categories, customers, products and suppliers using Aimeos XML files. They are as flexible as the Aimeos data structures so you can import all items in a document oriented way. A simple example for a product XML import file would be:

<products>
    <product ref="test-article">
       <product.type>event</product.type>
       <product.code>test-article</product.code>
       <product.label>Test event</product.label>
       <product.datestart>2000-01-01T10:00:00</product.datestart>
       <lists>
          <text><textitem>...</textitem></text>
          <price><priceitem>...</priceitem></price>
          <media><mediaitem>...</mediaitem></media>
       </lists>
    </product>
</products>

The product XML export job produces the same XML format so you can share data between different Aimeos instances too.

Performance

Aimeos has gotten faster once more. Complex queries which ask for entries that reference items from other domains or have properties of a specific value are now lightning fast in all DBMS when using the *:has and *:prop search functions. To fetch all products which reference a specific attribute use:

$search = $manager->createSearch();
$func = $search->createFunction( 'product:has', ['attribute', 'default', 123 );
$search->setConditions( $search->combine( '!=', $func, null ) );
$products = $manager->searchItems();

To get notfied about queries which take longer than one second, a monitoring similar to the MySQL slowlog is now active. Furthermore, using utf8mb4 as charset in MySQL doesn’t have a performance drawback any more so it’s now used by default. Existing setups are migrated towards this charset if possible (requires MySQL >= 5.7.8).

SEO friendly URLs

In the past, Aimeos required the product ID to be part of the URL. Due to the simplifed index for product texts which contains the product URL name and due to optimized routes, the URLs of all detail pages can now look like

https://shop.com/My_cool_product

The product name in the URL can be localized for each language of corse.