├── .gitignore ├── .vuepress └── config.js ├── documentation.md ├── deploy.sh ├── README.md ├── installation.md ├── presenters.md ├── shortcode.md ├── themes.md ├── trusty.md ├── widget.md ├── generators.md ├── menus.md └── modules.md /.gitignore: -------------------------------------------------------------------------------- 1 | .vuepress/dist -------------------------------------------------------------------------------- /.vuepress/config.js: -------------------------------------------------------------------------------- 1 | module.exports = { 2 | title: "Pingpong Labs", 3 | description: "An open-sourced Laravel Packages", 4 | base: "/docs/" 5 | }; 6 | -------------------------------------------------------------------------------- /documentation.md: -------------------------------------------------------------------------------- 1 | - [Installation](/docs/2.1/installation) 2 | - [Modules](/docs/2.1/modules) 3 | - [Menus](/docs/2.1/menus) 4 | - [Widget](/docs/2.1/widget) 5 | - [Generators](/docs/2.1/generators) 6 | - [Presenters](/docs/2.1/presenters) 7 | - [Trusty](/docs/2.1/trusty) 8 | - [Themes](/docs/2.1/themes) 9 | - [Shortcode](/docs/2.1/shortcode) -------------------------------------------------------------------------------- /deploy.sh: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env sh 2 | 3 | # abort on errors 4 | set -e 5 | 6 | # build 7 | vuepress build 8 | 9 | # navigate into the build output directory 10 | cd .vuepress/dist 11 | 12 | # if you are deploying to a custom domain 13 | # echo 'www.example.com' > CNAME 14 | 15 | git init 16 | git add -A 17 | git commit -m 'deploy' 18 | 19 | # if you are deploying to https://.github.io 20 | # git push -f git@github.com:/.github.io.git master 21 | 22 | # if you are deploying to https://.github.io/ 23 | git push -f git@github.com:pingpong-labs/docs.git master:gh-pages 24 | 25 | cd - -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: An open-sourced Laravel Packages 3 | --- 4 | 5 | # Introduction 6 | 7 | Pingpong Sky is a PHP component made specifically for Laravel. Pingpong Sky includes some ready-made components such as Modules, Menus and Widgets. 8 | 9 | # Features 10 | 11 | - [Menus](./menus.md) 12 | - [Modules](./modules.md) 13 | - [Widget](./widget.md) 14 | - [Shortcode](./shortcode.md) 15 | - [Presenters](./presenters.md) 16 | - [Themes](./themes.md) 17 | - [Trusty](./trusty.md) 18 | - [Generators](./generators.md) 19 | 20 | # License 21 | 22 | This package is open-sourced software licensed under [The BSD 3-Clause License](http://opensource.org/licenses/BSD-3-Clause) 23 | -------------------------------------------------------------------------------- /installation.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Installation 3 | --- 4 | 5 | # Installation 6 | 7 | [![Build Status](https://travis-ci.org/pingpong-labs/sky.svg)](https://travis-ci.org/pingpong-labs/sky) 8 | [![Latest Stable Version](https://poser.pugx.org/pingpong/sky/v/stable.svg)](https://packagist.org/packages/pingpong/sky) [![Total Downloads](https://poser.pugx.org/pingpong/sky/downloads.svg)](https://packagist.org/packages/pingpong/sky) [![Latest Unstable Version](https://poser.pugx.org/pingpong/sky/v/unstable.svg)](https://packagist.org/packages/pingpong/sky) [![License](https://poser.pugx.org/pingpong/sky/license.svg)](https://packagist.org/packages/pingpong/sky) 9 | 10 | ### Version Compability 11 | 12 | | Laravel | Pingpong Sky | PHP | 13 | | :------ | :----------- | :----- | 14 | | 4.\* | 1.\* | >= 5.4 | 15 | | 5.0.\* | 2.0.\* | >= 5.4 | 16 | | 5.1.\* | 2.1.\* | >= 5.4 | 17 | 18 | ### Quick Installation Via Composer 19 | 20 | ``` 21 | composer require "pingpong/sky:~2.1" 22 | ``` 23 | -------------------------------------------------------------------------------- /presenters.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Laravel 5 View Presenter 3 | --- 4 | 5 | # Laravel 5 View Presenter 6 | 7 | - [Installation](#installation) 8 | - [Usage](#usage) 9 | 10 | 11 | 12 | ### Installation 13 | 14 | Open your composer.json file, and add the new required package. 15 | "pingpong/presenters": "~2.1" 16 | 17 | Next, open a terminal and run. 18 | 19 | composer update 20 | 21 | Done. 22 | 23 | 24 | 25 | ### Usage 26 | 27 | First, create your own presenter and make sure that class is extends to `Pingpong\Presenters\Presenter` class. Like this. 28 | 29 | ```php 30 | resource->email, $this->resource->email, $attributes); 39 | } 40 | } 41 | ?> 42 | ``` 43 | 44 | Make sure your model/eloquent to extends `Pingpong\Presenters\Model` and set the presenter property to that model/eloquent. 45 | 46 | ```php 47 | 56 | ``` 57 | 58 | That's it! You're done. Now, within your view, you can do: 59 | 60 | ```php 61 |

Your email is {{ $user->present()->email }}

62 | ``` 63 | 64 | Or, call the presenter as method. 65 | 66 | ```php 67 |

Your email is {{ $user->present()->email(['width' => 140]) }}

