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 new 2.0 major release of the PHP map package is available which includes new methods and support for working with multi-dimensional arrays in an easy way. Additionally, it comes with the best documentation ever so you find everything you need quickly!

Instead of applying independent PHP functions on arrays, use the PHP Map object to stream array data through several methods to transform, order and shorten its elements until the result exactly conforms to your requirements, for example:

$data = [
    ['name' => 'Tom', 'dep' => 'Dev', 'qty' => 30],
    ['name' => 'Bob', 'dep' => 'Sales', 'qty' => 50],
    ['name' => 'Joe', 'dep' => 'Dev', 'qty' => 10]
];
 
// get the person with the highest quantity in "Dev" department
$name = map( $data )
    ->groupBy( 'dep' )->only( 'Dev' )
    ->flat( 1 )->col( 'name', 'qty' )
    ->ksort()->last();

To get the result in one statement is easier and much more elegant than the traditional way in PHP. The PHP Map object is perfectly suited to work on result sets returned by relational databases. You can transform them until you get a collection that exactly fits for your template generating the HTML for the frontend.

The PHP Map package combines the best from Laravel and CakePHP collections, jQuery, Backbone.js, and Lodash in an easy to use PHP package for every PHP application.

What’s new in PHP Map 2.0

One of the biggest new feature is the ability to pass a path of keys as parameter to several PHP Map methods to work on nested arrays directly. Instead of writing own code for diving into multi-dimensional arrays, you can now use the available methods to e.g. get a value by using:

map( ['key' => ['to' => ['value' => 'yes!']]] )
    ->get( 'key/to/value' ); // returns "yes!"

This also works for more advanced methods like col() to reindex an array by using a nested key:

$data = [
    ['name' => 'Tom', 'addr' => ['zip' => '12AB', 'city' => 'NY']],
    ['name' => 'Bob', 'addr' => ['zip' => '23WD', 'city' => 'LA']]
];
 
$map = map( $data )->col( 'name', 'addr/zip' );
// ['12AB' => 'Tom', '23WD' => 'Bob']

By default, a dot (“/”) is used as seperator between the array key names but you can change that for the current map using the sep() method:

$map = map( $data )->sep( '.' )->col( 'name', 'addr.zip' );

If you want to use another seperator in all new PHP Map objects (existing ones will keep their separator), you can change the delimiter globally with the delimiter() method:

Map::delimiter( ',' );

It also returns the delimiter used before if you want to revert the used delimiter later in your code.

Breaking changes in PHP Map 2.0

The new major version contains a few breaking changes to avoid potential problems that came up in the past. You won’t be affected by most of them but you should have a look to prevent unexpected behaviour.

New slash separator

The most important change affects parameter values including slashes because they are now treated as path separators for nested arrays.

$data = [
    'item/id' => 1,
    'item/code' => 'test',
    'item/name' => 'Test'
];
 
map( $data )->col( 'item/code', 'item/id' );
 
// 1.x
[1 => 'test']
 
// 2.x
[]
// use instead
map( $data )->sep( '.' )->col( 'item/code', 'item/id' );

jQuery style method calls

You can call methods of objects in a map like this:

// MyClass implements setStatus() (returning $this) and
// getCode() (initialized by constructor)
 
$map = Map::from( [
    'a' => new MyClass( 'x' ),
    'b' => new MyClass( 'y' )
] );
$map->setStatus( 1 )->getCode()->toArray();

Before, the objects had been checked if they really implement the setStatus() and getCode() methods.

To avoid returning an empty map if the method name is wrong or the called method is catched by the __call() magic method, this isn’t the case any more. If the method isn’t implemented by all objects, PHP generates a fatal error now for better error tracing.

Second equals() parameter

The $assoc parameter of the equals() method to compare keys too has been removed and now, you must use the is() method instead:

// 1.x
map( ['one' => 1] )->equals( ['one' => 1], true );
 
// 2.x
map( ['one' => 1] )->is( ['one' => 1] );

New find() argument

The find() method now accepts a default value or exception object as second argument and the $reverse argument is at the third position now:

// 1.x
Map::from( ['a', 'c', 'e'] )->find( function( $value, $key ) {
    return $value >= 'b';
}, true );
 
// 2.x
Map::from( ['a', 'c', 'e'] )->find( function( $value, $key ) {
    return $value >= 'b';
}, null, true );

Semantic change in groupBy()

Before, items have been grouped by the key string itself if the key passed to groupBy() didn’t exist. To offer easier checking and sorting of the keys, an empty string is used as key now:

Map::from( [
    10 => ['aid' => 123, 'code' => 'x-abc'],
] )->groupBy( 'xid' );
 
