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.

What are cache groups

In the TYPO3 caching framework, there are currently three types of caches:

• pages : Front-end related caches
• system : Low-level caches that shouldn’t normally be flushed
• all : All other caches that don’t fall into one of the two categories before

Based on the cache type (a.k.a cache group) the caches are flushed on different occasions. This makes a difference for the editors because depending on what they have changed, most often one of the cache groups will be flushed as well. Also, there are at least two options available when editors decide to flush the caches manually:

The first option will only flush front-end related caches while the second one flushes all caches that are not in the “system” or “pages” cache group. Flushing the “system” caches isn’t that easy any more but those don’t need to be cleared at all by editors. Instead, they are automatically flushed if e.g. a new extension is installed.

Therefore, it makes sense to tell TYPO3 which cache group your cache should be in if you use the caching framework to store data temporarily. This allows at least editors to selectively flush caches instead of the famous “flush all caches to be sure”! More information about which cache in in which cache group can be found in the article about the TYPO3 caching architecture.

Set up your extension cache

To create your own cache in your TYPO3 extension, there are only a few lines in the ext_localconf.php of your extension necessary. You can copy and paste these lines and only have to replace the aimeos string by the name of your own TYPO3 extension:

if( !is_array( $TYPO3_CONF_VARS['SYS']['caching']['cacheConfigurations']['aimeos'] ) ) {
    $TYPO3_CONF_VARS['SYS']['caching']['cacheConfigurations']['aimeos'] = array();
}
 
if( !isset($TYPO3_CONF_VARS['SYS']['caching']['cacheConfigurations']['aimeos']['frontend'] ) ) {
    $TYPO3_CONF_VARS['SYS']['caching']['cacheConfigurations']['aimeos']['frontend'] = 'TYPO3\\CMS\\Core\\Cache\\Frontend\\StringFrontend';
}
 
if( !isset($TYPO3_CONF_VARS['SYS']['caching']['cacheConfigurations']['aimeos']['backend'] ) ) {
    $TYPO3_CONF_VARS['SYS']['caching']['cacheConfigurations']['aimeos']['backend'] = 'TYPO3\\CMS\\Core\\Cache\\Backend\\DatabaseBackend';
}
 
if( !isset($TYPO3_CONF_VARS['SYS']['caching']['cacheConfigurations']['aimeos']['options'] ) ) {
	$TYPO3_CONF_VARS['SYS']['caching']['cacheConfigurations']['aimeos']['options'] = array( 'defaultLifetime' => 0 );
}
 
if( !isset($TYPO3_CONF_VARS['SYS']['caching']['cacheConfigurations']['aimeos']['groups'] ) ) {
	$TYPO3_CONF_VARS['SYS']['caching']['cacheConfigurations']['aimeos']['groups'] = array( 'pages' );
}

The whole if/is_array/isset thing is necessary to allow administrators to overwrite your settings in the typo3conf/LocalConfiguration.php file as the configuration of your extension is loaded afterwards. Thus, it would overwrite any previous configuration settings if you don’t check first if they exist.

There are four settings you can use to configure your cache in the TYPO3 caching framework:

• frontend : What type of data is accepted
• backend : Where is the data stored
• options : Additional configuration settings for the back-end
• groups : The cache groups your extension cache belongs to

There’s the choice between two cache front-ends and several cache back-ends. A complete list of both including their options is available in the TYPO3 cache front-end/back-end article. The groups setting can be either pages, system, all or a combination thereof. Normally, you should use only one cache group and the group all is the default value if you don’t specify one.

Use your new cache

Once set up, you can access the cache everywhere in you TYPO3 extension and you only have to write a few lines:

$name = 'TYPO3\\CMS\\Core\\Cache\\CacheManager';
$manager = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance( $name );
$cache = $manager->getCache( 'aimeos' );

They create an instance of the cache manager and retrieve your cache by name. Replace aimeos with the name of your extension resp. the name you’ve used in your ext_localconf.php in the cache setup code. Now you are able to set and get cached entries or remove them from the cache again:

$cache->set( 'auniqueidentifier', $data, array( 'tag1', 'tag2' ) );
$data = $cache->get( 'auniqueidentifier' );
$cache->remove( 'auniqueidentifier' );

So, let’s go and make your TYPO3 extension fast!

The dark side

You will face the dark side of the bootstrap package when you try to use different languages than those configured as examples. There’s only a mapping between the value of sys_language_id and English, German and Danish available and if you try to add a mapping manually, RealURL immediately switches to the “manual mode” where you have to configure everything yourself once again.

Loosing the auto-configuration implies a lot of work, especially if you are using the Aimeos web shop extension or similar ones, which add a lot of RealURL rules out of the box. Thus, it’s very compelling to try to overwrite only the RealURL configuration which is responsible for the language ID/code mapping.

The bright side

Fortunately, the bootstrap package allows you to overwrite its RealURL auto-configuration rules including the preVars section which is responsible for the language mapping.

First of all, you need an extension for your project where you can add the RealURL rules to. You can either use the Kickstarter extension or the Aimeos extension creator. The automatic configuration requires a PHP class and method that will add new or overwrite existing RealURL rules. You should add it in the Classes/Realurl.php file of your extension. Copy this code to your new file:

The addAutoConfig() method replaces the second entry of the “preVars” array, which are exactly the language mapping rules in the bootstrap package. You can change or add as many entries in the “valueMap” array as you like. The array keys are the strings that will be shown in the URL while the values are the sys_language_id values of the languages you’ve configured in your TYPO3 page tree and TypoScript configuration.

