FLOW3 Supports PHP Vendor Namespaces


The result of the last big refactoring before FLOW3 1.0 now made it to our review queue (typo3.org login required): vendor namespaces support. This new feature has two great benefits: first of all we don't need a central package key registry (like the one we have for TYPO3 4.x extensions) and secondly, it allows anyone to seamlessly integrate third-party packages, such as Symfony2 components and Zend Framework components or virtually any other PHP 5.3 based library.

Namespaces in PHP 5.3

One of the key features of PHP 5.3 was the introduction of namespaces. This can be a big enabler when it comes to mixing libraries developed by different projects and companies (aka "vendors"): Each of them uses their own namespace for class naming, thus avoiding name clashes when the components are put together.

Namespaces in a programming language can be compared with the Internet's domain name system – once you own a certain domain, you're completely free with naming your directories and files because the domain name gives you your own namespace to work in.

Before we had namespaces, the TYPO3 project was using its own namespace-like system: extension keys. Once you registered an extension key at typo3.org, you could be sure that it's safe to use a class name like "Tx_MyExtensionKey_Foo" in your code. That works pretty well in our part of the universe but also has a few drawbacks:

  • you need to be online for registering a new package key
  • other PHP projects don't have a typo3.org extension key
  • it's difficult to find suitable extension keys because easy names like "news" can only be owned by one registrant

FLOW3's Implementation

The implementation of vendor namespaces support took some intensive 7 working days. All parts of FLOW3 somehow dealing with packages, package keys or PHP namespace parts had to be adjusted and backed by new tests. The most visible part of all is the new parent namespace of the framework packages. Our de-facto vendor namespace in the past has been "F3" – the namespace of all packages followed the pattern F3\PackageKey\Foo\Bar ... Since FLOW3 is part of the TYPO3 project, the core team decided to choose "TYPO3" as our new vendor namespace. The Object Manager for example is now known under the class name TYPO3\FLOW3\Object\ObjectManager.

Here's a comparison between old and new for namespace related features in FLOW3:

 BeforeAfter
Package Key FLOW3
Fluid
MyTwitter
TYPO3.FLOW3
TYPO3.Fluid
Com.Acme.MyTwitter
Namespace F3\FLOW3
F3\Fluid
F3\MyTwitter
TYPO3\FLOW3
TYPO3\Fluid
Com\Acme\MyTwitter
Packages/… Framework/FLOW3/
Framework/Fluid/
Application/MyTwitter
Framework/TYPO3/FLOW3
Framework/TYPO3/Fluid
Application/Com/Acme/MyTwitter
resource:// FLOW3/Private/Templates/…
MyTwitter/Private/…
TYPO3.FLOW3/Private/Templates/…
Com.Acme.MyTwitter/Private/…
YAML
FLOW3:
  security:
    enable: y
TYPO3:
  FLOW3:
    security:
      enable: y

Those third-party libraries we already used (Doctrine, the YAML parser, ExtJS) will be moved into dedicated packages. Doctrine for example will now be located in the directory Packages/Framework/Doctrine/ and its classes can be loaded without further ado by the FLOW3 class loader.

Updating Existing Code

Such a big change doesn't come without adaption of existing FLOW3 packages. If you're one of those who already created FLOW3-based packages, you'll be happy to know that most of the code adjustments will be done automatically. Along with the new feature, FLOW3 comes with a migration script (located in Packages/Framework/TYPO3/FLOW3/Scripts/) which scans existing packages for necessary changes to PHP code, YAML settings and HTML templates. All references to the FLOW3 framework and its related packages (such as "Fluid" or "Party") will be updated. After the migration your own package will reside in the "MyCompany\[old package key]" namespace (ie. replacing "F3" by "MyCompany") and you will have to do a global search and replace to adjust your package to the vendor namespace you intend to use in the future. As the last step you'll need to manually move your package to the correct directory and flush the caches.

Next Steps

The FLOW3 core team is currently reviewing my patches and we're migrating our existing code base (TYPO3 5.0, the T3CON11 site and plugin and the Blog). We already were quite busy updating the FLOW3 manuals last week and will continue with that for certainly two weeks. Along the way we'll fix bugs we don't want to see in the 1.0 beta 1 and keep focused on finding the shortest, yet reasonable way to the first beta release. As it seems, we won't be able to keep the tentative release date (scheduled for next week) but we don't want to miss it by months either. As soon as all 1.0 features are basically working and the documentation is updated, we'll release FLOW3 1.0 beta 1 – and it would bug me a lot if that wouldn't happen in July ...


Leave a reply