The Joomla packager application is a self-contained Phar built using the Joomla Platform. Its purpose is to build PHP archives for easy deployment and management. This can be used for Joomla Platform applications, Joomla CMS extensions, or really any other PHP application or libraries.
- PHP 5.3+
The packager requires an XML manifest to build a package. By default it will look for packager.xml in the current working directory. You can optionally tell it what XML manifest to use by passing the -f <file> argument during execution.
Using the Joomla Packager is really as hard as writing an XML manifest for your package. You can see below for how to write the manifest files for your application or package.
The XML manifest files read by the Joomla packager contain a root <packager> element and a single child <code> of the <packager> element.
The <packager> element is the root node in the XML manifest file. As such it is required for all manifests and currently has the following possible attributes:
| Attribute | Required | Description |
|---|---|---|
| alias | False | By default the alias will be set to the filename of the destination phar file. |
| destination | True | The file path for the phar file to be written. This can be either absolute or relative to the XML manifest. |
| minify | False | If you want to have all php files imported into the phar file stripped of whitespace and comments set this attribute to "true". This decreases the overall package size dramatically without introducing compression. Note that this will make debugging infinitely more difficult since line numbers collapse and everything will likely be on line 2. You've been warned. |
The <code> element is the immediate child of the root <packager> element. This element contains the description of all of the files that are pacakged into the phar.
| Attribute | Required | Description |
|---|---|---|
| stub | False | The contents of the file at this absolute file path are executed when the Phar is included/executed. This is a great place to put class loaders or front controllers. See Phar::setStub(). Note: you don't have to import this file into the Phar in any other way. |
The <file> element can live as a child of the <code> tag or the <git> tag. It imports a file into the phar either from the local filesystem [or a specific git repository if within a <git> tag].
| Attribute | Required | Description |
|---|---|---|
| localPath | False | If the localPath attribute is set then the given file will be imported into the Phar underneath the path given as the attribute value. For example: <file>path/to/foo.php</file> would mean that foo.php is simply imported into the root path within the Phar. If the localPath attribute is set that would change: <file localPath="bar/baz">path/to/foo.php</file> would mean that foo.php is imported into the Phar underneath the localPath like bar/baz/foo.php. Note: if <file> is within a <git> tag it is possible to have the localPath be appended to a localPath set within the <git> tag itself. |
The <folder> element can live as a child of the <code> tag or the <git> tag. It imports a folder into the phar either from the local filesystem [or a specific git repository if within a <git> tag].
| Attribute | Required | Description |
|---|---|---|
| localPath | False | If the localPath attribute is set then the given folder will be imported into the Phar underneath the path given as the attribute value. For example: <folder>path/to/foo</folder> would mean that foo is simply imported into the root path within the Phar. If the localPath attribute is set that would change: <folder localPath="bar/baz">path/to/foo</folder> would mean that foo is imported into the Phar underneath the localPath like bar/baz/foo. Note: if <folder> is within a <git> tag it is possible to have the localPath be appended to a localPath set within the <git> tag itself. |
| recursive | False | If you want to have all children of the folder recursively imported into the phar set this attribute to "true". Otherwise only the files in the exact folder will be imported. |
The <git> element can live as a child of the <code> tag only. It allows you to package parts of an existing git repository into your phar. It will clone the repository specified in the <git> tag into a temporary location and then import any <file>s or <folder>s specified within the <git> tag.
| Attribute | Required | Description |
|---|---|---|
| url | True | The URL of the git repository from which you want to import files. Anything that is valid input to git clone should be fine. |
| ref | True | The branch or tag of the git repository you want to use for importing files. |
| localPath | False | If the localPath attribute is set then any files or folders will be imported into the phar underneath the path given as the attribute value. |
<git url="http://domain.com/repository.git" ref="master">
<file>foo.php</file>
</git>results in phar://foo.php.
<git url="http://domain.com/repository.git" ref="master" localPath="lib">
<folder recursive="true">libraries</file>
</git>or
<git url="http://domain.com/repository.git" ref="master">
<folder recursive="true" localPath="lib">libraries</file>
</git>both result in phar://lib/{LIBRARIES}.
The <platform> element is used for packaging up the Joomla Platform into the phar. You can specify whether legacy should be enabled and also optionally which packages you want to import using the <packages> and <package> tags.
| Attribute | Required | Description |
|---|---|---|
| version | True | The Joomla Platform version you would like to import. This can be any version number ["11.4", "12.1", etc] or "master". |
| legacy | False | If you want to import the legacy libraries for the Joomla Platform into the phar set this attribute to "true". |
| localPath | False | If the localPath attribute is set then the platform will be imported into the phar underneath the path given as the attribute value. |
The <packages> element may only be underneath the <platform> tag and serves as a container for <package> elements. Additionally it has an optional attribute exclude which affects how the contents of the <package> tags are treated.
| Attribute | Required | Description |
|---|---|---|
| exclude | False | If you want to import all Joomla Platform packages except the ones listed in child <package> tags set this attribute to "true". Otherwise only the packages listed in child <package> tags will be imported. Note: if no child <package> tags are present then all packages will be imported regardless of this attribute. |
The <package> element may only be underneath the <packages> tag and has no attributes. It is used to enumerate the Joomla Platform packages to be imported into the phar.
<platform version="12.1" localPath="lib" />Example: Import the Joomla Platform [log package only] at version 11.4 without legacy at path lib/log/.
<platform version="11.4" localPath="lib/log">
<packages>
<package name="log" />
</packages>
</platform>Example: Import the Joomla Platform [everything but the GitHub package] at current master with legacy at path libraries/.
<platform version="master" legacy="true" localPath="libraries">
<packages exclude="true">
<package name="github" />
</packages>
</platform><?xml version="1.0" encoding="UTF-8"?>
<packager minify="true" destination="foo.phar">
<code stub="main.stub.php">
<!-- Import the local folder "foo" into /foo in the phar. -->
<folder recursive="true" localPath="foo">foo</folder>
<!-- Import the lib folder of this repo into /magic in the phar. -->
<git url="git://domain.com/repo-path.git" ref="3.0">
<folder recursive="true" localPath="magic">lib</folder>
</git>
<!-- We only want to import a small subset of the Joomla Platform. -->
<platform version="12.1" localPath="lib">
<packages>
<package name="application" />
<package name="registry" />
<package name="input" />
<package name="filter" />
<package name="event" />
<package name="log" />
<package name="object" />
</packages>
</platform>
</code>
</packager>