README
This commit is contained in:
parent
d7b097d061
commit
89a451b825
403
README.md
Normal file
403
README.md
Normal file
@ -0,0 +1,403 @@
|
|||||||
|
## 1. 系統需求
|
||||||
|
- PHP 7.3
|
||||||
|
- PHP Extensions
|
||||||
|
- BCMath
|
||||||
|
- Ctype
|
||||||
|
- JSON
|
||||||
|
- Mbstring
|
||||||
|
- OpenSSL
|
||||||
|
- PDO PHP
|
||||||
|
- Tokenizer
|
||||||
|
- XML,
|
||||||
|
|
||||||
|
## 2. IDE需求
|
||||||
|
- 支援Editor Config
|
||||||
|
|
||||||
|
## 3. 額外Composer套件
|
||||||
|
#### 3.1 Dev
|
||||||
|
- **[barryvdh/laravel-ide-helper](https://github.com/barryvdh/laravel-ide-helper)**
|
||||||
|
> 會自動產生Laravel相關的phpDocs, 使IDE對Laravel的支援度提高
|
||||||
|
- **[barryvdh/laravel-debugbar](https://github.com/barryvdh/laravel-debugbar)**
|
||||||
|
> 輔助偵錯用的小工具
|
||||||
|
#### 3.2 Online
|
||||||
|
- **[spatie/laravel-permission](https://github.com/spatie/laravel-permission)**
|
||||||
|
> 權限管理(Role、Permission)
|
||||||
|
- **[predis/predis](https://github.com/nrk/predis)**
|
||||||
|
> Redis連線套件
|
||||||
|
|
||||||
|
|
||||||
|
## 4. 安裝注意事項(網站資料庫重置後請從4.2開始)
|
||||||
|
|
||||||
|
#### 4.1 Laravel安裝步驟
|
||||||
|
1. 安裝Node Packages
|
||||||
|
> npm i
|
||||||
|
2. 複製.env.example 至 .env
|
||||||
|
> cp .env.example .env
|
||||||
|
3. 產生APP Key
|
||||||
|
> php artisan key:generate
|
||||||
|
4. 在.env填好資料庫資訊
|
||||||
|
|
||||||
|
#### 4.2 網站安裝步驟
|
||||||
|
1. 安裝資料表，建立預設資料
|
||||||
|
|
||||||
|
> php artisan migrate --seed
|
||||||
|
|
||||||
|
2. 建立管理員權限帳號
|
||||||
|
|
||||||
|
> php artisan account:create-admin {email} {password}
|
||||||
|
|
||||||
|
3. 建立編輯者權限帳號
|
||||||
|
|
||||||
|
> php artisan account:create-editor {email} {password}
|
||||||
|
|
||||||
|
4. 訪問後台，預設路徑為*/adm*
|
||||||
|
|
||||||
|
## 5. Debugbar使用說明
|
||||||
|
使用套件為 [barryvdh/laravel-debugbar](https://github.com/barryvdh/laravel-debugbar)*(正式環境請勿開啟)*
|
||||||
|
|
||||||
|
#### 5.1 載入Debugbar
|
||||||
|
將 `.env` 檔案內的 `APP_DEBUG` 設為 `true`
|
||||||
|
|
||||||
|
#### 5.2 啟用與停用
|
||||||
|
啟用: 在網址後傳入參數: `__debugbar` , 值為 `enable`
|
||||||
|
|
||||||
|
例: `https://example.com/?__debugbar=enable`
|
||||||
|
|
||||||
|
停用: 在網址後傳入參數: `__debugbar` , 值為 `enable` 之外的任意值
|
||||||
|
|
||||||
|
例: `https://example.com/?__debugbar=disable`
|
||||||
|
|
||||||
|
## 6. 設定語系
|
||||||
|
|
||||||
|
新訪問的使用者會根據瀏覽器語言自動設定語系
|
||||||
|
|
||||||
|
如不支援，則設定成設定檔`app.fallback_locale`所定義的語系
|
||||||
|
|
||||||
|
#### 6.1 支援的語系
|
||||||
|
所有支援的語系資訊在 `config/languages.php`
|
||||||
|
|
||||||
|
#### 6.2 切換語系
|
||||||
|
|
||||||
|
網址傳入參數: `locale`
|
||||||
|
|
||||||
|
例: `https://example.com/?locale=ja`
|
||||||
|
|
||||||
|
## 7. 資料夾檔案與類別
|
||||||
|
|
||||||
|
#### 7.1 程式類別
|
||||||
|
- **Controllers**
|
||||||
|
|
||||||
|
App\Http\Controllers\Admin
|
||||||
|
|
||||||
|
> 後台
|
||||||
|
|
||||||
|
App\Http\Controllers\Admin\Menu
|
||||||
|
|
||||||
|
> 後台選單
|
||||||
|
- **App\Presenters**
|
||||||
|
|
||||||
|
> 用來輔助產生Html或文字的類別
|
||||||
|
- **App\Repositories**
|
||||||
|
|
||||||
|
> 用來進行複雜的資料庫存取，可繼承BaseRepository
|
||||||
|
- **App\Service**
|
||||||
|
|
||||||
|
> 其他的輔助類別
|
||||||
|
|
||||||
|
#### 7.2 Config(設定檔)
|
||||||
|
- config/admin.php
|
||||||
|
> 後台相關設定檔
|
||||||
|
- config/data-resets.php
|
||||||
|
> 網站的種子資料(須在網站安裝時存入的資料，透過Seeder安裝)
|
||||||
|
- config/languages.php
|
||||||
|
> 網站所支援的語系
|
||||||
|
|
||||||
|
#### 7.3 圖片檔案
|
||||||
|
- storage/app/public/uploads/app
|
||||||
|
> 媒體庫上傳的檔案
|
||||||
|
## 8.自訂Artisan指令列表
|
||||||
|
|
||||||
|
Artisan指令參數格式：
|
||||||
|
|
||||||
|
- `{xxx}` 必填，輸入 xxx
|
||||||
|
- `{xxx?}` 選填，輸入 xxx
|
||||||
|
- `{--xxx}` 可選選項，輸入 --xxx
|
||||||
|
- `{--xxx=}` 可選選項，輸入 --xxx=值，不帶的話都是隨機產生
|
||||||
|
|
||||||
|
輸入範例，指令media:create {amount?} {--app} {--user=} {--width=} {--height=} {--category=}
|
||||||
|
|
||||||
|
```bash
|
||||||
|
media:create 1
|
||||||
|
media:create --app --user=1 --width=1080
|
||||||
|
media:create --user=1 --category=12
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
#### 8.1 帳號
|
||||||
|
- 建立管理員帳號
|
||||||
|
|
||||||
|
```bash
|
||||||
|
account:create-admin {Email} {密碼}
|
||||||
|
```
|
||||||
|
|
||||||
|
- 產生編輯帳號
|
||||||
|
|
||||||
|
```bash
|
||||||
|
account:create-editor{Email} {密碼}
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
#### 8.2 建立檔案
|
||||||
|
- 建立一個Repository類別檔案
|
||||||
|
|
||||||
|
```bash
|
||||||
|
make:repository {類別名稱: xxxRepository}
|
||||||
|
```
|
||||||
|
|
||||||
|
- 建立一個後台選單Controller(MenuItemController)檔案
|
||||||
|
|
||||||
|
> 主項目
|
||||||
|
|
||||||
|
```bash
|
||||||
|
make:menu-item-controller ParentMenuItemController
|
||||||
|
```
|
||||||
|
|
||||||
|
> 子項目
|
||||||
|
|
||||||
|
```bash
|
||||||
|
make:menu-item-controller Parent/Children/ChildrenMenuItemController
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
#### 8.3 媒體庫(參考9.)
|
||||||
|
- 產生媒體庫圖片
|
||||||
|
|
||||||
|
```bash
|
||||||
|
media:generate {數量?}預設1 {--user=}使用者id {--width=}寬度 {--height=}高度 {--category=}媒體庫分類id
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
#### 8.5 媒體庫分類
|
||||||
|
- 產生媒體庫分類
|
||||||
|
|
||||||
|
```bash
|
||||||
|
media-category:generate {數量?}預設1 {--app}是否為網站媒體庫分類 {--user=}使用者id
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
#### 8.6 Permission
|
||||||
|
- 重新安裝所有角色與權限，當data-presets檔內有修改權限的話可用這個指令重新安裝，會將原本有的重新對應權限給角色
|
||||||
|
|
||||||
|
```bash
|
||||||
|
permission:reinstall
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
## 9. 媒體庫
|
||||||
|
|
||||||
|
後台使用者共用媒體庫圖片
|
||||||
|
|
||||||
|
## 10. 後台選單架構
|
||||||
|
|
||||||
|
#### 10.1 建立選單的流程
|
||||||
|
1. 於`app/Http/Controllers/Admin/Menu/` 下依照原有結構去建立資料夾及Controller，一個Menu項目建立一個Controller
|
||||||
|
2. 每個Controller皆繼承`App\Http\Controllers\Admin\Menu\BaseMenuItemController`
|
||||||
|
3. Controller內填入
|
||||||
|
- `name` (選單名稱，可支援翻譯路徑表示法)
|
||||||
|
- `slug` (選單項目唯一名稱，不可重複)
|
||||||
|
- `permissions` (選填，設定後台選單項目的權限，須有權限才能看得到項目及進去頁面，如果有子母選單，則要看到子選單，必須要有母選單的權限才行，子選單也可獨立設定權限，這樣就兩個權限都要符合才行)
|
||||||
|
- `iconClasses` (選填，選單項目圖示的class, 可為陣列或字串)
|
||||||
|
- `badge` (選填，Bootstrap的badge)
|
||||||
|
- `type` (badge類型) secondary、dange、success等等
|
||||||
|
- `label` (badge的文字內容)
|
||||||
|
- `isPill` (是否為橢圓形)
|
||||||
|
4. 繼承"handle" method，處理進去選單項目時的動作，如果是母選單項目可不設，因為母選單點下去就只是展開子選單而已，不會有動作
|
||||||
|
5. 在`config/admin.php`的`menuItems`內填入新增的Controller
|
||||||
|
> type支援item、title(文字)、divider(分隔線)，參考`App\Presenters\Admin\MainMenuItemPresenter`
|
||||||
|
|
||||||
|
#### 10.2 相關類別
|
||||||
|
- App\Services\Admin\MainMenuItemService
|
||||||
|
|
||||||
|
`Singleton Instance`，建構及儲存Menu項目的資料
|
||||||
|
|
||||||
|
- App\Provider\AdminMenuServiceProvider
|
||||||
|
|
||||||
|
讀取`config/admin.php`中的`menuItems`設定，建立route與儲存到MainMenuItemService
|
||||||
|
|
||||||
|
- App\Presenters\Admin\MainMenuItemPresenter
|
||||||
|
|
||||||
|
根據`MainMenuItemService`內儲存的Menu資料，建構Html
|
||||||
|
|
||||||
|
- App\Http\Middleware\CheckAdminMenuPagePermission
|
||||||
|
|
||||||
|
檢查Admin選單項目的route權限
|
||||||
|
|
||||||
|
## 11. 後台"設定"頁面及程式架構
|
||||||
|
|
||||||
|
#### 11.1 新增一個設定子頁面的流程
|
||||||
|
1. 於`config/app.php`的`options`內設定頁面的slug及頁面下面有哪些選項
|
||||||
|
|
||||||
|
```php
|
||||||
|
'page_slug' => [ // 頁面slug
|
||||||
|
'permission': 'admin manage options page_slug' // OptionsController的gate
|
||||||
|
'option_1' => [ // 選項slug，實際儲存在資料庫中的key
|
||||||
|
'type' => 'checkbox', // 選填，預設值為input text，選項的類型，支援的類型參考`App\Presenters\Admin\OptionFormFieldsPresenter`
|
||||||
|
'label(選項的名稱)' => 'abc', // 翻譯的字串，定義在lang/form.php內的labels
|
||||||
|
'validator' => 'required|min:8', // 選填，選項更新時的後端驗證規則，此為Laravel Validator的規則
|
||||||
|
'required' => true, // 選填，選項輸入欄位的html中的required屬性,
|
||||||
|
]
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
2. 建立設定頁面的`選單項目Controller`，在`App\Http\Controller\Admin\Menu\Options\Children`，並加入至`config`
|
||||||
|
|
||||||
|
#### 11.2 相關類別
|
||||||
|
- App\Providers\OptionRouteServiceProvider
|
||||||
|
|
||||||
|
> 建立儲存選項時的Route
|
||||||
|
|
||||||
|
- App\Http\Controllers\Admin\OptionsController
|
||||||
|
|
||||||
|
> 儲存選項時的 Route Controller
|
||||||
|
|
||||||
|
## 12. MiddlWare
|
||||||
|
|
||||||
|
- App\Http\Middleware\AdminAreaGuard
|
||||||
|
|
||||||
|
> 判斷後台權限
|
||||||
|
|
||||||
|
- App\Http\Middlwware\CheckAdminMenuPagePermission
|
||||||
|
|
||||||
|
> 檢查Admin選單項目的route權限
|
||||||
|
|
||||||
|
- App\Http\Middleware\DebugbarEnabler
|
||||||
|
|
||||||
|
> 開啟或關閉debugbar並處理
|
||||||
|
|
||||||
|
- App\Http\Middlware\SetAppLanguage
|
||||||
|
|
||||||
|
> 設定網站語系
|
||||||
|
|
||||||
|
- App\Http\Middleware\SetSiteStates
|
||||||
|
|
||||||
|
> 設定SiteStateService中的資料
|
||||||
|
|
||||||
|
## 13. Service
|
||||||
|
|
||||||
|
- App\Services\AppJsObjectService
|
||||||
|
|
||||||
|
> 提供資料給前端js使用
|
||||||
|
|
||||||
|
- App\Services\MediaFileFactoryService
|
||||||
|
|
||||||
|
> 產生假的媒體檔案
|
||||||
|
|
||||||
|
- App\Services\SiteStateService
|
||||||
|
|
||||||
|
> 紀錄全域的網站狀態
|
||||||
|
|
||||||
|
## 14. Service Provider
|
||||||
|
|
||||||
|
- App\Providers\AdminMenuServiceProvider
|
||||||
|
|
||||||
|
> 從Config檔案建立Menu Item，並註冊相關Route
|
||||||
|
|
||||||
|
- App\Providers\OptionRouteServiceProvider
|
||||||
|
|
||||||
|
> 建立後台設定頁面的route
|
||||||
|
|
||||||
|
- App\Providers\SingletonServiceProvider
|
||||||
|
|
||||||
|
> 初始化所有singleton class 的 instance
|
||||||
|
|
||||||
|
## 15. 資料表 & Model
|
||||||
|
|
||||||
|
- **disks** **Disk**
|
||||||
|
> 本機儲存位置，定義在config/filesystems.php
|
||||||
|
- **media_categories** **MediaCategory**
|
||||||
|
> 媒體分類
|
||||||
|
- **media_files** **MediaFile**
|
||||||
|
> 媒體檔案
|
||||||
|
- **media_sources** **MediaSource**
|
||||||
|
> 外部媒體來源
|
||||||
|
- **model_translations** **ModelTranslation**
|
||||||
|
> Model的翻譯
|
||||||
|
- **options** **Option**
|
||||||
|
> 設定選項
|
||||||
|
- **users** **User**
|
||||||
|
> 使用者
|
||||||
|
- **password_resets**
|
||||||
|
> 重設密碼的tokens
|
||||||
|
- **model_has_permissions**
|
||||||
|
> model的權限，給spatie/laravel-permission套件使用的table
|
||||||
|
- **model_has_roles**
|
||||||
|
> model的角色，給spatie/laravel-permission套件使用的table
|
||||||
|
- **permissions**
|
||||||
|
> 權限，給spatie/laravel-permission套件使用的table
|
||||||
|
- **roles**
|
||||||
|
> 角色，給spatie/laravel-permission套件使用的table
|
||||||
|
- **role_has_permissions**
|
||||||
|
> 角色的能力，給spatie/laravel-permission套件使用的table
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## 16. Model
|
||||||
|
|
||||||
|
- App\TranslatableModel
|
||||||
|
|
||||||
|
> 被繼承用，需要翻譯的Model，繼承的Model要設定需要被翻譯的屬性
|
||||||
|
|
||||||
|
- App\Post
|
||||||
|
|
||||||
|
> 被繼承用，為各文章類型的Parent Model
|
||||||
|
|
||||||
|
## 17. 文章類型
|
||||||
|
|
||||||
|
建立文章類型的流程
|
||||||
|
|
||||||
|
1. 建立Model，繼承App\Post
|
||||||
|
2. 建立migration，基本屬性可使用*App\Traits\PostBlueprintGettable:processSchema()*，傳入Blueprint
|
||||||
|
3. 加入文章類型至`/config/postTypes.php`
|
||||||
|
4. 加入選單項目(參考現有)，後台管理功能和模板會自動共用
|
||||||
|
|
||||||
|
## 18. Event及Listener
|
||||||
|
用來在Model產生特定資料庫操作動作(增刪修)後做特定的事情
|
||||||
|
|
||||||
|
例如
|
||||||
|
|
||||||
|
- Media刪除後須跟著刪除檔案
|
||||||
|
- 可翻譯的Model被刪除後須跟著刪除翻譯資料
|
||||||
|
|
||||||
|
#### 17.1 類別
|
||||||
|
- App\Event
|
||||||
|
|
||||||
|
> Model做特定動作之後會發出的Event
|
||||||
|
|
||||||
|
- App\Listeners
|
||||||
|
|
||||||
|
> 發出Event之後要做的動作
|
||||||
|
|
||||||
|
- App\Observers
|
||||||
|
|
||||||
|
> 觀察Model並在Model做特定動作之後要做的動作
|
||||||
|
|
||||||
|
#### 17.2 使用方法
|
||||||
|
|
||||||
|
**Event**
|
||||||
|
1. 新增一個Event
|
||||||
|
2. 新增一個Listener
|
||||||
|
3. 在Model內註冊event
|
||||||
|
4. 在EventServiceProvider內註冊Event對應的Listener
|
||||||
|
5. 在Event內設定Event發生的主體Model
|
||||||
|
6. 在Listener內處理要做的事情
|
||||||
|
|
||||||
|
**Observer**
|
||||||
|
1. 新增一個Oberserver
|
||||||
|
2. 在Model內註冊Observer
|
||||||
|
3. 在Observer內處理要做的事情
|
||||||
Loading…
Reference in New Issue
Block a user