Package Management¶

Package Locations¶

Package Directory Layout¶

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 as follows:

• <[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 as necessary. All classes or interfaces below this directory are handled by the autoloading mechanism and will be registered at the object manager automatically (and will thus be considered “registered objects”).

    One special file in here is the Package.php which contains the class with the package’s bootstrap code.

  • 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 Objects.yaml file which may be used to configure the package’s objects and the Settings.yaml file which contains general user-level settings.

  • Documentation

    Holds the package documentation. 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, ... In general, there is a distinction between public and private resources.

    • Private

      Contains private resources for the package. All files inside this directory will never be directly available from the web.

    • Public

      Contains public resources for the package. All files in this directory will be mirrored into FLOW3’s Web directory by the Resource Manager (and therefore become accessible from the web).

    Although it is up to the package author to name the directories, we suggest the following conventions for directories below Private and Public:

    Warning

    The following folder structure is not yet finalized, it is more a rough draft.

    • Media

      This directory holds images, PDF, Flash, CSS and other files that will be delivered to the client directly without further processing.

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

    • Unit

      Holds the unit tests for the package.

    • Functional

      Holds the functional tests for the package.

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 class name as well as the file name. An example for a valid class name is \MyCompany\MyPackage\Controller\StandardController while the file containing this class would be named StandardController.php and is expected to be in a directory MyPackage/Classes/Controller.

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.

We use vendor namespaces for package keys, i.e. all packages which are released and maintained by the TYPO3 and FLOW3 core teams start with TYPO3.*. In your company we suggest that you use your company name as vendor namespace.

Importing and Installing Packages¶

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

If no PackageStates.php exists in your Configuration folder, it will be created and all found packages will be activated. If PackageStates.php exists, you can use the package manager to activate and deactivate packages through the FLOW3 command line script.

The FLOW3 command line interface is triggered through the flow3 script in the main directory of the FLOW3 distribution. From a Unix shell you should be able to run the script by entering ./flow3 (on windows, use flow3.bat).

To activate a package, use the package:activate command:

$ ./flow3 package:activate <PackageKey>

To deactivate a package, use package:deactivate. For a listing of all packages (active and inactive) use package:list.

Package Manager¶

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

Creating a New Package¶

Use the package:create command to create a new package:

$ ./flow3 package:create Acme.Demo

This will create the package in Packages/Application. After that, adjust Meta/Package.xml to your needs. Apart from that no further steps are necessary.

Package Meta Information¶

All packages need to provide some meta information to FLOW3. The data is split in two files, depending on primary use.

namespace Acme\Demo;

use TYPO3\FLOW3\Package\Package as BasePackage;

/**
 * The Acme.Demo Package
 *
 */
class Package extends BasePackage {
}

<?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>Test to demonstrate the features of Package.xml</description>
   <version>0.0.1</version>
   <categories>
      <category>System</category>
      <category>Testing</category>
   </categories>
   <parties>
      <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="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>