Voyager 的使用及二次開發

skyArony發表於2018-10-23

主要整理了我對 Laravel 的後臺開源專案 Voyager 的一點經驗。

一、簡介

做一個 Web 系統,後臺是必須的,後臺大致可以分為兩類:

後端導向

這裡以 Laravel 為例,這類後臺的特點是可以直接透過關聯了資料表的 Model 來輕易的建立 CURD(增刪改查),這樣可以省去大量控制器 CURD 的程式碼。後端具有更強的主導性。

前端導向

這種前端具有更強的主導性。

本文重點

在此主要介紹的是 Voyager,如上所述,Voyager 可以輕易的根據 Model 自動建立 BREAD(即 CURD),這樣你可以省去寫控制器及方法的程式碼,並且 Voyager 支援二次開發,具有足夠高的定製性。

至於 Voyager 的缺點,主要還是前端是用的 Blade 寫的,雖然 Blade 是 Laravel 自帶提供的前端模板引擎,但是對於飛速發展的前端框架來說,Vue 是個更好的解決方案。

本文主要是介紹我自己在使用 Voyager 中遇到的一些問題和解決方案,和一些二次開發時的經驗。

二、安裝

1. 下載包

先把包下載過來

composer require tcg/voyager

2. 設定語言環境

設定環境為中文

config\app.php

'locale' => 'zh_CN',

3. 執行安裝

# 正常安裝
php artisan voyager:install

# 假資料安裝
php artisan voyager:install --with-dummy

# 把一個使用者設定為可登陸的管理員
php artisan voyager:admin your@email.com

# 新建一個可登陸的管理員
php artisan voyager:admin your@email.com --create

假資料安裝下的賬號和密碼:

email: admin@admin.com
password: password

三、二次開發

Voyager 的二次開發主要有三種形式:覆寫檢視,覆寫路由,繼承控制器。

1. 覆寫檢視

檢視層的二次開發可以參照官方文件,大致思路就是在 resource 下建立一個和 vendor 中包目錄下一樣的目錄結構,複製你想要重寫的檢視內容檔案,然後以此為基礎進行修改即可。

包目錄下的

image-20180821165431966.pngfile

自己的開發目錄

image-20180821165537551.pngfile

方式一:修改 blade

這一層只需要按照 blade 模板引擎的語法對檔案進行修改即可。

同時如果有這樣一個需求:對於所有 post,我只想讓 post 的建立者看到,即每個管理員只能看到自己建立的 post。但是在 Voyager 預設建立好 BREAD 之後,Voyager 中的許可權管理只能做到使用者要麼全看到,要麼全看不到。

這個時候,就可以修改 blade,在其中加一個過濾操作即可解決問題。

但是值得注意的是:這樣並不優雅,因為更好的邏輯應該是在查資料庫時就只取所需的資料,而不是這樣全取出來再過濾。但是這種方法比較簡單,改動的程式碼量也小。所以見仁見智啦。

方式二:Vue 單檔案元件

這種方式是透過 Vue 寫單檔案元件,然後直接像 HTML 標籤一樣插入 Blade 中,然後其中的內容就隨便你 Vue 怎麼寫了。

/resources/assets/js/app.js

// 單檔案元件
Vue.component('worlduc-video', require('./components/Index-Video.vue'));

/resources/views/video.blade.php

<div id="app" style="width:100%;height:100%;">
  <worlduc-video></worlduc-video>
</div>

額外

  • 若是想要新增子頁面,並且是帶那種左側 admin 導航的子頁,在新建的 blade 檔案中新增如下即可:

    @extends('voyager::master')
  • 若是新增的子頁面想要放在登陸保護後,則新增其路由至 admin.user 中介軟體後

    // 自定義的頁要加到認證後的,就加到這個裡面
    Route::group(['middleware' => 'admin.user'], function () {
      // 課程資訊頁
      Route::view('/admin/teams/member/{teamId}', 'addMember');
      // 首頁
      Route::view('/', 'index');
    });
  • 若想要一個使用者可以登入的 Voyager 並看到其中的內容,必須給予 admin 的 browse 許可權,否則無法登陸成功。

2. 覆寫路由

這也是官方文件中明確支援的一種方式,能夠將本來 Voyager 定義的一些路由,比如登陸,用自己的控制器和對應方法去替代。

Route::get('/', function () {
    return view('welcome');
});

Route::group(['prefix' => 'admin'], function () {
    // Voyager 原本的路由
    Voyager::routes();  
    // 覆蓋了原先的登入,新增了自定義的本身認證
    Route::post('login', 'LoginController@postLogin')->name('voyager.login');
    // 覆蓋原先的登出
    Route::post('logout', 'LoginController@postLogout')->name('voyager.logout');
});

3. 覆寫控制器

控制器的重寫,官方文件也寫的足夠詳細了,首先在 config/voyager.php 中如下定義:

'controllers' => [
  'namespace' => 'App\\Http\\Controllers\\Voyager',
],

然後執行 php artisan voyager:controllers,這樣控制器就會被建立到你的控制器目錄,而這些控制器是繼承自包中原先的控制器,如果你不覆寫,還是能正常工作,如果你想進行自己的控制,那麼就可以直接重寫對應的方法。

4. 自定義控制器

除了上面覆寫控制器的方法,你還可以看到在建立 BREAD 時,可以直接選擇控制器,而這個控制器完全可以由你自己寫,但是我並沒有實踐,BREAD 對應的增刪改查操作應該對應的是控制器什麼方法名,有興趣的同學可以去看一下原始碼。

四、其他

除了上面的二次開發外,還有其他一些使用的的經驗和實踐,整理如下:

1. 部分欄位自定義 create

現在有一個需求,我需要在一個表中插入一條資料,這條資料由三個欄位組成,分別為 A、B、C。其中 B、C 我讓使用者自己輸入,但是 A 我想要系統讀取使用者的資訊來自動填入(比如讀取使用者的 ID,用來標識這條資料的建立者)。想想該怎麼做呢?

一般來說,我們可以先考慮一下資料儲存過程中需要用到的兩個東西:Controller 和 Model,其中 Model 可以試著一個 attributes 屬性來設定欄位的預設值,但是這個屬性要求都為靜態值,是無法使用變數的。Controller 的話可以重寫 Controller,修該邏輯即可,但是重寫 Controller 其實程式碼量還是比較大的。有沒有更加簡單的辦法呢?當然是有的!

方法一

在 bread 中設定欄位為 hidden 並在可選細項中設定一個預設值,然後在模型中配置一個修改器,設定成你想要的值即可。

image-20180822145611512.pngfile

public function setCreaterIdAttribute($value)
{
  $this->attributes['creater_id'] = Cookie::get('user_id');
}

為什麼要配置這個預設值呢?因為模型中的修改器只有在這個欄位被設定了值才能成功觸發。

方法二

不在可選細項配置預設值,只新增修改器即可:

// 讓你想要設定的值在其他修改器中順便被新增即可
public function setTeamNameAttribute($value)
{
  $this->attributes['team_name'] = $value;
  $this->attributes['creater_id'] = Cookie::get('user_id');
}

方法三

配置一個關係,按照圖中勾選即可(其實 creater_id 那隻需勾選『新增』便可達到效果,其他不影響)

image-20181023151613114.pngfile

public function setCreaterIdAttribute($value)
{
  $this->attributes['creater_id'] = Cookie::get('id');
}

2. datetimepicker 無法顯示的 bug

覆寫 master.blade.php,新增如下:

<!-- datatimepicker -->
<link rel="stylesheet" href="/css/bootstrap-datetimepicker.min.css">
// 這個 css 新增到上方合適位置
// css 自行下載 https://github.com/Eonasdan/bootstrap-datetimepicker/releases

<script type="text/javascript" src="{{ voyager_asset('js/app.js') }}"></script> 
// 這一行是本來有的

<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/moment.js/2.19.1/moment-with-locales.js"></script>
<script>
    moment.locale("zh-cn");
</script>
// 上面是設定語言,不過語言設定為中文會格式化報錯

<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/bootstrap-datetimepicker/4.17.47/js/bootstrap-datetimepicker.min.js"></script>

出現 bug 的原因是其引用的一個 js 外掛有 bug,指定一個沒有 bug 的版本即可。

3. 表單欄位可為空如何控制

在進行新建或編輯時,你會發現有些欄位是必填的,而有些欄位是非必填,但是並沒有看到有一個控制的選項。其實這個是根據資料表的欄位是否可為 NULL 控制的。但其實這個設定存在不少 bug:

  1. 如果輸入空白符,前端會認為你填寫了資料而放行,但是後端會報錯
  2. 對於下拉選擇,如果你選擇的是 None ,並提交而這個欄位又設定未非空的話也會報錯。

所以我建議還是覆寫 edit-add 這個 blade,新增 js 進行控制。

4. Voyager 配置完畢後如何匯出設定

Voyager 的後臺一些設定是儲存在資料庫中的,建議使用 orangehill/iseed 這個外掛來將資料庫的資料轉換為 seeder,然後新增 Git 進行管理即可。

五、總結

Voyager 是一個非常不錯的後臺模板,功能齊全,顏值高,能夠快速的搭建一個好用的後臺,但是其中存在的小 bug 還是比較多,如果是作為開發者內部團隊簡單使用遠遠足夠,但是若作為一個開放給外部使用者使用,還需針對各個小 bug 進行修復,因為只有針對角色的許可權分配,不能根據資源的建立者分配更細的許可權,所以還需額外部署對應的邏輯。

本作品採用《CC 協議》,轉載必須註明作者和本文連結

相關文章