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.

1. Navigate to the Website Root Directory

   Open the Terminal app and switch to ServBay’s recommended website root directory:

   cd /Applications/ServBay/www

2. Create a Project Directory

   Create a new directory for your FuelPHP project, then navigate into it:

   mkdir servbay-fuelphp-app
   cd servbay-fuelphp-app

3. Create 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:

   composer create-project fuel/fuel .

   Composer 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.

1. Open the ServBay main interface.
2. Click the Websites menu item in the sidebar.
3. Click the Add Website button in the top-right corner.
4. 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’s public subdirectory: /Applications/ServBay/www/servbay-fuelphp-app/public.
5. 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
/**
 * 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
    ],
];

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 both root, 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
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
];

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
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
];

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.

1. Create a Migration File

   In your project root (servbay-fuelphp-app), use the Oil tool to generate a migration file for the users table:

   php oil generate migration create_users_table

   This creates a new migration file in the fuel/app/migrations directory, with a timestamp in its filename.

2. Edit the Migration File

   Open the newly created migration file (fuel/app/migrations/xxxxxxxxxxxx_create_users_table.php) and edit the up() method to define the table structure. In the down() method, define the rollback actions:

   <?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');
       }
   }

3. Run the Migration

   In your project root (servbay-fuelphp-app), use the Oil tool to apply the migration and create the database table:

   php oil refine migrate

   If successful, the users table will be created in the fuel_dev database.

Adding Sample Controller Code

Edit fuel/app/classes/controller/welcome.php to add methods illustrating database and cache operations:

<?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));
    }
}

Note:

• Both DB and Redis 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
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
);

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!
• 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)
• Test Redis: https://servbay-fuelphp-test.local/redis
  • Expected output: Hello Redis from ServBay! (if Redis is running)
• 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)
• 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)

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 in db.php. FuelPHP’s migration tool oil 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’s public 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!