在 ServBay 中建立並運行 Laravel 專案

概述

ServBay 是一款功能強大的本地 Web 開發環境，支援 macOS 與 Windows，內建多種主流套件，包括 PHP、Node.js、Python、Go、Java、多種資料庫（MySQL、PostgreSQL、MongoDB）、快取服務（Redis、Memcached）以及網頁伺服器（Caddy、Nginx、Apache）。

本文件將指引您如何於 ServBay 環境中快速建立、設定並運行 Laravel 專案。我們會善用 ServBay 內建的 PHP 環境、Composer 套件管理器，並藉助強大的網站（原稱「主機」）管理功能，讓整個流程更簡便流暢。

什麼是 Laravel？

Laravel 為 Taylor Otwell 所創立的，廣受歡迎的開源 PHP Web 應用框架。其採用 MVC（模型-視圖-控制器）架構，並提供許多即取即用功能，能簡化 Web 開發中常見任務，如使用者認證、路由管理、工作階段管理、快取與資料庫操作。Laravel 以優雅語法、豐富功能及強大社群聞名，是建構現代化、易維護 Web 應用的理想選擇。

Laravel 的主要特色與優勢

• 優雅語法： 代碼簡潔且具表現力，提升開發效率與可讀性。
• Eloquent ORM： 提供強大的 ActiveRecord 實作，讓資料庫操作直觀輕鬆。
• Artisan 命令列工具： 內建多種實用指令，能執行資料庫遷移、程式碼產生、測試等任務。
• Blade 模板引擎： 語法簡潔，方便建立動態視圖。
• 豐富生態系： 擁有大量官方與第三方套件，可透過 Composer 輕鬆整合。
• 強大社群支援： 活躍社群提供大量資源、教學及解決方案。

使用 ServBay 開發 Laravel 專案的優勢

ServBay 為 Laravel 開發者帶來極大便利：

• 整合環境： ServBay 預安裝多組 PHP 版本、Composer，以及主流資料庫與快取服務，無需分別安裝與設定。
• 易於管理： 透過 ServBay 圖形介面，能輕鬆切換 PHP 版本、管理網站設定、啟動/停止服務。
• 預先最佳化的網頁伺服器： ServBay 預設使用 Caddy，並針對主流 PHP 框架（如 Laravel）進行最佳化，簡化伺服器設置。
• HTTPS 支援： ServBay 會自動為 .local 網域配置 ServBay User CA 發放的 SSL 憑證，預設啟用 HTTPS，讓本地開發更安全且貼近正式環境。

建立 Laravel 專案

ServBay 建議將您的網站專案統一存放於以下目錄，有助於結構整齊且易於管理：

• macOS: /Applications/ServBay/www
• Windows: C:\ServBay\www

1. 確認 Composer 已安裝

   ServBay 安裝過程中已自帶 Composer，無需額外安裝。您可開啟終端機驗證 Composer 是否可用：

   composer --version

   若指令執行後顯示版本號，就代表 Composer 已就緒。

2. 建立新的 Laravel 專案

   開啟終端機，移動至 ServBay 推薦的網站目錄，並使用 Composer 建立新 Laravel 專案。此範例將專案目錄命名為 servbay-laravel-app：

   macOS:

   cd /Applications/ServBay/www
   # 建立專案目錄
   mkdir servbay-laravel-app
   # 進入專案目錄
   cd servbay-laravel-app
   # 使用 Composer 將 Laravel 專案安裝至目前目錄
   composer create-project --prefer-dist laravel/laravel .

   Windows:

   cd C:\ServBay\www
   # 建立專案目錄
   mkdir servbay-laravel-app
   # 進入專案目錄
   cd servbay-laravel-app
   # 使用 Composer 將 Laravel 專案安裝至目前目錄
   composer create-project --prefer-dist laravel/laravel .

   Composer 將自動下載並安裝 Laravel 及其所有相依套件。

3. 進入專案目錄

   請確定您的終端機目前所在之目錄為新建立的 Laravel 專案根目錄：

   macOS:

   cd /Applications/ServBay/www/servbay-laravel-app

   Windows:

   cd C:\ServBay\www\servbay-laravel-app

初始設定

