Skip to content
This repository has been archived by the owner on Nov 26, 2017. It is now read-only.

Commit

Permalink
Browse files Browse the repository at this point in the history
Updating documentation about JLoader
  • Loading branch information
florianv committed Nov 11, 2012
1 parent 4a3e051 commit 889182f
Showing 1 changed file with 178 additions and 42 deletions.
220 changes: 178 additions & 42 deletions docs/manual/en-US/chapters/introduction.md
Expand Up @@ -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(1, true);

// Setup the loader with the Natural Case strategy.
JLoader::setup(2, true);

// Setup the loader with the Mixed Case strategy.
JLoader::setup(3, 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
Expand All @@ -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');
Expand All @@ -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
Expand Down

0 comments on commit 889182f

Please sign in to comment.