Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

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.

branch: master

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 bin
Octocat-spinner-32 src
Octocat-spinner-32 README.md
README.md

Joomla Packager

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.

Requirements

  • PHP 5.3+

Usage

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.

XML Manifest

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

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

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

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

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

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.

Example: Import a file from a git repository into Phar root.

<git url="http://domain.com/repository.git" ref="master">
    <file>foo.php</file>
</git>

results in phar://foo.php.

Example: Import a libraries from a git repository into Phar path lib/.

<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

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

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

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.

Example: Import the Joomla Platform version 12.1 without legacy at path lib/.

<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>

Example XML Manifest

<?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>
Something went wrong with that request. Please try again.