/docs/manual/en-US/chapters/introduction.md
Markdown | 361 lines | 245 code | 116 blank | 0 comment | 0 complexity | 843617f4ea799f49644f971ea3c3bef7 MD5 | raw file
Possible License(s): GPL-2.0, LGPL-2.1
- # Joomla Platform Manual
- ## Introduction
- This is the introduction to the Joomla Platform.
- ## Folder Structure
- The following outlines the purpose of the top-level folder structure of
- the Joomla Platform as found in the [GitHub repository](https://github.com/joomla/joomla-platform/ "Joomla Platform Github repository").
- Folder | Description
- ---------- | --------------------
- /build | Contains information relevant for building code style reports about the platform. Output from various automated processes may also end up in this folder.
- /docs | Contain developer manuals in Markdown format.
- /libraries | Contains all the server-side PHP code used in the Joomla Platform API.
- /media | Contains any client-side resources used by the platform.
- /tests | Contains all of the unit tests used for quality control.
- ## Bootstrapping
- Bootstrapping the Joomla Platform is done by including
- `/libraries/import.php` in your application. This file will initiliase a
- number of constants if they are not already defined by the developer
- prior to including the import.php file:
- Name | Description
- ---------------- | -----------------------
- JPATH\_PLATFORM | The path to the Joomla Platform (where `loader.php` or `platform.php` is located, usually in the same folder as `import.php`).
- IS\_WIN | A boolean value, true if the platform is Microsoft Windows based.
- IS\_MAC | A boolean value, true if the platform is Apple OSX based.
- IS\_UNIX | A bollean value, true is the platform is some flavor or Unix, Linux or similar (but not Mac).
- The bootstrap file will load the `JPlatform` and `JLoader` classes and
- also `JFactory`, `JException` (legacy), `JObject`, `JRequest` (legacy), `JText`
- and `JRoute`. Depending on the version, it may also register classes in a
- transitional state that do not conform to the auto-loader standards.
- ### Minimalistic Approach
- If required, the bootstrap file (`import.php`) can be ignored and a custom
- solution can be implemented (such as if the core `JFactory` class is to be
- overriden).
- ```php
- // Define the base path.
- define('JPATH_PLATFORM', '/path/to/platform/');
- // Load the platform version and loader classes.
- require_once JPATH_PLATFORM . '/platform.php';
- require_once JPATH_PLATFORM . '/loader.php';
- // Setup the autoloaders.
- JLoader::setup();
- // Do custom registration if required.
- ```
- ### Legacy Platform
- The Joomla Platform also supports a legacy tree for API. It includes
- many classes that are only used by the Joomla CMS, or classes and
- packages that have been upgraded and introduced backward compatibility
- issues. Bootstrapping the legacy Joomla Platform is done by including
- `/libraries/import.legacy.php`. This instructs the auto-loader to look
- for classes in the legacy tree first, and then in the core tree.
- ### Using Phar
- The Joomla Platform can be packed into a Phar file (a PHP archive). This can allow a developer to ship an application with the Platform in a compressed format so that everything can 'just work' without downloading the Platform separately. In large bespoke projects it also provides a convenient way to update the Joomla Platform with a single file and also ensuring that development and production environments are all set up with the same version of the Platform.
- To make a Phar of the Platform first download the Packager Tool from [https://github.com/LouisLandry/packager/downloads](https://github.com/LouisLandry/packager/downloads) and put the `joomla-packager.phar` file in your operating system's executable path. This is actually a standalone application with selected parts of the Joomla Platform included with it (it's one of those applications that uses itself to build itself).
- To create the phar of the core Joomla Platform (without the legacy tree) go to the root folder of the Joomla Platform and execute `joomla-packager.phar`. This will build automatically detect the `packager.xml` configuration file and place the phar file in `build/joomla.phar`. You can then include this phar file in your application by using the following code:
- ```php
- require_once 'path/to/joomla.phar';
- ```
- After this you can just start using the Platform API as required.
- For advanced applications or projects that include their own unit test suite, the Platform and test framework can also be built into a phar by executing the following:
- ```bash
- $ joomla-packager.phar -f packager.test.phar
- ```
- ## Platform Version
- Platform version information can be found by accessing the `JPlatform`
- class.
- ### JPlatform
- `JPlatform` is a final class that cannot be modified by the developer. It
- has a number of public constant pertaining to the platform version and
- some static utility methods.
- #### Constants
- Name | Description
- ------------------------------ | ---------------------------
- JPlatform::PRODUCT | Joomla Platform
- JPlatform::RELEASE | The release number of the platform.
- JPlatform::MAINTENANCE | The point maintenance version if applicable.
- JPlatform::STATUS | The development status.
- JPlatform::BUILD | The build number for the platform, if applicable.
- JPlatform::CODE\_NAME | A human readable code name for this version.
- JPlatform::RELEASE\_DATE | The official release date for this version.
- JPlatform::RELEASE\_TIME | The official release time for this version, if applicable.
- JPlatform::RELEASE\_TIME\_ZONE | The timezone for the official release date and time.
- JPlatform::COPYRIGHT | The copyright statement.
- JPlatform::LINK\_TEXT | An HTML hyperlink to the Joomla Project.
- #### Methods
- `JPlatform` has three utility methods, one for testing the version and two
- for display.
- Method | Description
- --------------------------------- | ------------------------
- JPlatform::isCompatible($version) | Tests if $version is the installed version of the platform.
- JPlatform::getShortVersion() | A short textual representation of the platform version.
- JPlatform::getLongVersion() | A really verbose representation of the platform version.
- ```php
- // Tests the required version of the platform.
- if (!JPlatform::isCompatible('11.4'))
- {
- throw new LogicException(sprintf('Platform version %s not compatible.', JPlatform::getShortVersion());
- }
- ```
- ## Class Auto-loading
- `JLoader` is the mainstay of the Joomla Platform as it controls auto-loading of classes.
- It removes the need for the developer to include files by hand, or by using a fall to the `jimport` function.
- Multiple ways of auto loading classes, following different conventions are proposed by JLoader.
- ### The Namespace Loader
- Since the release 12.3 of the Joomla Platform there is the possibility to auto classes within namespaces.
- * A developer can register the full path to a top level (root) namespace where the loader can find classes (within this namespace).
- * A developer can override an existing namespace path by replacing it with a new one.
- * A developer can register multiple paths to the same namespace.
- #### Convention
- The convention is to have the namespace names matching the directories names.
- For example :
- ```php
- <?php
- namespace Chess\Piece;
- 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);
- ```
- ### 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
- supported, bound to the `/libraries/joomla` folder). This allows for
- several scenarios:
- * A developer can register the prefix of custom classes, and a root path to allow the auto-loader to find them.
- * 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');
- // Tell the auto-loader to look for classes starting with "Foo" in a specific folder.
- JLoader::registerPrefix('Foo', '/path/to/custom/packages');
- // Tell the auto-loader to reset the "J" prefix and point it to a custom fork of the platform.
- JLoader::registerPrefix('J', '/my/platform/fork', true);
- ```
- ### 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
- `JLoader`'s discover method. The `discover` method looks at the file names
- in a folder and registers classes based on those names. Additional
- arguments can be used to update the class register and recurse into
- sub-folders.
- ```php
- // Register all files in the /the/path/ folder as classes with a name like: Prefix<Filename>
- JLoader::discover('Prefix', '/the/path/');
- ```