// 1.x
[
    'xid' => [
        10 => ['aid' => 123, 'code' => 'x-abc']
    ]
]
 
// 2.x
[
    '' => [
        10 => ['aid' => 123, 'code' => 'x-abc']
    ]
]

Semantic change in offsetExists()

The offsetExists() method uses isset() instead of array_key_exists() now to be in line with typical PHP behavior. Thus, keys with NULL values are now treated differently:

$m = Map::from( ['foo' => null] );
 
// 1.x
isset( $m['foo'] ); // true
 
// 2.x
isset( $m['foo'] ); // false

Renamed split() to explode()

To avoid conflicts with the Laravel split() method and to be in line with the PHP explode() method, the static Map::split() method has been renamed to Map::explode(). Also, the argument order has changed:

// 1.x
Map::split( 'a,b,c', ',' );
 
// 2.x
Map::explode( ',', 'a,b,c' );

The PHP Map package contains many methods to ease your day to day work. They are extremely helpful in a lot of situations where you’ve written custom code up to now. This tutorial explains some of the most useful ones you don’t want to miss any more!

• Documentation at Github
• Composer package at Packagist

Installation

To use the PHP Map package, you have to add it to your composer based application:

composer req aimeos/map

Afterwards, there will be a map() function available, that creates a Map object which offers the methods explained.

col(): Map key/value pairs

There are numerous times when you need to transform an existing array into a list of key/value pairs. Think about a list of database records for example which should be indexed by ID instead of a sequential index. The col() method creates that without the necessity of a loop:

$rows = [['id' => 1, 'code' => 'a'], ['id' => 3, 'code' => 'd']];
$result = map( $rows )->col( 'code', 'id' );
 
// Result equals:
map( [1 => 'a', 3 => 'd'] );

This does also work with objects if they implement the magic PHP __get() method.

collapse() and flat(): Transform multi-dimensional arrays

Do you remember the last time when you had a multi-dimensional array and you needed a flat array of all elements? If you know the maximum depth, you can nest several loops but if not, you need to write a recursive function, which is very cumbersome. The Map object offers the flat() method, that can to do that in one line:

$array = [[1, 2], [3, [4, 5]]];
$result = map( $array )->flat();
 
// Result equals:
map( [1, 2, 3, 4, 5] );

There’s a similar method named collapse(), that does almost the same but keeps the key of each value. Thus, it will overwrite elements with duplicate keys (also numeric keys):

$array = [['a' => 1, 'b' => 2], ['c' => 3, ['a' => 4, 'b' => 5]]];
$result = map( $array )->collapse();
 
// Result equals:
map( ['a' => 4, 'b' => 5, 'c' => 3] );

Both methods accept the number of levels they should collapse or flatten as parameter. That way it’s easy to keep e.g. the third level and above unflattened or uncollapsed.

concat(), merge() and union(): Differences in combining arrays

In PHP, you can combine arrays using array_merge() or the + operator but their results are different. The PHP map package also offers the concat() method:

$one = [0 => 'a', 'b' => 2];
$two = ['b' => 3, 0 => 4];
 
$result = map( $one )->concat( $two );
//equals map( [0 => 'a', 'b' => 2, 1 => 3, 2 => 4] );
 
$result = map( $one )->merge( $two );
//equals map( [0 => 'a', 'b' => 3, 1 => 4] );
 
$result = map( $one )->union( $two );
//equals map( [0 => 'a', 'b' => 2] );

concat() combines the elements of both arrays but doesn’t care about their keys and the resulting list will contain all elements of both arrays. merge() which uses the array_merge() function overwrites existing string keys but renumbers numeric keys. union() is the same as using the + operator and doesn’t add elements whose keys does already exist.

equals(): Test if arrays contains the same elements

To compare arrays, PHP only offers the == and === operators. They return only true if both array contains the same elements with the same keys (and the same order in case of ===). Contrary, the equals() method of the Map object can also test arrays without checking the keys:

$one = ['a', 'b'];
$two = ['b', 'a'];
 
map( $one )->equals( $two ); // true
map( $one )->equals( $two, true ); // false

When passing true as second parameter, equals() works like the == operator.

find(): Return the first matching element

Sometimes, you need the first element from an array that matches your needs. The Map object offers the find() method which allows you to pass a closure function as parameter. This anonymous function can check whose element matches your needs:

map( ['a', 'c', 'e'] )->find( function( $value, $key ) {
    return $value >= 'b';
} );
 
// Result equals 'c'

If no matching value is found, null is returned. If you pass true as second parameter, the search for the matching element will be reversed and you will get the last matching element.

first(), last(), get() and pull(): Advanced ways to retrieve an element

