This repository has been archived by the owner. It is now read-only.
Permalink
Browse files

Merge pull request #1591 from florianv/jloader-namespaces

Namespaces support for JLoader
  • Loading branch information...
LouisLandry committed Nov 12, 2012
2 parents 9104707 + c48c0b4 commit 187bef38412cad749c80dd211c2a164608d53a53
@@ -113,62 +113,160 @@ JPlatform::getLongVersion() | A really verbose representation of the platf
## Class Auto-loading
-The Joomla Platform implements a class auto-loader removing the need for
-the developer to include files by hand, or by using a fall to the
-`jimport` function (this is now discourage in favor of using
-JLoader::register). Only class names that begin with upper case "J" will
-be considered for auto-loading. Following the "J" prefix, the class name
-must be in camel case and each segment of the name will represent a
-folder path below `JPLATFORM_PATH/joomla` where the last segment of the
-name is the name of the class file. If there is only one part to the
-class name, the auto-loader will look for the file in a folder of the
-same name. Folder names must be in lower case.
+`JLoader` is the mainstay of the Joomla Platform as it controls auto-loading of classes.
-JDatabase should be located in `JPATH_PLATFORM/joomla/database/database.php`
+It removes the need for the developer to include files by hand, or by using a fall to the `jimport` function.
-JDatabaseQuery should be located in `JPATH_PLATFORM/joomla/database/query.php`
+Multiple ways of auto loading classes, following different conventions are proposed by JLoader.
-JDatabaseQueryMysql should be located in `JPATH_PLATFORM/joomla/database/query/mysql.php`
+### The Namespace Loader
-There is no limit to the depth to which the auto-loader will search,
-providing it forms a valid path based on the camel case natural of the
-class name. Note that while acronyms and names such as HTML, XML and
-MySQL have a standard presention in text, such terms should observe camel
-case rules programmatically ("HTML" becomes "Html", "XML" becomes "Xml"
-and so on).
+Since the release 12.3 of the Joomla Platform there is the possibility to auto classes within namespaces.
-The `JLoader` class allows additional customisation including, but not
-limited to, providing the ability to override core classes and cater for
-classes that do not conform with the auto-loader naming and path
-convention.
+* A developer can register the full path to a top level (root) namespace where the loader can find classes (within this namespace).
-### JLoader
+* A developer can override an existing namespace path by replacing it with a new one.
-`JLoader` is the mainstay of the Joomla Platform as it controls
-auto-loading of classes. Wherever possible, class names and paths should
-conform to the auto-loader convention in the form:
+* A developer can register multiple paths to the same namespace.
-`JClassname` located in `JPATH\_PLATFORM/joomla/classname/classname.php`, or
-`JPathtoClassname` located in `JPATH\_PLATFORM/joomla/pathto/classname.php`.
-However, deviations, and even overrides can be handled by `JLoader`'s
-register and discover methods.
+#### Convention
-#### Registering Classes
+The convention is to have the namespace names matching the directories names.
-New classes, or override classes can be registered using the register
-method. This method takes the class name, the path to the class file,
-and an option boolean to force an update of the class register.
+For example :
```php
-// Register an adhoc class.
-JLoader::register('AdhocClass', '/the/path/adhoc.php');
+<?php
+namespace Chess\Piece;
-// Register a custom class to override as core class.
-// This must be done before the core class is loaded.
-JLoader::register('JDatabase', '/custom/path/database_driver.php', true);
+class Pawn
+{
+
+}
+```
+
+must be found in `BASE_PATH/chess/piece/pawn.php` or in `BASE_PATH/Chess/Piece/Pawn.php`.
+
+For the namespace declaration, it is recommanded to use camel case letters as you will have for a class name.
+
+But as you saw above there are different possibilities for the paths case :
+
+#### Lower Case :
+
+The directory structure is lower case and the namespace can be any case.
+
+It must be used when the path is lower case and the namespace camel case.
+
+Example :
+
+```php
+<?php
+namespace Chess\Piece;
+
+class Pawn
+{
+
+}
+```
+
+for a class in `BASE_PATH/chess/piece/pawn.php`.
+
+#### Natural Case :
+
+The namespace case matches the path case.
+
+It must be used when you have lower case namespaces and paths or when you have camel case namespaces and paths.
+
+Examples :
+
+```php
+<?php
+namespace Chess\Piece;
+
+class Pawn
+{
+
+}
+```
+
+for a class in `BASE_PATH/Chess/Pieces/Pawn.php`.
+
+```php
+<?php
+namespace chess\piece;
+
+class Pawn
+{
+
+}
+```
+
+for a class in `BASE_PATH/chess/pieces/pawn.php`.
+
+#### Mixed Case :
+
+It regroups the two options.
+
+It must be used when you have some lower case and camel case paths and camel case or lower case namespace declarations.
+
+For example, Joomla can stay lower case and your application can have a camel case directory structure.
+Both can be auto loaded using the same Mixed Case loader.
+
+#### Usage
+
+#### Setup the Loader
+
+In order to correctly use the namespace auto loader you need to setup it according the case strategy you choosed.
+
+```php
+<?php
+
+// Setup the loader with the Lower Case strategy.
+JLoader::setup(JLoader::LOWER_CASE, true);
+
+// Setup the loader with the Natural Case strategy.
+JLoader::setup(JLoader::NATURAL_CASE, true);
+
+// Setup the loader with the Mixed Case strategy.
+JLoader::setup(JLoader::MIXED_CASE, true);
+```
+
+#### Registering a namespace
+
+You can register a top level namespace by using `JLoader::registerNamespace`.
+
+For example :
+
+```php
+<?php
+
+// The two parameters are case sensitive.
+// The first one must match the namespace declaration case.
+// The second one must match the path case.
+JLoader::registerNamespace('Chess', BASE_PATH . '/chess');
+```
+
+All classes respecting the naming and path convention will be auto loaded.
+
+#### Appending an other path
+
+```php
+<?php
+
+// Adding an other path to the Chess namespace.
+JLoader::registerNamespace('Chess', AN_OTHER_PATH . '/chess');
+```
+
+#### Reseting a path
+
+```php
+<?php
+
+// Reseting a path by adding an other one.
+JLoader::registerNamespace('Chess', AN_OTHER_PATH . '/chess', true);
```
-#### Registering a Class Prefix
+### The Prefix Loader
Since 12.1, there is the ability to register where the auto-loader will
look based on a class prefix (previously only the "J" prefix was
@@ -179,6 +277,29 @@ several scenarios:
* A developer can register an extra path for an existing prefix (for example, this allows the Joomla CMS to have custom libraries but still using the "J" prefix).
* A developer can register a force override for a prefix. This could be used to completely override the core classes with a custom replacement.
+#### Convention
+
+The class name must be in camel case and each segment of the name will represent a folder path
+where the last segment of the name is the name of the class file.
+If there is only one part to the class name, the auto-loader will look for the file in a folder of the
+same name.
+Folder names must be in lower case.
+
+Examples :
+
+`PrefixUserModel` should be located in `PATH_TO_PREFIX/user/model.php`.
+
+`PrefixUser` should be located in `PATH_TO_PREFIX/user/user.php`.
+
+There is no limit to the depth to which the auto-loader will search,
+providing it forms a valid path based on the camel case natural of the
+class name.
+Note that while acronyms and names such as HTML, XML and MySQL have a standard presention in text,
+such terms should observe camel case rules programmatically ("HTML" becomes "Html", "XML" becomes "Xml"
+and so on).
+
+#### Usage
+
```php
// Tell the auto-loader to also look in the /libraries/cms folder for "J" prefixed classes.
JLoader::registerPrefix('J', JPATH_PLATFORM . '/cms');
@@ -190,7 +311,22 @@ JLoader::registerPrefix('Foo', '/path/to/custom/packages');
JLoader::registerPrefix('J', '/my/platform/fork', true);
```
-#### Discovering Classes
+### Registering Classes
+
+New classes, or override classes can be registered using the register
+method. This method takes the class name, the path to the class file,
+and an option boolean to force an update of the class register.
+
+```php
+// Register an adhoc class.
+JLoader::register('AdhocClass', '/the/path/adhoc.php');
+
+// Register a custom class to override as core class.
+// This must be done before the core class is loaded.
+JLoader::register('JDatabase', '/custom/path/database_driver.php', true);
+```
+
+### Discovering Classes
Classes in a folder that follow a naming convention, but not one the
auto-loader immediately recognises, can be registered collectively with
Oops, something went wrong.

0 comments on commit 187bef3

Please sign in to comment.