Instruction - Installation - FuelPHP Documentation

Prerequisites

FuelPHP uses Composer, both for installation and for package dependencies. Make sure you installed composer locally before you continue, because the installation methods described below depend on it being present. See the Download Composer page on how to install composer on your machine.

Command Line Installation

using Oil

Our quick installer is a stripped down interface for the Oil package. It allows you to create a new project with one command. You will also no longer need to use 'php' in your oil commands.

To install the quick installer, simply open up a shell and run the following command:

$ curl -L https://get.fuelphp.com/oil | sh

This will ask for your password, as it installs the script to /usr/bin.

Now you can just use 'oil' instead of 'php oil' in your projects.

If you had installed the oil script before version 1.6, you have to re-install it to have it run composer too!

To create a new project simply run:

$ oil create <project_name>

This will create a folder in the directory you are in with the project name you gave. It will then clone the repository and all submodules into that directory.

Note: This will also run $ oil refine install which makes the necessary directories writable, and $ composer update to pull in the defined composer dependencies.

This currently only works on *nix systems (Linux, OS X, Unix, etc).

using Composer

This will create the default installation of the Fuel framework on your virtual host root directory.

Clone the latest release from github

$ cd /where/ever/your/virtualhost/root/is
$ git clone git://github.com/fuel/fuel.git .
$ composer install --prefer-dist

Don't forget the single dot, otherwise this will create a folder called fuel in your virtual host root directory!

Alternatively, you can use composer to install everything in one go:

$ composer create-project fuel/fuel --prefer-dist .

The first method has the advantage that you install the part that will contain your application installed as a git repository. You can change the origin of that repository to your own git server, so your application development is under version control.

The second method creates a complete package with all dependencies. If you want to add that to a git repository, you will also add all dependencies to it. You would like to take this route if your target server on which you run production doesn't have the option to run composer locally to download application dependencies.

Clone the latest development branch from github

$ cd /where/ever/your/virtualhost/root/is
$ git clone git://github.com/fuel/fuel.git -b 1.9/develop .
$ composer install

Don't forget the single dot, otherwise this will create a folder called fuel in your virtual host root directory!

Alternatively, you can use composer to install everything in one go:

$ composer create-project fuel/fuel:dev-1.9/develop --prefer-source .

Both will do exactlt the same, and install the latest development version as local git repository clones.

Download the zip file

If for some reason you can't have access to composer, you can also Download the Fuel Framework in a single ZIP file. It contains exactly the same as the command composer create-project fuel/fuel --prefer-dist . would produce.

Altering the default installation

After installation, you will find a folder structure in your installation directory that looks like this:

/
  docs/
  fuel/
    app/
    core/
    packages/
  public/
    .htaccess
    assets/
    index.php
  oil

In this structure, the public directory in the source equals your web server's public document directory. If you can't define your own public folder (or DocumentRoot) in your webserver configuration, Move its contents of the public directory to the folder your provider dictates, i.e. public_html, public, htdocs, etc.

If you want to re-locate the fuel directory, or any directory inside the fuel directory, you need to modify the constants defined in the web frontloader (public/index.php) and the commandline frontloader (oil) so that they point to the correct app, core and packages directories.

After installation, make sure the permissions are correct on folders that the framework needs access to. There is an oil task available to set the default folders writable:

$ oil refine install
	Made writable: APPPATH/cache
	Made writable: APPPATH/logs
	Made writable: APPPATH/tmp
	Made writable: APPPATH/config

If you haven't installed oil like documented at the top of this page, you can also run oil from the installation root directory using:

$ cd /where/ever/your/virtualhost/root/is
$ php oil refine install
	Made writable: APPPATH/cache
	Made writable: APPPATH/logs
	Made writable: APPPATH/tmp
	Made writable: APPPATH/config

Configuration

The main configuration can be found at app/config/config.php. Edit it to your liking.

URL rewriting

Fuel comes with default rewrite rules for Apache (.htaccess) and IIS (web.config). You can find these files in the web application DOCROOT, by default this is the "public folder". If you use Nginx, please find an example here.

