Fuel PHP – How To – Extending or Changing a Core Class

Hi Everyone,

I’m going to be sharing a series of mini guides on the Fuelphp.com Framework as I learn it. For those that don’t know me, I’ve never been heavily in to OOP, and I whilst I use classes, I never leverage what’s possible with the latest changes in PHP5. I’ve noticed there’s good documentation for FuelPHP but no many guides, especially for people who are picking FuelPHP as their first PHP Framework.

The documentation for Fuel PHP is available here:- http://fuelphp.com/docs/index.html

Objective:-

  • Create a Custom Version of a Core Class.
  • Tell FuelPHP to use it instead of the original.

The reason we don’t make changes to the original are, when the framework is upgraded, your changes will be overwritten. But if we Copy the Original File or Class, and then modify, and put in the App Extensions folder, then that will be used instead.

App Extensions Folder?

Inside the Fuel Folder (Which isn’t supposed to be public facing) are sub folders called:-

  • App – Your Apps Custom Files
  • Core – Classes that Ship with FuelPHP as Standard
  • Packages – Place to Extend the Core or keep 3rd Party Code without Messing up the MVC file structure.
  • Vendor – Location of Dependency Packages typically installed by Composer.

The App Folder

The app folder has a Bootstrap.php, it’s in this file where we tell FuelPHP to use our own class.

My Example

Let’s modify a Core Class which handles the Database Connection. Browse to this folder and open the file:-

Fuel >>> Core >>> Classes> Database >>> Mysqli >>> connection.php

You’ll notice the file has a Namespace specificying that this file and included class is a FuelCore file.

Problem is, this class is already extending another class, and PHP doesn’t like do this currently (there are new methods in PHP 5.6 I believe). You could copy class, rename it, and rename all the references through the code, but that isn’t a good idea.

What you do is:-

  1. In Windows Explorer or your Favourite IDE, browse to this folder:
    Fuel >>> App >>> Classes >>> Extension
  2. If the folder “Extension” doesn’t exist, create it.
  3. Copy the Core database>>> mysqli >>> connection.php file from the Core to the extensions folder.
    (For me, I recreate the directory structure in core inside of extensions, purely so I know where the file came from based on how it’s save, and it groups functionality together.
  4. You’ve probably already setup up your database connection, so I want you to break it, but changing the config database password inside of App >>> Config >>> config.php
  5. Modify the file in some way, for me, on Line 125 is a row that catches an error if the database connection fails. On my installation of FuelPHP it shows a white page, which isn’t useful, the code should display an error, but mine hasn’t, I’ll get to that later. I decided to write a simple message to verify my class extension and autoloading was working as expected. 
    echo "Sorry Database Connection Failed, mysql details incorrect";
  6. The class copy inside of extensions won’t be loaded as this time, the first couple of times I tried nothing happened, then I had a look at the Fuel >>> Core >>> Bootstrap.php
  7. Inside of that is a function called setup_autoloader(), and add_classes, this file essentially tells fuel php where to load all the php files from, to override the original, you need to copy and Key/Value of the original. This is what mine looks like:- 
    'Fuel\Core\Database_Mysql_Connection'      => COREPATH.'classes/database/mysql/connection.php',
  8. All that’s doing is telling the autoloader to include the Core File version where is found it originally.
  9. The App Bootloader takes priority, it has an “add_classes” section as well, so paste our new code there.
  10. Then modify the code to point to the Copy we changed in the Extensions Folder 
    'Fuel\Core\Database_Mysql_Connection'      => APPPATH.'classes/database/mysql/connection.php',
  11. If you recreate the original directory structure, you simply need to change it from COREPATH to APPPATH. Alternatively, put in the path to your modified file.
  12. If you refresh FuelPHP in a Browser, you should see your message, which is an indicator that the new Class is being loaded instead of the original.