Fetching the first, last or any element of a list of elements is very handy and most useful in many cases. But the PHP Map object offers more than that. What if those methods don’t return null if no element is found but throw an exception or execute a closure? Instead of:

if( ( $item = map( [] ) )->first() === null ) {
    throw new \Exception( 'error' );
}
 
if( ( $item = map( [] ) )->last() === null ) {
    // fetch and return record from database
}
$id = $item->getId();

you can simply write:

$id = map( [] )->first( new \Exception( 'error' ) )->getId();
 
$id = map( [] )->last( function() {
    // fetch and return record from database
} )->getId();

All methods (first(), last(), get() and pull()) methods accept either an exception that’s thrown or a closure that’s executed if no element is available. Thus, it saves you the annoying checks that make you code full of if/else statements.

If you pass an exception, the exception object is created whether it’s used or not. This is no problem as long as you don’t do that in a loop. Then, create one exception object before the loop and pass only the variable to the methods.

in(): Check if several elements are in the list

To test if an value is in a list of elements with in() isn’t much different than using in_array(). But what if you need to do that several times with different elements? Then, in() takes away the burden of doing that within a loop:

map( ['a', 'b', 'c'] )->in( 'b' ); // true
map( ['a', 'b', 'c'] )->in( ['b', 'a'] ); // true
map( ['a', 'b', 'c'] )->in( ['d', 'a'] ); // false

The in() method of the Map object checks if all elements of the passed array are available in the list and only then it returns true.

toJson(): Encode everything into JSON

When working with APIs, you almost always need to encode the result into its JSON representation. The PHP map object offers a convenient way to transform all elements to JSON:

