Site package basics
This part of the site packages help explains how a package is built and how Exponential reads it. It is for
administrators who install sites and want to know what happens, and for developers who change or write packages.
Every statement on these pages was checked against the kernel code of 6.0.15 (kernel/classes/ezpackage.php and
the classes around it), settings/package.ini, the package sources and the live package server.
If you only want to install a site, you do not need any of this: the setup wizard, the kickstarter and
exp:install do it for you (see Choosing an install method).
Read on when an install fails, when you want to change what a new site contains, or when you build a package.
Contents
The pages of this part
| Page | What it answers |
|---|---|
| What a site installer package is | What a site package is, what it carries, and how it differs from the packages it requires |
| The .ezpkg file | The archive: its layout, the checks on upload and import, and how to open one by hand |
| package.xml reference | Every element and attribute of package.xml, as eZPackage reads and writes it |
| Package types | site, sitestyle, contentclass, contentobject, extension: TypeList and the types the index really uses |
| Install items and handlers | <install> items, HandlerAlias, and what each package handler does |
| Dependencies and install order | <requires>, min-version, and the order things are fetched and installed in |
| Install scripts in a site package | <settings><settings-file> and the functions the installer calls |
| How the setup wizard uses packages | The steps Site types, Package language options and Create sites |
| How the kickstarter and the console use packages | kickstart.ini [site_types] Site_package and exp:install --package |
| The local package repository | var/storage/packages/, the vendor folders, local, .cache and an offline index.xml |
| Classic and JSON packages | The two storage formats of a package |
| Import versus install | install_type, and what import, install, uninstall and remove mean |
Reading order
- New to packages: start with What a site installer package is, then The .ezpkg file and Import versus install.
- An install failed while fetching packages: How the setup wizard uses packages, then When the package server cannot be reached.
- You are writing or changing a package: package.xml reference, Install items and handlers, Dependencies and install order and Install scripts in a site package, then the documentation requirements.
The basics in ten lines
- A package is a directory with a definition file (
package.xml, orpackage.jsonin the JSON format) and the files it names. - Shipped as one file, a package is a gzip compressed tar archive ending in
.ezpkg. - Every package has a type (
<type value="..."/>); a site package has the typesite. - A site package requires other packages (
<require type="ezpackage" name="..." min-version="..."/>): content classes, content, extensions, site styles. - A site package can carry install scripts (
<settings><settings-file filename="..."/>) that set up siteaccesses, settings, roles and preferences. - The packages it requires carry install items (
<install><item type="..."/>), each handled by a package handler named insettings/package.ini [PackageSettings] HandlerAlias[]. - Import puts a package into the local repository,
var/storage/packages/<vendor>/<name>/; nothing on the site changes. - Install runs the install items. Packages with
install_type="import"(every site package of the 6.0.15 index) have nothing to install themselves. - The setup wizard, the kickstarter and
exp:installall run the same steps fromkernel/setup/steps/ezstep_data.php: they find the site package, import it and its requirements, install the requirements, and call the install scripts. - Packages come from the package server, whose address is
settings/package.ini [RepositorySettings] RemotePackagesIndexURL; see The package server.
Where the code is
| What | Where |
|---|---|
| The package model: read, write, import, install, uninstall | kernel/classes/ezpackage.php (eZPackage) |
| Archive checks before anything is written | kernel/classes/ezpackageuploadinspector.php |
Version comparison (min-version) | kernel/classes/ezpackageversion.php |
| Install item handlers | kernel/classes/packagehandlers/*/ |
| Package creation wizards | kernel/classes/packagecreators/*/ |
| Step installers of the administration | kernel/classes/packageinstallers/*/ |
| The administration's package views | kernel/package/ (entry points), kernel/private/classes/views/package/ |
| The setup steps that use packages | kernel/setup/steps/ezstep_site_types.php, ezstep_package_language_options.php, ezstep_create_sites.php |
| The command line package manager | ezpm.php in the installation root, code in kernel/private/classes/commands/ezpm.php |
| Settings | settings/package.ini |
Related pages
- Site packages: start here
- Glossary
- Contribute your site package: 7x and the Exponential Foundation strongly encourage you to submit your own site packages to the shared package server.
- Packages guide: Setup > Packages in the administration
- What an Exponential package is: the designer's view
- 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.