1.3. Packages

FLOW3 is a package-based system. In fact, FLOW3 itself is just a package as well - but obviously an important one. Packages act as a container for many different purposes: Most of them contain PHP code which adds certain functionality, others only contain documentation and yet other packages consist of templates, images or other resources. The TYPO3 project hosts a package repository which acts as a convenient hub for interchanging FLOW3 based packages with other community members.

Note

At the time of this writing the package repository is still in the planning phase.

Files and Locations

The FLOW3 package directory structure follows a certain convention which has the advantage that you don't need to care about any package-related configuration. If you put your files into the right directories, everything will just work.

The suggested directory layout of a FLOW3 package is shown below:

[PackageName]
Classes

This directory contains the actual source code for the package. Package authors are free to add (only!) class or interface files directly to this directory or add subdirectories to organize the content if necessary. All classes or interfaces below this directory are handled by the autolading mechanism and will be registered at the component manager automatically (and will thus be considered "components").

Configuration

All kinds of configuration which are delivered with the package reside in this directory. The configuration files are immutable and must not be changed by the user or administrator. The most prominent configuration files are the Components.php file which may be used to configure the package's components and the Settings.php file which contains general user-level settings.

Documentation

Holds the package documentation. The english (DocBook) manual for example must be located in a subdirectory called Manual/en/. Please refer to the Documentor's Guide for more details about the directories and files within this directory.

Meta

A folder which provides some meta information about the package.

Package.xml

This mandatory file contains some basic information about the package, such as title, description, author, constraints, version number and more. You should take great care to keep this information updated.

Resources

Contains static resources the package needs, such as library code, template files, graphics, ...

Media

This directory holds images, PDF, Flash, CSS and other files that will be delivered to the client directly without further processing. The content of the Media/Public/ directory will be automatically mirrored to the public file cache directory by the resource manager. You're free to create subdirectories as they become necessary.

Templates

Template files used by the package should go here. If a user wants to modify the template it will end up elsewhere and should be pointed to by some configuration setting.

PHP

Should hold any PHP code that is an external library which should not be handled by the component manager (at least not by default), is of procedural nature or doesn't belong into the classes directory for any other reason.

Java

Should hold any Java code needed by the package. Repeat and rinse for Smalltalk, Modula, Pascal, ... ;)

More directories can be added as needed.

Tests

Holds the unit tests for the package. Testcases will be recognized by the Testing package if they follow the require naming convention.

As already mentioned, all classes which are found in the Classes directory will be detected and registered. However, this only works if you follow the naming rules equally for the classname as well as the file name. An example for a valid class name is be F3_MyPackage_Controller_Default while the file containing this class would be named "F3_MyPackage_Controller_Default.php".

All details about naming files, classes, methods and variables correctly can be found in the FLOW3 Coding Guidelines. You're highly encouraged to read (and follow) them.

Package Keys

Package keys are used to uniquely identify packages and provide them with a namespace for different purposes. They save you from conflicts between packages which were provided by different parties.

Any public package needs to have a unique packge key which you need to register at forge.typo3.org prior to use. But even if you develop a package for private use only, it's clever to register a package key for it.

Note

At the time of this writing the package key registration has not yet been implemented and you therefore can't register package keys. Just get in touch with the TYPO3 Forge team in case you need one.

Importing and Installing Packages

At this time the features for import and installation of packages have not been implemented. The current behaviour is that all directories which are found below the Packages folder are assumed to be packages and are active by default. Just make sure that you created a Package.xml file in the Meta directory of your package.

Package Manager

The Package Manager is in charge of downloading, installing, configuring and activating packages and registers their components and resources.

Note

In its current form, the package manager only provides the basic functionality which is necessary to use packages and their components. More advanced features like installing or configuring packages are of course planned.

Creating a New Package

For the time being just create the package folder and subdirectories manually and copy & adapt a Package.xml file from one of the other packages. Apart from that no further steps are necessary.

Package Meta Information

All packages need to provide some meta information to the package manager. This data is stored in a file called Package.xml which resides in the Meta directory of a package. The format of this file follows a RelaxNG schema which is available at http://typo3.org/ns/2008/flow3/package/Package.rng.

Here is an example of a valid Package.xml file:

Example 1.1. Package.xml

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<package xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://typo3.org/ns/2008/flow3/package" version="1.0">
   <key>TestPackage</key>
   <title>Test Package</title>
   <description>The test package to demonstrate the features of Package.xml</description>
   <version>0.0.1</version>
   <state>Alpha</state>
   <categories>
      <category>System</category>
      <category>Testing</category>
   </categories>
   <parties>
      <person role="LeadDeveloper">
         <name>David Brühlmeier</name>
         <email>typo3@bruehlmeier.com</email>
      </person>
      <person role="Maintainer">
         <name>John Smith</name>
         <email>john@smith.com</email>
         <organisation>Smith Ltd.</organisation>
         <repositoryUserName>jsmith</repositoryUserName>
      </person>
      <organisation role="Sponsor">
         <name>John Doe Co.</name>
         <email>info@johndoe.com</email>
         <website>www.johndoe.com</website>
      </organisation>
   </parties>
   <constraints>
      <depends>
         <package minVersion="1.0.0" maxVersion="1.9.9">FLOW3</package>
         <system type="PHP" minVersion="5.1.0" />
         <system type="PHPExtension">xml</system>
         <system type="PHPExtension">pgsql</system>
         <system type="PEAR" minVersion="1.5.1">XML_RPC</system>
      </depends>
      <conflicts>
         <system type="OperatingSystem">Windows_NT</system>
      </conflicts>
      <suggests>
         <system type="Memory">16M</system>
      </suggests>
   </constraints>

   <!-- The following elements are only used and generated by the repository -->
   <repository>
      <downloads>
         <total>3929</total>
         <thisVersion>444</thisVersion>
      </downloads>
      <uploads>
         <upload>
            <comment>Just a comment...</comment>
            <repositoryUserName>jsmith</repositoryUserName>
            <timestamp>2008-04-22T17:23:09Z</timestamp>
         </upload>
         <upload>
            <comment/>
            <repositoryUserName>jsmith</repositoryUserName>
            <timestamp>2008-04-19T03:54:13Z</timestamp>
         </upload>
      </uploads>
   </repository>
</package>