Creating and Running a Webman Project in ServBay

What is Webman?

Webman is a high-performance PHP asynchronous web framework built on Workerman, designed for the development of high-concurrency and high-performance web applications. Unlike traditional synchronous blocking frameworks, Webman uses an event-driven and asynchronous non-blocking I/O model, allowing it to excel in handling large volumes of concurrent requests. Webman offers a clean and easy-to-use API with a flexible extension mechanism, making it ideal for building real-time applications, API services, microservices, and more.

Key Features and Advantages of Webman

• High Performance: Built on Workerman’s event-driven, asynchronous non-blocking I/O, Webman can handle massive concurrent connections and provides far greater throughput than traditional synchronous frameworks.
• Ease of Use: Offers an intuitive API and a rich set of features, helping developers get started quickly and efficiently build applications.
• Multi-Protocol Support: Natively supports HTTP, WebSocket, and other common application layer protocols, making it easy to develop various types of services.
• Flexible Extensions: Easily extendable via Composer packages, plugins, and middleware.
• Low Resource Usage: As a resident memory application, Webman consumes fewer resources compared to the traditional Web Server + PHP-FPM architecture.
• Strong Community Support: Maintained by an active developer community and extensive documentation.

Webman empowers developers to rapidly build high-performance, highly available web applications and API services—especially suited for scenarios requiring high concurrency and low latency.

Creating and Running a Simple Webman Project with ServBay

This guide details how to use ServBay’s local development environment to create and run a simple Webman web project. We’ll walk through installing Webman, writing basic routing and controller code, and integrating ServBay’s database services (MySQL, PostgreSQL) and cache services (Redis, Memcached).

TIP

ServBay recommends storing all your local website projects in the /Applications/ServBay/www directory for unified management—for example, when configuring local sites (formerly “hosts”).

Prerequisites

Before getting started, ensure you have completed the following steps:

1. Install ServBay: ServBay should be successfully installed on your macOS system, providing an all-in-one local development environment with PHP, Composer, MySQL, PostgreSQL, Redis, Memcached, and all required components for this guide.
2. Enable Required Packages: Using the ServBay control panel, confirm that the following packages are installed and running:
   • Your chosen PHP version (recommended: PHP 8.x or later)
   • Composer (pre-installed with ServBay)
   • MySQL
   • PostgreSQL
   • Redis
   • Memcached
   • Ensure your selected PHP version has enabled the necessary extensions: memcached, redis, pdo_mysql, pdo_pgsql, etc. ServBay usually enables these by default; you can double-check in the ServBay PHP configuration interface.
3. Terminal Access: Be familiar with using the macOS Terminal app.

Installing Webman

1. Verify Composer Is Available

   ServBay comes with Composer pre-installed and configured for direct usage in the terminal. Check by running:

   composer --version

   If Composer version info appears, you’re ready to proceed.

2. Navigate to the ServBay Website Directory

   Open Terminal and move into ServBay’s recommended web root directory:

   cd /Applications/ServBay/www

3. Create a Webman Project with Composer

   Use the Composer create-project command to install the Webman framework in your chosen directory. Name the project servbay-webman-app:

   composer create-project workerman/webman servbay-webman-app

   Composer will download Webman and its core dependencies into the servbay-webman-app folder.

4. Enter the Project Directory

   Once installation completes, switch to your new project folder:

   cd servbay-webman-app

5. Install Required Components

   To showcase database and caching features, install several extra Composer packages. Webman commonly uses illuminate/database (Laravel’s database component), illuminate/redis, etc. The -W option (--with-dependencies) helps resolve dependency conflicts and ensures compatibility.

   composer require -W illuminate/database illuminate/redis illuminate/pagination illuminate/events symfony/var-dumper

   This command installs a database ORM, Redis client, pagination, event dispatcher, and Symfony’s VarDumper for debugging.

Creating the Database and Tables

To run the example code, you need to create the appropriate database and users table in ServBay’s MySQL and PostgreSQL. ServBay’s default database root password is password.

