Refactor: Change docroot to public to align with Symfony's best practice structure

[matbcvo]

This PR updates the project structure to align with Symfony's best practices by renaming the docroot directory to public. This change ensures consistency with Symfony's default directory structure, as outlined in the Symfony Best Practices documentation.

Fixes #6

Changes

• Updated composer.json to reference public instead of docroot.
• Updated README.md to replace all references to docroot with public.

A PR needs to be created in the mautic/user-documentation repository to update the Composer installation steps related to the web root for the 6.x version.

[RCheesley]

cc @mautic/education-team-leaders for when you've made the 6.x branch - let us know :)

[escopecz]

I see no issues from the code change perspecitve. Will this work for people upgrading from Mautic 5?

[RCheesley]

I guess we would have to do some magic in the upgrade process to move/rename the folder, and/or make it very clear about it being a breaking change? I don't know why it was called docroot in the first place, but I suspect it's because the whole composer process took a lot of inspiration from Drupal's implementation, which I believe uses docroot.

[matbcvo]

I don’t see any reason why it wouldn’t work for users upgrading from Mautic 5.

Users upgrading from Mautic 5 have two choices:

• Keep the web root set to docroot/ (or another directory, depending on the hosting provider) in the composer.json file, or
• Switch the web root from docroot/ to public/ using the instructions provided in the README.md file (these instructions will also be included in the user documentation).

When a user upgrading from Mautic 5 replaces the entire composer.json file with the newer version, the web root will change from docroot/ to public/ unless the user manually changes it back. The user documentation should highlight this web root change so users know what actions they need to take - either revert the web root to docroot/ in the composer.json file or proceed with the switch to public/ using the provided instructions.

[matbcvo]

I could add a Composer script that updates the web root from docroot/ to public/ in the composer.json file and renames the web root directory accordingly. Users could then run this script (eg, composer migrate-webroot) during the upgrade process if they choose to switch to public/. I don’t think it would be ideal to include this in the composer update command, as some users might prefer to keep docroot/.

[escopecz]

That would be helpful. Is the docroot present also in config/local.php file when Mautic is installed via Composer?

[matbcvo]

Config parameters containing docroot/, which are related to the media directory, appear in config/local.php when saving the configuration after installing Mautic via Composer. After changing the web root and re-saving the configuration, those paths are not overwritten. So, they need to be manually updated in config/local.php. This can also be done using a Composer script.

<?php
$parameters = array(
	// ...
	'upload_dir' => '/var/www/vhosts/test.example.com/docroot/media/files',
	// ...
	'form_upload_dir' => '/var/www/vhosts/test.example.com/docroot/media/files/form',
	// ...
	'contact_export_dir' => '/var/www/vhosts/test.example.com/docroot/media/files/temp',
	// ...
	'report_temp_dir' => '/var/www/vhosts/test.example.com/docroot/media/files/temp',
	// ...
);

[RCheesley]

Is this OK to go now @escopecz from your side?

[matbcvo]

Since M6 has already been released, I think it's better to rebase this PR onto 7.x and update the README.md file accordingly.

[RCheesley]

Yes, I think that'd be a sensible approach as it'd be a breaking change, right?

[matbcvo]

I would like to get this PR merged, but I've started to think that the current solution isn't ideal. The escaped PHP code is hard to read and maintain (and I'm sure @escopecz doesn't like it either).

To address this, I've created a Composer plugin instead, which is more readable and maintainable. At the moment the repository is under my GitHub account, but I can transfer it to the Mautic org and let Ruth set up the Packagist package. The plugin works in the same way as the Mautic scaffold Composer plugin. We would just need to add it to the require section of composer.json instead of using the escaped PHP code under scripts.

@escopecz, do you prefer this approach? If so, can we move forward with it?

https://github.com/matbcvo/mautic-migrate-webroot

Testing steps:

# Create test folder
mkdir test-webroot-migration

# Move into test folder
cd test-webroot-migration

# Download composer.json from mautic/recommended-project 7.x branch
wget https://raw.githubusercontent.com/mautic/recommended-project/refs/heads/7.x/composer.json

# Install the plugin
composer require matbcvo/mautic-migrate-webroot

# Check that the command is available
composer list

# Run the command
composer mautic:migrate-webroot

# Verify that:
# - composer.json has been patched (compare with composer.json.backup)
diff composer.json composer.json.backup
# - webroot has been renamed from docroot/ to public/
ls -al

$ diff composer.json composer.json.backup
113c113
<       "MauticPlugin\\": "public/plugins/"
---
>       "MauticPlugin\\": "docroot/plugins/"
134c134
<         "web-root": "public/"
---
>         "web-root": "docroot/"
138c138
<       "public/app": [
---
>       "docroot/app": [
141c141
<       "public/plugins/{$name}": [
---
>       "docroot/plugins/{$name}": [
144c144
<       "public/themes/{$name}": [
---
>       "docroot/themes/{$name}": [

[escopecz]

Much better than debugging PHP in a JSON file. I'm thinking the new repo and composer package is quite an overhead. Could it be part of Mautic itself?

Or even could it be a Doctrine migration? Similar to what we did when we were moving the local.php file?

[matbcvo]

I'm not sure a Doctrine migration is the right fit here. I see this as an optional step: new installations would default to public/, while existing projects can choose whether to migrate (as discussed in issue #6). A Doctrine migration would force the change, but some user may prefer to keep their webroot as docroot/.

Since this only applies when Mautic is installed via Composer (mautic/recommended-project), the Composer plugin approach seems to make sense for me. We could add this command into the existing Mautic scaffold Composer plugin to avoid creating a separate repository/package. Another option would be to add the command into Mautic, but then we'd need to check whether it was installed via Composer and not from the .zip package, since that one doesn't define a separate webroot - all files there are at the same level.

[escopecz]

I'd like to avoid adding a dependency just to rename a folder. So perhaps a Mautic command then? That would check the name in the json file of this repo and if that's not right rename the folder?

Do we even want to support multiple dir names? I think that if we want to rename in this project then everyone should follow. Because otherwise a year from now someone will make some change and won't test with the original folder name and users will get issues.

TBH I'm not sure if it would be simpler to change the doc instead of this configuration. It seems it is way more complicated than useful. Or am I missing some good reason for the renaming?