The most unsettling end user guide to composer for Flarum

luceos

Seeing questions about composer commands arise often, let's whip up something for you to look at and sink in.

Everywhere i mention commands, replace composer with composer.phar if you installed composer by downloading it locally. You might need to prefix the command with php so that composer is parsed by php.
This guide is meant for end users, not developers. The commands hold flags that generate an optimised and slimmer vendor folder containing dependent packages.

Installing flarum:

composer create-project flarum/flarum -s beta <target directory> --prefer-dist --no-dev

Target directory is a relative path from where you currently are. The dot . can be used for the current directory. The target directory has to be empty or does not exist and can be created. The target directory cannot point to an non existing directory inside a non existing directory.

Install extension

composer require <vendor>/<package> --prefer-dist --no-dev -o --no-suggest
php flarum cache:clear
rm -f assets/rev-manifest.json

You can use composer require "<vendor>/<package>:*" to always pull the correct version of an extension for your Flarum version (useful if an extension has published a release made for a future version of Flarum).

Update extension

composer update <vendor>/<package> --prefer-dist --no-dev -o --no-suggest
php flarum cache:clear
rm -f assets/rev-manifest.json

Do not run composer update without a package unless you know what you're doing. Running it without a specific package will update all packages, which will result in a Flarum installation we haven't tested.

Uninstall extension

composer remove <vendor>/<package> -o
php flarum cache:clear
rm -f assets/rev-manifest.json

Please note uninstalling an extension via composer will cause database tables and resource files (images) to remain in your Flarum installation.

Install/reset

composer install --prefer-dist --no-dev -o --no-suggest

If you want to install all packages (based on the lock file).

Tips

Do not edit files inside the vendor directory. It is meant to be disposable.
The composer.lock file tracks the currently installed versions (the state) of all packages.
Deleting the vendor directory (rm -rf vendor) and running the install/reset command will completely reinstate the vendor directory holding all dependencies.
When taking backups make sure to exclude the vendor folder, but include the composer.lock and composer.json files as well as the assets folder!
If composer will not run on your server, use curl -s https://getcomposer.org/installer | php -- --check to check if there is a missing dependency for composer.

app

tl;dr How do I get rid the 500 error after modified the vendor files ?

Very good tips, I'm still wondering how flarum works behind the scene, its just this, I installed an extension or change a little bit of the translation and next thing is 500 and nothing more.

flarum cache:clean

doesnt work and I'm lost at where to start debug or whatever when encountered this 500. I have no trouble with PHP but with frameworks its different story. Sometimes exceptions were thrown and again, I'm lost. Why does it break with just a small change ?

clarkwinkelmann

app it often comes down to caching. The more is cached, the better the performance are. And right now beta7 isn't always properly clearing the cache when installing extension, hence why we have to run cache:clear manually.

If you are editing core files you're really shooting yourself in the foot because now you're bypassing both Flarum and Composer (the dependency management) caching/loading strategy. You need to make sure both of these have been rebuilt correctly before continuing.

Now if you're looking for a better explanation of your specific 500 you'll need to enable debug mode and look for messages in storage/flarum.log and your webserver/system logs ?

app

clarkwinkelmann
Ok thanks, that explain a lot about the need to refresh multiple times - its still creating the cache.
About the debug, I found the page.

Nope, not touching the core and as suggested - vendor is disposable (tried that just now with your command.)

New weird prob, I installed and extension, and it did not show up in the list ?
and
Am I correct to clean:cache and delete the rev-manifest.json every time I do something with vendor folder ?