You can use ServBay’s database management tools like phpMyAdmin or pgAdmin (accessible through the ServBay control panel) or run the following SQL statements via command line.

1. Create the webman_app Database

   • MySQL:

     CREATE DATABASE IF NOT EXISTS webman_app CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

   • PostgreSQL:

     CREATE DATABASE webman_app;

2. Create the users Table in webman_app Database

   • MySQL:

     USE webman_app;
     CREATE TABLE users (
         id INT AUTO_INCREMENT PRIMARY KEY,
         name VARCHAR(255) NOT NULL,
         email VARCHAR(255) NOT NULL UNIQUE,
         created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
     );

   • PostgreSQL:

     \c webman_app; -- connect to the newly created database
     CREATE TABLE users (
         id SERIAL PRIMARY KEY,
         name VARCHAR(255) NOT NULL,
         email VARCHAR(255) NOT NULL UNIQUE,
         created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
     );

Writing Web Project Code

Now, let’s add code to define routes, create controllers, and handle logic for database and cache interactions.

1. Configure Routes

   Edit the config/route.php file in your project’s root directory to define the required example routes:

   <?php
   
   use Webman\Route;
   use app\controller\IndexController;
   use app\controller\CacheController;
   use app\controller\DatabaseController;
   
   // Define root route mapping to IndexController’s index method
   Route::any('/', [IndexController::class, 'index']);
   
   // Define cache-related routes
   Route::any('/memcached', [CacheController::class, 'memcached']);
   Route::any('/redis', [CacheController::class, 'redis']);
   
   // Define database-related routes
   Route::any('/mysql-add', [DatabaseController::class, 'mysqlAdd']);
   Route::any('/mysql', [DatabaseController::class, 'mysqlGet']);
   Route::any('/pgsql-add', [DatabaseController::class, 'pgsqlAdd']);
   Route::any('/pgsql', [DatabaseController::class, 'pgsqlGet']);
   
   // Add more routes here as needed...

