diff --git a/README.md b/README.md new file mode 100644 index 0000000..6b4a321 --- /dev/null +++ b/README.md @@ -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內處理要做的事情