Creating and Running a FuelPHP Project in the ServBay Local Development Environment
What is FuelPHP?
FuelPHP is a flexible and modular PHP framework designed for building modern web applications. It adopts the Hierarchical Model-View-Controller (HMVC) design pattern, offering a rich set of features and tools to help developers quickly and efficiently build high-quality web apps. Thanks to its exceptional flexibility, performance, and easy extensibility, FuelPHP has become the framework of choice for many PHP developers.
Key Features and Advantages of FuelPHP
- HMVC Architecture: Supports hierarchical MVC, which enhances code organization, reuse, and modular development—especially beneficial for large or complex projects.
- High Performance: FuelPHP is engineered with performance in mind, renowned for its speed and efficient resource utilization, making it suitable for handling high traffic.
- Easy Extensibility: The framework provides robust extension mechanisms, allowing developers to seamlessly integrate third-party libraries or add custom features to meet specific project requirements.
- Security: Equipped with multiple security features, including automatic input validation, output filtering (preventing XSS), CSRF protection, and SQL injection prevention, FuelPHP helps developers build safer applications.
- Strong Community Support: FuelPHP boasts an active developer community, offering prompt assistance and a wealth of third-party resources.
With these features, FuelPHP empowers developers to swiftly build high-performance, secure, and maintainable web applications for projects ranging from small sites to large enterprise solutions.
Setting Up a FuelPHP Development Environment with ServBay
ServBay is a developer-focused local web development environment that comes pre-installed with PHP, Caddy/Nginx/Apache, MySQL/PostgreSQL/MongoDB, Redis, and other essential services and tools. With ServBay, you can easily set up everything needed for your FuelPHP projects without manual installation or complicated configurations.
This guide walks you through creating and running a FuelPHP project using ServBay’s Websites feature to configure the web server, as well as leveraging its PHP, database, and cache services for rapid access and testing.
Prerequisites
Before you begin, ensure the following:
- ServBay is successfully installed and running on macOS.
- The PHP environment in ServBay is enabled (ServBay enables PHP by default).
- The database service (e.g., MySQL) and cache services (e.g., Redis, Memcached) you intend to use in ServBay are started and working properly.
- Composer is included in ServBay, no separate installation required.
Creating a FuelPHP Project
Recommended Project Storage Path
ServBay recommends developers place all website projects under the /Applications/ServBay/www
directory for easier management and configuration. This guide uses this path as an example.
Navigate to the Website Root Directory
Open the Terminal app and switch to ServBay’s recommended website root directory:
bashcd /Applications/ServBay/www
1Create a Project Directory
Create a new directory for your FuelPHP project, then navigate into it:
bashmkdir servbay-fuelphp-app cd servbay-fuelphp-app
1
2Create a FuelPHP Project with Composer
Run Composer in the project directory to download and initialize the FuelPHP framework. The dot (
.
) means create the project in the current folder:bashcomposer create-project fuel/fuel .
1Composer will automatically download the FuelPHP framework and its dependencies into the
servbay-fuelphp-app
directory.
Configuring the Web Server (Using ServBay Websites Feature)
To access your FuelPHP project via a browser, use ServBay’s Websites feature to set up a virtual host.
- Open the ServBay main interface.
- Click the Websites menu item in the sidebar.
- Click the Add Website button in the top-right corner.
- Fill in the following details in the configuration popup:
- Name: Set a recognizable site name, such as
My First FuelPHP Dev Site
. - Domain: Specify a local development domain, e.g.,
servbay-fuelphp-test.local
. ServBay will automatically resolve this to your local machine. - Website Type: Select
PHP
. - PHP Version: Choose your desired PHP version, e.g.,
8.3
. - Website Root Directory: Specify the entry point for your FuelPHP project. FuelPHP’s main entry file is
public/index.php
, so set the root directory to the project’spublic
subdirectory:/Applications/ServBay/www/servbay-fuelphp-app/public
.
- Name: Set a recognizable site name, such as
- Click Add to save your settings.
ServBay will automatically update your Caddy configuration and reload services to activate the new domain.
For full details, refer to the ServBay documentation on Adding Your First Website.
Configuring FuelPHP Project Service Connections
Most FuelPHP projects require configuration for database and cache service connections.
Database Configuration
FuelPHP’s database settings can be found in fuel/app/config/development/db.php
. Edit this file to add your database connection information. If you’re using ServBay’s default MySQL service:
php
<?php
/**
* The development database settings. These get merged with the global settings.
*/
return [
'default' => [
'connection' => [
'dsn' => 'mysql:host=localhost;dbname=fuel_dev', // Make sure the fuel_dev database exists
'username' => 'root', // ServBay MongoDB default user
'password' => 'root', // ServBay MySQL default password (for local development only!)
],
'identifier' => '`', // MySQL needs backticks as identifiers
],
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
2
3
4
5
6
7
8
9
10
11
12
13
14
Note:
- You need to manually create a
fuel_dev
database in ServBay’s database management tool (such as phpMyAdmin or Adminer). ServBay’s default MySQL user and password are bothroot
, which is recommended only for local development. 'identifier' => '
'` is required for MySQL to ensure proper quoting of table and field names.
Cache Configuration (Memcached and Redis)
FuelPHP supports multiple cache drivers. You can configure the cache driver and connection information in fuel/app/config/cache.php
. Make sure Memcached and/or Redis are started in ServBay.
Memcached Configuration (fuel/app/config/cache.php
):
To use Memcached as the default cache:
php
<?php
return [
'driver' => 'memcached', // Set default driver to memcached
'memcached' => [
'cache_id' => 'fuel', // Cache ID
'servers' => [
'default' => [
'host' => '127.0.0.1', // Memcached listens on this address by default
'port' => 11211, // Memcached default port
'weight' => 100,
],
],
'compression' => false, // Enable or disable compression
],
// ... other cache driver settings
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
ServBay’s PHP versions typically come with the Memcached extension pre-installed.
Redis Configuration (fuel/app/config/redis.php
):
To use Redis, configure its connection info in redis.php
. FuelPHP usually stores Redis settings in a separate file:
php
<?php
return [
'default' => [
'hostname' => '127.0.0.1', // Redis listens on this address by default
'port' => 6379, // Redis default port
'database' => 0, // Redis database index
],
// You can configure multiple Redis connections
];
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
ServBay’s PHP versions typically come with the Redis extension pre-installed.
Examples for Database and Cache Services
To illustrate how FuelPHP communicates with database and cache services, let’s add some sample code.
Preparing a Database Table (Using FuelPHP Migrations)
FuelPHP offers the Oil tool for managing database migrations—a way to version and control your database schema.
Create a Migration File
In your project root (
servbay-fuelphp-app
), use the Oil tool to generate a migration file for theusers
table:bashphp oil generate migration create_users_table
1This creates a new migration file in the
fuel/app/migrations
directory, with a timestamp in its filename.Edit the Migration File
Open the newly created migration file (
fuel/app/migrations/xxxxxxxxxxxx_create_users_table.php
) and edit theup()
method to define the table structure. In thedown()
method, define the rollback actions:php<?php namespace Fuel\Migrations; use Fuel\Core\DBUtil; class Create_users_table { public function up() { // Create users table DBUtil::create_table('users', [ 'id' => ['type' => 'int', 'constraint' => 11, 'auto_increment' => true], 'name' => ['type' => 'varchar', 'constraint' => 100], 'email' => ['type' => 'varchar', 'constraint' => 100, 'unique' => true], ], ['id'], true, 'InnoDB', 'utf8mb4_unicode_ci'); // Specify primary key, enable indexing, set engine and charset } public function down() { // Drop users table (rollback) DBUtil::drop_table('users'); } }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23Run the Migration
In your project root (
servbay-fuelphp-app
), use the Oil tool to apply the migration and create the database table:bashphp oil refine migrate
1If successful, the
users
table will be created in thefuel_dev
database.
Adding Sample Controller Code
Edit fuel/app/classes/controller/welcome.php
to add methods illustrating database and cache operations:
php
<?php
use Fuel\Core\Controller;
use Fuel\Core\Response;
use Fuel\Core\Cache;
use Fuel\Core\DB; // Import DB facade
use Fuel\Core\Redis; // Import Redis facade
class Controller_Welcome extends Controller
{
// Default homepage action
public function action_index()
{
return Response::forge('Hello ServBay!');
}
// Memcached sample action
public function action_memcached()
{
// Try to get data from cache
$value = Cache::get('servbay_memcached_key');
if ($value === false) {
// If not cached, set the data
$value = 'Hello Memcached from ServBay!';
Cache::set('servbay_memcached_key', $value, 60); // Cache for 60 seconds
$value .= ' (from cache)';
} else {
$value .= ' (cached)';
}
return Response::forge($value);
}
// Redis sample action
public function action_redis()
{
// Get Redis instance (default connection)
$redis = \Redis_Db::instance(); // FuelPHP 1.x uses Redis_Db::instance()
// Or use \Redis_Db::instance('connection_name') for multiple connections
// Set data in Redis
$redis->set('servbay_redis_key', 'Hello Redis from ServBay!');
// Get data from Redis
$value = $redis->get('servbay_redis_key');
return Response::forge($value);
}
// MySQL insert sample action
public function action_mysql_add()
{
try {
// Insert a new record into users table
$result = DB::insert('users')->set([
'name' => 'ServBay Demo User ' . time(), // Use timestamp for uniqueness
'email' => 'demo_user_' . time() . '@servbay.test',
])->execute(); // execute() returns an array with the new ID
return Response::forge('User added with ID: ' . $result[0]);
} catch (\Database_Exception $e) {
// Capture database exception, e.g., duplicate email
return Response::forge('Error adding user: ' . $e->getMessage(), 500);
}
}
// MySQL read sample action
public function action_mysql()
{
// Query all records from users table
$users = DB::select('id', 'name', 'email')->from('users')->execute()->as_array();
// Return user list as JSON
return Response::forge(json_encode($users, JSON_PRETTY_PRINT));
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
Note:
- Both
DB
andRedis
facades are imported for convenience (use Fuel\Core\DB;
,use Fuel\Core\Redis;
). - Memcached and Redis keys are prefixed with
servbay_
to avoid conflicts. - The MySQL insert sample includes timestamp-based uniqueness and basic error handling with practical sample text.
- For FuelPHP 1.x, use
\Redis_Db::instance()
to access Redis.
Configuring Routes
To access the controller actions via URLs, configure routes in fuel/app/config/routes.php
. While FuelPHP routes to Controller_Welcome
by default, for memcached
, redis
, mysql_add
, and mysql
actions, you should explicitly add routes.
In fuel/app/config/routes.php
, add or update the returning array as follows:
php
<?php
return array(
'_root_' => 'welcome/index', // Default route to welcome controller’s index action
'_404_' => 'welcome/404', // 404 page route
// Routes for sample actions
'memcached' => 'welcome/memcached',
'redis' => 'welcome/redis',
'mysql_add' => 'welcome/mysql_add',
'mysql' => 'welcome/mysql',
// ... other route configurations
);
1
2
3
4
5
6
7
8
9
10
11
12
13
2
3
4
5
6
7
8
9
10
11
12
13
Accessing and Testing the Website
You can now use your browser to access the domain you set up in ServBay, such as https://servbay-fuelphp-test.local
, to test your FuelPHP project and its service connections.
- Access the default page:
https://servbay-fuelphp-test.local
- Expected output:
Hello ServBay!
- Expected output:
- Test Memcached:
https://servbay-fuelphp-test.local/memcached
- First-time output might be:
Hello Memcached from ServBay! (from cache)
(if cache is working) - Subsequent visits might show:
Hello Memcached from ServBay! (cached)
(if cache active and not expired)
- First-time output might be:
- Test Redis:
https://servbay-fuelphp-test.local/redis
- Expected output:
Hello Redis from ServBay!
(if Redis is running)
- Expected output:
- Add a user to MySQL:
https://servbay-fuelphp-test.local/mysql_add
- Expected output:
User added with ID: [new inserted ID]
(if MySQL and table are set up)
- Expected output:
- Read MySQL user list:
https://servbay-fuelphp-test.local/mysql
- Expected output: A JSON array containing all records from the
users
table (if MySQL and table hold data)
- Expected output: A JSON array containing all records from the
About HTTPS: ServBay automatically configures SSL certificates for local sites, trusted via ServBay User CA or ServBay Public CA. If your browser warns that the certificate is untrusted, ensure that you have trusted ServBay’s CA certificate in your system.
Important Notes
- Make sure all required services—PHP (your chosen version), Caddy (or Nginx/Apache), MySQL (for database), Redis (for caching), Memcached (for caching)—are running in the ServBay main interface.
- Ensure that you have manually created the
fuel_dev
database in ServBay’s database management tool, or configured another existing database indb.php
. FuelPHP’s migration tooloil refine migrate
creates tables within the specified database but does not create the database itself. - FuelPHP’s public entry file is
public/index.php
, so in ServBay’s Websites configuration, the website root directory must point to the project’spublic
subfolder.
Conclusion
With ServBay, you can effortlessly set up a complete local development environment for FuelPHP projects on macOS. This guide has covered how to create a FuelPHP project, configure ServBay’s Websites feature, set up database and cache service connections, and validate everything via practical sample code. ServBay’s pre-integrated services and streamlined configuration greatly enhance productivity.
We hope this guide helps you kickstart your FuelPHP development journey with ServBay!