Skip to content

Commit

Permalink
[8.x] Improve linkability of docs by adding named anchors to h4 tags (l…
Browse files Browse the repository at this point in the history 
…aravel#6506)

* Add anchors to h4 tags

A selection of h4 tags already had anchor tags so this is really just
filling in the gaps (of which there is many!)

This makes it much easier to share a specific subsection of the docs in
blog posts, PRs, chat, etc.

* Fix existing duplicate anchor

* Add missing anchors for h3 tags
  • Loading branch information
@jessarcher
jessarcher authored Oct 20, 2020
1 parent 403f584 commit 6823f65
Show file tree
Hide file tree
Showing 66 changed files with 674 additions and 1 deletion.
13 changes: 13 additions & 0 deletions artisan.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@ Every command also includes a "help" screen which displays and describes the com

Laravel Tinker is a powerful REPL for the Laravel framework, powered by the [PsySH](https://github.com/bobthecow/psysh) package.

<a name="installation"></a>
#### Installation

All Laravel applications include Tinker by default. However, you may install it manually if needed using Composer:
Expand All @@ -45,6 +46,7 @@ All Laravel applications include Tinker by default. However, you may install it

> {tip} Looking for a graphical UI for interacting with your Laravel application? Check out [Tinkerwell](https://tinkerwell.app)!
<a name="usage"></a>
#### Usage

Tinker allows you to interact with your entire Laravel application on the command line, including the Eloquent ORM, jobs, events, and more. To enter the Tinker environment, run the `tinker` Artisan command:
Expand All @@ -57,6 +59,7 @@ You can publish Tinker's configuration file using the `vendor:publish` command:

> {note} The `dispatch` helper function and `dispatch` method on the `Dispatchable` class depends on garbage collection to place the job on the queue. Therefore, when using tinker, you should use `Bus::dispatch` or `Queue::push` to dispatch jobs.
<a name="command-whitelist"></a>
#### Command Whitelist

Tinker utilizes a white-list to determine which Artisan commands are allowed to be run within its shell. By default, you may run the `clear-compiled`, `down`, `env`, `inspire`, `migrate`, `optimize`, and `up` commands. If you would like to white-list more commands you may add them to the `commands` array in your `tinker.php` configuration file:
Expand All @@ -65,6 +68,7 @@ Tinker utilizes a white-list to determine which Artisan commands are allowed to
// App\Console\Commands\ExampleCommand::class,
],

<a name="classes-that-should-not-be-aliased"></a>
#### Classes That Should Not Be Aliased

Typically, Tinker automatically aliases classes as you require them in Tinker. However, you may wish to never alias some classes. You may accomplish this by listing the classes in the `dont_alias` array of your `tinker.php` configuration file:
Expand Down Expand Up @@ -163,6 +167,7 @@ Even though this file does not define HTTP routes, it defines console based entr

The Closure is bound to the underlying command instance, so you have full access to all of the helper methods you would typically be able to access on a full command class.

<a name="type-hinting-dependencies"></a>
#### Type-Hinting Dependencies

In addition to receiving your command's arguments and options, command Closures may also type-hint additional dependencies that you would like resolved out of the [service container](/docs/{{version}}/container):
Expand All @@ -174,6 +179,7 @@ In addition to receiving your command's arguments and options, command Closures
$drip->send(User::find($user));
});

<a name="closure-command-descriptions"></a>
#### Closure Command Descriptions

When defining a Closure based command, you may use the `describe` method to add a description to the command. This description will be displayed when you run the `php artisan list` or `php artisan help` commands:
Expand Down Expand Up @@ -334,6 +340,7 @@ The `secret` method is similar to `ask`, but the user's input will not be visibl

$password = $this->secret('What is the password?');

<a name="asking-for-confirmation"></a>
#### Asking For Confirmation

If you need to ask the user for a simple confirmation, you may use the `confirm` method. By default, this method will return `false`. However, if the user enters `y` or `yes` in response to the prompt, the method will return `true`.
Expand All @@ -342,6 +349,7 @@ If you need to ask the user for a simple confirmation, you may use the `confirm`
//
}

<a name="auto-completion"></a>
#### Auto-Completion

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:
Expand All @@ -354,6 +362,7 @@ Alternatively, you may pass a Closure as the second argument to the `anticipate`
// Return auto-completion options...
});

<a name="multiple-choice-questions"></a>
#### 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 array index of the default value to be returned if no option is chosen:
Expand Down Expand Up @@ -400,6 +409,7 @@ You may use the `newLine` method to display a blank line:
// Write three blank lines...
$this->newLine(3);

<a name="table-layouts"></a>
#### Table Layouts

The `table` method makes it easy to correctly format multiple rows / columns of data. Just pass in the headers and rows to the method. The width and height will be dynamically calculated based on the given data:
Expand All @@ -410,6 +420,7 @@ The `table` method makes it easy to correctly format multiple rows / columns of

$this->table($headers, $users);

