Import versus install
This page is for administrators who handle packages in Setup > Packages or with ezpm, and for developers who set
install_type. It answers the question that causes most confusion around packages: what is the difference between
importing and installing, and what do uninstall and remove leave behind?
Contents
- Four verbs
- Import
- Install
- The install type
- Uninstall
- Remove
- Which tool does which
- Common situations
- Related pages
Four verbs
| Verb | Changes the repository | Changes the site | Code |
|---|---|---|---|
| Import | adds the package directory | no | eZPackage::import() |
| Install | no | yes: runs the install items | eZPackage::install() |
| Uninstall | no | yes: runs the uninstall of the items | eZPackage::uninstall(), the package/uninstall view |
| Remove | deletes the package directory | no | eZPackage::remove() |
The site is the database, extension/, design/ and settings/; the repository is var/storage/packages/
(The local package repository).
Import
Import takes an .ezpkg archive, checks it, and extracts it into var/storage/packages/<vendor directory>/<name>/.
After an import the package can be listed, viewed, exported and installed; nothing on the site has changed. Import
refuses a package whose name is invalid or that already exists (STATUS_INVALID_NAME, STATUS_ALREADY_EXISTS); the
setup wizard's downloads remove an older copy first when they must replace it. Details:
The .ezpkg file.
Install
Install runs the package on the site (eZPackage::installUnaudited()):
- Install every package listed in
<requires>first, recursively. - Stop here, successfully, when
install_typeis notinstall. - Run the
<install>items in order, each in its own database transaction, each by its handler (Install items and handlers). The first failing item stops the install unlesscontinue-on-erroris set. - When every item succeeded, record the package as installed: a row in the
ezpackagetable with the name, the version<number>-<release>and the date.
Each install is recorded in the audit trail as system.package.install. With as_drafts (ezpm install --as-drafts,
Install as drafts in the administration) only content object items run, as drafts, and the package is not
marked installed, so it can be installed as drafts again
(install as drafts).
Note
Installing a package again runs its items again; install() does not skip a package that is installed already.
The administration's install page warns about this.
The install type
install_type is an attribute of the root element: <package ... install_type="import">. It has two values:
| Value | Meaning | Used by |
|---|---|---|
install (the default when the attribute is missing) | The items are run on install; the package can be uninstalled | content class, content object and extension packages |
import | The package is only kept in the repository: install runs its requirements but no items of its own, records nothing, and uninstall does nothing | every site package of the 6.0.15 index, and the 7x and ezwebin_ / ezflow_ site style packages |
For an import package the administration's package page says: "There is nothing to install here: this package
has the install type "import". A site package is imported by the setup wizard together with the packages it
requires, and is not installed on its own." After an upload, such a package opens on its page instead of the install
page. ezpm create <name> <summary> <version> <install|import> sets the value for a new package; anything else
becomes install.
Uninstall
Uninstall only applies to a package with install_type="install" that is recorded as installed. It calls each
handler's uninstall() and then deletes the installed record.
- The administration's Uninstall (
/package/uninstall/<name>) walks the<uninstall>items in reverse order, asks when a handler needs a decision (for example, removing a class that has objects), and needs thepackage/installpolicy for the package's type. eZPackage::uninstall()in PHP walks the items of<install>.ezpmhas no uninstall command.
What is removed depends on the handler: classes, objects and extensions are removed; from 6.0.15 on also the files
the install created and nobody changed since; SQL and INI changes have
no uninstall of their own and stay. Uninstalling cannot be undone. Each uninstall of an installed package is recorded
in the audit trail as system.package.uninstall.
Remove
Remove deletes the package directory from the repository and clears its installed record. It does not uninstall:
classes, content, extensions and files the package installed stay on the site, and the package can then no longer be
uninstalled from Setup > Packages. In the administration the confirmation page lists what goes, which packages require
it and whether the installer uses it as a source; see
Packages guide, 9. Removing packages. On the command line:
php ezpm.php delete <name> (aliases del, remove, rm).
Which tool does which
| Tool | Import | Install | Uninstall | Remove |
|---|---|---|---|---|
Setup wizard, kickstarter, exp:install | the site package and its requirements | the requirements with install_type="install" | ||
| Setup > Packages | Upload (package/upload) | Install (package/install/<name>) | Uninstall (package/uninstall/<name>) | Remove on the list or the package page |
ezpm.php | import <file> | install <name> | delete <name> | |
| ezupdate | fetches packages from package servers into the repository |
The ezupdate part is described in Fetching packages with ezupdate.
Common situations
| You want to ... | Do |
|---|---|
| Have a site package available offline | import it and its requirements; do not install them |
| Add a content class package to a running site | import it, then install it |
| Replace an imported package with the server's newer one | remove it, then import the new archive |
| Undo an install | uninstall in Setup > Packages, before you remove the package |
| Clean up the repository | remove; the site keeps what was installed |
Related pages
- Site package basics
- Site packages: start here
- Importing a package
- Installing and uninstalling
- Packages guide, 7. Installing and uninstalling
- ezpm, the package manager on the command line
- Contribute your site package
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.