Please note that in some default webserver configuration, URL rewriting is disabled by default. To quickly check if this is the case, make a typo in your rewrite config (for example, in your .htaccess file). If your webserver can read and process the file, a typo should give you a 500 Server error. If the typo you introduced doesn't make a change, changes are rewriting or htaccess processing is disabled in the global config.

Install inside the document root

For security reasons, it is strongly advised NOT to install Fuel inside your webserver's document root.

However, there are cases where you would like to do that, for example for a (local) development environment where Apache's dynamic mass virtual hosting module is used to quickly setup new development environments without the need to restart the webserver.

If you need this, install FuelPHP in the folder you have designated to be the installation root. After you have done that, go into the public folder, move everything in the public folder one level up, and remove the then empty public folder. The only purpose of that folder is to provide an anchor point for your webservers DocumentRoot. You don't need that anymore, since you have installed FuelPHP in the folder that is the DocumentRoot.

After the move, change the location of the application, the packages and the framework core in your index.php to:

define('APPPATH', realpath(__DIR__.'/fuel/app/').DIRECTORY_SEPARATOR);
define('PKGPATH', realpath(__DIR__.'/fuel/packages/').DIRECTORY_SEPARATOR);
define('COREPATH', realpath(__DIR__.'/fuel/core/').DIRECTORY_SEPARATOR);

What about several folders deep?

That doesn't make a difference, the procedure remains exactly the same.

In this case however, accessing your application might be a bit more complicated due to the folder structure involved. But you can't just put a simple .htaccess in, you probably still want to access other stuff installed in that same folder structure.

Assuming you have installed FuelPHP in the folder "/deep/sub/folder" of your DocumentRoot, you would normally have to access your FuelPHP application using the URL http://example.org/deep/sub/folder.

Apache

By placing this .htaccess into one of the higher folders, you can have the browser redirect to your FuelPHP application if no match was found on file or directory name:

<IfModule mod_rewrite.c>
	RewriteEngine on

	# Send request to the subfolder, if it's not a real file, folder or it's a root request
	RewriteCond %{REQUEST_FILENAME} !-f
	RewriteCond %{REQUEST_FILENAME} !-d [OR]
	RewriteCond $1 ^$

	RewriteRule ^(.*)$ /deep/sub/folder [R=301,L]
</IfModule>

Note that this does a redirect, it therefore does not hide the subfolders in the path from the user. If you want that, use this instead:

<IfModule mod_rewrite.c>
	RewriteEngine on

	# Send request to the subfolder, if it's not a real file, folder or it's a root request
	RewriteCond %{REQUEST_FILENAME} !-f
	RewriteCond %{REQUEST_FILENAME} !-d [OR]
	RewriteCond $1 ^$

	RewriteRule ^(.*)$ /deep/sub/folder [QSA,L]
</IfModule>

Obviously, if you place it in the "sub" folder, you can hide "sub/folder" from the URL, but not "deep"...

Note that having a .htaccess enabled will slow your Apache server down considerably. If you have access to the server configuration, consider disabling this functionality, and add the rewrite rules to the virtualhost definition.

Nginx

Nginx doesn't support client configurated files, you so need to add the rewrite to the Nginx configuration file for the virtual host. You can use this as a guideline:

server {
	server_name fuelphp.local;

	# make sure Nginx can write to these files
	access_log /var/www/fuelphp/nginxlogs/access.log;
	error_log /var/www/fuelphp/nginxlogs/error.log;
	root /var/www/fuelphp/public;

	location / {
		index index.php;
		try_files $uri $uri/ /index.php$is_args$args;
	}

	location ~ \.php$ {
		include /etc/nginx/fastcgi_params;
		fastcgi_pass 127.0.0.1:9000;
		fastcgi_index index.php;
		fastcgi_param FUEL_ENV "production";
		fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
	}
}

Setting the Environment

By default, the environment is set to Development mode. Fuel uses the environment to define which database settings to use, but you can use it for other things.

To set the environment, drop the following line into your .htaccess file.

SetEnv FUEL_ENV production

For Nginx, you use the "fastcgi_param" statement as shown in the example above. Available options are detailed in the Class constants of the Fuel Class.