ave-cms/help/en/modules/packages.md

Install module from ZIP

← To the “Modules” section

The control panel accepts an administrative module or a composite public/admin package AVE.cms. After checking, the archive is unpacked into the standard directory and installed immediately.

The module archives are distributed by the system owner. Requires two to download individual rights: managing modules and installing executable code.

Archive building

Don't create the ZIP manually. The regular collector adds the required manifest and checks the archive after packaging:

php tools/build-module-package.php modules/reviews
php tools/build-module-package.php adminx/modules/Notes

By default, the result is stored in storage/releases/modules/. The way is possible override with the parameter --output=....

Valid structure

Control panel only:

notes.zip
└── Notes/
    ├── module.php
    └── ...

Composite package:

reviews.zip
└── reviews/
	├── AVE-MODULE.json
    ├── app/
    │   ├── module.php
    │   └── ...
    └── admin/
        ├── module.php
        └── ...

A self-contained site package may also embed verified dependency archives:

site-package.zip
└── site_package/
    ├── admin/
    ├── app/
    └── packages/
        └── modules/
            ├── search-1.2.4.zip
            └── contacts-1.0.4.zip

Do not add these archives manually. Declare module codes in package.embedded_dependencies in the admin module.php. The standard builder will package the dependencies, calculate SHA-256 checksums, and emit an ave-module-package-v2 manifest.

An archive without an external folder is allowed. There must be exactly one at the root module.php or one admin/module.php, as well as AVE-MODULE.json.

For a composite package, the folder name must match code. The code starts with lowercase Latin letter, contains only lowercase letters, numbers and _, its maximum length is 64 characters.

Required properties

'lifecycle' => array('managed' => true),
'admin_extension' => array(/* метаданные раздела */),

lifecycle.adopt_existing is prohibited: it is intended for controlled use only moving existing functionality. The new archive code must not match code of an already detected module.

Security restrictions

Limit	Meaning
Format	ZIP only
Archive size	Up to 25 MB
Files and directories	Up to 1500
One unpacked file	Up to 25 MB
Total unpacked size	Up to 100 MB

The installer does not allow absolute paths, .., control characters, duplicates, symbolic links and suspicious compression ratio. Required PHP extension zip; catalogs <admin-directory>/modules and modules must be writable by the web process. In the build command above, adminx stands for project source directory; the installed system determines the actual directory panels automatically.

Before executing module.php, the installer checks the format, owner, code, version, package type, full list of files and SHA-256. Extra, missing or changed the file stops the installation. Checksum protects integrity, but archive still must come through the owner's trusted channel.

Installation order

1. Open System → Modules.
2. Select the installation from the archive and download the ZIP.
3. After success, check the version and dependencies.
4. Assign rights to roles and fill in the module settings.
5. Check administrative and public routes.

For a self-contained package dependencies are processed before the root lifecycle. Missing dependencies are installed, older versions are updated, and equal or newer versions are reused. Removing the root package does not uninstall shared modules because they may already contain user data.

If there is an error before the manifest check, the temporary and target folders are deleted. If manifest has already been checked and some of the migrations have been completed, the package remains in place: eliminate the cause and repeat normal installation.

ZIP is executable PHP code. Install a package only from a trusted one source and make a backup before migrating existing data.

To publish multiple official ZIPs over HTTPS use remote signed directory.