Afterwards, you have to add your class to the RealURL hook that will call your method when collecting the rules for auto-configuration. This is done in the ext_localconf.php of your extension by adding these lines:

As above, you have to replace the <vendor> and <extname> placeholders with the same values you’ve used for the namespace statement.

Finally, clear your caches (TYPO3 general and frontend caches) and delete the typo3conf/realurl_autoconf.php file. Then, your languages should appear correctly mapped in your URLs.

So why not build an extension that works out of the box and configures itself as far as possible to give users an instant feeling of success? The constants.txt or setup.txt TypoScript files of the extensions can contain almost all default settings. But things get difficult if the required configuration depends on dynamic things like page IDs. Then, all hope of simplicity is lost and users have to add the necessary settings themselves again.

Is this really true?

The signal/slot mechanism described in the article about executing scripts after installing an extension provides the tools to get things done. Although, the article is very generic and I would like to go into more detail about how we’ve implemented things in the Aimeos web shop distribution.

The distribution imports some pages from the data.t3d file and the TYPO3 importer cares about avoiding conflicts with existing pages by reassigning the page IDs. Problems arose after we’ve added some required TypoScript settings for access restricted pages like the “MyAccount” page. In order to redirect to the login form when a user isn’t logged in, you have to configure its page ID. That seems to be impossible at the first glance when the page ID will differ in each TYPO3 installation.

The solution is to look up the page ID from the database dynamically after the extension is installed and generate a constants.txt file that will then contain the actual page ID. The constants in this file can be used in the TypoScript setup.txt file afterwards.

But first, you need to make sure your code will be executed automatically after the extension is installed. Remember the steps from the article about executing scripts? The first one was to register your extension for listening to the signal for extension installation:

Please replace <vendor>, <extension>, <classname> and <method> with the strings that fits for your extension. Afterwards, you must implement the method of your class you’ve registered for listening. We use the name of the Aimeos setup class in our example because you can have a look at it’s implementation for reference.

First we have to ensure that the constants.txt file is only created if our own extension is installed. Thus, we check for the extension name to filter out all other extension installations.

The TYPO3 backend utilities contains some nice methods to retrieve records from the database with only little effort. For example, you can use the getRecordsByField() method from the BackendUtility class to fetch all records from a table where a field matches a certain value. Here we want to get all records where the “title” equals “My account” from the “pages” table.

Make sure you generate valid TypoScript afterwards, including new lines and keep an eye on security by enforcing the types you are expecting! The foreach() loop is a great way to deal with no records and several returned records too because both can an will happen sooner or later. Don’t throw an exception if something unexpected happens because it may lead to not being able to install your extension at all! It’s better to drop those records and add a message to the log file.

At last, your extension has to write the TypoScript statements to the constants.txt file. The GeneralUtiltiy class from the TYPO3 core contains a little writeFile() helper function to get this done within one line.

Simple, isn’t it?

These few additional lines can make the difference between an easy installable extension and hours of frustrations bugging your users. I think the little effort during the development of your extension is worth the hours saved later on. Your users will thank you for your work by using your extension more often!

A special thanks for the inspiration to this tutorial goes to Stephan Schuler from netlogix.

Often, the remaining tasks of configuring the extension, adding new pages with the plug-ins from the extension or importing required data into the database becomes much more cumbersome. Why can’t life be not as easy as in other CMS? Just click and everything works?

Yes, we can!

The infrastructure for performing additional tasks after installing extensions is part of TYPO3 since some time. At least since TYPO3 6.2 it works flawlessly, before your way may vary. The trick is to utilize the signal/slot mechanism to connect to the Extension Management service and listen for signals emitted after an extension was installed.

In the Aimeos TYPO3 web shop extension we’ve added the following code to the ext_localconf.php:

The first line ensures that we are connecting only to the Extension Management service if we are in the back-end. If you leave this line out, your script would connect at every front-end request too, which would only slow down response times. The next two lines instantiates the signal/slot dispatcher class and the makeInstance() method of the GeneralUtility class does a good job.

The remaining lines connect your method executeOnSignal() of your namespaced class Aimeos\Aimeos\Setup to the Extension Management service whose class name is handed over as first parameter. Here we are listening to the hasInstalledExtensions signal, that is emitted by the service after an extension has been installed. The key of the installed extension will be passed as first parameter to our method.

Do what you need

At last, you need to create a class that contains the code to be executed after an extension is installed. The Aimeos TYPO3 extension contains a Setup class in the Classes/ directory of the extension with a method named executeOnSignal() to care about this. The basic code of this class is:

The namespace declaration is important but must be adapted to your extension. The first namespace part is the vendor name, e.g. the name of your company. The second part is the extension key with the first letter uppercased. If your extension key contains an underscore, then the underscore is removed and the next character transformed to uppercase as well, e.g. the boostrap_package uses BootstrapPackage as the second namespace part.

You are free to use any valid class and method name in your extension. Only make sure that the third and fourth parameter of the connect() method call are named appropriately. Also, ensure that your class and method are neither abstract nor static so an instance can be created. Like said above, the key name of the extension that has been installed is given as first parameter to your method. For compatibility reasons, you should make that parameter optional by assigning a default value of null.

What’s next?

Pretty simple, isn’t it? Now it’s time to pimp your TYPO3 extension to remove as much burden as possible from the user! In a second article we will go into more detail how this can save your users day when your extension imports pages and depending TypoScript configuration.

A special thanks goes to Benjamin Kott for his bootstrap_package because it was the first that provided a working example that the signal/slot infrastructure can be used for these kind of use cases.