2. Create Controller Files

   In the app/controller directory, create IndexController.php, CacheController.php, and DatabaseController.php as follows.

   • app/controller/IndexController.php: Handles root path requests.

     <?php
     
     namespace app\controller;
     
     use support\Request;
     use support\Response; // Import the Response class
     
     class IndexController
     {
         /**
          * Example method for handling root path requests
          * @param Request $request The current request object
          * @return Response Returns a Response object
          */
         public function index(Request $request): Response // Specify return type
         {
             // Return a simple text response
             return response('Hello ServBay & Webman!'); // Welcome message
         }
     }

   • app/controller/CacheController.php: Demonstrates Memcached and Redis usage.

     <?php
     
     namespace app\controller;
     
     use support\Request;
     use support\Response;
     use Memcached; // Import the Memcached class
     use support\Redis; // Import Webman’s Redis Facade
     
     class CacheController
     {
         /**
          * Demonstrates using Memcached
          * @param Request $request
          * @return Response
          */
         public function memcached(Request $request): Response
         {
             // Connect to Memcached server; ServBay defaults to 127.0.0.1:11211
             $memcached = new Memcached();
             $memcached->addServer('127.0.0.1', 11211);
     
             // Set cache item, expires in 60 seconds
             $success = $memcached->set('servbay_key', 'Hello Memcached from ServBay!', 60); // Set key and value
             if (!$success) {
                  return response('Failed to set Memcached key', 500);
             }
     
             // Get cache item
             $value = $memcached->get('servbay_key'); // Retrieve key
     
             // Return the value obtained
             return response($value ?: 'Memcached key not found or expired'); // Message if key missing
         }
     
         /**
          * Demonstrates using Redis
          * @param Request $request
          * @return Response
          */
         public function redis(Request $request): Response
         {
             // Set cache item using Webman’s Redis Facade
             Redis::set('servbay_redis_key', 'Hello Redis from ServBay!'); // Set key and value
     
             // Get cache item using Webman’s Redis Facade
             $value = Redis::get('servbay_redis_key'); // Retrieve key
     
             // Return the value obtained
             return response($value ?: 'Redis key not found'); // Message if key missing
         }
     }

   • app/controller/DatabaseController.php: Demonstrates MySQL and PostgreSQL operations.

     <?php
     
     namespace app\controller;
     
     use support\Request;
     use support\Response;
     use support\Db; // Import Webman’s Db Facade
     
     class DatabaseController
     {
         /**
          * Add a user to MySQL
          * @param Request $request
          * @return Response
          */
         public function mysqlAdd(Request $request): Response
         {
             try {
                 // Connect to 'mysql' and insert data
                 Db::connection('mysql')->table('users')->insert([
                     'name' => 'ServBay Webman MySQL User', // Demo data
                     'email' => 'mysql_demo@servbay.test', // Demo email
                     'created_at' => date('Y-m-d H:i:s') // Created date
                 ]);
                 return response('User added to MySQL'); // Confirmation message
             } catch (\Exception $e) {
                 return response('Error adding user to MySQL: ' . $e->getMessage(), 500); // Error handling
             }
         }
     
         /**
          * Get user list from MySQL
          * @param Request $request
          * @return Response
          */
         public function mysqlGet(Request $request): Response
         {
             try {
                 // Connect to 'mysql' and fetch all users
                 $users = Db::connection('mysql')->table('users')->get();
                 // Return users list in JSON format
                 return response(json_encode($users), 200, ['Content-Type' => 'application/json']); // Explicit Content-Type
             } catch (\Exception $e) {
                  return response('Error getting users from MySQL: ' . $e->getMessage(), 500); // Error handling
             }
         }
     
         /**
          * Add a user to PostgreSQL
          * @param Request $request
          * @return Response
          */
         public function pgsqlAdd(Request $request): Response
         {
              try {
                 // Connect to 'pgsql' and insert data
                 Db::connection('pgsql')->table('users')->insert([
                     'name' => 'ServBay Webman PgSQL User', // Demo data
                     'email' => 'pgsql_demo@servbay.test', // Demo email
                     'created_at' => date('Y-m-d H:i:s') // Created date
                 ]);
                 return response('User added to PostgreSQL'); // Confirmation message
              } catch (\Exception $e) {
                 return response('Error adding user to PostgreSQL: ' . $e->getMessage(), 500); // Error handling
              }
         }
     
         /**
          * Get user list from PostgreSQL
          * @param Request $request
          * @return Response
          */
         public function pgsqlGet(Request $request): Response
         {
              try {
                 // Connect to 'pgsql' and fetch all users
                 $users = Db::connection('pgsql')->table('users')->get();
                 // Return users list in JSON format
                 return response(json_encode($users), 200, ['Content-Type' => 'application/json']); // Explicit Content-Type
              } catch (\Exception $e) {
                 return response('Error getting users from PostgreSQL: ' . $e->getMessage(), 500); // Error handling
              }
         }
     }

3. Configure Database Connections

   Edit the config/database.php in your project root to set MySQL and PostgreSQL connection info. ServBay’s default database host is 127.0.0.1, ports are 3306 (MySQL) and 5432 (PostgreSQL), with root as username and password as password.

   <?php
   /**
    * Database configuration
    */
   return [
       // Default database connection
       'default' => 'mysql',
   
       // List of connection configurations
       'connections' => [
           'mysql' => [
               'driver'    => 'mysql',
               // ServBay’s default MySQL host and port
               'host'      => '127.0.0.1',
               'port'      => 3306,
               // Database name created previously
               'database'  => 'webman_app',
               // ServBay’s default MySQL username
               'username'  => 'root',
               // ServBay’s default MySQL password
               'password'  => 'password',
               'charset'   => 'utf8mb4',
               'collation' => 'utf8mb4_unicode_ci',
               'prefix'    => '',
               'strict'    => true,
               'engine'    => null,
           ],
           'pgsql' => [
               'driver'   => 'pgsql',
               // ServBay’s default PostgreSQL host and port
               'host'     => '127.0.0.1',
               'port'     => 5432,
                // Database name created previously
               'database' => 'webman_app',
                // ServBay’s default PostgreSQL username
               'username' => 'root',
                // ServBay’s default PostgreSQL password
               'password' => 'password',
               'charset'  => 'utf8',
               'prefix'   => '',
               'schema'   => 'public',
               'sslmode'  => 'prefer', // Or require, verify-ca, verify-full
           ],
           // Add more connections here as needed...
       ],
   ];

   Important: In production, always change the default database password and avoid hardcoding sensitive credentials in code.

