Lesson 7.3: A Composer package or an .ezpkg
A finished theme is handed out as a Composer package, as an Exponential package (.ezpkg), or both. The choice
depends on who installs it and whether it carries database content such as content classes. In this lesson learners
make the choice for their theme and build an .ezpkg from it on the command line.
At a glance
| Course | Theme design |
| Module | Module 7: Packaging a theme |
| Duration | 45 minutes (15 presenting, 30 exercise) |
| Level | Intermediate |
| Audience | Designers and developers who publish themes |
| Prerequisites | Lesson 7.1; shell access to the learner's own installation |
Learning objectives
After this lesson, learners can:
- choose between a Composer package and an
.ezpkgwith the decision table; - name the four package types of Setup > Packages > Create new package;
- switch extension export on for one extension, and explain the secret check;
- create, fill and export a package with
ezpm.php, and inspect the archive.
Trainer's notes
How to present it
Sources: Composer package or .ezpkg, Exporting an extension as a package and Exporting and importing with ezpm.
The decision table (5 minutes).
Question Composer package .ezpkgWho installs it? Developers and hosts who run composerAdministrators who work in Setup > Packages What does it carry? Files: the theme extension Files and database content: classes, objects, a site style How is it updated? composer update <vendor>/<theme>Installing the next package version Three answers: Composer only; Composer with
.ezpkgclass packages inside (packages/);.ezpkgonly.Package types (3 minutes). Setup > Packages, Create new package: Content object export, Content class export, Extension export ("Exporting extensions has to be switched on first") and Site style (two stylesheets, their images and a thumbnail).
Export is off by default (4 minutes).
settings/package.ini [ExtensionExportSettings] AllowedExtensions[]is empty: no extension may be exported. The administrator lists the extension there, and in the administration the role also needspackage/export_extension. Every way of exporting refuses an extension that holds secret values or key material.ezpm (3 minutes).
php ezpm.php helplists the commands:create,add,export,import,check,install,validate,list,info.
Common questions
Why is export switched off? An extension may hold settings with passwords or keys; exporting it would put them in a file that is handed around. The secret check refuses those, and the allow-list makes export a deliberate decision.
Can I ship the theme's content classes with Composer? Yes, as .ezpkg class packages in the theme's packages/
folder, imported by the installer (Bundling content class packages).
What does composer.json need? type: ezpublish-legacy-extension and extra.ezpublish-legacy-extension-name
with the folder name (composer.json for a theme).
Pitfalls
- Leaving export switched on. End the exercise by removing the allow-list entry.
- Exporting into the installation's web-served tree. Write the archive to
var/tmp/and move it where it belongs. - A secret in the theme. If the check refuses the theme, read why; never weaken the check to get the package out.
Hands-on exercise
On your own training installation, in the installation root.
In the administration, open Setup > Packages, press Create new package and read the four types. Press Cancel.
Decide for
training_themewhich of the three answers fits, and write one sentence why.Allow the export of your theme only:
php bin/php/console exp:ini add 'package.ini/ExtensionExportSettings/AllowedExtensions[]' training_theme global php bin/php/ezcache.php --clear-tag=iniCreate and fill the package:
php ezpm.php create training_theme_pkg 'Training theme' 0.1.0 install php ezpm.php add training_theme_pkg ezextension training_themeExport it:
php ezpm.php export training_theme_pkg -d var/tmp.Find the file (
ls var/tmp/training_theme_pkg*) and list its content withtar tzf <file> | head -30.Check the list:
package.xml, the theme's files, and no.bak,.envor key files.Validate the archive as a receiving installation would:
php ezpm.php validate <file>.Switch export off again:
php bin/php/console exp:ini rem 'package.ini/ExtensionExportSettings/AllowedExtensions[]' training_theme global php bin/php/ezcache.php --clear-tag=ini
Expected result
- Step 5 writes an archive in
var/tmp/whose name starts withtraining_theme_pkg-0.1.0and ends in.ezpkg(the name carries the version, and may carry the package's release number). - Step 6 lists
package.xmland the files oftraining_theme. - Step 8 reports the archive valid.
- Step 9:
php bin/php/console exp:ini where package/ExtensionExportSettings/AllowedExtensionsno longer lists the theme in the override file. - The trainer checks one learner's archive list on the projector.
Quiz
- A theme needs two content classes of its own. Which way of shipping fits best?
- Why can no extension be exported on a fresh installation?
- Which four package types does Create new package offer?
- Which
ezpm.phpcommand writes the archive? A.createB.addC.exportD.install - What do you do if the secret check refuses your theme?
Answers
- Composer with the class packages inside (
packages/), or an.ezpkgthat carries them (Composer package or .ezpkg). package.ini [ExtensionExportSettings] AllowedExtensions[]is empty by default.- Content object export, Content class export, Extension export, Site style.
- C.
export <package> -d <dir>. - Read the finding and remove the secret from the theme; never weaken the check (The secret check).
Further reading
- What an Exponential package is.
- The package creator wizard, step by step: the same in the browser.
- The site style package: sharing only a color scheme.
- ezpm: the package manager on the command line.
Related pages
- Module 7: Packaging a theme
- Theme design: course overview
- Trainers: start here
- 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.