Introduction

How to upgrade depends on how you use FuelPHP in your development project.

In all cases, we assume you have followed the directive not to make any changes to core files, have used class extensions in app/classes to extend core functionality, and copied core configuration files to app/config when you wanted to modify the default configuration.

I just downloaded and installed the zip file

If you have taken this route, it depends from which version you are upgrading.

If you are upgrading from 1.7.1 or newer, chances are you can upgrade using composer by manually updating the oil and public/index.php files, and the composer.json file, either from the fuel/fuel repository or from the latest zipfile. After that, you can run 

$ php composer.phar self-update
$ php composer.phar update --prefer-dist
from the root of your application folder structure.

If you have to upgrade from an earlier version, you must manually remove the following folders: 

$ rm -rf fuel/core/ docs/
$ rm -rf fuel/packages/auth/ fuel/packages/email/ fuel/packages/oil/
$ rm -rf fuel/packages/orm/ fuel/packages/parser/ fuel/vendor/
before executing the composer update command as described above. If you are on a recent version but get composer errors when you attempt to directly update using composer, removing these folders will also allow you to upgrade again.

My project is in its own repository, including the framework files

Use the same procedure. Download the zip, and replace the files. Having them in a repository gives you the benefit though to see the diffs, which makes it easier to work with the changelog to make the required modifications your application (if needed).

Note that if you (still) use SubVersion, pay attention to the hidden `.svn` directories in each folder. Don't delete them when replacing the files!

My project is in its own repository, I use submodules for the FuelPHP repositories

If you have created the submodules manually, you know how it works, and how to update them. If you started with a clone of the fuel/fuel repository, add it as an upstream repository, and pull the master branch of the new version. Deal with any merge issues that may pop up, and run a `git submodule update` to update the submodules to the release version.

Note that it is strongly recommended to remove the submodules, and use composer to update the framework components!

My project is in its own repository, I use separate repositories for the FuelPHP components

If these repositories are your own, add the fuel repositories as upstream remotes, and pull the release branch to update your files. Then push to your repositories to complete the update. If you use fuel's repositories directly, simply switch branches. If the files are included in your app repository, push the changes this creates to your application repository to complete the update.

There are probably more scenario's possible. If you have a different scenario that you think is worth mentioning here, let us know or send us a pull request for this page.

And what about the application?

In most cases, when a new version is released there are also changes to the primary FuelPHP repository, the one that has become your application (i.e. everything in the app folder). As you have made extensive modifications to this folder while creating your application, you have to be a bit careful here. Potentionally three things might have been changed:

The index.php file in public

The index.php is an integral part of the FuelPHP framework, which takes care of setting up the environment and bootstrapping the framework. When you upgrade to a newer FuelPHP version, don't forget to replace this file from the fuel/fuel repository. If you have made changes to it, don't forget to port these changes to the new file!

Included asset files in public

Although the files in public/assets that are included with FuelPHP aren't critical to the framework, they do contain the files of Twitter Bootstrap, which are used in admin code generated by the Oil package. Since a new version of Bootstrap will introduce changes to the way that framework is used, you will have to check the markup of your generated admin code to make sure it still works with the new Bootstrap version.

Other included files

Other files may need upgrading. If you haven't changed them, just replace them with the new version, to make sure you don't run into issues.

oil - the 'Oil' bootstrap script, .htaccess and files needed by PHPUnit.

app/config/config.php - you may see an "There is no security.output_filter defined" error.
Keep your current config file, but copy over the "security" array from the latest version.

app/bootstrap.php - if you still have "Load in the Autoloader" (lines 3-6) these should be removed.
This is the cause of the "Cannot declare class Fuel\Core\Autoloader, because the name is already in use" error.

Using upstream repositories

If you use git to manage your repository, you can add the fuel/fuel repository as an upstream remote to your repository. This will allow you to pull in updates easily. If you use separate repositories for each of the FuelPHP core components, you can do the same for them. This can save you lots of time when it comes to upgrading to a newer version.