Summon a module or theme

$ grim require cart

The project is installed and running, and it needs one more piece: a cart, a payment gateway, a second frontend theme. grim require is the way to add it without opening grim.json. It picks the version for you, and the version it picks is not the newest one that exists. It is the newest one on the release train the project is already locked to, because a module from one train against the core of another is the combination trains exist to rule out.

For a project that has never been installed, or after editing grim.json by hand, the command is grim install.

Usage

$ grim require cart                  # one module and whatever it requires
$ grim require cart payments         # several at once
$ grim require monitor --frontend    # a frontend theme
$ grim require                       # pick modules from a list

Run it from the project root, next to grim.json. It does not look in parent directories. With no package name it loads the catalogue and asks; add --frontend or --admin and the list holds themes of that kind instead.

Arguments and options

Add and install a module or theme, pinned to the project train

Usage

grim require [--frontend] [--admin] [--] [<packages>...]

Arguments

Options

What it actually does

Every step is printed with its duration, and the first failure stops the run.

1. Checks the packages can be had. Each name is looked up on GitHub before anything is cloned. An archived, private or missing package ends the run with the full list and Nothing was installed.
2. Finds the train. The train recorded in grim.lock. Without a lock it resolves core from grim.json and takes that tag's MAJOR.MINOR.
3. Resolves dependencies. Each named module goes into requires as ~<train>, for example "cart": "~2.5". Then the whole of grim.json is resolved again, with only the tags of that train visible, so nothing in the closure can land outside it. The closure gets the same availability check as step 1.
4. Installs modules. Every module of the closure is a git checkout under src/<Module>/, at its resolved tag. Modules already at the right tag are left as they are.
5. Writes grim.json and grim.lock. The lock is rebuilt from what was installed: version, commit and requires of every module. Core and train are carried over.
6. Enables the modules you named in storage/config/modules-enabled.php.
7. Runs composer dump-autoload and php artisan migrate --force in the app container, when it is running.

It ends with a Packages added table: each package with its version, the train, and a Skipped row when something was left out.

Themes

With --frontend or --admin the names are themes, and the run is shorter: no dependency resolution, no autoloader, no migrations. The theme is checked out into resources/themes/<type>/<name> at its newest tag on the train.

A theme slot in grim.json can hold several themes, and the first one is the active one. The theme you require goes to the front of its slot; the ones already there stay installed behind it.

"themes": {
    "frontend": ["monitor:~2.5", "blank:~2.5"]
}

Pitfalls

A module that became part of core is skipped, not installed

It has no release of its own any more. The run succeeds, the summary says Skipped: webhooks (core since 2.5), and grim.json does not get the entry. Nothing to fix: the module is already in the project with core.

A theme with no release on the train is skipped quietly

The run still ends green. Read the Skipped row of the summary. The theme's maintainer has to release it on your train, or the project has to move to a train the theme is on with grim update.

Requiring a theme does not switch the running app to it

The order in grim.json decides what a fresh .env gets. An existing .env keeps its THEME_FRONTEND or THEME_ADMIN, and that is what the app reads. Change the value there and apply it with grim reload.

Nothing runs in a stopped project

With the app container down, the autoloader and the migrations are skipped without a word, and the steps still show as passed. Start the project and run grim artisan migrate.

Only the modules you named are enabled

Dependencies are installed and locked, but step 6 adds only the named packages to modules-enabled.php. If a dependency has to be switched on in the app, enable it yourself.

After it finishes

Commit grim.json and grim.lock together. To see what came along and why, ask grim why about any module you did not name.

$ grim why payments
$ git add grim.json grim.lock

Related spells

Recipes that use it