map( ['a', 'b', ['c', 'd'] )->toJson();

Like the PHP json_encode() method, it accepts a parameter for passing options that are used during encoding the elements. There are two that you may find extremely useful:

map( ['a', 'b', ['c', 'd'] )->toJson( JSON_FORCE_OBJECT|JSON_HEX_QUOT );

JSON_FORCE_OBJECT always creates {}, even for empty lists to avoid being encoded as []. If you add JSON output to HTML data attributes for storing something you need for dynamic Javascript features later on, JSON_HEX_QUOT saves you from generating invalid HTML.

walk(): Visit each value in a multi-dimensional array

You receive a multi-dimensional array from an HTML form and want to make sure that all values are of a certain type or doesn’t contain HTML tags? Then, the walk() method of the PHP Map object is your friend:

map( ['a', 'b', ['c', '<b>d</b>'] )->walk( function( &$val ) {
    $val = strip_tags( $val );
} );

You can also create a mapping based on the list you pass as second parameter:

$mapping = [1 => 'one', 2 => 'two', 3 => 'three', 4 => 'four'];
 
map( [1, 2, [3, 4] )->walk( function( &$val, $key, $data ) {
    $val = $data[$val] ?? $val;
}, $mapping );
 
// Result equals
map( ['one', 'two', ['three', 'four']] )

method(): Register your own methods

The best of all comes last: You can extend the PHP Map object by your own methods! This is extremely handy if you need the same code several times and different places. To register your own method, just do this:

\Aimeos\Map::method( 'strrev', function( $sep ) {
    return strrev( join( '-', $this->list ) );
} );

Your closure function has access to the internal array of elements using $this->list and you can read and/or modify that internal array of the Map object. You can use your new method the same way as any other method of the Map object afterwards:

map( ['a', 'b'] )->strrev( '-' );
// returns "b-a"

Conclusion

The PHP Map object offers some great methods that can simplify your code drastically and you will never want to miss them any more. Especially the possibility to register own methods to extend the Map object dynamically gives your great power in a few lines of code.

Arrays are the working horse of PHP, the programming language used by the vast majority of web applications. An array seems to be incredible simple to use but things get complicated and ugly when PHP functions for array manipulation come into play. Are you tired of hard to read code with excessive error handling too? Then maps can be the answer.

• Documentation at Github
• Composer package at Packagist

Why?

Here’s a common example of how array manipulation is done in most PHP code:

$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

It adds/removes elements, sorts and transforms the content and retrieves the first element. You can’t write that shorter or more elegant and moreover, you need to check almost all array functions for errors.

Using maps

The map composer package offers an easy API comparable to jQuery or Laravel collections:

composer req aimeos/map

When using the Map object, you can do the same as above more elegant with less code:

$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

And contrary to PHP arrays, you don’t have to care about error handling because either, there are no errors possible or the Map object will throw an exception if something is really wrong.

Of course, you can use the Map object still like a plain PHP array:

$map[] = ['id' => 'three', 'value' => 'value3'];
$value = $map[0];
count( $map );
foreach( $map as $key => value );

In addition, Map objects allow you to pass anonymous functions to a lot of methods. Thus, you can process and transform the elements according to your current needs, e.g. using the each() method:

$map->each( function( $val, $key ) {
    echo $key . ': ' . $val;
} );

You can even extend Maps dynamically by own methods. This is especially useful if you need a transformation of the Map elements more often and at several places of your code:

Map::method( 'strrev', function( $sep ) {
    return strrev( join( '-', $this->list ) );
} );
Map::from( ['a', 'b'] )->strrev( '-' );

The best part is using a Map like a jQuery object, where methods are applied to all objects of the Map. Then, you can create expressive code in one line:

class MyClass {
    private $code;
    private $status;
 
    public function __construct( $code ) { $this->code = $code; }
    public function setStatus( $s ) { $this->stat = $s; return $this; }
    public function getCode() { return $this->code; }
}
 
$objects = Map::from( ['a' => new MyClass( 'x' ), 'b' => new MyClass( 'y' )] );
$result = $objects->setStatus( 1 )->getCode()->toArray();

The example will call setStatus( 1 ) on all objects and creates a new Map with the returned values. Because setStatus() returns the same object ($this), we can apply another method on all objects afterwards (getCode()). The results of getCode() is wrapped in a Map object again and toArray() returns a plain PHP array which consists of:

['a' => 'x', 'b' => 'y']

Available methods

The Map object contains methods for almost all array functions available and more like collapse(), flat(), toJson() or methods found in the Javascript Array prototype. Here’s a list of its methods and for documentation, have a look at the Map readme at GitHub where you can also check the code.

• function is_map() : Tests if the variable is a map object
• function map() : Creates a new map from elements
• arsort() : Reverse sort elements with keys
• asort() : Sort elements with keys
• chunk() : Splits the map into chunks
• clear() : Removes all elements
• col() : Creates a key/value mapping
• collapse() : Collapses multi-dimensional elements
• concat() : Combines the elements
• copy() : Creates a new copy
• count() : Returns the number of elements
• diff() : Returns the missing elements
• diffAssoc() : Returns the missing elements and checks keys
• diffKeys() : Returns the missing elements by keys
• each() : Applies a callback to each element
• empty() : Tests if map is empty
• equals() : Tests if map contents are equal
• filter() : Applies a filter to the map elements
• find() : Returns the first matching element
• first() : Returns the first element
• firstKey() : Returns the first key
• flip() : Exchanges keys with their values
• flat() : Flattens multi-dimensional elements
• from() : Creates a new map from passed elements
• get() : Returns an element by key
• has() : Tests if a key exists
• in() : Tests if element is included
• includes() : Tests if element is included
• intersect() : Returns the shared elements
• intersectAssoc() : Returns the shared elements and checks keys
• intersectKeys() : Returns the shared elements by keys
• isEmpty() : Tests if map is empty
• join() : Returns concatenated elements as string
• keys() : Returns the keys
• krsort() : Reverse sort elements by keys
• ksort() : Sort elements by keys
• last() : Returns the last element
• lastKey() : Returns the last key
• map() : Applies a callback to each element and returns the results
• merge() : Combines elements overwriting existing ones
• method() : Registers a custom method
• pipe() : Applies a callback to the map
• pop() : Returns and removes the last element
• pull() : Returns and removes an element by key
• push() : Adds an element to the end
• random() : Returns random elements
• reduce() : Computes a value for the map content
• remove() : Removes an element by key
• replace() : Replaces elements recursively
• reverse() : Reverses the array order
• rsort() : Reverse sort elements
• search() : Find the key of an element
• set() : Overwrites an element
• shift() : Returns and removes the first element
• shuffle() : Randomizes the element order
• slice() : Returns a slice of the map
• sort() : Sorts elements
• split() : Splits a string into map elements
• splice() : Replaces a slice by new elements
• toArray() : Returns the plain array
• toJson() : Returns the elements in JSON format
• uasort() : Sorts elements with keys using callback
• uksort() : Sorts elements by keys using callback
• union() : Combines the element without overwriting
• unique() : Returns unique elements
• unshift() : Adds an element at the beginning
• usort() : Sorts elements using callback
• values() : Returns all elements with new keys

Again, the Map documentation offers descriptions, explains parameters/return values and has examples for each method. Some methods are even better documented than the corresponding PHP array function.

Conclusion

Map objects are an easy to use and elegant way to handle PHP arrays. After using it for a while you won’t want to remember the times before. If you’ve already worked with jQuery and like it’s simplicity, you will feel like home when using appropriate lists of objects in your application.

As the Map methods are using the native array functions or are highly optimized, it’s also save to use them in large scale applications. The documentation contains a section about the Map performance and hints to avoid performance bottlenecks.

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!