68 | ``` 69 | -------------------------------------------------------------------------------- /shortcode.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Laravel 5 Shortcode 3 | --- 4 | 5 | # Laravel 5 Shortcode 6 | 7 | - [Installation](#installation) 8 | - [Registering Shorcode](#registering-shortcode) 9 | - [Compiling Shorcode](#compiling-shortcode) 10 | - [Unregistering Shorcode](#unregistering-shortcode) 11 | - [Destroying All Shorcodes](#destroying-all-shortcode) 12 | 13 | 14 | 15 | ## Installation 16 | 17 | Open your composer.json file, and add the new required package. 18 | 19 | ```json 20 | "pingpong/shortcode": "~2.1" 21 | ``` 22 | 23 | Next, open a terminal and run. 24 | 25 | ``` 26 | composer update 27 | ``` 28 | 29 | After the composer updated. Add new service provider in `config/app.php`. 30 | 31 | ```php 32 | 'Pingpong\Shortcode\ShortcodeServiceProvider' 33 | ``` 34 | 35 | Add new Facade alias. 36 | 37 | ```php 38 | 'Shortcode' => 'Pingpong\Shortcode\ShortcodeFacade', 39 | ``` 40 | 41 | Done. 42 | 43 | 44 | 45 | ## Registering Shorcode 46 | 47 | Using closure: 48 | 49 | ```php 50 | Shortcode::register('a', function($attr, $content = null, $name = null) 51 | { 52 | $text = Shortcode::compile($content); 53 | return ''. $text .''; 54 | }); 55 | ``` 56 | 57 | Using class name. 58 | 59 | ```php 60 | class DivShortcode 61 | { 62 | public function register($attr, $content = null, $name = null) 63 | { 64 | $text = Shortcode::compile($content); 65 | return ''. $text .''; 66 | } 67 | } 68 | 69 | Shortcode::register('div', 'DivShortcode'); 70 | ``` 71 | 72 | Using class name with the specified method. 73 | 74 | ```php 75 | class HTMLShortcode 76 | { 77 | public function img($attr, $content = null, $name = null) 78 | { 79 | $src = array_get($attr, 'src'); 80 | $text = Shortcode::compile($content); 81 | return ''; 82 | } 83 | } 84 | 85 | 86 | Shortcode::register('img', 'HTMLShortcode@img'); 87 | ``` 88 | 89 | Using callback array. 90 | 91 | ```php 92 | class SpanShortcode 93 | { 94 | 95 | public function div($attr, $content = null, $name = null) 96 | { 97 | $text = Shortcode::compile($content); 98 | return ''. $text .''; 99 | } 100 | } 101 | 102 | Shortcode::register('span', array('SpanShortcode', 'span')); 103 | ``` 104 | 105 | Using function name. 106 | 107 | ```php 108 | function smallTag($attr, $content = null, $name = null) 109 | { 110 | $text = Shortcode::compile($content); 111 | return ''. $text .''; 112 | } 113 | 114 | Shortcode::register('small', 'smallTag'); 115 | ``` 116 | 117 | 118 | 119 | ## Compiling Shortcode 120 | 121 | ```php 122 | $text = '[a href="#"]Click here[/a]'; 123 | echo Shortcode::compile($text); 124 | 125 | $text = ' 126 | [a href="#"] 127 | [img src="http://placehold.it/140x140"] 128 | [small]This is small text[/small] 129 | [/a] 130 | '; 131 | echo Shortcode::compile($text); 132 | ``` 133 | 134 | 135 | 136 | ## Unregistering Shortcode 137 | 138 | ```php 139 | Shortcode::unregister('img'); 140 | ``` 141 | 142 | 143 | 144 | ## Destroying All Shortcodes 145 | 146 | ```php 147 | Shortcode::destroy(); 148 | ``` 149 | -------------------------------------------------------------------------------- /themes.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Laravel 5 Themes 3 | --- 4 | 5 | # Laravel 5 Themes 6 | 7 | - [Installation](#installation) 8 | - [Usage](#usage) 9 | - [Get All Themes](#get-all-themes) 10 | - [Set Active Theme](#set-active-theme) 11 | - [Get Current Theme](#get-current-theme) 12 | - [Check Theme](#check-theme) 13 | - [Set Themes Path](#set-themes-path) 14 | - [Get Themes Path](#get-themes-path) 15 | - [Get Theme's Path](#get-theme-path) 16 | - [Get Theme's View](#get-theme-view) 17 | - [Get Theme's Lang](#get-theme-lang) 18 | - [Get Theme's Config](#get-theme-config) 19 | - [Artisan Commands](#artisan-commands) 20 | - [theme:make](#theme-make-command) 21 | - [theme:list](#theme-list-command) 22 | - [theme:cache](#theme-cache-command) 23 | - [theme:publish](#theme-publish-command) 24 | 25 | 26 | 27 | ## Installation 28 | 29 | Open your composer.json file, and add the new required package. 30 | 31 | ```json 32 | "pingpong/themes": "~2.1" 33 | ``` 34 | 35 | Next, open a terminal and run. 36 | 37 | ``` 38 | composer update 39 | ``` 40 | 41 | Next, Add new service provider in `config/app.php`. 42 | 43 | ```php 44 | 'Pingpong\Themes\ThemesServiceProvider', 45 | ``` 46 | 47 | Next, Add new aliases in `config/app.php`. 48 | 49 | ```php 50 | 'Theme' => 'Pingpong\Themes\ThemeFacade', 51 | ``` 52 | 53 | Next, publish the package's assets. 54 | 55 | ``` 56 | php artisan vendor:publish 57 | ``` 58 | 59 | Done. 60 | 61 | 62 | 63 | ## Usage 64 | 65 | 66 | Get all themes. 67 | 68 | ```php 69 | Theme::all(); 70 | ``` 71 | 72 | 73 | Set theme active. 74 | 75 | ```php 76 | Theme::set('default'); 77 | 78 | Theme::setCurrent('default'); 79 | ``` 80 | 81 | 82 | Get current theme active. 83 | 84 | ```php 85 | Theme::getCurrent(); 86 | ``` 87 | 88 | 89 | Check theme. 90 | 91 | ```php 92 | Theme::has('simple') 93 | 94 | Theme::exists('other-theme'); 95 | ``` 96 | 97 | 98 | Set theme path. 99 | 100 | ```php 101 | $path = public_path('themes'); 102 | 103 | Theme::setPath($path); 104 | ``` 105 | 106 | 107 | Get theme path. 108 | 109 | ```php 110 | Theme::getThemePath('default'); 111 | ``` 112 | 113 | 114 | Get themes path. 115 | 116 | ```php 117 | Theme::getPath(); 118 | ``` 119 | 120 | 121 | Get view from current active theme. 122 | 123 | ```php 124 | Theme::view('index'); 125 | 126 | Theme::view('folders.view'); 127 | ``` 128 | 129 | 130 | Get translation value from active theme. 131 | 132 | ```php 133 | Theme::lang('group.name'); 134 | ``` 135 | 136 | 137 | Get theme's config value from active theme. 138 | 139 | ```php 140 | Theme::config('filename.key'); 141 | 142 | Theme::config('filename.key.subkey'); 143 | 144 | Theme::config('filename.key.subkey', 'default value here'); 145 | ``` 146 | 147 | If your theme's config file named `config.php`, you can get the value of config little bit short. 148 | 149 | ```php 150 | Theme::config('key'); 151 | 152 | Theme::config('key.subkey'); 153 | ``` 154 | 155 | You can also get config value from other theme. 156 | 157 | ```php 158 | // current theme 159 | Theme::config('key'); 160 | // from other theme 161 | Theme::config('bootstrap::key'); 162 | ``` 163 | 164 | 165 | 166 | ## Artisan Commands 167 | 168 | 169 | Generate a new theme. 170 | 171 | ``` 172 | php artisan theme:make foo 173 | ``` 174 | 175 | 176 | Show all available themes. 177 | 178 | ``` 179 | php artisan theme:list 180 | ``` 181 | 182 | 183 | Cache all themes. 184 | 185 | ``` 186 | php artisan theme:cache 187 | ``` 188 | 189 | 190 | Publish all theme's assets from all themes. 191 | 192 | ``` 193 | php artisan theme:publish 194 | ``` 195 | 196 | Publish all theme's assets from the specified theme. 197 | 198 | ``` 199 | php artisan theme:publish theme-name 200 | ``` 201 | -------------------------------------------------------------------------------- /trusty.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Roles and Permissions for Laravel 5 3 | --- 4 | 5 | # Trusty - Roles and Permissions for Laravel 5 6 | 7 | - [Installation](#installation) 8 | - [Creating A Role](#creating-a-role) 9 | - [Creating A Permission](#creating-a-permission) 10 | - [Adding Permission to Role](#adding-permission-to-role) 11 | - [Adding Role to User](#adding-role-to-user) 12 | - [Checking Role User](#checking-role-user) 13 | - [Checking User Permission](#checking-user-permission) 14 | 15 | 16 | 17 | ### Installation 18 | 19 | Open your composer.json file, and add the new required package. 20 | 21 | ```json 22 | "pingpong/trusty": "~2.1" 23 | ``` 24 | 25 | Next, open a terminal and run. 26 | 27 | ``` 28 | composer update 29 | ``` 30 | 31 | Next, Add new service provider in `config/app.php`. 32 | 33 | ```php 34 | 'Pingpong\Trusty\TrustyServiceProvider', 35 | ``` 36 | 37 | Next, Add new aliases in `config/app.php`. 38 | 39 | ```php 40 | 'Trusty' => 'Pingpong\Trusty\Facades\Trusty', 41 | 'Role' => 'Pingpong\Trusty\Role', 42 | 'Permission' => 'Pingpong\Trusty\Permission', 43 | ``` 44 | 45 | Next, publish the package's migrations. 46 | 47 | ``` 48 | php artisan vendor:publish 49 | ``` 50 | 51 | **NOTE:** If you want to modify the `roles` and `permissions` table, you can publish the migration. 52 | 53 | Done. 54 | 55 | ### Usage 56 | 57 | Add `Pingpong\Trusty\Traits\TrustyTrait` trait to your `User` model. For example. 58 | 59 | ```php 60 | 82 | ``` 83 | 84 | 85 | 86 | ## Creating A Role. 87 | 88 | With description. 89 | 90 | ```php 91 | Role::create([ 92 | 'name' => 'Administrator', 93 | 'slug' => Str::slug('Administrator', '_'), 94 | 'description' => 'The Super Administrator' 95 | ]); 96 | ``` 97 | 98 | Without description. 99 | 100 | ```php 101 | Role::create([ 102 | 'name' => 'Editor', 103 | 'slug' => Str::slug('Editor', '_'), 104 | ]); 105 | ``` 106 | 107 | 108 | 109 | ## Creating A Permission 110 | 111 | With description. 112 | 113 | ```php 114 | Permission::create([ 115 | 'name' => 'Manage Users', 116 | 'slug' => Str::slug('Manage Users', '_'), // manage_users 117 | 'description' => 'Create, Read, Update and Delete Users' 118 | ]); 119 | ``` 120 | 121 | Without description. 122 | 123 | ```php 124 | Permission::create([ 125 | 'name' => 'Manage Posts', 126 | 'slug' => Str::slug('Manage Posts', '_'), // manage_posts 127 | ]); 128 | ``` 129 | 130 | 131 | 132 | ## Adding Permission to Role. 133 | 134 | ```php 135 | $permission_id = 1; 136 | $role = Role::findOrFail(1); 137 | $role->permissions()->attach($permission_id); 138 | ``` 139 | 140 | 141 | 142 | ## Adding Role to User. 143 | 144 | By Role ID. 145 | 146 | ```php 147 | Auth::user()->addRole(1); 148 | ``` 149 | 150 | By Slug Or Name. 151 | 152 | ```php 153 | Auth::user()->addRole('admin'); 154 | 155 | Auth::user()->addRole('Administrator'); 156 | ``` 157 | 158 | 159 | 160 | ## Checking Role User 161 | 162 | Checking single role. 163 | 164 | ```php 165 | if(Auth::user()->is('administrator')) 166 | { 167 | // your code here 168 | } 169 | ``` 170 | 171 | Multiple roles. 172 | 173 | ```php 174 | if(Auth::user()->is('administrator', 'subscriber')) 175 | { 176 | // your code here 177 | } 178 | ``` 179 | 180 | Or using magic method. 181 | 182 | ```php 183 | if(Auth::user()->isAdministrator()) 184 | { 185 | // your code 186 | } 187 | ``` 188 | 189 | 190 | 191 | ## Checking User Permission 192 | 193 | Single check. 194 | 195 | ```php 196 | if(Auth::user()->can('manage_users')) 197 | { 198 | // your code here 199 | } 200 | ``` 201 | 202 | Checking multiple permissions. 203 | 204 | ```php 205 | if(Auth::user()->can('manage_users', 'manage_pages')) 206 | { 207 | // your code here 208 | } 209 | ``` 210 | 211 | Or using magic method. 212 | 213 | ```php 214 | if(Auth::user()->canManageUsers()) 215 | { 216 | // your code here 217 | } 218 | ``` 219 | 220 | Check permissions against a role. 221 | 222 | ```php 223 | $role = Role::findOrFail(1); 224 | 225 | if ($role->can('manage_users')) 226 | { 227 | // your code here 228 | } 229 | ``` 230 | 231 | Or using magic method. 232 | 233 | ```php 234 | $role = Role::findOrFail(1); 235 | 236 | if($role->canManageUsers()) 237 | { 238 | // your code here 239 | } 240 | ``` 241 | -------------------------------------------------------------------------------- /widget.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Laravel 5 Widget 3 | --- 4 | 5 | # Laravel 5 Widget 6 | 7 | - [Installation](#installation) 8 | - [What's New](#whats-new) 9 | - [Registering Widget](#registering-widget) 10 | - [Calling Widget](#calling-widget) 11 | - [Grouping Widget](#grouping-widget) 12 | 13 | 14 | 15 | ## Installation 16 | 17 | Open your composer.json file and add the new required package. 18 | 19 | ```json 20 | "pingpong/widget" : "~2.1" 21 | ``` 22 | 23 | Next, open your terminal and run `composer update`. 24 | 25 | After composer updated, add new service provider in `config/app.php` : 26 | 27 | ```php 28 | 'Pingpong\Widget\WidgetServiceProvider', 29 | ``` 30 | 31 | And add facade in the same file 32 | 33 | ```php 34 | 'Widget' => 'Pingpong\Widget\WidgetFacade' 35 | ``` 36 | 37 | Done. 38 | 39 | 40 | 41 | ## What's New! 42 | 43 | Subscribe widget: It's a new way to register widget using a specified class. For example: 44 | 45 | ```php 46 | Widget::subscribe('WidgetSubscriber'); 47 | 48 | class WidgetSubscriber { 49 | 50 | public function subscribe($widget) 51 | { 52 | $widget->register('image', __CLASS__ .'@image'); 53 | } 54 | 55 | public function image() 56 | { 57 | return 'Your handler here'; 58 | } 59 | } 60 | ``` 61 | 62 | You can also specified which method to handle subscriber of widget. 63 | 64 | ```php 65 | Widget::subscribe('WidgetSubscriber@handle'); 66 | 67 | class WidgetSubscriber { 68 | 69 | public function handle($widget) 70 | { 71 | $widget->register('image', __CLASS__ .'@image'); 72 | } 73 | 74 | public function image() 75 | { 76 | return 'Your handler here'; 77 | } 78 | } 79 | ``` 80 | 81 | 82 | 83 | ### Registering A Widget 84 | 85 | By default you can register a widget in `app/widgets.php`, that file will autoload automatically. 86 | 87 | Via Closure. 88 | 89 | ```php 90 | // app/widgets.php 91 | 92 | Widget::register('small', function($contents) 93 | { 94 | return "{$contents}"; 95 | }); 96 | 97 | Widget::register('view', function($view, $data = array(), $mergeData = array() 98 | { 99 | return View::make($view, $data, $mergeData)->render(); 100 | }); 101 | ``` 102 | 103 | Via Class Name. 104 | 105 | By default will call `register` method. 106 | 107 | ```php 108 | class MyWidget { 109 | 110 | public function register($contents, $attributes = array()) 111 | { 112 | $attributes = HTML::attributes($attributes); 113 | 114 | return "{$contents}"; 115 | } 116 | 117 | } 118 | 119 | Widget::register('h1', 'MyWidget'); 120 | ``` 121 | 122 | Via Class Name with the specified method. 123 | 124 | ```php 125 | class TagCreator { 126 | 127 | public function create($tag, $contents, $attributes = array()) 128 | { 129 | $attributes = HTML::attributes($attributes); 130 | 131 | return "<{$tag}{$attributes}>{$contents}"; 132 | } 133 | 134 | } 135 | 136 | class HTMLWidget { 137 | 138 | protected $tag; 139 | 140 | public function __construct(TagCreator $tag) 141 | { 142 | $this->tag = $tag; 143 | } 144 | 145 | public function p($contents, $attributes = array()) 146 | { 147 | return $this->tag->create('p', $contents, $attributes); 148 | } 149 | 150 | public function div($contents, $attributes = array()) 151 | { 152 | return $this->tag->create('div', $contents, $attributes); 153 | } 154 | } 155 | Widget::register('p', 'HTMLWidget@p'); 156 | 157 | Widget::register('div', 'HTMLWidget@div'); 158 | ``` 159 | 160 | 161 | 162 | ### Calling A Widget 163 | 164 | ```php 165 | Widget::get('small', array('My Content')); 166 | 167 | Widget::call('small', array('My Content')); 168 | 169 | Widget::small('My Content'); 170 | 171 | Widget::p('My Content'); 172 | 173 | Widget::div('My Content'); 174 | 175 | Widget::h1('My Content'); 176 | ``` 177 | 178 | On view you can call like this. 179 | 180 | ``` 181 | @small('My Content') 182 | 183 | @view('users.show', $data, $mergeData) 184 | 185 | @h1('Welcome!') 186 | 187 | @p('Hello World', array('class' => 'page-header')); 188 | 189 | @div('Lorem ipsum', array('class' => 'alert alert-warning')); 190 | ``` 191 | 192 | 193 | 194 | ### Grouping A Widget 195 | 196 | It is very easy to group widget. you only need to specify the group name and specify an array of the names of the widgets that will be grouped. 197 | 198 | ```php 199 | Widget::register('calendar', 'SidebarWidget@calendar') 200 | 201 | Widget::register('archive', 'SidebarWidget@archive') 202 | 203 | Widget::group('sidebar', array('calendar', 'archive')); 204 | ``` 205 | 206 | To call a group of widgets is the same as calling the widget. 207 | 208 | ```php 209 | Widget::sidebar(); 210 | ``` 211 | 212 | If you want to send parameters to the widget that is in the group, you can call it like this. 213 | 214 | ```php 215 | Widget::sidebar( 216 | array('your-first-param', 'your-second-param'), 217 | array('first-param-for-second-widget', 'the-second') 218 | ); 219 | ``` 220 | 221 | On view you can call a group of widgets is same as calling the widget. 222 | 223 | ``` 224 | @sidebar() 225 | 226 | @sidebar(array('first-param'), array('first-param-for-second-widget')) 227 | ``` 228 | -------------------------------------------------------------------------------- /generators.md: -------------------------------------------------------------------------------- 1 | # Laravel 5 Generators 2 | 3 | - [Installation](#installation) 4 | - [Artisan Commands](#artisan-commands) 5 | - [Generate a controller](#controller) 6 | - [Generate a model](#model) 7 | - [Generate a console command](#console) 8 | - [Generate a form request](#request) 9 | - [Generate a migration](#migration) 10 | - [Generate a pivot migration](#pivot) 11 | - [Generate a seed](#seed) 12 | - [Generate a view](#view) 13 | - [Generate a scaffold](#scaffold) 14 | - [Modifying Templates](#modifying-templates) 15 | 16 | 17 | 18 | ## Installation 19 | 20 | ``` 21 | composer require "pingpong/generators:~2.1" 22 | ``` 23 | 24 | Next, register new service provider to `providers` array in `config/app.php`. 25 | 26 | ```php 27 | 'Pingpong\Generators\GeneratorsServiceProvider' 28 | ``` 29 | 30 | Done. 31 | 32 | 33 | 34 | ## Artisan Commands 35 | 36 | In this package, there are many CLI commands that are useful to speed up you in creating web applications with Laravel. Some commands may already be familiar, such as the command to create a controller or model. However we are aware, sometimes we want everything instantly. Although not all of them can be so. 37 | 38 | 39 | 40 | ### Generate a new controller 41 | 42 | Generate a basic controller. 43 | 44 | ```bash 45 | php artisan generate:controller UsersController 46 | ``` 47 | 48 | Generate a resource controller. 49 | 50 | ```bash 51 | php artisan generate:controller UsersController --resource 52 | # OR 53 | php artisan generate:controller UsersController -r 54 | ``` 55 | 56 | Generate a scaffolded controller. 57 | 58 | ```bash 59 | php artisan generate:controller UsersController --scaffold 60 | # OR 61 | php artisan generate:controller UsersController -s 62 | ``` 63 | 64 | 65 | 66 | ### Generate a new model 67 | 68 | ```bash 69 | php artisan generate:model User 70 | 71 | php artisan generate:model Users/User 72 | ``` 73 | 74 | 75 | 76 | ### Generate a new console 77 | 78 | ```bash 79 | php artisan generate:console FooCommand 80 | 81 | php artisan generate:console FooCommand --command="foo" --description="a console" 82 | ``` 83 | 84 | 85 | 86 | ### Generate a new form request 87 | 88 | ```bash 89 | php artisan generate:request CreateUserRequest 90 | ``` 91 | 92 | You can also specify `rules`. 93 | 94 | ```bash 95 | php artisan generate:request CreateUserRequest --rules="username:required, email:required,email" 96 | 97 | php artisan generate:request CreateUserRequest --rules="username:unique(users;username)" 98 | ``` 99 | 100 | 101 | 102 | ### Generate a new migration 103 | 104 | Generate a basic migration. 105 | 106 | ``` 107 | php artisan generate:migration create_users_table 108 | ``` 109 | 110 | Generate a migration with specify the fields. 111 | 112 | ``` 113 | php artisan generate:migration create_users_table --fields="username:string, email:string:unique, remember_token, soft_delete" 114 | ``` 115 | 116 | Add new field to an existing table. 117 | 118 | ``` 119 | php artisan generate:migration add_password_to_users_table --fields="password:string" 120 | ``` 121 | 122 | Remove column from the specified table. 123 | 124 | ``` 125 | php artisan generate:migration remove_password_from_users_table --fields="password:string" 126 | ``` 127 | 128 | Drop the specified table. 129 | 130 | ``` 131 | php artisan generate:migration drop_users_table 132 | ``` 133 | 134 | 135 | 136 | ### Generate a pivot 137 | 138 | ```bash 139 | php artisan generate:pivot users roles 140 | ``` 141 | 142 | 143 | 144 | ### Generate a seed class 145 | 146 | Create a basic database seeder class. 147 | 148 | ```bash 149 | php artisan generate:seed users 150 | ``` 151 | 152 | 153 | 154 | ### Generate a view 155 | 156 | Basic usage. 157 | 158 | ```bash 159 | php artisan generate:view index 160 | ``` 161 | 162 | Auto generate folder. 163 | 164 | ```bash 165 | php artisan generate:view users/index 166 | ``` 167 | 168 | Generate a plain/blank view. 169 | 170 | ```bash 171 | php artisan generate:view users/index --plain 172 | ``` 173 | 174 | Generate a master view. 175 | 176 | ```bash 177 | php artisan generate:view layouts/master --master 178 | ``` 179 | 180 | 181 | 182 | ### Generate a scaffold resource 183 | 184 | For some cases, we may need to be faster in making resource. Let's say we're making a CRUD. First we have to create a migration, then the controller, and then the model and the others stuffs. If we use the commands to make it one by one, it is inefficient and will take a long time. That is where the "generate:scaffold" useful. With this command, we can create a CRUD with just one command. 185 | 186 | ```bash 187 | php artisan generate:scaffold task --fields="name:string, description:text" 188 | ``` 189 | 190 | From the example above we can see how easy it is to create a crud just one command. The first parameter is the name of the entity being in the singular convention. For example, if you want to create users CRUD, you just need to use user. You have to follow singular convention. 191 | 192 | ```bash 193 | php artisan generate:scaffold user 194 | ``` 195 | 196 | You can also specify the option `prefix` for this command. It is used as a `prefix` controller path , views, and also the route. 197 | 198 | ```bash 199 | php artisan generate:scaffold task --fields="name:string, description:text" --prefix=admin 200 | ``` 201 | 202 | 203 | 204 | ## Modifying Templates 205 | 206 | > This feature is added since version 2.1.2. 207 | 208 | You may also modify the generator templates (or stubs) as you want. To modify templates, you need to publish them first. You can publish the templates by running this following command. 209 | 210 | ```bash 211 | php artisan vendor:publish --provider="Pingpong\Generators\GeneratorsServiceProvider" 212 | ``` 213 | 214 | This command will publish the templates to `resources/pingpong/generators/stubs` path. 215 | 216 | You may also change the template path to other path by changing `template_path` value from `generators` config. 217 | 218 | ```php 219 | // File: config/generators.php 220 | return [ 221 | 'template_path' => base_path('resources/pingpong/generators/stubs') 222 | ]; 223 | ``` 224 | -------------------------------------------------------------------------------- /menus.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Laravel 5 Menus 3 | --- 4 | 5 | # Laravel 5 Menus 6 | 7 | - [Upgrades](#upgrades) 8 | - [Installation](#installation) 9 | - [Creating A Menu](#creating-a-menu) 10 | - [Menu Item](#menu-item) 11 | - [Menu Dropdown](#menu-dropdown) 12 | - [Menu Dropdown Milti Level](#menu-dropdown-multi-level) 13 | - [Menu Divider](#menu-divider) 14 | - [Dropdown Header](#dropdown-header) 15 | - [Ordering Menu Item](#ordering-menu-item) 16 | - [Make Lots of Menu](#make-lots-of-menu) 17 | - [Menu Presenter](#menu-presenter) 18 | - [The Available Presenter](#available-presenter) 19 | - [Make A Custom Presenter](#make-a-custom-presenter) 20 | - [Register A New Menu Style](#register-a-menu-style) 21 | - [View Presenter](#view-presenter) 22 | - [The Available View Presenter](#available-view-presenter) 23 | - [Rendering Menu](#rendering-menu) 24 | - [Menu Inheritance](#menu-inheritance) 25 | - [Menu Instance](#menu-instance) 26 | - [Finding Menu Item](#finding-menu-item) 27 | - [Modifying Menu](#modifying-menu) 28 | 29 | 30 | 31 | ## Upgrades 32 | 33 | #### **To 2.0.10** 34 | 35 | - Add new `ordering` config key in your `config/menus.php` file and set the value to false. 36 | 37 | ```php 38 | return [ 39 | // --more code here-- 40 | 'ordering' => false 41 | ]; 42 | ``` 43 | 44 | 45 | 46 | ## Installation 47 | 48 | You can install the through composer command line. 49 | 50 | ``` 51 | composer require pingpong/menus 52 | ``` 53 | 54 | After the package installed, add a new service provider to the `providers` array in `config/app.php` file. 55 | 56 | ```php 57 | 'providers' => array( 58 | 'Pingpong\Menus\MenusServiceProvider' 59 | ), 60 | ``` 61 | 62 | Add new alias for `Menu` facade to the `aliases` array at the same file. 63 | 64 | ```php 65 | 'aliases' => array( 66 | 'Menu' => 'Pingpong\Menus\MenuFacade', 67 | ) 68 | ``` 69 | 70 | Then, publish package's assets by running: 71 | 72 | ``` 73 | php artisan vendor:publish 74 | ``` 75 | 76 | 77 | 78 | ## Creating A Menu 79 | 80 | You can define your menus in `app/Support/menus.php` file. That file will loaded automatically by this package. 81 | 82 | To create a menu, simply call the `create` method from `Menu` facade. The first parameter is the menu name and the second parameter is callback for defining menu items. 83 | 84 | ```php 85 | Menu::create('navbar', function($menu) 86 | { 87 | // define your menu items here 88 | }); 89 | ``` 90 | 91 | Since version 2.1.1, you may also create a menu via `make` method. 92 | 93 | ```php 94 | Menu::make('navbar', function($menu) 95 | { 96 | // define your menu items here 97 | }); 98 | ``` 99 | 100 | 101 | **Menu Item** 102 | 103 | As explained before, we can defining menu item in the callback by accessing `$menu` variable, which the variable is instance of `Pingpong\Menus\MenuBuilder` class. 104 | 105 | To defining a plain URL, you can use `->url()` method. 106 | 107 | ```php 108 | Menu::create('navbar', function($menu) 109 | { 110 | // URL , Title, Attributes 111 | $menu->url('home', 'Home', ['target' => 'blank']); 112 | }); 113 | ``` 114 | 115 | If you have named route, you define the menu item by calling `->route()` method. 116 | 117 | ```php 118 | Menu::create('navbar', function($menu) 119 | { 120 | $menu->route( 121 | 'users.show', // route name 122 | 'View Profile', // title 123 | ['id' => 1], // route parameters 124 | ['target' => 'blank'] // attributes 125 | ); 126 | }); 127 | ``` 128 | 129 | You can also defining the menu item via array by calling `->add()` method. 130 | 131 | ```php 132 | Menu::create('navbar', function($menu) 133 | { 134 | $menu->add([ 135 | 'url' => 'about', 136 | 'title' => 'About', 137 | 'attributes' => [ 138 | 'target' => '_blank' 139 | ] 140 | ]); 141 | 142 | $menu->add([ 143 | 'route' => ['profile', ['user' => 'gravitano']], 144 | 'title' => 'Visit My Profile', 145 | 'attributes' => [ 146 | 'target' => '_blank' 147 | ] 148 | ]); 149 | }); 150 | ``` 151 | 152 | 153 | **Menu Dropdown** 154 | 155 | To create a dropdown menu, you can call to `->dropdown()` method and passing the first parameter by title of dropdown and the second parameter by closure callback that retrive `$sub` variable. The `$sub` variable is the the instance of `Pingpong\Menus\MenuItem` class. 156 | 157 | ```php 158 | Menu::create('navbar', function($menu) 159 | { 160 | $menu->url('/', 'Home'); 161 | $menu->dropdown('Settings', function ($sub) { 162 | $sub->url('settings/account', 'Account'); 163 | $sub->url('settings/password', 'Password'); 164 | $sub->url('settings/design', 'Design'); 165 | }); 166 | }); 167 | ``` 168 | 169 | 170 | **Menu Dropdown Multi Level** 171 | 172 | You can also create a dropdown inside dropdown by using `->dropdown()` method. This will allow to to create a multilevel menu items. 173 | 174 | ```php 175 | Menu::create('navbar', function($menu) 176 | { 177 | $menu->url('/', 'Home'); 178 | $menu->dropdown('Account', function ($sub) { 179 | $sub->url('profile', 'Visit My Profile'); 180 | $sub->dropdown('Settings', function ($sub) { 181 | $sub->url('settings/account', 'Account'); 182 | $sub->url('settings/password', 'Password'); 183 | $sub->url('settings/design', 'Design'); 184 | }); 185 | $sub->url('logout', 'Logout'); 186 | }); 187 | }); 188 | ``` 189 | 190 | 191 | **Menu Divider** 192 | 193 | You may also define a divider for each menu item. You can divide between menu item by using `->divider()` method. 194 | 195 | ```php 196 | Menu::create('navbar', function($menu) 197 | { 198 | $menu->url('/', 'Home'); 199 | $menu->divider(); 200 | $menu->url('profile', 'Profile') 201 | }); 202 | ``` 203 | 204 | 205 | **Dropdown Header** 206 | 207 | You may also add a dropdown header for the specified menu item by using `->header()` method. 208 | 209 | ```php 210 | Menu::create('navbar', function($menu) 211 | { 212 | $menu->url('/', 'Home') 213 | $menu->dropdown('Settings', function ($sub) { 214 | $sub->header('ACCOUNT'); 215 | $sub->url('/settings/design', 'Design'); 216 | $sub->divider(); 217 | $sub->url('logout', 'Logout'); 218 | }); 219 | }); 220 | ``` 221 | 222 | 223 | **Ordering Menu Item** 224 | 225 | You may order the menu by specify `order` parameter. 226 | 227 | ```php 228 | Menu::create('navbar', function($menu) 229 | { 230 | // url, title, order, attributes 231 | $menu->url('/', 'Home', 1); 232 | // url, title, route parameters, order, attributes 233 | $menu->route('/', 'About', ['user' => '1'], 2); 234 | // title, order, callback attributes 235 | $menu->dropdown('Settings', function ($sub) { 236 | $sub->header('ACCOUNT'); 237 | $sub->url('/settings/design', 'Design'); 238 | $sub->divider(); 239 | $sub->url('logout', 'Logout'); 240 | }, 3); 241 | }); 242 | ``` 243 | 244 | You may also set the order value by calling `->order` method. 245 | 246 | ```php 247 | Menu::create('navbar', function($menu) 248 | { 249 | $menu->url('/', 'Home', ['icon' => 'fa fa-dashboard'])->order(1); 250 | 251 | $menu->route('/', 'About', ['user' => '1'], ['icon' => 'fa fa-user'])->order(2); 252 | 253 | $menu->dropdown('Settings', function ($sub) { 254 | $sub->header('ACCOUNT'); 255 | $sub->url('/settings/design', 'Design'); 256 | $sub->divider(); 257 | $sub->url('logout', 'Logout'); 258 | })->order(3); 259 | }); 260 | ``` 261 | 262 | By default ordering feature is disabled. You can enable the `ordering` feature in your config file. Just update value of `ordering` config to `true` and now your menu will ordered by `order` key. 263 | 264 | ```php 265 | // File: config/menus.php 266 | return [ 267 | 'ordering' => true 268 | ]; 269 | ``` 270 | 271 | You may also enable or disable menu ordering for each menu via `->enableOrdering` and `->disableOrdering` method. 272 | 273 | ```php 274 | Menu::create('navbar', function($menu) 275 | { 276 | // disable menu ordering 277 | $menu->enableOrdering(); 278 | 279 | // disable menu ordering 280 | $menu->disableOrdering(); 281 | }); 282 | ``` 283 | 284 | 285 | **Make Lots of menu** 286 | 287 | You can also create a lots of menu with different name and menu items. 288 | 289 | ```php 290 | Menu::create('menu1', function($menu) 291 | { 292 | 293 | $menu->route('home', 'Home'); 294 | 295 | $menu->url('profile', 'Profile'); 296 | }); 297 | 298 | Menu::create('menu2', function($menu) 299 | { 300 | $menu->route('home', 'Home'); 301 | 302 | $menu->url('profile', 'Profile'); 303 | }); 304 | ``` 305 | 306 | 307 | 308 | ### Menu Presenter 309 | 310 | This package included with some presenter classes that used for converting menu to html tag. By default the generated menu style is `bootstrap navbar`. But, there are also several different menu styles. 311 | 312 | You can apply the menu style via `->style()` method. 313 | 314 | ```php 315 | Menu::create('navbar', function($menu) 316 | { 317 | $menu->style('nav-pills'); 318 | }); 319 | ``` 320 | 321 | Or you can set which presenter to present the menu style via `->setPresenter()` method. 322 | 323 | ```php 324 | Menu::create('navbar', function($menu) 325 | { 326 | $menu->setPresenter('Pingpong\Menus\Presenters\Bootstrap\NavTabPresenter'); 327 | }); 328 | ``` 329 | 330 | You can also set which style of presenter when you rendering a menu. 331 | 332 | ```php 333 | Menu::render('navbar', 'navbar-right'); 334 | 335 | Menu::render('navbar', 'Pingpong\Menus\Presenters\Bootstrap\NavPillsPresenter'); 336 | ``` 337 | 338 | 339 | **The List of Available Menu Presenter Class** 340 | 341 | | Name | Presenter Class | 342 | | -------------- | :--------------------------------------------------------- | 343 | | `navbar` | `Pingpong\Menus\Presenters\Bootstrap\NavbarPresenter` | 344 | | `navbar-right` | `Pingpong\Menus\Presenters\Bootstrap\NavbarRightPresenter` | 345 | | `nav-pills` | `Pingpong\Menus\Presenters\Bootstrap\NavPillsPresenter` | 346 | | `nav-tab` | `Pingpong\Menus\Presenters\Bootstrap\NavTabPresenter` | 347 | | `sidebar` | `Pingpong\Menus\Presenters\Bootstrap\SidebarMenuPresenter` | 348 | | `navmenu` | `Pingpong\Menus\Presenters\Bootstrap\NavMenuPresenter` | 349 | 350 | 351 | **Make A Costum Presenter** 352 | 353 | You can create your own presenter class. Make sure your presenter is extends to `Pingpong\Menus\Presenters\Presenter` and `implements` to 'Pingpong\Menus\Presenters\PresenterInterface'. 354 | 355 | For example, this is `zurb-top-bar` presenter. 356 | 357 | ```php 358 | use Pingpong\Menus\Presenters\Presenter; 359 | 360 | class ZurbTopBarPresenter extends Presenter 361 | { 362 | /** 363 | * {@inheritdoc } 364 | */ 365 | public function getOpenTagWrapper() 366 | { 367 | return PHP_EOL . '
' . PHP_EOL; 368 | } 369 | 370 | /** 371 | * {@inheritdoc } 372 | */ 373 | public function getCloseTagWrapper() 374 | { 375 | return PHP_EOL . '
' . PHP_EOL; 376 | } 377 | 378 | /** 379 | * {@inheritdoc } 380 | */ 381 | public function getMenuWithoutDropdownWrapper($item) 382 | { 383 | return 'getActiveState($item).'>'.$item->getIcon().' '.$item->title.''; 384 | } 385 | 386 | /** 387 | * {@inheritdoc } 388 | */ 389 | public function getActiveState($item) 390 | { 391 | return \Request::is($item->getRequest()) ? ' class="active"' : null; 392 | } 393 | 394 | /** 395 | * {@inheritdoc } 396 | */ 397 | public function getDividerWrapper() 398 | { 399 | return '
  • '; 400 | } 401 | 402 | /** 403 | * {@inheritdoc } 404 | */ 405 | public function getMenuWithDropDownWrapper($item) 406 | { 407 | return '
  • 408 | 409 | '.$item->getIcon().' '.$item->title.' 410 | 411 |
      412 | '.$this->getChildMenuItems($item).' 413 |
    414 |
    • ' . PHP_EOL; 415 | ; 416 | } 417 | } 418 | ``` 419 | 420 | To use this costum presenter, you can use the `setPresenter` method. 421 | 422 | ```php 423 | Menu::create('zurb-top-bar', function($menu) 424 | { 425 | $menu->setPresenter('ZurbTopBarPresenter'); 426 | }); 427 | ``` 428 | 429 | 430 | **Register A New Menu Style** 431 | 432 | Menu style is like an alias to a presenter. You can register your style from your costum presenter in the configuration file in `config/menus.php`. 433 | 434 | ```php 435 | return array( 436 | 'navbar' => 'Pingpong\Menus\Presenters\Bootstrap\NavbarPresenter', 437 | 'navbar-right' => 'Pingpong\Menus\Presenters\Bootstrap\NavbarRightPresenter', 438 | 'nav-pills' => 'Pingpong\Menus\Presenters\Bootstrap\NavPillsPresenter', 439 | 'nav-tab' => 'Pingpong\Menus\Presenters\Bootstrap\NavTabPresenter', 440 | 441 | 'zurb-top-bar' => 'ZurbTopBarPresenter', 442 | ); 443 | ``` 444 | 445 | Now, you can use a style like this. 446 | 447 | ```php 448 | Menu::create('zurb-top-bar', function($menu) 449 | { 450 | $menu->style('zurb-top-bar'); 451 | }); 452 | ``` 453 | 454 | 455 | 456 | ### View Presenter 457 | 458 | If you don't like to use presenter class, you use view presenter instead. We can set which view to present the menus by calling `->setView()` method. 459 | 460 | ```php 461 | Menu::create('navbar', function($menu) 462 | { 463 | $menu->setView('menus::default'); 464 | }); 465 | ``` 466 | 467 | 468 | **The List of Available View Presenter** 469 | 470 | | View Name | Menu Style | 471 | | ---------------------------- | :---------------------------- | 472 | | `menus::default` | Bootstrap Navbar (default) | 473 | | `menus::navbar-left` | Bootstrap Navbar Left | 474 | | `menus::navbar-right` | Bootstrap Navbar Right | 475 | | `menus::nav-tabs` | Bootstrap Nav Tabs | 476 | | `menus::nav-tabs-justified` | Bootstrap Nav Tabs Justified | 477 | | `menus::nav-pills` | Bootstrap Nav Pills | 478 | | `menus::nav-pills-stacked` | Bootstrap Nav Pills Stacked | 479 | | `menus::nav-pills-justified` | Bootstrap Nav Pills Justified | 480 | | `menus::menu` | Plain Menu | 481 | 482 | 483 | 484 | ### Rendering Menu 485 | 486 | To render the menu you can use `render` or `get` method. 487 | 488 | ```php 489 | Menu::render('navbar'); 490 | 491 | Menu::get('navbar'); 492 | ``` 493 | 494 | You can also set which style to present the menu in the second parameter. 495 | 496 | ```php 497 | Menu::render('navbar', 'navbar-right'); 498 | ``` 499 | 500 | Or you may also set which view to present the menu. 501 | 502 | ```php 503 | Menu::render('navbar', 'menus::nav-tabs'); 504 | ``` 505 | 506 | 507 | 508 | 509 | 510 | ### The Menu Instance 511 | 512 | Sometimes, maybe we need to add a new additional menu from controller or other place. To get an instance of an existing menu, you can use the `instance` method. 513 | 514 | ```php 515 | $menu = Menu::instance('zurb-top-bar'); 516 | 517 | // You can also make additions to the menu again 518 | 519 | $menu->add(['title' => 'Settings', 'route' => 'settings']); 520 | 521 | $menu->url('profile', 'Profile'); 522 | 523 | $menu->route('settings', 'Settings'); 524 | ``` 525 | 526 | 527 | 528 | ### Finding Menu Item 529 | 530 | To find menu item, you can use `findBy` method from `Pingpong\Menus\MenuBuilder` class. 531 | 532 | ```php 533 | $menu = Menu::instance('sidebar'); 534 | 535 | $menu->url('profile', 'Profile'); 536 | 537 | $menuItem = $menu->findBy('title', 'Profile'); 538 | 539 | // add child menu 540 | $menuItem->url('foo', 'Foo'); 541 | ``` 542 | 543 | You may also use `whereTitle` helper method to find a specific menu item. Also, you can add other child menu item in the callback that located in the second argument in `whereTitle` method. 544 | 545 | ```php 546 | $menu = Menu::instance('sidebar'); 547 | 548 | $menu->url('profile', 'Profile'); 549 | 550 | $menu->whereTitle('Profile', function ($sub) 551 | { 552 | $sub->url('foo', 'Foo'); 553 | }); 554 | 555 | // add childs menu 556 | ``` 557 | 558 | 559 | 560 | ### Modifying Menu 561 | 562 | After we create a menu, maybe we need to add other additional menus. You may modifying menu via `->modify` method. 563 | 564 | ```php 565 | Menu::modify('navbar', function($menu) 566 | { 567 | $menu->add([ 568 | 'title' => 'Foo', 569 | 'url' => 'bar', 570 | ]); 571 | }); 572 | ``` 573 | -------------------------------------------------------------------------------- /modules.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Laravel 5 Modules 3 | --- 4 | 5 | # Laravel 5 Modules 6 | 7 | - [Upgrade Guide](#upgrade-guide) 8 | - [Installation](#installation) 9 | - [Configuration](#configuration) 10 | - [Naming Convension](#naming-convension) 11 | - [Folder Structure](#folder-structure) 12 | - [Creating Module](#creating-a-module) 13 | - [Artisan Commands](#artisan-commands) 14 | - [Facades](#facades) 15 | - [Entity](#entity) 16 | - [Auto Scan Vendor Directory](#auto-scan-vendor-directory) 17 | - [Publishing Modules](#publishing-modules) 18 | 19 | `pingpong/modules` is a laravel package which created to manage your large laravel app using modules. Module is like a laravel package, it have some views, controllers or models. This package is supported and tested in both Laravel 4 and Laravel 5. 20 | 21 | 22 | 23 | ## Upgrade Guide 24 | 25 | #### To 2.0.18 26 | 27 | If you have been updated to version `2.0.18`, please read [this release note](https://github.com/pingpong-labs/modules/releases/tag/2.0.18). 28 | 29 | #### To 2.0.10 30 | 31 | Previously, we add two service provider from this package. In version `2.0.5`, we just need register one service provider. Now, we can remove `Pingpong\Modules\Providers\BootstrapServiceProvider` from `providers` array, because now it service provider is registered automatically by `Pingpong\Modules\ModulesServiceProvider`. 32 | 33 | #### From Laravel 4 to Laravel 5 34 | 35 | If upgrade your Laravel app from Laravel 4 to Laravel 5, there is a few things to do if you are using this package. You will receive some kind errors about config not loaded. To fix this issue, please follow this instruction. 36 | 37 | - If you publish the package's configuration file, you need to move the config file from `app/config/packages/pingpong/modules/config.php` to `app/config/modules.php`. 38 | - If you are not publish the package's configuration file and you want to publish the config file, just run `php artisan vendor:publish` command and you are done. 39 | 40 | #### From 1.1.\* to 1.2.0 41 | 42 | New configuration file. This breaking change affected if you publish the configuration file from this package. To fix this issue, create new config file called `config.php` in your `app/config/packages/pingpong/modules/` directory. Next move the array contents from `paths.php` file to `paths` array in new configuration file. 43 | Your config file will looks like [this](https://github.com/pingpong-labs/modules/blob/1.2.0/src/config/config.php). 44 | 45 | 46 | 47 | ## Installation 48 | 49 | To install through composer, simply put the following in your composer.json file: 50 | 51 | ```json 52 | { 53 | "require": { 54 | "pingpong/modules": "~2.1" 55 | } 56 | } 57 | ``` 58 | 59 | And then run `composer install` to fetch the package. 60 | 61 | #### Quick Installation 62 | 63 | You could also simplify the above code by using the following command: 64 | 65 | ``` 66 | composer require "pingpong/modules:~2.1" 67 | ``` 68 | 69 | #### Add Service Provider 70 | 71 | Next add the following service provider in `config/app.php`. 72 | 73 | ```php 74 | 'providers' => array( 75 | 'Pingpong\Modules\ModulesServiceProvider', 76 | ), 77 | ``` 78 | 79 | Next, add the following aliases to `aliases` array in the same file. 80 | 81 | ```php 82 | 'aliases' => array( 83 | 'Module' => 'Pingpong\Modules\Facades\Module', 84 | ), 85 | ``` 86 | 87 | Next publish the package's configuration file by run : 88 | 89 | ``` 90 | php artisan vendor:publish 91 | ``` 92 | 93 | #### Autoloading 94 | 95 | By default controllers, entities or repositories not loaded automatically. You can autoload all that stuff using `psr-4`. For example : 96 | 97 | ```json 98 | { 99 | "autoload": { 100 | "psr-4": { 101 | "App\\": "app/", 102 | "Modules\\": "modules/" 103 | } 104 | } 105 | } 106 | ``` 107 | 108 | 109 | 110 | ## Configuration 111 | 112 | - `modules` - Used for save the generated modules. 113 | - `assets` - Used for save the modules's assets from each modules. 114 | - `migration` - Used for save the modules's migrations if you publish the modules's migrations. 115 | - `generator` - Used for generate modules folders. 116 | - `scan` - Used for allow to scan other folders. 117 | - `enabled` - If `true`, the package will scan other paths. By default the value is `false` 118 | - `paths` - The list of path which can scanned automatically by the package. 119 | - `composer` 120 | - `vendor` - Composer vendor name. 121 | - `author.name` - Composer author name. 122 | - `author.email` - Composer author email. 123 | - `cache` 124 | - `enabled` - If `true`, the scanned modules (all modules) will cached automatically. By default the value is `false` 125 | - `key` - The name of cache. 126 | - `lifetime` - Lifetime of cache. 127 | 128 | 129 | 130 | ## Creating A Module 131 | 132 | To create a new module you can simply run : 133 | 134 | ``` 135 | php artisan module:make 136 | ``` 137 | 138 | - `` - Required. The name of module will be created. 139 | 140 | **Create a new module** 141 | 142 | ``` 143 | php artisan module:make Blog 144 | ``` 145 | 146 | **Create multiple modules** 147 | 148 | ``` 149 | php artisan module:make Blog User Auth 150 | ``` 151 | 152 | By default if you create a new module, that will add some resources like controller, seed class or provider automatically. If you don't want these, you can add `--plain` flag, to generate a plain module. 153 | 154 | ```shell 155 | php artisan module:make Blog --plain 156 | #OR 157 | php artisan module:make Blog -p 158 | ``` 159 | 160 | 161 | **Naming Convension** 162 | 163 | Because we are autoloading the modules using `psr-4`, we strongly recommend using `StudlyCase` convension. 164 | 165 | 166 | **Folder Structure** 167 | 168 | ``` 169 | laravel-app/ 170 | app/ 171 | bootstrap/ 172 | vendor/ 173 | modules/ 174 | ├── Blog/ 175 | ├── Assets/ 176 | ├── Config/ 177 | ├── Console/ 178 | ├── Database/ 179 | ├── Migrations/ 180 | ├── Seeders/ 181 | ├── Entities/ 182 | ├── Http/ 183 | ├── Controllers/ 184 | ├── Middleware/ 185 | ├── Requests/ 186 | ├── routes.php 187 | ├── Providers/ 188 | ├── BlogServiceProvider.php 189 | ├── Resources/ 190 | ├── lang/ 191 | ├── views/ 192 | ├── Repositories/ 193 | ├── Tests/ 194 | ├── composer.json 195 | ├── module.json 196 | ├── start.php 197 | ``` 198 | 199 | 200 | 201 | ## Artisan Commands 202 | 203 | Create new module. 204 | 205 | ``` 206 | php artisan module:make blog 207 | ``` 208 | 209 | Use the specified module. Please see [#26](https://github.com/pingpong-labs/modules/pull/26). 210 | 211 | ```php 212 | php artisan module:use blog 213 | ``` 214 | 215 | Show all modules in command line. 216 | 217 | ``` 218 | php artisan module:list 219 | ``` 220 | 221 | Create new command for the specified module. 222 | 223 | ``` 224 | php artisan module:make-command CustomCommand blog 225 | 226 | php artisan module:make-command CustomCommand --command=custom:command blog 227 | 228 | php artisan module:make-command CustomCommand --namespace=Modules\Blog\Commands blog 229 | ``` 230 | 231 | Create new migration for the specified module. 232 | 233 | ``` 234 | php artisan module:make-migration create_users_table blog 235 | 236 | php artisan module:make-migration create_users_table --fields="username:string, password:string" blog 237 | 238 | php artisan module:make-migration add_email_to_users_table --fields="email:string:unique" blog 239 | 240 | php artisan module:make-migration remove_email_from_users_table --fields="email:string:unique" blog 241 | 242 | php artisan module:make-migration drop_users_table blog 243 | ``` 244 | 245 | Rollback, Reset and Refresh The Modules Migrations. 246 | 247 | ``` 248 | php artisan module:migrate-rollback 249 | 250 | php artisan module:migrate-reset 251 | 252 | php artisan module:migrate-refresh 253 | ``` 254 | 255 | Rollback, Reset and Refresh The Migrations for the specified module. 256 | 257 | ``` 258 | php artisan module:migrate-rollback blog 259 | 260 | php artisan module:migrate-reset blog 261 | 262 | php artisan module:migrate-refresh blog 263 | ``` 264 | 265 | Create new seed for the specified module. 266 | 267 | ``` 268 | php artisan module:make-seed users blog 269 | ``` 270 | 271 | Migrate from the specified module. 272 | 273 | ``` 274 | php artisan module:migrate blog 275 | ``` 276 | 277 | Migrate from all modules. 278 | 279 | ``` 280 | php artisan module:migrate 281 | ``` 282 | 283 | Seed from the specified module. 284 | 285 | ``` 286 | php artisan module:seed blog 287 | ``` 288 | 289 | Seed from all modules. 290 | 291 | ``` 292 | php artisan module:seed 293 | ``` 294 | 295 | Create new controller for the specified module. 296 | 297 | ``` 298 | php artisan module:make-controller SiteController blog 299 | ``` 300 | 301 | Publish assets from the specified module to public directory. 302 | 303 | ``` 304 | php artisan module:publish blog 305 | ``` 306 | 307 | Publish assets from all modules to public directory. 308 | 309 | ``` 310 | php artisan module:publish 311 | ``` 312 | 313 | Create new model for the specified module. 314 | 315 | ``` 316 | php artisan module:make-model User blog 317 | 318 | php artisan module:make-model User blog --fillable="username,email,password" 319 | ``` 320 | 321 | Create new service provider for the specified module. 322 | 323 | ``` 324 | php artisan module:make-provider MyServiceProvider blog 325 | ``` 326 | 327 | Publish migration for the specified module or for all modules. 328 | This helpful when you want to rollback the migrations. You can also run `php artisan migrate` instead of `php artisan module:migrate` command for migrate the migrations. 329 | 330 | For the specified module. 331 | 332 | ``` 333 | php artisan module:publish-migration blog 334 | ``` 335 | 336 | For all modules. 337 | 338 | ``` 339 | php artisan module:publish-migration 340 | ``` 341 | 342 | Enable the specified module. 343 | 344 | ``` 345 | php artisan module:enable blog 346 | ``` 347 | 348 | Disable the specified module. 349 | 350 | ``` 351 | php artisan module:disable blog 352 | ``` 353 | 354 | Generate new middleware class. 355 | 356 | ``` 357 | php artisan module:make-middleware Auth 358 | ``` 359 | 360 | Update dependencies for the specified module. 361 | 362 | ``` 363 | php artisan module:update ModuleName 364 | ``` 365 | 366 | Update dependencies for all modules. 367 | 368 | ``` 369 | php artisan module:update 370 | ``` 371 | 372 | Show the list of modules. 373 | 374 | ``` 375 | php artisan module:list 376 | ``` 377 | 378 | 379 | 380 | ## Facades 381 | 382 | Get all modules. 383 | 384 | ```php 385 | Module::all(); 386 | ``` 387 | 388 | Get all cached modules. 389 | 390 | ```php 391 | Module::getCached() 392 | ``` 393 | 394 | Get ordered modules. The modules will be ordered by the `priority` key in `module.json` file. 395 | 396 | ```php 397 | Module::getOrdered(); 398 | ``` 399 | 400 | Get scanned modules. 401 | 402 | ```php 403 | Module::scan(); 404 | ``` 405 | 406 | Find a specific module. 407 | 408 | ```php 409 | Module::find('name'); 410 | // OR 411 | Module::get('name'); 412 | ``` 413 | 414 | Find a module, if there is one, return the `Module` instance, otherwise throw `Pingpong\Modules\Exeptions\ModuleNotFoundException`. 415 | 416 | ```php 417 | Module::findOrFail('module-name'); 418 | ``` 419 | 420 | Get scanned paths. 421 | 422 | ```php 423 | Module::getScanPaths(); 424 | ``` 425 | 426 | Get all modules as a collection instance. 427 | 428 | ```php 429 | Module::toCollection(); 430 | ``` 431 | 432 | Get modules by the status. 1 for active and 0 for inactive. 433 | 434 | ```php 435 | Module::getByStatus(1); 436 | ``` 437 | 438 | Check the specified module. If it exists, will return `true`, otherwise `false`. 439 | 440 | ```php 441 | Module::has('blog'); 442 | ``` 443 | 444 | Get all enabled modules. 445 | 446 | ```php 447 | Module::enabled(); 448 | ``` 449 | 450 | Get all disabled modules. 451 | 452 | ```php 453 | Module::disabled(); 454 | ``` 455 | 456 | Get count of all modules. 457 | 458 | ```php 459 | Module::count(); 460 | ``` 461 | 462 | Get module path. 463 | 464 | ```php 465 | Module::getPath(); 466 | ``` 467 | 468 | Register the modules. 469 | 470 | ```php 471 | Module::register(); 472 | ``` 473 | 474 | Boot all available modules. 475 | 476 | ```php 477 | Module::boot(); 478 | ``` 479 | 480 | Get all enabled modules as collection instance. 481 | 482 | ```php 483 | Module::collections(); 484 | ``` 485 | 486 | Get module path from the specified module. 487 | 488 | ```php 489 | Module::getModulePath('name'); 490 | ``` 491 | 492 | Get assets path from the specified module. 493 | 494 | ```php 495 | Module::getAssetPath('name'); 496 | ``` 497 | 498 | Get config value from this package. 499 | 500 | ```php 501 | Module::config('composer.vendor'); 502 | ``` 503 | 504 | Get used storage path. 505 | 506 | ```php 507 | Module::getUsedStoragePath(); 508 | ``` 509 | 510 | Get used module for cli session. 511 | 512 | ```php 513 | Module::getUsedNow(); 514 | // OR 515 | Module::getUsed(); 516 | ``` 517 | 518 | Set used module for cli session. 519 | 520 | ```php 521 | Module::setUsed('name'); 522 | ``` 523 | 524 | Get modules's assets path. 525 | 526 | ```php 527 | Module::getAssetsPath(); 528 | ``` 529 | 530 | Get asset url from specific module. 531 | 532 | ```php 533 | Module::asset('blog:img/logo.img'); 534 | ``` 535 | 536 | Install the specified module by given module name. 537 | 538 | ```php 539 | Module::install('pingpong-modules/hello'); 540 | ``` 541 | 542 | Update dependencies for the specified module. 543 | 544 | ```php 545 | Module::update('hello'); 546 | ``` 547 | 548 | 549 | 550 | ## Module Entity 551 | 552 | Get an entity from a specific module. 553 | 554 | ```php 555 | $module = Module::find('blog'); 556 | ``` 557 | 558 | Get module name. 559 | 560 | ```php 561 | $module->getName(); 562 | ``` 563 | 564 | Get module name in lowercase. 565 | 566 | ```php 567 | $module->getLowerName(); 568 | ``` 569 | 570 | Get module name in studlycase. 571 | 572 | ```php 573 | $module->getStudlyName(); 574 | ``` 575 | 576 | Get module path. 577 | 578 | ```php 579 | $module->getPath(); 580 | ``` 581 | 582 | Get extra path. 583 | 584 | ```php 585 | $module->getExtraPath('Assets'); 586 | ``` 587 | 588 | Disable the specified module. 589 | 590 | ```php 591 | $module->enable(); 592 | ``` 593 | 594 | Enable the specified module. 595 | 596 | ```php 597 | $module->disable(); 598 | ``` 599 | 600 | Delete the specified module. 601 | 602 | ```php 603 | $module->delete(); 604 | ``` 605 | 606 | 607 | 608 | ## Custom Namespaces 609 | 610 | When you create a new module it also registers new custom namespace for `Lang`, `View` and `Config`. For example, if you create a new module named blog, it will also register new namespace/hint blog for that module. Then, you can use that namespace for calling `Lang`, `View` or `Config`. Following are some examples of its usage: 611 | 612 | Calling Lang: 613 | 614 | ```php 615 | Lang::get('blog::group.name'); 616 | ``` 617 | 618 | Calling View: 619 | 620 | ```php 621 | View::make('blog::index') 622 | 623 | View::make('blog::partials.sidebar') 624 | ``` 625 | 626 | Calling Config: 627 | 628 | ```php 629 | Config::get('blog.name') 630 | ``` 631 | 632 | ## Publishing Modules 633 | 634 | Have you created a laravel modules? Yes, I've. Then, I want to publish my modules. Where do I publish it? That's the question. What's the answer ? The answer is [Packagist](http://packagist.org). In pingpong/modules version >= 1.2.0, when you generate a module, you will see there is a new file generated called `composer.json`. 635 | 636 | 637 | 638 | ### Auto Scan Vendor Directory 639 | 640 | By default the `vendor` directory is not scanned automatically, you need to update the configuration file to allow that. Set `scan.enabled` value to `true`. For example : 641 | 642 | ```php 643 | // file config/modules.php 644 | 645 | return [ 646 | //... 647 | 'scan' => [ 648 | 'enabled' => true 649 | ] 650 | //... 651 | ] 652 | ``` 653 | 654 | You can verify the module has been installed using `module:list` command: 655 | 656 | ``` 657 | php artisan module:list 658 | ``` 659 | 660 | 661 | 662 | ## Publishing Modules 663 | 664 | After creating a module and you are sure your module module will be used by other developers. You can push your module to [github](https://github.com) or [bitbucket](https://bitbucket.org) and after that you can submit your module to the packagist website. 665 | 666 | You can follow this step to publish your module. 667 | 668 | 1. Create A Module. 669 | 2. Push the module to github. 670 | 3. Submit your module to the packagist website. 671 | Submit to packagist is very easy, just give your github repository, click submit and you done. 672 | --------------------------------------------------------------------------------