1. 產生應用程式密鑰

   Laravel 需要一組密鑰來保護使用者工作階段及加密資料。請於專案根目錄執行 Artisan 指令產生密鑰：

   專案根目錄路徑:

   • macOS: /Applications/ServBay/www/servbay-laravel-app
   • Windows: C:\ServBay\www\servbay-laravel-app

   php artisan key:generate

   此指令將於 .env 檔案中自動產生與設定 APP_KEY。

2. 設定環境變數 (.env)

   Laravel 使用 .env 來管理專案環境參數，諸如資料庫連線、應用程式網址等。請開啟專案根目錄下的 .env 檔，依需求設定。請確認以下基礎配置正確填寫：

   APP_NAME=ServBay Laravel Demo
   APP_ENV=local
   APP_KEY=base64:... # 此值已由 php artisan key:generate 產生
   APP_DEBUG=true
   APP_URL=https://servbay-laravel-test.local
   
   LOG_CHANNEL=stack
   
   # 資料庫設定範例 (MySQL)
   DB_CONNECTION=mysql
   DB_HOST=127.0.0.1
   DB_PORT=3306
   DB_DATABASE=servbay_laravel_app # 欲使用的資料庫名稱
   DB_USERNAME=root # ServBay 預設資料庫使用者
   DB_PASSWORD=password # ServBay 預設資料庫密碼
   
   # 快取/佇列設定範例 (Redis)
   CACHE_STORE=redis
   REDIS_HOST=127.0.0.1
   REDIS_PASSWORD=null # ServBay 預設 Redis 無密碼
   REDIS_PORT=6379
   
   # 快取/佇列設定範例 (Memcached)
   # CACHE_STORE=memcached
   # MEMCACHED_HOST=127.0.0.1
   # MEMCACHED_PORT=11211

   注意： 您可能需依實際所用資料庫或服務，調整 DB_*、REDIS_*、MEMCACHED_* 等配置。ServBay 預設資料庫帳號及密碼可於 ServBay 控制面板查詢。

設定網頁伺服器（於 ServBay 新增網站）

善用 ServBay 的網站管理功能，將網域指向 Laravel 專案的 public 目錄。

1. 開啟 ServBay 控制面板

   啟動 ServBay 應用程式，開啟控制面板。

2. 新增網站

   進入 ServBay 控制面板的「網站」區塊。點擊新增按鈕（通常是 + 或類似圖示），建立新網站。

3. 填寫網站設定

   依下列範例填寫網站設定資訊：

   • 名稱 (Name)： My First Laravel Dev Site（方便辨識用的名稱）

   • 網域 (Domain)： servbay-laravel-test.local（瀏覽器欲使用的網域）

   • 網站類型 (Site Type)： PHP

   • PHP 版本 (PHP Version)： 選擇符合您 Laravel 版本的 PHP，如 8.3。

   • 網站根目錄 (Site Root)：

     • macOS: /Applications/ServBay/www/servbay-laravel-app/public
     • Windows: C:\ServBay\www\servbay-laravel-app\public

     （重要：必須指向 Laravel 專案根目錄下的 public 資料夾）

   更詳細步驟及選項請參考 ServBay 官方文件之 新增第一個網站 指南（請查閱英文版連結）。

4. 儲存並套用變更

   儲存您的網站設定。ServBay 會自動更新網頁伺服器設定（預設為 Caddy）。如有提示須重啟網頁伺服器，請依指示操作。

驗證基本訪問

此時，您的 Laravel 專案應可透過設定的網域正常訪問。

1. 開啟瀏覽器

   於瀏覽器輸入設定的網域，如 https://servbay-laravel-test.local。

2. 檢查結果

   若設定正確，應會看到 Laravel 歡迎頁面。

新增簡易範例程式

為更直觀驗證運作狀態，可於 routes/web.php 新增一組路由，顯示 "Hello ServBay!"。

請至專案目錄的 routes/web.php 檔案，新增或修改下列內容：

<?php

use Illuminate\Support\Facades\Route;

/*
|--------------------------------------------------------------------------
| Web Routes
|--------------------------------------------------------------------------
|
| Here is where you can register web routes for your application. These
| routes are loaded by the RouteServiceProvider within a group which
| contains the "web" middleware group. Now create something great!
|
*/

Route::get('/', function () {
    return 'Hello ServBay!'; // 修改或新增此行
});

// ... 其他路由

