在 ServBay 中建立並執行 Laravel 專案

概述

ServBay 是一款功能強大的本機 Web 開發環境，專為 macOS 設計，整合了多種熱門套件，包括 PHP、Node.js、Python、Go、Java、多種資料庫（MySQL、PostgreSQL、MongoDB）、快取服務（Redis、Memcached）以及 Web 伺服器（Caddy、Nginx、Apache）。

本文件將指引您如何在 ServBay 環境中快速建立、配置並執行一個 Laravel 專案。我們將善用 ServBay 內建的 PHP 環境、Composer 套件管理器，以及強大的網站（前稱「主機」）管理功能，使整個流程更加簡單易行。

什麼是 Laravel？

Laravel 是一個廣受歡迎的開源 PHP Web 應用框架，由 Taylor Otwell 開發。它遵循 MVC（Model-View-Controller）架構模式，並提供許多即開即用的方便功能，大幅簡化 Web 開發過程中的常見任務，例如使用者認證、路由、會話管理、快取以及資料庫操作。Laravel 因其優雅的語法、豐富的功能集與強大的社群支持而著稱，是打造現代且易維護 Web 應用的理想選擇。

Laravel 的主要特色與優勢

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

使用 ServBay 開發 Laravel 專案的優勢

ServBay 對於 Laravel 開發者有諸多便利：

• 整合環境： 預先安裝多個 PHP 版本、Composer，以及多種常用資料庫和快取服務，免除繁瑣的手動安裝與設定。
• 易於管理： 透過 ServBay 圖像化介面，能快速切換 PHP 版本、管理網站（網站）設定、啟動／停止服務。
• 預設最佳化 Web 伺服器： ServBay 預設採用 Caddy，並針對 Laravel 等主流 PHP 框架進行最佳化配置，讓 Web 伺服器設定變得更簡單。
• HTTPS 支援： ServBay 會自動為 .local 網域簽發 ServBay User CA 的 SSL 憑證，預設啟用 HTTPS，讓本機開發更安全且更貼近生產環境。

建立 Laravel 專案

ServBay 建議您將所有網站專案統一儲存於 /Applications/ServBay/www 目錄下，以便於結構整齊與集中管理。

1. 確認 Composer 已安裝

   ServBay 安裝時已內建 Composer，無需額外安裝。可透過終端機確認 Composer 狀態：

   composer --version

   若成功顯示版本號，表示 Composer 可正常運作。

2. 建立新的 Laravel 專案

   開啟終端機，切換至 ServBay 推薦的網站目錄，使用 Composer 建立新 Laravel 專案。我們將專案資料夾命名為 servbay-laravel-app：

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

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

3. 進入專案目錄

   請確認您在新建的 Laravel 專案根目錄下：

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

初始設定

1. 產生應用金鑰

   Laravel 需要一組應用金鑰來保護使用者 session 及加密資料。在專案根目錄（/Applications/ServBay/www/servbay-laravel-app）下執行 Artisan 指令產生金鑰：

   php artisan key:generate

   此指令會於 .env 檔案自動產生及設定 APP_KEY。

2. 設定環境變數（.env）

   Laravel 使用 .env 文件管理環境變數，例如資料庫連線、應用程式 URL 等。請於專案根目錄開啟 .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 控制台查閱。

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

透過 ServBay 的網站管理功能，讓您的網域指向 Laravel 專案 public 目錄。

1. 開啟 ServBay 控制台

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

2. 新增網站

   進入控制台的「網站」頁籤。點擊新增（通常是 + 或相關圖示）來建立新網站。

3. 填寫網站資訊

   以下為範例填寫內容：

   • 名稱 (Name)： My First Laravel Dev Site（方便辨識的名稱）
   • 網域 (Domain)： servbay-laravel-test.local（您欲用於瀏覽器的網域）
   • 網站型態 (Site Type)： PHP
   • PHP 版本 (PHP Version)： 根據您的 Laravel 版本選擇，例如 8.3
   • 網站根目錄 (Site Root)： /Applications/ServBay/www/servbay-laravel-app/public（重點： 必須指向 Laravel 專案底下的 public 子目錄）

   更多操作細節請參考 ServBay 官方新增第一個網站（請查閱英文版說明）。

4. 儲存並套用更改

   儲存網站設定後，ServBay 會自動重載 Web 伺服器設定（預設為 Caddy）。如需重啟 Web 伺服器請依提示操作。

驗證基礎訪問

此時，您應可透過設定的網域來存取 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 具備強大的資料庫抽象層與 Eloquent ORM，能輕鬆連接各種資料庫。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 快取 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

   於路由或控制器操作 Redis facade 或 Cache facade：

   在 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 產生新的 migration 檔案。

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
   {
       /**
        * Run the migrations.
        */
       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 欄位
           });
       }
   
       /**
        * Reverse the migrations.
        */
       public function down(): void
       {
           Schema::dropIfExists('accounts');
       }
   };

   儲存檔案。

3. 執行遷移

   於專案根目錄執行宣告遷移，建立 accounts 表：

   php artisan migrate

   若資料庫設定正確且 servbay_laravel_app 資料庫已建立，此指令會建立 accounts 表及 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
       // $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，您可於 macOS 輕鬆打造本機開發環境以建立並運行 Laravel 專案。ServBay 內建 PHP、Composer、Caddy Web 伺服器，以及各式資料庫與快取服務，大幅簡化環境組建流程。只需幾步即可新建 Laravel 專案、完成 Web 伺服器設定並開始開發，同時便捷整合與測試資料庫和快取功能。ServBay 致力於為開發者提供高效且便利的本地開發體驗。

如在操作途中遇到任何困難，歡迎查閱 ServBay 官方文件或向社群尋求協助。