FuelPHP - Packages

Packages are similar to modules in code reuse but differs in the following ways,

  • It does not map to the web URLs
  • It is not approachable through HMVC requests

In short, packages are not direct web functionalities such as blog, album, etc. Instead, it is a library of functions grouped together such as email processing, document creation, chart creation, authentication, etc. which aids in faster development of the web application.

Creating Packages

To create a package, first we need to arrange our source code specified as follows.

/fuel 
   /packages 
      /package (root directory of package) 
         /bootstrap.php 
      /classes 
         /our.php 
      /classes.php 
         /here.php 
      /config 
         /config.php 
         /and_so_on

The structure of the package has two package specific files, config.php and bootstrap.php files. The purpose of the configuration file is to group the configuration of the package under the package folder itself without disturbing the main application. The purpose of the bootstrap file is to set the namespace so that the autoloader loads it properly.

Some ways to set the namespace is as follows,

Autoloader::add_namespace('Mypackage', __DIR__.'/classes/'); 
Autoloader::add_core_namespace('Mypackage'); 
Autoloader::add_core_namespace('Mypackage', true); 
Autoloader::add_classes (array( 
   'Mypackage\\Classname' => __DIR__.'/classes/classname.php', 
   'Mypackage\\Anotherclass' => __DIR__.'/classes/anotherclass.php', 
));

Once the bootstrap file is properly configured and packages are loaded into the application, we can use it as follows.

$instance = new Myclass; 
$instance = new Mynamespace\Myclass;

Installing Packages

Packages are usually placed under fuel/packages directory. By default, the following packages are installed,

  • auth − Authentication package

  • email − Email package

  • oil − Fuel's command, oil package

  • orm − ORM package

  • parser − Markdown parser package

To install a new package, following are the two options,

Option 1 − Manual installation - download and install

To manually install the package, first download the package from the author's website. Unpack it and place it under fuel/packages/ folder.

Option 2 − Automatic method using oil command

FuelPHP provides an automated way of installing the packages hosted in github. Use the following command to install the package, mytestpackage.

php oil package install mytestpackage

It clones the package source code using git client and moves it to fuel/packages folder. If git client is not available, then we can use –direct command argument to direct the command to download and install the packages as follows.

php oil package install mytestpackage --direct

Using Packages

Packages can be used in the application once it is loaded into the application. There are two ways to load the packages into the application.

Option 1 − Through Package class

FuelPHP provides a class, Package to load, unload, and check the availability of the packages through load, unload, and loaded methods, respectively. load method has two parameters. The first parameter, $package is the name of the package and second parameter, path is the path of the package. The second parameter is optional, if the package is installed in fuel/packages folder.

// load the orm package 
Package::load('orm');  

// load the parser package from a specific directory 
Package::load('parser', '/path/to/packages/dir/');  

// load the non-existent package 
Package::load('awesome'); // Throws a PackageNotFoundException

Option 2 − Through configuration file

To load a package permanently, just add the package under always_load configuration entry in the main configuration file, fuel/app/config/config.php. To load email package, use the following syntax.

'always_load' => array ( 
   'packages' => array ( 
      'email', 
   ), 
),

Once packages are loaded into the application, we can use it as follows.

$instance = new Myclass; 
$instance = new Mynamespace\Myclass;
Advertisements