<a name="progress-bars"></a>
#### 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. First, define the total number of steps the process will iterate through. Then, advance the Progress Bar after processing each item:
Expand Down Expand Up @@ -487,6 +498,7 @@ You may also specify the connection or queue the Artisan command should be dispa
'user' => 1, '--queue' => 'default'
])->onConnection('redis')->onQueue('commands');

<a name="passing-array-values"></a>
#### Passing Array Values

If your command defines an option that accepts an array, you may pass an array of values to that option:
Expand All @@ -497,6 +509,7 @@ If your command defines an option that accepts an array, you may pass an array o
]);
});

<a name="passing-boolean-values"></a>
#### Passing Boolean Values

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 should pass `true` or `false`:
Expand Down
18 changes: 18 additions & 0 deletions authentication.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@ Providers define how users are retrieved from your persistent storage. Laravel s

Don't worry if this all sounds confusing now! Many applications will never need to modify the default authentication configuration.

<a name="getting-started-fast"></a>
#### Getting Started Fast

Want to get started fast? Install [Laravel Jetstream](https://jetstream.laravel.com) in a fresh Laravel application. After migrating your database, navigate your browser to `/register` or any other URL that is assigned to your application. Jetstream will take care of scaffolding your entire authentication system!
Expand All @@ -62,6 +63,7 @@ First, consider how authentication works. When using a web browser, a user will

When a remote service needs to authenticate to access an API, cookies are not typically used because there is no web browser. Instead, the remote service sends an API token to the API on each request. The application may validate the incoming token against a table of valid API tokens and "authenticate" the request as being performed by the user associated with that API token.

<a name="laravels-built-in-browser-authentication-services"></a>
#### Laravel's Built-in Browser Authentication Services

Laravel includes built-in authentication and session services which are typically accessed via the `Auth` and `Session` facades. These features provide cookie based authentication for requests that are initiated from web browsers. They provide methods that allow you to verify a user's credentials and authenticate the user. In addition, these services will automatically store the proper data in the user's session and issue the proper session cookie. A discussion of how to use these services is contained within this documentation.
Expand All @@ -72,6 +74,7 @@ As discussed in this documentation, you can interact with these authentication s

Laravel Fortify is a headless authentication backend for Laravel that implements many of the features found in this documentation, including cookie-based authentication as well as other features such as two-factor authentication and email verification. Laravel Jetstream is a UI that consumes and exposes Fortify's authentication services with a beautiful, modern UI powered by [Tailwind CSS](https://tailwindcss.com), [Laravel Livewire](https://laravel-livewire.com), and / or [Inertia.js](https://inertiajs.com). Laravel Jetstream, in addition to offering browser-based cookie authentication, includes built-in integration with Laravel Sanctum to offer API token authentication. Laravel's API authentication offerings are discussed below.

<a name="laravels-api-authentication-services"></a>
#### Laravel's API Authentication Services

Laravel provides two optional packages to assist you in managing API tokens and authenticating requests made with API tokens: [Passport](/docs/{{version}}/passport) and [Sanctum](/docs/{{version}}/sanctum). Please note that these libraries and Laravel's built-in cookie based authentication libraries are not mutually exclusive. These libraries primarily focus on API token authentication while the built-in authentication services focus on cookie based browser authentication. Many applications will use both Laravel's built-in cookie based authentication services and one of Laravel's API authentication packages.
Expand All @@ -88,6 +91,7 @@ Laravel Sanctum is a hybrid web / API authentication package that can manage you

Laravel Sanctum is the API package we have chosen to include with the [Laravel Jetstream](https://jetstream.laravel.com) authentication scaffolding because we believe it is the best fit for the majority of web application's authentication needs.

<a name="summary-choosing-your-stack"></a>
#### Summary & Choosing Your Stack

In summary, if your application will be accessed using a browser, your application will use Laravel's built-in authentication services.
Expand Down Expand Up @@ -118,6 +122,7 @@ Laravel's `laravel/jetstream` package provides a quick way to scaffold all of th

This command should be used on fresh applications and will install a layout view, registration and login views, as well as routes for all authentication end-points. A `/dashboard` route will also be generated to handle post-login requests to your application's dashboard.

<a name="creating-applications-including-authentication"></a>
#### Creating Applications Including Authentication

If you are starting a brand new application and would like to include the authentication scaffolding, you may use the `--jet` directive when creating your application via the Laravel Installer. This command will create a new application with all of the authentication scaffolding compiled and installed:
Expand All @@ -138,6 +143,7 @@ Jetstream will also create a `resources/views/layouts` directory containing a ba

Now that your application has been scaffolded for authentication, you are ready to register and authenticate! You may simply access your application in a browser since Jetstream's authentication controllers already contain the logic to authenticate existing users and store new users in the database.

<a name="path-customization"></a>
#### Path Customization

When a user is successfully authenticated, they will typically be redirected to the `/home` URI. You can customize the post-authentication redirect path using the `HOME` constant defined in your `RouteServiceProvider`:
Expand Down Expand Up @@ -181,6 +187,7 @@ Alternatively, once a user is authenticated, you may access the authenticated us
}
}

<a name="determining-if-the-current-user-is-authenticated"></a>
#### Determining If The Current User Is Authenticated

