├── LaravelCollectiveDocs-banner.png
├── annotations.md
├── docs.md
├── html.md
├── readme.md
└── ssh.md


/LaravelCollectiveDocs-banner.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/LaravelCollective/docs/20d46f3fd402c1337cadf3e188f7d40717e59911/LaravelCollectiveDocs-banner.png


--------------------------------------------------------------------------------
/annotations.md:
--------------------------------------------------------------------------------
  1 | # Annotations
  2 | 
  3 | - [Installation](#installation)
  4 | - [Scanning](#scanning)
  5 | - [Event Annotations](#events)
  6 | - [Route Annotations](#routes)
  7 | - [Scanning Controllers](#controllers)
  8 | - [Model Annotations](#models)
  9 | - [Custom Annotations](#custom-annotations)
 10 | 
 11 | <a name="installation"></a>
 12 | ## Installation
 13 | 
 14 | > If you have changed the top-level namespace to something like 'MyCompany', then you would use the new namespace instead of 'App'.
 15 | 
 16 | Begin by installing this package through Composer. Edit your project's `composer.json` file to require `laravelcollective/annotations`.
 17 | 
 18 |     "require": {
 19 |         "laravelcollective/annotations": "6.0.\*"
 20 |     }
 21 | 
 22 | Next, update Composer from the Terminal:
 23 | 
 24 |     composer update
 25 | 
 26 | Once composer is done, you'll need to create a Service Provider in `app/Providers/AnnotationsServiceProvider.php`.
 27 | 
 28 | ```php
 29 | <?php namespace App\Providers;
 30 | 
 31 | use Collective\Annotations\AnnotationsServiceProvider as ServiceProvider;
 32 | 
 33 | class AnnotationsServiceProvider extends ServiceProvider {
 34 | 
 35 |     /**
 36 |      * The classes to scan for event annotations.
 37 |      *
 38 |      * @var array
 39 |      */
 40 |     protected $scanEvents = [];
 41 | 
 42 |     /**
 43 |      * The classes to scan for route annotations.
 44 |      *
 45 |      * @var array
 46 |      */
 47 |     protected $scanRoutes = [];
 48 | 
 49 |     /**
 50 |      * The classes to scan for model annotations.
 51 |      *
 52 |      * @var array
 53 |      */
 54 |     protected $scanModels = [];
 55 | 
 56 |     /**
 57 |      * Determines if we will auto-scan in the local environment.
 58 |      *
 59 |      * @var bool
 60 |      */
 61 |     protected $scanWhenLocal = false;
 62 | 
 63 |     /**
 64 |      * Determines whether or not to automatically scan the controllers
 65 |      * directory (App\Http\Controllers) for routes
 66 |      *
 67 |      * @var bool
 68 |      */
 69 |     protected $scanControllers = false;
 70 | 
 71 |     /**
 72 |      * Determines whether or not to automatically scan all namespaced
 73 |      * classes for event, route, and model annotations.
 74 |      *
 75 |      * @var bool
 76 |      */
 77 |     protected $scanEverything = false;
 78 | 
 79 | }
 80 | ```
 81 | 
 82 | Finally, add your new provider to the `providers` array of `config/app.php`:
 83 | 
 84 | ```php
 85 |   'providers' => [
 86 |     // ...
 87 |     App\Providers\AnnotationsServiceProvider::class
 88 |     // ...
 89 |   ];
 90 | ```
 91 | 
 92 | <a name="scanning"></a>
 93 | ## Setting up Scanning
 94 | 
 95 | Add event handler classes to the `protected $scanEvents` array to scan for event annotations.
 96 | 
 97 | ```php
 98 |     /**
 99 |      * The classes to scan for event annotations.
100 |      *
101 |      * @var array
102 |      */
103 |     protected $scanEvents = [
104 |       App\Handlers\Events\MailHandler::class,
105 |     ];
106 | ```
107 | 
108 | Add controllers to the `protected $scanRoutes` array to scan for route annotations.
109 | 
110 | ```php
111 |     /**
112 |      * The classes to scan for route annotations.
113 |      *
114 |      * @var array
115 |      */
116 |     protected $scanRoutes = [
117 |       App\Http\Controllers\HomeController::class,
118 |     ];
119 | ```
120 | 
121 | Add models to the `protected $scanModels` array to scan for model annotations.
122 | 
123 | ```php
124 |     /**
125 |      * The classes to scan for model annotations.
126 |      *
127 |      * @var array
128 |      */
129 |     protected $scanModels = [
130 |       'App\User',
131 |     ];
132 | ```
133 | 
134 | Alternatively, you can set `protected $scanEverything` to `true` to automatically scan all classes within your application's namespace. *Note:* This may increase the time required to execute the scanners, depending on the size of your application.
135 | 
136 | Scanning your event handlers, controllers, and models can be done manually by using `php artisan event:scan`, `php artisan route:scan`, or `php artisan model:scan` respectively. In the local environment, you can scan them automatically by setting `protected $scanWhenLocal = true`.
137 | 
138 | <a name="events"></a>
139 | ## Event Annotations
140 | 
141 | ### @Hears
142 | 
143 | The `@Hears` annotation registers an event listener for a particular event. Annotating any method with `@Hears("SomeEventName")` will register an event listener that will call that method when the `SomeEventName` event is fired.
144 | 
145 | ```php
146 | <?php namespace App\Handlers\Events;
147 | 
148 | use App\User;
149 | 
150 | class MailHandler {
151 | 
152 |   /**
153 |    * Send welcome email to User
154 |    * @Hears("UserWasRegistered")
155 |    */
156 |   public function sendWelcomeEmail(User $user)
157 |   {
158 |     // send welcome email to $user
159 |   }
160 | 
161 | }
162 | ```
163 | 
164 | <a name="routes"></a>
165 | ## Route Annotations
166 | 
167 | Route annotations can be incredibly powerful, however the order of your route definitions can impact how your application matches specific routes, specifically any wildcard routes. If `protected $scanEverything` is set to `true`, you will have no control over the order of your route definitions.
168 | 
169 | ### @Get
170 | 
171 | The `@Get` annotation registeres a route for an HTTP GET request.
172 | 
173 | ```php
174 | <?php namespace App\Http\Controllers;
175 | 
176 | class HomeController {
177 | 
178 |   /**
179 |    * Show the Index Page
180 |    * @Get("/")
181 |    */
182 |   public function getIndex()
183 |   {
184 |     return view('index');
185 |   }
186 | 
187 | }
188 | ```
189 | 
190 | You can also set up route names.
191 | 
192 | ```php
193 |   /**
194 |    * @Get("/", as="index")
195 |    */
196 | ```
197 | 
198 | ... or middlewares.
199 | 
200 | ```php
201 |   /**
202 |    * @Get("/", middleware="guest")
203 |    */
204 | ```
205 | 
206 | ... or both.
207 | 
208 | ```php
209 |   /**
210 |    * @Get("/", as="index", middleware="guest")
211 |    */
212 | ```
213 | 
214 | Here's an example that uses all of the available parameters for a `@Get` annotation:
215 | 
216 | ```php
217 |   /**
218 |    * @Get("/profiles/{id}", as="profiles.show", middleware="guest", domain="foo.com", where={"id": "[0-9]+"})
219 |    */
220 | ```
221 | 
222 | ### @Post, @Options, @Put, @Patch, @Delete, @any
223 | 
224 | The `@Post`, `@Options`, `@Put`, `@Patch`, `@Delete`, and `@Any` annotations have the exact same syntax as the `@Get` annotation, except it will register a route for the respective HTTP verb, as opposed to the GET verb.
225 | 
226 | ### @Middleware
227 | 
228 | As well as defining middleware inline in the route definition tags (`@Get`, `@Post`, etc.), the `@Middleware` tag can be used on its own. It works both individual methods:
229 | 
230 | ```php
231 |   /**
232 |    * Show the Login Page
233 |    *
234 |    * @Get("login")
235 |    * @Middleware("guest")
236 |    */
237 |   public function login()
238 |   {
239 |     return view('index');
240 |   }
241 | ```
242 | 
243 | Or on a whole controller, with the same only/exclude filter syntax that you can use elsewhere in laravel:
244 | 
245 | ```php
246 | /**
247 |  * @Middleware("guest", except={"logout"})
248 |  */
249 | class AuthController extends Controller {
250 | 
251 |   /**
252 |    * Log the user out.
253 |    *
254 |    * @Get("logout", as="logout")
255 |    * @Middleware("auth")
256 |    *
257 |    * @return Response
258 |    */
259 |   public function logout()
260 |   {
261 |     $this->auth->logout();
262 | 
263 |     return redirect( route('login') );
264 |   }
265 | 
266 | }
267 | ```
268 | 
269 | ### @Resource
270 | 
271 | Using the `@Resource` annotation on a controller allows you to easily set up a Resource Controller.
272 | 
273 | ```php
274 | <?php
275 | /**
276 |  * @Resource('users')
277 |  */
278 | class UsersController extends Controller {
279 |   // index(), create(), store(), show($id), edit($id), update($id), destroy($id)
280 | }
281 | ```
282 | 
283 | You can specify the `only` and `except` arguments, just like you can with the regular `Route::resource()` command.
284 | 
285 | ```php
286 |   /**
287 |    * @Resource('users', only={"index", "show"})
288 |    */
289 | ```
290 | 
291 | You can also specify the route names of each resource method.
292 | 
293 | ```php
294 |   /**
295 |    * @Resource('users', names={"index"="user.all", "show"="user.view"})
296 |    */
297 | ```
298 | 
299 | ### @Controller
300 | 
301 | Using the `@Controller` annotation on a controller allows you to set various options for the routes contained in it:
302 | 
303 | ```php
304 | <?php
305 | /**
306 |  * @Controller(prefix="admin", domain="foo.com")
307 |  */
308 | class AdminController extends Controller {
309 |   // All routes will be prefixed by admin/
310 | }
311 | ```
312 | 
313 | <a name="controllers"></a>
314 | ## Scan the Controllers Directory
315 | 
316 | To recursively scan the entire controllers namespace ( `App\Http\Controllers` ), you can set the `$scanControllers` flag to true.
317 | 
318 | It will automatically adjust `App` to your app's namespace.
319 | 
320 | ```php
321 |     $scanControllers = true;
322 | ```
323 | 
324 | ### Advanced
325 | 
326 | If you want to use any logic to add classes to the list to scan, you can override the `routeScans()` or `eventScans()` methods.
327 | 
328 | The following is an example of adding a controller to the scan list if the current environment is `local`:
329 | 
330 | ```php
331 | public function routeScans() {
332 |     $classes = parent::routeScans();
333 | 
334 |     if ( $this->app->environment('local') ) {
335 |         $classes = array_merge($classes, [App\Http\Controllers\LocalOnlyController::class]);
336 |     }
337 | 
338 |     return $classes;
339 | }
340 | ```
341 | 
342 | #### Scanning Namespaces
343 | 
344 | You can use the `getClassesFromNamespace( $namespace )` method to recursively add namespaces to the list. This will scan the given namespace. It only works for classes in the `app` directory, and relies on the PSR-4 namespacing standard.
345 | 
346 | This is what the `$scanControllers` flag uses with the controllers directory.
347 | 
348 | Here is an example that builds on the last one - adding a whole local-only namespace.
349 | 
350 | ```php
351 | public function routeScans() {
352 |     $classes = parent::routeScans();
353 | 
354 |     if ( $this->app->environment('local') ) {
355 |     {
356 |         $classes = array_merge(
357 |             $classes,
358 |             $this->getClassesFromNamespace( App\Http\Controllers\Local::class )
359 |         );
360 |     }
361 | 
362 |     return $classes;
363 | }
364 | ```
365 | 
366 | <a name="models"></a>
367 | ## Model Annotations
368 | 
369 | You can use annotations to automatically bind your models to route parameters, using [Route Model Binding](http://laravel.com/docs/5.0/routing#route-model-binding). To do this, use the `@Bind` annotation.
370 | 
371 | ```php
372 | /**
373 |  * @Bind("users")
374 |  */
375 | class User extends Eloquent {
376 |   //
377 | }
378 | ```
379 | 
380 | This is the equivalent of calling `Route::model('users', 'App\Users')`.
381 | 
382 | <a name="custom-annotations"></a>
383 | ## Custom Annotations
384 | 
385 | If you want to register your own annotations, create a namespace containing subclasses of `Collective\Annotations\Routing\Annotations\Annotations\Annotation` - let's say `App\Http\Annotations`.
386 | 
387 | Then, in your annotations service provider, override the `addRoutingAnnotations( RouteScanner $scanner )` method, and register your routing annotations namespace:
388 | 
389 | ```php
390 | <?php namespace App\Providers;
391 | 
392 | use Collective\Annotations\Routing\Annotations\Scanner as RouteScanner;
393 | 
394 | /* ... then, in the class definition ... */
395 | 
396 |     /**
397 |      * Add annotation classes to the route scanner
398 |      *
399 |      * @param RouteScanner $namespace
400 |      */
401 |     public function addRoutingAnnotations( RouteScanner $scanner )
402 |     {
403 |       $scanner->addAnnotationNamespace( 'App\Http\Annotations' );
404 |     }
405 | ```
406 | 
407 | Your annotation classes must must have the `@Annotation` class annotation (see the following example).
408 | 
409 | There is an equivalent method for event annotations: `addEventAnnotations( EventScanner $scanner )`.
410 | 
411 | ### Custom Annotation Example
412 | 
413 | Here is an example to make an `@Auth` annotation. It provides the same functionality as using the annotation `@Middleware("auth")`.
414 | 
415 | In a namespace - in this example, `App\Annotations`:
416 | 
417 | ```php
418 | <?php namespace App\Http\Annotations;
419 | 
420 | use Collective\Annotations\Routing\Annotations\Annotations\Annotation;
421 | use Collective\Annotations\Routing\Annotations\MethodEndpoint;
422 | use ReflectionMethod;
423 | 
424 | /**
425 |  * @Annotation
426 |  */
427 | class Auth extends Annotation {
428 | 
429 |   /**
430 |    * {@inheritdoc}
431 |    */
432 |   public function modify(MethodEndpoint $endpoint, ReflectionMethod $method)
433 |   {
434 |     if ($endpoint->hasPaths())
435 |     {
436 |       foreach ($endpoint->getPaths() as $path)
437 |       {
438 |         $path->middleware = array_merge($path->middleware, (array) 'auth');
439 |       }
440 |     }
441 |     else
442 |     {
443 |       $endpoint->middleware = array_merge($endpoint->middleware, (array) 'auth');
444 |     }
445 |   }
446 | 
447 | }
448 | ```
449 | 


--------------------------------------------------------------------------------
/docs.md:
--------------------------------------------------------------------------------
1 | - [Annotations](/docs/master/annotations)
2 | - [HTML & Forms](/docs/master/html)
3 | - [Remote (SSH)](/docs/master/ssh)
4 | 


--------------------------------------------------------------------------------
/html.md:
--------------------------------------------------------------------------------
  1 | # Forms & HTML
  2 | 
  3 | - [Installation](#installation)
  4 | - [Important](#important)
  5 | - [Opening A Form](#opening-a-form)
  6 | - [CSRF Protection](#csrf-protection)
  7 | - [Form Model Binding](#form-model-binding)
  8 | - [Form Model Accessors](#form-model-accessors)
  9 | - [Labels](#labels)
 10 | - [Text, Text Area, Password & Hidden Fields](#text)
 11 | - [Checkboxes and Radio Buttons](#checkboxes-and-radio-buttons)
 12 | - [File Input](#file-input)
 13 | - [Number Input](#number)
 14 | - [Date Input](#date)
 15 | - [Drop-Down Lists](#drop-down-lists)
 16 | - [Buttons](#buttons)
 17 | - [Custom Macros](#custom-macros)
 18 | - [Custom Components](#custom-components)
 19 | - [Generating URLs](#generating-urls)
 20 | 
 21 | ## Replacement
 22 | If you're looking to replace this package due to it's retirement we recommend using [Shift](https://laravelshift.com/convert-laravelcollective-html-to-spatie-laravel-html): 
 23 | 
 24 | <a name="installation"></a>
 25 | ## Installation
 26 | 
 27 | Begin by installing this package through Composer. Edit your project's `composer.json` file to require `laravelcollective/html`.
 28 | 
 29 | ```bash
 30 | $ composer require laravelcollective/html
 31 | ```
 32 | 
 33 | > Looking to install this package in <a href="http://lumen.laravel.com" target="\_blank">Lumen</a>? First of all, making this package compatible with Lumen will require some core changes to Lumen, which we believe would dampen the effectiveness of having Lumen in the first place. Secondly, it is our belief that if you need this package in your application, then you should be using Laravel anyway.
 34 | 
 35 | <a name="important"></a>
 36 | ## Important
 37 | 
 38 | Since this package internally uses strict comparisons (`===` instead of `==`) be careful when passing numeric values into your forms.
 39 | Values in HTML are submitted as strings and Laravel old values stored in flash session are strings.
 40 | 
 41 | In this example, this package will correctly insert `selected` HTML attribute into the radio input - because the passed value `'1'` strictly equals to the old submitted value in the session `'1'`:
 42 | ```php
 43 | echo Form::radio('category_id', '1'); //  '1' === '1' - comparing passed value and old session value
 44 | ```
 45 | 
 46 | However, in this example, the passed integer value `1` is not strictly equal to the old submitted string value `'1'` in the session and the `selected` HTML attribute will not be inserted:
 47 | ```php
 48 | echo Form::radio('category_id', 1); // 1 === '1' - comparing passed value and old session value
 49 | ```
 50 | 
 51 | <a name="opening-a-form"></a>
 52 | ## Opening A Form
 53 | 
 54 | #### Opening A Form
 55 | 
 56 | ```php
 57 | {!! Form::open(['url' => 'foo/bar']) !!}
 58 | 	//
 59 | {!! Form::close() !!}
 60 | ```
 61 | 
 62 | By default, a `POST` method will be assumed; however, you are free to specify another method:
 63 | 
 64 | ```php
 65 | echo Form::open(['url' => 'foo/bar', 'method' => 'put'])
 66 | ```
 67 | 
 68 | > **Note:** Since HTML forms only support `POST` and `GET`, `PUT` and `DELETE` methods will be spoofed by automatically adding a `_method` hidden field to your form.
 69 | 
 70 | You may also open forms that point to named routes or controller actions:
 71 | 
 72 | ```php
 73 | echo Form::open(['route' => 'route.name'])
 74 | 
 75 | echo Form::open(['action' => 'Controller@method'])
 76 | ```
 77 | 
 78 | You may pass in route parameters as well:
 79 | 
 80 | ```php
 81 | echo Form::open(['route' => ['route.name', $user->id]])
 82 | 
 83 | echo Form::open(['route' => ['route.name', 'id' => $user->id, 'foo' => 'bar']])
 84 | 
 85 | echo Form::open(['action' => ['Controller@method', $user->id]])
 86 | 
 87 | echo Form::open(['action' => ['Controller@method', 'id' => $user->id, 'foo' => 'bar']])
 88 | ```
 89 | 
 90 | If your form is going to accept file uploads, add a `files` option to your array:
 91 | 
 92 | ```php
 93 | echo Form::open(['url' => 'foo/bar', 'files' => true])
 94 | ```
 95 | 
 96 | <a name="csrf-protection"></a>
 97 | ## CSRF Protection
 98 | 
 99 | #### Adding The CSRF Token To A Form
100 | 
101 | Laravel provides an easy method of protecting your application from cross-site request forgeries. First, a random token is placed in your user's session. If you use the `Form::open` method with `POST`, `PUT` or `DELETE` the CSRF token will be added to your forms as a hidden field automatically. Alternatively, if you wish to generate the HTML for the hidden CSRF field, you may use the `token` method:
102 | 
103 | ```php
104 | echo Form::token();
105 | ```
106 | 
107 | #### Attaching The CSRF Filter To A Route
108 | 
109 | ```php
110 | Route::post('profile',
111 |     [
112 |         'before' => 'csrf',
113 |         function()
114 |         {
115 |             //
116 |         }
117 |     ]
118 | );
119 | ```
120 | 
121 | <a name="form-model-binding"></a>
122 | ## Form Model Binding
123 | 
124 | #### Opening A Model Form
125 | 
126 | Often, you will want to populate a form based on the contents of a model. To do so, use the `Form::model` method:
127 | 
128 | ```php
129 | echo Form::model($user, ['route' => ['user.update', $user->id]])
130 | ```
131 | 
132 | Now, when you generate a form element, like a text input, the model's value matching the field's name will automatically be set as the field value. So, for example, for a text input named `email`, the user model's `email` attribute would be set as the value. However, there's more! If there is an item in the Session flash data matching the input name, that will take precedence over the model's value. So, the priority looks like this:
133 | 
134 | 1. Session Flash Data (Old Input)
135 | 2. Explicitly Passed Value
136 | 3. Model Attribute Data
137 | 
138 | This allows you to quickly build forms that not only bind to model values, but easily re-populate if there is a validation error on the server!
139 | 
140 | > **Note:** When using `Form::model`, be sure to close your form with `Form::close`!
141 | 
142 | <a name="form-model-accessors"></a>
143 | #### Form Model Accessors
144 | 
145 | Laravel's [Eloquent Accessor](http://laravel.com/docs/5.2/eloquent-mutators#accessors-and-mutators) allow you to manipulate a model attribute before returning it. This can be extremely useful for defining global date formats, for example. However, the date format used for display might not match the date format used for form elements. You can solve this by creating two separate accessors: a standard accessor, *and/or* a form accessor.
146 | 
147 | To define a form accessor, create a `formFooAttribute` method on your model where `Foo` is the "camel" cased name of the column you wish to access. In this example, we'll define an accessor for the `date_of_birth` attribute. The accessor will automatically be called by the HTML Form Builder when attempting to pre-fill a form field when `Form::model()` is used.
148 | 
149 | You must include the FormAccessible trait in your model definition for this to work.
150 | 
151 | ```php
152 | <?php
153 | 
154 | namespace App;
155 | 
156 | use Carbon\Carbon;
157 | use Illuminate\Database\Eloquent\Model;
158 | use Collective\Html\Eloquent\FormAccessible;
159 | 
160 | class User extends Model
161 | {
162 |     use FormAccessible;
163 | 
164 |     /**
165 |      * Get the user's date of birth.
166 |      *
167 |      * @param  string  $value
168 |      * @return string
169 |      */
170 |     public function getDateOfBirthAttribute($value)
171 |     {
172 |         return Carbon::parse($value)->format('m/d/Y');
173 |     }
174 | 
175 |     /**
176 |      * Get the user's date of birth for forms.
177 |      *
178 |      * @param  string  $value
179 |      * @return string
180 |      */
181 |     public function formDateOfBirthAttribute($value)
182 |     {
183 |         return Carbon::parse($value)->format('Y-m-d');
184 |     }
185 | }
186 | ```
187 | 
188 | <a name="labels"></a>
189 | ## Labels
190 | 
191 | #### Generating A Label Element
192 | 
193 | ```php
194 | echo Form::label('email', 'E-Mail Address');
195 | ```
196 | 
197 | #### Specifying Extra HTML Attributes
198 | 
199 | ```php
200 | echo Form::label('email', 'E-Mail Address', ['class' => 'awesome']);
201 | ```
202 | 
203 | > **Note:** After creating a label, any form element you create with a name matching the label name will automatically receive an ID matching the label name as well.
204 | 
205 | <a name="text"></a>
206 | ## Text, Text Area, Password & Hidden Fields
207 | 
208 | #### Generating A Text Input
209 | 
210 | ```php
211 | echo Form::text('username');
212 | ```
213 | 
214 | #### Specifying A Default Value
215 | 
216 | ```php
217 | echo Form::text('email', 'example@gmail.com');
218 | ```
219 | 
220 | > **Note:** The *hidden* and *textarea* methods have the same signature as the *text* method.
221 | 
222 | #### Generating A Password Input
223 | 
224 | ```php
225 | echo Form::password('password', ['class' => 'awesome']);
226 | ```
227 | 
228 | #### Generating Other Inputs
229 | 
230 | ```php
231 | echo Form::email($name, $value = null, $attributes = []);
232 | echo Form::file($name, $attributes = []);
233 | ```
234 | 
235 | <a name="checkboxes-and-radio-buttons"></a>
236 | ## Checkboxes and Radio Buttons
237 | 
238 | #### Generating A Checkbox Or Radio Input
239 | 
240 | ```php
241 | echo Form::checkbox('name', 'value');
242 | 
243 | echo Form::radio('name', 'value');
244 | ```
245 | 
246 | #### Generating A Checkbox Or Radio Input That Is Checked
247 | 
248 | ```php
249 | echo Form::checkbox('name', 'value', true);
250 | 
251 | echo Form::radio('name', 'value', true);
252 | ```
253 | 
254 | <a name="number"></a>
255 | ## Number
256 | 
257 | #### Generating A Number Input
258 | 
259 | ```php
260 | echo Form::number('name', 'value');
261 | ```
262 | 
263 | <a name="date"></a>
264 | ## Date
265 | 
266 | #### Generating A Date Input
267 | 
268 | ```php
269 | echo Form::date('name', \Carbon\Carbon::now());
270 | ```
271 | 
272 | <a name="file-input"></a>
273 | ## File Input
274 | 
275 | #### Generating A File Input
276 | 
277 | ```php
278 | echo Form::file('image');
279 | ```
280 | 
281 | > **Note:** The form must have been opened with the `files` option set to `true`.
282 | 
283 | <a name="drop-down-lists"></a>
284 | ## Drop-Down Lists
285 | 
286 | #### Generating A Drop-Down List
287 | 
288 | ```php
289 | echo Form::select('size', ['L' => 'Large', 'S' => 'Small']);
290 | ```
291 | 
292 | #### Generating A Drop-Down List With Selected Default
293 | 
294 | ```php
295 | echo Form::select('size', ['L' => 'Large', 'S' => 'Small'], 'S');
296 | ```
297 | 
298 | #### Generating a Drop-Down List With an Empty Placeholder
299 | 
300 | This will create an `<option>` element with no value as the very first option of your drop-down.
301 | 
302 | ```php
303 | echo Form::select('size', ['L' => 'Large', 'S' => 'Small'], null, ['placeholder' => 'Pick a size...']);
304 | ```
305 | 
306 | #### Generating A Grouped List
307 | 
308 | ```php
309 | echo Form::select('animal',[
310 | 	'Cats' => ['leopard' => 'Leopard'],
311 | 	'Dogs' => ['spaniel' => 'Spaniel'],
312 | ]);
313 | ```
314 | 
315 | #### Generating A Drop-Down List With A Range
316 | 
317 | ```php
318 | echo Form::selectRange('number', 10, 20);
319 | ```
320 | 
321 | #### Generating A List With Month Names
322 | 
323 | ```php
324 | echo Form::selectMonth('month');
325 | ```
326 | 
327 | <a name="buttons"></a>
328 | ## Buttons
329 | 
330 | #### Generating A Submit Button
331 | 
332 | ```php
333 | echo Form::submit('Click Me!');
334 | ```
335 | 
336 | > **Note:** Need to create a button element? Try the *button* method. It has the same signature as *submit*.
337 | 
338 | <a name="custom-macros"></a>
339 | ## Custom Macros
340 | 
341 | #### Registering A Form Macro
342 | 
343 | It's easy to define your own custom Form class helpers called "macros". Here's how it works. First, simply register the macro with a given name and a Closure:
344 | 
345 | ```php
346 | Form::macro('myField', function()
347 | {
348 | 	return '<input type="awesome">';
349 | });
350 | ```
351 | 
352 | Now you can call your macro using its name:
353 | 
354 | #### Calling A Custom Form Macro
355 | 
356 | ```php
357 | echo Form::myField();
358 | ```
359 | 
360 | <a name="custom-components"></a>
361 | ##Custom Components
362 | 
363 | #### Registering A Custom Component
364 | 
365 | Custom Components are similar to Custom Macros, however instead of using a closure to generate the resulting HTML, Components utilize [Laravel Blade Templates](http://laravel.com/docs/5.2/blade). Components can be incredibly useful for developers who use [Twitter Bootstrap](http://getbootstrap.com/), or any other front-end framework, which requires additional markup to properly render forms.
366 | 
367 | Let's build a Form Component for a simple Bootstrap text input. You might consider registering your Components inside a Service Provider's `boot` method.
368 | 
369 | ```php
370 | Form::component('bsText', 'components.form.text', ['name', 'value', 'attributes']);
371 | ```
372 | 
373 | Notice how we reference a view path of `components.form.text`. Also, the array we provided is a sort of method signature for your Component. This defines the names of the variables that will be passed to your view. Your view might look something like this:
374 | 
375 | ```php
376 | // resources/views/components/form/text.blade.php
377 | <div class="form-group">
378 |     {{ Form::label($name, null, ['class' => 'control-label']) }}
379 |     {{ Form::text($name, $value, array_merge(['class' => 'form-control'], $attributes)) }}
380 | </div>
381 | ```
382 | 
383 | > Custom Components can also be created on the `Html` facade in the same fashion as on the `Form` facade.
384 | 
385 | ##### Providing Default Values
386 | 
387 | When defining your Custom Component's method signature, you can provide default values simply by giving your array items values, like so:
388 | 
389 | ```php
390 | Form::component('bsText', 'components.form.text', ['name', 'value' => null, 'attributes' => []]);
391 | ```
392 | 
393 | #### Calling A Custom Form Component
394 | 
395 | Using our example from above (specifically, the one with default values provided), you can call your Custom Component like so:
396 | 
397 | ```php
398 | {{ Form::bsText('first_name') }}
399 | ```
400 | 
401 | This would result in something like the following HTML output:
402 | 
403 | ```php
404 | <div class="form-group">
405 |     <label for="first_name">First Name</label>
406 |     <input type="text" name="first_name" value="" class="form-control">
407 | </div>
408 | ```
409 | 
410 | <a name="generating-urls"></a>
411 | ##Generating URLs
412 | 
413 | #### link_to
414 | 
415 | Generate a HTML link to the given URL.
416 | 
417 | ```php
418 | echo link_to('foo/bar', $title = null, $attributes = [], $secure = null);
419 | ```
420 | 
421 | #### link_to_asset
422 | 
423 | Generate a HTML link to the given asset.
424 | 
425 | ```php
426 | echo link_to_asset('foo/bar.zip', $title = null, $attributes = [], $secure = null);
427 | ```
428 | 
429 | #### link_to_route
430 | 
431 | Generate a HTML link to the given named route.
432 | 
433 | ```php
434 | echo link_to_route('route.name', $title = null, $parameters = [], $attributes = []);
435 | ```
436 | 
437 | #### link_to_action
438 | 
439 | Generate a HTML link to the given controller action.
440 | 
441 | ```php
442 | echo link_to_action('HomeController@getIndex', $title = null, $parameters = [], $attributes = []);
443 | ```
444 | 
445 | #### mailto
446 | 
447 | Generate a HTML link to the given email address. **Note:** this obfuscates the email address to prevent spam-bots from sniffing it using the `email` method also provide with this package.
448 | 
449 | ```php
450 | echo mailto('foo@bar.baz', $title = null, $attributes = [], $escape = true);
451 | ```
452 | 


--------------------------------------------------------------------------------
/readme.md:
--------------------------------------------------------------------------------
1 | ![LaravelCollective Docs](LaravelCollectiveDocs-banner.png)
2 | 
3 | Please feel free to contribute to the docs. If you wish to issue a Pull-Request please make sure you compare the PR to the version of the docs you wish to update.


--------------------------------------------------------------------------------
/ssh.md:
--------------------------------------------------------------------------------
  1 | # SSH
  2 | 
  3 | - [Installation](#installation)
  4 | - [Configuration](#configuration)
  5 | - [Basic Usage](#basic-usage)
  6 | - [Tasks](#tasks)
  7 | - [SFTP Downloads](#sftp-downloads)
  8 | - [SFTP Uploads](#sftp-uploads)
  9 | - [Tailing Remote Logs](#tailing-remote-logs)
 10 | 
 11 | <a name="installation"></a>
 12 | ## Installation
 13 | 
 14 | > If you have changed the top-level namespace to something like 'MyCompany', then you would use the new namespace instead of 'App'.
 15 | 
 16 | Begin by installing this package through Composer.
 17 | 
 18 | ```
 19 | $ composer require laravelcollective/remote
 20 | ```
 21 | 
 22 | Finally, publish the config file:
 23 | 
 24 | ```php
 25 |   php artisan vendor:publish --provider="Collective\Remote\RemoteServiceProvider"
 26 | ```
 27 | <a name="configuration"></a>
 28 | ## Configuration
 29 | 
 30 | Laravel includes a simple way to SSH into remote servers and run commands, allowing you to easily build Artisan tasks that work on remote servers. The `SSH` facade provides the access point to connecting to your remote servers and running commands.
 31 | 
 32 | The configuration file is located at `config/remote.php`, and contains all of the options you need to configure your remote connections. The `connections` array contains a list of your servers keyed by name. Simply populate the credentials in the `connections` array and you will be ready to start running remote tasks. Note that the `SSH` can authenticate using either a password or an SSH key.
 33 | 
 34 | > **Note:** Need to easily run a variety of tasks on your remote server? Check out the [Envoy task runner](http://laravel.com/docs/5.3/envoy)!
 35 | 
 36 | <a name="basic-usage"></a>
 37 | ## Basic Usage
 38 | 
 39 | #### Running Commands On The Default Server
 40 | 
 41 | To run commands on your `default` remote connection, use the `SSH::run` method:
 42 | 
 43 | 	SSH::run([
 44 | 		'cd /var/www',
 45 | 		'git pull origin master',
 46 | 	]);
 47 | 
 48 | #### Running Commands On A Specific Connection
 49 | 
 50 | Alternatively, you may run commands on a specific connection using the `into` method:
 51 | 
 52 | 	SSH::into('staging')->run([
 53 | 		'cd /var/www',
 54 | 		'git pull origin master',
 55 | 	]);
 56 | 
 57 | #### Catching Output From Commands
 58 | 
 59 | You may catch the "live" output of your remote commands by passing a Closure into the `run` method:
 60 | 
 61 | 	SSH::run($commands, function($line)
 62 | 	{
 63 | 		echo $line.PHP_EOL;
 64 | 	});
 65 | 
 66 | ## Tasks
 67 | <a name="tasks"></a>
 68 | 
 69 | If you need to define a group of commands that should always be run together, you may use the `define` method to define a `task`:
 70 | 
 71 | 	SSH::into('staging')->define('deploy', [
 72 | 		'cd /var/www',
 73 | 		'git pull origin master',
 74 | 		'php artisan migrate',
 75 | 	]);
 76 | 
 77 | Once the task has been defined, you may use the `task` method to run it:
 78 | 
 79 | 	SSH::into('staging')->task('deploy', function($line)
 80 | 	{
 81 | 		echo $line.PHP_EOL;
 82 | 	});
 83 | 
 84 | <a name="sftp-downloads"></a>
 85 | ## SFTP Downloads
 86 | 
 87 | The `SSH` class includes a simple way to download files using the `get` and `getString` methods:
 88 | 
 89 | 	SSH::into('staging')->get($remotePath, $localPath);
 90 | 
 91 | 	$contents = SSH::into('staging')->getString($remotePath);
 92 | 
 93 | <a name="sftp-uploads"></a>
 94 | ## SFTP Uploads
 95 | 
 96 | The `SSH` class also includes a simple way to upload files, or even strings, to the server using the `put` and `putString` methods:
 97 | 
 98 | 	SSH::into('staging')->put($localFile, $remotePath);
 99 | 
100 | 	SSH::into('staging')->putString($remotePath, 'Foo');
101 | 
102 | <a name="tailing-remote-logs"></a>
103 | ## Tailing Remote Logs
104 | 
105 | Laravel includes a helpful command for tailing the `laravel.log` files on any of your remote connections. Simply use the `tail` Artisan command and specify the name of the remote connection you would like to tail:
106 | 
107 | 	php artisan tail staging
108 | 
109 | 	php artisan tail staging --path=/path/to/log.file
110 | 


--------------------------------------------------------------------------------