Modules, extensions, and package operations

Know what each package changes

Modules add business capabilities, Extensions connect providers, and Themes control presentation. Core provides shared commerce and administration. A store preset is a convenience bundle of modules, not a permanent store type. See getting started.

First-party optional packages are distributed from the optional-packages repository. Core discovers materialized packages under storage/app/packages, or from explicitly configured locations. Do not assume a permanent modules/ or extensions/ tree inside Core.

Packages execute trusted application code. Installing a package is more privileged than editing a product. Restrict module/extension management permissions and review the source, version constraints, and dependencies before installation. A ZIP passing validation is not a security review of its PHP code.

Install and enable a first-party package

1. Take a backup before changes to a store with real data.
2. Open Admin → Modules or Admin → Extensions with the relevant management permission.
3. Select the available first-party package or module preset and install it. Read any compatibility or dependency error instead of overriding the manifest.
4. Check that the package is installed, then enable it when appropriate. Installation and enablement are separate lifecycle concepts; confirm the resulting state rather than assuming a click completed both.
5. For a provider extension, configure its settings after enablement and run the offered connection check.
6. Reopen the relevant product or operations screen and test the feature. A new navigation item alone is not proof of fulfillment.

The source configuration uses AGOVENA_PACKAGES_MONOREPO_URL and AGOVENA_PACKAGES_MONOREPO_REF. The default ref is main, a moving branch. For controlled deployments, choose an available immutable revision and verify its compatibility before updating. AGOVENA_OPTIONAL_PACKAGES_PATH is an explicit filesystem discovery option, commonly useful for sibling checkouts, not a requirement for merchant installations.

References: package configuration, Modules screen, and Extensions screen.

Custom packages and upload limits

The remote-install form supports Composer package name, version constraint, and an optional VCS repository URL. ZIP installation is also implemented. Use the exact metadata supplied by the package author, not a guessed Composer name or branch.

Core allowlists source hosts and limits archive size and contents. The ZIP form permits up to 51200 KiB, but supplied web-server templates cap requests below that. Adjust PHP, proxy, and web-server limits together if a reviewed package requires it; a larger UI allowance does not make the upload reach PHP.

Composer operations require an available executable and access to trusted package sources. AGOVENA_COMPOSER_BINARY can set its path. Package Composer state is isolated under storage/app/packages/composer; do not edit Core's dependency files merely to imitate an Admin package operation. See remote installation actions.

Update, disable, uninstall, or purge

Treat every lifecycle action as a change to a running store:

• Update: rehearse compatibility and migrations, preserve package files and the database, then verify the installed version and behavior.
• Disable: stops the enabled capability/provider path. Check active products, recurring work, dependencies, and incoming callbacks before disabling it.
• Uninstall: is not the same as purging files. The current action explicitly requests purgeFiles: false.
• Purge: is a distinct operation requiring recent-password confirmation. Read the package-specific data and filesystem implications before proceeding; never use it as a routine troubleshooting reset.

Do not remove package directories by hand while their installed state remains in the database. During a Core deployment, php artisan agovena:upgrade applies migrations to installed Modules and Extensions. It does not fetch a new package release for you.

Recover an interrupted operation

Preserve the error and current files. Check writable package storage, Composer/network access, compatible manifests, and any compensation-journal connection. Correct the cause before using the normal upgrade/recovery path. If schema changes partially committed, a clean application-file rollback may not be enough; use update recovery.

Never edit lifecycle database flags to make the UI look installed. Verify the actual package version, enabled state, migrations, provider settings, and merchant operation after recovery.