To determine if the user is already logged into your application, you may use the `check` method on the `Auth` facade, which will return `true` if the user is authenticated:
Expand All @@ -202,6 +209,7 @@ To determine if the user is already logged into your application, you may use th
// Only authenticated users may enter...
})->middleware('auth');

<a name="redirecting-unauthenticated-users"></a>
#### Redirecting Unauthenticated Users

When the `auth` middleware detects an unauthorized user, it will redirect the user to the `login` [named route](/docs/{{version}}/routing#named-routes). You may modify this behavior by updating the `redirectTo` function in your `app/Http/Middleware/Authenticate.php` file:
Expand All @@ -217,6 +225,7 @@ When the `auth` middleware detects an unauthorized user, it will redirect the us
return route('login');
}

<a name="specifying-a-guard"></a>
#### Specifying A Guard

When attaching the `auth` middleware to a route, you may also specify which guard should be used to authenticate the user. The guard specified should correspond to one of the keys in the `guards` array of your `auth.php` configuration file:
Expand Down Expand Up @@ -272,6 +281,7 @@ The `attempt` method will return `true` if authentication was successful. Otherw

The `intended` method on the redirector will redirect the user to the URL they were attempting to access before being intercepted by the authentication middleware. A fallback URI may be given to this method in case the intended destination is not available.

<a name="specifying-additional-conditions"></a>
#### Specifying Additional Conditions

If you wish, you may also add extra conditions to the authentication query in addition to the user's e-mail and password. For example, we may verify that the user is marked as "active":
Expand All @@ -282,6 +292,7 @@ If you wish, you may also add extra conditions to the authentication query in ad

> {note} In these examples, `email` is not a required option, it is merely used as an example. You should use whatever column name corresponds to a "username" in your database.
<a name="accessing-specific-guard-instances"></a>
#### Accessing Specific Guard Instances

You may specify which guard instance you would like to utilize using the `guard` method on the `Auth` facade. This allows you to manage authentication for separate parts of your application using entirely separate authenticatable models or user tables.
Expand All @@ -292,6 +303,7 @@ The guard name passed to the `guard` method should correspond to one of the guar
//
}

<a name="manually-logging-out"></a>
#### Logging Out

To log users out of your application, you may use the `logout` method on the `Auth` facade. This will clear the authentication information in the user's session:
Expand All @@ -316,6 +328,7 @@ If you are "remembering" users, you may use the `viaRemember` method to determin
<a name="other-authentication-methods"></a>
### Other Authentication Methods

<a name="authenticate-a-user-instance"></a>
#### Authenticate A User Instance

If you need to log an existing user instance into your application, you may call the `login` method with the user instance. The given object must be an implementation of the `Illuminate\Contracts\Auth\Authenticatable` [contract](/docs/{{version}}/contracts). The `App\Models\User` model included with Laravel already implements this interface. This method of authentication is useful when you already have a valid user instance, such as directly after a user registers with your application:
Expand All @@ -329,6 +342,7 @@ You may specify the guard instance you would like to use:

Auth::guard('admin')->login($user);

<a name="authenticate-a-user-by-id"></a>
#### Authenticate A User By ID

To log a user into the application by their ID, you may use the `loginUsingId` method. This method accepts the primary key of the user you wish to authenticate:
Expand All @@ -338,6 +352,7 @@ To log a user into the application by their ID, you may use the `loginUsingId` m
// Login and "remember" the given user...
Auth::loginUsingId(1, true);

<a name="authenticate-a-user-once"></a>
#### Authenticate A User Once

You may use the `once` method to log a user into the application for a single request. No sessions or cookies will be utilized, which means this method may be helpful when building a stateless API:
Expand All @@ -357,6 +372,7 @@ You may use the `once` method to log a user into the application for a single re

Once the middleware has been attached to the route, you will automatically be prompted for credentials when accessing the route in your browser. By default, the `auth.basic` middleware will use the `email` column on the user record as the "username".

<a name="a-note-on-fastcgi"></a>
#### A Note On FastCGI

If you are using PHP FastCGI, HTTP Basic authentication may not work correctly out of the box. The following lines should be added to your `.htaccess` file:
Expand Down Expand Up @@ -444,6 +460,7 @@ After confirming their password, a user will not be asked to confirm their passw
<a name="password-confirmation-routing"></a>
### Routing

<a name="the-password-confirmation-form"></a>
#### The Password Confirmation Form

First, we will define the route that is needed to display a view requesting that the user confirm their password:
Expand All @@ -454,6 +471,7 @@ First, we will define the route that is needed to display a view requesting that

As you might expect, the view that is returned by this route should have a form containing a `password` field. In addition, feel free to include text within the view that explains that the user is entering a protected area of the application and must confirm their password.

<a name="confirming-the-password"></a>
#### Confirming The Password

Next, we will define a route that will handle the form request from the "confirm password" view. This route will be responsible for validating the password and redirecting the user to their intended destination:
Expand Down
Loading

0 comments on commit 6823f65

Please sign in to comment.