## 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內處理要做的事情