儲存後，再次訪問 https://servbay-laravel-test.local，即可於瀏覽器看到 Hello ServBay! 輸出。

資料庫整合範例

Laravel 提供強大的資料庫抽象與 ORM（Eloquent），便於連接各類資料庫。ServBay 預安裝 MySQL、PostgreSQL、MongoDB、Redis、Memcached，讓本地開發測試更便利。

NoSQL 資料庫範例

ServBay 已整合 Redis 及 Memcached，且相關 PHP 擴充模組皆已預裝。

Memcached 範例

1. 設定 .env

   若尚未設定，可於 .env 中指定 Memcached 連線資訊：

   CACHE_STORE=memcached
   MEMCACHED_HOST=127.0.0.1
   MEMCACHED_PORT=11211 # ServBay 預設 Memcached 埠號

2. 使用 Memcached

   可於路由或控制器透過 Laravel Cache facade 存取 Memcached：

   於 routes/web.php 新增路由範例：

   use Illuminate\Support\Facades\Cache;
   
   Route::get('/memcached-test', function () {
       // 存入快取，保存 10 分鐘（600 秒）
       Cache::put('servbay_memcached_key', 'Hello from Memcached on ServBay!', 600);
   
       // 取出快取資料
       $value = Cache::get('servbay_memcached_key');
   
       if ($value) {
           return "Memcached 資料: " . $value;
       } else {
           return "Memcached 資料不存在或已過期。";
       }
   });

   訪問 https://servbay-laravel-test.local/memcached-test 進行測試。

Redis 範例

1. 設定 .env

   若未設定，可於 .env 文件填入 Redis 連線資訊：

   CACHE_STORE=redis
   REDIS_HOST=127.0.0.1
   REDIS_PASSWORD=null # ServBay 預設 Redis 無密碼
   REDIS_PORT=6379 # ServBay 預設 Redis 埠號

   注意： 若同時設定 Memcached 與 Redis 作為快取，請確保 .env 中 CACHE_STORE 僅啟用欲測試者（可註解掉另一個）。

2. 使用 Redis

   於路由或控制器使用 Laravel Redis facade 或 Cache facade 存取 Redis：

   於 routes/web.php 新增路由範例：

   use Illuminate\Support\Facades\Redis;
   // 或可使用 Cache facade，前提是 CACHE_STORE=redis
   // use Illuminate\Support\Facades\Cache;
   
   Route::get('/redis-test', function () {
       // 使用 Redis facade
       Redis::set('servbay_redis_key', 'Hello from Redis on ServBay!');
       $value_redis = Redis::get('servbay_redis_key');
   
       // 或使用 Cache facade（若 CACHE_STORE=redis）
       // Cache::put('servbay_redis_key', 'Hello from Redis on ServBay!', 600);
       // $value_cache = Cache::get('servbay_redis_key');
   
       return "Redis 資料: " . $value_redis;
   });

   訪問 https://servbay-laravel-test.local/redis-test 進行測試。

關聯式資料庫範例（MySQL & PostgreSQL）

ServBay 預設已安裝 MySQL 與 PostgreSQL 資料庫伺服器。Laravel 的 Eloquent ORM 能輕鬆連接並操作。

首先，需為專案建立資料庫。可用 ServBay 內建的資料庫管理工具（如 phpMyAdmin、Adminer、pgAdmin 等，可由 ServBay 控制面板進入）或終端機客戶端建立名為 servbay_laravel_app 的資料庫。

接著，利用 Laravel 遷移功能建立資料庫結構。

1. 建立遷移檔

   於專案根目錄執行 Artisan 指令產生新遷移檔：

   php artisan make:migration create_accounts_table --create=accounts

   會於 database/migrations 目錄下新增一個遷移檔。

2. 編輯遷移檔

   開啟新建立的遷移檔（檔名如 YYYY_MM_DD_HHMMSS_create_accounts_table.php），於 up 方法定義 accounts 表格結構：

   <?php
   
   use Illuminate\Database\Migrations\Migration;
   use Illuminate\Database\Schema\Blueprint;
   use Illuminate\Support\Facades\Schema;
   
   return new class extends Migration
   {
       /**
        * 執行遷移
        */
       public function up(): void
       {
           Schema::create('accounts', function (Blueprint $table) {
               $table->id();
               $table->string('name');
               $table->string('email')->unique();
               $table->timestamps(); // 新增 created_at 及 updated_at 欄位
           });
       }
   
       /**
        * 回復遷移
        */
       public function down(): void
       {
           Schema::dropIfExists('accounts');
       }
   };

   儲存檔案。

