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.

The new beta version contains a lot of improvements and focuses on:

• Even more performance
• Developer experience
• Code cleanup

Performance improvements

Aimeos is already known as ultra fast e-commerce solution for Laravel, Symfony, SlimPHP, TYPO3 and Flow/NeosCMS even for complex requirements. This release pushes the limits teared down by Aimeos #gigacommerce further with render times of 20ms and below if content caching is enabled. Without caching, response times are exceptional too compared to other shop systems and in the 2019.01 release, we reduced that time further.

First, we denormalized tables that use types, so the type code is now stored directly instead of the type ID. This saves several database queries per request. Additionally, it’s possible to retrieve related data for e.g. products filtered by type:

$manager->searchItems( $filter, ['text', 'price', 'product' => ['suggestion'] );

This fetches related products of type “suggestion” only instead of all related products. Especially for shops with many relations, this can be a huge performance improvement if components can’t be cached.

PHP 7.3 promises another huge performance improvement and we are testing that version every time. Unfortunately, there’s a bug in PHP 7.3 with prevents production usage yet. It seems that the PHP developers over-optimized opcode caching so PHP 7.3 produces wrong results: https://bugs.php.net/bug.php?id=77310

Simplifications for developers

One of the major goals for this Aimeos release was to simplify interfaces so the first steps for new developers are easier. As a result, creating managers, controllers and clients requires only:

$manager = \Aimeos\MShop::create( $context, 'product' );
$cntl = \Aimeos\Controller\Frontend::create( $context, 'catalog' );
$client = \Aimeos\Client\Html::create( $context, 'catalog/lists' );

Items with relations are fetched recursively now and a decorator limits the recursion depth to two levels. The allowed depth is configurable like everything else in Aimeos. This allows you to get all releated data you need at one without fetching and merging data from several calls to searchItems():

$products = $manager->searchItems( $filter, ['product', 'price', 'text] );

For bundle and selection products, the items in the result list contains the bundled and variant articles including prices, texts and related products.

Also, all newly created items have the status “enabled” by default and must be explicitly disabled if required. This saves many calls to “setStatus()” especially when implementing a new importer. The frontend controllers allow multiple category IDs for filtering so it’s possible to search for
products in multiple categories with one method call.

Code cleanups

Finally, a lot of old code has been removed due to the switch to document oriented managment of items. Especially in the index managers and the filter criteria implementation was some code left after the changes required to use ElasticSearch natively.

The 2019.x releases are the last ones that will support PHP 5 as 5.6 isn’t maintained any more since this year. You should use PHP 7 nevertheless to get the best performance.

For a full list of backward incompatible changes, please have a look at the Wiki article. BC breaking changes in 2019.01 are listed up to 2018-12-31:

https://aimeos.org/docs/Developers/Changelog/2019

Neos is well known for its well designed interface for editors who quickly fall in love with the system. On the other hand, it’s also infamous for being hard to set up by starters due to its high demands towards the hosting environment. Someone also compared it to walking on a slack line: It’s easy to stumble and to get frustrated.

This article focuses on creating a hosting environment suited for Neos so you will be able to finish the Neos setup and get a running instance afterwards. I’m using Ubuntu 14.04 as reference but it also applies to other Linux distributions like Fedora, only the path names might differ a bit (/etc/apache2/ vs. /etc/httpd/).

Required software

At first, you need to make sure that the required software is installed. Apache, MySQL and PHP might be obvious but that’s not enough. Especially the additional Apache and PHP modules are important to get it running at all. You will have a good start with these packages:

• Apache 2.2+
• MySQL 5.1+
• PHP 5.3.2+
  • mbstring
  • tokenizer
  • pdo_mysql

Even if the minimum requirement for PHP is version 5.3.2, it’s better to use newer versions for performance reasons. Also, the requirements for Neos will be PHP 5.5+ for Neos 2.0.

You can install the required packages via the package manager of your distribution (apt-get for Ubuntu/Debian, rpm for Fedora/SuSE):

To check if all required PHP extensions are available, the easiest way is to place a short PHP file named info.php in your Apache document root directory (usually /var/www/) containing this content:

If you open http://localhost/info.php in your browser, the output will contain the environment, the configuration settings and the installed modules available in your installation. Search for the strings “mbstring”, “tokenizer” and “pdo_mysql”. There should be sections with this names in the rendered page.

Apache configuration

Most often, the first problems occur due to an insufficient Apache configuration. Neos uses .htaccess files and needs some modules that are not activated by default all the times. The “mod_rewrite” and “mod_env” modules are the best examples for this. To enable them in your Apache configuration, you need to execute these commands on the command line:

If you got the message that one or both modules had been already enabled then this was set up correctly before.

The VHost configuration is another common source of problems and you have to adapt it for sure. The default configuration is located in /etc/apache2/sites-enabled/000-default.conf (in Fedora or other Linux distributions the files might be located somewhere else). In this file, change the DocumentRoot to the Neos ./Web/ directory, e.g.

Furthermore, you need to add a “Directory” directive below the “DocumentRoot” line to allow the Neos .htaccess file to add rewrite rules and some settings:

If there’s already a “Directory” section available, replace it with the lines above.

The last task is to restart Apache:

Now you should be at able to open at least http://localhost/setup in your browser but beware: http://localhost/index.php/setup still won’t work!

PHP configuration

There are various PHP settings that can cause your Neos installation to fail. First of all you should have a look into the output of the info.php file again and check if one of the required PHP functions is disabled. This is often the case for security reasons in shared hosting environments and this leads to errors afterwards. Especially check the disable_functions line in the core section for:

• system
• shell_exec
• escapeshellcmd
• escapeshellarg

If non of these function is listed there, then you are on the safe side.

The next problems are lurking in your PHP configuration but that can be fixed either by adding a few lines to your /etc/php5/apache2/php.ini or to the .htaccess file in the Neos ./Web/ directory. When using the php.ini file you should add these lines at the end of the file:

In case you are allowed to overwrite settings also via the .htaccess file, you can add these lines to the ./Web/.htaccess of your Neos installation:

Neos can be very memory consuming so even the standard memory limit of 128MB can be to low. Errors due to an insufficient memory limit are written to the Apache error log file (usually in /var/log/apache2/error.log) so it’s a good idea to keep an eye on the content of that file.

The magic_quotes_gpc directive has been removed in PHP 5.4 and was already deprecated before. To disable it for PHP 5.3 is only a safety measure for installations that have been constantly updated during the last years.

For the timezone value you can use any valid timezone if it fits better for your location. A list of valid timezones is available at the PHP web site.

When you’ve installed the PHP XDebug extension you might run into error messages like Maximum function nesting level of '...' reached. Only in this case you need to increase the XDebug nesting level for functions.

Done!

Finally, you should be able to open the Neos setup page in your browser, that is available at http://localhost/setup. The rest of the installation is usually a non-brainer due to the nice setup routine provided by the Neos installer.

Afterwards you can enjoy Neos. Happy editing!