Mageforge Laravel Package

Getting Started

MageForge is a CLI toolchain aimed at Magento 2 codebases, but it lives in the same Composer/PHP world as Laravel, so the onboarding is familiar.

1. Install as a dev dependency (or globally if you work across several shops):

   composer require --dev openforgeproject/mageforge
   

2. Look first at the interactive menu — as of 0.28.0 there is a TUI-style entry point (MageForge Inspector actions) that lists every available command. Run the binary with no arguments (or ./vendor/bin/mageforge) and browse the menu before reading docs; it's the fastest way to discover what the tool actually does in your project.
3. Configure the package config file (published via the usual vendor:publish-style command or created on first run) — check it in, minus machine-specific paths.
4. First real use case: run the new template override command against a template you need to customise. It scaffolds the override in your theme/module instead of you hand-copying files and guessing the directory layout — the same ergonomics as artisan vendor:publish, but for view templates.

If you're a Laravel dev dipping into a Magento codebase for an integration, start with the Inspector menu, then use the override command; those two alone remove most of the "where does this file go" friction.

Implementation Patterns

Menu-driven exploration, scripted execution. The interactive menu (new in 0.28.0) is for humans; every action underneath is a discrete command. Discover in the menu, then copy the equivalent non-interactive invocation into your scripts/CI so runs are reproducible.

Template overrides as a repeatable step. Rather than committing hand-copied templates, treat the override command as the canonical way to introduce a template customisation. Chain it into a project bootstrap script so new environments/teammates get identical overrides.

Dependency updates as a pipeline, not a chore. 0.28.0 lands three related pieces:

• dependency updater command — updates dependencies on demand.
• auto dependency updater — runs the update path automatically (scheduled/CI).
• update cooldown for Dependabot — deliberately delays adopting fresh upstream releases as supply-chain protection.

The pattern that works: let the auto updater open PRs on a schedule, keep the cooldown on, and review the generated composer.json/composer.lock diff like any other dependency PR. Don't let it push straight to main.

Wrap it for Laravel-side teams. If your Laravel app orchestrates or seeds a Magento storefront, expose the handful of MageForge commands you actually use as thin artisan commands or Composer scripts ("post-install-cmd", "scripts": {"mage:override": "..."}). Keeps the team in one mental model and one command surface.

Keyboard shortcuts config (0.28.0). Commit the shortcuts config alongside the rest of the tool config so the whole team gets the same menu bindings — it's a shared dev-environment artifact, not a personal preference file.

Gotchas and Tips

• Interactive menu needs a TTY. Anything menu- or shortcut-driven will hang or fail in CI, Docker build steps, and composer run contexts without a terminal. Always call the underlying command explicitly in automation; if a command only exists inside the menu, that's a gap worth an issue.
• The auto dependency updater is the highest-risk feature here. It mutates dependency manifests. Gate it behind a branch + PR, pin the cooldown, and never run it against a dirty working tree — you want a clean diff to review.
• Respect the Dependabot cooldown. It was added specifically for supply-chain safety. Lowering it for "faster updates" trades a real risk for convenience; leave it at the default unless you have a reason.
• Template override collisions. Running the override command twice for the same template will either overwrite your edits or produce duplicates depending on flags. Check git status before and after; prefer running it on a clean tree, then diffing.
• CI action pinning matters even here. This release fixes a wrong SHA for peter-evans/create-pull-request — a reminder that if you vendor or mirror these workflows, pin by SHA and re-check pins on upgrade.
• Upgrade sanity check for 0.28.0. It's additive (new commands, menu, shortcuts, config), no deprecations or removals announced, so a minor-version bump is low risk. Still re-run your config publish step — new menu/shortcut config keys likely need merging into an existing published config, and stale configs are the usual cause of "the new command doesn't show up."
• Extension point: config-driven command registration plus the shortcut bindings are the natural places to add project-specific actions rather than forking the package.