working on artisan docs

Alanaktion · Jul 18, 2016 · 307e9f4 · 307e9f4
1 parent b19da75
commit 307e9f4
Showing 1 changed file with 70 additions and 41 deletions.
diff --git a/artisan.md b/artisan.md
@@ -2,19 +2,26 @@
 
 - [Introduction](#introduction)
 - [Writing Commands](#writing-commands)
+    - [Generating Commands](#generating-commands)
     - [Command Structure](#command-structure)
+- [Defining Input Expectations](#defining-input-expectations)
+    - [Arguments](#arguments)
+    - [Options](#options)
+    - [Input Arrays](#input-arrays)
+    - [Input Descriptions](#input-descriptions)
 - [Command I/O](#command-io)
     - [Defining Input Expectations](#defining-input-expectations)
     - [Retrieving Input](#retrieving-input)
     - [Prompting For Input](#prompting-for-input)
     - [Writing Output](#writing-output)
 - [Registering Commands](#registering-commands)
-- [Calling Commands Via Code](#calling-commands-via-code)
+- [Programatically Executing Commands](#programatically-executing-commands)
+    - [Calling Commands From Other Commands](#calling-commands-from-other-commands)
 
 <a name="introduction"></a>
 ## Introduction
 
-Artisan is the name of the command-line interface included with Laravel. It provides a number of helpful commands for your use while developing your application. It is driven by the powerful Symfony Console component. To view a list of all available Artisan commands, you may use the `list` command:
+Artisan is the command-line interface included with Laravel. It provides a number of helpful commands that can assist you while you build your application. To view a list of all available Artisan commands, you may use the `list` command:
 
     php artisan list
 
@@ -25,24 +32,23 @@ Every command also includes a "help" screen which displays and describes the com
 <a name="writing-commands"></a>
 ## Writing Commands
 
-In addition to the commands provided with Artisan, you may also build your own custom commands for working with your application. You may store your custom commands in the `app/Console/Commands` directory; however, you are free to choose your own storage location as long as your commands can be autoloaded based on your `composer.json` settings.
+In addition to the commands provided with Artisan, you may also build your own custom commands. Commands are typically stored in the `app/Console/Commands` directory; however, you are free to choose your own storage location as long as your commands can be loaded by Composer.
 
-To create a new command, you may use the `make:command` Artisan command, which will generate a command stub to help you get started:
+<a name="generating-commands"></a>
+### Generating Commands
 
-    php artisan make:command SendEmails
-
-The command above would generate a class at `app/Console/Commands/SendEmails.php`. When creating the command, the `--command` option may be used to assign the terminal command name:
+To create a new command, use the `make:command` Artisan command. This command will create a new command class in the `app/Console/Commands` directory. The generated command will include the default set of properties and methods that are present on all commands:
 
-    php artisan make:command SendEmails --command=emails:send
+    php artisan make:command SendEmails
 
 <a name="command-structure"></a>
 ### Command Structure
 
-Once your command is generated, you should fill out the `signature` and `description` properties of the class, which will be used when displaying your command on the `list` screen.
+After generating your command, you should fill in the `signature` and `description` properties of the class, which will be used when displaying your command on the `list` screen. The `handle` method will be called when your command is executed. You may place your command logic in this method.
 
-The `handle` method will be called when your command is executed. You may place any command logic in this method. Let's take a look at an example command.
+> {tip} For greater code reuse, it is good practice to keep your console commands light and let them defer to application services to accomplish their tasks. In the example below, note that we inject a service class to do the "heavy lifting" of sending the e-mails.
 
-Note that we are able to inject any dependencies we need into the command's constructor. The Laravel [service container](/docs/{{version}}/container) will automatically inject all dependencies type-hinted in the constructor. For greater code reusability, it is good practice to keep your console commands light and let them defer to application services to accomplish their tasks.
+Let's take a look at an example command. Note that we are able to inject any dependencies we need into the command's constructor. The Laravel [service container](/docs/{{version}}/container) will automatically inject all dependencies type-hinted in the constructor:
 
     <?php
 
@@ -99,14 +105,14 @@ Note that we are able to inject any dependencies we need into the command's cons
         }
     }
 
-<a name="command-io"></a>
-## Command I/O
-
 <a name="defining-input-expectations"></a>
-### Defining Input Expectations
+## Defining Input Expectations
 
 When writing console commands, it is common to gather input from the user through arguments or options. Laravel makes it very convenient to define the input you expect from the user using the `signature` property on your commands. The `signature` property allows you to define the name, arguments, and options for the command in a single, expressive, route-like syntax.
 
+<a name="arguments"></a>
+### Arguments
+
 All user supplied arguments and options are wrapped in curly braces. In the following example, the command defines one **required** argument: `user`:
 
     /**
@@ -116,15 +122,18 @@ All user supplied arguments and options are wrapped in curly braces. In the foll
      */
     protected $signature = 'email:send {user}';
 
-You may also make arguments optional and define default values for optional arguments:
+You may also make arguments optional and define default values for arguments:
 
     // Optional argument...
     email:send {user?}
 
     // Optional argument with default value...
     email:send {user=foo}
 
-Options, like arguments, are also a form of user input. However, they are prefixed by two hyphens (`--`) when they are specified on the command line. We can define options in the signature like so:
+<a name="options"></a>
+### Options
+
+Options, like arguments, are another form of user input. Options are prefixed by two hyphens (`--`) when they are specified on the command line. There are two types of options: those that receive a value and those that don't. Options that don't receive a value serve as a boolean "switch". Let's take a look at an example of this type of option:
 
     /**
      * The name and signature of the console command.
@@ -137,7 +146,10 @@ In this example, the `--queue` switch may be specified when calling the Artisan
 
     php artisan email:send 1 --queue
 
-You may also specify that the option should be assigned a value by the user by suffixing the option name with a `=` sign, indicating that a value should be provided:
+<a name="options-with-values"></a>
+#### Options With Values
+
+Next, let's take a look at an option that expects a value. If the user must specify a value for an option, suffix the option name with a `=` sign:
 
     /**
      * The name and signature of the console command.
@@ -150,23 +162,38 @@ In this example, the user may pass a value for the option like so:
 
     php artisan email:send 1 --queue=default
 
-You may also assign default values to options:
+You may assign default values to options by specifying the default value after the option name. If no option value is passed by the user, the default value will be used:
 
     email:send {user} {--queue=default}
 
+<a name="option-shortcuts"></a>
+#### Option Shortcuts
+
 To assign a shortcut when defining an option, you may specify it before the option name and use a | delimiter to separate the shortcut from the full option name:
 
     email:send {user} {--Q|queue}
 
-If you would like to define arguments or options to expect array inputs, you may use the `*` character:
+<a name="input-arrays"></a>
+### Input Arrays
+
+If you would like to define arguments or options to expect array inputs, you may use the `*` character. First, let's take a look at an example that specifies an array argument:
 
     email:send {user*}
 
+When calling this method, the `user` arguments may be passed in order to the command line. For example, the following command will set the value of `user` to `['foo', 'bar']`:
+
+    php artisan email:send foo bar
+
+When defining an option that expects an array input, each option value passed to the command should be prefixed with the option name:
+
     email:send {user} {--id=*}
 
-#### Input Descriptions
+    php artisan email:send --id=1 --id=2
 
-You may assign descriptions to input arguments and options by separating the parameter from the description using a colon:
+<a name="input-descriptions"></a>
+### Input Descriptions
+
+You may assign descriptions to input arguments and options by separating the parameter from the description using a colon. If you need a little extra room to define your command, feel free to spread the definition across multiple lines:
 
     /**
      * The name and signature of the console command.
@@ -177,6 +204,9 @@ You may assign descriptions to input arguments and options by separating the par
                             {user : The ID of the user}
                             {--queue= : Whether the job should be queued}';
 
+<a name="command-io"></a>
+## Command I/O
+
 <a name="retrieving-input"></a>
 ### Retrieving Input
 
@@ -194,17 +224,17 @@ While your command is executing, you will obviously need to access the values fo
         //
     }
 
-If you need to retrieve all of the arguments as an `array`, call `argument` with no parameters:
+If you need to retrieve all of the arguments as an `array`, call the `arguments` method:
 
-    $arguments = $this->argument();
+    $arguments = $this->arguments();
 
-Options may be retrieved just as easily as arguments using the `option` method. Like the `argument` method, you may call `option` without any parameters in order to retrieve all of the options as an `array`:
+Options may be retrieved just as easily as arguments using the `option` method. To retrieve all of the options as an array, call the `options` method:
 
     // Retrieve a specific option...
     $queueName = $this->option('queue');
 
     // Retrieve all options...
-    $options = $this->option();
+    $options = $this->options();
 
 If the argument or option does not exist, `null` will be returned.
 
@@ -235,22 +265,22 @@ If you need to ask the user for a simple confirmation, you may use the `confirm`
         //
     }
 
-#### Giving The User A Choice
+#### Auto-Completion
 
-The `anticipate` method can be used to provide autocompletion for possible choices. The user can still choose any answer, regardless of the auto-completion hints:
+The `anticipate` method can be used to provide auto-completion for possible choices. The user can still choose any answer, regardless of the auto-completion hints:
 
     $name = $this->anticipate('What is your name?', ['Taylor', 'Dayle']);
 
-If you need to give the user a predefined set of choices, you may use the `choice` method. The user chooses the index of the answer, but the value of the answer will be returned to you. You may set the default value to be returned if nothing is chosen:
+#### Multiple Choice Questions
+
+If you need to give the user a predefined set of choices, you may use the `choice` method. You may set the default value to be returned if no option is chosen:
 
     $name = $this->choice('What is your name?', ['Taylor', 'Dayle'], $default);
 
 <a name="writing-output"></a>
 ### Writing Output
 
-To send output to the console, use the `line`, `info`, `comment`, `question` and `error` methods. Each of these methods will use the appropriate ANSI colors for their purpose.
-
-To display an information message to the user, use the `info` method. Typically, this will display in the console as green text:
+To send output to the console, use the `line`, `info`, `comment`, `question` and `error` methods. Each of these methods will use appropriate ANSI colors for their purpose. For example, let's display some general information to the user. Typically, the `info` method will display in the console as green text:
 
     /**
      * Execute the console command.
@@ -266,7 +296,7 @@ To display an error message, use the `error` method. Error message text is typic
 
     $this->error('Something went wrong!');
 
-If you want to display plain console output, use the `line` method. The `line` method does not receive any unique coloration:
+If you would like to display plain, uncolored console output, use the `line` method:
 
     $this->line('Display this on the screen');
 
@@ -282,7 +312,7 @@ The `table` method makes it easy to correctly format multiple rows / columns of
 
 #### Progress Bars
 
-For long running tasks, it could be helpful to show a progress indicator. Using the output object, we can start, advance and stop the Progress Bar. You have to define the number of steps when you start the progress, then advance the Progress Bar after each step:
+For long running tasks, it could be helpful to show a progress indicator. Using the output object, we can start, advance and stop the Progress Bar. First, define the total number of steps the process will iterate through. Then, advance the Progress Bar after processing each item:
 
     $users = App\User::all();
 
@@ -301,16 +331,14 @@ For more advanced options, check out the [Symfony Progress Bar component documen
 <a name="registering-commands"></a>
 ## Registering Commands
 
-Once your command is finished, you need to register it with Artisan so it will be available for use. This is done within the `app/Console/Kernel.php` file.
-
-Within this file, you will find a list of commands in the `commands` property. To register your command, simply add the class name to the list. When Artisan boots, all the commands listed in this property will be resolved by the [service container](/docs/{{version}}/container) and registered with Artisan:
+Once your command is finished, you need to register it with Artisan. All commands are registered in the `app/Console/Kernel.php` file. Within this file, you will find a list of commands in the `commands` property. To register your command, simply add the command's class name to the list. When Artisan boots, all the commands listed in this property will be resolved by the [service container](/docs/{{version}}/container) and registered with Artisan:
 
     protected $commands = [
         Commands\SendEmails::class
     ];
 
-<a name="calling-commands-via-code"></a>
-## Calling Commands Via Code
+<a name="programatically-executing-commands"></a>
+## Programatically Executing Commands
 
 Sometimes you may wish to execute an Artisan command outside of the CLI. For example, you may wish to fire an Artisan command from a route or controller. You may use the `call` method on the `Artisan` facade to accomplish this. The `call` method accepts the name of the command as the first argument, and an array of command parameters as the second argument. The exit code will be returned:
 
@@ -322,7 +350,7 @@ Sometimes you may wish to execute an Artisan command outside of the CLI. For exa
         //
     });
 
-Using the `queue` method on the `Artisan` facade, you may even queue Artisan commands so they are processed in the background by your [queue workers](/docs/{{version}}/queues):
+Using the `queue` method on the `Artisan` facade, you may even queue Artisan commands so they are processed in the background by your [queue workers](/docs/{{version}}/queues). Before using this method, make sure you have configured your queue and are running a queue listener:
 
     Route::get('/foo', function () {
         Artisan::queue('email:send', [
@@ -332,12 +360,13 @@ Using the `queue` method on the `Artisan` facade, you may even queue Artisan com
         //
     });
 
-If you need to specify the value of an option that does not accept string values, such as the `--force` flag on the `migrate:refresh` command, you may pass a boolean `true` or `false`:
+If you need to specify the value of an option that does not accept string values, such as the `--force` flag on the `migrate:refresh` command, you may pass `true` or `false`:
 
     $exitCode = Artisan::call('migrate:refresh', [
         '--force' => true,
     ]);
 
+<a name="calling-commands-from-other-commands"></a>
 ### Calling Commands From Other Commands
 
 Sometimes you may wish to call other commands from an existing Artisan command. You may do so using the `call` method. This `call` method accepts the command name and an array of command parameters: