Folder structure that will be used to support Composer natively

Add your comments directly to the page. Include links to any relevant research, data, or feedback.

Background

We want to move to supporting Composer-base install and upgrades natively in Mautic. To do that we have identified several challenges:

  • Composer would wipe out everything each time, so we need to change the structure to prevent that happening otherwise custom plugins and themes would be lost,

  • Local.php will need to be moved to the database as some file systems are not writeable, and many using Composer will expect this - at present there are all kinds of hacky things going on to work around it like creating an empty file,

  • Plugin and theme discovery is difficult - it should be possible to look for the folders rather than pre-specify the locations so that they can be moved to suit the environment,

  • We are essentially moving from being a Symfony project to being a library - this needs to be taken into consideration

We need to brainstorm the folder structure that we need, and come to an agreement of what it would be:

  • Would have to be released in 4.0, we expect, but we can work on it now and get those decisions made

  • We need to think about shared hosting and make it configurable so Mautic can still work without the folders being a level above - this should be the default with an option during the install process to move it

Questions / discussion points

  • Multiple Mautic instances - would that be a problem?

 

Suggested Composer package structure

 

http://github.com/mautic/mautic

The project as seen from the outside and where PR’s are made against. Like it is today

http://github.com/mautic/app or mautic/core?

Git subtree split from the github.com/mautic/mautic/app folder. To be discussed if we need to change this to core.

http://github.com/mautic/core-recommended

Separate package to guarantee that all of the dependencies from mautic/core

http://github.com/mautic/core-composer-scaffold

Composer plugin to make sure we can have some mautic knowledge similar to https://github.com/nickveenhof/mautic-core-composer-scaffold

It would all come together in a project called http://github.com/mautic/recommended-project similar to https://github.com/nickveenhof/mautic-project

 

This means we have the following as required packages in recommended-project

 

"mautic/core-composer-scaffold": "^4.0"

"mautic/core-recommended": "^4.0"

 

Suggested folder structure

This also means that the following folders and files should be generated from within the scaffold resource folder in mautic/core

index.php (first time setup coming from app/assets/scaffold/files/index.php)
.htaccess (first time setup coming from app/assets/scaffold/files/.htaccess)
app → Core Mautic application coming from mautic/core
themes/contrib → themes downloaded by composer (public)
themes/contrib → themes downloaded by composer or custom written (private)
plugins/contrib → plugins downloaded by composer
plugins/custom → plugins from own packagists or custom code
media/ → all media files similar to today including the different folders
config/ → Configuration (user created)
vendor/ → All dependencies from composer

Alternative folder structures possible with composer

web/index.php (first time setup coming from app/assets/scaffold/files/index.php)
web/.htaccess (first time setup coming from app/assets/scaffold/files/.htaccess)
web/app → Core Mautic application coming from mautic/core
web/themes/contrib → themes downloaded by composer (public)
web/themes/contrib → themes downloaded by composer or custom written (private)
web/plugins/contrib → plugins downloaded by composer
web/plugins/custom → plugins from own packagists or custom code
web/media/ → all media files similar to today including the different folders
config/ → Configuration files
vendor/ → All dependencies from composer

This means the in the mautic/core (or mautic/app) we should also have folders such as app/plugins and app/themes where the core plugins and core themes live

Options considered

Mautic core/app folder name

Option 1:

Option 2:

Mautic core/app folder name

Option 1:

Option 2:

Description

core

app

Pros and cons

In line with Drupal project and easier to learn from

a change in how mautic works today

The folder stays similar as it is today

Harder to map when learning from the Drupal project

Estimated cost

Medium

Medium

Action items

Outcome