Asgardcms Installer Laravel Package

Getting Started

The AsgardCms installer is a global Composer binary in the same mould as laravel/installer: it doesn't do anything inside your application at runtime, it exists to scaffold a fresh AsgardCms project from the asgardcms/asgardcms skeleton. Treat it as a one-shot developer-machine tool, not an application dependency.

Minimal path from zero to a running install:

# 1. Install the binary globally (once per machine)
composer global require "asgardcms/asgardcms-installer"

# 2. Ensure the global Composer bin dir is on your PATH
#    (usually ~/.composer/vendor/bin or ~/.config/composer/vendor/bin)
export PATH="$PATH:$HOME/.composer/vendor/bin"

# 3. Scaffold a project
asgardcms new blog

# 4. Finish the CMS-specific setup from inside the project
cd blog
php artisan asgard:install

Where to look first after scaffolding:

1. config/asgard.core.php (and the other config/asgard.*.php files) — this is where core behaviour, module/theme paths, and middleware groups are configured. Almost every day-to-day tweak starts here.
2. Modules/ — every feature in AsgardCms is a module. Reading one bundled module end-to-end (routes, controllers, repositories, events, migrations) teaches you the package's conventions faster than any docs.
3. Themes/ — front-end is theme-driven, separate from the module layer.
4. php artisan list — run it early and grep for asgard: and module:. The artisan surface is the real API of the package.

First use case: stand up a local dev instance, log into the admin panel, and create one custom module with php artisan module:make Blog so you understand the module lifecycle before touching a real project.

Implementation Patterns

Scaffold-then-pin, not scaffold-latest. Because the skeleton is resolved at install time, the version you get depends on the installer build and Packagist state. For anything you intend to keep, immediately commit composer.json/composer.lock after the first composer install, and record the installer version you used in your README. On a team, that's the difference between reproducible and "works on my machine".

Bypass the installer in CI and Docker. The installer solves a human problem (typing a long create-project command). In automation, skip it and call Composer directly:

composer create-project asgardcms/asgardcms blog --prefer-dist --no-interaction

This removes a global-binary dependency from your build image and gives you explicit control over version constraints.

Use it as a disposable-sandbox generator. The most valuable day-to-day use of a CMS installer is spinning up a throwaway instance to test a module or theme against a clean core:

asgardcms new /tmp/sandbox-$(date +%s)
cd /tmp/sandbox-*/
php artisan asgard:install
# symlink or copy your module in, run migrations, iterate

Because module code lives in Modules/, this is cheap and safe — you never have to risk your primary app to answer "does this still install cleanly?"

Non-interactive install for scripted setup. The asgard:install command is interactive (admin user, database credentials). For repeatable environments, prefer driving setup through .env + php artisan migrate --seed where the command allows it, or wrap the interactive command with expect/printf piping. Check php artisan help asgard:install for --no-interaction support before assuming prompts will be skipped automatically — several Laravel-era commands gate interactivity inconsistently.

Integration with an existing Laravel app is not supported by this package. The installer produces a whole application, including its own composer.json, config/, and public/. If you're tempted to composer require asgardcms/asgardcms-installer inside an existing project, don't — you want asgardcms/asgardcms (the core) and manual module registration instead. Mixing the two is the most common structural mistake with this package family.

Gotchas and Tips

It's a scaffolding tool with a short half-life. The installer's own version rarely matters; the skeleton's does. If asgardcms new produces a project that fails composer install or dies on boot, the problem is almost always the skeleton/core's compatibility with your PHP version, not the installer. Diagnose by running the underlying composer create-project manually so you see the real dependency-resolution errors instead of the installer's terse wrapper output.

PHP version drift is the primary failure mode. AsgardCms is a Laravel 5.x-era codebase. Modern PHP (8.1+) will produce deprecation noise at best and hard failures (removed each(), dynamic properties, str_contains polyfill conflicts, facade/ignition vs spatie/ignition mismatches) at worst. If you must run it, pin PHP to a matching minor version in a container rather than trying to modernise the dependency tree — that fight is not winnable for a day-to-day tool.

Global binary name collision. The installer registers a asgardcms executable. If you also have laravel/installer globally installed, both live in the same bin directory and neither interferes — but a stale ~/.composer/vendor/bin entry in $PATH from an old Composer 1 layout is a classic "command not found after install" cause. Confirm with composer global config bin-dir --absolute and use that exact path.

.env and key generation are not guaranteed. Depending on installer version, the scaffold may leave .env unset or APP_KEY empty. Always check and run php artisan key:generate before concluding the install is broken.

Permissions bite on the storage and cache dirs. The installer creates files as your current user; if you later run the dev server or queue workers as a different user (or under Docker with a bind mount), you'll get silent 500s. chmod -R ug+rw storage bootstrap/cache immediately after scaffolding saves an hour of confusion.

Extension points live in the skeleton, not the installer. You cannot customise what asgardcms new generates without forking the installer and pointing it at your own skeleton repository. If your team needs a standardised AsgardCms baseline (pre-installed modules, house config), maintain a private skeleton repo and use composer create-project your/org-skeleton — that's the supported pattern, and it's a one-line change for developers versus teaching everyone installer internals.

Debugging tip: the installer is tiny. Read its src/ (typically a single Symfony Console NewCommand plus Application) rather than searching for docs — the whole behaviour, including which package it pulls and what post-install commands it runs, is visible in a few hundred lines. That's the fastest way to answer "what did it actually do to my machine?"

Assess maintenance before betting on it. At 28 stars and clearly a thin wrapper around core AsgardCms, this package inherits all of core's staleness. For a greenfield project, treat the installer as a curiosity and evaluate AsgardCms core's activity level first; for an existing AsgardCms codebase, it's convenient but entirely optional, and composer create-project is a perfectly adequate substitute.