Running the Webman Project

Webman projects are typically started using the start.php script, which launches Workerman processes. Unlike traditional Nginx/Apache + PHP-FPM, Webman runs as a resident asynchronous application.

From your project root (/Applications/ServBay/www/servbay-webman-app), start the Webman project with:

php start.php start

On success, you’ll see the Webman startup info; by default, it listens for HTTP requests on 127.0.0.1:8787.

• Note: The php command uses ServBay’s PHP executable. ServBay automatically configures your terminal so you can use its PHP version directly.
• To run Webman in the background, add -d: php start.php start -d.
• To stop Webman, run: php start.php stop.
• To restart Webman, run: php start.php restart.
• For smooth restarts (without interrupting current requests), run: php start.php reload.

Testing the Project

Once Webman is running and listening on 127.0.0.1:8787, test each feature in your browser via the following URLs:

• http://localhost:8787/: Outputs Hello ServBay & Webman!.
• http://localhost:8787/memcached: Outputs Hello Memcached from ServBay!—a successful ServBay Memcached connection.
• http://localhost:8787/redis: Outputs Hello Redis from ServBay!—a working ServBay Redis connection.
• http://localhost:8787/mysql-add: Outputs User added to MySQL—inserts a record into the MySQL users table.
• http://localhost:8787/mysql: Returns JSON with the MySQL users table contents.
• http://localhost:8787/pgsql-add: Outputs User added to PostgreSQL—inserts a record into the PostgreSQL users table.
• http://localhost:8787/pgsql: Returns JSON with the PostgreSQL users table contents.

If you encounter issues, check the terminal for Webman errors, confirm MySQL, PostgreSQL, Redis, and Memcached are running in ServBay, and verify the required PHP extensions are enabled.

Frequently Asked Questions (FAQ)

• Q: Can’t find the php start.php start command?
  • A: Make sure you’ve cd into the servbay-webman-app directory in your terminal. Also, confirm that ServBay’s PHP is correctly added to your system’s PATH (ServBay usually handles this automatically).
• Q: Unable to access localhost:8787?
  • A: Check your terminal for errors when running php start.php start. Ensure port 8787 isn’t occupied by another process. If needed, update the listening port in Webman’s configuration (e.g., edit config/server.php).
• Q: Database connection failure?
  • A: Confirm MySQL and PostgreSQL are running in ServBay. Check that your settings (host, port, database, username, password) in config/database.php match ServBay’s defaults (user: root, password: password). Ensure the webman_app database and users table exist.
• Q: Memcached or Redis connection failure?
  • A: Ensure Memcached and Redis are running in ServBay. Check connection host and port in app/controller/CacheController.php (127.0.0.1:11211, 127.0.0.1:6379 by default). Confirm your PHP version has enabled the memcached and redis extensions.

Conclusion

Following these steps, you’ve successfully created, configured, and run a basic Webman project locally in the ServBay development environment. You’ve learned how to quickly set up Webman with ServBay’s all-in-one services and integrate database and caching functionality. Webman’s high performance paired with ServBay’s convenience gives your asynchronous PHP development a powerful boost. We hope this guide enables you to build outstanding web applications using ServBay and Webman.