3. 執行遷移

   於專案根目錄執行 Artisan 指令創建 accounts 表：

   php artisan migrate

   若資料庫設定正確且已建立 servbay_laravel_app 資料庫，此指令將同時建立 Laravel 預設的 users、password_reset_tokens、failed_jobs、cache、cache_locks、jobs、job_batches 等資料表。

MySQL 範例

1. .env 設定 for MySQL

   確認 .env 文件中的資料庫連線設定為 MySQL：

   DB_CONNECTION=mysql
   DB_HOST=127.0.0.1
   DB_PORT=3306 # ServBay 預設 MySQL 埠號
   DB_DATABASE=servbay_laravel_app
   DB_USERNAME=root
   DB_PASSWORD=password # ServBay 預設 MySQL 密碼

2. 寫入範例資料

   於 routes/web.php 新增路由，可將資料寫入 accounts 表：

   use Illuminate\Support\Facades\DB;
   
   Route::get('/mysql-add-account', function () {
       DB::table('accounts')->insert([
           'name' => 'ServBay Demo User',
           'email' => 'demo-user@servbay.test',
           'created_at' => now(),
           'updated_at' => now(),
       ]);
       return 'Account added to MySQL!';
   });

   訪問 https://servbay-laravel-test.local/mysql-add-account 寫入資料。

3. 讀取範例資料

   於 routes/web.php 新增路由，將 accounts 表資料讀出：

   use App\Models\Account; // 若已有建立 Account 模型
   // 或直接使用 DB facade
   
   Route::get('/mysql-accounts', function () {
       // 使用 DB facade
       $accounts = DB::table('accounts')->get();
   
       // 或使用 Eloquent ORM（需有 Account 模型）
       // $accounts = Account::all();
   
       return $accounts;
   });

   訪問 https://servbay-laravel-test.local/mysql-accounts 以查看資料。

PostgreSQL 範例

1. .env 設定 for PostgreSQL

   若欲使用 PostgreSQL，請於 .env 檔案調整設定：

   DB_CONNECTION=pgsql
   DB_HOST=127.0.0.1
   DB_PORT=5432 # ServBay 預設 PostgreSQL 埠號
   DB_DATABASE=servbay_laravel_app
   DB_USERNAME=root # ServBay 預設 PostgreSQL 帳號
   DB_PASSWORD=password # ServBay 預設 PostgreSQL 密碼

   注意： 切換資料庫連線後，可能需再次執行 php artisan migrate:refresh 或 php artisan migrate 用以建立 PostgreSQL 資料表結構。

2. 寫入範例資料（PostgreSQL）

   於 routes/web.php 新增路由，將資料寫入 accounts 表：

   use Illuminate\Support\Facades\DB;
   
   Route::get('/pgsql-add-account', function () {
       DB::table('accounts')->insert([
           'name' => 'ServBay PG Demo User',
           'email' => 'pg-demo-user@servbay.test',
           'created_at' => now(),
           'updated_at' => now(),
       ]);
       return 'Account added to PostgreSQL!';
   });

   訪問 https://servbay-laravel-test.local/pgsql-add-account 寫入資料。

3. 讀取範例資料（PostgreSQL）

   於 routes/web.php 新增路由，以查詢 accounts 表資料：

   use Illuminate\Support\Facades\DB;
   
   Route::get('/pgsql-accounts', function () {
       $accounts = DB::table('accounts')->get();
       return $accounts;
   });

   訪問 https://servbay-laravel-test.local/pgsql-accounts 以查看資料。

總結

借助 ServBay，您可快速佈建本地開發環境，來建立並運行 Laravel 專案。ServBay 預載 PHP、Composer、Caddy 網頁伺服器及多種資料庫、快取服務，大幅減簡環境設置流程。只需幾個簡單步驟，即可創建新 Laravel 專案、設定網頁伺服器、開始開發，也能便捷整合測試資料庫與快取功能。ServBay 致力提供高效、便利的本地開發體驗。

若於使用過程中遇到任何問題，歡迎查閱 ServBay 官方文件，或加入社群討論取得協助。