Setup a Magento module via setup:upgrade or not?

Technical installation of Magento

First of all, when you're dealing with the installation of a Magento module, you will need to get the files in place. Preferred choice is installing the module via composer (Packagist, private composer repository, path repository or something), but an alternative could be to upload the files to app/code/ (via FTP, hihi).

Next, Magento needs to know about the module. And this is where the instruction of running the command bin/magento setup:upgrade often kicks in. However, what does that command do and why should you not run the command.

Things that setup:upgrade actually does do

First of all, the command flushes the configuration cache and then cleans all caches (including the configuration cache). The double cleaning does not annoy me too much. In development, I keep cleaning the cache (either manually or by using the Mage2TV Cache Cleaner).

Next, the command tries to cleanup generated files - unless keep-generated flag is used. This is weirder. Yes, in development, you will be removing the generated/ folder repeatedly for a variety of reasons. But mostly, in the Developer Mode, a lot of this happens automatically. Removing the generated files anyway seems like a failsafe method. But if that failsafe is there, I wouldn't know why you would not want this (so, adding the keep generated flag) in development. On the other hand, if you are deploying to production, most likely your procedure first generates all files and then runs setup:upgrade - so during deployment, the flag should be set.

To continue, the next thing the command does is to recreate the module listing in the file app/etc/config.php. I personally think this is the number 1 reason why module developers started to mention this command in the first place. The configuration (enabled or disabled) of existing modules remains the same, but new modules are automatically enabled! Which is nice.

The next thing is that the search engine is validated. I'm not sure why you want to do this when you are just trying to enable a new module.

And finally, we reach the setup stuff. Unused database triggers are removed. Schemas are updated (Setup/ classes, db_schema.xml files, setup patches) - the database is updated. This usually takes the longest to complete. AND IT IS ABSOLUTELY NOT NEEDED WHEN YOUR MODULE IS NOT INCLUDING ANY DATABASE CHANGES.

The itch

So, here is the itch: The command setup:upgrade is not the command to enable a module. There is a different command for that: bin/magento module:enable Foo_Bar. Instead, the setup:upgrade command is there to upgrade the setup, which for the main part means to make changes to the database. To do so, you need to go through a series of steps. And it just happens to be that the command also enables modules that were not discovered yet. Note that in the past used to be different: In earlier Magento 2 versions, new modules were just simply disabled.

Using the command setup:upgrade for enabling modules, to my opinion, sets wrong expectations. It is better to be explicit about all steps. A proper Magento developer needs to thoroughly understand those underlying steps anyway.

How then to add a command?

I personally favor a different approach: I assume that people are only modifying a Magento instance if that instance is in the Developer Mode. When a module Foo_Bar therefore needs to be enabled, the following command needs to be executed:

bin/magento module:enable Foo_Bar

As part of this command, the cache is cleaned and the code is regenerated (in the Developer Mode). But no database upgrade, no search engine check, no double cache clean, no unneeded waiting.

It could be that the module in question also has database changes, so in that case, an additional command is needed:

bin/magento setup:upgrade

Ideally, there is a command that only runs the database changes belonging to a specific module, but unfortunately, we don't have that.

But note that the command setup:upgrade does not need to be run if the module does not include any database changes - it would be just a waste of time to wait for database upgrades where there aren't any. Also, if the modules does have a db_schema.xml and you are re-enabling the module, it could be that the schema has been created already. So it really depends whether or not this command makes sense to run.

This is a personal itch. Opinions of others are probably different. There will be dragons.