| {{ $invoice->date()->toFormattedDateString() }} | -{{ $invoice->total() }} | -Download | -
| {{ $invoice->date()->toFormattedDateString() }} | +{{ $invoice->total() }} | +Download | +
+ {{ $value }}
+
+@endsession
+```
+
+
+#### Context Directives
+
+The `@context` directive may be used to determine if a [context](/docs/{{version}}/context) value exists. If the context value exists, the template contents within the `@context` and `@endcontext` directives will be evaluated. Within the `@context` directive's contents, you may echo the `$value` variable to display the context value:
+
+```blade
+@context('canonical')
+
+@endcontext
+```
+
### Switch Statements
@@ -336,9 +377,10 @@ In addition to conditional statements, Blade provides simple directives for work
@endwhile
```
-> {tip} While iterating through a `foreach` loop, you may use the [loop variable](#the-loop-variable) to gain valuable information about the loop, such as whether you are in the first or last iteration through the loop.
+> [!NOTE]
+> While iterating through a `foreach` loop, you may use the [loop variable](#the-loop-variable) to gain valuable information about the loop, such as whether you are in the first or last iteration through the loop.
-When using loops you may also end the loop or skip the current iteration using the `@continue` and `@break` directives:
+When using loops you may also skip the current iteration or end the loop using the `@continue` and `@break` directives:
```blade
@foreach ($users as $user)
@@ -399,21 +441,25 @@ If you are in a nested loop, you may access the parent loop's `$loop` variable v
The `$loop` variable also contains a variety of other useful properties:
-Property | Description
-------------- | -------------
-`$loop->index` | The index of the current loop iteration (starts at 0).
-`$loop->iteration` | The current loop iteration (starts at 1).
-`$loop->remaining` | The iterations remaining in the loop.
-`$loop->count` | The total number of items in the array being iterated.
-`$loop->first` | Whether this is the first iteration through the loop.
-`$loop->last` | Whether this is the last iteration through the loop.
-`$loop->even` | Whether this is an even iteration through the loop.
-`$loop->odd` | Whether this is an odd iteration through the loop.
-`$loop->depth` | The nesting level of the current loop.
-`$loop->parent` | When in a nested loop, the parent's loop variable.
+
+
+| Property | Description |
+| ------------------ | ------------------------------------------------------ |
+| `$loop->index` | The index of the current loop iteration (starts at 0). |
+| `$loop->iteration` | The current loop iteration (starts at 1). |
+| `$loop->remaining` | The iterations remaining in the loop. |
+| `$loop->count` | The total number of items in the array being iterated. |
+| `$loop->first` | Whether this is the first iteration through the loop. |
+| `$loop->last` | Whether this is the last iteration through the loop. |
+| `$loop->even` | Whether this is an even iteration through the loop. |
+| `$loop->odd` | Whether this is an odd iteration through the loop. |
+| `$loop->depth` | The nesting level of the current loop. |
+| `$loop->parent` | When in a nested loop, the parent's loop variable. |
+
+
-### Conditional Classes
+### Conditional Classes & Styles
The `@class` directive conditionally compiles a CSS class string. The directive accepts an array of classes where the array key contains the class or classes you wish to add, while the value is a boolean expression. If the array element has a numeric key, it will always be included in the rendered class list:
@@ -433,16 +479,33 @@ The `@class` directive conditionally compiles a CSS class string. The directive
```
-
-### Checked / Selected / Disabled
+Likewise, the `@style` directive may be used to conditionally add inline CSS styles to an HTML element:
+
+```blade
+@php
+ $isActive = true;
+@endphp
+
+ $isActive,
+])>
+
+
+```
+
+
+### Additional Attributes
For convenience, you may use the `@checked` directive to easily indicate if a given HTML checkbox input is "checked". This directive will echo `checked` if the provided condition evaluates to `true`:
```blade
-active)) />
+active))
+/>
```
Likewise, the `@selected` directive may be used to indicate if a given select option should be "selected":
@@ -463,10 +526,33 @@ Additionally, the `@disabled` directive may be used to indicate if a given eleme
```
+Moreover, the `@readonly` directive may be used to indicate if a given element should be "readonly":
+
+```blade
+isNotAdmin())
+/>
+```
+
+In addition, the `@required` directive may be used to indicate if a given element should be "required":
+
+```blade
+isAdmin())
+/>
+```
+
### Including Subviews
-> {tip} While you're free to use the `@include` directive, Blade [components](#components) provide similar functionality and offer several benefits over the `@include` directive such as data and attribute binding.
+> [!NOTE]
+> While you're free to use the `@include` directive, Blade [components](#components) provide similar functionality and offer several benefits over the `@include` directive such as data and attribute binding.
Blade's `@include` directive allows you to include a Blade view from within another view. All variables that are available to the parent view will be made available to the included view:
@@ -506,10 +592,11 @@ To include the first view that exists from a given array of views, you may use t
@includeFirst(['custom.admin', 'admin'], ['status' => 'complete'])
```
-> {note} You should avoid using the `__DIR__` and `__FILE__` constants in your Blade views, since they will refer to the location of the cached, compiled view.
+> [!WARNING]
+> You should avoid using the `__DIR__` and `__FILE__` constants in your Blade views, since they will refer to the location of the cached, compiled view.
-#### Rendering Views For Collections
+#### Rendering Views for Collections
You may combine loops and includes into one line with Blade's `@each` directive:
@@ -525,7 +612,8 @@ You may also pass a fourth argument to the `@each` directive. This argument dete
@each('view.name', $jobs, 'job', 'view.empty')
```
-> {note} Views rendered via `@each` do not inherit the variables from the parent view. If the child view requires these variables, you should use the `@foreach` and `@include` directives instead.
+> [!WARNING]
+> Views rendered via `@each` do not inherit the variables from the parent view. If the child view requires these variables, you should use the `@foreach` and `@include` directives instead.
### The `@once` Directive
@@ -552,6 +640,20 @@ Since the `@once` directive is often used in conjunction with the `@push` or `@p
@endPushOnce
```
+If you are pushing duplicate content from two separate Blade templates, you should provide a unique identifier as the second argument to the `@pushOnce` directive to ensure the content is only rendered once:
+
+```blade
+
+@pushOnce('scripts', 'chart.js')
+
+@endPushOnce
+
+
+@pushOnce('scripts', 'chart.js')
+
+@endPushOnce
+```
+
### Raw PHP
@@ -563,6 +665,45 @@ In some situations, it's useful to embed PHP code into your views. You can use t
@endphp
```
+Or, if you only need to use PHP to import a class, you may use the `@use` directive:
+
+```blade
+@use('App\Models\Flight')
+```
+
+A second argument may be provided to the `@use` directive to alias the imported class:
+
+```blade
+@use('App\Models\Flight', 'FlightModel')
+```
+
+If you have multiple classes within the same namespace, you may group the imports of those classes:
+
+```blade
+@use('App\Models\{Flight, Airport}')
+```
+
+The `@use` directive also supports importing PHP functions and constants by prefixing the import path with the `function` or `const` modifiers:
+
+```blade
+@use(function App\Helpers\format_currency)
+@use(const App\Constants\MAX_ATTEMPTS)
+```
+
+Just like class imports, aliases are supported for functions and constants as well:
+
+```blade
+@use(function App\Helpers\format_currency, 'formatMoney')
+@use(const App\Constants\MAX_ATTEMPTS, 'MAX_TRIES')
+```
+
+Grouped imports are also supported with both function and const modifiers, allowing you to import multiple symbols from the same namespace in a single directive:
+
+```blade
+@use(function App\Helpers\{format_currency, format_date})
+@use(const App\Constants\{MAX_ATTEMPTS, DEFAULT_TIMEOUT})
+```
+
### Comments
@@ -575,9 +716,9 @@ Blade also allows you to define comments in your views. However, unlike HTML com
## Components
-Components and slots provide similar benefits to sections, layouts, and includes; however, some may find the mental model of components and slots easier to understand. There are two approaches to writing components: class based components and anonymous components.
+Components and slots provide similar benefits to sections, layouts, and includes; however, some may find the mental model of components and slots easier to understand. There are two approaches to writing components: class-based components and anonymous components.
-To create a class based component, you may use the `make:component` Artisan command. To illustrate how to use components, we will create a simple `Alert` component. The `make:component` command will place the component in the `App\View\Components` directory:
+To create a class-based component, you may use the `make:component` Artisan command. To illustrate how to use components, we will create a simple `Alert` component. The `make:component` command will place the component in the `app/View/Components` directory:
```shell
php artisan make:component Alert
@@ -591,15 +732,7 @@ You may also create components within subdirectories:
php artisan make:component Forms/Input
```
-The command above will create an `Input` component in the `App\View\Components\Forms` directory and the view will be placed in the `resources/views/components/forms` directory.
-
-If you would like to create an anonymous component (a component with only a Blade template and no class), you may use the `--view` flag when invoking the `make:component` command:
-
-```shell
-php artisan make:component forms.input --view
-```
-
-The command above will create a Blade file at `resources/views/components/forms/input.blade.php` which can be rendered as a component via `Components content
';
- };
- }
+/**
+ * Get the view / contents that represent the component.
+ */
+public function render(): Closure
+{
+ return function () {
+ return 'Components content
';
+ };
+}
+```
+
+The closure returned by your component's `render` method may also receive a `$data` array as its only argument. This array will contain several elements that provide information about the component:
+
+```php
+return function (array $data) {
+ // $data['componentName'];
+ // $data['attributes'];
+ // $data['slot'];
+
+ return 'Components content
';
+}
+```
+
+> [!WARNING]
+> The elements in the `$data` array should never be directly embedded into the Blade string returned by your `render` method, as doing so could allow remote code execution via malicious attribute content.
The `componentName` is equal to the name used in the HTML tag after the `x-` prefix. So `All of the attributes are present
+@endif
+```
+
+The `hasAny` method may be used to determine if any of the given attributes are present on the component:
+
+```blade
+@if ($attributes->hasAny(['href', ':href', 'v-bind:href']))
+ One of the attributes is present
+@endif
+```
+
You may retrieve a specific attribute's value using the `get` method:
```blade
{{ $attributes->get('class') }}
```
+The `only` method may be used to retrieve only the attributes with the given keys:
+
+```blade
+{{ $attributes->only(['class']) }}
+```
+
+The `except` method may be used to retrieve all attributes except those with the given keys:
+
+```blade
+{{ $attributes->except(['class']) }}
+```
+
### Reserved Keywords
@@ -1021,6 +1221,7 @@ By default, some keywords are reserved for Blade's internal use in order to rend
- `data`
- `render`
+- `resolve`
- `resolveView`
- `shouldRender`
- `view`
@@ -1074,6 +1275,28 @@ You may define the content of the named slot using the `x-slot` tag. Any content
```
+You may invoke a slot's `isEmpty` method to determine if the slot contains content:
+
+```blade
+{{ $title }}
+
+
+ @if ($slot->isEmpty())
+ This is default content if the slot is empty.
+ @else
+ {{ $slot }}
+ @endif
+
+```
+
+Additionally, the `hasActualContent` method may be used to determine if the slot contains any "actual" content that is not an HTML comment:
+
+```blade
+@if ($slot->hasActualContent())
+ The scope has non-comment content.
+@endif
+```
+
#### Scoped Slots
@@ -1134,19 +1357,19 @@ To interact with slot attributes, you may access the `attributes` property of th
For very small components, it may feel cumbersome to manage both the component class and the component's view template. For this reason, you may return the component's markup directly from the `render` method:
- /**
- * Get the view / contents that represent the component.
- *
- * @return \Illuminate\View\View|\Closure|string
- */
- public function render()
- {
- return <<<'blade'
-
- {{ $slot }}
-
- blade;
- }
+```php
+/**
+ * Get the view / contents that represent the component.
+ */
+public function render(): string
+{
+ return <<<'blade'
+
+ {{ $slot }}
+
+ blade;
+}
+```
#### Generating Inline View Components
@@ -1157,8 +1380,73 @@ To create a component that renders an inline view, you may use the `inline` opti
php artisan make:component Alert --inline
```
+
+### Dynamic Components
+
+Sometimes you may need to render a component but not know which component should be rendered until runtime. In this situation, you may use Laravel's built-in `dynamic-component` component to render the component based on a runtime value or variable:
+
+```blade
+// $componentName = "secondary-button";
+
+{{ $task }}
@endforeach
{{ $task }}
@endforeach
```
Now that we have defined our layout and task list views, we just need to return the `task` view from a route:
- use App\Models\Task;
+```php
+use App\Models\Task;
- Route::get('/tasks', function () {
- return view('tasks', ['tasks' => Task::all()]);
- });
+Route::get('/tasks', function () {
+ return view('tasks', ['tasks' => Task::all()]);
+});
+```
### Layouts Using Template Inheritance
-#### Defining A Layout
+#### Defining a Layout
Layouts may also be created via "template inheritance". This was the primary way of building applications prior to the introduction of [components](#components).
@@ -1425,7 +1697,7 @@ As you can see, this file contains typical HTML mark-up. However, take note of t
Now that we have defined a layout for our application, let's define a child page that inherits the layout.
-#### Extending A Layout
+#### Extending a Layout
When defining a child view, use the `@extends` Blade directive to specify which layout the child view should "inherit". Views which extend a Blade layout may inject content into the layout's sections using `@section` directives. Remember, as seen in the example above, the contents of these sections will be displayed in the layout using `@yield`:
@@ -1449,7 +1721,8 @@ When defining a child view, use the `@extends` Blade directive to specify which
In this example, the `sidebar` section is utilizing the `@@parent` directive to append (rather than overwriting) content to the layout's sidebar. The `@@parent` directive will be replaced by the content of the layout when the view is rendered.
-> {tip} Contrary to the previous example, this `sidebar` section ends with `@endsection` instead of `@show`. The `@endsection` directive will only define a section while `@show` will define and **immediately yield** the section.
+> [!NOTE]
+> Contrary to the previous example, this `sidebar` section ends with `@endsection` instead of `@show`. The `@endsection` directive will only define a section while `@show` will define and **immediately yield** the section.
The `@yield` directive also accepts a default value as its second parameter. This value will be rendered if the section being yielded is undefined:
@@ -1496,9 +1769,11 @@ The `@error` directive may be used to quickly check if [validation error message
-
+ class="@error('title') is-invalid @enderror"
+/>
@error('title')
{{ $message }}
@@ -1512,9 +1787,11 @@ Since the `@error` directive compiles to an "if" statement, you may use the `@el
-
+ class="@error('email') is-invalid @else is-valid @enderror"
+/>
```
You may pass [the name of a specific error bag](/docs/{{version}}/validation#named-error-bags) as the second parameter to the `@error` directive to retrieve validation error messages on pages containing multiple forms:
@@ -1524,9 +1801,11 @@ You may pass [the name of a specific error bag](/docs/{{version}}/validation#nam
-
+ class="@error('email', 'login') is-invalid @enderror"
+/>
@error('email', 'login')
{{ $message }}
@@ -1544,6 +1823,14 @@ Blade allows you to push to named stacks which can be rendered somewhere else in
@endpush
```
+If you would like to `@push` content if a given boolean expression evaluates to `true`, you may use the `@pushIf` directive:
+
+```blade
+@pushIf($shouldPush, 'scripts')
+
+@endPushIf
+```
+
You may push to a stack as many times as needed. To render the complete stack contents, pass the name of the stack to the `@stack` directive:
```blade
@@ -1602,6 +1889,47 @@ return Blade::render(
);
```
+
+## Rendering Blade Fragments
+
+When using frontend frameworks such as [Turbo](https://turbo.hotwired.dev/) and [htmx](https://htmx.org/), you may occasionally need to only return a portion of a Blade template within your HTTP response. Blade "fragments" allow you to do just that. To get started, place a portion of your Blade template within `@fragment` and `@endfragment` directives:
+
+```blade
+@fragment('user-list')
+ -
+ @foreach ($users as $user)
+
- {{ $user->name }} + @endforeach +
+
+| Event Name |
+|----------------------------------------------|
+| `Illuminate\Cache\Events\CacheFlushed` |
+| `Illuminate\Cache\Events\CacheFlushing` |
+| `Illuminate\Cache\Events\CacheHit` |
+| `Illuminate\Cache\Events\CacheMissed` |
+| `Illuminate\Cache\Events\ForgettingKey` |
+| `Illuminate\Cache\Events\KeyForgetFailed` |
+| `Illuminate\Cache\Events\KeyForgotten` |
+| `Illuminate\Cache\Events\KeyWriteFailed` |
+| `Illuminate\Cache\Events\KeyWritten` |
+| `Illuminate\Cache\Events\RetrievingKey` |
+| `Illuminate\Cache\Events\RetrievingManyKeys` |
+| `Illuminate\Cache\Events\WritingKey` |
+| `Illuminate\Cache\Events\WritingManyKeys` |
+
+
+
+To increase performance, you may disable cache events by setting the `events` configuration option to `false` for a given cache store in your application's `config/cache.php` configuration file:
+
+```php
+'database' => [
+ 'driver' => 'database',
+ // ...
+ 'events' => false,
+],
+```
diff --git a/cashier-paddle.md b/cashier-paddle.md
index 939276c8da5..d0df4c60774 100644
--- a/cashier-paddle.md
+++ b/cashier-paddle.md
@@ -4,20 +4,26 @@
- [Upgrading Cashier](#upgrading-cashier)
- [Installation](#installation)
- [Paddle Sandbox](#paddle-sandbox)
- - [Database Migrations](#database-migrations)
- [Configuration](#configuration)
- [Billable Model](#billable-model)
- [API Keys](#api-keys)
- [Paddle JS](#paddle-js)
- [Currency Configuration](#currency-configuration)
- [Overriding Default Models](#overriding-default-models)
-- [Core Concepts](#core-concepts)
- - [Pay Links](#pay-links)
+- [Quickstart](#quickstart)
+ - [Selling Products](#quickstart-selling-products)
+ - [Selling Subscriptions](#quickstart-selling-subscriptions)
+- [Checkout Sessions](#checkout-sessions)
+ - [Overlay Checkout](#overlay-checkout)
- [Inline Checkout](#inline-checkout)
- - [User Identification](#user-identification)
-- [Prices](#prices)
+ - [Guest Checkouts](#guest-checkouts)
+- [Price Previews](#price-previews)
+ - [Customer Price Previews](#customer-price-previews)
+ - [Discounts](#price-discounts)
- [Customers](#customers)
- [Customer Defaults](#customer-defaults)
+ - [Retrieving Customers](#retrieving-customers)
+ - [Creating Customers](#creating-customers)
- [Subscriptions](#subscriptions)
- [Creating Subscriptions](#creating-subscriptions)
- [Checking Subscription Status](#checking-subscription-status)
@@ -25,30 +31,34 @@
- [Updating Payment Information](#updating-payment-information)
- [Changing Plans](#changing-plans)
- [Subscription Quantity](#subscription-quantity)
- - [Subscription Modifiers](#subscription-modifiers)
+ - [Subscriptions With Multiple Products](#subscriptions-with-multiple-products)
+ - [Multiple Subscriptions](#multiple-subscriptions)
- [Pausing Subscriptions](#pausing-subscriptions)
- - [Cancelling Subscriptions](#cancelling-subscriptions)
+ - [Canceling Subscriptions](#canceling-subscriptions)
- [Subscription Trials](#subscription-trials)
- [With Payment Method Up Front](#with-payment-method-up-front)
- [Without Payment Method Up Front](#without-payment-method-up-front)
+ - [Extend or Activate a Trial](#extend-or-activate-a-trial)
- [Handling Paddle Webhooks](#handling-paddle-webhooks)
- [Defining Webhook Event Handlers](#defining-webhook-event-handlers)
- [Verifying Webhook Signatures](#verifying-webhook-signatures)
- [Single Charges](#single-charges)
- - [Simple Charge](#simple-charge)
- - [Charging Products](#charging-products)
- - [Refunding Orders](#refunding-orders)
-- [Receipts](#receipts)
- - [Past & Upcoming Payments](#past-and-upcoming-payments)
-- [Handling Failed Payments](#handling-failed-payments)
+ - [Charging for Products](#charging-for-products)
+ - [Refunding Transactions](#refunding-transactions)
+ - [Crediting Transactions](#crediting-transactions)
+- [Transactions](#transactions)
+ - [Past and Upcoming Payments](#past-and-upcoming-payments)
- [Testing](#testing)
## Introduction
-[Laravel Cashier Paddle](https://github.com/laravel/cashier-paddle) provides an expressive, fluent interface to [Paddle's](https://paddle.com) subscription billing services. It handles almost all of the boilerplate subscription billing code you are dreading. In addition to basic subscription management, Cashier can handle: coupons, swapping subscription, subscription "quantities", cancellation grace periods, and more.
+> [!WARNING]
+> This documentation is for Cashier Paddle 2.x's integration with Paddle Billing. If you're still using Paddle Classic, you should use [Cashier Paddle 1.x](https://github.com/laravel/cashier-paddle/tree/1.x).
-While working with Cashier we recommend you also review Paddle's [user guides](https://developer.paddle.com/guides) and [API documentation](https://developer.paddle.com/api-reference/intro).
+[Laravel Cashier Paddle](https://github.com/laravel/cashier-paddle) provides an expressive, fluent interface to [Paddle's](https://paddle.com) subscription billing services. It handles almost all of the boilerplate subscription billing code you are dreading. In addition to basic subscription management, Cashier can handle: swapping subscriptions, subscription "quantities", subscription pausing, cancelation grace periods, and more.
+
+Before digging into Cashier Paddle, we recommend you also review Paddle's [concept guides](https://developer.paddle.com/concepts/overview) and [API documentation](https://developer.paddle.com/api-reference/overview).
## Upgrading Cashier
@@ -64,49 +74,33 @@ First, install the Cashier package for Paddle using the Composer package manager
composer require laravel/cashier-paddle
```
-> {note} To ensure Cashier properly handles all Paddle events, remember to [set up Cashier's webhook handling](#handling-paddle-webhooks).
-
-
-### Paddle Sandbox
-
-During local and staging development, you should [register a Paddle Sandbox account](https://developer.paddle.com/getting-started/sandbox). This account will give you a sandboxed environment to test and develop your applications without making actual payments. You may use Paddle's [test card numbers](https://developer.paddle.com/getting-started/sandbox#test-cards) to simulate various payment scenarios.
-
-When using the Paddle Sandbox environment, you should set the `PADDLE_SANDBOX` environment variable to `true` within your application's `.env` file:
+Next, you should publish the Cashier migration files using the `vendor:publish` Artisan command:
-```ini
-PADDLE_SANDBOX=true
+```shell
+php artisan vendor:publish --tag="cashier-migrations"
```
-After you have finished developing your application you may [apply for a Paddle vendor account](https://paddle.com). Before your application is placed into production, Paddle will need to approve your application's domain.
-
-
-### Database Migrations
-
-The Cashier service provider registers its own database migration directory, so remember to migrate your database after installing the package. The Cashier migrations will create a new `customers` table. In addition, a new `subscriptions` table will be created to store all of your customer's subscriptions. Finally, a new `receipts` table will be created to store all of your application's receipt information:
+Then, you should run your application's database migrations. The Cashier migrations will create a new `customers` table. In addition, new `subscriptions` and `subscription_items` tables will be created to store all of your customer's subscriptions. Lastly, a new `transactions` table will be created to store all of the Paddle transactions associated with your customers:
```shell
php artisan migrate
```
-If you need to overwrite the migrations that are included with Cashier, you can publish them using the `vendor:publish` Artisan command:
+> [!WARNING]
+> To ensure Cashier properly handles all Paddle events, remember to [set up Cashier's webhook handling](#handling-paddle-webhooks).
-```shell
-php artisan vendor:publish --tag="cashier-migrations"
-```
+
+### Paddle Sandbox
-If you would like to prevent Cashier's migrations from running entirely, you may use the `ignoreMigrations` provided by Cashier. Typically, this method should be called in the `register` method of your `AppServiceProvider`:
+During local and staging development, you should [register a Paddle Sandbox account](https://sandbox-login.paddle.com/signup). This account will give you a sandboxed environment to test and develop your applications without making actual payments. You may use Paddle's [test card numbers](https://developer.paddle.com/concepts/payment-methods/credit-debit-card#test-payment-method) to simulate various payment scenarios.
- use Laravel\Paddle\Cashier;
+When using the Paddle Sandbox environment, you should set the `PADDLE_SANDBOX` environment variable to `true` within your application's `.env` file:
- /**
- * Register any application services.
- *
- * @return void
- */
- public function register()
- {
- Cashier::ignoreMigrations();
- }
+```ini
+PADDLE_SANDBOX=true
+```
+
+After you have finished developing your application you may [apply for a Paddle vendor account](https://paddle.com). Before your application is placed into production, Paddle will need to approve your application's domain.
## Configuration
@@ -114,24 +108,28 @@ If you would like to prevent Cashier's migrations from running entirely, you may
### Billable Model
-Before using Cashier, you must add the `Billable` trait to your user model definition. This trait provides various methods to allow you to perform common billing tasks, such as creating subscriptions, applying coupons and updating payment method information:
+Before using Cashier, you must add the `Billable` trait to your user model definition. This trait provides various methods to allow you to perform common billing tasks, such as creating subscriptions and updating payment method information:
- use Laravel\Paddle\Billable;
+```php
+use Laravel\Paddle\Billable;
- class User extends Authenticatable
- {
- use Billable;
- }
+class User extends Authenticatable
+{
+ use Billable;
+}
+```
If you have billable entities that are not users, you may also add the trait to those classes:
- use Illuminate\Database\Eloquent\Model;
- use Laravel\Paddle\Billable;
+```php
+use Illuminate\Database\Eloquent\Model;
+use Laravel\Paddle\Billable;
- class Team extends Model
- {
- use Billable;
- }
+class Team extends Model
+{
+ use Billable;
+}
+```
### API Keys
@@ -139,14 +137,17 @@ If you have billable entities that are not users, you may also add the trait to
Next, you should configure your Paddle keys in your application's `.env` file. You can retrieve your Paddle API keys from the Paddle control panel:
```ini
-PADDLE_VENDOR_ID=your-paddle-vendor-id
-PADDLE_VENDOR_AUTH_CODE=your-paddle-vendor-auth-code
-PADDLE_PUBLIC_KEY="your-paddle-public-key"
+PADDLE_CLIENT_SIDE_TOKEN=your-paddle-client-side-token
+PADDLE_API_KEY=your-paddle-api-key
+PADDLE_RETAIN_KEY=your-paddle-retain-key
+PADDLE_WEBHOOK_SECRET="your-paddle-webhook-secret"
PADDLE_SANDBOX=true
```
The `PADDLE_SANDBOX` environment variable should be set to `true` when you are using [Paddle's Sandbox environment](#paddle-sandbox). The `PADDLE_SANDBOX` variable should be set to `false` if you are deploying your application to production and are using Paddle's live vendor environment.
+The `PADDLE_RETAIN_KEY` is optional and should only be set if you're using Paddle with [Retain](https://developer.paddle.com/concepts/retain/overview).
+
### Paddle JS
@@ -163,321 +164,577 @@ Paddle relies on its own JavaScript library to initiate the Paddle checkout widg
### Currency Configuration
-The default Cashier currency is United States Dollars (USD). You can change the default currency by defining a `CASHIER_CURRENCY` environment variable within your application's `.env` file:
-
-```ini
-CASHIER_CURRENCY=EUR
-```
-
-In addition to configuring Cashier's currency, you may also specify a locale to be used when formatting money values for display on invoices. Internally, Cashier utilizes [PHP's `NumberFormatter` class](https://www.php.net/manual/en/class.numberformatter.php) to set the currency locale:
+You can specify a locale to be used when formatting money values for display on invoices. Internally, Cashier utilizes [PHP's `NumberFormatter` class](https://www.php.net/manual/en/class.numberformatter.php) to set the currency locale:
```ini
CASHIER_CURRENCY_LOCALE=nl_BE
```
-> {note} In order to use locales other than `en`, ensure the `ext-intl` PHP extension is installed and configured on your server.
+> [!WARNING]
+> In order to use locales other than `en`, ensure the `ext-intl` PHP extension is installed and configured on your server.
### Overriding Default Models
You are free to extend the models used internally by Cashier by defining your own model and extending the corresponding Cashier model:
- use Laravel\Paddle\Subscription as CashierSubscription;
+```php
+use Laravel\Paddle\Subscription as CashierSubscription;
- class Subscription extends CashierSubscription
- {
- // ...
- }
+class Subscription extends CashierSubscription
+{
+ // ...
+}
+```
After defining your model, you may instruct Cashier to use your custom model via the `Laravel\Paddle\Cashier` class. Typically, you should inform Cashier about your custom models in the `boot` method of your application's `App\Providers\AppServiceProvider` class:
- use App\Models\Cashier\Receipt;
- use App\Models\Cashier\Subscription;
+```php
+use App\Models\Cashier\Subscription;
+use App\Models\Cashier\Transaction;
+
+/**
+ * Bootstrap any application services.
+ */
+public function boot(): void
+{
+ Cashier::useSubscriptionModel(Subscription::class);
+ Cashier::useTransactionModel(Transaction::class);
+}
+```
+
+
+## Quickstart
+
+
+### Selling Products
+
+> [!NOTE]
+> Before utilizing Paddle Checkout, you should define Products with fixed prices in your Paddle dashboard. In addition, you should [configure Paddle's webhook handling](#handling-paddle-webhooks).
+
+Offering product and subscription billing via your application can be intimidating. However, thanks to Cashier and [Paddle's Checkout Overlay](https://developer.paddle.com/concepts/sell/overlay-checkout), you can easily build modern, robust payment integrations.
+To charge customers for non-recurring, single-charge products, we'll utilize Cashier to charge customers with Paddle's Checkout Overlay, where they will provide their payment details and confirm their purchase. Once the payment has been made via the Checkout Overlay, the customer will be redirected to a success URL of your choosing within your application:
+
+```php
+use Illuminate\Http\Request;
+
+Route::get('/buy', function (Request $request) {
+ $checkout = $request->user()->checkout('pri_deluxe_album')
+ ->returnTo(route('dashboard'));
+
+ return view('buy', ['checkout' => $checkout]);
+})->name('checkout');
+```
+
+As you can see in the example above, we will utilize Cashier's provided `checkout` method to create a checkout object to present the customer the Paddle Checkout Overlay for a given "price identifier". When using Paddle, "prices" refer to [defined prices for specific products](https://developer.paddle.com/build/products/create-products-prices).
+
+If necessary, the `checkout` method will automatically create a customer in Paddle and connect that Paddle customer record to the corresponding user in your application's database. After completing the checkout session, the customer will be redirected to a dedicated success page where you can display an informational message to the customer.
+
+In the `buy` view, we will include a button to display the Checkout Overlay. The `paddle-button` Blade component is included with Cashier Paddle; however, you may also [manually render an overlay checkout](#manually-rendering-an-overlay-checkout):
+
+```html
+You are subscribed.
+@endif +``` + +We can even easily determine if a user is subscribed to specific product or price: + +```blade +@if ($user->subscribedToProduct('pro_basic')) +You are subscribed to our Basic product.
+@endif + +@if ($user->subscribedToPrice('price_basic_monthly')) +You are subscribed to our monthly Basic plan.
+@endif +``` + + +#### Building a Subscribed Middleware + +For convenience, you may wish to create a [middleware](/docs/{{version}}/middleware) which determines if the incoming request is from a subscribed user. Once this middleware has been defined, you may easily assign it to a route to prevent users that are not subscribed from accessing the route: + +```php +user()?->subscribed()) { + // Redirect user to billing page and ask them to subscribe... + return redirect('/subscribe'); + } + + return $next($request); + } +} +``` + +Once the middleware has been defined, you may assign it to a route: + +```php +use App\Http\Middleware\Subscribed; + +Route::get('/dashboard', function () { + // ... +})->middleware([Subscribed::class]); +``` + + +#### Allowing Customers to Manage Their Billing Plan + +Of course, customers may want to change their subscription plan to another product or "tier". In our example from above, we'd want to allow the customer to change their plan from a monthly subscription to a yearly subscription. For this you'll need to implement something like a button that leads to the below route: + +```php +use Illuminate\Http\Request; + +Route::put('/subscription/{price}/swap', function (Request $request, $price) { + $user->subscription()->swap($price); // With "$price" being "price_basic_yearly" for this example. + + return redirect()->route('dashboard'); +})->name('subscription.swap'); +``` + +Besides swapping plans you'll also need to allow your customers to cancel their subscription. Like swapping plans, provide a button that leads to the following route: + +```php +use Illuminate\Http\Request; + +Route::put('/subscription/cancel', function (Request $request, $price) { + $user->subscription()->cancel(); + + return redirect()->route('dashboard'); +})->name('subscription.cancel'); +``` + +And now your subscription will get canceled at the end of its billing period. + +> [!NOTE] +> As long as you have configured Cashier's webhook handling, Cashier will automatically keep your application's Cashier-related database tables in sync by inspecting the incoming webhooks from Paddle. So, for example, when you cancel a customer's subscription via Paddle's dashboard, Cashier will receive the corresponding webhook and mark the subscription as "canceled" in your application's database. + + +## Checkout Sessions + +Most operations to bill customers are performed using "checkouts" via Paddle's [Checkout Overlay widget](https://developer.paddle.com/build/checkout/build-overlay-checkout) or by utilizing [inline checkout](https://developer.paddle.com/build/checkout/build-branded-inline-checkout). + +Before processing checkout payments using Paddle, you should define your application's [default payment link](https://developer.paddle.com/build/transactions/default-payment-link#set-default-link) in your Paddle checkout settings dashboard. + + +### Overlay Checkout + +Before displaying the Checkout Overlay widget, you must generate a checkout session using Cashier. A checkout session will inform the checkout widget of the billing operation that should be performed: + +```php +use Illuminate\Http\Request; + +Route::get('/buy', function (Request $request) { + $checkout = $user->checkout('pri_34567') + ->returnTo(route('dashboard')); + + return view('billing', ['checkout' => $checkout]); +}); +``` + +Cashier includes a `paddle-button` [Blade component](/docs/{{version}}/blade#components). You may pass the checkout session to this component as a "prop". Then, when this button is clicked, Paddle's checkout widget will be displayed: ```html --
- @foreach ($prices as $price)
-
- {{ $price->product_title }} - {{ $price->price()->gross() }} - @endforeach -
-
@foreach ($prices as $price)
-
- {{ $price->product_title }} - {{ $price->price()->net() }} (+ {{ $price->price()->tax() }} tax) +
- {{ $price->product['name'] }} - {{ $price->total() }} @endforeach
-
@foreach ($prices as $price)
-
- {{ $price->product_title }} - Initial: {{ $price->initialPrice()->gross() }} - Recurring: {{ $price->recurringPrice()->gross() }} +
- {{ $price->product['name'] }} - {{ $price->subtotal() }} (+ {{ $price->tax() }} tax) @endforeach
-
- @foreach ($prices as $price)
-
- {{ $price->product_title }} - {{ $price->price()->gross() }} - @endforeach -
-
@foreach ($prices as $price)
-
- {{ $price->product_title }} - {{ $price->listPrice()->gross() }} +
- {{ $price->product['name'] }} - {{ $price->total() }} @endforeach
-- `Laravel\Paddle\Events\PaymentSucceeded`
-- `Laravel\Paddle\Events\SubscriptionPaymentSucceeded`
+- `Laravel\Paddle\Events\CustomerUpdated`
+- `Laravel\Paddle\Events\TransactionCompleted`
+- `Laravel\Paddle\Events\TransactionUpdated`
- `Laravel\Paddle\Events\SubscriptionCreated`
- `Laravel\Paddle\Events\SubscriptionUpdated`
-- `Laravel\Paddle\Events\SubscriptionCancelled`
+- `Laravel\Paddle\Events\SubscriptionPaused`
+- `Laravel\Paddle\Events\SubscriptionCanceled`
@@ -1035,175 +1425,156 @@ CASHIER_WEBHOOK=https://example.com/my-paddle-webhook-url
### Verifying Webhook Signatures
-To secure your webhooks, you may use [Paddle's webhook signatures](https://developer.paddle.com/webhook-reference/verifying-webhooks). For convenience, Cashier automatically includes a middleware which validates that the incoming Paddle webhook request is valid.
+To secure your webhooks, you may use [Paddle's webhook signatures](https://developer.paddle.com/webhooks/signature-verification). For convenience, Cashier automatically includes a middleware which validates that the incoming Paddle webhook request is valid.
-To enable webhook verification, ensure that the `PADDLE_PUBLIC_KEY` environment variable is defined in your application's `.env` file. The public key may be retrieved from your Paddle account dashboard.
+To enable webhook verification, ensure that the `PADDLE_WEBHOOK_SECRET` environment variable is defined in your application's `.env` file. The webhook secret may be retrieved from your Paddle account dashboard.
## Single Charges
-
-### Simple Charge
+
+### Charging for Products
-If you would like to make a one-time charge against a customer, you may use the `charge` method on a billable model instance to generate a pay link for the charge. The `charge` method accepts the charge amount (float) as its first argument and a charge description as its second argument:
+If you would like to initiate a product purchase for a customer, you may use the `checkout` method on a billable model instance to generate a checkout session for the purchase. The `checkout` method accepts one or multiple price ID's. If necessary, an associative array may be used to provide the quantity of the product that is being purchased:
- use Illuminate\Http\Request;
+```php
+use Illuminate\Http\Request;
- Route::get('/store', function (Request $request) {
- return view('store', [
- 'payLink' => $user->charge(12.99, 'Action Figure')
- ]);
- });
+Route::get('/buy', function (Request $request) {
+ $checkout = $request->user()->checkout(['pri_tshirt', 'pri_socks' => 5]);
-After generating the pay link, you may use Cashier's provided `paddle-button` Blade component to allow the user to initiate the Paddle widget and complete the charge:
+ return view('buy', ['checkout' => $checkout]);
+});
+```
+
+After generating the checkout session, you may use Cashier's provided `paddle-button` [Blade component](#overlay-checkout) to allow the user to view the Paddle checkout widget and complete the purchase:
```blade
-| {{ $receipt->paid_at->toFormattedDateString() }} | -{{ $receipt->amount() }} | -Download | +{{ $transaction->billed_at->toFormattedDateString() }} | +{{ $transaction->total() }} | +{{ $transaction->tax() }} | +Download |
+
+ */
+ public function tags(): array
{
- /**
- * Get the tags that should be assigned to the job.
- *
- * @return array
- */
- public function tags()
- {
- return ['render', 'video:'.$this->video->id];
- }
+ return ['render', 'video:'.$this->video->id];
}
+}
+```
-
-## Notifications
-
-> {note} When configuring Horizon to send Slack or SMS notifications, you should review the [prerequisites for the relevant notification channel](/docs/{{version}}/notifications).
+
+#### Manually Tagging Event Listeners
-If you would like to be notified when one of your queues has a long wait time, you may use the `Horizon::routeMailNotificationsTo`, `Horizon::routeSlackNotificationsTo`, and `Horizon::routeSmsNotificationsTo` methods. You may call these methods from the `boot` method of your application's `App\Providers\HorizonServiceProvider`:
+When retrieving the tags for a queued event listener, Horizon will automatically pass the event instance to the `tags` method, allowing you to add event data to the tags:
+```php
+class SendRenderNotifications implements ShouldQueue
+{
/**
- * Bootstrap any application services.
+ * Get the tags that should be assigned to the listener.
*
- * @return void
+ * @return array
*/
- public function boot()
+ public function tags(VideoRendered $event): array
{
- parent::boot();
-
- Horizon::routeSmsNotificationsTo('15556667777');
- Horizon::routeMailNotificationsTo('example@example.com');
- Horizon::routeSlackNotificationsTo('slack-webhook-url', '#channel');
+ return ['video:'.$event->video->id];
}
+}
+```
+
+
+## Notifications
+
+> [!WARNING]
+> When configuring Horizon to send Slack or SMS notifications, you should review the [prerequisites for the relevant notification channel](/docs/{{version}}/notifications).
+
+If you would like to be notified when one of your queues has a long wait time, you may use the `Horizon::routeMailNotificationsTo`, `Horizon::routeSlackNotificationsTo`, and `Horizon::routeSmsNotificationsTo` methods. You may call these methods from the `boot` method of your application's `App\Providers\HorizonServiceProvider`:
+
+```php
+/**
+ * Bootstrap any application services.
+ */
+public function boot(): void
+{
+ parent::boot();
+
+ Horizon::routeSmsNotificationsTo('15556667777');
+ Horizon::routeMailNotificationsTo('example@example.com');
+ Horizon::routeSlackNotificationsTo('slack-webhook-url', '#channel');
+}
+```
#### Configuring Notification Wait Time Thresholds
-You may configure how many seconds are considered a "long wait" within your application's `config/horizon.php` configuration file. The `waits` configuration option within this file allows you to control the long wait threshold for each connection / queue combination:
+You may configure how many seconds are considered a "long wait" within your application's `config/horizon.php` configuration file. The `waits` configuration option within this file allows you to control the long wait threshold for each connection / queue combination. Any undefined connection / queue combinations will default to a long wait threshold of 60 seconds:
- 'waits' => [
- 'redis:default' => 60,
- 'redis:critical,high' => 90,
- ],
+```php
+'waits' => [
+ 'redis:critical' => 30,
+ 'redis:default' => 60,
+ 'redis:batch' => 120,
+],
+```
+
+Setting a queue's threshold to `0` will disable long wait notifications for that queue.
## Metrics
-Horizon includes a metrics dashboard which provides information regarding your job and queue wait times and throughput. In order to populate this dashboard, you should configure Horizon's `snapshot` Artisan command to run every five minutes via your application's [scheduler](/docs/{{version}}/scheduling):
+Horizon includes a metrics dashboard which provides information regarding your job and queue wait times and throughput. In order to populate this dashboard, you should configure Horizon's `snapshot` Artisan command to run every five minutes in your application's `routes/console.php` file:
- /**
- * Define the application's command schedule.
- *
- * @param \Illuminate\Console\Scheduling\Schedule $schedule
- * @return void
- */
- protected function schedule(Schedule $schedule)
- {
- $schedule->command('horizon:snapshot')->everyFiveMinutes();
- }
+```php
+use Illuminate\Support\Facades\Schedule;
+
+Schedule::command('horizon:snapshot')->everyFiveMinutes();
+```
+
+If you would like to delete all metric data, you can invoke the `horizon:clear-metrics` Artisan command:
+
+```shell
+php artisan horizon:clear-metrics
+```
## Deleting Failed Jobs
@@ -388,6 +689,12 @@ If you would like to delete a failed job, you may use the `horizon:forget` comma
php artisan horizon:forget 5
```
+If you would like to delete all failed jobs, you may provide the `--all` option to the `horizon:forget` command:
+
+```shell
+php artisan horizon:forget --all
+```
+
## Clearing Jobs From Queues
diff --git a/http-client.md b/http-client.md
index 564e21ab1d7..9e9eb65328a 100644
--- a/http-client.md
+++ b/http-client.md
@@ -8,12 +8,16 @@
- [Timeout](#timeout)
- [Retries](#retries)
- [Error Handling](#error-handling)
+ - [Guzzle Middleware](#guzzle-middleware)
- [Guzzle Options](#guzzle-options)
- [Concurrent Requests](#concurrent-requests)
+ - [Request Pooling](#request-pooling)
+ - [Request Batching](#request-batching)
- [Macros](#macros)
- [Testing](#testing)
- [Faking Responses](#faking-responses)
- [Inspecting Requests](#inspecting-requests)
+ - [Preventing Stray Requests](#preventing-stray-requests)
- [Events](#events)
@@ -21,262 +25,620 @@
Laravel provides an expressive, minimal API around the [Guzzle HTTP client](http://docs.guzzlephp.org/en/stable/), allowing you to quickly make outgoing HTTP requests to communicate with other web applications. Laravel's wrapper around Guzzle is focused on its most common use cases and a wonderful developer experience.
-Before getting started, you should ensure that you have installed the Guzzle package as a dependency of your application. By default, Laravel automatically includes this dependency. However, if you have previously removed the package, you may install it again via Composer:
-
-```shell
-composer require guzzlehttp/guzzle
-```
-
## Making Requests
To make requests, you may use the `head`, `get`, `post`, `put`, `patch`, and `delete` methods provided by the `Http` facade. First, let's examine how to make a basic `GET` request to another URL:
- use Illuminate\Support\Facades\Http;
+```php
+use Illuminate\Support\Facades\Http;
- $response = Http::get('http://example.com/');
+$response = Http::get('http://example.com/');
+```
The `get` method returns an instance of `Illuminate\Http\Client\Response`, which provides a variety of methods that may be used to inspect the response:
- $response->body() : string;
- $response->json($key = null) : array|mixed;
- $response->object() : object;
- $response->collect($key = null) : Illuminate\Support\Collection;
- $response->status() : int;
- $response->ok() : bool;
- $response->successful() : bool;
- $response->redirect(): bool;
- $response->failed() : bool;
- $response->serverError() : bool;
- $response->clientError() : bool;
- $response->header($header) : string;
- $response->headers() : array;
+```php
+$response->body() : string;
+$response->json($key = null, $default = null) : mixed;
+$response->object() : object;
+$response->collect($key = null) : Illuminate\Support\Collection;
+$response->resource() : resource;
+$response->status() : int;
+$response->successful() : bool;
+$response->redirect(): bool;
+$response->failed() : bool;
+$response->clientError() : bool;
+$response->header($header) : string;
+$response->headers() : array;
+```
The `Illuminate\Http\Client\Response` object also implements the PHP `ArrayAccess` interface, allowing you to access JSON response data directly on the response:
- return Http::get('http://example.com/users/1')['name'];
+```php
+return Http::get('http://example.com/users/1')['name'];
+```
+
+In addition to the response methods listed above, the following methods may be used to determine if the response has a specific status code:
+
+```php
+$response->ok() : bool; // 200 OK
+$response->created() : bool; // 201 Created
+$response->accepted() : bool; // 202 Accepted
+$response->noContent() : bool; // 204 No Content
+$response->movedPermanently() : bool; // 301 Moved Permanently
+$response->found() : bool; // 302 Found
+$response->badRequest() : bool; // 400 Bad Request
+$response->unauthorized() : bool; // 401 Unauthorized
+$response->paymentRequired() : bool; // 402 Payment Required
+$response->forbidden() : bool; // 403 Forbidden
+$response->notFound() : bool; // 404 Not Found
+$response->requestTimeout() : bool; // 408 Request Timeout
+$response->conflict() : bool; // 409 Conflict
+$response->unprocessableEntity() : bool; // 422 Unprocessable Entity
+$response->tooManyRequests() : bool; // 429 Too Many Requests
+$response->serverError() : bool; // 500 Internal Server Error
+```
+
+
+#### URI Templates
+
+The HTTP client also allows you to construct request URLs using the [URI template specification](https://www.rfc-editor.org/rfc/rfc6570). To define the URL parameters that can be expanded by your URI template, you may use the `withUrlParameters` method:
+
+```php
+Http::withUrlParameters([
+ 'endpoint' => 'https://laravel.com/',
+ 'page' => 'docs',
+ 'version' => '12.x',
+ 'topic' => 'validation',
+])->get('{+endpoint}/{page}/{version}/{topic}');
+```
#### Dumping Requests
If you would like to dump the outgoing request instance before it is sent and terminate the script's execution, you may add the `dd` method to the beginning of your request definition:
- return Http::dd()->get('http://example.com/');
+```php
+return Http::dd()->get('http://example.com/');
+```
### Request Data
Of course, it is common when making `POST`, `PUT`, and `PATCH` requests to send additional data with your request, so these methods accept an array of data as their second argument. By default, data will be sent using the `application/json` content type:
- use Illuminate\Support\Facades\Http;
+```php
+use Illuminate\Support\Facades\Http;
- $response = Http::post('http://example.com/users', [
- 'name' => 'Steve',
- 'role' => 'Network Administrator',
- ]);
+$response = Http::post('http://example.com/users', [
+ 'name' => 'Steve',
+ 'role' => 'Network Administrator',
+]);
+```
#### GET Request Query Parameters
When making `GET` requests, you may either append a query string to the URL directly or pass an array of key / value pairs as the second argument to the `get` method:
- $response = Http::get('http://example.com/users', [
- 'name' => 'Taylor',
- 'page' => 1,
- ]);
+```php
+$response = Http::get('http://example.com/users', [
+ 'name' => 'Taylor',
+ 'page' => 1,
+]);
+```
+
+Alternatively, the `withQueryParameters` method may be used:
+
+```php
+Http::retry(3, 100)->withQueryParameters([
+ 'name' => 'Taylor',
+ 'page' => 1,
+])->get('http://example.com/users');
+```
#### Sending Form URL Encoded Requests
If you would like to send data using the `application/x-www-form-urlencoded` content type, you should call the `asForm` method before making your request:
- $response = Http::asForm()->post('http://example.com/users', [
- 'name' => 'Sara',
- 'role' => 'Privacy Consultant',
- ]);
+```php
+$response = Http::asForm()->post('http://example.com/users', [
+ 'name' => 'Sara',
+ 'role' => 'Privacy Consultant',
+]);
+```
-#### Sending A Raw Request Body
+#### Sending a Raw Request Body
You may use the `withBody` method if you would like to provide a raw request body when making a request. The content type may be provided via the method's second argument:
- $response = Http::withBody(
- base64_encode($photo), 'image/jpeg'
- )->post('http://example.com/photo');
+```php
+$response = Http::withBody(
+ base64_encode($photo), 'image/jpeg'
+)->post('http://example.com/photo');
+```
#### Multi-Part Requests
-If you would like to send files as multi-part requests, you should call the `attach` method before making your request. This method accepts the name of the file and its contents. If needed, you may provide a third argument which will be considered the file's filename:
+If you would like to send files as multi-part requests, you should call the `attach` method before making your request. This method accepts the name of the file and its contents. If needed, you may provide a third argument which will be considered the file's filename, while a fourth argument may be used to provide headers associated with the file:
- $response = Http::attach(
- 'attachment', file_get_contents('photo.jpg'), 'photo.jpg'
- )->post('http://example.com/attachments');
+```php
+$response = Http::attach(
+ 'attachment', file_get_contents('photo.jpg'), 'photo.jpg', ['Content-Type' => 'image/jpeg']
+)->post('http://example.com/attachments');
+```
Instead of passing the raw contents of a file, you may pass a stream resource:
- $photo = fopen('photo.jpg', 'r');
+```php
+$photo = fopen('photo.jpg', 'r');
- $response = Http::attach(
- 'attachment', $photo, 'photo.jpg'
- )->post('http://example.com/attachments');
+$response = Http::attach(
+ 'attachment', $photo, 'photo.jpg'
+)->post('http://example.com/attachments');
+```
### Headers
Headers may be added to requests using the `withHeaders` method. This `withHeaders` method accepts an array of key / value pairs:
- $response = Http::withHeaders([
- 'X-First' => 'foo',
- 'X-Second' => 'bar'
- ])->post('http://example.com/users', [
- 'name' => 'Taylor',
- ]);
+```php
+$response = Http::withHeaders([
+ 'X-First' => 'foo',
+ 'X-Second' => 'bar'
+])->post('http://example.com/users', [
+ 'name' => 'Taylor',
+]);
+```
You may use the `accept` method to specify the content type that your application is expecting in response to your request:
- $response = Http::accept('application/json')->get('http://example.com/users');
+```php
+$response = Http::accept('application/json')->get('http://example.com/users');
+```
For convenience, you may use the `acceptJson` method to quickly specify that your application expects the `application/json` content type in response to your request:
- $response = Http::acceptJson()->get('http://example.com/users');
+```php
+$response = Http::acceptJson()->get('http://example.com/users');
+```
+
+The `withHeaders` method merges new headers into the request's existing headers. If needed, you may replace all of the headers entirely using the `replaceHeaders` method:
+
+```php
+$response = Http::withHeaders([
+ 'X-Original' => 'foo',
+])->replaceHeaders([
+ 'X-Replacement' => 'bar',
+])->post('http://example.com/users', [
+ 'name' => 'Taylor',
+]);
+```
### Authentication
You may specify basic and digest authentication credentials using the `withBasicAuth` and `withDigestAuth` methods, respectively:
- // Basic authentication...
- $response = Http::withBasicAuth('taylor@laravel.com', 'secret')->post(...);
+```php
+// Basic authentication...
+$response = Http::withBasicAuth('taylor@laravel.com', 'secret')->post(/* ... */);
- // Digest authentication...
- $response = Http::withDigestAuth('taylor@laravel.com', 'secret')->post(...);
+// Digest authentication...
+$response = Http::withDigestAuth('taylor@laravel.com', 'secret')->post(/* ... */);
+```
#### Bearer Tokens
If you would like to quickly add a bearer token to the request's `Authorization` header, you may use the `withToken` method:
- $response = Http::withToken('token')->post(...);
+```php
+$response = Http::withToken('token')->post(/* ... */);
+```
### Timeout
-The `timeout` method may be used to specify the maximum number of seconds to wait for a response:
+The `timeout` method may be used to specify the maximum number of seconds to wait for a response. By default, the HTTP client will timeout after 30 seconds:
- $response = Http::timeout(3)->get(...);
+```php
+$response = Http::timeout(3)->get(/* ... */);
+```
If the given timeout is exceeded, an instance of `Illuminate\Http\Client\ConnectionException` will be thrown.
-You may specify the maximum number of seconds to wait while trying to connect to a server using the `connectTimeout` method:
+You may specify the maximum number of seconds to wait while trying to connect to a server using the `connectTimeout` method. The default is 10 seconds:
- $response = Http::connectTimeout(3)->get(...);
+```php
+$response = Http::connectTimeout(3)->get(/* ... */);
+```
### Retries
-If you would like HTTP client to automatically retry the request if a client or server error occurs, you may use the `retry` method. The `retry` method accepts the maximum number of times the request should be attempted and the number of milliseconds that Laravel should wait in between attempts:
+If you would like the HTTP client to automatically retry the request if a client or server error occurs, you may use the `retry` method. The `retry` method accepts the maximum number of times the request should be attempted and the number of milliseconds that Laravel should wait in between attempts:
+
+```php
+$response = Http::retry(3, 100)->post(/* ... */);
+```
+
+If you would like to manually calculate the number of milliseconds to sleep between attempts, you may pass a closure as the second argument to the `retry` method:
+
+```php
+use Exception;
+
+$response = Http::retry(3, function (int $attempt, Exception $exception) {
+ return $attempt * 100;
+})->post(/* ... */);
+```
+
+For convenience, you may also provide an array as the first argument to the `retry` method. This array will be used to determine how many milliseconds to sleep between subsequent attempts:
- $response = Http::retry(3, 100)->post(...);
+```php
+$response = Http::retry([100, 200])->post(/* ... */);
+```
If needed, you may pass a third argument to the `retry` method. The third argument should be a callable that determines if the retries should actually be attempted. For example, you may wish to only retry the request if the initial request encounters an `ConnectionException`:
- $response = Http::retry(3, 100, function ($exception) {
- return $exception instanceof ConnectionException;
- })->post(...);
+```php
+use Exception;
+use Illuminate\Http\Client\PendingRequest;
+
+$response = Http::retry(3, 100, function (Exception $exception, PendingRequest $request) {
+ return $exception instanceof ConnectionException;
+})->post(/* ... */);
+```
+
+If a request attempt fails, you may wish to make a change to the request before a new attempt is made. You can achieve this by modifying the request argument provided to the callable you provided to the `retry` method. For example, you might want to retry the request with a new authorization token if the first attempt returned an authentication error:
+
+```php
+use Exception;
+use Illuminate\Http\Client\PendingRequest;
+use Illuminate\Http\Client\RequestException;
+
+$response = Http::withToken($this->getToken())->retry(2, 0, function (Exception $exception, PendingRequest $request) {
+ if (! $exception instanceof RequestException || $exception->response->status() !== 401) {
+ return false;
+ }
+
+ $request->withToken($this->getNewToken());
+
+ return true;
+})->post(/* ... */);
+```
If all of the requests fail, an instance of `Illuminate\Http\Client\RequestException` will be thrown. If you would like to disable this behavior, you may provide a `throw` argument with a value of `false`. When disabled, the last response received by the client will be returned after all retries have been attempted:
- $response = Http::retry(3, 100, throw: false)->post(...);
+```php
+$response = Http::retry(3, 100, throw: false)->post(/* ... */);
+```
+
+> [!WARNING]
+> If all of the requests fail because of a connection issue, a `Illuminate\Http\Client\ConnectionException` will still be thrown even when the `throw` argument is set to `false`.
### Error Handling
Unlike Guzzle's default behavior, Laravel's HTTP client wrapper does not throw exceptions on client or server errors (`400` and `500` level responses from servers). You may determine if one of these errors was returned using the `successful`, `clientError`, or `serverError` methods:
- // Determine if the status code is >= 200 and < 300...
- $response->successful();
+```php
+// Determine if the status code is >= 200 and < 300...
+$response->successful();
- // Determine if the status code is >= 400...
- $response->failed();
+// Determine if the status code is >= 400...
+$response->failed();
- // Determine if the response has a 400 level status code...
- $response->clientError();
+// Determine if the response has a 400 level status code...
+$response->clientError();
- // Determine if the response has a 500 level status code...
- $response->serverError();
+// Determine if the response has a 500 level status code...
+$response->serverError();
- // Immediately execute the given callback if there was a client or server error...
- $response->onError(callable $callback);
+// Immediately execute the given callback if there was a client or server error...
+$response->onError(callable $callback);
+```
#### Throwing Exceptions
If you have a response instance and would like to throw an instance of `Illuminate\Http\Client\RequestException` if the response status code indicates a client or server error, you may use the `throw` or `throwIf` methods:
- $response = Http::post(...);
+```php
+use Illuminate\Http\Client\Response;
- // Throw an exception if a client or server error occurred...
- $response->throw();
+$response = Http::post(/* ... */);
- // Throw an exception if an error occurred and the given condition is true...
- $response->throwIf($condition);
+// Throw an exception if a client or server error occurred...
+$response->throw();
- return $response['user']['id'];
+// Throw an exception if an error occurred and the given condition is true...
+$response->throwIf($condition);
+
+// Throw an exception if an error occurred and the given closure resolves to true...
+$response->throwIf(fn (Response $response) => true);
+
+// Throw an exception if an error occurred and the given condition is false...
+$response->throwUnless($condition);
+
+// Throw an exception if an error occurred and the given closure resolves to false...
+$response->throwUnless(fn (Response $response) => false);
+
+// Throw an exception if the response has a specific status code...
+$response->throwIfStatus(403);
+
+// Throw an exception unless the response has a specific status code...
+$response->throwUnlessStatus(200);
+
+return $response['user']['id'];
+```
The `Illuminate\Http\Client\RequestException` instance has a public `$response` property which will allow you to inspect the returned response.
The `throw` method returns the response instance if no error occurred, allowing you to chain other operations onto the `throw` method:
- return Http::post(...)->throw()->json();
+```php
+return Http::post(/* ... */)->throw()->json();
+```
If you would like to perform some additional logic before the exception is thrown, you may pass a closure to the `throw` method. The exception will be thrown automatically after the closure is invoked, so you do not need to re-throw the exception from within the closure:
- return Http::post(...)->throw(function ($response, $e) {
- //
- })->json();
+```php
+use Illuminate\Http\Client\Response;
+use Illuminate\Http\Client\RequestException;
+
+return Http::post(/* ... */)->throw(function (Response $response, RequestException $e) {
+ // ...
+})->json();
+```
+
+By default, `RequestException` messages are truncated to 120 characters when logged or reported. To customize or disable this behavior, you may utilize the `truncateRequestExceptionsAt` and `dontTruncateRequestExceptions` methods when configuring your application's exception handling behavior in your `bootstrap/app.php` file:
+
+```php
+use Illuminate\Foundation\Configuration\Exceptions;
+
+->withExceptions(function (Exceptions $exceptions): void {
+ // Truncate request exception messages to 240 characters...
+ $exceptions->truncateRequestExceptionsAt(240);
+
+ // Disable request exception message truncation...
+ $exceptions->dontTruncateRequestExceptions();
+})
+```
+
+Alternatively, you may customize the exception truncation behavior per request using the `truncateExceptionsAt` method:
+
+```php
+return Http::truncateExceptionsAt(240)->post(/* ... */);
+```
+
+
+### Guzzle Middleware
+
+Since Laravel's HTTP client is powered by Guzzle, you may take advantage of [Guzzle Middleware](https://docs.guzzlephp.org/en/stable/handlers-and-middleware.html) to manipulate the outgoing request or inspect the incoming response. To manipulate the outgoing request, register a Guzzle middleware via the `withRequestMiddleware` method:
+
+```php
+use Illuminate\Support\Facades\Http;
+use Psr\Http\Message\RequestInterface;
+
+$response = Http::withRequestMiddleware(
+ function (RequestInterface $request) {
+ return $request->withHeader('X-Example', 'Value');
+ }
+)->get('http://example.com/');
+```
+
+Likewise, you can inspect the incoming HTTP response by registering a middleware via the `withResponseMiddleware` method:
+
+```php
+use Illuminate\Support\Facades\Http;
+use Psr\Http\Message\ResponseInterface;
+
+$response = Http::withResponseMiddleware(
+ function (ResponseInterface $response) {
+ $header = $response->getHeader('X-Example');
+
+ // ...
+
+ return $response;
+ }
+)->get('http://example.com/');
+```
+
+
+#### Global Middleware
+
+Sometimes, you may want to register a middleware that applies to every outgoing request and incoming response. To accomplish this, you may use the `globalRequestMiddleware` and `globalResponseMiddleware` methods. Typically, these methods should be invoked in the `boot` method of your application's `AppServiceProvider`:
+
+```php
+use Illuminate\Support\Facades\Http;
+
+Http::globalRequestMiddleware(fn ($request) => $request->withHeader(
+ 'User-Agent', 'Example Application/1.0'
+));
+
+Http::globalResponseMiddleware(fn ($response) => $response->withHeader(
+ 'X-Finished-At', now()->toDateTimeString()
+));
+```
### Guzzle Options
-You may specify additional [Guzzle request options](http://docs.guzzlephp.org/en/stable/request-options.html) using the `withOptions` method. The `withOptions` method accepts an array of key / value pairs:
+You may specify additional [Guzzle request options](http://docs.guzzlephp.org/en/stable/request-options.html) for an outgoing request using the `withOptions` method. The `withOptions` method accepts an array of key / value pairs:
+
+```php
+$response = Http::withOptions([
+ 'debug' => true,
+])->get('http://example.com/users');
+```
+
+
+#### Global Options
+
+To configure default options for every outgoing request, you may utilize the `globalOptions` method. Typically, this method should be invoked from the `boot` method of your application's `AppServiceProvider`:
+
+```php
+use Illuminate\Support\Facades\Http;
- $response = Http::withOptions([
- 'debug' => true,
- ])->get('http://example.com/users');
+/**
+ * Bootstrap any application services.
+ */
+public function boot(): void
+{
+ Http::globalOptions([
+ 'allow_redirects' => false,
+ ]);
+}
+```
## Concurrent Requests
Sometimes, you may wish to make multiple HTTP requests concurrently. In other words, you want several requests to be dispatched at the same time instead of issuing the requests sequentially. This can lead to substantial performance improvements when interacting with slow HTTP APIs.
+
+### Request Pooling
+
Thankfully, you may accomplish this using the `pool` method. The `pool` method accepts a closure which receives an `Illuminate\Http\Client\Pool` instance, allowing you to easily add requests to the request pool for dispatching:
- use Illuminate\Http\Client\Pool;
- use Illuminate\Support\Facades\Http;
+```php
+use Illuminate\Http\Client\Pool;
+use Illuminate\Support\Facades\Http;
- $responses = Http::pool(fn (Pool $pool) => [
- $pool->get('http://localhost/first'),
- $pool->get('http://localhost/second'),
- $pool->get('http://localhost/third'),
- ]);
+$responses = Http::pool(fn (Pool $pool) => [
+ $pool->get('http://localhost/first'),
+ $pool->get('http://localhost/second'),
+ $pool->get('http://localhost/third'),
+]);
- return $responses[0]->ok() &&
- $responses[1]->ok() &&
- $responses[2]->ok();
+return $responses[0]->ok() &&
+ $responses[1]->ok() &&
+ $responses[2]->ok();
+```
As you can see, each response instance can be accessed based on the order it was added to the pool. If you wish, you can name the requests using the `as` method, which allows you to access the corresponding responses by name:
- use Illuminate\Http\Client\Pool;
- use Illuminate\Support\Facades\Http;
+```php
+use Illuminate\Http\Client\Pool;
+use Illuminate\Support\Facades\Http;
- $responses = Http::pool(fn (Pool $pool) => [
- $pool->as('first')->get('http://localhost/first'),
- $pool->as('second')->get('http://localhost/second'),
- $pool->as('third')->get('http://localhost/third'),
- ]);
+$responses = Http::pool(fn (Pool $pool) => [
+ $pool->as('first')->get('http://localhost/first'),
+ $pool->as('second')->get('http://localhost/second'),
+ $pool->as('third')->get('http://localhost/third'),
+]);
- return $responses['first']->ok();
+return $responses['first']->ok();
+```
+
+
+#### Customizing Concurrent Requests
+
+The `pool` method cannot be chained with other HTTP client methods such as the `withHeaders` or `middleware` methods. If you want to apply custom headers or middleware to pooled requests, you should configure those options on each request in the pool:
+
+```php
+use Illuminate\Http\Client\Pool;
+use Illuminate\Support\Facades\Http;
+
+$headers = [
+ 'X-Example' => 'example',
+];
+
+$responses = Http::pool(fn (Pool $pool) => [
+ $pool->withHeaders($headers)->get('http://laravel.test/test'),
+ $pool->withHeaders($headers)->get('http://laravel.test/test'),
+ $pool->withHeaders($headers)->get('http://laravel.test/test'),
+]);
+```
+
+
+### Request Batching
+
+Another way of working with concurrent requests in Laravel is to use the `batch` method. Like the `pool` method, it accepts a closure which receives an `Illuminate\Http\Client\Batch` instance, allowing you to easily add requests to the request pool for dispatching, but it also allows you to define completion callbacks:
+
+```php
+use Illuminate\Http\Client\Batch;
+use Illuminate\Http\Client\ConnectionException;
+use Illuminate\Http\Client\RequestException;
+use Illuminate\Http\Client\Response;
+use Illuminate\Support\Facades\Http;
+
+$responses = Http::batch(fn (Batch $batch) => [
+ $batch->get('http://localhost/first'),
+ $batch->get('http://localhost/second'),
+ $batch->get('http://localhost/third'),
+])->before(function (Batch $batch) {
+ // The batch has been created but no requests have been initialized...
+})->progress(function (Batch $batch, int|string $key, Response $response) {
+ // An individual request has completed successfully...
+})->then(function (Batch $batch, array $results) {
+ // All requests completed successfully...
+})->catch(function (Batch $batch, int|string $key, Response|RequestException|ConnectionException $response) {
+ // First batch request failure detected...
+})->finally(function (Batch $batch, array $results) {
+ // The batch has finished executing...
+})->send();
+```
+
+Like the `pool` method, you can use the `as` method to name your requests:
+
+```php
+$responses = Http::batch(fn (Batch $batch) => [
+ $batch->as('first')->get('http://localhost/first'),
+ $batch->as('second')->get('http://localhost/second'),
+ $batch->as('third')->get('http://localhost/third'),
+])->send();
+```
+
+After a `batch` is started by calling the `send` method, you can't add new requests to it. Trying to do so will result in a `Illuminate\Http\Client\BatchInProgressException` exception being thrown.
+
+
+#### Inspecting Batches
+
+The `Illuminate\Http\Client\Batch` instance that is provided to batch completion callbacks has a variety of properties and methods to assist you in interacting with and inspecting a given batch of requests:
+
+```php
+// The number of requests assigned to the batch...
+$batch->totalRequests;
+
+// The number of requests that have not been processed yet...
+$batch->pendingRequests;
+
+// The number of requests that have failed...
+$batch->failedRequests;
+
+// The number of requests that have been processed thus far...
+$batch->processedRequests();
+
+// Indicates if the batch has finished executing...
+$batch->finished();
+
+// Indicates if the batch has request failures...
+$batch->hasFailures();
+```
+
+#### Deferring Batches
+
+When the `defer` method is invoked, the batch of requests is not executed immediately. Instead, Laravel will execute the batch after the current application request's HTTP response has been sent to the user, keeping your application feeling fast and responsive:
+
+```php
+use Illuminate\Http\Client\Batch;
+use Illuminate\Support\Facades\Http;
+
+$responses = Http::batch(fn (Batch $batch) => [
+ $batch->get('http://localhost/first'),
+ $batch->get('http://localhost/second'),
+ $batch->get('http://localhost/third'),
+])->then(function (Batch $batch, array $results) {
+ // All requests completed successfully...
+})->defer();
+```
## Macros
@@ -288,10 +650,8 @@ use Illuminate\Support\Facades\Http;
/**
* Bootstrap any application services.
- *
- * @return void
*/
-public function boot()
+public function boot(): void
{
Http::macro('github', function () {
return Http::withHeaders([
@@ -310,79 +670,124 @@ $response = Http::github()->get('/');
## Testing
-Many Laravel services provide functionality to help you easily and expressively write tests, and Laravel's HTTP wrapper is no exception. The `Http` facade's `fake` method allows you to instruct the HTTP client to return stubbed / dummy responses when requests are made.
+Many Laravel services provide functionality to help you easily and expressively write tests, and Laravel's HTTP client is no exception. The `Http` facade's `fake` method allows you to instruct the HTTP client to return stubbed / dummy responses when requests are made.
### Faking Responses
For example, to instruct the HTTP client to return empty, `200` status code responses for every request, you may call the `fake` method with no arguments:
- use Illuminate\Support\Facades\Http;
+```php
+use Illuminate\Support\Facades\Http;
- Http::fake();
+Http::fake();
- $response = Http::post(...);
+$response = Http::post(/* ... */);
+```
#### Faking Specific URLs
-Alternatively, you may pass an array to the `fake` method. The array's keys should represent URL patterns that you wish to fake and their associated responses. The `*` character may be used as a wildcard character. Any requests made to URLs that have not been faked will actually be executed. You may use the `Http` facade's `response` method to construct stub / fake responses for these endpoints:
+Alternatively, you may pass an array to the `fake` method. The array's keys should represent URL patterns that you wish to fake and their associated responses. The `*` character may be used as a wildcard character. You may use the `Http` facade's `response` method to construct stub / fake responses for these endpoints:
- Http::fake([
- // Stub a JSON response for GitHub endpoints...
- 'github.com/*' => Http::response(['foo' => 'bar'], 200, $headers),
+```php
+Http::fake([
+ // Stub a JSON response for GitHub endpoints...
+ 'github.com/*' => Http::response(['foo' => 'bar'], 200, $headers),
- // Stub a string response for Google endpoints...
- 'google.com/*' => Http::response('Hello World', 200, $headers),
- ]);
+ // Stub a string response for Google endpoints...
+ 'google.com/*' => Http::response('Hello World', 200, $headers),
+]);
+```
-If you would like to specify a fallback URL pattern that will stub all unmatched URLs, you may use a single `*` character:
+Any requests made to URLs that have not been faked will actually be executed. If you would like to specify a fallback URL pattern that will stub all unmatched URLs, you may use a single `*` character:
- Http::fake([
- // Stub a JSON response for GitHub endpoints...
- 'github.com/*' => Http::response(['foo' => 'bar'], 200, ['Headers']),
+```php
+Http::fake([
+ // Stub a JSON response for GitHub endpoints...
+ 'github.com/*' => Http::response(['foo' => 'bar'], 200, ['Headers']),
- // Stub a string response for all other endpoints...
- '*' => Http::response('Hello World', 200, ['Headers']),
- ]);
+ // Stub a string response for all other endpoints...
+ '*' => Http::response('Hello World', 200, ['Headers']),
+]);
+```
+
+For convenience, simple string, JSON, and empty responses may be generated by providing a string, array, or integer as the response:
+
+```php
+Http::fake([
+ 'google.com/*' => 'Hello World',
+ 'github.com/*' => ['foo' => 'bar'],
+ 'chatgpt.com/*' => 200,
+]);
+```
+
+
+#### Faking Exceptions
+
+Sometimes you may need to test your application's behavior if the HTTP client encounters an `Illuminate\Http\Client\ConnectionException` when attempting to make a request. You can instruct the HTTP client to throw a connection exception using the `failedConnection` method:
+
+```php
+Http::fake([
+ 'github.com/*' => Http::failedConnection(),
+]);
+```
+
+To test your application's behavior if a `Illuminate\Http\Client\RequestException` is thrown, you may use the `failedRequest` method:
+
+```php
+Http::fake([
+ 'github.com/*' => Http::failedRequest(['code' => 'not_found'], 404),
+]);
+```
#### Faking Response Sequences
Sometimes you may need to specify that a single URL should return a series of fake responses in a specific order. You may accomplish this using the `Http::sequence` method to build the responses:
- Http::fake([
- // Stub a series of responses for GitHub endpoints...
- 'github.com/*' => Http::sequence()
- ->push('Hello World', 200)
- ->push(['foo' => 'bar'], 200)
- ->pushStatus(404),
- ]);
+```php
+Http::fake([
+ // Stub a series of responses for GitHub endpoints...
+ 'github.com/*' => Http::sequence()
+ ->push('Hello World', 200)
+ ->push(['foo' => 'bar'], 200)
+ ->pushStatus(404),
+]);
+```
-When all of the responses in a response sequence have been consumed, any further requests will cause the response sequence to throw an exception. If you would like to specify a default response that should be returned when a sequence is empty, you may use the `whenEmpty` method:
+When all the responses in a response sequence have been consumed, any further requests will cause the response sequence to throw an exception. If you would like to specify a default response that should be returned when a sequence is empty, you may use the `whenEmpty` method:
- Http::fake([
- // Stub a series of responses for GitHub endpoints...
- 'github.com/*' => Http::sequence()
- ->push('Hello World', 200)
- ->push(['foo' => 'bar'], 200)
- ->whenEmpty(Http::response()),
- ]);
+```php
+Http::fake([
+ // Stub a series of responses for GitHub endpoints...
+ 'github.com/*' => Http::sequence()
+ ->push('Hello World', 200)
+ ->push(['foo' => 'bar'], 200)
+ ->whenEmpty(Http::response()),
+]);
+```
If you would like to fake a sequence of responses but do not need to specify a specific URL pattern that should be faked, you may use the `Http::fakeSequence` method:
- Http::fakeSequence()
- ->push('Hello World', 200)
- ->whenEmpty(Http::response());
+```php
+Http::fakeSequence()
+ ->push('Hello World', 200)
+ ->whenEmpty(Http::response());
+```
#### Fake Callback
If you require more complicated logic to determine what responses to return for certain endpoints, you may pass a closure to the `fake` method. This closure will receive an instance of `Illuminate\Http\Client\Request` and should return a response instance. Within your closure, you may perform whatever logic is necessary to determine what type of response to return:
- Http::fake(function ($request) {
- return Http::response('Hello World', 200);
- });
+```php
+use Illuminate\Http\Client\Request;
+
+Http::fake(function (Request $request) {
+ return Http::response('Hello World', 200);
+});
+```
### Inspecting Requests
@@ -391,73 +796,157 @@ When faking responses, you may occasionally wish to inspect the requests the cli
The `assertSent` method accepts a closure which will receive an `Illuminate\Http\Client\Request` instance and should return a boolean value indicating if the request matches your expectations. In order for the test to pass, at least one request must have been issued matching the given expectations:
- use Illuminate\Http\Client\Request;
- use Illuminate\Support\Facades\Http;
-
- Http::fake();
-
- Http::withHeaders([
- 'X-First' => 'foo',
- ])->post('http://example.com/users', [
- 'name' => 'Taylor',
- 'role' => 'Developer',
- ]);
+```php
+use Illuminate\Http\Client\Request;
+use Illuminate\Support\Facades\Http;
- Http::assertSent(function (Request $request) {
- return $request->hasHeader('X-First', 'foo') &&
- $request->url() == 'http://example.com/users' &&
- $request['name'] == 'Taylor' &&
- $request['role'] == 'Developer';
- });
+Http::fake();
+
+Http::withHeaders([
+ 'X-First' => 'foo',
+])->post('http://example.com/users', [
+ 'name' => 'Taylor',
+ 'role' => 'Developer',
+]);
+
+Http::assertSent(function (Request $request) {
+ return $request->hasHeader('X-First', 'foo') &&
+ $request->url() == 'http://example.com/users' &&
+ $request['name'] == 'Taylor' &&
+ $request['role'] == 'Developer';
+});
+```
If needed, you may assert that a specific request was not sent using the `assertNotSent` method:
- use Illuminate\Http\Client\Request;
- use Illuminate\Support\Facades\Http;
+```php
+use Illuminate\Http\Client\Request;
+use Illuminate\Support\Facades\Http;
- Http::fake();
+Http::fake();
- Http::post('http://example.com/users', [
- 'name' => 'Taylor',
- 'role' => 'Developer',
- ]);
+Http::post('http://example.com/users', [
+ 'name' => 'Taylor',
+ 'role' => 'Developer',
+]);
- Http::assertNotSent(function (Request $request) {
- return $request->url() === 'http://example.com/posts';
- });
+Http::assertNotSent(function (Request $request) {
+ return $request->url() === 'http://example.com/posts';
+});
+```
You may use the `assertSentCount` method to assert how many requests were "sent" during the test:
- Http::fake();
+```php
+Http::fake();
- Http::assertSentCount(5);
+Http::assertSentCount(5);
+```
Or, you may use the `assertNothingSent` method to assert that no requests were sent during the test:
- Http::fake();
+```php
+Http::fake();
+
+Http::assertNothingSent();
+```
+
+
+#### Recording Requests / Responses
+
+You may use the `recorded` method to gather all requests and their corresponding responses. The `recorded` method returns a collection of arrays that contains instances of `Illuminate\Http\Client\Request` and `Illuminate\Http\Client\Response`:
+
+```php
+Http::fake([
+ 'https://laravel.com/' => Http::response(status: 500),
+ 'https://nova.laravel.com/' => Http::response(),
+]);
- Http::assertNothingSent();
+Http::get('https://laravel.com/');
+Http::get('https://nova.laravel.com/');
+
+$recorded = Http::recorded();
+
+[$request, $response] = $recorded[0];
+```
+
+Additionally, the `recorded` method accepts a closure which will receive an instance of `Illuminate\Http\Client\Request` and `Illuminate\Http\Client\Response` and may be used to filter request / response pairs based on your expectations:
+
+```php
+use Illuminate\Http\Client\Request;
+use Illuminate\Http\Client\Response;
+
+Http::fake([
+ 'https://laravel.com/' => Http::response(status: 500),
+ 'https://nova.laravel.com/' => Http::response(),
+]);
+
+Http::get('https://laravel.com/');
+Http::get('https://nova.laravel.com/');
+
+$recorded = Http::recorded(function (Request $request, Response $response) {
+ return $request->url() !== 'https://laravel.com/' &&
+ $response->successful();
+});
+```
+
+
+### Preventing Stray Requests
+
+If you would like to ensure that all requests sent via the HTTP client have been faked throughout your individual test or complete test suite, you can call the `preventStrayRequests` method. After calling this method, any requests that do not have a corresponding fake response will throw an exception rather than making the actual HTTP request:
+
+```php
+use Illuminate\Support\Facades\Http;
+
+Http::preventStrayRequests();
+
+Http::fake([
+ 'github.com/*' => Http::response('ok'),
+]);
+
+// An "ok" response is returned...
+Http::get('https://github.com/laravel/framework');
+
+// An exception is thrown...
+Http::get('https://laravel.com/');
+```
+
+Sometimes, you may wish to prevent most stray requests while still allowing specific requests to execute. To accomplish this, you may pass an array of URL patterns to the `allowStrayRequests` method. Any request matching one of the given patterns will be allowed, while all other requests will continue to throw an exception:
+
+```php
+use Illuminate\Support\Facades\Http;
+
+Http::preventStrayRequests();
+
+Http::allowStrayRequests([
+ 'http://127.0.0.1:5000/*',
+]);
+
+// This request is executed...
+Http::get('http://127.0.0.1:5000/generate');
+
+// An exception is thrown...
+Http::get('https://laravel.com/');
+```
## Events
Laravel fires three events during the process of sending HTTP requests. The `RequestSending` event is fired prior to a request being sent, while the `ResponseReceived` event is fired after a response is received for a given request. The `ConnectionFailed` event is fired if no response is received for a given request.
-The `RequestSending` and `ConnectionFailed` events both contain a public `$request` property that you may use to inspect the `Illuminate\Http\Client\Request` instance. Likewise, the `ResponseReceived` event contains a `$request` property as well as a `$response` property which may be used to inspect the `Illuminate\Http\Client\Response` instance. You may register event listeners for this event in your `App\Providers\EventServiceProvider` service provider:
+The `RequestSending` and `ConnectionFailed` events both contain a public `$request` property that you may use to inspect the `Illuminate\Http\Client\Request` instance. Likewise, the `ResponseReceived` event contains a `$request` property as well as a `$response` property which may be used to inspect the `Illuminate\Http\Client\Response` instance. You may create [event listeners](/docs/{{version}}/events) for these events within your application:
+
+```php
+use Illuminate\Http\Client\Events\RequestSending;
+class LogRequest
+{
/**
- * The event listener mappings for the application.
- *
- * @var array
+ * Handle the event.
*/
- protected $listen = [
- 'Illuminate\Http\Client\Events\RequestSending' => [
- 'App\Listeners\LogRequestSending',
- ],
- 'Illuminate\Http\Client\Events\ResponseReceived' => [
- 'App\Listeners\LogResponseReceived',
- ],
- 'Illuminate\Http\Client\Events\ConnectionFailed' => [
- 'App\Listeners\LogConnectionFailed',
- ],
- ];
+ public function handle(RequestSending $event): void
+ {
+ // $event->request ...
+ }
+}
+```
diff --git a/http-tests.md b/http-tests.md
index 1b3855f2368..4f705ea3dd4 100644
--- a/http-tests.md
+++ b/http-tests.md
@@ -11,38 +11,47 @@
- [Fluent JSON Testing](#fluent-json-testing)
- [Testing File Uploads](#testing-file-uploads)
- [Testing Views](#testing-views)
- - [Rendering Blade & Components](#rendering-blade-and-components)
+ - [Rendering Blade and Components](#rendering-blade-and-components)
- [Available Assertions](#available-assertions)
- [Response Assertions](#response-assertions)
- [Authentication Assertions](#authentication-assertions)
+ - [Validation Assertions](#validation-assertions)
## Introduction
Laravel provides a very fluent API for making HTTP requests to your application and examining the responses. For example, take a look at the feature test defined below:
- get('/');
- use Illuminate\Foundation\Testing\RefreshDatabase;
- use Illuminate\Foundation\Testing\WithoutMiddleware;
- use Tests\TestCase;
+ $response->assertStatus(200);
+});
+```
+
+```php tab=PHPUnit
+get('/');
+ $response = $this->get('/');
- $response->assertStatus(200);
- }
+ $response->assertStatus(200);
}
+}
+```
The `get` method makes a `GET` request into the application, while the `assertStatus` method asserts that the returned response should have the given HTTP status code. In addition to this simple assertion, Laravel also contains a variety of assertions for inspecting the response headers, content, JSON structure, and more.
@@ -53,426 +62,720 @@ To make a request to your application, you may invoke the `get`, `post`, `put`,
Instead of returning an `Illuminate\Http\Response` instance, test request methods return an instance of `Illuminate\Testing\TestResponse`, which provides a [variety of helpful assertions](#available-assertions) that allow you to inspect your application's responses:
- get('/');
- namespace Tests\Feature;
+ $response->assertStatus(200);
+});
+```
+
+```php tab=PHPUnit
+get('/');
+ $response = $this->get('/');
- $response->assertStatus(200);
- }
+ $response->assertStatus(200);
}
+}
+```
In general, each of your tests should only make one request to your application. Unexpected behavior may occur if multiple requests are executed within a single test method.
-> {tip} For convenience, the CSRF middleware is automatically disabled when running tests.
+> [!NOTE]
+> For convenience, the CSRF middleware is automatically disabled when running tests.
### Customizing Request Headers
You may use the `withHeaders` method to customize the request's headers before it is sent to the application. This method allows you to add any custom headers you would like to the request:
- withHeaders([
+ 'X-Header' => 'Value',
+ ])->post('/user', ['name' => 'Sally']);
+
+ $response->assertStatus(201);
+});
+```
+
+```php tab=PHPUnit
+withHeaders([
- 'X-Header' => 'Value',
- ])->post('/user', ['name' => 'Sally']);
+ $response = $this->withHeaders([
+ 'X-Header' => 'Value',
+ ])->post('/user', ['name' => 'Sally']);
- $response->assertStatus(201);
- }
+ $response->assertStatus(201);
}
+}
+```
### Cookies
You may use the `withCookie` or `withCookies` methods to set cookie values before making a request. The `withCookie` method accepts a cookie name and value as its two arguments, while the `withCookies` method accepts an array of name / value pairs:
- withCookie('color', 'blue')->get('/');
+
+ $response = $this->withCookies([
+ 'color' => 'blue',
+ 'name' => 'Taylor',
+ ])->get('/');
- namespace Tests\Feature;
+ //
+});
+```
+
+```php tab=PHPUnit
+withCookie('color', 'blue')->get('/');
+ $response = $this->withCookie('color', 'blue')->get('/');
- $response = $this->withCookies([
- 'color' => 'blue',
- 'name' => 'Taylor',
- ])->get('/');
- }
+ $response = $this->withCookies([
+ 'color' => 'blue',
+ 'name' => 'Taylor',
+ ])->get('/');
+
+ //
}
+}
+```
### Session / Authentication
Laravel provides several helpers for interacting with the session during HTTP testing. First, you may set the session data to a given array using the `withSession` method. This is useful for loading the session with data before issuing a request to your application:
- withSession(['banned' => false])->get('/');
+
+ //
+});
+```
- namespace Tests\Feature;
+```php tab=PHPUnit
+withSession(['banned' => false])->get('/');
- }
+ $response = $this->withSession(['banned' => false])->get('/');
+
+ //
}
+}
+```
+
+Laravel's session is typically used to maintain state for the currently authenticated user. Therefore, the `actingAs` helper method provides a simple way to authenticate a given user as the current user. For example, we may use a [model factory](/docs/{{version}}/eloquent-factories) to generate and authenticate a user:
-Laravel's session is typically used to maintain state for the currently authenticated user. Therefore, the `actingAs` helper method provides a simple way to authenticate a given user as the current user. For example, we may use a [model factory](/docs/{{version}}/database-testing#writing-factories) to generate and authenticate a user:
+```php tab=Pest
+create();
- use App\Models\User;
- use Tests\TestCase;
+ $response = $this->actingAs($user)
+ ->withSession(['banned' => false])
+ ->get('/');
- class ExampleTest extends TestCase
+ //
+});
+```
+
+```php tab=PHPUnit
+create();
+ $user = User::factory()->create();
- $response = $this->actingAs($user)
- ->withSession(['banned' => false])
- ->get('/');
- }
+ $response = $this->actingAs($user)
+ ->withSession(['banned' => false])
+ ->get('/');
+
+ //
}
+}
+```
-You may also specify which guard should be used to authenticate the given user by passing the guard name as the second argument to the `actingAs` method:
+You may also specify which guard should be used to authenticate the given user by passing the guard name as the second argument to the `actingAs` method. The guard that is provided to the `actingAs` method will also become the default guard for the duration of the test:
- $this->actingAs($user, 'web')
+```php
+$this->actingAs($user, 'web');
+```
+
+If you would like to ensure the request is unauthenticated, you may use the `actingAsGuest` method:
+
+```php
+$this->actingAsGuest();
+```
### Debugging Responses
After making a test request to your application, the `dump`, `dumpHeaders`, and `dumpSession` methods may be used to examine and debug the response contents:
- get('/');
- use Tests\TestCase;
+ $response->dump();
+ $response->dumpHeaders();
+ $response->dumpSession();
+});
+```
- class ExampleTest extends TestCase
- {
- /**
- * A basic test example.
- *
- * @return void
- */
- public function test_basic_test()
- {
- $response = $this->get('/');
+```php tab=PHPUnit
+dumpHeaders();
+namespace Tests\Feature;
- $response->dumpSession();
+use Tests\TestCase;
- $response->dump();
- }
+class ExampleTest extends TestCase
+{
+ /**
+ * A basic test example.
+ */
+ public function test_basic_test(): void
+ {
+ $response = $this->get('/');
+
+ $response->dump();
+ $response->dumpHeaders();
+ $response->dumpSession();
}
+}
+```
-Alternatively, you may use the `dd`, `ddHeaders`, and `ddSession` methods to dump information about the response and then stop execution:
+Alternatively, you may use the `dd`, `ddHeaders`, `ddBody`, `ddJson`, and `ddSession` methods to dump information about the response and then stop execution:
- get('/');
- use Tests\TestCase;
+ $response->dd();
+ $response->ddHeaders();
+ $response->ddBody();
+ $response->ddJson();
+ $response->ddSession();
+});
+```
- class ExampleTest extends TestCase
- {
- /**
- * A basic test example.
- *
- * @return void
- */
- public function test_basic_test()
- {
- $response = $this->get('/');
+```php tab=PHPUnit
+ddHeaders();
+namespace Tests\Feature;
- $response->ddSession();
+use Tests\TestCase;
- $response->dd();
- }
+class ExampleTest extends TestCase
+{
+ /**
+ * A basic test example.
+ */
+ public function test_basic_test(): void
+ {
+ $response = $this->get('/');
+
+ $response->dd();
+ $response->ddHeaders();
+ $response->ddBody();
+ $response->ddJson();
+ $response->ddSession();
}
+}
+```
### Exception Handling
-Sometimes you may want to test that your application is throwing a specific exception. To ensure that the exception does not get caught by Laravel's exception handler and returned as an HTTP response, you may invoke the `withoutExceptionHandling` method before making your request:
+Sometimes you may need to test that your application is throwing a specific exception. To accomplish this, you may "fake" the exception handler via the `Exceptions` facade. Once the exception handler has been faked, you may utilize the `assertReported` and `assertNotReported` methods to make assertions against exceptions that were thrown during the request:
+
+```php tab=Pest
+withoutExceptionHandling()->get('/');
+use App\Exceptions\InvalidOrderException;
+use Illuminate\Support\Facades\Exceptions;
+
+test('exception is thrown', function () {
+ Exceptions::fake();
+
+ $response = $this->get('/order/1');
+
+ // Assert an exception was thrown...
+ Exceptions::assertReported(InvalidOrderException::class);
+
+ // Assert against the exception...
+ Exceptions::assertReported(function (InvalidOrderException $e) {
+ return $e->getMessage() === 'The order was invalid.';
+ });
+});
+```
+
+```php tab=PHPUnit
+get('/');
+
+ // Assert an exception was thrown...
+ Exceptions::assertReported(InvalidOrderException::class);
+
+ // Assert against the exception...
+ Exceptions::assertReported(function (InvalidOrderException $e) {
+ return $e->getMessage() === 'The order was invalid.';
+ });
+ }
+}
+```
+
+The `assertNotReported` and `assertNothingReported` methods may be used to assert that a given exception was not thrown during the request or that no exceptions were thrown:
+
+```php
+Exceptions::assertNotReported(InvalidOrderException::class);
+
+Exceptions::assertNothingReported();
+```
+
+You may totally disable exception handling for a given request by invoking the `withoutExceptionHandling` method before making your request:
+
+```php
+$response = $this->withoutExceptionHandling()->get('/');
+```
In addition, if you would like to ensure that your application is not utilizing features that have been deprecated by the PHP language or the libraries your application is using, you may invoke the `withoutDeprecationHandling` method before making your request. When deprecation handling is disabled, deprecation warnings will be converted to exceptions, thus causing your test to fail:
- $response = $this->withoutDeprecationHandling()->get('/');
+```php
+$response = $this->withoutDeprecationHandling()->get('/');
+```
+
+The `assertThrows` method may be used to assert that code within a given closure throws an exception of the specified type:
+
+```php
+$this->assertThrows(
+ fn () => (new ProcessOrder)->execute(),
+ OrderInvalid::class
+);
+```
+
+If you would like to inspect and make assertions against the exception that is thrown, you may provide a closure as the second argument to the `assertThrows` method:
+
+```php
+$this->assertThrows(
+ fn () => (new ProcessOrder)->execute(),
+ fn (OrderInvalid $e) => $e->orderId() === 123;
+);
+```
+
+The `assertDoesntThrow` method may be used to assert that the code within a given closure does not throw any exceptions:
+
+```php
+$this->assertDoesntThrow(fn () => (new ProcessOrder)->execute());
+```
## Testing JSON APIs
Laravel also provides several helpers for testing JSON APIs and their responses. For example, the `json`, `getJson`, `postJson`, `putJson`, `patchJson`, `deleteJson`, and `optionsJson` methods may be used to issue JSON requests with various HTTP verbs. You may also easily pass data and headers to these methods. To get started, let's write a test to make a `POST` request to `/api/user` and assert that the expected JSON data was returned:
- postJson('/api/user', ['name' => 'Sally']);
+
+ $response
+ ->assertStatus(201)
+ ->assertJson([
+ 'created' => true,
+ ]);
+});
+```
- namespace Tests\Feature;
+```php tab=PHPUnit
+postJson('/api/user', ['name' => 'Sally']);
+ $response = $this->postJson('/api/user', ['name' => 'Sally']);
- $response
- ->assertStatus(201)
- ->assertJson([
- 'created' => true,
- ]);
- }
+ $response
+ ->assertStatus(201)
+ ->assertJson([
+ 'created' => true,
+ ]);
}
+}
+```
In addition, JSON response data may be accessed as array variables on the response, making it convenient for you to inspect the individual values returned within a JSON response:
- $this->assertTrue($response['created']);
+```php tab=Pest
+expect($response['created'])->toBeTrue();
+```
+
+```php tab=PHPUnit
+$this->assertTrue($response['created']);
+```
-> {tip} The `assertJson` method converts the response to an array and utilizes `PHPUnit::assertArraySubset` to verify that the given array exists within the JSON response returned by the application. So, if there are other properties in the JSON response, this test will still pass as long as the given fragment is present.
+> [!NOTE]
+> The `assertJson` method converts the response to an array to verify that the given array exists within the JSON response returned by the application. So, if there are other properties in the JSON response, this test will still pass as long as the given fragment is present.
#### Asserting Exact JSON Matches
As previously mentioned, the `assertJson` method may be used to assert that a fragment of JSON exists within the JSON response. If you would like to verify that a given array **exactly matches** the JSON returned by your application, you should use the `assertExactJson` method:
- postJson('/user', ['name' => 'Sally']);
- use Tests\TestCase;
+ $response
+ ->assertStatus(201)
+ ->assertExactJson([
+ 'created' => true,
+ ]);
+});
+```
+
+```php tab=PHPUnit
+postJson('/user', ['name' => 'Sally']);
+ $response = $this->postJson('/user', ['name' => 'Sally']);
- $response
- ->assertStatus(201)
- ->assertExactJson([
- 'created' => true,
- ]);
- }
+ $response
+ ->assertStatus(201)
+ ->assertExactJson([
+ 'created' => true,
+ ]);
}
+}
+```
-#### Asserting On JSON Paths
+#### Asserting on JSON Paths
If you would like to verify that the JSON response contains the given data at a specified path, you should use the `assertJsonPath` method:
- postJson('/user', ['name' => 'Sally']);
- namespace Tests\Feature;
+ $response
+ ->assertStatus(201)
+ ->assertJsonPath('team.owner.name', 'Darian');
+});
+```
+
+```php tab=PHPUnit
+postJson('/user', ['name' => 'Sally']);
+ $response = $this->postJson('/user', ['name' => 'Sally']);
- $response
- ->assertStatus(201)
- ->assertJsonPath('team.owner.name', 'Darian');
- }
+ $response
+ ->assertStatus(201)
+ ->assertJsonPath('team.owner.name', 'Darian');
}
+}
+```
+
+The `assertJsonPath` method also accepts a closure, which may be used to dynamically determine if the assertion should pass:
+
+```php
+$response->assertJsonPath('team.owner.name', fn (string $name) => strlen($name) >= 3);
+```
### Fluent JSON Testing
Laravel also offers a beautiful way to fluently test your application's JSON responses. To get started, pass a closure to the `assertJson` method. This closure will be invoked with an instance of `Illuminate\Testing\Fluent\AssertableJson` which can be used to make assertions against the JSON that was returned by your application. The `where` method may be used to make assertions against a particular attribute of the JSON, while the `missing` method may be used to assert that a particular attribute is missing from the JSON:
- use Illuminate\Testing\Fluent\AssertableJson;
+```php tab=Pest
+use Illuminate\Testing\Fluent\AssertableJson;
- /**
- * A basic functional test example.
- *
- * @return void
- */
- public function test_fluent_json()
- {
- $response = $this->getJson('/users/1');
+test('fluent json', function () {
+ $response = $this->getJson('/users/1');
- $response
- ->assertJson(fn (AssertableJson $json) =>
- $json->where('id', 1)
- ->where('name', 'Victoria Faith')
- ->missing('password')
- ->etc()
- );
- }
+ $response
+ ->assertJson(fn (AssertableJson $json) =>
+ $json->where('id', 1)
+ ->where('name', 'Victoria Faith')
+ ->where('email', fn (string $email) => str($email)->is('victoria@gmail.com'))
+ ->whereNot('status', 'pending')
+ ->missing('password')
+ ->etc()
+ );
+});
+```
+
+```php tab=PHPUnit
+use Illuminate\Testing\Fluent\AssertableJson;
+
+/**
+ * A basic functional test example.
+ */
+public function test_fluent_json(): void
+{
+ $response = $this->getJson('/users/1');
+
+ $response
+ ->assertJson(fn (AssertableJson $json) =>
+ $json->where('id', 1)
+ ->where('name', 'Victoria Faith')
+ ->where('email', fn (string $email) => str($email)->is('victoria@gmail.com'))
+ ->whereNot('status', 'pending')
+ ->missing('password')
+ ->etc()
+ );
+}
+```
-#### Understanding The `etc` Method
+#### Understanding the `etc` Method
In the example above, you may have noticed we invoked the `etc` method at the end of our assertion chain. This method informs Laravel that there may be other attributes present on the JSON object. If the `etc` method is not used, the test will fail if other attributes that you did not make assertions against exist on the JSON object.
The intention behind this behavior is to protect you from unintentionally exposing sensitive information in your JSON responses by forcing you to either explicitly make an assertion against the attribute or explicitly allow additional attributes via the `etc` method.
+However, you should be aware that not including the `etc` method in your assertion chain does not ensure that additional attributes are not being added to arrays that are nested within your JSON object. The `etc` method only ensures that no additional attributes exist at the nesting level in which the `etc` method is invoked.
+
#### Asserting Attribute Presence / Absence
To assert that an attribute is present or absent, you may use the `has` and `missing` methods:
- $response->assertJson(fn (AssertableJson $json) =>
- $json->has('data')
- ->missing('message')
- );
+```php
+$response->assertJson(fn (AssertableJson $json) =>
+ $json->has('data')
+ ->missing('message')
+);
+```
In addition, the `hasAll` and `missingAll` methods allow asserting the presence or absence of multiple attributes simultaneously:
- $response->assertJson(fn (AssertableJson $json) =>
- $json->hasAll('status', 'data')
- ->missingAll('message', 'code')
- );
+```php
+$response->assertJson(fn (AssertableJson $json) =>
+ $json->hasAll(['status', 'data'])
+ ->missingAll(['message', 'code'])
+);
+```
You may use the `hasAny` method to determine if at least one of a given list of attributes is present:
- $response->assertJson(fn (AssertableJson $json) =>
- $json->has('status')
- ->hasAny('data', 'message', 'code')
- );
+```php
+$response->assertJson(fn (AssertableJson $json) =>
+ $json->has('status')
+ ->hasAny('data', 'message', 'code')
+);
+```
#### Asserting Against JSON Collections
Often, your route will return a JSON response that contains multiple items, such as multiple users:
- Route::get('/users', function () {
- return User::all();
- });
+```php
+Route::get('/users', function () {
+ return User::all();
+});
+```
In these situations, we may use the fluent JSON object's `has` method to make assertions against the users included in the response. For example, let's assert that the JSON response contains three users. Next, we'll make some assertions about the first user in the collection using the `first` method. The `first` method accepts a closure which receives another assertable JSON string that we can use to make assertions about the first object in the JSON collection:
- $response
- ->assertJson(fn (AssertableJson $json) =>
- $json->has(3)
- ->first(fn ($json) =>
- $json->where('id', 1)
- ->where('name', 'Victoria Faith')
- ->missing('password')
- ->etc()
- )
- );
+```php
+$response
+ ->assertJson(fn (AssertableJson $json) =>
+ $json->has(3)
+ ->first(fn (AssertableJson $json) =>
+ $json->where('id', 1)
+ ->where('name', 'Victoria Faith')
+ ->where('email', fn (string $email) => str($email)->is('victoria@gmail.com'))
+ ->missing('password')
+ ->etc()
+ )
+ );
+```
#### Scoping JSON Collection Assertions
Sometimes, your application's routes will return JSON collections that are assigned named keys:
- Route::get('/users', function () {
- return [
- 'meta' => [...],
- 'users' => User::all(),
- ];
- })
+```php
+Route::get('/users', function () {
+ return [
+ 'meta' => [...],
+ 'users' => User::all(),
+ ];
+})
+```
When testing these routes, you may use the `has` method to assert against the number of items in the collection. In addition, you may use the `has` method to scope a chain of assertions:
- $response
- ->assertJson(fn (AssertableJson $json) =>
- $json->has('meta')
- ->has('users', 3)
- ->has('users.0', fn ($json) =>
- $json->where('id', 1)
- ->where('name', 'Victoria Faith')
- ->missing('password')
- ->etc()
- )
- );
+```php
+$response
+ ->assertJson(fn (AssertableJson $json) =>
+ $json->has('meta')
+ ->has('users', 3)
+ ->has('users.0', fn (AssertableJson $json) =>
+ $json->where('id', 1)
+ ->where('name', 'Victoria Faith')
+ ->where('email', fn (string $email) => str($email)->is('victoria@gmail.com'))
+ ->missing('password')
+ ->etc()
+ )
+ );
+```
However, instead of making two separate calls to the `has` method to assert against the `users` collection, you may make a single call which provides a closure as its third parameter. When doing so, the closure will automatically be invoked and scoped to the first item in the collection:
- $response
- ->assertJson(fn (AssertableJson $json) =>
- $json->has('meta')
- ->has('users', 3, fn ($json) =>
- $json->where('id', 1)
- ->where('name', 'Victoria Faith')
- ->missing('password')
- ->etc()
- )
- );
+```php
+$response
+ ->assertJson(fn (AssertableJson $json) =>
+ $json->has('meta')
+ ->has('users', 3, fn (AssertableJson $json) =>
+ $json->where('id', 1)
+ ->where('name', 'Victoria Faith')
+ ->where('email', fn (string $email) => str($email)->is('victoria@gmail.com'))
+ ->missing('password')
+ ->etc()
+ )
+ );
+```
#### Asserting JSON Types
You may only want to assert that the properties in the JSON response are of a certain type. The `Illuminate\Testing\Fluent\AssertableJson` class provides the `whereType` and `whereAllType` methods for doing just that:
- $response->assertJson(fn (AssertableJson $json) =>
- $json->whereType('id', 'integer')
- ->whereAllType([
- 'users.0.name' => 'string',
- 'meta' => 'array'
- ])
- );
+```php
+$response->assertJson(fn (AssertableJson $json) =>
+ $json->whereType('id', 'integer')
+ ->whereAllType([
+ 'users.0.name' => 'string',
+ 'meta' => 'array'
+ ])
+);
+```
You may specify multiple types using the `|` character, or passing an array of types as the second parameter to the `whereType` method. The assertion will be successful if the response value is any of the listed types:
- $response->assertJson(fn (AssertableJson $json) =>
- $json->whereType('name', 'string|null')
- ->whereType('id', ['string', 'integer'])
- );
+```php
+$response->assertJson(fn (AssertableJson $json) =>
+ $json->whereType('name', 'string|null')
+ ->whereType('id', ['string', 'integer'])
+);
+```
The `whereType` and `whereAllType` methods recognize the following types: `string`, `integer`, `double`, `boolean`, `array`, and `null`.
@@ -481,112 +784,159 @@ The `whereType` and `whereAllType` methods recognize the following types: `strin
The `Illuminate\Http\UploadedFile` class provides a `fake` method which may be used to generate dummy files or images for testing. This, combined with the `Storage` facade's `fake` method, greatly simplifies the testing of file uploads. For example, you may combine these two features to easily test an avatar upload form:
- image('avatar.jpg');
- class ExampleTest extends TestCase
+ $response = $this->post('/avatar', [
+ 'avatar' => $file,
+ ]);
+
+ Storage::disk('avatars')->assertExists($file->hashName());
+});
+```
+
+```php tab=PHPUnit
+image('avatar.jpg');
+ $file = UploadedFile::fake()->image('avatar.jpg');
- $response = $this->post('/avatar', [
- 'avatar' => $file,
- ]);
+ $response = $this->post('/avatar', [
+ 'avatar' => $file,
+ ]);
- Storage::disk('avatars')->assertExists($file->hashName());
- }
+ Storage::disk('avatars')->assertExists($file->hashName());
}
+}
+```
If you would like to assert that a given file does not exist, you may use the `assertMissing` method provided by the `Storage` facade:
- Storage::fake('avatars');
+```php
+Storage::fake('avatars');
- // ...
+// ...
- Storage::disk('avatars')->assertMissing('missing.jpg');
+Storage::disk('avatars')->assertMissing('missing.jpg');
+```
#### Fake File Customization
When creating files using the `fake` method provided by the `UploadedFile` class, you may specify the width, height, and size of the image (in kilobytes) in order to better test your application's validation rules:
- UploadedFile::fake()->image('avatar.jpg', $width, $height)->size(100);
+```php
+UploadedFile::fake()->image('avatar.jpg', $width, $height)->size(100);
+```
In addition to creating images, you may create files of any other type using the `create` method:
- UploadedFile::fake()->create('document.pdf', $sizeInKilobytes);
+```php
+UploadedFile::fake()->create('document.pdf', $sizeInKilobytes);
+```
If needed, you may pass a `$mimeType` argument to the method to explicitly define the MIME type that should be returned by the file:
- UploadedFile::fake()->create(
- 'document.pdf', $sizeInKilobytes, 'application/pdf'
- );
+```php
+UploadedFile::fake()->create(
+ 'document.pdf', $sizeInKilobytes, 'application/pdf'
+);
+```
## Testing Views
Laravel also allows you to render a view without making a simulated HTTP request to the application. To accomplish this, you may call the `view` method within your test. The `view` method accepts the view name and an optional array of data. The method returns an instance of `Illuminate\Testing\TestView`, which offers several methods to conveniently make assertions about the view's contents:
- view('welcome', ['name' => 'Taylor']);
+
+ $view->assertSee('Taylor');
+});
+```
+
+```php tab=PHPUnit
+view('welcome', ['name' => 'Taylor']);
+ $view = $this->view('welcome', ['name' => 'Taylor']);
- $view->assertSee('Taylor');
- }
+ $view->assertSee('Taylor');
}
+}
+```
The `TestView` class provides the following assertion methods: `assertSee`, `assertSeeInOrder`, `assertSeeText`, `assertSeeTextInOrder`, `assertDontSee`, and `assertDontSeeText`.
If needed, you may get the raw, rendered view contents by casting the `TestView` instance to a string:
- $contents = (string) $this->view('welcome');
+```php
+$contents = (string) $this->view('welcome');
+```
#### Sharing Errors
Some views may depend on errors shared in the [global error bag provided by Laravel](/docs/{{version}}/validation#quick-displaying-the-validation-errors). To hydrate the error bag with error messages, you may use the `withViewErrors` method:
- $view = $this->withViewErrors([
- 'name' => ['Please provide a valid name.']
- ])->view('form');
+```php
+$view = $this->withViewErrors([
+ 'name' => ['Please provide a valid name.']
+])->view('form');
- $view->assertSee('Please provide a valid name.');
+$view->assertSee('Please provide a valid name.');
+```
-### Rendering Blade & Components
+### Rendering Blade and Components
If necessary, you may use the `blade` method to evaluate and render a raw [Blade](/docs/{{version}}/blade) string. Like the `view` method, the `blade` method returns an instance of `Illuminate\Testing\TestView`:
- $view = $this->blade(
- '/example-app`. The `github` flag assumes you have properly installed the [GitHub CLI](https://cli.github.com) and are authenticated with GitHub. Additionally, you should have `git` installed and properly configured. If needed, you can pass additional flags that are supported by the GitHub CLI:
+For those seeking a cloud-based development experience, [Firebase Studio](https://firebase.studio/) provides instant access to building with Laravel directly in your browser. With zero setup required, Firebase Studio makes it easy to start building Laravel applications from any device.
-```shell
-laravel new example-app --github="--public"
-```
+
+## Laravel and AI
-You may use the `--organization` flag to create the repository under a specific GitHub organization:
+[Laravel Boost](https://github.com/laravel/boost) is a powerful tool that bridges the gap between AI coding agents and Laravel applications. Boost provides AI agents with Laravel-specific context, tools, and guidelines so they can generate more accurate, version-specific code that follows Laravel conventions.
-```shell
-laravel new example-app --github="--public" --organization="laravel"
-```
+When you install Boost in your Laravel application, AI agents gain access to over 15 specialized tools including the ability to know which packages you are using, query your database, search the Laravel documentation, read browser logs, generate tests, and execute code via Tinker.
-
-## Initial Configuration
+In addition, Boost gives AI agents access to over 17,000 pieces of vectorized Laravel ecosystem documentation, specific to your installed package versions. This means agents can provide guidance targeted to the exact versions your project uses.
-All of the configuration files for the Laravel framework are stored in the `config` directory. Each option is documented, so feel free to look through the files and get familiar with the options available to you.
+Boost also includes Laravel-maintained AI guidelines that help agents to follow framework conventions, write appropriate tests, and avoid common pitfalls when generating Laravel code.
-Laravel needs almost no additional configuration out of the box. You are free to get started developing! However, you may wish to review the `config/app.php` file and its documentation. It contains several options such as `timezone` and `locale` that you may wish to change according to your application.
+
+### Installing Laravel Boost
-
-### Environment Based Configuration
+Boost can be installed in Laravel 10, 11, and 12 applications running PHP 8.1 or higher. To get started, install Boost as a development dependency:
-Since many of Laravel's configuration option values may vary depending on whether your application is running on your local computer or on a production web server, many important configuration values are defined using the `.env` file that exists at the root of your application.
+```shell
+composer require laravel/boost --dev
+```
-Your `.env` file should not be committed to your application's source control, since each developer / server using your application could require a different environment configuration. Furthermore, this would be a security risk in the event an intruder gains access to your source control repository, since any sensitive credentials would get exposed.
+Once installed, run the interactive installer:
-> {tip} For more information about the `.env` file and environment based configuration, check out the full [configuration documentation](/docs/{{version}}/configuration#environment-configuration).
+```shell
+php artisan boost:install
+```
-
-### Directory Configuration
+The installer will auto-detect your IDE and AI agents, allowing you to opt into the features that make sense for your project. Boost respects existing project conventions and doesn't force opinionated style rules by default.
-Laravel should always be served out of the root of the "web directory" configured for your web server. You should not attempt to serve a Laravel application out of a subdirectory of the "web directory". Attempting to do so could expose sensitive files that exist within your application.
+> [!NOTE]
+> To learn more about Boost, check out the [Laravel Boost repository on GitHub](https://github.com/laravel/boost).
## Next Steps
-Now that you have created your Laravel project, you may be wondering what to learn next. First, we strongly recommend becoming familiar with how Laravel works by reading the following documentation:
+Now that you have created your Laravel application, you may be wondering what to learn next. First, we strongly recommend becoming familiar with how Laravel works by reading the following documentation:
+[after](#method-after)
[all](#method-all)
[average](#method-average)
[avg](#method-avg)
+[before](#method-before)
[chunk](#method-chunk)
[chunkWhile](#method-chunkwhile)
[collapse](#method-collapse)
+[collapseWithKeys](#method-collapsewithkeys)
[collect](#method-collect)
[combine](#method-combine)
[concat](#method-concat)
[contains](#method-contains)
+[containsOneItem](#method-containsoneitem)
[containsStrict](#method-containsstrict)
[count](#method-count)
[countBy](#method-countBy)
@@ -108,28 +125,38 @@ For the majority of the remaining collection documentation, we'll discuss each m
[dd](#method-dd)
[diff](#method-diff)
[diffAssoc](#method-diffassoc)
+[diffAssocUsing](#method-diffassocusing)
[diffKeys](#method-diffkeys)
[doesntContain](#method-doesntcontain)
+[doesntContainStrict](#method-doesntcontainstrict)
+[dot](#method-dot)
[dump](#method-dump)
[duplicates](#method-duplicates)
[duplicatesStrict](#method-duplicatesstrict)
[each](#method-each)
[eachSpread](#method-eachspread)
+[ensure](#method-ensure)
[every](#method-every)
[except](#method-except)
[filter](#method-filter)
[first](#method-first)
+[firstOrFail](#method-first-or-fail)
[firstWhere](#method-first-where)
[flatMap](#method-flatmap)
[flatten](#method-flatten)
[flip](#method-flip)
[forget](#method-forget)
[forPage](#method-forpage)
+[fromJson](#method-fromjson)
[get](#method-get)
[groupBy](#method-groupby)
[has](#method-has)
+[hasAny](#method-hasany)
[implode](#method-implode)
[intersect](#method-intersect)
+[intersectUsing](#method-intersectusing)
+[intersectAssoc](#method-intersectAssoc)
+[intersectAssocUsing](#method-intersectassocusing)
[intersectByKeys](#method-intersectbykeys)
[isEmpty](#method-isempty)
[isNotEmpty](#method-isnotempty)
@@ -137,6 +164,7 @@ For the majority of the remaining collection documentation, we'll discuss each m
[keyBy](#method-keyby)
[keys](#method-keys)
[last](#method-last)
+[lazy](#method-lazy)
[macro](#method-macro)
[make](#method-make)
[map](#method-map)
@@ -150,10 +178,12 @@ For the majority of the remaining collection documentation, we'll discuss each m
[mergeRecursive](#method-mergerecursive)
[min](#method-min)
[mode](#method-mode)
+[multiply](#method-multiply)
[nth](#method-nth)
[only](#method-only)
[pad](#method-pad)
[partition](#method-partition)
+[percentage](#method-percentage)
[pipe](#method-pipe)
[pipeInto](#method-pipeinto)
[pipeThrough](#method-pipethrough)
@@ -166,20 +196,20 @@ For the majority of the remaining collection documentation, we'll discuss each m
[random](#method-random)
[range](#method-range)
[reduce](#method-reduce)
-[reduceMany](#method-reduce-many)
[reduceSpread](#method-reduce-spread)
[reject](#method-reject)
[replace](#method-replace)
[replaceRecursive](#method-replacerecursive)
[reverse](#method-reverse)
[search](#method-search)
+[select](#method-select)
[shift](#method-shift)
[shuffle](#method-shuffle)
-[sliding](#method-sliding)
[skip](#method-skip)
[skipUntil](#method-skipuntil)
[skipWhile](#method-skipwhile)
[slice](#method-slice)
+[sliding](#method-sliding)
[sole](#method-sole)
[some](#method-some)
[sort](#method-sort)
@@ -200,6 +230,7 @@ For the majority of the remaining collection documentation, we'll discuss each m
[times](#method-times)
[toArray](#method-toarray)
[toJson](#method-tojson)
+[toPrettyJson](#method-to-pretty-json)
[transform](#method-transform)
[undot](#method-undot)
[union](#method-union)
@@ -209,6 +240,7 @@ For the majority of the remaining collection documentation, we'll discuss each m
[unlessEmpty](#method-unlessempty)
[unlessNotEmpty](#method-unlessnotempty)
[unwrap](#method-unwrap)
+[value](#method-value)
[values](#method-values)
[when](#method-when)
[whenEmpty](#method-whenempty)
@@ -242,52 +274,120 @@ For the majority of the remaining collection documentation, we'll discuss each m
}
+
+#### `after()` {.collection-method .first-collection-method}
+
+The `after` method returns the item after the given item. `null` is returned if the given item is not found or is the last item:
+
+```php
+$collection = collect([1, 2, 3, 4, 5]);
+
+$collection->after(3);
+
+// 4
+
+$collection->after(5);
+
+// null
+```
+
+This method searches for the given item using "loose" comparison, meaning a string containing an integer value will be considered equal to an integer of the same value. To use "strict" comparison, you may provide the `strict` argument to the method:
+
+```php
+collect([2, 4, 6, 8])->after('4', strict: true);
+
+// null
+```
+
+Alternatively, you may provide your own closure to search for the first item that passes a given truth test:
+
+```php
+collect([2, 4, 6, 8])->after(function (int $item, int $key) {
+ return $item > 5;
+});
+
+// 8
+```
+
-#### `all()` {.collection-method .first-collection-method}
+#### `all()` {.collection-method}
The `all` method returns the underlying array represented by the collection:
- collect([1, 2, 3])->all();
+```php
+collect([1, 2, 3])->all();
- // [1, 2, 3]
+// [1, 2, 3]
+```
#### `average()` {.collection-method}
-Alias for the [`avg`](#method-avg) method.
+Alias for the [avg](#method-avg) method.
#### `avg()` {.collection-method}
The `avg` method returns the [average value](https://en.wikipedia.org/wiki/Average) of a given key:
- $average = collect([
- ['foo' => 10],
- ['foo' => 10],
- ['foo' => 20],
- ['foo' => 40]
- ])->avg('foo');
+```php
+$average = collect([
+ ['foo' => 10],
+ ['foo' => 10],
+ ['foo' => 20],
+ ['foo' => 40]
+])->avg('foo');
+
+// 20
+
+$average = collect([1, 1, 2, 4])->avg();
+
+// 2
+```
+
+
+#### `before()` {.collection-method}
+
+The `before` method is the opposite of the [after](#method-after) method. It returns the item before the given item. `null` is returned if the given item is not found or is the first item:
- // 20
+```php
+$collection = collect([1, 2, 3, 4, 5]);
- $average = collect([1, 1, 2, 4])->avg();
+$collection->before(3);
- // 2
+// 2
+
+$collection->before(1);
+
+// null
+
+collect([2, 4, 6, 8])->before('4', strict: true);
+
+// null
+
+collect([2, 4, 6, 8])->before(function (int $item, int $key) {
+ return $item > 5;
+});
+
+// 4
+```
#### `chunk()` {.collection-method}
The `chunk` method breaks the collection into multiple, smaller collections of a given size:
- $collection = collect([1, 2, 3, 4, 5, 6, 7]);
+```php
+$collection = collect([1, 2, 3, 4, 5, 6, 7]);
- $chunks = $collection->chunk(4);
+$chunks = $collection->chunk(4);
- $chunks->all();
+$chunks->all();
- // [[1, 2, 3, 4], [5, 6, 7]]
+// [[1, 2, 3, 4], [5, 6, 7]]
+```
-This method is especially useful in [views](/docs/{{version}}/views) when working with a grid system such as [Bootstrap](https://getbootstrap.com/docs/4.1/layout/grid/). For example, imagine you have a collection of [Eloquent](/docs/{{version}}/eloquent) models you want to display in a grid:
+This method is especially useful in [views](/docs/{{version}}/views) when working with a grid system such as [Bootstrap](https://getbootstrap.com/docs/5.3/layout/grid/). For example, imagine you have a collection of [Eloquent](/docs/{{version}}/eloquent) models you want to display in a grid:
```blade
@foreach ($products->chunk(3) as $chunk)
@@ -304,91 +404,127 @@ This method is especially useful in [views](/docs/{{version}}/views) when workin
The `chunkWhile` method breaks the collection into multiple, smaller collections based on the evaluation of the given callback. The `$chunk` variable passed to the closure may be used to inspect the previous element:
- $collection = collect(str_split('AABBCCCD'));
+```php
+$collection = collect(str_split('AABBCCCD'));
- $chunks = $collection->chunkWhile(function ($value, $key, $chunk) {
- return $value === $chunk->last();
- });
+$chunks = $collection->chunkWhile(function (string $value, int $key, Collection $chunk) {
+ return $value === $chunk->last();
+});
- $chunks->all();
+$chunks->all();
- // [['A', 'A'], ['B', 'B'], ['C', 'C', 'C'], ['D']]
+// [['A', 'A'], ['B', 'B'], ['C', 'C', 'C'], ['D']]
+```
#### `collapse()` {.collection-method}
-The `collapse` method collapses a collection of arrays into a single, flat collection:
+The `collapse` method collapses a collection of arrays or collections into a single, flat collection:
+
+```php
+$collection = collect([
+ [1, 2, 3],
+ [4, 5, 6],
+ [7, 8, 9],
+]);
+
+$collapsed = $collection->collapse();
+
+$collapsed->all();
+
+// [1, 2, 3, 4, 5, 6, 7, 8, 9]
+```
+
+
+#### `collapseWithKeys()` {.collection-method}
- $collection = collect([
- [1, 2, 3],
- [4, 5, 6],
- [7, 8, 9],
- ]);
+The `collapseWithKeys` method flattens a collection of arrays or collections into a single collection, keeping the original keys intact. If the collection is already flat, it will return an empty collection:
- $collapsed = $collection->collapse();
+```php
+$collection = collect([
+ ['first' => collect([1, 2, 3])],
+ ['second' => [4, 5, 6]],
+ ['third' => collect([7, 8, 9])]
+]);
- $collapsed->all();
+$collapsed = $collection->collapseWithKeys();
- // [1, 2, 3, 4, 5, 6, 7, 8, 9]
+$collapsed->all();
+
+// [
+// 'first' => [1, 2, 3],
+// 'second' => [4, 5, 6],
+// 'third' => [7, 8, 9],
+// ]
+```
#### `collect()` {.collection-method}
The `collect` method returns a new `Collection` instance with the items currently in the collection:
- $collectionA = collect([1, 2, 3]);
+```php
+$collectionA = collect([1, 2, 3]);
- $collectionB = $collectionA->collect();
+$collectionB = $collectionA->collect();
- $collectionB->all();
+$collectionB->all();
- // [1, 2, 3]
+// [1, 2, 3]
+```
The `collect` method is primarily useful for converting [lazy collections](#lazy-collections) into standard `Collection` instances:
- $lazyCollection = LazyCollection::make(function () {
- yield 1;
- yield 2;
- yield 3;
- });
+```php
+$lazyCollection = LazyCollection::make(function () {
+ yield 1;
+ yield 2;
+ yield 3;
+});
- $collection = $lazyCollection->collect();
+$collection = $lazyCollection->collect();
- get_class($collection);
+$collection::class;
- // 'Illuminate\Support\Collection'
+// 'Illuminate\Support\Collection'
- $collection->all();
+$collection->all();
- // [1, 2, 3]
+// [1, 2, 3]
+```
-> {tip} The `collect` method is especially useful when you have an instance of `Enumerable` and need a non-lazy collection instance. Since `collect()` is part of the `Enumerable` contract, you can safely use it to get a `Collection` instance.
+> [!NOTE]
+> The `collect` method is especially useful when you have an instance of `Enumerable` and need a non-lazy collection instance. Since `collect()` is part of the `Enumerable` contract, you can safely use it to get a `Collection` instance.
#### `combine()` {.collection-method}
The `combine` method combines the values of the collection, as keys, with the values of another array or collection:
- $collection = collect(['name', 'age']);
+```php
+$collection = collect(['name', 'age']);
- $combined = $collection->combine(['George', 29]);
+$combined = $collection->combine(['George', 29]);
- $combined->all();
+$combined->all();
- // ['name' => 'George', 'age' => 29]
+// ['name' => 'George', 'age' => 29]
+```
#### `concat()` {.collection-method}
-The `concat` method appends the given `array` or collection's values onto the end of another collection:
+The `concat` method appends the given array or collection's values onto the end of another collection:
- $collection = collect(['John Doe']);
+```php
+$collection = collect(['John Doe']);
- $concatenated = $collection->concat(['Jane Doe'])->concat(['name' => 'Johnny Doe']);
+$concatenated = $collection->concat(['Jane Doe'])->concat(['name' => 'Johnny Doe']);
- $concatenated->all();
+$concatenated->all();
- // ['John Doe', 'Jane Doe', 'Johnny Doe']
+// ['John Doe', 'Jane Doe', 'Johnny Doe']
+```
The `concat` method numerically reindexes keys for items concatenated onto the original collection. To maintain keys in associative collections, see the [merge](#method-merge) method.
@@ -397,384 +533,525 @@ The `concat` method numerically reindexes keys for items concatenated onto the o
The `contains` method determines whether the collection contains a given item. You may pass a closure to the `contains` method to determine if an element exists in the collection matching a given truth test:
- $collection = collect([1, 2, 3, 4, 5]);
+```php
+$collection = collect([1, 2, 3, 4, 5]);
- $collection->contains(function ($value, $key) {
- return $value > 5;
- });
+$collection->contains(function (int $value, int $key) {
+ return $value > 5;
+});
- // false
+// false
+```
Alternatively, you may pass a string to the `contains` method to determine whether the collection contains a given item value:
- $collection = collect(['name' => 'Desk', 'price' => 100]);
+```php
+$collection = collect(['name' => 'Desk', 'price' => 100]);
- $collection->contains('Desk');
+$collection->contains('Desk');
- // true
+// true
- $collection->contains('New York');
+$collection->contains('New York');
- // false
+// false
+```
You may also pass a key / value pair to the `contains` method, which will determine if the given pair exists in the collection:
- $collection = collect([
- ['product' => 'Desk', 'price' => 200],
- ['product' => 'Chair', 'price' => 100],
- ]);
+```php
+$collection = collect([
+ ['product' => 'Desk', 'price' => 200],
+ ['product' => 'Chair', 'price' => 100],
+]);
- $collection->contains('product', 'Bookcase');
+$collection->contains('product', 'Bookcase');
- // false
+// false
+```
-The `contains` method uses "loose" comparisons when checking item values, meaning a string with an integer value will be considered equal to an integer of the same value. Use the [`containsStrict`](#method-containsstrict) method to filter using "strict" comparisons.
+The `contains` method uses "loose" comparisons when checking item values, meaning a string with an integer value will be considered equal to an integer of the same value. Use the [containsStrict](#method-containsstrict) method to filter using "strict" comparisons.
For the inverse of `contains`, see the [doesntContain](#method-doesntcontain) method.
+
+#### `containsOneItem()` {.collection-method}
+
+The `containsOneItem` method determines whether the collection contains a single item:
+
+```php
+collect([])->containsOneItem();
+
+// false
+
+collect(['1'])->containsOneItem();
+
+// true
+
+collect(['1', '2'])->containsOneItem();
+
+// false
+
+collect([1, 2, 3])->containsOneItem(fn (int $item) => $item === 2);
+
+// true
+```
+
#### `containsStrict()` {.collection-method}
-This method has the same signature as the [`contains`](#method-contains) method; however, all values are compared using "strict" comparisons.
+This method has the same signature as the [contains](#method-contains) method; however, all values are compared using "strict" comparisons.
-> {tip} This method's behavior is modified when using [Eloquent Collections](/docs/{{version}}/eloquent-collections#method-contains).
+> [!NOTE]
+> This method's behavior is modified when using [Eloquent Collections](/docs/{{version}}/eloquent-collections#method-contains).
#### `count()` {.collection-method}
The `count` method returns the total number of items in the collection:
- $collection = collect([1, 2, 3, 4]);
+```php
+$collection = collect([1, 2, 3, 4]);
- $collection->count();
+$collection->count();
- // 4
+// 4
+```
#### `countBy()` {.collection-method}
The `countBy` method counts the occurrences of values in the collection. By default, the method counts the occurrences of every element, allowing you to count certain "types" of elements in the collection:
- $collection = collect([1, 2, 2, 2, 3]);
+```php
+$collection = collect([1, 2, 2, 2, 3]);
- $counted = $collection->countBy();
+$counted = $collection->countBy();
- $counted->all();
+$counted->all();
- // [1 => 1, 2 => 3, 3 => 1]
+// [1 => 1, 2 => 3, 3 => 1]
+```
-You pass a closure to the `countBy` method to count all items by a custom value:
+You may pass a closure to the `countBy` method to count all items by a custom value:
- $collection = collect(['alice@gmail.com', 'bob@yahoo.com', 'carlos@gmail.com']);
+```php
+$collection = collect(['alice@gmail.com', 'bob@yahoo.com', 'carlos@gmail.com']);
- $counted = $collection->countBy(function ($email) {
- return substr(strrchr($email, "@"), 1);
- });
+$counted = $collection->countBy(function (string $email) {
+ return substr(strrchr($email, '@'), 1);
+});
- $counted->all();
+$counted->all();
- // ['gmail.com' => 2, 'yahoo.com' => 1]
+// ['gmail.com' => 2, 'yahoo.com' => 1]
+```
#### `crossJoin()` {.collection-method}
The `crossJoin` method cross joins the collection's values among the given arrays or collections, returning a Cartesian product with all possible permutations:
- $collection = collect([1, 2]);
+```php
+$collection = collect([1, 2]);
- $matrix = $collection->crossJoin(['a', 'b']);
+$matrix = $collection->crossJoin(['a', 'b']);
- $matrix->all();
+$matrix->all();
- /*
- [
- [1, 'a'],
- [1, 'b'],
- [2, 'a'],
- [2, 'b'],
- ]
- */
+/*
+ [
+ [1, 'a'],
+ [1, 'b'],
+ [2, 'a'],
+ [2, 'b'],
+ ]
+*/
- $collection = collect([1, 2]);
+$collection = collect([1, 2]);
- $matrix = $collection->crossJoin(['a', 'b'], ['I', 'II']);
+$matrix = $collection->crossJoin(['a', 'b'], ['I', 'II']);
- $matrix->all();
+$matrix->all();
- /*
- [
- [1, 'a', 'I'],
- [1, 'a', 'II'],
- [1, 'b', 'I'],
- [1, 'b', 'II'],
- [2, 'a', 'I'],
- [2, 'a', 'II'],
- [2, 'b', 'I'],
- [2, 'b', 'II'],
- ]
- */
+/*
+ [
+ [1, 'a', 'I'],
+ [1, 'a', 'II'],
+ [1, 'b', 'I'],
+ [1, 'b', 'II'],
+ [2, 'a', 'I'],
+ [2, 'a', 'II'],
+ [2, 'b', 'I'],
+ [2, 'b', 'II'],
+ ]
+*/
+```
#### `dd()` {.collection-method}
The `dd` method dumps the collection's items and ends execution of the script:
- $collection = collect(['John Doe', 'Jane Doe']);
+```php
+$collection = collect(['John Doe', 'Jane Doe']);
- $collection->dd();
+$collection->dd();
- /*
- Collection {
- #items: array:2 [
- 0 => "John Doe"
- 1 => "Jane Doe"
- ]
- }
- */
+/*
+ array:2 [
+ 0 => "John Doe"
+ 1 => "Jane Doe"
+ ]
+*/
+```
-If you do not want to stop executing the script, use the [`dump`](#method-dump) method instead.
+If you do not want to stop executing the script, use the [dump](#method-dump) method instead.
#### `diff()` {.collection-method}
The `diff` method compares the collection against another collection or a plain PHP `array` based on its values. This method will return the values in the original collection that are not present in the given collection:
- $collection = collect([1, 2, 3, 4, 5]);
+```php
+$collection = collect([1, 2, 3, 4, 5]);
- $diff = $collection->diff([2, 4, 6, 8]);
+$diff = $collection->diff([2, 4, 6, 8]);
- $diff->all();
+$diff->all();
- // [1, 3, 5]
+// [1, 3, 5]
+```
-> {tip} This method's behavior is modified when using [Eloquent Collections](/docs/{{version}}/eloquent-collections#method-diff).
+> [!NOTE]
+> This method's behavior is modified when using [Eloquent Collections](/docs/{{version}}/eloquent-collections#method-diff).
#### `diffAssoc()` {.collection-method}
The `diffAssoc` method compares the collection against another collection or a plain PHP `array` based on its keys and values. This method will return the key / value pairs in the original collection that are not present in the given collection:
- $collection = collect([
- 'color' => 'orange',
- 'type' => 'fruit',
- 'remain' => 6,
- ]);
+```php
+$collection = collect([
+ 'color' => 'orange',
+ 'type' => 'fruit',
+ 'remain' => 6,
+]);
- $diff = $collection->diffAssoc([
- 'color' => 'yellow',
- 'type' => 'fruit',
- 'remain' => 3,
- 'used' => 6,
- ]);
+$diff = $collection->diffAssoc([
+ 'color' => 'yellow',
+ 'type' => 'fruit',
+ 'remain' => 3,
+ 'used' => 6,
+]);
- $diff->all();
+$diff->all();
- // ['color' => 'orange', 'remain' => 6]
+// ['color' => 'orange', 'remain' => 6]
+```
-
-#### `diffKeys()` {.collection-method}
+
+#### `diffAssocUsing()` {.collection-method}
-The `diffKeys` method compares the collection against another collection or a plain PHP `array` based on its keys. This method will return the key / value pairs in the original collection that are not present in the given collection:
+Unlike `diffAssoc`, `diffAssocUsing` accepts a user supplied callback function for the indices comparison:
- $collection = collect([
- 'one' => 10,
- 'two' => 20,
- 'three' => 30,
- 'four' => 40,
- 'five' => 50,
- ]);
+```php
+$collection = collect([
+ 'color' => 'orange',
+ 'type' => 'fruit',
+ 'remain' => 6,
+]);
- $diff = $collection->diffKeys([
- 'two' => 2,
- 'four' => 4,
- 'six' => 6,
- 'eight' => 8,
- ]);
+$diff = $collection->diffAssocUsing([
+ 'Color' => 'yellow',
+ 'Type' => 'fruit',
+ 'Remain' => 3,
+], 'strnatcasecmp');
- $diff->all();
+$diff->all();
+
+// ['color' => 'orange', 'remain' => 6]
+```
+
+The callback must be a comparison function that returns an integer less than, equal to, or greater than zero. For more information, refer to the PHP documentation on [array_diff_uassoc](https://www.php.net/array_diff_uassoc#refsect1-function.array-diff-uassoc-parameters), which is the PHP function that the `diffAssocUsing` method utilizes internally.
+
+
+#### `diffKeys()` {.collection-method}
+
+The `diffKeys` method compares the collection against another collection or a plain PHP `array` based on its keys. This method will return the key / value pairs in the original collection that are not present in the given collection:
- // ['one' => 10, 'three' => 30, 'five' => 50]
+```php
+$collection = collect([
+ 'one' => 10,
+ 'two' => 20,
+ 'three' => 30,
+ 'four' => 40,
+ 'five' => 50,
+]);
+
+$diff = $collection->diffKeys([
+ 'two' => 2,
+ 'four' => 4,
+ 'six' => 6,
+ 'eight' => 8,
+]);
+
+$diff->all();
+
+// ['one' => 10, 'three' => 30, 'five' => 50]
+```
#### `doesntContain()` {.collection-method}
The `doesntContain` method determines whether the collection does not contain a given item. You may pass a closure to the `doesntContain` method to determine if an element does not exist in the collection matching a given truth test:
- $collection = collect([1, 2, 3, 4, 5]);
+```php
+$collection = collect([1, 2, 3, 4, 5]);
- $collection->doesntContain(function ($value, $key) {
- return $value < 5;
- });
+$collection->doesntContain(function (int $value, int $key) {
+ return $value < 5;
+});
- // false
+// false
+```
Alternatively, you may pass a string to the `doesntContain` method to determine whether the collection does not contain a given item value:
- $collection = collect(['name' => 'Desk', 'price' => 100]);
+```php
+$collection = collect(['name' => 'Desk', 'price' => 100]);
- $collection->doesntContain('Table');
+$collection->doesntContain('Table');
- // true
+// true
- $collection->doesntContain('Desk');
+$collection->doesntContain('Desk');
- // false
+// false
+```
You may also pass a key / value pair to the `doesntContain` method, which will determine if the given pair does not exist in the collection:
- $collection = collect([
- ['product' => 'Desk', 'price' => 200],
- ['product' => 'Chair', 'price' => 100],
- ]);
+```php
+$collection = collect([
+ ['product' => 'Desk', 'price' => 200],
+ ['product' => 'Chair', 'price' => 100],
+]);
- $collection->doesntContain('product', 'Bookcase');
+$collection->doesntContain('product', 'Bookcase');
- // true
+// true
+```
The `doesntContain` method uses "loose" comparisons when checking item values, meaning a string with an integer value will be considered equal to an integer of the same value.
+
+#### `doesntContainStrict()` {.collection-method}
+
+This method has the same signature as the [doesntContain](#method-doesntcontain) method; however, all values are compared using "strict" comparisons.
+
+
+#### `dot()` {.collection-method}
+
+The `dot` method flattens a multi-dimensional collection into a single level collection that uses "dot" notation to indicate depth:
+
+```php
+$collection = collect(['products' => ['desk' => ['price' => 100]]]);
+
+$flattened = $collection->dot();
+
+$flattened->all();
+
+// ['products.desk.price' => 100]
+```
+
#### `dump()` {.collection-method}
The `dump` method dumps the collection's items:
- $collection = collect(['John Doe', 'Jane Doe']);
+```php
+$collection = collect(['John Doe', 'Jane Doe']);
- $collection->dump();
+$collection->dump();
- /*
- Collection {
- #items: array:2 [
- 0 => "John Doe"
- 1 => "Jane Doe"
- ]
- }
- */
+/*
+ array:2 [
+ 0 => "John Doe"
+ 1 => "Jane Doe"
+ ]
+*/
+```
-If you want to stop executing the script after dumping the collection, use the [`dd`](#method-dd) method instead.
+If you want to stop executing the script after dumping the collection, use the [dd](#method-dd) method instead.
#### `duplicates()` {.collection-method}
The `duplicates` method retrieves and returns duplicate values from the collection:
- $collection = collect(['a', 'b', 'a', 'c', 'b']);
+```php
+$collection = collect(['a', 'b', 'a', 'c', 'b']);
- $collection->duplicates();
+$collection->duplicates();
- // [2 => 'a', 4 => 'b']
+// [2 => 'a', 4 => 'b']
+```
If the collection contains arrays or objects, you can pass the key of the attributes that you wish to check for duplicate values:
- $employees = collect([
- ['email' => 'abigail@example.com', 'position' => 'Developer'],
- ['email' => 'james@example.com', 'position' => 'Designer'],
- ['email' => 'victoria@example.com', 'position' => 'Developer'],
- ]);
+```php
+$employees = collect([
+ ['email' => 'abigail@example.com', 'position' => 'Developer'],
+ ['email' => 'james@example.com', 'position' => 'Designer'],
+ ['email' => 'victoria@example.com', 'position' => 'Developer'],
+]);
- $employees->duplicates('position');
+$employees->duplicates('position');
- // [2 => 'Developer']
+// [2 => 'Developer']
+```
#### `duplicatesStrict()` {.collection-method}
-This method has the same signature as the [`duplicates`](#method-duplicates) method; however, all values are compared using "strict" comparisons.
+This method has the same signature as the [duplicates](#method-duplicates) method; however, all values are compared using "strict" comparisons.
#### `each()` {.collection-method}
The `each` method iterates over the items in the collection and passes each item to a closure:
- $collection->each(function ($item, $key) {
- //
- });
+```php
+$collection = collect([1, 2, 3, 4]);
+
+$collection->each(function (int $item, int $key) {
+ // ...
+});
+```
If you would like to stop iterating through the items, you may return `false` from your closure:
- $collection->each(function ($item, $key) {
- if (/* condition */) {
- return false;
- }
- });
+```php
+$collection->each(function (int $item, int $key) {
+ if (/* condition */) {
+ return false;
+ }
+});
+```
#### `eachSpread()` {.collection-method}
The `eachSpread` method iterates over the collection's items, passing each nested item value into the given callback:
- $collection = collect([['John Doe', 35], ['Jane Doe', 33]]);
+```php
+$collection = collect([['John Doe', 35], ['Jane Doe', 33]]);
- $collection->eachSpread(function ($name, $age) {
- //
- });
+$collection->eachSpread(function (string $name, int $age) {
+ // ...
+});
+```
You may stop iterating through the items by returning `false` from the callback:
- $collection->eachSpread(function ($name, $age) {
- return false;
- });
+```php
+$collection->eachSpread(function (string $name, int $age) {
+ return false;
+});
+```
+
+
+#### `ensure()` {.collection-method}
+
+The `ensure` method may be used to verify that all elements of a collection are of a given type or list of types. Otherwise, an `UnexpectedValueException` will be thrown:
+
+```php
+return $collection->ensure(User::class);
+
+return $collection->ensure([User::class, Customer::class]);
+```
+
+Primitive types such as `string`, `int`, `float`, `bool`, and `array` may also be specified:
+
+```php
+return $collection->ensure('int');
+```
+
+> [!WARNING]
+> The `ensure` method does not guarantee that elements of different types will not be added to the collection at a later time.
#### `every()` {.collection-method}
The `every` method may be used to verify that all elements of a collection pass a given truth test:
- collect([1, 2, 3, 4])->every(function ($value, $key) {
- return $value > 2;
- });
+```php
+collect([1, 2, 3, 4])->every(function (int $value, int $key) {
+ return $value > 2;
+});
- // false
+// false
+```
If the collection is empty, the `every` method will return true:
- $collection = collect([]);
+```php
+$collection = collect([]);
- $collection->every(function ($value, $key) {
- return $value > 2;
- });
+$collection->every(function (int $value, int $key) {
+ return $value > 2;
+});
- // true
+// true
+```
#### `except()` {.collection-method}
The `except` method returns all items in the collection except for those with the specified keys:
- $collection = collect(['product_id' => 1, 'price' => 100, 'discount' => false]);
+```php
+$collection = collect(['product_id' => 1, 'price' => 100, 'discount' => false]);
- $filtered = $collection->except(['price', 'discount']);
+$filtered = $collection->except(['price', 'discount']);
- $filtered->all();
+$filtered->all();
- // ['product_id' => 1]
+// ['product_id' => 1]
+```
For the inverse of `except`, see the [only](#method-only) method.
-> {tip} This method's behavior is modified when using [Eloquent Collections](/docs/{{version}}/eloquent-collections#method-except).
+> [!NOTE]
+> This method's behavior is modified when using [Eloquent Collections](/docs/{{version}}/eloquent-collections#method-except).
#### `filter()` {.collection-method}
The `filter` method filters the collection using the given callback, keeping only those items that pass a given truth test:
- $collection = collect([1, 2, 3, 4]);
+```php
+$collection = collect([1, 2, 3, 4]);
- $filtered = $collection->filter(function ($value, $key) {
- return $value > 2;
- });
+$filtered = $collection->filter(function (int $value, int $key) {
+ return $value > 2;
+});
- $filtered->all();
+$filtered->all();
- // [3, 4]
+// [3, 4]
+```
If no callback is supplied, all entries of the collection that are equivalent to `false` will be removed:
- $collection = collect([1, 2, 3, null, false, '', 0, []]);
+```php
+$collection = collect([1, 2, 3, null, false, '', 0, []]);
- $collection->filter()->all();
+$collection->filter()->all();
- // [1, 2, 3]
+// [1, 2, 3]
+```
For the inverse of `filter`, see the [reject](#method-reject) method.
@@ -783,110 +1060,147 @@ For the inverse of `filter`, see the [reject](#method-reject) method.
The `first` method returns the first element in the collection that passes a given truth test:
- collect([1, 2, 3, 4])->first(function ($value, $key) {
- return $value > 2;
- });
+```php
+collect([1, 2, 3, 4])->first(function (int $value, int $key) {
+ return $value > 2;
+});
- // 3
+// 3
+```
You may also call the `first` method with no arguments to get the first element in the collection. If the collection is empty, `null` is returned:
- collect([1, 2, 3, 4])->first();
+```php
+collect([1, 2, 3, 4])->first();
+
+// 1
+```
+
+
+#### `firstOrFail()` {.collection-method}
+
+The `firstOrFail` method is identical to the `first` method; however, if no result is found, an `Illuminate\Support\ItemNotFoundException` exception will be thrown:
+
+```php
+collect([1, 2, 3, 4])->firstOrFail(function (int $value, int $key) {
+ return $value > 5;
+});
+
+// Throws ItemNotFoundException...
+```
+
+You may also call the `firstOrFail` method with no arguments to get the first element in the collection. If the collection is empty, an `Illuminate\Support\ItemNotFoundException` exception will be thrown:
- // 1
+```php
+collect([])->firstOrFail();
+
+// Throws ItemNotFoundException...
+```
#### `firstWhere()` {.collection-method}
The `firstWhere` method returns the first element in the collection with the given key / value pair:
- $collection = collect([
- ['name' => 'Regena', 'age' => null],
- ['name' => 'Linda', 'age' => 14],
- ['name' => 'Diego', 'age' => 23],
- ['name' => 'Linda', 'age' => 84],
- ]);
+```php
+$collection = collect([
+ ['name' => 'Regena', 'age' => null],
+ ['name' => 'Linda', 'age' => 14],
+ ['name' => 'Diego', 'age' => 23],
+ ['name' => 'Linda', 'age' => 84],
+]);
- $collection->firstWhere('name', 'Linda');
+$collection->firstWhere('name', 'Linda');
- // ['name' => 'Linda', 'age' => 14]
+// ['name' => 'Linda', 'age' => 14]
+```
You may also call the `firstWhere` method with a comparison operator:
- $collection->firstWhere('age', '>=', 18);
+```php
+$collection->firstWhere('age', '>=', 18);
- // ['name' => 'Diego', 'age' => 23]
+// ['name' => 'Diego', 'age' => 23]
+```
Like the [where](#method-where) method, you may pass one argument to the `firstWhere` method. In this scenario, the `firstWhere` method will return the first item where the given item key's value is "truthy":
- $collection->firstWhere('age');
+```php
+$collection->firstWhere('age');
- // ['name' => 'Linda', 'age' => 14]
+// ['name' => 'Linda', 'age' => 14]
+```
#### `flatMap()` {.collection-method}
The `flatMap` method iterates through the collection and passes each value to the given closure. The closure is free to modify the item and return it, thus forming a new collection of modified items. Then, the array is flattened by one level:
- $collection = collect([
- ['name' => 'Sally'],
- ['school' => 'Arkansas'],
- ['age' => 28]
- ]);
+```php
+$collection = collect([
+ ['name' => 'Sally'],
+ ['school' => 'Arkansas'],
+ ['age' => 28]
+]);
- $flattened = $collection->flatMap(function ($values) {
- return array_map('strtoupper', $values);
- });
+$flattened = $collection->flatMap(function (array $values) {
+ return array_map('strtoupper', $values);
+});
- $flattened->all();
+$flattened->all();
- // ['name' => 'SALLY', 'school' => 'ARKANSAS', 'age' => '28'];
+// ['name' => 'SALLY', 'school' => 'ARKANSAS', 'age' => '28'];
+```
#### `flatten()` {.collection-method}
The `flatten` method flattens a multi-dimensional collection into a single dimension:
- $collection = collect([
- 'name' => 'taylor',
- 'languages' => [
- 'php', 'javascript'
- ]
- ]);
+```php
+$collection = collect([
+ 'name' => 'Taylor',
+ 'languages' => [
+ 'PHP', 'JavaScript'
+ ]
+]);
- $flattened = $collection->flatten();
+$flattened = $collection->flatten();
- $flattened->all();
+$flattened->all();
- // ['taylor', 'php', 'javascript'];
+// ['Taylor', 'PHP', 'JavaScript'];
+```
If necessary, you may pass the `flatten` method a "depth" argument:
- $collection = collect([
- 'Apple' => [
- [
- 'name' => 'iPhone 6S',
- 'brand' => 'Apple'
- ],
+```php
+$collection = collect([
+ 'Apple' => [
+ [
+ 'name' => 'iPhone 6S',
+ 'brand' => 'Apple'
],
- 'Samsung' => [
- [
- 'name' => 'Galaxy S7',
- 'brand' => 'Samsung'
- ],
+ ],
+ 'Samsung' => [
+ [
+ 'name' => 'Galaxy S7',
+ 'brand' => 'Samsung'
],
- ]);
+ ],
+]);
- $products = $collection->flatten(1);
+$products = $collection->flatten(1);
- $products->values()->all();
+$products->values()->all();
- /*
- [
- ['name' => 'iPhone 6S', 'brand' => 'Apple'],
- ['name' => 'Galaxy S7', 'brand' => 'Samsung'],
- ]
- */
+/*
+ [
+ ['name' => 'iPhone 6S', 'brand' => 'Apple'],
+ ['name' => 'Galaxy S7', 'brand' => 'Samsung'],
+ ]
+*/
+```
In this example, calling `flatten` without providing the depth would have also flattened the nested arrays, resulting in `['iPhone 6S', 'Apple', 'Galaxy S7', 'Samsung']`. Providing a depth allows you to specify the number of levels nested arrays will be flattened.
@@ -895,322 +1209,510 @@ In this example, calling `flatten` without providing the depth would have also f
The `flip` method swaps the collection's keys with their corresponding values:
- $collection = collect(['name' => 'taylor', 'framework' => 'laravel']);
+```php
+$collection = collect(['name' => 'Taylor', 'framework' => 'Laravel']);
- $flipped = $collection->flip();
+$flipped = $collection->flip();
- $flipped->all();
+$flipped->all();
- // ['taylor' => 'name', 'laravel' => 'framework']
+// ['Taylor' => 'name', 'Laravel' => 'framework']
+```
#### `forget()` {.collection-method}
The `forget` method removes an item from the collection by its key:
- $collection = collect(['name' => 'taylor', 'framework' => 'laravel']);
+```php
+$collection = collect(['name' => 'Taylor', 'framework' => 'Laravel']);
- $collection->forget('name');
+// Forget a single key...
+$collection->forget('name');
- $collection->all();
+// ['framework' => 'Laravel']
- // ['framework' => 'laravel']
+// Forget multiple keys...
+$collection->forget(['name', 'framework']);
-> {note} Unlike most other collection methods, `forget` does not return a new modified collection; it modifies the collection it is called on.
+// []
+```
+
+> [!WARNING]
+> Unlike most other collection methods, `forget` does not return a new modified collection; it modifies and returns the collection it is called on.
#### `forPage()` {.collection-method}
The `forPage` method returns a new collection containing the items that would be present on a given page number. The method accepts the page number as its first argument and the number of items to show per page as its second argument:
- $collection = collect([1, 2, 3, 4, 5, 6, 7, 8, 9]);
+```php
+$collection = collect([1, 2, 3, 4, 5, 6, 7, 8, 9]);
+
+$chunk = $collection->forPage(2, 3);
+
+$chunk->all();
- $chunk = $collection->forPage(2, 3);
+// [4, 5, 6]
+```
+
+
+#### `fromJson()` {.collection-method}
+
+The static `fromJson` method creates a new collection instance by decoding a given JSON string using the `json_decode` PHP function:
+
+```php
+use Illuminate\Support\Collection;
- $chunk->all();
+$json = json_encode([
+ 'name' => 'Taylor Otwell',
+ 'role' => 'Developer',
+ 'status' => 'Active',
+]);
- // [4, 5, 6]
+$collection = Collection::fromJson($json);
+```
#### `get()` {.collection-method}
The `get` method returns the item at a given key. If the key does not exist, `null` is returned:
- $collection = collect(['name' => 'taylor', 'framework' => 'laravel']);
+```php
+$collection = collect(['name' => 'Taylor', 'framework' => 'Laravel']);
- $value = $collection->get('name');
+$value = $collection->get('name');
- // taylor
+// Taylor
+```
You may optionally pass a default value as the second argument:
- $collection = collect(['name' => 'taylor', 'framework' => 'laravel']);
+```php
+$collection = collect(['name' => 'Taylor', 'framework' => 'Laravel']);
- $value = $collection->get('age', 34);
+$value = $collection->get('age', 34);
- // 34
+// 34
+```
You may even pass a callback as the method's default value. The result of the callback will be returned if the specified key does not exist:
- $collection->get('email', function () {
- return 'taylor@example.com';
- });
+```php
+$collection->get('email', function () {
+ return 'taylor@example.com';
+});
- // taylor@example.com
+// taylor@example.com
+```
#### `groupBy()` {.collection-method}
The `groupBy` method groups the collection's items by a given key:
- $collection = collect([
- ['account_id' => 'account-x10', 'product' => 'Chair'],
- ['account_id' => 'account-x10', 'product' => 'Bookcase'],
- ['account_id' => 'account-x11', 'product' => 'Desk'],
- ]);
+```php
+$collection = collect([
+ ['account_id' => 'account-x10', 'product' => 'Chair'],
+ ['account_id' => 'account-x10', 'product' => 'Bookcase'],
+ ['account_id' => 'account-x11', 'product' => 'Desk'],
+]);
- $grouped = $collection->groupBy('account_id');
+$grouped = $collection->groupBy('account_id');
- $grouped->all();
+$grouped->all();
- /*
- [
- 'account-x10' => [
- ['account_id' => 'account-x10', 'product' => 'Chair'],
- ['account_id' => 'account-x10', 'product' => 'Bookcase'],
- ],
- 'account-x11' => [
- ['account_id' => 'account-x11', 'product' => 'Desk'],
- ],
- ]
- */
+/*
+ [
+ 'account-x10' => [
+ ['account_id' => 'account-x10', 'product' => 'Chair'],
+ ['account_id' => 'account-x10', 'product' => 'Bookcase'],
+ ],
+ 'account-x11' => [
+ ['account_id' => 'account-x11', 'product' => 'Desk'],
+ ],
+ ]
+*/
+```
Instead of passing a string `key`, you may pass a callback. The callback should return the value you wish to key the group by:
- $grouped = $collection->groupBy(function ($item, $key) {
- return substr($item['account_id'], -3);
- });
+```php
+$grouped = $collection->groupBy(function (array $item, int $key) {
+ return substr($item['account_id'], -3);
+});
- $grouped->all();
+$grouped->all();
- /*
- [
- 'x10' => [
- ['account_id' => 'account-x10', 'product' => 'Chair'],
- ['account_id' => 'account-x10', 'product' => 'Bookcase'],
- ],
- 'x11' => [
- ['account_id' => 'account-x11', 'product' => 'Desk'],
- ],
- ]
- */
+/*
+ [
+ 'x10' => [
+ ['account_id' => 'account-x10', 'product' => 'Chair'],
+ ['account_id' => 'account-x10', 'product' => 'Bookcase'],
+ ],
+ 'x11' => [
+ ['account_id' => 'account-x11', 'product' => 'Desk'],
+ ],
+ ]
+*/
+```
Multiple grouping criteria may be passed as an array. Each array element will be applied to the corresponding level within a multi-dimensional array:
- $data = new Collection([
- 10 => ['user' => 1, 'skill' => 1, 'roles' => ['Role_1', 'Role_3']],
- 20 => ['user' => 2, 'skill' => 1, 'roles' => ['Role_1', 'Role_2']],
- 30 => ['user' => 3, 'skill' => 2, 'roles' => ['Role_1']],
- 40 => ['user' => 4, 'skill' => 2, 'roles' => ['Role_2']],
- ]);
-
- $result = $data->groupBy(['skill', function ($item) {
- return $item['roles'];
- }], $preserveKeys = true);
-
- /*
- [
- 1 => [
- 'Role_1' => [
- 10 => ['user' => 1, 'skill' => 1, 'roles' => ['Role_1', 'Role_3']],
- 20 => ['user' => 2, 'skill' => 1, 'roles' => ['Role_1', 'Role_2']],
- ],
- 'Role_2' => [
- 20 => ['user' => 2, 'skill' => 1, 'roles' => ['Role_1', 'Role_2']],
- ],
- 'Role_3' => [
- 10 => ['user' => 1, 'skill' => 1, 'roles' => ['Role_1', 'Role_3']],
- ],
+```php
+$data = new Collection([
+ 10 => ['user' => 1, 'skill' => 1, 'roles' => ['Role_1', 'Role_3']],
+ 20 => ['user' => 2, 'skill' => 1, 'roles' => ['Role_1', 'Role_2']],
+ 30 => ['user' => 3, 'skill' => 2, 'roles' => ['Role_1']],
+ 40 => ['user' => 4, 'skill' => 2, 'roles' => ['Role_2']],
+]);
+
+$result = $data->groupBy(['skill', function (array $item) {
+ return $item['roles'];
+}], preserveKeys: true);
+
+/*
+[
+ 1 => [
+ 'Role_1' => [
+ 10 => ['user' => 1, 'skill' => 1, 'roles' => ['Role_1', 'Role_3']],
+ 20 => ['user' => 2, 'skill' => 1, 'roles' => ['Role_1', 'Role_2']],
+ ],
+ 'Role_2' => [
+ 20 => ['user' => 2, 'skill' => 1, 'roles' => ['Role_1', 'Role_2']],
],
- 2 => [
- 'Role_1' => [
- 30 => ['user' => 3, 'skill' => 2, 'roles' => ['Role_1']],
- ],
- 'Role_2' => [
- 40 => ['user' => 4, 'skill' => 2, 'roles' => ['Role_2']],
- ],
+ 'Role_3' => [
+ 10 => ['user' => 1, 'skill' => 1, 'roles' => ['Role_1', 'Role_3']],
],
- ];
- */
+ ],
+ 2 => [
+ 'Role_1' => [
+ 30 => ['user' => 3, 'skill' => 2, 'roles' => ['Role_1']],
+ ],
+ 'Role_2' => [
+ 40 => ['user' => 4, 'skill' => 2, 'roles' => ['Role_2']],
+ ],
+ ],
+];
+*/
+```
#### `has()` {.collection-method}
The `has` method determines if a given key exists in the collection:
- $collection = collect(['account_id' => 1, 'product' => 'Desk', 'amount' => 5]);
+```php
+$collection = collect(['account_id' => 1, 'product' => 'Desk', 'amount' => 5]);
+
+$collection->has('product');
+
+// true
+
+$collection->has(['product', 'amount']);
+
+// true
+
+$collection->has(['amount', 'price']);
- $collection->has('product');
+// false
+```
+
+
+#### `hasAny()` {.collection-method}
- // true
+The `hasAny` method determines whether any of the given keys exist in the collection:
- $collection->has(['product', 'amount']);
+```php
+$collection = collect(['account_id' => 1, 'product' => 'Desk', 'amount' => 5]);
- // true
+$collection->hasAny(['product', 'price']);
- $collection->has(['amount', 'price']);
+// true
- // false
+$collection->hasAny(['name', 'price']);
+
+// false
+```
#### `implode()` {.collection-method}
The `implode` method joins items in a collection. Its arguments depend on the type of items in the collection. If the collection contains arrays or objects, you should pass the key of the attributes you wish to join, and the "glue" string you wish to place between the values:
- $collection = collect([
- ['account_id' => 1, 'product' => 'Desk'],
- ['account_id' => 2, 'product' => 'Chair'],
- ]);
+```php
+$collection = collect([
+ ['account_id' => 1, 'product' => 'Desk'],
+ ['account_id' => 2, 'product' => 'Chair'],
+]);
- $collection->implode('product', ', ');
+$collection->implode('product', ', ');
- // Desk, Chair
+// 'Desk, Chair'
+```
If the collection contains simple strings or numeric values, you should pass the "glue" as the only argument to the method:
- collect([1, 2, 3, 4, 5])->implode('-');
+```php
+collect([1, 2, 3, 4, 5])->implode('-');
+
+// '1-2-3-4-5'
+```
+
+You may pass a closure to the `implode` method if you would like to format the values being imploded:
- // '1-2-3-4-5'
+```php
+$collection->implode(function (array $item, int $key) {
+ return strtoupper($item['product']);
+}, ', ');
+
+// 'DESK, CHAIR'
+```
#### `intersect()` {.collection-method}
-The `intersect` method removes any values from the original collection that are not present in the given `array` or collection. The resulting collection will preserve the original collection's keys:
+The `intersect` method removes any values from the original collection that are not present in the given array or collection. The resulting collection will preserve the original collection's keys:
+
+```php
+$collection = collect(['Desk', 'Sofa', 'Chair']);
+
+$intersect = $collection->intersect(['Desk', 'Chair', 'Bookcase']);
+
+$intersect->all();
+
+// [0 => 'Desk', 2 => 'Chair']
+```
+
+> [!NOTE]
+> This method's behavior is modified when using [Eloquent Collections](/docs/{{version}}/eloquent-collections#method-intersect).
- $collection = collect(['Desk', 'Sofa', 'Chair']);
+
+#### `intersectUsing()` {.collection-method}
- $intersect = $collection->intersect(['Desk', 'Chair', 'Bookcase']);
+The `intersectUsing` method removes any values from the original collection that are not present in the given array or collection, using a custom callback to compare the values. The resulting collection will preserve the original collection's keys:
- $intersect->all();
+```php
+$collection = collect(['Desk', 'Sofa', 'Chair']);
- // [0 => 'Desk', 2 => 'Chair']
+$intersect = $collection->intersectUsing(['desk', 'chair', 'bookcase'], function (string $a, string $b) {
+ return strcasecmp($a, $b);
+});
-> {tip} This method's behavior is modified when using [Eloquent Collections](/docs/{{version}}/eloquent-collections#method-intersect).
+$intersect->all();
+
+// [0 => 'Desk', 2 => 'Chair']
+```
+
+
+#### `intersectAssoc()` {.collection-method}
+
+The `intersectAssoc` method compares the original collection against another collection or array, returning the key / value pairs that are present in all of the given collections:
+
+```php
+$collection = collect([
+ 'color' => 'red',
+ 'size' => 'M',
+ 'material' => 'cotton'
+]);
+
+$intersect = $collection->intersectAssoc([
+ 'color' => 'blue',
+ 'size' => 'M',
+ 'material' => 'polyester'
+]);
+
+$intersect->all();
+
+// ['size' => 'M']
+```
+
+
+#### `intersectAssocUsing()` {.collection-method}
+
+The `intersectAssocUsing` method compares the original collection against another collection or array, returning the key / value pairs that are present in both, using a custom comparison callback to determine equality for both keys and values:
+
+```php
+$collection = collect([
+ 'color' => 'red',
+ 'Size' => 'M',
+ 'material' => 'cotton',
+]);
+
+$intersect = $collection->intersectAssocUsing([
+ 'color' => 'blue',
+ 'size' => 'M',
+ 'material' => 'polyester',
+], function (string $a, string $b) {
+ return strcasecmp($a, $b);
+});
+
+$intersect->all();
+
+// ['Size' => 'M']
+```
#### `intersectByKeys()` {.collection-method}
-The `intersectByKeys` method removes any keys and their corresponding values from the original collection that are not present in the given `array` or collection:
+The `intersectByKeys` method removes any keys and their corresponding values from the original collection that are not present in the given array or collection:
- $collection = collect([
- 'serial' => 'UX301', 'type' => 'screen', 'year' => 2009,
- ]);
+```php
+$collection = collect([
+ 'serial' => 'UX301', 'type' => 'screen', 'year' => 2009,
+]);
- $intersect = $collection->intersectByKeys([
- 'reference' => 'UX404', 'type' => 'tab', 'year' => 2011,
- ]);
+$intersect = $collection->intersectByKeys([
+ 'reference' => 'UX404', 'type' => 'tab', 'year' => 2011,
+]);
- $intersect->all();
+$intersect->all();
- // ['type' => 'screen', 'year' => 2009]
+// ['type' => 'screen', 'year' => 2009]
+```
#### `isEmpty()` {.collection-method}
The `isEmpty` method returns `true` if the collection is empty; otherwise, `false` is returned:
- collect([])->isEmpty();
+```php
+collect([])->isEmpty();
- // true
+// true
+```
#### `isNotEmpty()` {.collection-method}
The `isNotEmpty` method returns `true` if the collection is not empty; otherwise, `false` is returned:
- collect([])->isNotEmpty();
+```php
+collect([])->isNotEmpty();
- // false
+// false
+```
#### `join()` {.collection-method}
The `join` method joins the collection's values with a string. Using this method's second argument, you may also specify how the final element should be appended to the string:
- collect(['a', 'b', 'c'])->join(', '); // 'a, b, c'
- collect(['a', 'b', 'c'])->join(', ', ', and '); // 'a, b, and c'
- collect(['a', 'b'])->join(', ', ' and '); // 'a and b'
- collect(['a'])->join(', ', ' and '); // 'a'
- collect([])->join(', ', ' and '); // ''
+```php
+collect(['a', 'b', 'c'])->join(', '); // 'a, b, c'
+collect(['a', 'b', 'c'])->join(', ', ', and '); // 'a, b, and c'
+collect(['a', 'b'])->join(', ', ' and '); // 'a and b'
+collect(['a'])->join(', ', ' and '); // 'a'
+collect([])->join(', ', ' and '); // ''
+```
#### `keyBy()` {.collection-method}
The `keyBy` method keys the collection by the given key. If multiple items have the same key, only the last one will appear in the new collection:
- $collection = collect([
- ['product_id' => 'prod-100', 'name' => 'Desk'],
- ['product_id' => 'prod-200', 'name' => 'Chair'],
- ]);
+```php
+$collection = collect([
+ ['product_id' => 'prod-100', 'name' => 'Desk'],
+ ['product_id' => 'prod-200', 'name' => 'Chair'],
+]);
- $keyed = $collection->keyBy('product_id');
+$keyed = $collection->keyBy('product_id');
- $keyed->all();
+$keyed->all();
- /*
- [
- 'prod-100' => ['product_id' => 'prod-100', 'name' => 'Desk'],
- 'prod-200' => ['product_id' => 'prod-200', 'name' => 'Chair'],
- ]
- */
+/*
+ [
+ 'prod-100' => ['product_id' => 'prod-100', 'name' => 'Desk'],
+ 'prod-200' => ['product_id' => 'prod-200', 'name' => 'Chair'],
+ ]
+*/
+```
You may also pass a callback to the method. The callback should return the value to key the collection by:
- $keyed = $collection->keyBy(function ($item) {
- return strtoupper($item['product_id']);
- });
+```php
+$keyed = $collection->keyBy(function (array $item, int $key) {
+ return strtoupper($item['product_id']);
+});
- $keyed->all();
+$keyed->all();
- /*
- [
- 'PROD-100' => ['product_id' => 'prod-100', 'name' => 'Desk'],
- 'PROD-200' => ['product_id' => 'prod-200', 'name' => 'Chair'],
- ]
- */
+/*
+ [
+ 'PROD-100' => ['product_id' => 'prod-100', 'name' => 'Desk'],
+ 'PROD-200' => ['product_id' => 'prod-200', 'name' => 'Chair'],
+ ]
+*/
+```
#### `keys()` {.collection-method}
The `keys` method returns all of the collection's keys:
- $collection = collect([
- 'prod-100' => ['product_id' => 'prod-100', 'name' => 'Desk'],
- 'prod-200' => ['product_id' => 'prod-200', 'name' => 'Chair'],
- ]);
+```php
+$collection = collect([
+ 'prod-100' => ['product_id' => 'prod-100', 'name' => 'Desk'],
+ 'prod-200' => ['product_id' => 'prod-200', 'name' => 'Chair'],
+]);
- $keys = $collection->keys();
+$keys = $collection->keys();
- $keys->all();
+$keys->all();
- // ['prod-100', 'prod-200']
+// ['prod-100', 'prod-200']
+```
#### `last()` {.collection-method}
The `last` method returns the last element in the collection that passes a given truth test:
- collect([1, 2, 3, 4])->last(function ($value, $key) {
- return $value < 3;
- });
+```php
+collect([1, 2, 3, 4])->last(function (int $value, int $key) {
+ return $value < 3;
+});
- // 2
+// 2
+```
You may also call the `last` method with no arguments to get the last element in the collection. If the collection is empty, `null` is returned:
- collect([1, 2, 3, 4])->last();
+```php
+collect([1, 2, 3, 4])->last();
+
+// 4
+```
+
+
+#### `lazy()` {.collection-method}
+
+The `lazy` method returns a new [LazyCollection](#lazy-collections) instance from the underlying array of items:
+
+```php
+$lazyCollection = collect([1, 2, 3, 4])->lazy();
+
+$lazyCollection::class;
+
+// Illuminate\Support\LazyCollection
+
+$lazyCollection->all();
+
+// [1, 2, 3, 4]
+```
+
+This is especially useful when you need to perform transformations on a huge `Collection` that contains many items:
+
+```php
+$count = $hugeCollection
+ ->lazy()
+ ->where('country', 'FR')
+ ->where('balance', '>', '100')
+ ->count();
+```
- // 4
+By converting the collection to a `LazyCollection`, we avoid having to allocate a ton of additional memory. Though the original collection still keeps _its_ values in memory, the subsequent filters will not. Therefore, virtually no additional memory will be allocated when filtering the collection's results.
#### `macro()` {.collection-method}
@@ -1222,282 +1724,339 @@ The static `macro` method allows you to add methods to the `Collection` class at
The static `make` method creates a new collection instance. See the [Creating Collections](#creating-collections) section.
+```php
+use Illuminate\Support\Collection;
+
+$collection = Collection::make([1, 2, 3]);
+```
+
#### `map()` {.collection-method}
The `map` method iterates through the collection and passes each value to the given callback. The callback is free to modify the item and return it, thus forming a new collection of modified items:
- $collection = collect([1, 2, 3, 4, 5]);
+```php
+$collection = collect([1, 2, 3, 4, 5]);
- $multiplied = $collection->map(function ($item, $key) {
- return $item * 2;
- });
+$multiplied = $collection->map(function (int $item, int $key) {
+ return $item * 2;
+});
- $multiplied->all();
+$multiplied->all();
- // [2, 4, 6, 8, 10]
+// [2, 4, 6, 8, 10]
+```
-> {note} Like most other collection methods, `map` returns a new collection instance; it does not modify the collection it is called on. If you want to transform the original collection, use the [`transform`](#method-transform) method.
+> [!WARNING]
+> Like most other collection methods, `map` returns a new collection instance; it does not modify the collection it is called on. If you want to transform the original collection, use the [transform](#method-transform) method.
#### `mapInto()` {.collection-method}
The `mapInto()` method iterates over the collection, creating a new instance of the given class by passing the value into the constructor:
- class Currency
- {
- /**
- * Create a new currency instance.
- *
- * @param string $code
- * @return void
- */
- function __construct(string $code)
- {
- $this->code = $code;
- }
- }
+```php
+class Currency
+{
+ /**
+ * Create a new currency instance.
+ */
+ function __construct(
+ public string $code,
+ ) {}
+}
- $collection = collect(['USD', 'EUR', 'GBP']);
+$collection = collect(['USD', 'EUR', 'GBP']);
- $currencies = $collection->mapInto(Currency::class);
+$currencies = $collection->mapInto(Currency::class);
- $currencies->all();
+$currencies->all();
- // [Currency('USD'), Currency('EUR'), Currency('GBP')]
+// [Currency('USD'), Currency('EUR'), Currency('GBP')]
+```
#### `mapSpread()` {.collection-method}
The `mapSpread` method iterates over the collection's items, passing each nested item value into the given closure. The closure is free to modify the item and return it, thus forming a new collection of modified items:
- $collection = collect([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
+```php
+$collection = collect([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
- $chunks = $collection->chunk(2);
+$chunks = $collection->chunk(2);
- $sequence = $chunks->mapSpread(function ($even, $odd) {
- return $even + $odd;
- });
+$sequence = $chunks->mapSpread(function (int $even, int $odd) {
+ return $even + $odd;
+});
- $sequence->all();
+$sequence->all();
- // [1, 5, 9, 13, 17]
+// [1, 5, 9, 13, 17]
+```
#### `mapToGroups()` {.collection-method}
The `mapToGroups` method groups the collection's items by the given closure. The closure should return an associative array containing a single key / value pair, thus forming a new collection of grouped values:
- $collection = collect([
- [
- 'name' => 'John Doe',
- 'department' => 'Sales',
- ],
- [
- 'name' => 'Jane Doe',
- 'department' => 'Sales',
- ],
- [
- 'name' => 'Johnny Doe',
- 'department' => 'Marketing',
- ]
- ]);
+```php
+$collection = collect([
+ [
+ 'name' => 'John Doe',
+ 'department' => 'Sales',
+ ],
+ [
+ 'name' => 'Jane Doe',
+ 'department' => 'Sales',
+ ],
+ [
+ 'name' => 'Johnny Doe',
+ 'department' => 'Marketing',
+ ]
+]);
- $grouped = $collection->mapToGroups(function ($item, $key) {
- return [$item['department'] => $item['name']];
- });
+$grouped = $collection->mapToGroups(function (array $item, int $key) {
+ return [$item['department'] => $item['name']];
+});
- $grouped->all();
+$grouped->all();
- /*
- [
- 'Sales' => ['John Doe', 'Jane Doe'],
- 'Marketing' => ['Johnny Doe'],
- ]
- */
+/*
+ [
+ 'Sales' => ['John Doe', 'Jane Doe'],
+ 'Marketing' => ['Johnny Doe'],
+ ]
+*/
- $grouped->get('Sales')->all();
+$grouped->get('Sales')->all();
- // ['John Doe', 'Jane Doe']
+// ['John Doe', 'Jane Doe']
+```
#### `mapWithKeys()` {.collection-method}
The `mapWithKeys` method iterates through the collection and passes each value to the given callback. The callback should return an associative array containing a single key / value pair:
- $collection = collect([
- [
- 'name' => 'John',
- 'department' => 'Sales',
- 'email' => 'john@example.com',
- ],
- [
- 'name' => 'Jane',
- 'department' => 'Marketing',
- 'email' => 'jane@example.com',
- ]
- ]);
-
- $keyed = $collection->mapWithKeys(function ($item, $key) {
- return [$item['email'] => $item['name']];
- });
+```php
+$collection = collect([
+ [
+ 'name' => 'John',
+ 'department' => 'Sales',
+ 'email' => 'john@example.com',
+ ],
+ [
+ 'name' => 'Jane',
+ 'department' => 'Marketing',
+ 'email' => 'jane@example.com',
+ ]
+]);
- $keyed->all();
+$keyed = $collection->mapWithKeys(function (array $item, int $key) {
+ return [$item['email'] => $item['name']];
+});
- /*
- [
- 'john@example.com' => 'John',
- 'jane@example.com' => 'Jane',
- ]
- */
+$keyed->all();
+
+/*
+ [
+ 'john@example.com' => 'John',
+ 'jane@example.com' => 'Jane',
+ ]
+*/
+```
#### `max()` {.collection-method}
The `max` method returns the maximum value of a given key:
- $max = collect([
- ['foo' => 10],
- ['foo' => 20]
- ])->max('foo');
+```php
+$max = collect([
+ ['foo' => 10],
+ ['foo' => 20]
+])->max('foo');
- // 20
+// 20
- $max = collect([1, 2, 3, 4, 5])->max();
+$max = collect([1, 2, 3, 4, 5])->max();
- // 5
+// 5
+```
#### `median()` {.collection-method}
The `median` method returns the [median value](https://en.wikipedia.org/wiki/Median) of a given key:
- $median = collect([
- ['foo' => 10],
- ['foo' => 10],
- ['foo' => 20],
- ['foo' => 40]
- ])->median('foo');
+```php
+$median = collect([
+ ['foo' => 10],
+ ['foo' => 10],
+ ['foo' => 20],
+ ['foo' => 40]
+])->median('foo');
- // 15
+// 15
- $median = collect([1, 1, 2, 4])->median();
+$median = collect([1, 1, 2, 4])->median();
- // 1.5
+// 1.5
+```
#### `merge()` {.collection-method}
-The `merge` method merges the given array or collection with the original collection. If a string key in the given items matches a string key in the original collection, the given items's value will overwrite the value in the original collection:
+The `merge` method merges the given array or collection with the original collection. If a string key in the given items matches a string key in the original collection, the given item's value will overwrite the value in the original collection:
- $collection = collect(['product_id' => 1, 'price' => 100]);
+```php
+$collection = collect(['product_id' => 1, 'price' => 100]);
- $merged = $collection->merge(['price' => 200, 'discount' => false]);
+$merged = $collection->merge(['price' => 200, 'discount' => false]);
- $merged->all();
+$merged->all();
- // ['product_id' => 1, 'price' => 200, 'discount' => false]
+// ['product_id' => 1, 'price' => 200, 'discount' => false]
+```
-If the given items's keys are numeric, the values will be appended to the end of the collection:
+If the given item's keys are numeric, the values will be appended to the end of the collection:
- $collection = collect(['Desk', 'Chair']);
+```php
+$collection = collect(['Desk', 'Chair']);
- $merged = $collection->merge(['Bookcase', 'Door']);
+$merged = $collection->merge(['Bookcase', 'Door']);
- $merged->all();
+$merged->all();
- // ['Desk', 'Chair', 'Bookcase', 'Door']
+// ['Desk', 'Chair', 'Bookcase', 'Door']
+```
#### `mergeRecursive()` {.collection-method}
The `mergeRecursive` method merges the given array or collection recursively with the original collection. If a string key in the given items matches a string key in the original collection, then the values for these keys are merged together into an array, and this is done recursively:
- $collection = collect(['product_id' => 1, 'price' => 100]);
+```php
+$collection = collect(['product_id' => 1, 'price' => 100]);
- $merged = $collection->mergeRecursive([
- 'product_id' => 2,
- 'price' => 200,
- 'discount' => false
- ]);
+$merged = $collection->mergeRecursive([
+ 'product_id' => 2,
+ 'price' => 200,
+ 'discount' => false
+]);
- $merged->all();
+$merged->all();
- // ['product_id' => [1, 2], 'price' => [100, 200], 'discount' => false]
+// ['product_id' => [1, 2], 'price' => [100, 200], 'discount' => false]
+```
#### `min()` {.collection-method}
The `min` method returns the minimum value of a given key:
- $min = collect([['foo' => 10], ['foo' => 20]])->min('foo');
+```php
+$min = collect([['foo' => 10], ['foo' => 20]])->min('foo');
- // 10
+// 10
- $min = collect([1, 2, 3, 4, 5])->min();
+$min = collect([1, 2, 3, 4, 5])->min();
- // 1
+// 1
+```
#### `mode()` {.collection-method}
The `mode` method returns the [mode value](https://en.wikipedia.org/wiki/Mode_(statistics)) of a given key:
- $mode = collect([
- ['foo' => 10],
- ['foo' => 10],
- ['foo' => 20],
- ['foo' => 40]
- ])->mode('foo');
+```php
+$mode = collect([
+ ['foo' => 10],
+ ['foo' => 10],
+ ['foo' => 20],
+ ['foo' => 40]
+])->mode('foo');
+
+// [10]
- // [10]
+$mode = collect([1, 1, 2, 4])->mode();
- $mode = collect([1, 1, 2, 4])->mode();
+// [1]
- // [1]
+$mode = collect([1, 1, 2, 2])->mode();
+
+// [1, 2]
+```
- $mode = collect([1, 1, 2, 2])->mode();
+
+#### `multiply()` {.collection-method}
- // [1, 2]
+The `multiply` method creates the specified number of copies of all items in the collection:
+
+```php
+$users = collect([
+ ['name' => 'User #1', 'email' => 'user1@example.com'],
+ ['name' => 'User #2', 'email' => 'user2@example.com'],
+])->multiply(3);
+
+/*
+ [
+ ['name' => 'User #1', 'email' => 'user1@example.com'],
+ ['name' => 'User #2', 'email' => 'user2@example.com'],
+ ['name' => 'User #1', 'email' => 'user1@example.com'],
+ ['name' => 'User #2', 'email' => 'user2@example.com'],
+ ['name' => 'User #1', 'email' => 'user1@example.com'],
+ ['name' => 'User #2', 'email' => 'user2@example.com'],
+ ]
+*/
+```
#### `nth()` {.collection-method}
The `nth` method creates a new collection consisting of every n-th element:
- $collection = collect(['a', 'b', 'c', 'd', 'e', 'f']);
+```php
+$collection = collect(['a', 'b', 'c', 'd', 'e', 'f']);
- $collection->nth(4);
+$collection->nth(4);
- // ['a', 'e']
+// ['a', 'e']
+```
You may optionally pass a starting offset as the second argument:
- $collection->nth(4, 1);
+```php
+$collection->nth(4, 1);
- // ['b', 'f']
+// ['b', 'f']
+```
#### `only()` {.collection-method}
The `only` method returns the items in the collection with the specified keys:
- $collection = collect([
- 'product_id' => 1,
- 'name' => 'Desk',
- 'price' => 100,
- 'discount' => false
- ]);
+```php
+$collection = collect([
+ 'product_id' => 1,
+ 'name' => 'Desk',
+ 'price' => 100,
+ 'discount' => false
+]);
- $filtered = $collection->only(['product_id', 'name']);
+$filtered = $collection->only(['product_id', 'name']);
- $filtered->all();
+$filtered->all();
- // ['product_id' => 1, 'name' => 'Desk']
+// ['product_id' => 1, 'name' => 'Desk']
+```
For the inverse of `only`, see the [except](#method-except) method.
-> {tip} This method's behavior is modified when using [Eloquent Collections](/docs/{{version}}/eloquent-collections#method-only).
+> [!NOTE]
+> This method's behavior is modified when using [Eloquent Collections](/docs/{{version}}/eloquent-collections#method-only).
#### `pad()` {.collection-method}
@@ -1506,1681 +2065,1970 @@ The `pad` method will fill the array with the given value until the array reache
To pad to the left, you should specify a negative size. No padding will take place if the absolute value of the given size is less than or equal to the length of the array:
- $collection = collect(['A', 'B', 'C']);
+```php
+$collection = collect(['A', 'B', 'C']);
- $filtered = $collection->pad(5, 0);
+$filtered = $collection->pad(5, 0);
- $filtered->all();
+$filtered->all();
- // ['A', 'B', 'C', 0, 0]
+// ['A', 'B', 'C', 0, 0]
- $filtered = $collection->pad(-5, 0);
+$filtered = $collection->pad(-5, 0);
- $filtered->all();
+$filtered->all();
- // [0, 0, 'A', 'B', 'C']
+// [0, 0, 'A', 'B', 'C']
+```
#### `partition()` {.collection-method}
The `partition` method may be combined with PHP array destructuring to separate elements that pass a given truth test from those that do not:
- $collection = collect([1, 2, 3, 4, 5, 6]);
+```php
+$collection = collect([1, 2, 3, 4, 5, 6]);
- [$underThree, $equalOrAboveThree] = $collection->partition(function ($i) {
- return $i < 3;
- });
+[$underThree, $equalOrAboveThree] = $collection->partition(function (int $i) {
+ return $i < 3;
+});
+
+$underThree->all();
+
+// [1, 2]
+
+$equalOrAboveThree->all();
+
+// [3, 4, 5, 6]
+```
+
+> [!NOTE]
+> This method's behavior is modified when interacting with [Eloquent collections](/docs/{{version}}/eloquent-collections#method-partition).
+
+
+#### `percentage()` {.collection-method}
+
+The `percentage` method may be used to quickly determine the percentage of items in the collection that pass a given truth test:
+
+```php
+$collection = collect([1, 1, 2, 2, 2, 3]);
- $underThree->all();
+$percentage = $collection->percentage(fn (int $value) => $value === 1);
- // [1, 2]
+// 33.33
+```
+
+By default, the percentage will be rounded to two decimal places. However, you may customize this behavior by providing a second argument to the method:
- $equalOrAboveThree->all();
+```php
+$percentage = $collection->percentage(fn (int $value) => $value === 1, precision: 3);
- // [3, 4, 5, 6]
+// 33.333
+```
#### `pipe()` {.collection-method}
The `pipe` method passes the collection to the given closure and returns the result of the executed closure:
- $collection = collect([1, 2, 3]);
+```php
+$collection = collect([1, 2, 3]);
- $piped = $collection->pipe(function ($collection) {
- return $collection->sum();
- });
+$piped = $collection->pipe(function (Collection $collection) {
+ return $collection->sum();
+});
- // 6
+// 6
+```
#### `pipeInto()` {.collection-method}
The `pipeInto` method creates a new instance of the given class and passes the collection into the constructor:
- class ResourceCollection
- {
- /**
- * The Collection instance.
- */
- public $collection;
-
- /**
- * Create a new ResourceCollection instance.
- *
- * @param Collection $collection
- * @return void
- */
- public function __construct(Collection $collection)
- {
- $this->collection = $collection;
- }
- }
+```php
+class ResourceCollection
+{
+ /**
+ * Create a new ResourceCollection instance.
+ */
+ public function __construct(
+ public Collection $collection,
+ ) {}
+}
- $collection = collect([1, 2, 3]);
+$collection = collect([1, 2, 3]);
- $resource = $collection->pipeInto(ResourceCollection::class);
+$resource = $collection->pipeInto(ResourceCollection::class);
- $resource->collection->all();
+$resource->collection->all();
- // [1, 2, 3]
+// [1, 2, 3]
+```
#### `pipeThrough()` {.collection-method}
The `pipeThrough` method passes the collection to the given array of closures and returns the result of the executed closures:
- $collection = collect([1, 2, 3]);
+```php
+use Illuminate\Support\Collection;
+
+$collection = collect([1, 2, 3]);
- $result = $collection->pipeThrough([
- function ($collection) {
- return $collection->merge([4, 5]);
- },
- function ($collection) {
- return $collection->sum();
- },
- ]);
+$result = $collection->pipeThrough([
+ function (Collection $collection) {
+ return $collection->merge([4, 5]);
+ },
+ function (Collection $collection) {
+ return $collection->sum();
+ },
+]);
- // 15
+// 15
+```
#### `pluck()` {.collection-method}
The `pluck` method retrieves all of the values for a given key:
- $collection = collect([
- ['product_id' => 'prod-100', 'name' => 'Desk'],
- ['product_id' => 'prod-200', 'name' => 'Chair'],
- ]);
+```php
+$collection = collect([
+ ['product_id' => 'prod-100', 'name' => 'Desk'],
+ ['product_id' => 'prod-200', 'name' => 'Chair'],
+]);
- $plucked = $collection->pluck('name');
+$plucked = $collection->pluck('name');
- $plucked->all();
+$plucked->all();
- // ['Desk', 'Chair']
+// ['Desk', 'Chair']
+```
You may also specify how you wish the resulting collection to be keyed:
- $plucked = $collection->pluck('name', 'product_id');
+```php
+$plucked = $collection->pluck('name', 'product_id');
- $plucked->all();
+$plucked->all();
- // ['prod-100' => 'Desk', 'prod-200' => 'Chair']
+// ['prod-100' => 'Desk', 'prod-200' => 'Chair']
+```
The `pluck` method also supports retrieving nested values using "dot" notation:
- $collection = collect([
- [
- 'speakers' => [
- 'first_day' => ['Rosa', 'Judith'],
- 'second_day' => ['Angela', 'Kathleen'],
- ],
+```php
+$collection = collect([
+ [
+ 'name' => 'Laracon',
+ 'speakers' => [
+ 'first_day' => ['Rosa', 'Judith'],
+ ],
+ ],
+ [
+ 'name' => 'VueConf',
+ 'speakers' => [
+ 'first_day' => ['Abigail', 'Joey'],
],
- ]);
+ ],
+]);
- $plucked = $collection->pluck('speakers.first_day');
+$plucked = $collection->pluck('speakers.first_day');
- $plucked->all();
+$plucked->all();
- // ['Rosa', 'Judith']
+// [['Rosa', 'Judith'], ['Abigail', 'Joey']]
+```
If duplicate keys exist, the last matching element will be inserted into the plucked collection:
- $collection = collect([
- ['brand' => 'Tesla', 'color' => 'red'],
- ['brand' => 'Pagani', 'color' => 'white'],
- ['brand' => 'Tesla', 'color' => 'black'],
- ['brand' => 'Pagani', 'color' => 'orange'],
- ]);
+```php
+$collection = collect([
+ ['brand' => 'Tesla', 'color' => 'red'],
+ ['brand' => 'Pagani', 'color' => 'white'],
+ ['brand' => 'Tesla', 'color' => 'black'],
+ ['brand' => 'Pagani', 'color' => 'orange'],
+]);
- $plucked = $collection->pluck('color', 'brand');
+$plucked = $collection->pluck('color', 'brand');
- $plucked->all();
+$plucked->all();
- // ['Tesla' => 'black', 'Pagani' => 'orange']
+// ['Tesla' => 'black', 'Pagani' => 'orange']
+```
#### `pop()` {.collection-method}
-The `pop` method removes and returns the last item from the collection:
+The `pop` method removes and returns the last item from the collection. If the collection is empty, `null` will be returned:
- $collection = collect([1, 2, 3, 4, 5]);
+```php
+$collection = collect([1, 2, 3, 4, 5]);
- $collection->pop();
+$collection->pop();
- // 5
+// 5
- $collection->all();
+$collection->all();
- // [1, 2, 3, 4]
+// [1, 2, 3, 4]
+```
You may pass an integer to the `pop` method to remove and return multiple items from the end of a collection:
- $collection = collect([1, 2, 3, 4, 5]);
+```php
+$collection = collect([1, 2, 3, 4, 5]);
- $collection->pop(3);
+$collection->pop(3);
- // collect([5, 4, 3])
+// collect([5, 4, 3])
- $collection->all();
+$collection->all();
- // [1, 2]
+// [1, 2]
+```
#### `prepend()` {.collection-method}
The `prepend` method adds an item to the beginning of the collection:
- $collection = collect([1, 2, 3, 4, 5]);
+```php
+$collection = collect([1, 2, 3, 4, 5]);
- $collection->prepend(0);
+$collection->prepend(0);
- $collection->all();
+$collection->all();
- // [0, 1, 2, 3, 4, 5]
+// [0, 1, 2, 3, 4, 5]
+```
You may also pass a second argument to specify the key of the prepended item:
- $collection = collect(['one' => 1, 'two' => 2]);
+```php
+$collection = collect(['one' => 1, 'two' => 2]);
- $collection->prepend(0, 'zero');
+$collection->prepend(0, 'zero');
- $collection->all();
+$collection->all();
- // ['zero' => 0, 'one' => 1, 'two' => 2]
+// ['zero' => 0, 'one' => 1, 'two' => 2]
+```
#### `pull()` {.collection-method}
The `pull` method removes and returns an item from the collection by its key:
- $collection = collect(['product_id' => 'prod-100', 'name' => 'Desk']);
+```php
+$collection = collect(['product_id' => 'prod-100', 'name' => 'Desk']);
- $collection->pull('name');
+$collection->pull('name');
- // 'Desk'
+// 'Desk'
- $collection->all();
+$collection->all();
- // ['product_id' => 'prod-100']
+// ['product_id' => 'prod-100']
+```
#### `push()` {.collection-method}
The `push` method appends an item to the end of the collection:
- $collection = collect([1, 2, 3, 4]);
+```php
+$collection = collect([1, 2, 3, 4]);
- $collection->push(5);
+$collection->push(5);
- $collection->all();
+$collection->all();
+
+// [1, 2, 3, 4, 5]
+```
- // [1, 2, 3, 4, 5]
+You may also provide multiple items to append to the end of the collection:
+
+```php
+$collection = collect([1, 2, 3, 4]);
+
+$collection->push(5, 6, 7);
+
+$collection->all();
+
+// [1, 2, 3, 4, 5, 6, 7]
+```
#### `put()` {.collection-method}
The `put` method sets the given key and value in the collection:
- $collection = collect(['product_id' => 1, 'name' => 'Desk']);
+```php
+$collection = collect(['product_id' => 1, 'name' => 'Desk']);
- $collection->put('price', 100);
+$collection->put('price', 100);
- $collection->all();
+$collection->all();
- // ['product_id' => 1, 'name' => 'Desk', 'price' => 100]
+// ['product_id' => 1, 'name' => 'Desk', 'price' => 100]
+```
#### `random()` {.collection-method}
The `random` method returns a random item from the collection:
- $collection = collect([1, 2, 3, 4, 5]);
+```php
+$collection = collect([1, 2, 3, 4, 5]);
- $collection->random();
+$collection->random();
- // 4 - (retrieved randomly)
+// 4 - (retrieved randomly)
+```
You may pass an integer to `random` to specify how many items you would like to randomly retrieve. A collection of items is always returned when explicitly passing the number of items you wish to receive:
- $random = $collection->random(3);
+```php
+$random = $collection->random(3);
- $random->all();
+$random->all();
- // [2, 4, 5] - (retrieved randomly)
+// [2, 4, 5] - (retrieved randomly)
+```
If the collection instance has fewer items than requested, the `random` method will throw an `InvalidArgumentException`.
+The `random` method also accepts a closure, which will receive the current collection instance:
+
+```php
+use Illuminate\Support\Collection;
+
+$random = $collection->random(fn (Collection $items) => min(10, count($items)));
+
+$random->all();
+
+// [1, 2, 3, 4, 5] - (retrieved randomly)
+```
+
#### `range()` {.collection-method}
The `range` method returns a collection containing integers between the specified range:
- $collection = collect()->range(3, 6);
+```php
+$collection = collect()->range(3, 6);
- $collection->all();
+$collection->all();
- // [3, 4, 5, 6]
+// [3, 4, 5, 6]
+```
#### `reduce()` {.collection-method}
The `reduce` method reduces the collection to a single value, passing the result of each iteration into the subsequent iteration:
- $collection = collect([1, 2, 3]);
+```php
+$collection = collect([1, 2, 3]);
- $total = $collection->reduce(function ($carry, $item) {
- return $carry + $item;
- });
+$total = $collection->reduce(function (?int $carry, int $item) {
+ return $carry + $item;
+});
- // 6
+// 6
+```
The value for `$carry` on the first iteration is `null`; however, you may specify its initial value by passing a second argument to `reduce`:
- $collection->reduce(function ($carry, $item) {
- return $carry + $item;
- }, 4);
-
- // 10
-
-The `reduce` method also passes array keys in associative collections to the given callback:
+```php
+$collection->reduce(function (int $carry, int $item) {
+ return $carry + $item;
+}, 4);
- $collection = collect([
- 'usd' => 1400,
- 'gbp' => 1200,
- 'eur' => 1000,
- ]);
-
- $ratio = [
- 'usd' => 1,
- 'gbp' => 1.37,
- 'eur' => 1.22,
- ];
-
- $collection->reduce(function ($carry, $value, $key) use ($ratio) {
- return $carry + ($value * $ratio[$key]);
- });
-
- // 4264
+// 10
+```
-
-#### `reduceMany()` {.collection-method}
+The `reduce` method also passes array keys to the given callback:
-The `reduceMany` method reduces the collection to an array of values, passing the results of each iteration into the subsequent iteration. This method is similar to the `reduce` method; however, it can accept multiple initial values:
+```php
+$collection = collect([
+ 'usd' => 1400,
+ 'gbp' => 1200,
+ 'eur' => 1000,
+]);
- [$creditsRemaining, $batch] = Image::where('status', 'unprocessed')
- ->get()
- ->reduceMany(function ($creditsRemaining, $batch, $image) {
- if ($creditsRemaining >= $image->creditsRequired()) {
- $batch->push($image);
+$ratio = [
+ 'usd' => 1,
+ 'gbp' => 1.37,
+ 'eur' => 1.22,
+];
- $creditsRemaining -= $image->creditsRequired();
- }
+$collection->reduce(function (int $carry, int $value, string $key) use ($ratio) {
+ return $carry + ($value * $ratio[$key]);
+}, 0);
- return [$creditsRemaining, $batch];
- }, $creditsAvailable, collect());
+// 4264
+```
#### `reduceSpread()` {.collection-method}
The `reduceSpread` method reduces the collection to an array of values, passing the results of each iteration into the subsequent iteration. This method is similar to the `reduce` method; however, it can accept multiple initial values:
- [$creditsRemaining, $batch] = Image::where('status', 'unprocessed')
- ->get()
- ->reduceSpread(function ($creditsRemaining, $batch, $image) {
- if ($creditsRemaining >= $image->creditsRequired()) {
- $batch->push($image);
+```php
+[$creditsRemaining, $batch] = Image::where('status', 'unprocessed')
+ ->get()
+ ->reduceSpread(function (int $creditsRemaining, Collection $batch, Image $image) {
+ if ($creditsRemaining >= $image->creditsRequired()) {
+ $batch->push($image);
- $creditsRemaining -= $image->creditsRequired();
- }
+ $creditsRemaining -= $image->creditsRequired();
+ }
- return [$creditsRemaining, $batch];
- }, $creditsAvailable, collect());
+ return [$creditsRemaining, $batch];
+ }, $creditsAvailable, collect());
+```
#### `reject()` {.collection-method}
The `reject` method filters the collection using the given closure. The closure should return `true` if the item should be removed from the resulting collection:
- $collection = collect([1, 2, 3, 4]);
+```php
+$collection = collect([1, 2, 3, 4]);
- $filtered = $collection->reject(function ($value, $key) {
- return $value > 2;
- });
+$filtered = $collection->reject(function (int $value, int $key) {
+ return $value > 2;
+});
- $filtered->all();
+$filtered->all();
- // [1, 2]
+// [1, 2]
+```
-For the inverse of the `reject` method, see the [`filter`](#method-filter) method.
+For the inverse of the `reject` method, see the [filter](#method-filter) method.
#### `replace()` {.collection-method}
The `replace` method behaves similarly to `merge`; however, in addition to overwriting matching items that have string keys, the `replace` method will also overwrite items in the collection that have matching numeric keys:
- $collection = collect(['Taylor', 'Abigail', 'James']);
+```php
+$collection = collect(['Taylor', 'Abigail', 'James']);
- $replaced = $collection->replace([1 => 'Victoria', 3 => 'Finn']);
+$replaced = $collection->replace([1 => 'Victoria', 3 => 'Finn']);
- $replaced->all();
+$replaced->all();
- // ['Taylor', 'Victoria', 'James', 'Finn']
+// ['Taylor', 'Victoria', 'James', 'Finn']
+```
#### `replaceRecursive()` {.collection-method}
-This method works like `replace`, but it will recur into arrays and apply the same replacement process to the inner values:
+The `replaceRecursive` method behaves similarly to `replace`, but it will recur into arrays and apply the same replacement process to the inner values:
- $collection = collect([
- 'Taylor',
- 'Abigail',
- [
- 'James',
- 'Victoria',
- 'Finn'
- ]
- ]);
+```php
+$collection = collect([
+ 'Taylor',
+ 'Abigail',
+ [
+ 'James',
+ 'Victoria',
+ 'Finn'
+ ]
+]);
- $replaced = $collection->replaceRecursive([
- 'Charlie',
- 2 => [1 => 'King']
- ]);
+$replaced = $collection->replaceRecursive([
+ 'Charlie',
+ 2 => [1 => 'King']
+]);
- $replaced->all();
+$replaced->all();
- // ['Charlie', 'Abigail', ['James', 'King', 'Finn']]
+// ['Charlie', 'Abigail', ['James', 'King', 'Finn']]
+```
#### `reverse()` {.collection-method}
The `reverse` method reverses the order of the collection's items, preserving the original keys:
- $collection = collect(['a', 'b', 'c', 'd', 'e']);
+```php
+$collection = collect(['a', 'b', 'c', 'd', 'e']);
- $reversed = $collection->reverse();
+$reversed = $collection->reverse();
- $reversed->all();
+$reversed->all();
- /*
- [
- 4 => 'e',
- 3 => 'd',
- 2 => 'c',
- 1 => 'b',
- 0 => 'a',
- ]
- */
+/*
+ [
+ 4 => 'e',
+ 3 => 'd',
+ 2 => 'c',
+ 1 => 'b',
+ 0 => 'a',
+ ]
+*/
+```
#### `search()` {.collection-method}
The `search` method searches the collection for the given value and returns its key if found. If the item is not found, `false` is returned:
- $collection = collect([2, 4, 6, 8]);
+```php
+$collection = collect([2, 4, 6, 8]);
- $collection->search(4);
+$collection->search(4);
- // 1
+// 1
+```
The search is done using a "loose" comparison, meaning a string with an integer value will be considered equal to an integer of the same value. To use "strict" comparison, pass `true` as the second argument to the method:
- collect([2, 4, 6, 8])->search('4', $strict = true);
+```php
+collect([2, 4, 6, 8])->search('4', strict: true);
- // false
+// false
+```
Alternatively, you may provide your own closure to search for the first item that passes a given truth test:
- collect([2, 4, 6, 8])->search(function ($item, $key) {
- return $item > 5;
- });
+```php
+collect([2, 4, 6, 8])->search(function (int $item, int $key) {
+ return $item > 5;
+});
+
+// 2
+```
+
+
+#### `select()` {.collection-method}
- // 2
+The `select` method selects the given keys from the collection, similar to an SQL `SELECT` statement:
+
+```php
+$users = collect([
+ ['name' => 'Taylor Otwell', 'role' => 'Developer', 'status' => 'active'],
+ ['name' => 'Victoria Faith', 'role' => 'Researcher', 'status' => 'active'],
+]);
+
+$users->select(['name', 'role']);
+
+/*
+ [
+ ['name' => 'Taylor Otwell', 'role' => 'Developer'],
+ ['name' => 'Victoria Faith', 'role' => 'Researcher'],
+ ],
+*/
+```
#### `shift()` {.collection-method}
The `shift` method removes and returns the first item from the collection:
- $collection = collect([1, 2, 3, 4, 5]);
+```php
+$collection = collect([1, 2, 3, 4, 5]);
- $collection->shift();
+$collection->shift();
- // 1
+// 1
- $collection->all();
+$collection->all();
- // [2, 3, 4, 5]
+// [2, 3, 4, 5]
+```
You may pass an integer to the `shift` method to remove and return multiple items from the beginning of a collection:
- $collection = collect([1, 2, 3, 4, 5]);
+```php
+$collection = collect([1, 2, 3, 4, 5]);
- $collection->shift(3);
+$collection->shift(3);
- // collect([1, 2, 3])
+// collect([1, 2, 3])
- $collection->all();
+$collection->all();
- // [4, 5]
+// [4, 5]
+```
#### `shuffle()` {.collection-method}
The `shuffle` method randomly shuffles the items in the collection:
- $collection = collect([1, 2, 3, 4, 5]);
+```php
+$collection = collect([1, 2, 3, 4, 5]);
- $shuffled = $collection->shuffle();
+$shuffled = $collection->shuffle();
- $shuffled->all();
+$shuffled->all();
- // [3, 2, 5, 1, 4] - (generated randomly)
+// [3, 2, 5, 1, 4] - (generated randomly)
+```
-
-#### `sliding()` {.collection-method}
+
+#### `skip()` {.collection-method}
-The `sliding` method returns a new collection of chunks representing a "sliding window" view of the items in the collection:
+The `skip` method returns a new collection, with the given number of elements removed from the beginning of the collection:
- $collection = collect([1, 2, 3, 4, 5]);
+```php
+$collection = collect([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
- $chunks = $collection->sliding(2);
+$collection = $collection->skip(4);
- $chunks->toArray();
+$collection->all();
- // [[1, 2], [2, 3], [3, 4], [4, 5]]
+// [5, 6, 7, 8, 9, 10]
+```
-This is especially useful in conjunction with the [`eachSpread`](#method-eachspread) method:
+
+#### `skipUntil()` {.collection-method}
- $transactions->sliding(2)->eachSpread(function ($previous, $current) {
- $current->total = $previous->total + $current->amount;
- });
+The `skipUntil` method skips over items from the collection while the given callback returns `false`. Once the callback returns `true` all of the remaining items in the collection will be returned as a new collection:
-You may optionally pass a second "step" value, which determines the distance between the first item of every chunk:
+```php
+$collection = collect([1, 2, 3, 4]);
- $collection = collect([1, 2, 3, 4, 5]);
+$subset = $collection->skipUntil(function (int $item) {
+ return $item >= 3;
+});
- $chunks = $collection->sliding(3, step: 2);
+$subset->all();
- $chunks->toArray();
+// [3, 4]
+```
- // [[1, 2, 3], [3, 4, 5]]
+You may also pass a simple value to the `skipUntil` method to skip all items until the given value is found:
-
-#### `skip()` {.collection-method}
+```php
+$collection = collect([1, 2, 3, 4]);
-The `skip` method returns a new collection, with the given number of elements removed from the beginning of the collection:
+$subset = $collection->skipUntil(3);
- $collection = collect([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+$subset->all();
- $collection = $collection->skip(4);
+// [3, 4]
+```
- $collection->all();
+> [!WARNING]
+> If the given value is not found or the callback never returns `true`, the `skipUntil` method will return an empty collection.
- // [5, 6, 7, 8, 9, 10]
+
+#### `skipWhile()` {.collection-method}
-
-#### `skipUntil()` {.collection-method}
+The `skipWhile` method skips over items from the collection while the given callback returns `true`. Once the callback returns `false` all of the remaining items in the collection will be returned as a new collection:
-The `skipUntil` method skips over items from the collection until the given callback returns `true` and then returns the remaining items in the collection as a new collection instance:
+```php
+$collection = collect([1, 2, 3, 4]);
- $collection = collect([1, 2, 3, 4]);
+$subset = $collection->skipWhile(function (int $item) {
+ return $item <= 3;
+});
- $subset = $collection->skipUntil(function ($item) {
- return $item >= 3;
- });
+$subset->all();
- $subset->all();
+// [4]
+```
- // [3, 4]
+> [!WARNING]
+> If the callback never returns `false`, the `skipWhile` method will return an empty collection.
-You may also pass a simple value to the `skipUntil` method to skip all items until the given value is found:
+
+#### `slice()` {.collection-method}
- $collection = collect([1, 2, 3, 4]);
+The `slice` method returns a slice of the collection starting at the given index:
- $subset = $collection->skipUntil(3);
+```php
+$collection = collect([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
- $subset->all();
+$slice = $collection->slice(4);
- // [3, 4]
+$slice->all();
-> {note} If the given value is not found or the callback never returns `true`, the `skipUntil` method will return an empty collection.
+// [5, 6, 7, 8, 9, 10]
+```
-
-#### `skipWhile()` {.collection-method}
+If you would like to limit the size of the returned slice, pass the desired size as the second argument to the method:
-The `skipWhile` method skips over items from the collection while the given callback returns `true` and then returns the remaining items in the collection as a new collection:
+```php
+$slice = $collection->slice(4, 2);
- $collection = collect([1, 2, 3, 4]);
+$slice->all();
- $subset = $collection->skipWhile(function ($item) {
- return $item <= 3;
- });
+// [5, 6]
+```
- $subset->all();
+The returned slice will preserve keys by default. If you do not wish to preserve the original keys, you can use the [values](#method-values) method to reindex them.
- // [4]
+
+#### `sliding()` {.collection-method}
-> {note} If the callback never returns `false`, the `skipWhile` method will return an empty collection.
+The `sliding` method returns a new collection of chunks representing a "sliding window" view of the items in the collection:
-
-#### `slice()` {.collection-method}
+```php
+$collection = collect([1, 2, 3, 4, 5]);
-The `slice` method returns a slice of the collection starting at the given index:
+$chunks = $collection->sliding(2);
- $collection = collect([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+$chunks->toArray();
- $slice = $collection->slice(4);
+// [[1, 2], [2, 3], [3, 4], [4, 5]]
+```
- $slice->all();
+This is especially useful in conjunction with the [eachSpread](#method-eachspread) method:
- // [5, 6, 7, 8, 9, 10]
+```php
+$transactions->sliding(2)->eachSpread(function (Collection $previous, Collection $current) {
+ $current->total = $previous->total + $current->amount;
+});
+```
-If you would like to limit the size of the returned slice, pass the desired size as the second argument to the method:
+You may optionally pass a second "step" value, which determines the distance between the first item of every chunk:
- $slice = $collection->slice(4, 2);
+```php
+$collection = collect([1, 2, 3, 4, 5]);
- $slice->all();
+$chunks = $collection->sliding(3, step: 2);
- // [5, 6]
+$chunks->toArray();
-The returned slice will preserve keys by default. If you do not wish to preserve the original keys, you can use the [`values`](#method-values) method to reindex them.
+// [[1, 2, 3], [3, 4, 5]]
+```
#### `sole()` {.collection-method}
The `sole` method returns the first element in the collection that passes a given truth test, but only if the truth test matches exactly one element:
- collect([1, 2, 3, 4])->sole(function ($value, $key) {
- return $value === 2;
- });
+```php
+collect([1, 2, 3, 4])->sole(function (int $value, int $key) {
+ return $value === 2;
+});
- // 2
+// 2
+```
You may also pass a key / value pair to the `sole` method, which will return the first element in the collection that matches the given pair, but only if it exactly one element matches:
- $collection = collect([
- ['product' => 'Desk', 'price' => 200],
- ['product' => 'Chair', 'price' => 100],
- ]);
+```php
+$collection = collect([
+ ['product' => 'Desk', 'price' => 200],
+ ['product' => 'Chair', 'price' => 100],
+]);
- $collection->sole('product', 'Chair');
+$collection->sole('product', 'Chair');
- // ['product' => 'Chair', 'price' => 100]
+// ['product' => 'Chair', 'price' => 100]
+```
Alternatively, you may also call the `sole` method with no argument to get the first element in the collection if there is only one element:
- $collection = collect([
- ['product' => 'Desk', 'price' => 200],
- ]);
+```php
+$collection = collect([
+ ['product' => 'Desk', 'price' => 200],
+]);
- $collection->sole();
+$collection->sole();
- // ['product' => 'Desk', 'price' => 200]
+// ['product' => 'Desk', 'price' => 200]
+```
If there are no elements in the collection that should be returned by the `sole` method, an `\Illuminate\Collections\ItemNotFoundException` exception will be thrown. If there is more than one element that should be returned, an `\Illuminate\Collections\MultipleItemsFoundException` will be thrown.
#### `some()` {.collection-method}
-Alias for the [`contains`](#method-contains) method.
+Alias for the [contains](#method-contains) method.
#### `sort()` {.collection-method}
-The `sort` method sorts the collection. The sorted collection keeps the original array keys, so in the following example we will use the [`values`](#method-values) method to reset the keys to consecutively numbered indexes:
+The `sort` method sorts the collection. The sorted collection keeps the original array keys, so in the following example we will use the [values](#method-values) method to reset the keys to consecutively numbered indexes:
- $collection = collect([5, 3, 1, 2, 4]);
+```php
+$collection = collect([5, 3, 1, 2, 4]);
- $sorted = $collection->sort();
+$sorted = $collection->sort();
- $sorted->values()->all();
+$sorted->values()->all();
- // [1, 2, 3, 4, 5]
+// [1, 2, 3, 4, 5]
+```
-If your sorting needs are more advanced, you may pass a callback to `sort` with your own algorithm. Refer to the PHP documentation on [`uasort`](https://secure.php.net/manual/en/function.uasort.php#refsect1-function.uasort-parameters), which is what the collection's `sort` method calls utilizes internally.
+If your sorting needs are more advanced, you may pass a callback to `sort` with your own algorithm. Refer to the PHP documentation on [uasort](https://secure.php.net/manual/en/function.uasort.php#refsect1-function.uasort-parameters), which is what the collection's `sort` method calls utilizes internally.
-> {tip} If you need to sort a collection of nested arrays or objects, see the [`sortBy`](#method-sortby) and [`sortByDesc`](#method-sortbydesc) methods.
+> [!NOTE]
+> If you need to sort a collection of nested arrays or objects, see the [sortBy](#method-sortby) and [sortByDesc](#method-sortbydesc) methods.
#### `sortBy()` {.collection-method}
-The `sortBy` method sorts the collection by the given key. The sorted collection keeps the original array keys, so in the following example we will use the [`values`](#method-values) method to reset the keys to consecutively numbered indexes:
+The `sortBy` method sorts the collection by the given key. The sorted collection keeps the original array keys, so in the following example we will use the [values](#method-values) method to reset the keys to consecutively numbered indexes:
- $collection = collect([
- ['name' => 'Desk', 'price' => 200],
+```php
+$collection = collect([
+ ['name' => 'Desk', 'price' => 200],
+ ['name' => 'Chair', 'price' => 100],
+ ['name' => 'Bookcase', 'price' => 150],
+]);
+
+$sorted = $collection->sortBy('price');
+
+$sorted->values()->all();
+
+/*
+ [
['name' => 'Chair', 'price' => 100],
['name' => 'Bookcase', 'price' => 150],
- ]);
+ ['name' => 'Desk', 'price' => 200],
+ ]
+*/
+```
- $sorted = $collection->sortBy('price');
+The `sortBy` method accepts [sort flags](https://www.php.net/manual/en/function.sort.php) as its second argument:
- $sorted->values()->all();
+```php
+$collection = collect([
+ ['title' => 'Item 1'],
+ ['title' => 'Item 12'],
+ ['title' => 'Item 3'],
+]);
- /*
- [
- ['name' => 'Chair', 'price' => 100],
- ['name' => 'Bookcase', 'price' => 150],
- ['name' => 'Desk', 'price' => 200],
- ]
- */
+$sorted = $collection->sortBy('title', SORT_NATURAL);
-The `sortBy` method accepts [sort flags](https://www.php.net/manual/en/function.sort.php) as its second argument:
+$sorted->values()->all();
- $collection = collect([
+/*
+ [
['title' => 'Item 1'],
- ['title' => 'Item 12'],
['title' => 'Item 3'],
- ]);
+ ['title' => 'Item 12'],
+ ]
+*/
+```
- $sorted = $collection->sortBy('title', SORT_NATURAL);
+Alternatively, you may pass your own closure to determine how to sort the collection's values:
- $sorted->values()->all();
+```php
+$collection = collect([
+ ['name' => 'Desk', 'colors' => ['Black', 'Mahogany']],
+ ['name' => 'Chair', 'colors' => ['Black']],
+ ['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']],
+]);
- /*
- [
- ['title' => 'Item 1'],
- ['title' => 'Item 3'],
- ['title' => 'Item 12'],
- ]
- */
+$sorted = $collection->sortBy(function (array $product, int $key) {
+ return count($product['colors']);
+});
-Alternatively, you may pass your own closure to determine how to sort the collection's values:
+$sorted->values()->all();
- $collection = collect([
- ['name' => 'Desk', 'colors' => ['Black', 'Mahogany']],
+/*
+ [
['name' => 'Chair', 'colors' => ['Black']],
+ ['name' => 'Desk', 'colors' => ['Black', 'Mahogany']],
['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']],
- ]);
+ ]
+*/
+```
- $sorted = $collection->sortBy(function ($product, $key) {
- return count($product['colors']);
- });
+If you would like to sort your collection by multiple attributes, you may pass an array of sort operations to the `sortBy` method. Each sort operation should be an array consisting of the attribute that you wish to sort by and the direction of the desired sort:
- $sorted->values()->all();
+```php
+$collection = collect([
+ ['name' => 'Taylor Otwell', 'age' => 34],
+ ['name' => 'Abigail Otwell', 'age' => 30],
+ ['name' => 'Taylor Otwell', 'age' => 36],
+ ['name' => 'Abigail Otwell', 'age' => 32],
+]);
- /*
- [
- ['name' => 'Chair', 'colors' => ['Black']],
- ['name' => 'Desk', 'colors' => ['Black', 'Mahogany']],
- ['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']],
- ]
- */
+$sorted = $collection->sortBy([
+ ['name', 'asc'],
+ ['age', 'desc'],
+]);
-If you would like to sort your collection by multiple attributes, you may pass an array of sort operations to the `sortBy` method. Each sort operation should be an array consisting of the attribute that you wish to sort by and the direction of the desired sort:
+$sorted->values()->all();
- $collection = collect([
- ['name' => 'Taylor Otwell', 'age' => 34],
+/*
+ [
+ ['name' => 'Abigail Otwell', 'age' => 32],
['name' => 'Abigail Otwell', 'age' => 30],
['name' => 'Taylor Otwell', 'age' => 36],
- ['name' => 'Abigail Otwell', 'age' => 32],
- ]);
+ ['name' => 'Taylor Otwell', 'age' => 34],
+ ]
+*/
+```
- $sorted = $collection->sortBy([
- ['name', 'asc'],
- ['age', 'desc'],
- ]);
+When sorting a collection by multiple attributes, you may also provide closures that define each sort operation:
- $sorted->values()->all();
+```php
+$collection = collect([
+ ['name' => 'Taylor Otwell', 'age' => 34],
+ ['name' => 'Abigail Otwell', 'age' => 30],
+ ['name' => 'Taylor Otwell', 'age' => 36],
+ ['name' => 'Abigail Otwell', 'age' => 32],
+]);
- /*
- [
- ['name' => 'Abigail Otwell', 'age' => 32],
- ['name' => 'Abigail Otwell', 'age' => 30],
- ['name' => 'Taylor Otwell', 'age' => 36],
- ['name' => 'Taylor Otwell', 'age' => 34],
- ]
- */
+$sorted = $collection->sortBy([
+ fn (array $a, array $b) => $a['name'] <=> $b['name'],
+ fn (array $a, array $b) => $b['age'] <=> $a['age'],
+]);
-When sorting a collection by multiple attributes, you may also provide closures that define each sort operation:
+$sorted->values()->all();
- $collection = collect([
- ['name' => 'Taylor Otwell', 'age' => 34],
+/*
+ [
+ ['name' => 'Abigail Otwell', 'age' => 32],
['name' => 'Abigail Otwell', 'age' => 30],
['name' => 'Taylor Otwell', 'age' => 36],
- ['name' => 'Abigail Otwell', 'age' => 32],
- ]);
-
- $sorted = $collection->sortBy([
- fn ($a, $b) => $a['name'] <=> $b['name'],
- fn ($a, $b) => $b['age'] <=> $a['age'],
- ]);
-
- $sorted->values()->all();
-
- /*
- [
- ['name' => 'Abigail Otwell', 'age' => 32],
- ['name' => 'Abigail Otwell', 'age' => 30],
- ['name' => 'Taylor Otwell', 'age' => 36],
- ['name' => 'Taylor Otwell', 'age' => 34],
- ]
- */
+ ['name' => 'Taylor Otwell', 'age' => 34],
+ ]
+*/
+```
#### `sortByDesc()` {.collection-method}
-This method has the same signature as the [`sortBy`](#method-sortby) method, but will sort the collection in the opposite order.
+This method has the same signature as the [sortBy](#method-sortby) method, but will sort the collection in the opposite order.
#### `sortDesc()` {.collection-method}
-This method will sort the collection in the opposite order as the [`sort`](#method-sort) method:
+This method will sort the collection in the opposite order as the [sort](#method-sort) method:
- $collection = collect([5, 3, 1, 2, 4]);
+```php
+$collection = collect([5, 3, 1, 2, 4]);
- $sorted = $collection->sortDesc();
+$sorted = $collection->sortDesc();
- $sorted->values()->all();
+$sorted->values()->all();
- // [5, 4, 3, 2, 1]
+// [5, 4, 3, 2, 1]
+```
-Unlike `sort`, you may not pass a closure to `sortDesc`. Instead, you should use the [`sort`](#method-sort) method and invert your comparison.
+Unlike `sort`, you may not pass a closure to `sortDesc`. Instead, you should use the [sort](#method-sort) method and invert your comparison.
#### `sortKeys()` {.collection-method}
The `sortKeys` method sorts the collection by the keys of the underlying associative array:
- $collection = collect([
- 'id' => 22345,
- 'first' => 'John',
- 'last' => 'Doe',
- ]);
+```php
+$collection = collect([
+ 'id' => 22345,
+ 'first' => 'John',
+ 'last' => 'Doe',
+]);
- $sorted = $collection->sortKeys();
+$sorted = $collection->sortKeys();
- $sorted->all();
+$sorted->all();
- /*
- [
- 'first' => 'John',
- 'id' => 22345,
- 'last' => 'Doe',
- ]
- */
+/*
+ [
+ 'first' => 'John',
+ 'id' => 22345,
+ 'last' => 'Doe',
+ ]
+*/
+```
#### `sortKeysDesc()` {.collection-method}
-This method has the same signature as the [`sortKeys`](#method-sortkeys) method, but will sort the collection in the opposite order.
+This method has the same signature as the [sortKeys](#method-sortkeys) method, but will sort the collection in the opposite order.
#### `sortKeysUsing()` {.collection-method}
The `sortKeysUsing` method sorts the collection by the keys of the underlying associative array using a callback:
- $collection = collect([
- 'ID' => 22345,
- 'first' => 'John',
- 'last' => 'Doe',
- ]);
+```php
+$collection = collect([
+ 'ID' => 22345,
+ 'first' => 'John',
+ 'last' => 'Doe',
+]);
- $sorted = $collection->sortKeysUsing('strnatcasecmp');
+$sorted = $collection->sortKeysUsing('strnatcasecmp');
- $sorted->all();
+$sorted->all();
- /*
- [
- 'first' => 'John',
- 'ID' => 22345,
- 'last' => 'Doe',
- ]
- */
+/*
+ [
+ 'first' => 'John',
+ 'ID' => 22345,
+ 'last' => 'Doe',
+ ]
+*/
+```
-The callback must be a comparison function that returns an integer less than, equal to, or greater than zero. For more information, refer to the PHP documentation on [`uksort`](https://www.php.net/manual/en/function.uksort.php#refsect1-function.uksort-parameters), which is the PHP function that `sortKeysUsing` method utilizes internally.
+The callback must be a comparison function that returns an integer less than, equal to, or greater than zero. For more information, refer to the PHP documentation on [uksort](https://www.php.net/manual/en/function.uksort.php#refsect1-function.uksort-parameters), which is the PHP function that `sortKeysUsing` method utilizes internally.
#### `splice()` {.collection-method}
The `splice` method removes and returns a slice of items starting at the specified index:
- $collection = collect([1, 2, 3, 4, 5]);
+```php
+$collection = collect([1, 2, 3, 4, 5]);
- $chunk = $collection->splice(2);
+$chunk = $collection->splice(2);
- $chunk->all();
+$chunk->all();
- // [3, 4, 5]
+// [3, 4, 5]
- $collection->all();
+$collection->all();
- // [1, 2]
+// [1, 2]
+```
You may pass a second argument to limit the size of the resulting collection:
- $collection = collect([1, 2, 3, 4, 5]);
+```php
+$collection = collect([1, 2, 3, 4, 5]);
- $chunk = $collection->splice(2, 1);
+$chunk = $collection->splice(2, 1);
- $chunk->all();
+$chunk->all();
- // [3]
+// [3]
- $collection->all();
+$collection->all();
- // [1, 2, 4, 5]
+// [1, 2, 4, 5]
+```
In addition, you may pass a third argument containing the new items to replace the items removed from the collection:
- $collection = collect([1, 2, 3, 4, 5]);
+```php
+$collection = collect([1, 2, 3, 4, 5]);
- $chunk = $collection->splice(2, 1, [10, 11]);
+$chunk = $collection->splice(2, 1, [10, 11]);
- $chunk->all();
+$chunk->all();
- // [3]
+// [3]
- $collection->all();
+$collection->all();
- // [1, 2, 10, 11, 4, 5]
+// [1, 2, 10, 11, 4, 5]
+```
#### `split()` {.collection-method}
The `split` method breaks a collection into the given number of groups:
- $collection = collect([1, 2, 3, 4, 5]);
+```php
+$collection = collect([1, 2, 3, 4, 5]);
- $groups = $collection->split(3);
+$groups = $collection->split(3);
- $groups->all();
+$groups->all();
- // [[1, 2], [3, 4], [5]]
+// [[1, 2], [3, 4], [5]]
+```
#### `splitIn()` {.collection-method}
The `splitIn` method breaks a collection into the given number of groups, filling non-terminal groups completely before allocating the remainder to the final group:
- $collection = collect([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+```php
+$collection = collect([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
- $groups = $collection->splitIn(3);
+$groups = $collection->splitIn(3);
- $groups->all();
+$groups->all();
- // [[1, 2, 3, 4], [5, 6, 7, 8], [9, 10]]
+// [[1, 2, 3, 4], [5, 6, 7, 8], [9, 10]]
+```
#### `sum()` {.collection-method}
The `sum` method returns the sum of all items in the collection:
- collect([1, 2, 3, 4, 5])->sum();
+```php
+collect([1, 2, 3, 4, 5])->sum();
- // 15
+// 15
+```
If the collection contains nested arrays or objects, you should pass a key that will be used to determine which values to sum:
- $collection = collect([
- ['name' => 'JavaScript: The Good Parts', 'pages' => 176],
- ['name' => 'JavaScript: The Definitive Guide', 'pages' => 1096],
- ]);
+```php
+$collection = collect([
+ ['name' => 'JavaScript: The Good Parts', 'pages' => 176],
+ ['name' => 'JavaScript: The Definitive Guide', 'pages' => 1096],
+]);
- $collection->sum('pages');
+$collection->sum('pages');
- // 1272
+// 1272
+```
In addition, you may pass your own closure to determine which values of the collection to sum:
- $collection = collect([
- ['name' => 'Chair', 'colors' => ['Black']],
- ['name' => 'Desk', 'colors' => ['Black', 'Mahogany']],
- ['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']],
- ]);
+```php
+$collection = collect([
+ ['name' => 'Chair', 'colors' => ['Black']],
+ ['name' => 'Desk', 'colors' => ['Black', 'Mahogany']],
+ ['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']],
+]);
- $collection->sum(function ($product) {
- return count($product['colors']);
- });
+$collection->sum(function (array $product) {
+ return count($product['colors']);
+});
- // 6
+// 6
+```
#### `take()` {.collection-method}
The `take` method returns a new collection with the specified number of items:
- $collection = collect([0, 1, 2, 3, 4, 5]);
+```php
+$collection = collect([0, 1, 2, 3, 4, 5]);
- $chunk = $collection->take(3);
+$chunk = $collection->take(3);
- $chunk->all();
+$chunk->all();
- // [0, 1, 2]
+// [0, 1, 2]
+```
You may also pass a negative integer to take the specified number of items from the end of the collection:
- $collection = collect([0, 1, 2, 3, 4, 5]);
+```php
+$collection = collect([0, 1, 2, 3, 4, 5]);
- $chunk = $collection->take(-2);
+$chunk = $collection->take(-2);
- $chunk->all();
+$chunk->all();
- // [4, 5]
+// [4, 5]
+```
#### `takeUntil()` {.collection-method}
The `takeUntil` method returns items in the collection until the given callback returns `true`:
- $collection = collect([1, 2, 3, 4]);
+```php
+$collection = collect([1, 2, 3, 4]);
- $subset = $collection->takeUntil(function ($item) {
- return $item >= 3;
- });
+$subset = $collection->takeUntil(function (int $item) {
+ return $item >= 3;
+});
- $subset->all();
+$subset->all();
- // [1, 2]
+// [1, 2]
+```
You may also pass a simple value to the `takeUntil` method to get the items until the given value is found:
- $collection = collect([1, 2, 3, 4]);
+```php
+$collection = collect([1, 2, 3, 4]);
- $subset = $collection->takeUntil(3);
+$subset = $collection->takeUntil(3);
- $subset->all();
+$subset->all();
- // [1, 2]
+// [1, 2]
+```
-> {note} If the given value is not found or the callback never returns `true`, the `takeUntil` method will return all items in the collection.
+> [!WARNING]
+> If the given value is not found or the callback never returns `true`, the `takeUntil` method will return all items in the collection.
#### `takeWhile()` {.collection-method}
The `takeWhile` method returns items in the collection until the given callback returns `false`:
- $collection = collect([1, 2, 3, 4]);
+```php
+$collection = collect([1, 2, 3, 4]);
- $subset = $collection->takeWhile(function ($item) {
- return $item < 3;
- });
+$subset = $collection->takeWhile(function (int $item) {
+ return $item < 3;
+});
- $subset->all();
+$subset->all();
- // [1, 2]
+// [1, 2]
+```
-> {note} If the callback never returns `false`, the `takeWhile` method will return all items in the collection.
+> [!WARNING]
+> If the callback never returns `false`, the `takeWhile` method will return all items in the collection.
#### `tap()` {.collection-method}
The `tap` method passes the collection to the given callback, allowing you to "tap" into the collection at a specific point and do something with the items while not affecting the collection itself. The collection is then returned by the `tap` method:
- collect([2, 4, 3, 1, 5])
- ->sort()
- ->tap(function ($collection) {
- Log::debug('Values after sorting', $collection->values()->all());
- })
- ->shift();
+```php
+collect([2, 4, 3, 1, 5])
+ ->sort()
+ ->tap(function (Collection $collection) {
+ Log::debug('Values after sorting', $collection->values()->all());
+ })
+ ->shift();
- // 1
+// 1
+```
#### `times()` {.collection-method}
The static `times` method creates a new collection by invoking the given closure a specified number of times:
- $collection = Collection::times(10, function ($number) {
- return $number * 9;
- });
+```php
+$collection = Collection::times(10, function (int $number) {
+ return $number * 9;
+});
- $collection->all();
+$collection->all();
- // [9, 18, 27, 36, 45, 54, 63, 72, 81, 90]
+// [9, 18, 27, 36, 45, 54, 63, 72, 81, 90]
+```
#### `toArray()` {.collection-method}
The `toArray` method converts the collection into a plain PHP `array`. If the collection's values are [Eloquent](/docs/{{version}}/eloquent) models, the models will also be converted to arrays:
- $collection = collect(['name' => 'Desk', 'price' => 200]);
+```php
+$collection = collect(['name' => 'Desk', 'price' => 200]);
- $collection->toArray();
+$collection->toArray();
- /*
- [
- ['name' => 'Desk', 'price' => 200],
- ]
- */
+/*
+ [
+ ['name' => 'Desk', 'price' => 200],
+ ]
+*/
+```
-> {note} `toArray` also converts all of the collection's nested objects that are an instance of `Arrayable` to an array. If you want to get the raw array underlying the collection, use the [`all`](#method-all) method instead.
+> [!WARNING]
+> `toArray` also converts all of the collection's nested objects that are an instance of `Arrayable` to an array. If you want to get the raw array underlying the collection, use the [all](#method-all) method instead.
#### `toJson()` {.collection-method}
The `toJson` method converts the collection into a JSON serialized string:
- $collection = collect(['name' => 'Desk', 'price' => 200]);
+```php
+$collection = collect(['name' => 'Desk', 'price' => 200]);
+
+$collection->toJson();
+
+// '{"name":"Desk", "price":200}'
+```
+
+
+#### `toPrettyJson()` {.collection-method}
- $collection->toJson();
+The `toPrettyJson` method converts the collection into a formatted JSON string using the `JSON_PRETTY_PRINT` option:
- // '{"name":"Desk", "price":200}'
+```php
+$collection = collect(['name' => 'Desk', 'price' => 200]);
+
+$collection->toPrettyJson();
+```
#### `transform()` {.collection-method}
The `transform` method iterates over the collection and calls the given callback with each item in the collection. The items in the collection will be replaced by the values returned by the callback:
- $collection = collect([1, 2, 3, 4, 5]);
+```php
+$collection = collect([1, 2, 3, 4, 5]);
- $collection->transform(function ($item, $key) {
- return $item * 2;
- });
+$collection->transform(function (int $item, int $key) {
+ return $item * 2;
+});
- $collection->all();
+$collection->all();
- // [2, 4, 6, 8, 10]
+// [2, 4, 6, 8, 10]
+```
-> {note} Unlike most other collection methods, `transform` modifies the collection itself. If you wish to create a new collection instead, use the [`map`](#method-map) method.
+> [!WARNING]
+> Unlike most other collection methods, `transform` modifies the collection itself. If you wish to create a new collection instead, use the [map](#method-map) method.
#### `undot()` {.collection-method}
The `undot` method expands a single-dimensional collection that uses "dot" notation into a multi-dimensional collection:
- $person = collect([
- 'name.first_name' => 'Marie',
- 'name.last_name' => 'Valentine',
- 'address.line_1' => '2992 Eagle Drive',
- 'address.line_2' => '',
- 'address.suburb' => 'Detroit',
- 'address.state' => 'MI',
- 'address.postcode' => '48219'
- ])
+```php
+$person = collect([
+ 'name.first_name' => 'Marie',
+ 'name.last_name' => 'Valentine',
+ 'address.line_1' => '2992 Eagle Drive',
+ 'address.line_2' => '',
+ 'address.suburb' => 'Detroit',
+ 'address.state' => 'MI',
+ 'address.postcode' => '48219'
+]);
- $person = $person->undot();
+$person = $person->undot();
- $person->toArray();
+$person->toArray();
- /*
- [
- "name" => [
- "first_name" => "Marie",
- "last_name" => "Valentine",
- ],
- "address" => [
- "line_1" => "2992 Eagle Drive",
- "line_2" => "",
- "suburb" => "Detroit",
- "state" => "MI",
- "postcode" => "48219",
- ],
- ]
- */
+/*
+ [
+ "name" => [
+ "first_name" => "Marie",
+ "last_name" => "Valentine",
+ ],
+ "address" => [
+ "line_1" => "2992 Eagle Drive",
+ "line_2" => "",
+ "suburb" => "Detroit",
+ "state" => "MI",
+ "postcode" => "48219",
+ ],
+ ]
+*/
+```
#### `union()` {.collection-method}
The `union` method adds the given array to the collection. If the given array contains keys that are already in the original collection, the original collection's values will be preferred:
- $collection = collect([1 => ['a'], 2 => ['b']]);
+```php
+$collection = collect([1 => ['a'], 2 => ['b']]);
- $union = $collection->union([3 => ['c'], 1 => ['d']]);
+$union = $collection->union([3 => ['c'], 1 => ['d']]);
- $union->all();
+$union->all();
- // [1 => ['a'], 2 => ['b'], 3 => ['c']]
+// [1 => ['a'], 2 => ['b'], 3 => ['c']]
+```
#### `unique()` {.collection-method}
-The `unique` method returns all of the unique items in the collection. The returned collection keeps the original array keys, so in the following example we will use the [`values`](#method-values) method to reset the keys to consecutively numbered indexes:
+The `unique` method returns all of the unique items in the collection. The returned collection keeps the original array keys, so in the following example we will use the [values](#method-values) method to reset the keys to consecutively numbered indexes:
- $collection = collect([1, 1, 2, 2, 3, 4, 2]);
+```php
+$collection = collect([1, 1, 2, 2, 3, 4, 2]);
- $unique = $collection->unique();
+$unique = $collection->unique();
- $unique->values()->all();
+$unique->values()->all();
- // [1, 2, 3, 4]
+// [1, 2, 3, 4]
+```
When dealing with nested arrays or objects, you may specify the key used to determine uniqueness:
- $collection = collect([
- ['name' => 'iPhone 6', 'brand' => 'Apple', 'type' => 'phone'],
- ['name' => 'iPhone 5', 'brand' => 'Apple', 'type' => 'phone'],
- ['name' => 'Apple Watch', 'brand' => 'Apple', 'type' => 'watch'],
- ['name' => 'Galaxy S6', 'brand' => 'Samsung', 'type' => 'phone'],
- ['name' => 'Galaxy Gear', 'brand' => 'Samsung', 'type' => 'watch'],
- ]);
+```php
+$collection = collect([
+ ['name' => 'iPhone 6', 'brand' => 'Apple', 'type' => 'phone'],
+ ['name' => 'iPhone 5', 'brand' => 'Apple', 'type' => 'phone'],
+ ['name' => 'Apple Watch', 'brand' => 'Apple', 'type' => 'watch'],
+ ['name' => 'Galaxy S6', 'brand' => 'Samsung', 'type' => 'phone'],
+ ['name' => 'Galaxy Gear', 'brand' => 'Samsung', 'type' => 'watch'],
+]);
- $unique = $collection->unique('brand');
+$unique = $collection->unique('brand');
- $unique->values()->all();
+$unique->values()->all();
- /*
- [
- ['name' => 'iPhone 6', 'brand' => 'Apple', 'type' => 'phone'],
- ['name' => 'Galaxy S6', 'brand' => 'Samsung', 'type' => 'phone'],
- ]
- */
+/*
+ [
+ ['name' => 'iPhone 6', 'brand' => 'Apple', 'type' => 'phone'],
+ ['name' => 'Galaxy S6', 'brand' => 'Samsung', 'type' => 'phone'],
+ ]
+*/
+```
Finally, you may also pass your own closure to the `unique` method to specify which value should determine an item's uniqueness:
- $unique = $collection->unique(function ($item) {
- return $item['brand'].$item['type'];
- });
+```php
+$unique = $collection->unique(function (array $item) {
+ return $item['brand'].$item['type'];
+});
- $unique->values()->all();
+$unique->values()->all();
- /*
- [
- ['name' => 'iPhone 6', 'brand' => 'Apple', 'type' => 'phone'],
- ['name' => 'Apple Watch', 'brand' => 'Apple', 'type' => 'watch'],
- ['name' => 'Galaxy S6', 'brand' => 'Samsung', 'type' => 'phone'],
- ['name' => 'Galaxy Gear', 'brand' => 'Samsung', 'type' => 'watch'],
- ]
- */
+/*
+ [
+ ['name' => 'iPhone 6', 'brand' => 'Apple', 'type' => 'phone'],
+ ['name' => 'Apple Watch', 'brand' => 'Apple', 'type' => 'watch'],
+ ['name' => 'Galaxy S6', 'brand' => 'Samsung', 'type' => 'phone'],
+ ['name' => 'Galaxy Gear', 'brand' => 'Samsung', 'type' => 'watch'],
+ ]
+*/
+```
-The `unique` method uses "loose" comparisons when checking item values, meaning a string with an integer value will be considered equal to an integer of the same value. Use the [`uniqueStrict`](#method-uniquestrict) method to filter using "strict" comparisons.
+The `unique` method uses "loose" comparisons when checking item values, meaning a string with an integer value will be considered equal to an integer of the same value. Use the [uniqueStrict](#method-uniquestrict) method to filter using "strict" comparisons.
-> {tip} This method's behavior is modified when using [Eloquent Collections](/docs/{{version}}/eloquent-collections#method-unique).
+> [!NOTE]
+> This method's behavior is modified when using [Eloquent Collections](/docs/{{version}}/eloquent-collections#method-unique).
#### `uniqueStrict()` {.collection-method}
-This method has the same signature as the [`unique`](#method-unique) method; however, all values are compared using "strict" comparisons.
+This method has the same signature as the [unique](#method-unique) method; however, all values are compared using "strict" comparisons.
#### `unless()` {.collection-method}
-The `unless` method will execute the given callback unless the first argument given to the method evaluates to `true`:
+The `unless` method will execute the given callback unless the first argument given to the method evaluates to `true`. The collection instance and the first argument given to the `unless` method will be provided to the closure:
- $collection = collect([1, 2, 3]);
+```php
+$collection = collect([1, 2, 3]);
- $collection->unless(true, function ($collection) {
- return $collection->push(4);
- });
+$collection->unless(true, function (Collection $collection, bool $value) {
+ return $collection->push(4);
+});
- $collection->unless(false, function ($collection) {
- return $collection->push(5);
- });
+$collection->unless(false, function (Collection $collection, bool $value) {
+ return $collection->push(5);
+});
- $collection->all();
+$collection->all();
- // [1, 2, 3, 5]
+// [1, 2, 3, 5]
+```
A second callback may be passed to the `unless` method. The second callback will be executed when the first argument given to the `unless` method evaluates to `true`:
- $collection = collect([1, 2, 3]);
+```php
+$collection = collect([1, 2, 3]);
- $collection->unless(true, function ($collection) {
- return $collection->push(4);
- }, function ($collection) {
- return $collection->push(5);
- });
+$collection->unless(true, function (Collection $collection, bool $value) {
+ return $collection->push(4);
+}, function (Collection $collection, bool $value) {
+ return $collection->push(5);
+});
- $collection->all();
+$collection->all();
- // [1, 2, 3, 5]
+// [1, 2, 3, 5]
+```
-For the inverse of `unless`, see the [`when`](#method-when) method.
+For the inverse of `unless`, see the [when](#method-when) method.
#### `unlessEmpty()` {.collection-method}
-Alias for the [`whenNotEmpty`](#method-whennotempty) method.
+Alias for the [whenNotEmpty](#method-whennotempty) method.
#### `unlessNotEmpty()` {.collection-method}
-Alias for the [`whenEmpty`](#method-whenempty) method.
+Alias for the [whenEmpty](#method-whenempty) method.
#### `unwrap()` {.collection-method}
The static `unwrap` method returns the collection's underlying items from the given value when applicable:
- Collection::unwrap(collect('John Doe'));
+```php
+Collection::unwrap(collect('John Doe'));
- // ['John Doe']
+// ['John Doe']
- Collection::unwrap(['John Doe']);
+Collection::unwrap(['John Doe']);
+
+// ['John Doe']
+
+Collection::unwrap('John Doe');
+
+// 'John Doe'
+```
- // ['John Doe']
+
+#### `value()` {.collection-method}
- Collection::unwrap('John Doe');
+The `value` method retrieves a given value from the first element of the collection:
- // 'John Doe'
+```php
+$collection = collect([
+ ['product' => 'Desk', 'price' => 200],
+ ['product' => 'Speaker', 'price' => 400],
+]);
+
+$value = $collection->value('price');
+
+// 200
+```
#### `values()` {.collection-method}
The `values` method returns a new collection with the keys reset to consecutive integers:
- $collection = collect([
- 10 => ['product' => 'Desk', 'price' => 200],
- 11 => ['product' => 'Desk', 'price' => 200],
- ]);
+```php
+$collection = collect([
+ 10 => ['product' => 'Desk', 'price' => 200],
+ 11 => ['product' => 'Desk', 'price' => 200],
+]);
- $values = $collection->values();
+$values = $collection->values();
- $values->all();
+$values->all();
- /*
- [
- 0 => ['product' => 'Desk', 'price' => 200],
- 1 => ['product' => 'Desk', 'price' => 200],
- ]
- */
+/*
+ [
+ 0 => ['product' => 'Desk', 'price' => 200],
+ 1 => ['product' => 'Desk', 'price' => 200],
+ ]
+*/
+```
#### `when()` {.collection-method}
-The `when` method will execute the given callback when the first argument given to the method evaluates to `true`:
+The `when` method will execute the given callback when the first argument given to the method evaluates to `true`. The collection instance and the first argument given to the `when` method will be provided to the closure:
- $collection = collect([1, 2, 3]);
+```php
+$collection = collect([1, 2, 3]);
- $collection->when(true, function ($collection) {
- return $collection->push(4);
- });
+$collection->when(true, function (Collection $collection, bool $value) {
+ return $collection->push(4);
+});
- $collection->when(false, function ($collection) {
- return $collection->push(5);
- });
+$collection->when(false, function (Collection $collection, bool $value) {
+ return $collection->push(5);
+});
- $collection->all();
+$collection->all();
- // [1, 2, 3, 4]
+// [1, 2, 3, 4]
+```
A second callback may be passed to the `when` method. The second callback will be executed when the first argument given to the `when` method evaluates to `false`:
- $collection = collect([1, 2, 3]);
+```php
+$collection = collect([1, 2, 3]);
- $collection->when(false, function ($collection) {
- return $collection->push(4);
- }, function ($collection) {
- return $collection->push(5);
- });
+$collection->when(false, function (Collection $collection, bool $value) {
+ return $collection->push(4);
+}, function (Collection $collection, bool $value) {
+ return $collection->push(5);
+});
- $collection->all();
+$collection->all();
- // [1, 2, 3, 5]
+// [1, 2, 3, 5]
+```
-For the inverse of `when`, see the [`unless`](#method-unless) method.
+For the inverse of `when`, see the [unless](#method-unless) method.
#### `whenEmpty()` {.collection-method}
The `whenEmpty` method will execute the given callback when the collection is empty:
- $collection = collect(['Michael', 'Tom']);
+```php
+$collection = collect(['Michael', 'Tom']);
- $collection->whenEmpty(function ($collection) {
- return $collection->push('Adam');
- });
-
- $collection->all();
+$collection->whenEmpty(function (Collection $collection) {
+ return $collection->push('Adam');
+});
- // ['Michael', 'Tom']
+$collection->all();
+// ['Michael', 'Tom']
- $collection = collect();
+$collection = collect();
- $collection->whenEmpty(function ($collection) {
- return $collection->push('Adam');
- });
+$collection->whenEmpty(function (Collection $collection) {
+ return $collection->push('Adam');
+});
- $collection->all();
+$collection->all();
- // ['Adam']
+// ['Adam']
+```
A second closure may be passed to the `whenEmpty` method that will be executed when the collection is not empty:
- $collection = collect(['Michael', 'Tom']);
+```php
+$collection = collect(['Michael', 'Tom']);
- $collection->whenEmpty(function ($collection) {
- return $collection->push('Adam');
- }, function ($collection) {
- return $collection->push('Taylor');
- });
+$collection->whenEmpty(function (Collection $collection) {
+ return $collection->push('Adam');
+}, function (Collection $collection) {
+ return $collection->push('Taylor');
+});
- $collection->all();
+$collection->all();
- // ['Michael', 'Tom', 'Taylor']
+// ['Michael', 'Tom', 'Taylor']
+```
-For the inverse of `whenEmpty`, see the [`whenNotEmpty`](#method-whennotempty) method.
+For the inverse of `whenEmpty`, see the [whenNotEmpty](#method-whennotempty) method.
#### `whenNotEmpty()` {.collection-method}
The `whenNotEmpty` method will execute the given callback when the collection is not empty:
- $collection = collect(['michael', 'tom']);
+```php
+$collection = collect(['Michael', 'Tom']);
- $collection->whenNotEmpty(function ($collection) {
- return $collection->push('adam');
- });
+$collection->whenNotEmpty(function (Collection $collection) {
+ return $collection->push('Adam');
+});
- $collection->all();
+$collection->all();
- // ['michael', 'tom', 'adam']
+// ['Michael', 'Tom', 'Adam']
+$collection = collect();
- $collection = collect();
+$collection->whenNotEmpty(function (Collection $collection) {
+ return $collection->push('Adam');
+});
- $collection->whenNotEmpty(function ($collection) {
- return $collection->push('adam');
- });
-
- $collection->all();
+$collection->all();
- // []
+// []
+```
A second closure may be passed to the `whenNotEmpty` method that will be executed when the collection is empty:
- $collection = collect();
+```php
+$collection = collect();
- $collection->whenNotEmpty(function ($collection) {
- return $collection->push('adam');
- }, function ($collection) {
- return $collection->push('taylor');
- });
+$collection->whenNotEmpty(function (Collection $collection) {
+ return $collection->push('Adam');
+}, function (Collection $collection) {
+ return $collection->push('Taylor');
+});
- $collection->all();
+$collection->all();
- // ['taylor']
+// ['Taylor']
+```
-For the inverse of `whenNotEmpty`, see the [`whenEmpty`](#method-whenempty) method.
+For the inverse of `whenNotEmpty`, see the [whenEmpty](#method-whenempty) method.
#### `where()` {.collection-method}
The `where` method filters the collection by a given key / value pair:
- $collection = collect([
- ['product' => 'Desk', 'price' => 200],
- ['product' => 'Chair', 'price' => 100],
- ['product' => 'Bookcase', 'price' => 150],
- ['product' => 'Door', 'price' => 100],
- ]);
+```php
+$collection = collect([
+ ['product' => 'Desk', 'price' => 200],
+ ['product' => 'Chair', 'price' => 100],
+ ['product' => 'Bookcase', 'price' => 150],
+ ['product' => 'Door', 'price' => 100],
+]);
- $filtered = $collection->where('price', 100);
+$filtered = $collection->where('price', 100);
- $filtered->all();
+$filtered->all();
- /*
- [
- ['product' => 'Chair', 'price' => 100],
- ['product' => 'Door', 'price' => 100],
- ]
- */
+/*
+ [
+ ['product' => 'Chair', 'price' => 100],
+ ['product' => 'Door', 'price' => 100],
+ ]
+*/
+```
-The `where` method uses "loose" comparisons when checking item values, meaning a string with an integer value will be considered equal to an integer of the same value. Use the [`whereStrict`](#method-wherestrict) method to filter using "strict" comparisons.
+The `where` method uses "loose" comparisons when checking item values, meaning a string with an integer value will be considered equal to an integer of the same value. Use the [whereStrict](#method-wherestrict) method to filter using "strict" comparisons, or the [whereNull](#method-wherenull) and [whereNotNull](#method-wherenotnull) methods to filter for `null` values.
-Optionally, you may pass a comparison operator as the second parameter.
+Optionally, you may pass a comparison operator as the second parameter. Supported operators are: '===', '!==', '!=', '==', '=', '<>', '>', '<', '>=', and '<=':
- $collection = collect([
- ['name' => 'Jim', 'deleted_at' => '2019-01-01 00:00:00'],
- ['name' => 'Sally', 'deleted_at' => '2019-01-02 00:00:00'],
- ['name' => 'Sue', 'deleted_at' => null],
- ]);
+```php
+$collection = collect([
+ ['name' => 'Jim', 'platform' => 'Mac'],
+ ['name' => 'Sally', 'platform' => 'Mac'],
+ ['name' => 'Sue', 'platform' => 'Linux'],
+]);
- $filtered = $collection->where('deleted_at', '!=', null);
+$filtered = $collection->where('platform', '!=', 'Linux');
- $filtered->all();
+$filtered->all();
- /*
- [
- ['name' => 'Jim', 'deleted_at' => '2019-01-01 00:00:00'],
- ['name' => 'Sally', 'deleted_at' => '2019-01-02 00:00:00'],
- ]
- */
+/*
+ [
+ ['name' => 'Jim', 'platform' => 'Mac'],
+ ['name' => 'Sally', 'platform' => 'Mac'],
+ ]
+*/
+```
#### `whereStrict()` {.collection-method}
-This method has the same signature as the [`where`](#method-where) method; however, all values are compared using "strict" comparisons.
+This method has the same signature as the [where](#method-where) method; however, all values are compared using "strict" comparisons.
#### `whereBetween()` {.collection-method}
The `whereBetween` method filters the collection by determining if a specified item value is within a given range:
- $collection = collect([
- ['product' => 'Desk', 'price' => 200],
- ['product' => 'Chair', 'price' => 80],
- ['product' => 'Bookcase', 'price' => 150],
- ['product' => 'Pencil', 'price' => 30],
- ['product' => 'Door', 'price' => 100],
- ]);
+```php
+$collection = collect([
+ ['product' => 'Desk', 'price' => 200],
+ ['product' => 'Chair', 'price' => 80],
+ ['product' => 'Bookcase', 'price' => 150],
+ ['product' => 'Pencil', 'price' => 30],
+ ['product' => 'Door', 'price' => 100],
+]);
- $filtered = $collection->whereBetween('price', [100, 200]);
+$filtered = $collection->whereBetween('price', [100, 200]);
- $filtered->all();
+$filtered->all();
- /*
- [
- ['product' => 'Desk', 'price' => 200],
- ['product' => 'Bookcase', 'price' => 150],
- ['product' => 'Door', 'price' => 100],
- ]
- */
+/*
+ [
+ ['product' => 'Desk', 'price' => 200],
+ ['product' => 'Bookcase', 'price' => 150],
+ ['product' => 'Door', 'price' => 100],
+ ]
+*/
+```
#### `whereIn()` {.collection-method}
The `whereIn` method removes elements from the collection that do not have a specified item value that is contained within the given array:
- $collection = collect([
- ['product' => 'Desk', 'price' => 200],
- ['product' => 'Chair', 'price' => 100],
- ['product' => 'Bookcase', 'price' => 150],
- ['product' => 'Door', 'price' => 100],
- ]);
+```php
+$collection = collect([
+ ['product' => 'Desk', 'price' => 200],
+ ['product' => 'Chair', 'price' => 100],
+ ['product' => 'Bookcase', 'price' => 150],
+ ['product' => 'Door', 'price' => 100],
+]);
- $filtered = $collection->whereIn('price', [150, 200]);
+$filtered = $collection->whereIn('price', [150, 200]);
- $filtered->all();
+$filtered->all();
- /*
- [
- ['product' => 'Desk', 'price' => 200],
- ['product' => 'Bookcase', 'price' => 150],
- ]
- */
+/*
+ [
+ ['product' => 'Desk', 'price' => 200],
+ ['product' => 'Bookcase', 'price' => 150],
+ ]
+*/
+```
-The `whereIn` method uses "loose" comparisons when checking item values, meaning a string with an integer value will be considered equal to an integer of the same value. Use the [`whereInStrict`](#method-whereinstrict) method to filter using "strict" comparisons.
+The `whereIn` method uses "loose" comparisons when checking item values, meaning a string with an integer value will be considered equal to an integer of the same value. Use the [whereInStrict](#method-whereinstrict) method to filter using "strict" comparisons.
#### `whereInStrict()` {.collection-method}
-This method has the same signature as the [`whereIn`](#method-wherein) method; however, all values are compared using "strict" comparisons.
+This method has the same signature as the [whereIn](#method-wherein) method; however, all values are compared using "strict" comparisons.
#### `whereInstanceOf()` {.collection-method}
The `whereInstanceOf` method filters the collection by a given class type:
- use App\Models\User;
- use App\Models\Post;
+```php
+use App\Models\User;
+use App\Models\Post;
- $collection = collect([
- new User,
- new User,
- new Post,
- ]);
+$collection = collect([
+ new User,
+ new User,
+ new Post,
+]);
- $filtered = $collection->whereInstanceOf(User::class);
+$filtered = $collection->whereInstanceOf(User::class);
- $filtered->all();
+$filtered->all();
- // [App\Models\User, App\Models\User]
+// [App\Models\User, App\Models\User]
+```
#### `whereNotBetween()` {.collection-method}
The `whereNotBetween` method filters the collection by determining if a specified item value is outside of a given range:
- $collection = collect([
- ['product' => 'Desk', 'price' => 200],
- ['product' => 'Chair', 'price' => 80],
- ['product' => 'Bookcase', 'price' => 150],
- ['product' => 'Pencil', 'price' => 30],
- ['product' => 'Door', 'price' => 100],
- ]);
+```php
+$collection = collect([
+ ['product' => 'Desk', 'price' => 200],
+ ['product' => 'Chair', 'price' => 80],
+ ['product' => 'Bookcase', 'price' => 150],
+ ['product' => 'Pencil', 'price' => 30],
+ ['product' => 'Door', 'price' => 100],
+]);
- $filtered = $collection->whereNotBetween('price', [100, 200]);
+$filtered = $collection->whereNotBetween('price', [100, 200]);
- $filtered->all();
+$filtered->all();
- /*
- [
- ['product' => 'Chair', 'price' => 80],
- ['product' => 'Pencil', 'price' => 30],
- ]
- */
+/*
+ [
+ ['product' => 'Chair', 'price' => 80],
+ ['product' => 'Pencil', 'price' => 30],
+ ]
+*/
+```
#### `whereNotIn()` {.collection-method}
The `whereNotIn` method removes elements from the collection that have a specified item value that is contained within the given array:
- $collection = collect([
- ['product' => 'Desk', 'price' => 200],
- ['product' => 'Chair', 'price' => 100],
- ['product' => 'Bookcase', 'price' => 150],
- ['product' => 'Door', 'price' => 100],
- ]);
+```php
+$collection = collect([
+ ['product' => 'Desk', 'price' => 200],
+ ['product' => 'Chair', 'price' => 100],
+ ['product' => 'Bookcase', 'price' => 150],
+ ['product' => 'Door', 'price' => 100],
+]);
- $filtered = $collection->whereNotIn('price', [150, 200]);
+$filtered = $collection->whereNotIn('price', [150, 200]);
- $filtered->all();
+$filtered->all();
- /*
- [
- ['product' => 'Chair', 'price' => 100],
- ['product' => 'Door', 'price' => 100],
- ]
- */
+/*
+ [
+ ['product' => 'Chair', 'price' => 100],
+ ['product' => 'Door', 'price' => 100],
+ ]
+*/
+```
-The `whereNotIn` method uses "loose" comparisons when checking item values, meaning a string with an integer value will be considered equal to an integer of the same value. Use the [`whereNotInStrict`](#method-wherenotinstrict) method to filter using "strict" comparisons.
+The `whereNotIn` method uses "loose" comparisons when checking item values, meaning a string with an integer value will be considered equal to an integer of the same value. Use the [whereNotInStrict](#method-wherenotinstrict) method to filter using "strict" comparisons.
#### `whereNotInStrict()` {.collection-method}
-This method has the same signature as the [`whereNotIn`](#method-wherenotin) method; however, all values are compared using "strict" comparisons.
+This method has the same signature as the [whereNotIn](#method-wherenotin) method; however, all values are compared using "strict" comparisons.
#### `whereNotNull()` {.collection-method}
The `whereNotNull` method returns items from the collection where the given key is not `null`:
- $collection = collect([
- ['name' => 'Desk'],
- ['name' => null],
- ['name' => 'Bookcase'],
- ]);
+```php
+$collection = collect([
+ ['name' => 'Desk'],
+ ['name' => null],
+ ['name' => 'Bookcase'],
+ ['name' => 0],
+ ['name' => ''],
+]);
- $filtered = $collection->whereNotNull('name');
+$filtered = $collection->whereNotNull('name');
- $filtered->all();
+$filtered->all();
- /*
- [
- ['name' => 'Desk'],
- ['name' => 'Bookcase'],
- ]
- */
+/*
+ [
+ ['name' => 'Desk'],
+ ['name' => 'Bookcase'],
+ ['name' => 0],
+ ['name' => ''],
+ ]
+*/
+```
#### `whereNull()` {.collection-method}
The `whereNull` method returns items from the collection where the given key is `null`:
- $collection = collect([
- ['name' => 'Desk'],
- ['name' => null],
- ['name' => 'Bookcase'],
- ]);
-
- $filtered = $collection->whereNull('name');
+```php
+$collection = collect([
+ ['name' => 'Desk'],
+ ['name' => null],
+ ['name' => 'Bookcase'],
+ ['name' => 0],
+ ['name' => ''],
+]);
- $filtered->all();
+$filtered = $collection->whereNull('name');
- /*
- [
- ['name' => null],
- ]
- */
+$filtered->all();
+/*
+ [
+ ['name' => null],
+ ]
+*/
+```
#### `wrap()` {.collection-method}
The static `wrap` method wraps the given value in a collection when applicable:
- use Illuminate\Support\Collection;
+```php
+use Illuminate\Support\Collection;
- $collection = Collection::wrap('John Doe');
+$collection = Collection::wrap('John Doe');
- $collection->all();
+$collection->all();
- // ['John Doe']
+// ['John Doe']
- $collection = Collection::wrap(['John Doe']);
+$collection = Collection::wrap(['John Doe']);
- $collection->all();
+$collection->all();
- // ['John Doe']
+// ['John Doe']
- $collection = Collection::wrap(collect('John Doe'));
+$collection = Collection::wrap(collect('John Doe'));
- $collection->all();
+$collection->all();
- // ['John Doe']
+// ['John Doe']
+```
#### `zip()` {.collection-method}
The `zip` method merges together the values of the given array with the values of the original collection at their corresponding index:
- $collection = collect(['Chair', 'Desk']);
+```php
+$collection = collect(['Chair', 'Desk']);
- $zipped = $collection->zip([100, 200]);
+$zipped = $collection->zip([100, 200]);
- $zipped->all();
+$zipped->all();
- // [['Chair', 100], ['Desk', 200]]
+// [['Chair', 100], ['Desk', 200]]
+```
## Higher Order Messages
-Collections also provide support for "higher order messages", which are short-cuts for performing common actions on collections. The collection methods that provide higher order messages are: [`average`](#method-average), [`avg`](#method-avg), [`contains`](#method-contains), [`each`](#method-each), [`every`](#method-every), [`filter`](#method-filter), [`first`](#method-first), [`flatMap`](#method-flatmap), [`groupBy`](#method-groupby), [`keyBy`](#method-keyby), [`map`](#method-map), [`max`](#method-max), [`min`](#method-min), [`partition`](#method-partition), [`reject`](#method-reject), [`skipUntil`](#method-skipuntil), [`skipWhile`](#method-skipwhile), [`some`](#method-some), [`sortBy`](#method-sortby), [`sortByDesc`](#method-sortbydesc), [`sum`](#method-sum), [`takeUntil`](#method-takeuntil), [`takeWhile`](#method-takewhile), and [`unique`](#method-unique).
+Collections also provide support for "higher order messages", which are short-cuts for performing common actions on collections. The collection methods that provide higher order messages are: [average](#method-average), [avg](#method-avg), [contains](#method-contains), [each](#method-each), [every](#method-every), [filter](#method-filter), [first](#method-first), [flatMap](#method-flatmap), [groupBy](#method-groupby), [keyBy](#method-keyby), [map](#method-map), [max](#method-max), [min](#method-min), [partition](#method-partition), [reject](#method-reject), [skipUntil](#method-skipuntil), [skipWhile](#method-skipwhile), [some](#method-some), [sortBy](#method-sortby), [sortByDesc](#method-sortbydesc), [sum](#method-sum), [takeUntil](#method-takeuntil), [takeWhile](#method-takewhile), and [unique](#method-unique).
Each higher order message can be accessed as a dynamic property on a collection instance. For instance, let's use the `each` higher order message to call a method on each object within a collection:
- use App\Models\User;
+```php
+use App\Models\User;
- $users = User::where('votes', '>', 500)->get();
+$users = User::where('votes', '>', 500)->get();
- $users->each->markAsVip();
+$users->each->markAsVip();
+```
Likewise, we can use the `sum` higher order message to gather the total number of "votes" for a collection of users:
- $users = User::where('group', 'Development')->get();
+```php
+$users = User::where('group', 'Development')->get();
- return $users->sum->votes;
+return $users->sum->votes;
+```
## Lazy Collections
@@ -3188,68 +4036,94 @@ Likewise, we can use the `sum` higher order message to gather the total number o
### Introduction
-> {note} Before learning more about Laravel's lazy collections, take some time to familiarize yourself with [PHP generators](https://www.php.net/manual/en/language.generators.overview.php).
+> [!WARNING]
+> Before learning more about Laravel's lazy collections, take some time to familiarize yourself with [PHP generators](https://www.php.net/manual/en/language.generators.overview.php).
To supplement the already powerful `Collection` class, the `LazyCollection` class leverages PHP's [generators](https://www.php.net/manual/en/language.generators.overview.php) to allow you to work with very large datasets while keeping memory usage low.
For example, imagine your application needs to process a multi-gigabyte log file while taking advantage of Laravel's collection methods to parse the logs. Instead of reading the entire file into memory at once, lazy collections may be used to keep only a small part of the file in memory at a given time:
- use App\Models\LogEntry;
- use Illuminate\Support\LazyCollection;
+```php
+use App\Models\LogEntry;
+use Illuminate\Support\LazyCollection;
- LazyCollection::make(function () {
- $handle = fopen('log.txt', 'r');
+LazyCollection::make(function () {
+ $handle = fopen('log.txt', 'r');
- while (($line = fgets($handle)) !== false) {
- yield $line;
- }
- })->chunk(4)->map(function ($lines) {
- return LogEntry::fromLines($lines);
- })->each(function (LogEntry $logEntry) {
- // Process the log entry...
- });
+ while (($line = fgets($handle)) !== false) {
+ yield $line;
+ }
+
+ fclose($handle);
+})->chunk(4)->map(function (array $lines) {
+ return LogEntry::fromLines($lines);
+})->each(function (LogEntry $logEntry) {
+ // Process the log entry...
+});
+```
Or, imagine you need to iterate through 10,000 Eloquent models. When using traditional Laravel collections, all 10,000 Eloquent models must be loaded into memory at the same time:
- use App\Models\User;
+```php
+use App\Models\User;
- $users = User::all()->filter(function ($user) {
- return $user->id > 500;
- });
+$users = User::all()->filter(function (User $user) {
+ return $user->id > 500;
+});
+```
However, the query builder's `cursor` method returns a `LazyCollection` instance. This allows you to still only run a single query against the database but also only keep one Eloquent model loaded in memory at a time. In this example, the `filter` callback is not executed until we actually iterate over each user individually, allowing for a drastic reduction in memory usage:
- use App\Models\User;
+```php
+use App\Models\User;
- $users = User::cursor()->filter(function ($user) {
- return $user->id > 500;
- });
+$users = User::cursor()->filter(function (User $user) {
+ return $user->id > 500;
+});
- foreach ($users as $user) {
- echo $user->id;
- }
+foreach ($users as $user) {
+ echo $user->id;
+}
+```
### Creating Lazy Collections
To create a lazy collection instance, you should pass a PHP generator function to the collection's `make` method:
- use Illuminate\Support\LazyCollection;
+```php
+use Illuminate\Support\LazyCollection;
- LazyCollection::make(function () {
- $handle = fopen('log.txt', 'r');
+LazyCollection::make(function () {
+ $handle = fopen('log.txt', 'r');
- while (($line = fgets($handle)) !== false) {
- yield $line;
- }
- });
+ while (($line = fgets($handle)) !== false) {
+ yield $line;
+ }
+
+ fclose($handle);
+});
+```
### The Enumerable Contract
Almost all methods available on the `Collection` class are also available on the `LazyCollection` class. Both of these classes implement the `Illuminate\Support\Enumerable` contract, which defines the following methods:
-
@@ -544,7 +571,7 @@ Below is a list of additional Homestead service ports that you may wish to map f
### PHP Versions
-Homestead 6 introduced support for running multiple versions of PHP on the same virtual machine. You may specify which version of PHP to use for a given site within your `Homestead.yaml` file. The available PHP versions are: "5.6", "7.0", "7.1", "7.2", "7.3", "7.4", "8.0" (the default), and "8.1":
+Homestead supports running multiple versions of PHP on the same virtual machine. You may specify which version of PHP to use for a given site within your `Homestead.yaml` file. The available PHP versions are: "5.6", "7.0", "7.1", "7.2", "7.3", "7.4", "8.0", "8.1", "8.2", and "8.3", (the default):
```yaml
sites:
@@ -564,6 +591,8 @@ php7.3 artisan list
php7.4 artisan list
php8.0 artisan list
php8.1 artisan list
+php8.2 artisan list
+php8.3 artisan list
```
You may change the default version of PHP used by the CLI by issuing the following commands from within your Homestead virtual machine:
@@ -577,28 +606,33 @@ php73
php74
php80
php81
+php82
+php83
```
-### Connecting To Databases
+### Connecting to Databases
A `homestead` database is configured for both MySQL and PostgreSQL out of the box. To connect to your MySQL or PostgreSQL database from your host machine's database client, you should connect to `127.0.0.1` on port `33060` (MySQL) or `54320` (PostgreSQL). The username and password for both databases is `homestead` / `secret`.
-> {note} You should only use these non-standard ports when connecting to the databases from your host machine. You will use the default 3306 and 5432 ports in your Laravel application's `database` configuration file since Laravel is running _within_ the virtual machine.
+> [!WARNING]
+> You should only use these non-standard ports when connecting to the databases from your host machine. You will use the default 3306 and 5432 ports in your Laravel application's `database` configuration file since Laravel is running _within_ the virtual machine.
### Database Backups
Homestead can automatically backup your database when your Homestead virtual machine is destroyed. To utilize this feature, you must be using Vagrant 2.1.0 or greater. Or, if you are using an older version of Vagrant, you must install the `vagrant-triggers` plug-in. To enable automatic database backups, add the following line to your `Homestead.yaml` file:
- backup: true
+```yaml
+backup: true
+```
-Once configured, Homestead will export your databases to `mysql_backup` and `postgres_backup` directories when the `vagrant destroy` command is executed. These directories can be found in the folder where you installed Homestead or in the root of your project if you are using the [per project installation](#per-project-installation) method.
+Once configured, Homestead will export your databases to `.backup/mysql_backup` and `.backup/postgres_backup` directories when the `vagrant destroy` command is executed. These directories can be found in the folder where you installed Homestead or in the root of your project if you are using the [per project installation](#per-project-installation) method.
### Configuring Cron Schedules
-Laravel provides a convenient way to [schedule cron jobs](/docs/{{version}}/scheduling) by scheduling a single `schedule:run` Artisan command to run every minute. The `schedule:run` command will examine the job schedule defined in your `App\Console\Kernel` class to determine which scheduled tasks to run.
+Laravel provides a convenient way to [schedule cron jobs](/docs/{{version}}/scheduling) by scheduling a single `schedule:run` Artisan command to run every minute. The `schedule:run` command will examine the job schedule defined in your `routes/console.php` file to determine which scheduled tasks to run.
If you would like the `schedule:run` command to be run for a Homestead site, you may set the `schedule` option to `true` when defining the site:
@@ -611,10 +645,10 @@ sites:
The cron job for the site will be defined in the `/etc/cron.d` directory of the Homestead virtual machine.
-
-### Configuring MailHog
+
+### Configuring Mailpit
-[MailHog](https://github.com/mailhog/MailHog) allows you to intercept your outgoing email and examine it without actually sending the mail to its recipients. To get started, update your application's `.env` file to use the following mail settings:
+[Mailpit](https://github.com/axllent/mailpit) allows you to intercept your outgoing email and examine it without actually sending the mail to its recipients. To get started, update your application's `.env` file to use the following mail settings:
```ini
MAIL_MAILER=smtp
@@ -625,7 +659,7 @@ MAIL_PASSWORD=null
MAIL_ENCRYPTION=null
```
-Once MailHog has been configured, you may access the MailHog dashboard at `http://localhost:8025`.
+Once Mailpit has been configured, you may access the Mailpit dashboard at `http://localhost:8025`.
### Configuring Minio
@@ -636,25 +670,14 @@ Once MailHog has been configured, you may access the MailHog dashboard at `http:
By default, Minio is available on port 9600. You may access the Minio control panel by visiting `http://localhost:9600`. The default access key is `homestead`, while the default secret key is `secretkey`. When accessing Minio, you should always use region `us-east-1`.
-In order to use Minio, you will need to adjust the S3 disk configuration in your application's `config/filesystems.php` configuration file. You will need to add the `use_path_style_endpoint` option to the disk configuration as well as change the `url` key to `endpoint`:
-
- 's3' => [
- 'driver' => 's3',
- 'key' => env('AWS_ACCESS_KEY_ID'),
- 'secret' => env('AWS_SECRET_ACCESS_KEY'),
- 'region' => env('AWS_DEFAULT_REGION'),
- 'bucket' => env('AWS_BUCKET'),
- 'endpoint' => env('AWS_URL'),
- 'use_path_style_endpoint' => true,
- ]
-
-Finally, ensure your `.env` file has the following options:
+In order to use Minio, ensure your `.env` file has the following options:
```ini
+AWS_USE_PATH_STYLE_ENDPOINT=true
+AWS_ENDPOINT=http://localhost:9600
AWS_ACCESS_KEY_ID=homestead
AWS_SECRET_ACCESS_KEY=secretkey
AWS_DEFAULT_REGION=us-east-1
-AWS_URL=http://localhost:9600
```
To provision Minio powered "S3" buckets, add a `buckets` directive to your `Homestead.yaml` file. After defining your buckets, you should execute the `vagrant reload --provision` command in your terminal:
@@ -672,7 +695,7 @@ Supported `policy` values include: `none`, `download`, `upload`, and `public`.
### Laravel Dusk
-In order to run [Laravel Dusk](/docs/{{version}}/dusk) tests within Homestead, you should enable the [`webdriver` feature](#installing-optional-features) in your Homestead configuration:
+In order to run [Laravel Dusk](/docs/{{version}}/dusk) tests within Homestead, you should enable the [webdriver feature](#installing-optional-features) in your Homestead configuration:
```yaml
features:
@@ -698,10 +721,13 @@ After running the command, you will see an Ngrok screen appear which contains th
share homestead.test -region=eu -subdomain=laravel
```
-> {note} Remember, Vagrant is inherently insecure and you are exposing your virtual machine to the Internet when running the `share` command.
+If you need to share content over HTTPS rather than HTTP, using the `sshare` command instead of `share` will enable you to do so.
+
+> [!WARNING]
+> Remember, Vagrant is inherently insecure and you are exposing your virtual machine to the Internet when running the `share` command.
-## Debugging & Profiling
+## Debugging and Profiling
### Debugging Web Requests With Xdebug
@@ -710,7 +736,8 @@ Homestead includes support for step debugging using [Xdebug](https://xdebug.org)
By default, Xdebug is already running and ready to accept connections. If you need to enable Xdebug on the CLI, execute the `sudo phpenmod xdebug` command within your Homestead virtual machine. Next, follow your IDE's instructions to enable debugging. Finally, configure your browser to trigger Xdebug with an extension or [bookmarklet](https://www.jetbrains.com/phpstorm/marklets/).
-> {note} Xdebug causes PHP to run significantly slower. To disable Xdebug, run `sudo phpdismod xdebug` within your Homestead virtual machine and restart the FPM service.
+> [!WARNING]
+> Xdebug causes PHP to run significantly slower. To disable Xdebug, run `sudo phpdismod xdebug` within your Homestead virtual machine and restart the FPM service.
#### Autostarting Xdebug
@@ -719,8 +746,9 @@ When debugging functional tests that make requests to the web server, it is easi
```ini
; If Homestead.yaml contains a different subnet for the IP address, this address may be different...
-xdebug.remote_host = 192.168.10.1
-xdebug.remote_autostart = 1
+xdebug.client_host = 192.168.10.1
+xdebug.mode = debug
+xdebug.start_with_request = yes
```
@@ -728,10 +756,12 @@ xdebug.remote_autostart = 1
To debug a PHP CLI application, use the `xphp` shell alias inside your Homestead virtual machine:
- xphp /path/to/script
+```shell
+xphp /path/to/script
+```
-### Profiling Applications with Blackfire
+### Profiling Applications With Blackfire
[Blackfire](https://blackfire.io/docs/introduction) is a service for profiling web requests and CLI applications. It offers an interactive user interface which displays profile data in call-graphs and timelines. It is built for use in development, staging, and production, with no overhead for end users. In addition, Blackfire provides performance, quality, and security checks on code and `php.ini` configuration settings.
@@ -748,7 +778,7 @@ features:
client_token: "client_value"
```
-Blackfire server credentials and client credentials [require a Blackfire account](https://blackfire.io/signup). Blackfire offers various options to profile an application, including a CLI tool and browser extension. Please [review the Blackfire documentation for more details](https://blackfire.io/docs/cookbooks/index).
+Blackfire server credentials and client credentials [require a Blackfire account](https://blackfire.io/signup). Blackfire offers various options to profile an application, including a CLI tool and browser extension. Please [review the Blackfire documentation for more details](https://blackfire.io/docs/php/integrations/laravel/index).
## Network Interfaces
@@ -761,7 +791,7 @@ networks:
ip: "192.168.10.20"
```
-To enable a [bridged](https://www.vagrantup.com/docs/networking/public_network.html) interface, configure a `bridge` setting for the network and change the network type to `public_network`:
+To enable a [bridged](https://developer.hashicorp.com/vagrant/docs/networking/public_network) interface, configure a `bridge` setting for the network and change the network type to `public_network`:
```yaml
networks:
@@ -770,12 +800,22 @@ networks:
bridge: "en1: Wi-Fi (AirPort)"
```
-To enable [DHCP](https://www.vagrantup.com/docs/networking/public_network.html), just remove the `ip` option from your configuration:
+To enable [DHCP](https://developer.hashicorp.com/vagrant/docs/networking/public_network#dhcp), just remove the `ip` option from your configuration:
+
+```yaml
+networks:
+ - type: "public_network"
+ bridge: "en1: Wi-Fi (AirPort)"
+```
+
+To update what device the network is using, you may add a `dev` option to the network's configuration. The default `dev` value is `eth0`:
```yaml
networks:
- type: "public_network"
+ ip: "192.168.10.20"
bridge: "en1: Wi-Fi (AirPort)"
+ dev: "enp2s0"
```
@@ -812,14 +852,3 @@ By default, Homestead configures the `natdnshostresolver` setting to `on`. This
provider: virtualbox
natdnshostresolver: 'off'
```
-
-
-#### Symbolic Links On Windows
-
-If symbolic links are not working properly on your Windows machine, you may need to add the following block to your `Vagrantfile`:
-
-```ruby
-config.vm.provider "virtualbox" do |v|
- v.customize ["setextradata", :id, "VBoxInternal2/SharedFoldersEnableSymlinksCreate/v-root", "1"]
-end
-```
diff --git a/horizon.md b/horizon.md
index f049137a925..f5628aced49 100644
--- a/horizon.md
+++ b/horizon.md
@@ -3,8 +3,15 @@
- [Introduction](#introduction)
- [Installation](#installation)
- [Configuration](#configuration)
- - [Balancing Strategies](#balancing-strategies)
- [Dashboard Authorization](#dashboard-authorization)
+ - [Max Job Attempts](#max-job-attempts)
+ - [Job Timeout](#job-timeout)
+ - [Job Backoff](#job-backoff)
+ - [Silenced Jobs](#silenced-jobs)
+- [Balancing Strategies](#balancing-strategies)
+ - [Auto Balancing](#auto-balancing)
+ - [Simple Balancing](#simple-balancing)
+ - [No Balancing](#no-balancing)
- [Upgrading Horizon](#upgrading-horizon)
- [Running Horizon](#running-horizon)
- [Deploying Horizon](#deploying-horizon)
@@ -17,7 +24,8 @@
## Introduction
-> {tip} Before digging into Laravel Horizon, you should familiarize yourself with Laravel's base [queue services](/docs/{{version}}/queues). Horizon augments Laravel's queue with additional features that may be confusing if you are not already familiar with the basic queue features offered by Laravel.
+> [!NOTE]
+> Before digging into Laravel Horizon, you should familiarize yourself with Laravel's base [queue services](/docs/{{version}}/queues). Horizon augments Laravel's queue with additional features that may be confusing if you are not already familiar with the basic queue features offered by Laravel.
[Laravel Horizon](https://github.com/laravel/horizon) provides a beautiful dashboard and code-driven configuration for your Laravel powered [Redis queues](/docs/{{version}}/queues). Horizon allows you to easily monitor key metrics of your queue system such as job throughput, runtime, and job failures.
@@ -28,7 +36,8 @@ When using Horizon, all of your queue worker configuration is stored in a single
## Installation
-> {note} Laravel Horizon requires that you use [Redis](https://redis.io) to power your queue. Therefore, you should ensure that your queue connection is set to `redis` in your application's `config/queue.php` configuration file.
+> [!WARNING]
+> Laravel Horizon requires that you use [Redis](https://redis.io) to power your queue. Therefore, you should ensure that your queue connection is set to `redis` in your application's `config/queue.php` configuration file.
You may install Horizon into your project using the Composer package manager:
@@ -47,122 +56,386 @@ php artisan horizon:install
After publishing Horizon's assets, its primary configuration file will be located at `config/horizon.php`. This configuration file allows you to configure the queue worker options for your application. Each configuration option includes a description of its purpose, so be sure to thoroughly explore this file.
-> {note} Horizon uses a Redis connection named `horizon` internally. This Redis connection name is reserved and should not be assigned to another Redis connection in the `database.php` configuration file or as the value of the `use` option in the `horizon.php` configuration file.
+> [!WARNING]
+> Horizon uses a Redis connection named `horizon` internally. This Redis connection name is reserved and should not be assigned to another Redis connection in the `database.php` configuration file or as the value of the `use` option in the `horizon.php` configuration file.
#### Environments
After installation, the primary Horizon configuration option that you should familiarize yourself with is the `environments` configuration option. This configuration option is an array of environments that your application runs on and defines the worker process options for each environment. By default, this entry contains a `production` and `local` environment. However, you are free to add more environments as needed:
- 'environments' => [
- 'production' => [
- 'supervisor-1' => [
- 'maxProcesses' => 10,
- 'balanceMaxShift' => 1,
- 'balanceCooldown' => 3,
- ],
+```php
+'environments' => [
+ 'production' => [
+ 'supervisor-1' => [
+ 'maxProcesses' => 10,
+ 'balanceMaxShift' => 1,
+ 'balanceCooldown' => 3,
],
+ ],
+
+ 'local' => [
+ 'supervisor-1' => [
+ 'maxProcesses' => 3,
+ ],
+ ],
+],
+```
+
+You may also define a wildcard environment (`*`) which will be used when no other matching environment is found:
- 'local' => [
- 'supervisor-1' => [
- 'maxProcesses' => 3,
- ],
+```php
+'environments' => [
+ // ...
+
+ '*' => [
+ 'supervisor-1' => [
+ 'maxProcesses' => 3,
],
],
+],
+```
When you start Horizon, it will use the worker process configuration options for the environment that your application is running on. Typically, the environment is determined by the value of the `APP_ENV` [environment variable](/docs/{{version}}/configuration#determining-the-current-environment). For example, the default `local` Horizon environment is configured to start three worker processes and automatically balance the number of worker processes assigned to each queue. The default `production` environment is configured to start a maximum of 10 worker processes and automatically balance the number of worker processes assigned to each queue.
-> {note} You should ensure that the `environments` portion of your `horizon` configuration file contains an entry for each [environment](/docs/{{version}}/configuration#environment-configuration) on which you plan to run Horizon.
+> [!WARNING]
+> You should ensure that the `environments` portion of your `horizon` configuration file contains an entry for each [environment](/docs/{{version}}/configuration#environment-configuration) on which you plan to run Horizon.
#### Supervisors
-As you can see in Horizon's default configuration file. Each environment can contain one or more "supervisors". By default, the configuration file defines this supervisor as `supervisor-1`; however, you are free to name your supervisors whatever you want. Each supervisor is essentially responsible for "supervising" a group of worker processes and takes care of balancing worker processes across queues.
+As you can see in Horizon's default configuration file, each environment can contain one or more "supervisors". By default, the configuration file defines this supervisor as `supervisor-1`; however, you are free to name your supervisors whatever you want. Each supervisor is essentially responsible for "supervising" a group of worker processes and takes care of balancing worker processes across queues.
You may add additional supervisors to a given environment if you would like to define a new group of worker processes that should run in that environment. You may choose to do this if you would like to define a different balancing strategy or worker process count for a given queue used by your application.
+
+#### Maintenance Mode
+
+While your application is in [maintenance mode](/docs/{{version}}/configuration#maintenance-mode), queued jobs will not be processed by Horizon unless the supervisor's `force` option is defined as `true` within the Horizon configuration file:
+
+```php
+'environments' => [
+ 'production' => [
+ 'supervisor-1' => [
+ // ...
+ 'force' => true,
+ ],
+ ],
+],
+```
+
#### Default Values
Within Horizon's default configuration file, you will notice a `defaults` configuration option. This configuration option specifies the default values for your application's [supervisors](#supervisors). The supervisor's default configuration values will be merged into the supervisor's configuration for each environment, allowing you to avoid unnecessary repetition when defining your supervisors.
-
-### Balancing Strategies
+
+### Dashboard Authorization
+
+The Horizon dashboard may be accessed via the `/horizon` route. By default, you will only be able to access this dashboard in the `local` environment. However, within your `app/Providers/HorizonServiceProvider.php` file, there is an [authorization gate](/docs/{{version}}/authorization#gates) definition. This authorization gate controls access to Horizon in **non-local** environments. You are free to modify this gate as needed to restrict access to your Horizon installation:
+
+```php
+/**
+ * Register the Horizon gate.
+ *
+ * This gate determines who can access Horizon in non-local environments.
+ */
+protected function gate(): void
+{
+ Gate::define('viewHorizon', function (User $user) {
+ return in_array($user->email, [
+ 'taylor@laravel.com',
+ ]);
+ });
+}
+```
+
+
+#### Alternative Authentication Strategies
-Unlike Laravel's default queue system, Horizon allows you to choose from three worker balancing strategies: `simple`, `auto`, and `false`. The `simple` strategy, which is the configuration file's default, splits incoming jobs evenly between worker processes:
+Remember that Laravel automatically injects the authenticated user into the gate closure. If your application is providing Horizon security via another method, such as IP restrictions, then your Horizon users may not need to "login". Therefore, you will need to change `function (User $user)` closure signature above to `function (User $user = null)` in order to force Laravel to not require authentication.
- 'balance' => 'simple',
+
+### Max Job Attempts
-The `auto` strategy adjusts the number of worker processes per queue based on the current workload of the queue. For example, if your `notifications` queue has 1,000 pending jobs while your `render` queue is empty, Horizon will allocate more workers to your `notifications` queue until the queue is empty.
+> [!NOTE]
+> Before refining these options, make sure you are familiar with Laravel's default [queue services](/docs/{{version}}/queues#max-job-attempts-and-timeout) and the concept of 'attempts'.
-When using the `auto` strategy, you may define the `minProcesses` and `maxProcesses` configuration options to control the minimum and the maximum number of worker processes Horizon should scale up and down to:
+You can define the maximum number of attempts a job can consume within a supervisor's configuration:
- 'environments' => [
- 'production' => [
- 'supervisor-1' => [
- 'connection' => 'redis',
- 'queue' => ['default'],
- 'balance' => 'auto',
- 'minProcesses' => 1,
- 'maxProcesses' => 10,
- 'balanceMaxShift' => 1,
- 'balanceCooldown' => 3,
- 'tries' => 3,
- ],
+```php
+'environments' => [
+ 'production' => [
+ 'supervisor-1' => [
+ // ...
+ 'tries' => 10,
],
],
+],
+```
-The `balanceMaxShift` and `balanceCooldown` configuration values to determine how quickly Horizon will scale to meet worker demand. In the example above, a maximum of one new process will be created or destroyed every three seconds. You are free to tweak these values as necessary based on your application's needs.
+> [!NOTE]
+> This option is similar to the `--tries` option when using the Artisan command to process queues.
-When the `balance` option is set to `false`, the default Laravel behavior will be used, which processes queues in the order they are listed in your configuration.
+Adjusting the `tries` option is essential when using middlewares such as `WithoutOverlapping` or `RateLimited` because they consume attempts. To handle this, adjust the `tries` configuration value either at the supervisor level or by defining the `$tries` property on the job class.
-
-### Dashboard Authorization
+If you don't set the `tries` option, Horizon defaults to a single attempt, unless the job class defines `$tries`, which takes precedence over the Horizon configuration.
-Horizon exposes a dashboard at the `/horizon` URI. By default, you will only be able to access this dashboard in the `local` environment. However, within your `app/Providers/HorizonServiceProvider.php` file, there is an [authorization gate](/docs/{{version}}/authorization#gates) definition. This authorization gate controls access to Horizon in **non-local** environments. You are free to modify this gate as needed to restrict access to your Horizon installation:
+Setting `tries` or `$tries` to 0 allows unlimited attempts, which is ideal when the number of attempts is uncertain. To prevent endless failures, you can limit the number of exceptions allowed by setting the `$maxExceptions` property on the job class.
- /**
- * Register the Horizon gate.
- *
- * This gate determines who can access Horizon in non-local environments.
- *
- * @return void
- */
- protected function gate()
- {
- Gate::define('viewHorizon', function ($user) {
- return in_array($user->email, [
- 'taylor@laravel.com',
- ]);
- });
- }
+
+### Job Timeout
-
-#### Alternative Authentication Strategies
+Similarly, you can set a `timeout` value at the supervisor level, which specifies how many seconds a worker process can run a job before it's forcefully terminated. Once terminated, the job will either be retried or marked as failed, depending on your queue configuration:
-Remember that Laravel automatically injects the authenticated user into the gate closure. If your application is providing Horizon security via another method, such as IP restrictions, then your Horizon users may not need to "login". Therefore, you will need to change `function ($user)` closure signature above to `function ($user = null)` in order to force Laravel to not require authentication.
+```php
+'environments' => [
+ 'production' => [
+ 'supervisor-1' => [
+ // ...¨
+ 'timeout' => 60,
+ ],
+ ],
+],
+```
-
-## Upgrading Horizon
+> [!WARNING]
+> When using the `auto` balancing strategy, Horizon will consider in-progress workers as "hanging" and force-kill them after the Horizon timeout during scale down. Always ensure the Horizon timeout is greater than any job-level timeout, otherwise jobs may be terminated mid-execution. In addition, the `timeout` value should always be at least a few seconds shorter than the `retry_after` value defined in your `config/queue.php` configuration file. Otherwise, your jobs may be processed twice.
-When upgrading to a new major version of Horizon, it's important that you carefully review [the upgrade guide](https://github.com/laravel/horizon/blob/master/UPGRADE.md). In addition, when upgrading to any new Horizon version, you should re-publish Horizon's assets:
+
+### Job Backoff
-```shell
-php artisan horizon:publish
+You can define the `backoff` value at the supervisor level to specify how long Horizon should wait before retrying a job that encounters an unhandled exception:
+
+```php
+'environments' => [
+ 'production' => [
+ 'supervisor-1' => [
+ // ...
+ 'backoff' => 10,
+ ],
+ ],
+],
```
-To keep the assets up-to-date and avoid issues in future updates, you may add the `horizon:publish` command to the `post-update-cmd` scripts in your application's `composer.json` file:
+You may also configure "exponential" backoffs by using an array for the `backoff` value. In this example, the retry delay will be 1 second for the first retry, 5 seconds for the second retry, 10 seconds for the third retry, and 10 seconds for every subsequent retry if there are more attempts remaining:
-```json
+```php
+'environments' => [
+ 'production' => [
+ 'supervisor-1' => [
+ // ...
+ 'backoff' => [1, 5, 10],
+ ],
+ ],
+],
+```
+
+
+### Silenced Jobs
+
+Sometimes, you may not be interested in viewing certain jobs dispatched by your application or third-party packages. Instead of these jobs taking up space in your "Completed Jobs" list, you can silence them. To get started, add the job's class name to the `silenced` configuration option in your application's `horizon` configuration file:
+
+```php
+'silenced' => [
+ App\Jobs\ProcessPodcast::class,
+],
+```
+
+In addition to silencing individual job classes, Horizon also supports silencing jobs based on [tags](#tags). This can be useful if you want to hide multiple jobs that share a common tag:
+
+```php
+'silenced_tags' => [
+ 'notifications'
+],
+```
+
+Alternatively, the job you wish to silence can implement the `Laravel\Horizon\Contracts\Silenced` interface. If a job implements this interface, it will automatically be silenced, even if it is not present in the `silenced` configuration array:
+
+```php
+use Laravel\Horizon\Contracts\Silenced;
+
+class ProcessPodcast implements ShouldQueue, Silenced
{
- "scripts": {
- "post-update-cmd": [
- "@php artisan horizon:publish --ansi"
- ]
- }
+ use Queueable;
+
+ // ...
}
```
+
+## Balancing Strategies
+
+Each supervisor can process one or more queues but unlike Laravel's default queue system, Horizon allows you to choose from three worker balancing strategies: `auto`, `simple`, and `false`.
+
+
+### Auto Balancing
+
+The `auto` strategy, which is the default strategy, adjusts the number of worker processes per queue based on the current workload of the queue. For example, if your `notifications` queue has 1,000 pending jobs while your `default` queue is empty, Horizon will allocate more workers to your `notifications` queue until the queue is empty.
+
+When using the `auto` strategy, you may also configure the `minProcesses` and `maxProcesses` configuration options:
+
+
+
+
+
+ */
+public function attachments(): array
+{
+ return [
+ Attachment::fromStorage('/path/to/file'),
+ ];
+}
+```
### StyleCI
diff --git a/controllers.md b/controllers.md
index 15425185d9a..58fa9edf15e 100644
--- a/controllers.md
+++ b/controllers.md
@@ -13,7 +13,9 @@
- [Scoping Resource Routes](#restful-scoping-resource-routes)
- [Localizing Resource URIs](#restful-localizing-resource-uris)
- [Supplementing Resource Controllers](#restful-supplementing-resource-controllers)
-- [Dependency Injection & Controllers](#dependency-injection-and-controllers)
+ - [Singleton Resource Controllers](#singleton-resource-controllers)
+ - [Middleware and Resource Controllers](#middleware-and-resource-controllers)
+- [Dependency Injection and Controllers](#dependency-injection-and-controllers)
## Introduction
@@ -26,71 +28,78 @@ Instead of defining all of your request handling logic as closures in your route
### Basic Controllers
-Let's take a look at an example of a basic controller. Note that the controller extends the base controller class included with Laravel: `App\Http\Controllers\Controller`:
+To quickly generate a new controller, you may run the `make:controller` Artisan command. By default, all of the controllers for your application are stored in the `app/Http/Controllers` directory:
- User::findOrFail($id)
- ]);
- }
+ return view('user.profile', [
+ 'user' => User::findOrFail($id)
+ ]);
}
+}
+```
-You can define a route to this controller method like so:
+Once you have written a controller class and method, you may define a route to the controller method like so:
- use App\Http\Controllers\UserController;
+```php
+use App\Http\Controllers\UserController;
- Route::get('/user/{id}', [UserController::class, 'show']);
+Route::get('/user/{id}', [UserController::class, 'show']);
+```
When an incoming request matches the specified route URI, the `show` method on the `App\Http\Controllers\UserController` class will be invoked and the route parameters will be passed to the method.
-> {tip} Controllers are not **required** to extend a base class. However, you will not have access to convenient features such as the `middleware` and `authorize` methods.
+> [!NOTE]
+> Controllers are not **required** to extend a base class. However, it is sometimes convenient to extend a base controller class that contains methods that should be shared across all of your controllers.
### Single Action Controllers
If a controller action is particularly complex, you might find it convenient to dedicate an entire controller class to that single action. To accomplish this, you may define a single `__invoke` method within the controller:
- {tip} Controller stubs may be customized using [stub publishing](/docs/{{version}}/artisan#stub-customization).
+> [!NOTE]
+> Controller stubs may be customized using [stub publishing](/docs/{{version}}/artisan#stub-customization).
## Controller Middleware
[Middleware](/docs/{{version}}/middleware) may be assigned to the controller's routes in your route files:
- Route::get('profile', [UserController::class, 'show'])->middleware('auth');
+```php
+Route::get('/profile', [UserController::class, 'show'])->middleware('auth');
+```
+
+Or, you may find it convenient to specify middleware within your controller class. To do so, your controller should implement the `HasMiddleware` interface, which dictates that the controller should have a static `middleware` method. From this method, you may return an array of middleware that should be applied to the controller's actions:
+
+```php
+middleware('auth');
- $this->middleware('log')->only('index');
- $this->middleware('subscribed')->except('store');
- }
+ return [
+ 'auth',
+ new Middleware('log', only: ['index']),
+ new Middleware('subscribed', except: ['store']),
+ ];
}
-Controllers also allow you to register middleware using a closure. This provides a convenient way to define an inline middleware for a single controller without defining an entire middleware class:
+ // ...
+}
+```
- $this->middleware(function ($request, $next) {
- return $next($request);
- });
+You may also define controller middleware as closures, which provides a convenient way to define an inline middleware without writing an entire middleware class:
+
+```php
+use Closure;
+use Illuminate\Http\Request;
+
+/**
+ * Get the middleware that should be assigned to the controller.
+ */
+public static function middleware(): array
+{
+ return [
+ function (Request $request, Closure $next) {
+ return $next($request);
+ },
+ ];
+}
+```
## Resource Controllers
@@ -143,48 +179,84 @@ php artisan make:controller PhotoController --resource
This command will generate a controller at `app/Http/Controllers/PhotoController.php`. The controller will contain a method for each of the available resource operations. Next, you may register a resource route that points to the controller:
- use App\Http\Controllers\PhotoController;
+```php
+use App\Http\Controllers\PhotoController;
- Route::resource('photos', PhotoController::class);
+Route::resource('photos', PhotoController::class);
+```
This single route declaration creates multiple routes to handle a variety of actions on the resource. The generated controller will already have methods stubbed for each of these actions. Remember, you can always get a quick overview of your application's routes by running the `route:list` Artisan command.
You may even register many resource controllers at once by passing an array to the `resources` method:
- Route::resources([
- 'photos' => PhotoController::class,
- 'posts' => PostController::class,
- ]);
+```php
+Route::resources([
+ 'photos' => PhotoController::class,
+ 'posts' => PostController::class,
+]);
+```
-
-#### Actions Handled By Resource Controller
+The `softDeletableResources` method registers many resources controllers that all use the `withTrashed` method:
-Verb | URI | Action | Route Name
-----------|------------------------|--------------|---------------------
-GET | `/photos` | index | photos.index
-GET | `/photos/create` | create | photos.create
-POST | `/photos` | store | photos.store
-GET | `/photos/{photo}` | show | photos.show
-GET | `/photos/{photo}/edit` | edit | photos.edit
-PUT/PATCH | `/photos/{photo}` | update | photos.update
-DELETE | `/photos/{photo}` | destroy | photos.destroy
+```php
+Route::softDeletableResources([
+ 'photos' => PhotoController::class,
+ 'posts' => PostController::class,
+]);
+```
+
+
+#### Actions Handled by Resource Controllers
+
+
+ */
+public function elements(): array
+{
+ return [
+ '@email' => 'input[name=email]',
+ ];
+}
+```
Once the shortcut has been defined, you may use the shorthand selector anywhere you would typically use a full CSS selector:
- $browser->type('@email', 'taylor@laravel.com');
+```php
+$browser->type('@email', 'taylor@laravel.com');
+```
#### Global Shorthand Selectors
After installing Dusk, a base `Page` class will be placed in your `tests/Browser/Pages` directory. This class contains a `siteElements` method which may be used to define global shorthand selectors that should be available on every page throughout your application:
- /**
- * Get the global element shortcuts for the site.
- *
- * @return array
- */
- public static function siteElements()
- {
- return [
- '@element' => '#selector',
- ];
- }
+```php
+/**
+ * Get the global element shortcuts for the site.
+ *
+ * @return array
+ */
+public static function siteElements(): array
+{
+ return [
+ '@element' => '#selector',
+ ];
+}
+```
### Page Methods
In addition to the default methods defined on pages, you may define additional methods which may be used throughout your tests. For example, let's imagine we are building a music management application. A common action for one page of the application might be to create a playlist. Instead of re-writing the logic to create a playlist in each test, you may define a `createPlaylist` method on a page class:
- type('name', $name)
- ->check('share')
- ->press('Create Playlist');
- }
+ $browser->type('name', $name)
+ ->check('share')
+ ->press('Create Playlist');
}
+}
+```
Once the method has been defined, you may use it within any test that utilizes the page. The browser instance will automatically be passed as the first argument to custom page methods:
- use Tests\Browser\Pages\Dashboard;
+```php
+use Tests\Browser\Pages\Dashboard;
- $browser->visit(new Dashboard)
- ->createPlaylist('My Playlist')
- ->assertSee('My Playlist');
+$browser->visit(new Dashboard)
+ ->createPlaylist('My Playlist')
+ ->assertSee('My Playlist');
+```
## Components
-Components are similar to Dusk’s “page objects”, but are intended for pieces of UI and functionality that are re-used throughout your application, such as a navigation bar or notification window. As such, components are not bound to specific URLs.
+Components are similar to Dusk's "page objects", but are intended for pieces of UI and functionality that are re-used throughout your application, such as a navigation bar or notification window. As such, components are not bound to specific URLs.
### Generating Components
To generate a component, execute the `dusk:component` Artisan command. New components are placed in the `tests/Browser/Components` directory:
- php artisan dusk:component DatePicker
+```shell
+php artisan dusk:component DatePicker
+```
As shown above, a "date picker" is an example of a component that might exist throughout your application on a variety of pages. It can become cumbersome to manually write the browser automation logic to select a date in dozens of tests throughout your test suite. Instead, we can define a Dusk component to represent the date picker, allowing us to encapsulate that logic within the component:
- assertVisible($this->selector());
- }
+ /**
+ * Assert that the browser page contains the component.
+ */
+ public function assert(Browser $browser): void
+ {
+ $browser->assertVisible($this->selector());
+ }
- /**
- * Get the element shortcuts for the component.
- *
- * @return array
- */
- public function elements()
- {
- return [
- '@date-field' => 'input.datepicker-input',
- '@year-list' => 'div > div.datepicker-years',
- '@month-list' => 'div > div.datepicker-months',
- '@day-list' => 'div > div.datepicker-days',
- ];
- }
+ /**
+ * Get the element shortcuts for the component.
+ *
+ * @return array
+ */
+ public function elements(): array
+ {
+ return [
+ '@date-field' => 'input.datepicker-input',
+ '@year-list' => 'div > div.datepicker-years',
+ '@month-list' => 'div > div.datepicker-months',
+ '@day-list' => 'div > div.datepicker-days',
+ ];
+ }
- /**
- * Select the given date.
- *
- * @param \Laravel\Dusk\Browser $browser
- * @param int $year
- * @param int $month
- * @param int $day
- * @return void
- */
- public function selectDate(Browser $browser, $year, $month, $day)
- {
- $browser->click('@date-field')
- ->within('@year-list', function ($browser) use ($year) {
- $browser->click($year);
- })
- ->within('@month-list', function ($browser) use ($month) {
- $browser->click($month);
- })
- ->within('@day-list', function ($browser) use ($day) {
- $browser->click($day);
- });
- }
+ /**
+ * Select the given date.
+ */
+ public function selectDate(Browser $browser, int $year, int $month, int $day): void
+ {
+ $browser->click('@date-field')
+ ->within('@year-list', function (Browser $browser) use ($year) {
+ $browser->click($year);
+ })
+ ->within('@month-list', function (Browser $browser) use ($month) {
+ $browser->click($month);
+ })
+ ->within('@day-list', function (Browser $browser) use ($day) {
+ $browser->click($day);
+ });
}
+}
+```
### Using Components
Once the component has been defined, we can easily select a date within the date picker from any test. And, if the logic necessary to select a date changes, we only need to update the component:
- use(DatabaseMigrations::class);
- class ExampleTest extends DuskTestCase
+test('basic example', function () {
+ $this->browse(function (Browser $browser) {
+ $browser->visit('/')
+ ->within(new DatePicker, function (Browser $browser) {
+ $browser->selectDate(2019, 1, 30);
+ })
+ ->assertSee('January');
+ });
+});
+```
+
+```php tab=PHPUnit
+browse(function (Browser $browser) {
- $browser->visit('/')
- ->within(new DatePicker, function ($browser) {
- $browser->selectDate(2019, 1, 30);
- })
- ->assertSee('January');
- });
- }
+ $this->browse(function (Browser $browser) {
+ $browser->visit('/')
+ ->within(new DatePicker, function (Browser $browser) {
+ $browser->selectDate(2019, 1, 30);
+ })
+ ->assertSee('January');
+ });
}
+}
+```
+
+The `component` method may be used to retrieve a browser instance scoped to the given component:
+
+```php
+$datePicker = $browser->component(new DatePickerComponent);
+
+$datePicker->selectDate(2019, 1, 30);
+
+$datePicker->assertSee('January');
+```
## Continuous Integration
-> {note} Most Dusk continuous integration configurations expect your Laravel application to be served using the built-in PHP development server on port 8000. Therefore, before continuing, you should ensure that your continuous integration environment has an `APP_URL` environment variable value of `http://127.0.0.1:8000`.
+> [!WARNING]
+> Most Dusk continuous integration configurations expect your Laravel application to be served using the built-in PHP development server on port 8000. Therefore, before continuing, you should ensure that your continuous integration environment has an `APP_URL` environment variable value of `http://127.0.0.1:8000`.
### Heroku CI
To run Dusk tests on [Heroku CI](https://www.heroku.com/continuous-integration), add the following Google Chrome buildpack and scripts to your Heroku `app.json` file:
- {
- "environments": {
- "test": {
- "buildpacks": [
- { "url": "heroku/php" },
- { "url": "https://github.com/heroku/heroku-buildpack-google-chrome" }
- ],
- "scripts": {
- "test-setup": "cp .env.testing .env",
- "test": "nohup bash -c './vendor/laravel/dusk/bin/chromedriver-linux > /dev/null 2>&1 &' && nohup bash -c 'php artisan serve --no-reload > /dev/null 2>&1 &' && php artisan dusk"
- }
- }
+```json
+{
+ "environments": {
+ "test": {
+ "buildpacks": [
+ { "url": "heroku/php" },
+ { "url": "https://github.com/heroku/heroku-buildpack-chrome-for-testing" }
+ ],
+ "scripts": {
+ "test-setup": "cp .env.testing .env",
+ "test": "nohup bash -c './vendor/laravel/dusk/bin/chromedriver-linux --port=9515 > /dev/null 2>&1 &' && nohup bash -c 'php artisan serve --no-reload > /dev/null 2>&1 &' && php artisan dusk"
}
}
+ }
+}
+```
### Travis CI
@@ -1820,7 +2565,7 @@ To run your Dusk tests on [Travis CI](https://travis-ci.org), use the following
language: php
php:
- - 7.3
+ - 8.2
addons:
chrome: stable
@@ -1842,7 +2587,7 @@ script:
### GitHub Actions
-If you are using [Github Actions](https://github.com/features/actions) to run your Dusk tests, you may use the following configuration file as a starting point. Like TravisCI, we will use the `php artisan serve` command to launch PHP's built-in web server:
+If you are using [GitHub Actions](https://github.com/features/actions) to run your Dusk tests, you may use the following configuration file as a starting point. Like TravisCI, we will use the `php artisan serve` command to launch PHP's built-in web server:
```yaml
name: CI
@@ -1851,38 +2596,89 @@ jobs:
dusk-php:
runs-on: ubuntu-latest
+ env:
+ APP_URL: "http://127.0.0.1:8000/"
+ DB_USERNAME: root
+ DB_PASSWORD: root
+ MAIL_MAILER: log
steps:
- - uses: actions/checkout@v2
+ - uses: actions/checkout@v5
- name: Prepare The Environment
run: cp .env.example .env
- name: Create Database
run: |
sudo systemctl start mysql
- mysql --user="root" --password="root" -e "CREATE DATABASE 'my-database' character set UTF8mb4 collate utf8mb4_bin;"
+ mysql --user="root" --password="root" -e "CREATE DATABASE \`my-database\` character set UTF8mb4 collate utf8mb4_bin;"
- name: Install Composer Dependencies
run: composer install --no-progress --prefer-dist --optimize-autoloader
- name: Generate Application Key
run: php artisan key:generate
- name: Upgrade Chrome Driver
- run: php artisan dusk:chrome-driver `/opt/google/chrome/chrome --version | cut -d " " -f3 | cut -d "." -f1`
+ run: php artisan dusk:chrome-driver --detect
- name: Start Chrome Driver
- run: ./vendor/laravel/dusk/bin/chromedriver-linux &
+ run: ./vendor/laravel/dusk/bin/chromedriver-linux --port=9515 &
- name: Run Laravel Server
run: php artisan serve --no-reload &
- name: Run Dusk Tests
- env:
- APP_URL: "http://127.0.0.1:8000/"
run: php artisan dusk
- name: Upload Screenshots
if: failure()
- uses: actions/upload-artifact@v2
+ uses: actions/upload-artifact@v4
with:
name: screenshots
path: tests/Browser/screenshots
- name: Upload Console Logs
if: failure()
- uses: actions/upload-artifact@v2
+ uses: actions/upload-artifact@v4
with:
name: console
path: tests/Browser/console
```
+
+
+### Chipper CI
+
+If you are using [Chipper CI](https://chipperci.com) to run your Dusk tests, you may use the following configuration file as a starting point. We will use PHP's built-in server to run Laravel so we can listen for requests:
+
+```yaml
+# file .chipperci.yml
+version: 1
+
+environment:
+ php: 8.2
+ node: 16
+
+# Include Chrome in the build environment
+services:
+ - dusk
+
+# Build all commits
+on:
+ push:
+ branches: .*
+
+pipeline:
+ - name: Setup
+ cmd: |
+ cp -v .env.example .env
+ composer install --no-interaction --prefer-dist --optimize-autoloader
+ php artisan key:generate
+
+ # Create a dusk env file, ensuring APP_URL uses BUILD_HOST
+ cp -v .env .env.dusk.ci
+ sed -i "s@APP_URL=.*@APP_URL=http://$BUILD_HOST:8000@g" .env.dusk.ci
+
+ - name: Compile Assets
+ cmd: |
+ npm ci --no-audit
+ npm run build
+
+ - name: Browser Tests
+ cmd: |
+ php -S [::0]:8000 -t public 2>server.log &
+ sleep 2
+ php artisan dusk:chrome-driver $CHROME_DRIVER
+ php artisan dusk --env=ci
+```
+
+To learn more about running Dusk tests on Chipper CI, including how to use databases, consult the [official Chipper CI documentation](https://chipperci.com/docs/testing/laravel-dusk-new/).
diff --git a/eloquent-collections.md b/eloquent-collections.md
index dd90ef55d36..9eec2ebd366 100644
--- a/eloquent-collections.md
+++ b/eloquent-collections.md
@@ -11,21 +11,25 @@ All Eloquent methods that return more than one model result will return instance
All collections also serve as iterators, allowing you to loop over them as if they were simple PHP arrays:
- use App\Models\User;
+```php
+use App\Models\User;
- $users = User::where('active', 1)->get();
+$users = User::where('active', 1)->get();
- foreach ($users as $user) {
- echo $user->name;
- }
+foreach ($users as $user) {
+ echo $user->name;
+}
+```
However, as previously mentioned, collections are much more powerful than arrays and expose a variety of map / reduce operations that may be chained using an intuitive interface. For example, we may remove all inactive models and then gather the first name for each remaining user:
- $names = User::all()->reject(function ($user) {
- return $user->active === false;
- })->map(function ($user) {
- return $user->name;
- });
+```php
+$names = User::all()->reject(function (User $user) {
+ return $user->active === false;
+})->map(function (User $user) {
+ return $user->name;
+});
+```
#### Eloquent Collection Conversion
@@ -40,13 +44,15 @@ All Eloquent collections extend the base [Laravel collection](/docs/{{version}}/
In addition, the `Illuminate\Database\Eloquent\Collection` class provides a superset of methods to aid with managing your model collections. Most methods return `Illuminate\Database\Eloquent\Collection` instances; however, some methods, like `modelKeys`, return an `Illuminate\Support\Collection` instance.
-
-
-## Method Listing
-
-
-
## Arrays & Objects
@@ -325,3293 +237,3469 @@ Laravel includes a variety of global "helper" PHP functions. Many of these funct
The `Arr::accessible` method determines if the given value is array accessible:
- use Illuminate\Support\Arr;
- use Illuminate\Support\Collection;
+```php
+use Illuminate\Support\Arr;
+use Illuminate\Support\Collection;
- $isAccessible = Arr::accessible(['a' => 1, 'b' => 2]);
+$isAccessible = Arr::accessible(['a' => 1, 'b' => 2]);
- // true
+// true
- $isAccessible = Arr::accessible(new Collection);
+$isAccessible = Arr::accessible(new Collection);
- // true
+// true
- $isAccessible = Arr::accessible('abc');
+$isAccessible = Arr::accessible('abc');
- // false
+// false
- $isAccessible = Arr::accessible(new stdClass);
+$isAccessible = Arr::accessible(new stdClass);
- // false
+// false
+```
#### `Arr::add()` {.collection-method}
The `Arr::add` method adds a given key / value pair to an array if the given key doesn't already exist in the array or is set to `null`:
- use Illuminate\Support\Arr;
+```php
+use Illuminate\Support\Arr;
+
+$array = Arr::add(['name' => 'Desk'], 'price', 100);
+
+// ['name' => 'Desk', 'price' => 100]
+
+$array = Arr::add(['name' => 'Desk', 'price' => null], 'price', 100);
+
+// ['name' => 'Desk', 'price' => 100]
+```
+
+
+#### `Arr::array()` {.collection-method}
+
+The `Arr::array` method retrieves a value from a deeply nested array using "dot" notation (just as [Arr::get()](#method-array-get) does), but throws an `InvalidArgumentException` if the requested value is not an `array`:
+
+```
+use Illuminate\Support\Arr;
+
+$array = ['name' => 'Joe', 'languages' => ['PHP', 'Ruby']];
+
+$value = Arr::array($array, 'languages');
+
+// ['PHP', 'Ruby']
+
+$value = Arr::array($array, 'name');
+
+// throws InvalidArgumentException
+```
+
+
+#### `Arr::boolean()` {.collection-method}
+
+The `Arr::boolean` method retrieves a value from a deeply nested array using "dot" notation (just as [Arr::get()](#method-array-get) does), but throws an `InvalidArgumentException` if the requested value is not a `boolean`:
+
+```
+use Illuminate\Support\Arr;
+
+$array = ['name' => 'Joe', 'available' => true];
- $array = Arr::add(['name' => 'Desk'], 'price', 100);
+$value = Arr::boolean($array, 'available');
- // ['name' => 'Desk', 'price' => 100]
+// true
- $array = Arr::add(['name' => 'Desk', 'price' => null], 'price', 100);
+$value = Arr::boolean($array, 'name');
- // ['name' => 'Desk', 'price' => 100]
+// throws InvalidArgumentException
+```
#### `Arr::collapse()` {.collection-method}
-The `Arr::collapse` method collapses an array of arrays into a single array:
+The `Arr::collapse` method collapses an array of arrays or collections into a single array:
- use Illuminate\Support\Arr;
+```php
+use Illuminate\Support\Arr;
- $array = Arr::collapse([[1, 2, 3], [4, 5, 6], [7, 8, 9]]);
+$array = Arr::collapse([[1, 2, 3], [4, 5, 6], [7, 8, 9]]);
- // [1, 2, 3, 4, 5, 6, 7, 8, 9]
+// [1, 2, 3, 4, 5, 6, 7, 8, 9]
+```
#### `Arr::crossJoin()` {.collection-method}
The `Arr::crossJoin` method cross joins the given arrays, returning a Cartesian product with all possible permutations:
- use Illuminate\Support\Arr;
-
- $matrix = Arr::crossJoin([1, 2], ['a', 'b']);
-
- /*
- [
- [1, 'a'],
- [1, 'b'],
- [2, 'a'],
- [2, 'b'],
- ]
- */
-
- $matrix = Arr::crossJoin([1, 2], ['a', 'b'], ['I', 'II']);
-
- /*
- [
- [1, 'a', 'I'],
- [1, 'a', 'II'],
- [1, 'b', 'I'],
- [1, 'b', 'II'],
- [2, 'a', 'I'],
- [2, 'a', 'II'],
- [2, 'b', 'I'],
- [2, 'b', 'II'],
- ]
- */
+```php
+use Illuminate\Support\Arr;
+
+$matrix = Arr::crossJoin([1, 2], ['a', 'b']);
+
+/*
+ [
+ [1, 'a'],
+ [1, 'b'],
+ [2, 'a'],
+ [2, 'b'],
+ ]
+*/
+
+$matrix = Arr::crossJoin([1, 2], ['a', 'b'], ['I', 'II']);
+
+/*
+ [
+ [1, 'a', 'I'],
+ [1, 'a', 'II'],
+ [1, 'b', 'I'],
+ [1, 'b', 'II'],
+ [2, 'a', 'I'],
+ [2, 'a', 'II'],
+ [2, 'b', 'I'],
+ [2, 'b', 'II'],
+ ]
+*/
+```
#### `Arr::divide()` {.collection-method}
The `Arr::divide` method returns two arrays: one containing the keys and the other containing the values of the given array:
- use Illuminate\Support\Arr;
+```php
+use Illuminate\Support\Arr;
- [$keys, $values] = Arr::divide(['name' => 'Desk']);
+[$keys, $values] = Arr::divide(['name' => 'Desk']);
- // $keys: ['name']
+// $keys: ['name']
- // $values: ['Desk']
+// $values: ['Desk']
+```
#### `Arr::dot()` {.collection-method}
The `Arr::dot` method flattens a multi-dimensional array into a single level array that uses "dot" notation to indicate depth:
- use Illuminate\Support\Arr;
+```php
+use Illuminate\Support\Arr;
+
+$array = ['products' => ['desk' => ['price' => 100]]];
+
+$flattened = Arr::dot($array);
+
+// ['products.desk.price' => 100]
+```
+
+
+#### `Arr::every()` {.collection-method}
+
+The `Arr::every` method ensures that all values in the array pass a given truth test:
+
+```php
+use Illuminate\Support\Arr;
+
+$array = [1, 2, 3];
+
+Arr::every($array, fn ($i) => $i > 0);
- $array = ['products' => ['desk' => ['price' => 100]]];
+// true
- $flattened = Arr::dot($array);
+Arr::every($array, fn ($i) => $i > 2);
- // ['products.desk.price' => 100]
+// false
+```
#### `Arr::except()` {.collection-method}
The `Arr::except` method removes the given key / value pairs from an array:
- use Illuminate\Support\Arr;
+```php
+use Illuminate\Support\Arr;
- $array = ['name' => 'Desk', 'price' => 100];
+$array = ['name' => 'Desk', 'price' => 100];
- $filtered = Arr::except($array, ['price']);
+$filtered = Arr::except($array, ['price']);
- // ['name' => 'Desk']
+// ['name' => 'Desk']
+```
#### `Arr::exists()` {.collection-method}
The `Arr::exists` method checks that the given key exists in the provided array:
- use Illuminate\Support\Arr;
+```php
+use Illuminate\Support\Arr;
- $array = ['name' => 'John Doe', 'age' => 17];
+$array = ['name' => 'John Doe', 'age' => 17];
- $exists = Arr::exists($array, 'name');
+$exists = Arr::exists($array, 'name');
- // true
+// true
- $exists = Arr::exists($array, 'salary');
+$exists = Arr::exists($array, 'salary');
- // false
+// false
+```
#### `Arr::first()` {.collection-method}
The `Arr::first` method returns the first element of an array passing a given truth test:
- use Illuminate\Support\Arr;
+```php
+use Illuminate\Support\Arr;
- $array = [100, 200, 300];
+$array = [100, 200, 300];
- $first = Arr::first($array, function ($value, $key) {
- return $value >= 150;
- });
+$first = Arr::first($array, function (int $value, int $key) {
+ return $value >= 150;
+});
- // 200
+// 200
+```
A default value may also be passed as the third parameter to the method. This value will be returned if no value passes the truth test:
- use Illuminate\Support\Arr;
+```php
+use Illuminate\Support\Arr;
- $first = Arr::first($array, $callback, $default);
+$first = Arr::first($array, $callback, $default);
+```
#### `Arr::flatten()` {.collection-method}
The `Arr::flatten` method flattens a multi-dimensional array into a single level array:
- use Illuminate\Support\Arr;
+```php
+use Illuminate\Support\Arr;
+
+$array = ['name' => 'Joe', 'languages' => ['PHP', 'Ruby']];
+
+$flattened = Arr::flatten($array);
+
+// ['Joe', 'PHP', 'Ruby']
+```
+
+
+#### `Arr::float()` {.collection-method}
+
+The `Arr::float` method retrieves a value from a deeply nested array using "dot" notation (just as [Arr::get()](#method-array-get) does), but throws an `InvalidArgumentException` if the requested value is not a `float`:
+
+```
+use Illuminate\Support\Arr;
+
+$array = ['name' => 'Joe', 'balance' => 123.45];
- $array = ['name' => 'Joe', 'languages' => ['PHP', 'Ruby']];
+$value = Arr::float($array, 'balance');
- $flattened = Arr::flatten($array);
+// 123.45
- // ['Joe', 'PHP', 'Ruby']
+$value = Arr::float($array, 'name');
+
+// throws InvalidArgumentException
+```
#### `Arr::forget()` {.collection-method}
-The `Arr::forget` method removes a given key / value pair from a deeply nested array using "dot" notation:
+The `Arr::forget` method removes a given key / value pairs from a deeply nested array using "dot" notation:
+
+```php
+use Illuminate\Support\Arr;
+
+$array = ['products' => ['desk' => ['price' => 100]]];
+
+Arr::forget($array, 'products.desk');
+
+// ['products' => []]
+```
+
+
+#### `Arr::from()` {.collection-method}
+
+The `Arr::from` method converts various input types into a plain PHP array. It supports a range of input types, including arrays, objects, and several common Laravel interfaces, such as `Arrayable`, `Enumerable`, `Jsonable`, and `JsonSerializable`. Additionally, it handles `Traversable` and `WeakMap` instances:
- use Illuminate\Support\Arr;
+```php
+use Illuminate\Support\Arr;
- $array = ['products' => ['desk' => ['price' => 100]]];
+Arr::from((object) ['foo' => 'bar']); // ['foo' => 'bar']
- Arr::forget($array, 'products.desk');
+class TestJsonableObject implements Jsonable
+{
+ public function toJson($options = 0)
+ {
+ return json_encode(['foo' => 'bar']);
+ }
+}
- // ['products' => []]
+Arr::from(new TestJsonableObject); // ['foo' => 'bar']
+```
#### `Arr::get()` {.collection-method}
The `Arr::get` method retrieves a value from a deeply nested array using "dot" notation:
- use Illuminate\Support\Arr;
+```php
+use Illuminate\Support\Arr;
- $array = ['products' => ['desk' => ['price' => 100]]];
+$array = ['products' => ['desk' => ['price' => 100]]];
- $price = Arr::get($array, 'products.desk.price');
+$price = Arr::get($array, 'products.desk.price');
- // 100
+// 100
+```
The `Arr::get` method also accepts a default value, which will be returned if the specified key is not present in the array:
- use Illuminate\Support\Arr;
+```php
+use Illuminate\Support\Arr;
- $discount = Arr::get($array, 'products.desk.discount', 0);
+$discount = Arr::get($array, 'products.desk.discount', 0);
- // 0
+// 0
+```
#### `Arr::has()` {.collection-method}
The `Arr::has` method checks whether a given item or items exists in an array using "dot" notation:
- use Illuminate\Support\Arr;
+```php
+use Illuminate\Support\Arr;
+
+$array = ['product' => ['name' => 'Desk', 'price' => 100]];
+
+$contains = Arr::has($array, 'product.name');
+
+// true
+
+$contains = Arr::has($array, ['product.price', 'product.discount']);
- $array = ['product' => ['name' => 'Desk', 'price' => 100]];
+// false
+```
+
+
+#### `Arr::hasAll()` {.collection-method}
- $contains = Arr::has($array, 'product.name');
+The `Arr::hasAll` method determines if all of the specified keys exist in the given array using "dot" notation:
- // true
+```php
+use Illuminate\Support\Arr;
- $contains = Arr::has($array, ['product.price', 'product.discount']);
+$array = ['name' => 'Taylor', 'language' => 'PHP'];
- // false
+Arr::hasAll($array, ['name']); // true
+Arr::hasAll($array, ['name', 'language']); // true
+Arr::hasAll($array, ['name', 'IDE']); // false
+```
#### `Arr::hasAny()` {.collection-method}
The `Arr::hasAny` method checks whether any item in a given set exists in an array using "dot" notation:
- use Illuminate\Support\Arr;
+```php
+use Illuminate\Support\Arr;
+
+$array = ['product' => ['name' => 'Desk', 'price' => 100]];
+
+$contains = Arr::hasAny($array, 'product.name');
+
+// true
+
+$contains = Arr::hasAny($array, ['product.name', 'product.discount']);
+
+// true
+
+$contains = Arr::hasAny($array, ['category', 'product.discount']);
+
+// false
+```
+
+
+#### `Arr::integer()` {.collection-method}
- $array = ['product' => ['name' => 'Desk', 'price' => 100]];
+The `Arr::integer` method retrieves a value from a deeply nested array using "dot" notation (just as [Arr::get()](#method-array-get) does), but throws an `InvalidArgumentException` if the requested value is not an `int`:
- $contains = Arr::hasAny($array, 'product.name');
+```
+use Illuminate\Support\Arr;
- // true
+$array = ['name' => 'Joe', 'age' => 42];
- $contains = Arr::hasAny($array, ['product.name', 'product.discount']);
+$value = Arr::integer($array, 'age');
- // true
+// 42
- $contains = Arr::hasAny($array, ['category', 'product.discount']);
+$value = Arr::integer($array, 'name');
- // false
+// throws InvalidArgumentException
+```
#### `Arr::isAssoc()` {.collection-method}
The `Arr::isAssoc` method returns `true` if the given array is an associative array. An array is considered "associative" if it doesn't have sequential numerical keys beginning with zero:
- use Illuminate\Support\Arr;
+```php
+use Illuminate\Support\Arr;
- $isAssoc = Arr::isAssoc(['product' => ['name' => 'Desk', 'price' => 100]]);
+$isAssoc = Arr::isAssoc(['product' => ['name' => 'Desk', 'price' => 100]]);
- // true
+// true
- $isAssoc = Arr::isAssoc([1, 2, 3]);
+$isAssoc = Arr::isAssoc([1, 2, 3]);
- // false
+// false
+```
#### `Arr::isList()` {.collection-method}
The `Arr::isList` method returns `true` if the given array's keys are sequential integers beginning from zero:
- use Illuminate\Support\Arr;
+```php
+use Illuminate\Support\Arr;
+
+$isList = Arr::isList(['foo', 'bar', 'baz']);
- $isAssoc = Arr::isList(['foo', 'bar', 'baz']);
+// true
- // true
+$isList = Arr::isList(['product' => ['name' => 'Desk', 'price' => 100]]);
- $isAssoc = Arr::isList(['product' => ['name' => 'Desk', 'price' => 100]]);
+// false
+```
+
+
+#### `Arr::join()` {.collection-method}
+
+The `Arr::join` method joins array elements with a string. Using this method's third argument, you may also specify the joining string for the final element of the array:
+
+```php
+use Illuminate\Support\Arr;
+
+$array = ['Tailwind', 'Alpine', 'Laravel', 'Livewire'];
+
+$joined = Arr::join($array, ', ');
+
+// Tailwind, Alpine, Laravel, Livewire
+
+$joined = Arr::join($array, ', ', ', and ');
+
+// Tailwind, Alpine, Laravel, and Livewire
+```
+
+
+#### `Arr::keyBy()` {.collection-method}
+
+The `Arr::keyBy` method keys the array by the given key. If multiple items have the same key, only the last one will appear in the new array:
+
+```php
+use Illuminate\Support\Arr;
+
+$array = [
+ ['product_id' => 'prod-100', 'name' => 'Desk'],
+ ['product_id' => 'prod-200', 'name' => 'Chair'],
+];
- // false
+$keyed = Arr::keyBy($array, 'product_id');
+
+/*
+ [
+ 'prod-100' => ['product_id' => 'prod-100', 'name' => 'Desk'],
+ 'prod-200' => ['product_id' => 'prod-200', 'name' => 'Chair'],
+ ]
+*/
+```
#### `Arr::last()` {.collection-method}
The `Arr::last` method returns the last element of an array passing a given truth test:
- use Illuminate\Support\Arr;
+```php
+use Illuminate\Support\Arr;
- $array = [100, 200, 300, 110];
+$array = [100, 200, 300, 110];
- $last = Arr::last($array, function ($value, $key) {
- return $value >= 150;
- });
+$last = Arr::last($array, function (int $value, int $key) {
+ return $value >= 150;
+});
- // 300
+// 300
+```
A default value may be passed as the third argument to the method. This value will be returned if no value passes the truth test:
- use Illuminate\Support\Arr;
+```php
+use Illuminate\Support\Arr;
+
+$last = Arr::last($array, $callback, $default);
+```
+
+
+#### `Arr::map()` {.collection-method}
+
+The `Arr::map` method iterates through the array and passes each value and key to the given callback. The array value is replaced by the value returned by the callback:
+
+```php
+use Illuminate\Support\Arr;
+
+$array = ['first' => 'james', 'last' => 'kirk'];
+
+$mapped = Arr::map($array, function (string $value, string $key) {
+ return ucfirst($value);
+});
+
+// ['first' => 'James', 'last' => 'Kirk']
+```
+
+
+#### `Arr::mapSpread()` {.collection-method}
+
+The `Arr::mapSpread` method iterates over the array, passing each nested item value into the given closure. The closure is free to modify the item and return it, thus forming a new array of modified items:
+
+```php
+use Illuminate\Support\Arr;
+
+$array = [
+ [0, 1],
+ [2, 3],
+ [4, 5],
+ [6, 7],
+ [8, 9],
+];
+
+$mapped = Arr::mapSpread($array, function (int $even, int $odd) {
+ return $even + $odd;
+});
+
+/*
+ [1, 5, 9, 13, 17]
+*/
+```
+
+
+#### `Arr::mapWithKeys()` {.collection-method}
- $last = Arr::last($array, $callback, $default);
+The `Arr::mapWithKeys` method iterates through the array and passes each value to the given callback. The callback should return an associative array containing a single key / value pair:
+
+```php
+use Illuminate\Support\Arr;
+
+$array = [
+ [
+ 'name' => 'John',
+ 'department' => 'Sales',
+ 'email' => 'john@example.com',
+ ],
+ [
+ 'name' => 'Jane',
+ 'department' => 'Marketing',
+ 'email' => 'jane@example.com',
+ ]
+];
+
+$mapped = Arr::mapWithKeys($array, function (array $item, int $key) {
+ return [$item['email'] => $item['name']];
+});
+
+/*
+ [
+ 'john@example.com' => 'John',
+ 'jane@example.com' => 'Jane',
+ ]
+*/
+```
#### `Arr::only()` {.collection-method}
The `Arr::only` method returns only the specified key / value pairs from the given array:
- use Illuminate\Support\Arr;
+```php
+use Illuminate\Support\Arr;
+
+$array = ['name' => 'Desk', 'price' => 100, 'orders' => 10];
+
+$slice = Arr::only($array, ['name', 'price']);
+
+// ['name' => 'Desk', 'price' => 100]
+```
+
+
+#### `Arr::partition()` {.collection-method}
+
+The `Arr::partition` method may be combined with PHP array destructuring to separate elements that pass a given truth test from those that do not:
- $array = ['name' => 'Desk', 'price' => 100, 'orders' => 10];
+```php
+ 'Desk', 'price' => 100]
+// [1, 2]
+
+dump($equalOrAboveThree);
+
+// [3, 4, 5, 6]
+```
#### `Arr::pluck()` {.collection-method}
The `Arr::pluck` method retrieves all of the values for a given key from an array:
- use Illuminate\Support\Arr;
+```php
+use Illuminate\Support\Arr;
- $array = [
- ['developer' => ['id' => 1, 'name' => 'Taylor']],
- ['developer' => ['id' => 2, 'name' => 'Abigail']],
- ];
+$array = [
+ ['developer' => ['id' => 1, 'name' => 'Taylor']],
+ ['developer' => ['id' => 2, 'name' => 'Abigail']],
+];
- $names = Arr::pluck($array, 'developer.name');
+$names = Arr::pluck($array, 'developer.name');
- // ['Taylor', 'Abigail']
+// ['Taylor', 'Abigail']
+```
You may also specify how you wish the resulting list to be keyed:
- use Illuminate\Support\Arr;
+```php
+use Illuminate\Support\Arr;
- $names = Arr::pluck($array, 'developer.name', 'developer.id');
+$names = Arr::pluck($array, 'developer.name', 'developer.id');
- // [1 => 'Taylor', 2 => 'Abigail']
+// [1 => 'Taylor', 2 => 'Abigail']
+```
#### `Arr::prepend()` {.collection-method}
The `Arr::prepend` method will push an item onto the beginning of an array:
- use Illuminate\Support\Arr;
+```php
+use Illuminate\Support\Arr;
- $array = ['one', 'two', 'three', 'four'];
+$array = ['one', 'two', 'three', 'four'];
- $array = Arr::prepend($array, 'zero');
+$array = Arr::prepend($array, 'zero');
- // ['zero', 'one', 'two', 'three', 'four']
+// ['zero', 'one', 'two', 'three', 'four']
+```
If needed, you may specify the key that should be used for the value:
- use Illuminate\Support\Arr;
+```php
+use Illuminate\Support\Arr;
+
+$array = ['price' => 100];
+
+$array = Arr::prepend($array, 'Desk', 'name');
- $array = ['price' => 100];
+// ['name' => 'Desk', 'price' => 100]
+```
+
+
+#### `Arr::prependKeysWith()` {.collection-method}
+
+The `Arr::prependKeysWith` prepends all key names of an associative array with the given prefix:
+
+```php
+use Illuminate\Support\Arr;
+
+$array = [
+ 'name' => 'Desk',
+ 'price' => 100,
+];
- $array = Arr::prepend($array, 'Desk', 'name');
+$keyed = Arr::prependKeysWith($array, 'product.');
- // ['name' => 'Desk', 'price' => 100]
+/*
+ [
+ 'product.name' => 'Desk',
+ 'product.price' => 100,
+ ]
+*/
+```
#### `Arr::pull()` {.collection-method}
The `Arr::pull` method returns and removes a key / value pair from an array:
- use Illuminate\Support\Arr;
+```php
+use Illuminate\Support\Arr;
- $array = ['name' => 'Desk', 'price' => 100];
+$array = ['name' => 'Desk', 'price' => 100];
- $name = Arr::pull($array, 'name');
+$name = Arr::pull($array, 'name');
- // $name: Desk
+// $name: Desk
- // $array: ['price' => 100]
+// $array: ['price' => 100]
+```
A default value may be passed as the third argument to the method. This value will be returned if the key doesn't exist:
- use Illuminate\Support\Arr;
+```php
+use Illuminate\Support\Arr;
+
+$value = Arr::pull($array, $key, $default);
+```
+
+
+#### `Arr::push()` {.collection-method}
+
+The `Arr::push` method pushes an item into an array using "dot" notation. If an array does not exist at the given key, it will be created:
+
+```php
+use Illuminate\Support\Arr;
+
+$array = [];
+
+Arr::push($array, 'office.furniture', 'Desk');
- $value = Arr::pull($array, $key, $default);
+// $array: ['office' => ['furniture' => ['Desk']]]
+```
#### `Arr::query()` {.collection-method}
The `Arr::query` method converts the array into a query string:
- use Illuminate\Support\Arr;
+```php
+use Illuminate\Support\Arr;
- $array = [
- 'name' => 'Taylor',
- 'order' => [
- 'column' => 'created_at',
- 'direction' => 'desc'
- ]
- ];
+$array = [
+ 'name' => 'Taylor',
+ 'order' => [
+ 'column' => 'created_at',
+ 'direction' => 'desc'
+ ]
+];
- Arr::query($array);
+Arr::query($array);
- // name=Taylor&order[column]=created_at&order[direction]=desc
+// name=Taylor&order[column]=created_at&order[direction]=desc
+```
#### `Arr::random()` {.collection-method}
The `Arr::random` method returns a random value from an array:
- use Illuminate\Support\Arr;
+```php
+use Illuminate\Support\Arr;
- $array = [1, 2, 3, 4, 5];
+$array = [1, 2, 3, 4, 5];
- $random = Arr::random($array);
+$random = Arr::random($array);
- // 4 - (retrieved randomly)
+// 4 - (retrieved randomly)
+```
You may also specify the number of items to return as an optional second argument. Note that providing this argument will return an array even if only one item is desired:
- use Illuminate\Support\Arr;
+```php
+use Illuminate\Support\Arr;
- $items = Arr::random($array, 2);
+$items = Arr::random($array, 2);
- // [2, 5] - (retrieved randomly)
+// [2, 5] - (retrieved randomly)
+```
-
-#### `Arr::set()` {.collection-method}
+
+#### `Arr::reject()` {.collection-method}
-The `Arr::set` method sets a value within a deeply nested array using "dot" notation:
+The `Arr::reject` method removes items from an array using the given closure:
- use Illuminate\Support\Arr;
+```php
+use Illuminate\Support\Arr;
- $array = ['products' => ['desk' => ['price' => 100]]];
+$array = [100, '200', 300, '400', 500];
- Arr::set($array, 'products.desk.price', 200);
+$filtered = Arr::reject($array, function (string|int $value, int $key) {
+ return is_string($value);
+});
- // ['products' => ['desk' => ['price' => 200]]]
+// [0 => 100, 2 => 300, 4 => 500]
+```
-
-#### `Arr::shuffle()` {.collection-method}
+
+#### `Arr::select()` {.collection-method}
-The `Arr::shuffle` method randomly shuffles the items in the array:
+The `Arr::select` method selects an array of values from an array:
- use Illuminate\Support\Arr;
+```php
+use Illuminate\Support\Arr;
- $array = Arr::shuffle([1, 2, 3, 4, 5]);
+$array = [
+ ['id' => 1, 'name' => 'Desk', 'price' => 200],
+ ['id' => 2, 'name' => 'Table', 'price' => 150],
+ ['id' => 3, 'name' => 'Chair', 'price' => 300],
+];
- // [3, 2, 5, 1, 4] - (generated randomly)
+Arr::select($array, ['name', 'price']);
-
-#### `Arr::sort()` {.collection-method}
+// [['name' => 'Desk', 'price' => 200], ['name' => 'Table', 'price' => 150], ['name' => 'Chair', 'price' => 300]]
+```
-The `Arr::sort` method sorts an array by its values:
+
+#### `Arr::set()` {.collection-method}
- use Illuminate\Support\Arr;
+The `Arr::set` method sets a value within a deeply nested array using "dot" notation:
- $array = ['Desk', 'Table', 'Chair'];
+```php
+use Illuminate\Support\Arr;
- $sorted = Arr::sort($array);
+$array = ['products' => ['desk' => ['price' => 100]]];
- // ['Chair', 'Desk', 'Table']
+Arr::set($array, 'products.desk.price', 200);
-You may also sort the array by the results of a given closure:
+// ['products' => ['desk' => ['price' => 200]]]
+```
- use Illuminate\Support\Arr;
+
+#### `Arr::shuffle()` {.collection-method}
- $array = [
- ['name' => 'Desk'],
- ['name' => 'Table'],
- ['name' => 'Chair'],
- ];
+The `Arr::shuffle` method randomly shuffles the items in the array:
- $sorted = array_values(Arr::sort($array, function ($value) {
- return $value['name'];
- }));
+```php
+use Illuminate\Support\Arr;
- /*
- [
- ['name' => 'Chair'],
- ['name' => 'Desk'],
- ['name' => 'Table'],
- ]
- */
+$array = Arr::shuffle([1, 2, 3, 4, 5]);
-
-#### `Arr::sortRecursive()` {.collection-method}
+// [3, 2, 5, 1, 4] - (generated randomly)
+```
-The `Arr::sortRecursive` method recursively sorts an array using the `sort` function for numerically indexed sub-arrays and the `ksort` function for associative sub-arrays:
+
+#### `Arr::sole()` {.collection-method}
- use Illuminate\Support\Arr;
+The `Arr::sole` method retrieves a single value from an array using the given closure. If more than one value within the array matches the given truth test, an `Illuminate\Support\MultipleItemsFoundException` exception will be thrown. If no values match the truth test, an `Illuminate\Support\ItemNotFoundException` exception will be thrown:
- $array = [
- ['Roman', 'Taylor', 'Li'],
- ['PHP', 'Ruby', 'JavaScript'],
- ['one' => 1, 'two' => 2, 'three' => 3],
- ];
+```php
+use Illuminate\Support\Arr;
- $sorted = Arr::sortRecursive($array);
+$array = ['Desk', 'Table', 'Chair'];
- /*
- [
- ['JavaScript', 'PHP', 'Ruby'],
- ['one' => 1, 'three' => 3, 'two' => 2],
- ['Li', 'Roman', 'Taylor'],
- ]
- */
+$value = Arr::sole($array, fn (string $value) => $value === 'Desk');
-
-#### `Arr::toCssClasses()` {.collection-method}
+// 'Desk'
+```
-The `Arr::toCssClasses` conditionally compiles a CSS class string. The method accepts an array of classes where the array key contains the class or classes you wish to add, while the value is a boolean expression. If the array element has a numeric key, it will always be included in the rendered class list:
+
+#### `Arr::some()` {.collection-method}
- use Illuminate\Support\Arr;
+The `Arr::some` method ensures that at least one of the values in the array passes a given truth test:
- $isActive = false;
- $hasError = true;
+```php
+use Illuminate\Support\Arr;
- $array = ['p-4', 'font-bold' => $isActive, 'bg-red' => $hasError];
+$array = [1, 2, 3];
- $classes = Arr::toCssClasses($array);
+Arr::some($array, fn ($i) => $i > 2);
- /*
- 'p-4 bg-red'
- */
+// true
+```
-This method powers Laravel's functionality allowing [merging classes with a Blade component's attribute bag](/docs/{{version}}/blade#conditionally-merge-classes) as well as the `@class` [Blade directive](/docs/{{version}}/blade#conditional-classes).
+
+#### `Arr::sort()` {.collection-method}
-
-#### `Arr::undot()` {.collection-method}
-
-The `Arr::undot` method expands a single-dimensional array that uses "dot" notation into a multi-dimensional array:
+The `Arr::sort` method sorts an array by its values:
- use Illuminate\Support\Arr;
+```php
+use Illuminate\Support\Arr;
- $array = [
- 'user.name' => 'Kevin Malone',
- 'user.occupation' => 'Accountant',
- ];
+$array = ['Desk', 'Table', 'Chair'];
- $array = Arr::undot($array);
+$sorted = Arr::sort($array);
- // ['user' => ['name' => 'Kevin Malone', 'occupation' => 'Accountant']]
+// ['Chair', 'Desk', 'Table']
+```
-
-#### `Arr::where()` {.collection-method}
+You may also sort the array by the results of a given closure:
-The `Arr::where` method filters an array using the given closure:
+```php
+use Illuminate\Support\Arr;
- use Illuminate\Support\Arr;
+$array = [
+ ['name' => 'Desk'],
+ ['name' => 'Table'],
+ ['name' => 'Chair'],
+];
- $array = [100, '200', 300, '400', 500];
+$sorted = array_values(Arr::sort($array, function (array $value) {
+ return $value['name'];
+}));
- $filtered = Arr::where($array, function ($value, $key) {
- return is_string($value);
- });
+/*
+ [
+ ['name' => 'Chair'],
+ ['name' => 'Desk'],
+ ['name' => 'Table'],
+ ]
+*/
+```
- // [1 => '200', 3 => '400']
+
+#### `Arr::sortDesc()` {.collection-method}
-
-#### `Arr::whereNotNull()` {.collection-method}
+The `Arr::sortDesc` method sorts an array in descending order by its values:
-The `Arr::whereNotNull` method removes all `null` values from the given array:
+```php
+use Illuminate\Support\Arr;
- use Illuminate\Support\Arr;
+$array = ['Desk', 'Table', 'Chair'];
- $array = [0, null];
+$sorted = Arr::sortDesc($array);
- $filtered = Arr::whereNotNull($array);
+// ['Table', 'Desk', 'Chair']
+```
- // [0 => 0]
+You may also sort the array by the results of a given closure:
-
-#### `Arr::wrap()` {.collection-method}
+```php
+use Illuminate\Support\Arr;
-The `Arr::wrap` method wraps the given value in an array. If the given value is already an array it will be returned without modification:
+$array = [
+ ['name' => 'Desk'],
+ ['name' => 'Table'],
+ ['name' => 'Chair'],
+];
- use Illuminate\Support\Arr;
+$sorted = array_values(Arr::sortDesc($array, function (array $value) {
+ return $value['name'];
+}));
- $string = 'Laravel';
+/*
+ [
+ ['name' => 'Table'],
+ ['name' => 'Desk'],
+ ['name' => 'Chair'],
+ ]
+*/
+```
- $array = Arr::wrap($string);
+
+#### `Arr::sortRecursive()` {.collection-method}
- // ['Laravel']
+The `Arr::sortRecursive` method recursively sorts an array using the `sort` function for numerically indexed sub-arrays and the `ksort` function for associative sub-arrays:
-If the given value is `null`, an empty array will be returned:
+```php
+use Illuminate\Support\Arr;
+
+$array = [
+ ['Roman', 'Taylor', 'Li'],
+ ['PHP', 'Ruby', 'JavaScript'],
+ ['one' => 1, 'two' => 2, 'three' => 3],
+];
+
+$sorted = Arr::sortRecursive($array);
+
+/*
+ [
+ ['JavaScript', 'PHP', 'Ruby'],
+ ['one' => 1, 'three' => 3, 'two' => 2],
+ ['Li', 'Roman', 'Taylor'],
+ ]
+*/
+```
- use Illuminate\Support\Arr;
+If you would like the results sorted in descending order, you may use the `Arr::sortRecursiveDesc` method.
- $array = Arr::wrap(null);
+```php
+$sorted = Arr::sortRecursiveDesc($array);
+```
- // []
+
+#### `Arr::string()` {.collection-method}
-
-#### `data_fill()` {.collection-method}
+The `Arr::string` method retrieves a value from a deeply nested array using "dot" notation (just as [Arr::get()](#method-array-get) does), but throws an `InvalidArgumentException` if the requested value is not a `string`:
-The `data_fill` function sets a missing value within a nested array or object using "dot" notation:
+```
+use Illuminate\Support\Arr;
- $data = ['products' => ['desk' => ['price' => 100]]];
+$array = ['name' => 'Joe', 'languages' => ['PHP', 'Ruby']];
- data_fill($data, 'products.desk.price', 200);
+$value = Arr::string($array, 'name');
- // ['products' => ['desk' => ['price' => 100]]]
+// Joe
- data_fill($data, 'products.desk.discount', 10);
+$value = Arr::string($array, 'languages');
- // ['products' => ['desk' => ['price' => 100, 'discount' => 10]]]
+// throws InvalidArgumentException
+```
-This function also accepts asterisks as wildcards and will fill the target accordingly:
+
+#### `Arr::take()` {.collection-method}
- $data = [
- 'products' => [
- ['name' => 'Desk 1', 'price' => 100],
- ['name' => 'Desk 2'],
- ],
- ];
+The `Arr::take` method returns a new array with the specified number of items:
- data_fill($data, 'products.*.price', 200);
+```php
+use Illuminate\Support\Arr;
- /*
- [
- 'products' => [
- ['name' => 'Desk 1', 'price' => 100],
- ['name' => 'Desk 2', 'price' => 200],
- ],
- ]
- */
+$array = [0, 1, 2, 3, 4, 5];
-
-#### `data_get()` {.collection-method}
+$chunk = Arr::take($array, 3);
-The `data_get` function retrieves a value from a nested array or object using "dot" notation:
+// [0, 1, 2]
+```
- $data = ['products' => ['desk' => ['price' => 100]]];
+You may also pass a negative integer to take the specified number of items from the end of the array:
- $price = data_get($data, 'products.desk.price');
+```php
+$array = [0, 1, 2, 3, 4, 5];
- // 100
+$chunk = Arr::take($array, -2);
-The `data_get` function also accepts a default value, which will be returned if the specified key is not found:
+// [4, 5]
+```
- $discount = data_get($data, 'products.desk.discount', 0);
+
+#### `Arr::toCssClasses()` {.collection-method}
- // 0
+The `Arr::toCssClasses` method conditionally compiles a CSS class string. The method accepts an array of classes where the array key contains the class or classes you wish to add, while the value is a boolean expression. If the array element has a numeric key, it will always be included in the rendered class list:
-The function also accepts wildcards using asterisks, which may target any key of the array or object:
+```php
+use Illuminate\Support\Arr;
- $data = [
- 'product-one' => ['name' => 'Desk 1', 'price' => 100],
- 'product-two' => ['name' => 'Desk 2', 'price' => 150],
- ];
+$isActive = false;
+$hasError = true;
- data_get($data, '*.name');
+$array = ['p-4', 'font-bold' => $isActive, 'bg-red' => $hasError];
- // ['Desk 1', 'Desk 2'];
+$classes = Arr::toCssClasses($array);
-
-#### `data_set()` {.collection-method}
+/*
+ 'p-4 bg-red'
+*/
+```
-The `data_set` function sets a value within a nested array or object using "dot" notation:
+
+#### `Arr::toCssStyles()` {.collection-method}
- $data = ['products' => ['desk' => ['price' => 100]]];
+The `Arr::toCssStyles` conditionally compiles a CSS style string. The method accepts an array of classes where the array key contains the class or classes you wish to add, while the value is a boolean expression. If the array element has a numeric key, it will always be included in the rendered class list:
- data_set($data, 'products.desk.price', 200);
+```php
+use Illuminate\Support\Arr;
- // ['products' => ['desk' => ['price' => 200]]]
+$hasColor = true;
-This function also accepts wildcards using asterisks and will set values on the target accordingly:
+$array = ['background-color: blue', 'color: blue' => $hasColor];
- $data = [
- 'products' => [
- ['name' => 'Desk 1', 'price' => 100],
- ['name' => 'Desk 2', 'price' => 150],
- ],
- ];
+$classes = Arr::toCssStyles($array);
- data_set($data, 'products.*.price', 200);
+/*
+ 'background-color: blue; color: blue;'
+*/
+```
- /*
- [
- 'products' => [
- ['name' => 'Desk 1', 'price' => 200],
- ['name' => 'Desk 2', 'price' => 200],
- ],
- ]
- */
+This method powers Laravel's functionality allowing [merging classes with a Blade component's attribute bag](/docs/{{version}}/blade#conditionally-merge-classes) as well as the `@class` [Blade directive](/docs/{{version}}/blade#conditional-classes).
-By default, any existing values are overwritten. If you wish to only set a value if it doesn't exist, you may pass `false` as the fourth argument to the function:
+
+#### `Arr::undot()` {.collection-method}
- $data = ['products' => ['desk' => ['price' => 100]]];
+The `Arr::undot` method expands a single-dimensional array that uses "dot" notation into a multi-dimensional array:
- data_set($data, 'products.desk.price', 200, $overwrite = false);
+```php
+use Illuminate\Support\Arr;
- // ['products' => ['desk' => ['price' => 100]]]
+$array = [
+ 'user.name' => 'Kevin Malone',
+ 'user.occupation' => 'Accountant',
+];
-
-#### `head()` {.collection-method}
+$array = Arr::undot($array);
-The `head` function returns the first element in the given array:
+// ['user' => ['name' => 'Kevin Malone', 'occupation' => 'Accountant']]
+```
- $array = [100, 200, 300];
+
+#### `Arr::where()` {.collection-method}
- $first = head($array);
+The `Arr::where` method filters an array using the given closure:
- // 100
+```php
+use Illuminate\Support\Arr;
-
-#### `last()` {.collection-method}
+$array = [100, '200', 300, '400', 500];
-The `last` function returns the last element in the given array:
+$filtered = Arr::where($array, function (string|int $value, int $key) {
+ return is_string($value);
+});
- $array = [100, 200, 300];
+// [1 => '200', 3 => '400']
+```
- $last = last($array);
+
+#### `Arr::whereNotNull()` {.collection-method}
- // 300
+The `Arr::whereNotNull` method removes all `null` values from the given array:
-
-## Paths
+```php
+use Illuminate\Support\Arr;
-
-#### `app_path()` {.collection-method}
+$array = [0, null];
-The `app_path` function returns the fully qualified path to your application's `app` directory. You may also use the `app_path` function to generate a fully qualified path to a file relative to the application directory:
+$filtered = Arr::whereNotNull($array);
- $path = app_path();
+// [0 => 0]
+```
- $path = app_path('Http/Controllers/Controller.php');
+
+#### `Arr::wrap()` {.collection-method}
-
-#### `base_path()` {.collection-method}
+The `Arr::wrap` method wraps the given value in an array. If the given value is already an array it will be returned without modification:
-The `base_path` function returns the fully qualified path to your application's root directory. You may also use the `base_path` function to generate a fully qualified path to a given file relative to the project root directory:
+```php
+use Illuminate\Support\Arr;
- $path = base_path();
+$string = 'Laravel';
- $path = base_path('vendor/bin');
+$array = Arr::wrap($string);
-
-#### `config_path()` {.collection-method}
+// ['Laravel']
+```
-The `config_path` function returns the fully qualified path to your application's `config` directory. You may also use the `config_path` function to generate a fully qualified path to a given file within the application's configuration directory:
+If the given value is `null`, an empty array will be returned:
- $path = config_path();
+```php
+use Illuminate\Support\Arr;
- $path = config_path('app.php');
+$array = Arr::wrap(null);
-
-#### `database_path()` {.collection-method}
+// []
+```
-The `database_path` function returns the fully qualified path to your application's `database` directory. You may also use the `database_path` function to generate a fully qualified path to a given file within the database directory:
+
+#### `data_fill()` {.collection-method}
- $path = database_path();
+The `data_fill` function sets a missing value within a nested array or object using "dot" notation:
- $path = database_path('factories/UserFactory.php');
+```php
+$data = ['products' => ['desk' => ['price' => 100]]];
-
-#### `mix()` {.collection-method}
+data_fill($data, 'products.desk.price', 200);
-The `mix` function returns the path to a [versioned Mix file](/docs/{{version}}/mix):
+// ['products' => ['desk' => ['price' => 100]]]
- $path = mix('css/app.css');
+data_fill($data, 'products.desk.discount', 10);
-
-#### `public_path()` {.collection-method}
+// ['products' => ['desk' => ['price' => 100, 'discount' => 10]]]
+```
-The `public_path` function returns the fully qualified path to your application's `public` directory. You may also use the `public_path` function to generate a fully qualified path to a given file within the public directory:
+This function also accepts asterisks as wildcards and will fill the target accordingly:
- $path = public_path();
+```php
+$data = [
+ 'products' => [
+ ['name' => 'Desk 1', 'price' => 100],
+ ['name' => 'Desk 2'],
+ ],
+];
- $path = public_path('css/app.css');
+data_fill($data, 'products.*.price', 200);
-
-#### `resource_path()` {.collection-method}
+/*
+ [
+ 'products' => [
+ ['name' => 'Desk 1', 'price' => 100],
+ ['name' => 'Desk 2', 'price' => 200],
+ ],
+ ]
+*/
+```
-The `resource_path` function returns the fully qualified path to your application's `resources` directory. You may also use the `resource_path` function to generate a fully qualified path to a given file within the resources directory:
+
+#### `data_get()` {.collection-method}
- $path = resource_path();
+The `data_get` function retrieves a value from a nested array or object using "dot" notation:
- $path = resource_path('sass/app.scss');
+```php
+$data = ['products' => ['desk' => ['price' => 100]]];
-
-#### `storage_path()` {.collection-method}
+$price = data_get($data, 'products.desk.price');
-The `storage_path` function returns the fully qualified path to your application's `storage` directory. You may also use the `storage_path` function to generate a fully qualified path to a given file within the storage directory:
+// 100
+```
- $path = storage_path();
+The `data_get` function also accepts a default value, which will be returned if the specified key is not found:
- $path = storage_path('app/file.txt');
+```php
+$discount = data_get($data, 'products.desk.discount', 0);
-
-## Strings
+// 0
+```
-
-#### `__()` {.collection-method}
+The function also accepts wildcards using asterisks, which may target any key of the array or object:
-The `__` function translates the given translation string or translation key using your [localization files](/docs/{{version}}/localization):
+```php
+$data = [
+ 'product-one' => ['name' => 'Desk 1', 'price' => 100],
+ 'product-two' => ['name' => 'Desk 2', 'price' => 150],
+];
- echo __('Welcome to our application');
+data_get($data, '*.name');
- echo __('messages.welcome');
+// ['Desk 1', 'Desk 2'];
+```
-If the specified translation string or key does not exist, the `__` function will return the given value. So, using the example above, the `__` function would return `messages.welcome` if that translation key does not exist.
+The `{first}` and `{last}` placeholders may be used to retrieve the first or last items in an array:
-
-#### `class_basename()` {.collection-method}
+```php
+$flight = [
+ 'segments' => [
+ ['from' => 'LHR', 'departure' => '9:00', 'to' => 'IST', 'arrival' => '15:00'],
+ ['from' => 'IST', 'departure' => '16:00', 'to' => 'PKX', 'arrival' => '20:00'],
+ ],
+];
-The `class_basename` function returns the class name of the given class with the class's namespace removed:
+data_get($flight, 'segments.{first}.arrival');
- $class = class_basename('Foo\Bar\Baz');
+// 15:00
+```
- // Baz
+
+#### `data_set()` {.collection-method}
-
-#### `e()` {.collection-method}
+The `data_set` function sets a value within a nested array or object using "dot" notation:
-The `e` function runs PHP's `htmlspecialchars` function with the `double_encode` option set to `true` by default:
+```php
+$data = ['products' => ['desk' => ['price' => 100]]];
- echo e('foo');
+data_set($data, 'products.desk.price', 200);
- // <html>foo</html>
+// ['products' => ['desk' => ['price' => 200]]]
+```
-
-#### `preg_replace_array()` {.collection-method}
+This function also accepts wildcards using asterisks and will set values on the target accordingly:
-The `preg_replace_array` function replaces a given pattern in the string sequentially using an array:
+```php
+$data = [
+ 'products' => [
+ ['name' => 'Desk 1', 'price' => 100],
+ ['name' => 'Desk 2', 'price' => 150],
+ ],
+];
- $string = 'The event will take place between :start and :end';
+data_set($data, 'products.*.price', 200);
- $replaced = preg_replace_array('/:[a-z_]+/', ['8:30', '9:00'], $string);
+/*
+ [
+ 'products' => [
+ ['name' => 'Desk 1', 'price' => 200],
+ ['name' => 'Desk 2', 'price' => 200],
+ ],
+ ]
+*/
+```
- // The event will take place between 8:30 and 9:00
+By default, any existing values are overwritten. If you wish to only set a value if it doesn't exist, you may pass `false` as the fourth argument to the function:
-
-#### `Str::after()` {.collection-method}
+```php
+$data = ['products' => ['desk' => ['price' => 100]]];
-The `Str::after` method returns everything after the given value in a string. The entire string will be returned if the value does not exist within the string:
+data_set($data, 'products.desk.price', 200, overwrite: false);
- use Illuminate\Support\Str;
+// ['products' => ['desk' => ['price' => 100]]]
+```
- $slice = Str::after('This is my name', 'This is');
+
+#### `data_forget()` {.collection-method}
- // ' my name'
+The `data_forget` function removes a value within a nested array or object using "dot" notation:
-
-#### `Str::afterLast()` {.collection-method}
+```php
+$data = ['products' => ['desk' => ['price' => 100]]];
-The `Str::afterLast` method returns everything after the last occurrence of the given value in a string. The entire string will be returned if the value does not exist within the string:
+data_forget($data, 'products.desk.price');
- use Illuminate\Support\Str;
+// ['products' => ['desk' => []]]
+```
- $slice = Str::afterLast('App\Http\Controllers\Controller', '\\');
+This function also accepts wildcards using asterisks and will remove values on the target accordingly:
- // 'Controller'
+```php
+$data = [
+ 'products' => [
+ ['name' => 'Desk 1', 'price' => 100],
+ ['name' => 'Desk 2', 'price' => 150],
+ ],
+];
-
-#### `Str::ascii()` {.collection-method}
+data_forget($data, 'products.*.price');
-The `Str::ascii` method will attempt to transliterate the string into an ASCII value:
+/*
+ [
+ 'products' => [
+ ['name' => 'Desk 1'],
+ ['name' => 'Desk 2'],
+ ],
+ ]
+*/
+```
- use Illuminate\Support\Str;
+
+#### `head()` {.collection-method}
- $slice = Str::ascii('û');
+The `head` function returns the first element in the given array. If the array is empty, `false` will be returned:
- // 'u'
+```php
+$array = [100, 200, 300];
-
-#### `Str::before()` {.collection-method}
+$first = head($array);
-The `Str::before` method returns everything before the given value in a string:
+// 100
+```
- use Illuminate\Support\Str;
+
+#### `last()` {.collection-method}
- $slice = Str::before('This is my name', 'my name');
+The `last` function returns the last element in the given array. If the array is empty, `false` will be returned:
- // 'This is '
+```php
+$array = [100, 200, 300];
-
-#### `Str::beforeLast()` {.collection-method}
+$last = last($array);
-The `Str::beforeLast` method returns everything before the last occurrence of the given value in a string:
+// 300
+```
- use Illuminate\Support\Str;
+
+## Numbers
- $slice = Str::beforeLast('This is my name', 'is');
+
+#### `Number::abbreviate()` {.collection-method}
- // 'This '
+The `Number::abbreviate` method returns the human-readable format of the provided numerical value, with an abbreviation for the units:
-
-#### `Str::between()` {.collection-method}
+```php
+use Illuminate\Support\Number;
-The `Str::between` method returns the portion of a string between two values:
+$number = Number::abbreviate(1000);
- use Illuminate\Support\Str;
+// 1K
- $slice = Str::between('This is my name', 'This', 'name');
+$number = Number::abbreviate(489939);
- // ' is my '
+// 490K
-
-#### `Str::camel()` {.collection-method}
+$number = Number::abbreviate(1230000, precision: 2);
-The `Str::camel` method converts the given string to `camelCase`:
+// 1.23M
+```
- use Illuminate\Support\Str;
+
+#### `Number::clamp()` {.collection-method}
- $converted = Str::camel('foo_bar');
+The `Number::clamp` method ensures a given number stays within a specified range. If the number is lower than the minimum, the minimum value is returned. If the number is higher than the maximum, the maximum value is returned:
- // fooBar
+```php
+use Illuminate\Support\Number;
-
-#### `Str::contains()` {.collection-method}
+$number = Number::clamp(105, min: 10, max: 100);
-The `Str::contains` method determines if the given string contains the given value. This method is case sensitive:
+// 100
- use Illuminate\Support\Str;
+$number = Number::clamp(5, min: 10, max: 100);
- $contains = Str::contains('This is my name', 'my');
+// 10
- // true
+$number = Number::clamp(10, min: 10, max: 100);
-You may also pass an array of values to determine if the given string contains any of the values in the array:
+// 10
- use Illuminate\Support\Str;
+$number = Number::clamp(20, min: 10, max: 100);
- $contains = Str::contains('This is my name', ['my', 'foo']);
+// 20
+```
- // true
+
+#### `Number::currency()` {.collection-method}
-
-#### `Str::containsAll()` {.collection-method}
+The `Number::currency` method returns the currency representation of the given value as a string:
-The `Str::containsAll` method determines if the given string contains all of the values in a given array:
+```php
+use Illuminate\Support\Number;
- use Illuminate\Support\Str;
+$currency = Number::currency(1000);
- $containsAll = Str::containsAll('This is my name', ['my', 'name']);
+// $1,000.00
- // true
+$currency = Number::currency(1000, in: 'EUR');
-
-#### `Str::endsWith()` {.collection-method}
+// €1,000.00
-The `Str::endsWith` method determines if the given string ends with the given value:
+$currency = Number::currency(1000, in: 'EUR', locale: 'de');
- use Illuminate\Support\Str;
+// 1.000,00 €
- $result = Str::endsWith('This is my name', 'name');
+$currency = Number::currency(1000, in: 'EUR', locale: 'de', precision: 0);
- // true
+// 1.000 €
+```
+
+#### `Number::defaultCurrency()` {.collection-method}
-You may also pass an array of values to determine if the given string ends with any of the values in the array:
+The `Number::defaultCurrency` method returns the default currency being used by the `Number` class:
- use Illuminate\Support\Str;
+```php
+use Illuminate\Support\Number;
- $result = Str::endsWith('This is my name', ['name', 'foo']);
+$currency = Number::defaultCurrency();
- // true
+// USD
+```
- $result = Str::endsWith('This is my name', ['this', 'foo']);
+
+#### `Number::defaultLocale()` {.collection-method}
- // false
+The `Number::defaultLocale` method returns the default locale being used by the `Number` class:
-
-#### `Str::excerpt()` {.collection-method}
+```php
+use Illuminate\Support\Number;
-The `Str::excerpt` method extracts an excerpt from a given string that matches the first instance of a phrase within that string:
+$locale = Number::defaultLocale();
- use Illuminate\Support\Str;
+// en
+```
- $excerpt = Str::excerpt('This is my name', 'my', [
- 'radius' => 3
- ]);
+
+#### `Number::fileSize()` {.collection-method}
- // '...is my na...'
+The `Number::fileSize` method returns the file size representation of the given byte value as a string:
-The `radius` option, which defaults to `100`, allows you to define the number of characters that should appear on each side of the truncated string.
+```php
+use Illuminate\Support\Number;
-In addition, you may use the `omission` option to define the string that will be prepended and appended to the truncated string:
+$size = Number::fileSize(1024);
- use Illuminate\Support\Str;
+// 1 KB
- $excerpt = Str::excerpt('This is my name', 'name', [
- 'radius' => 3,
- 'omission' => '(...) '
- ]);
+$size = Number::fileSize(1024 * 1024);
- // '(...) my name'
+// 1 MB
-
-#### `Str::finish()` {.collection-method}
+$size = Number::fileSize(1024, precision: 2);
-The `Str::finish` method adds a single instance of the given value to a string if it does not already end with that value:
+// 1.00 KB
+```
- use Illuminate\Support\Str;
+
+#### `Number::forHumans()` {.collection-method}
- $adjusted = Str::finish('this/string', '/');
+The `Number::forHumans` method returns the human-readable format of the provided numerical value:
- // this/string/
+```php
+use Illuminate\Support\Number;
- $adjusted = Str::finish('this/string/', '/');
+$number = Number::forHumans(1000);
- // this/string/
+// 1 thousand
-
-#### `Str::headline()` {.collection-method}
+$number = Number::forHumans(489939);
-The `Str::headline` method will convert strings delimited by casing, hyphens, or underscores into a space delimited string with each word's first letter capitalized:
+// 490 thousand
- use Illuminate\Support\Str;
+$number = Number::forHumans(1230000, precision: 2);
- $headline = Str::headline('steve_jobs');
+// 1.23 million
+```
- // Steve Jobs
+
+#### `Number::format()` {.collection-method}
- $headline = Str::headline('EmailNotificationSent');
+The `Number::format` method formats the given number into a locale specific string:
- // Email Notification Sent
+```php
+use Illuminate\Support\Number;
-
-#### `Str::is()` {.collection-method}
+$number = Number::format(100000);
-The `Str::is` method determines if a given string matches a given pattern. Asterisks may be used as wildcard values:
+// 100,000
- use Illuminate\Support\Str;
+$number = Number::format(100000, precision: 2);
- $matches = Str::is('foo*', 'foobar');
+// 100,000.00
- // true
+$number = Number::format(100000.123, maxPrecision: 2);
- $matches = Str::is('baz*', 'foobar');
+// 100,000.12
- // false
+$number = Number::format(100000, locale: 'de');
-
-#### `Str::isAscii()` {.collection-method}
+// 100.000
+```
-The `Str::isAscii` method determines if a given string is 7 bit ASCII:
+
+#### `Number::ordinal()` {.collection-method}
- use Illuminate\Support\Str;
+The `Number::ordinal` method returns a number's ordinal representation:
- $isAscii = Str::isAscii('Taylor');
+```php
+use Illuminate\Support\Number;
- // true
+$number = Number::ordinal(1);
- $isAscii = Str::isAscii('ü');
+// 1st
- // false
+$number = Number::ordinal(2);
-
-#### `Str::isUuid()` {.collection-method}
+// 2nd
-The `Str::isUuid` method determines if the given string is a valid UUID:
+$number = Number::ordinal(21);
- use Illuminate\Support\Str;
+// 21st
+```
- $isUuid = Str::isUuid('a0a2a2d2-0b87-4a18-83f2-2529882be2de');
+
+#### `Number::pairs()` {.collection-method}
- // true
+The `Number::pairs` method generates an array of number pairs (sub-ranges) based on a specified range and step value. This method can be useful for dividing a larger range of numbers into smaller, manageable sub-ranges for things like pagination or batching tasks. The `pairs` method returns an array of arrays, where each inner array represents a pair (sub-range) of numbers:
- $isUuid = Str::isUuid('laravel');
+```php
+use Illuminate\Support\Number;
- // false
+$result = Number::pairs(25, 10);
-
-#### `Str::kebab()` {.collection-method}
+// [[0, 9], [10, 19], [20, 25]]
-The `Str::kebab` method converts the given string to `kebab-case`:
+$result = Number::pairs(25, 10, offset: 0);
- use Illuminate\Support\Str;
+// [[0, 10], [10, 20], [20, 25]]
+```
- $converted = Str::kebab('fooBar');
+
+#### `Number::parseInt()` {.collection-method}
- // foo-bar
+The `Number::parseInt` method parse a string into an integer according to the specified locale:
-
-#### `Str::length()` {.collection-method}
+```php
+use Illuminate\Support\Number;
-The `Str::length` method returns the length of the given string:
+$result = Number::parseInt('10.123');
- use Illuminate\Support\Str;
+// (int) 10
- $length = Str::length('Laravel');
+$result = Number::parseInt('10,123', locale: 'fr');
- // 7
+// (int) 10
+```
-
-#### `Str::limit()` {.collection-method}
+
+#### `Number::parseFloat()` {.collection-method}
-The `Str::limit` method truncates the given string to the specified length:
+The `Number::parseFloat` method parse a string into a float according to the specified locale:
- use Illuminate\Support\Str;
+```php
+use Illuminate\Support\Number;
- $truncated = Str::limit('The quick brown fox jumps over the lazy dog', 20);
+$result = Number::parseFloat('10');
- // The quick brown fox...
+// (float) 10.0
-You may pass a third argument to the method to change the string that will be appended to the end of the truncated string:
+$result = Number::parseFloat('10', locale: 'fr');
- use Illuminate\Support\Str;
+// (float) 10.0
+```
- $truncated = Str::limit('The quick brown fox jumps over the lazy dog', 20, ' (...)');
+
+#### `Number::percentage()` {.collection-method}
- // The quick brown fox (...)
+The `Number::percentage` method returns the percentage representation of the given value as a string:
-
-#### `Str::lower()` {.collection-method}
+```php
+use Illuminate\Support\Number;
-The `Str::lower` method converts the given string to lowercase:
+$percentage = Number::percentage(10);
- use Illuminate\Support\Str;
+// 10%
- $converted = Str::lower('LARAVEL');
+$percentage = Number::percentage(10, precision: 2);
- // laravel
+// 10.00%
-
-#### `Str::markdown()` {.collection-method}
+$percentage = Number::percentage(10.123, maxPrecision: 2);
-The `Str::markdown` method converts GitHub flavored Markdown into HTML:
+// 10.12%
- use Illuminate\Support\Str;
+$percentage = Number::percentage(10, precision: 2, locale: 'de');
- $html = Str::markdown('# Laravel');
+// 10,00%
+```
- //
[all](#method-all)
[average](#method-average)
@@ -3278,6 +4152,7 @@ Almost all methods available on the `Collection` class are also available on the
[except](#method-except)
[filter](#method-filter)
[first](#method-first)
+[firstOrFail](#method-first-or-fail)
[firstWhere](#method-first-where)
[flatMap](#method-flatmap)
[flatten](#method-flatten)
@@ -3288,6 +4163,7 @@ Almost all methods available on the `Collection` class are also available on the
[has](#method-has)
[implode](#method-implode)
[intersect](#method-intersect)
+[intersectAssoc](#method-intersectAssoc)
[intersectByKeys](#method-intersectbykeys)
[isEmpty](#method-isempty)
[isNotEmpty](#method-isnotempty)
@@ -3324,6 +4200,7 @@ Almost all methods available on the `Collection` class are also available on the
[shuffle](#method-shuffle)
[skip](#method-skip)
[slice](#method-slice)
+[sole](#method-sole)
[some](#method-some)
[sort](#method-sort)
[sortBy](#method-sortby)
@@ -3362,7 +4239,8 @@ Almost all methods available on the `Collection` class are also available on the
-> {note} Methods that mutate the collection (such as `shift`, `pop`, `prepend` etc.) are **not** available on the `LazyCollection` class.
+> [!WARNING]
+> Methods that mutate the collection (such as `shift`, `pop`, `prepend` etc.) are **not** available on the `LazyCollection` class.
### Lazy Collection Methods
@@ -3374,61 +4252,111 @@ In addition to the methods defined in the `Enumerable` contract, the `LazyCollec
The `takeUntilTimeout` method returns a new lazy collection that will enumerate values until the specified time. After that time, the collection will then stop enumerating:
- $lazyCollection = LazyCollection::times(INF)
- ->takeUntilTimeout(now()->addMinute());
+```php
+$lazyCollection = LazyCollection::times(INF)
+ ->takeUntilTimeout(now()->addMinute());
- $lazyCollection->each(function ($number) {
- dump($number);
+$lazyCollection->each(function (int $number) {
+ dump($number);
- sleep(1);
- });
+ sleep(1);
+});
- // 1
- // 2
- // ...
- // 58
- // 59
+// 1
+// 2
+// ...
+// 58
+// 59
+```
To illustrate the usage of this method, imagine an application that submits invoices from the database using a cursor. You could define a [scheduled task](/docs/{{version}}/scheduling) that runs every 15 minutes and only processes invoices for a maximum of 14 minutes:
- use App\Models\Invoice;
- use Illuminate\Support\Carbon;
+```php
+use App\Models\Invoice;
+use Illuminate\Support\Carbon;
- Invoice::pending()->cursor()
- ->takeUntilTimeout(
- Carbon::createFromTimestamp(LARAVEL_START)->add(14, 'minutes')
- )
- ->each(fn ($invoice) => $invoice->submit());
+Invoice::pending()->cursor()
+ ->takeUntilTimeout(
+ Carbon::createFromTimestamp(LARAVEL_START)->add(14, 'minutes')
+ )
+ ->each(fn (Invoice $invoice) => $invoice->submit());
+```
#### `tapEach()` {.collection-method}
While the `each` method calls the given callback for each item in the collection right away, the `tapEach` method only calls the given callback as the items are being pulled out of the list one by one:
- // Nothing has been dumped so far...
- $lazyCollection = LazyCollection::times(INF)->tapEach(function ($value) {
- dump($value);
- });
+```php
+// Nothing has been dumped so far...
+$lazyCollection = LazyCollection::times(INF)->tapEach(function (int $value) {
+ dump($value);
+});
- // Three items are dumped...
- $array = $lazyCollection->take(3)->all();
+// Three items are dumped...
+$array = $lazyCollection->take(3)->all();
- // 1
- // 2
- // 3
+// 1
+// 2
+// 3
+```
+
+
+#### `throttle()` {.collection-method}
+
+The `throttle` method will throttle the lazy collection such that each value is returned after the specified number of seconds. This method is especially useful for situations where you may be interacting with external APIs that rate limit incoming requests:
+
+```php
+use App\Models\User;
+
+User::where('vip', true)
+ ->cursor()
+ ->throttle(seconds: 1)
+ ->each(function (User $user) {
+ // Call external API...
+ });
+```
#### `remember()` {.collection-method}
The `remember` method returns a new lazy collection that will remember any values that have already been enumerated and will not retrieve them again on subsequent collection enumerations:
- // No query has been executed yet...
- $users = User::cursor()->remember();
+```php
+// No query has been executed yet...
+$users = User::cursor()->remember();
+
+// The query is executed...
+// The first 5 users are hydrated from the database...
+$users->take(5)->all();
- // The query is executed...
- // The first 5 users are hydrated from the database...
- $users->take(5)->all();
+// First 5 users come from the collection's cache...
+// The rest are hydrated from the database...
+$users->take(20)->all();
+```
+
+
+#### `withHeartbeat()` {.collection-method}
+
+The `withHeartbeat` method allows you to execute a callback at regular time intervals while a lazy collection is being enumerated. This is particularly useful for long-running operations that require periodic maintenance tasks, such as extending locks or sending progress updates:
+
+```php
+use Carbon\CarbonInterval;
+use Illuminate\Support\Facades\Cache;
- // First 5 users come from the collection's cache...
- // The rest are hydrated from the database...
- $users->take(20)->all();
+$lock = Cache::lock('generate-reports', seconds: 60 * 5);
+
+if ($lock->get()) {
+ try {
+ Report::where('status', 'pending')
+ ->lazy()
+ ->withHeartbeat(
+ CarbonInterval::minutes(4),
+ fn () => $lock->extend(CarbonInterval::minutes(5))
+ )
+ ->each(fn ($report) => $report->process());
+ } finally {
+ $lock->release();
+ }
+}
+```
diff --git a/concurrency.md b/concurrency.md
new file mode 100644
index 00000000000..9a412ee2b60
--- /dev/null
+++ b/concurrency.md
@@ -0,0 +1,67 @@
+# Concurrency
+
+- [Introduction](#introduction)
+- [Running Concurrent Tasks](#running-concurrent-tasks)
+- [Deferring Concurrent Tasks](#deferring-concurrent-tasks)
+
+
+## Introduction
+
+Sometimes you may need to execute several slow tasks which do not depend on one another. In many cases, significant performance improvements can be realized by executing the tasks concurrently. Laravel's `Concurrency` facade provides a simple, convenient API for executing closures concurrently.
+
+
+#### How it Works
+
+Laravel achieves concurrency by serializing the given closures and dispatching them to a hidden Artisan CLI command, which unserializes the closures and invokes it within its own PHP process. After the closure has been invoked, the resulting value is serialized back to the parent process.
+
+The `Concurrency` facade supports three drivers: `process` (the default), `fork`, and `sync`.
+
+The `fork` driver offers improved performance compared to the default `process` driver, but it may only be used within PHP's CLI context, as PHP does not support forking during web requests. Before using the `fork` driver, you need to install the `spatie/fork` package:
+
+```shell
+composer require spatie/fork
+```
+
+The `sync` driver is primarily useful during testing when you want to disable all concurrency and simply execute the given closures in sequence within the parent process.
+
+
+## Running Concurrent Tasks
+
+To run concurrent tasks, you may invoke the `Concurrency` facade's `run` method. The `run` method accepts an array of closures which should be executed simultaneously in child PHP processes:
+
+```php
+use Illuminate\Support\Facades\Concurrency;
+use Illuminate\Support\Facades\DB;
+
+[$userCount, $orderCount] = Concurrency::run([
+ fn () => DB::table('users')->count(),
+ fn () => DB::table('orders')->count(),
+]);
+```
+
+To use a specific driver, you may use the `driver` method:
+
+```php
+$results = Concurrency::driver('fork')->run(...);
+```
+
+Or, to change the default concurrency driver, you should publish the `concurrency` configuration file via the `config:publish` Artisan command and update the `default` option within the file:
+
+```shell
+php artisan config:publish concurrency
+```
+
+
+## Deferring Concurrent Tasks
+
+If you would like to execute an array of closures concurrently, but are not interested in the results returned by those closures, you should consider using the `defer` method. When the `defer` method is invoked, the given closures are not executed immediately. Instead, Laravel will execute the closures concurrently after the HTTP response has been sent to the user:
+
+```php
+use App\Services\Metrics;
+use Illuminate\Support\Facades\Concurrency;
+
+Concurrency::defer([
+ fn () => Metrics::report('users'),
+ fn () => Metrics::report('orders'),
+]);
+```
diff --git a/configuration.md b/configuration.md
index ba2622647cb..2e56183b1f5 100644
--- a/configuration.md
+++ b/configuration.md
@@ -4,9 +4,11 @@
- [Environment Configuration](#environment-configuration)
- [Environment Variable Types](#environment-variable-types)
- [Retrieving Environment Configuration](#retrieving-environment-configuration)
- - [Determining The Current Environment](#determining-the-current-environment)
+ - [Determining the Current Environment](#determining-the-current-environment)
+ - [Encrypting Environment Files](#encrypting-environment-files)
- [Accessing Configuration Values](#accessing-configuration-values)
- [Configuration Caching](#configuration-caching)
+- [Configuration Publishing](#configuration-publishing)
- [Debug Mode](#debug-mode)
- [Maintenance Mode](#maintenance-mode)
@@ -15,7 +17,28 @@
All of the configuration files for the Laravel framework are stored in the `config` directory. Each option is documented, so feel free to look through the files and get familiar with the options available to you.
-These configuration files allow you to configure things like your database connection information, your mail server information, as well as various other core configuration values such as your application timezone and encryption key.
+These configuration files allow you to configure things like your database connection information, your mail server information, as well as various other core configuration values such as your application URL and encryption key.
+
+
+#### The `about` Command
+
+Laravel can display an overview of your application's configuration, drivers, and environment via the `about` Artisan command.
+
+```shell
+php artisan about
+```
+
+If you're only interested in a particular section of the application overview output, you may filter for that section using the `--only` option:
+
+```shell
+php artisan about --only=environment
+```
+
+Or, to explore a specific configuration file's values in detail, you may use the `config:show` Artisan command:
+
+```shell
+php artisan config:show database
+```
## Environment Configuration
@@ -24,37 +47,44 @@ It is often helpful to have different configuration values based on the environm
To make this a cinch, Laravel utilizes the [DotEnv](https://github.com/vlucas/phpdotenv) PHP library. In a fresh Laravel installation, the root directory of your application will contain a `.env.example` file that defines many common environment variables. During the Laravel installation process, this file will automatically be copied to `.env`.
-Laravel's default `.env` file contains some common configuration values that may differ based on whether your application is running locally or on a production web server. These values are then retrieved from various Laravel configuration files within the `config` directory using Laravel's `env` function.
+Laravel's default `.env` file contains some common configuration values that may differ based on whether your application is running locally or on a production web server. These values are then read by the configuration files within the `config` directory using Laravel's `env` function.
-If you are developing with a team, you may wish to continue including a `.env.example` file with your application. By putting placeholder values in the example configuration file, other developers on your team can clearly see which environment variables are needed to run your application.
+If you are developing with a team, you may wish to continue including and updating the `.env.example` file with your application. By putting placeholder values in the example configuration file, other developers on your team can clearly see which environment variables are needed to run your application.
-> {tip} Any variable in your `.env` file can be overridden by external environment variables such as server-level or system-level environment variables.
+> [!NOTE]
+> Any variable in your `.env` file can be overridden by external environment variables such as server-level or system-level environment variables.
#### Environment File Security
Your `.env` file should not be committed to your application's source control, since each developer / server using your application could require a different environment configuration. Furthermore, this would be a security risk in the event an intruder gains access to your source control repository, since any sensitive credentials would get exposed.
+However, it is possible to encrypt your environment file using Laravel's built-in [environment encryption](#encrypting-environment-files). Encrypted environment files may be placed in source control safely.
+
#### Additional Environment Files
-Before loading your application's environment variables, Laravel determines if either the `APP_ENV` environment variable has been externally provided or if the `--env` CLI argument has been specified. If so, Laravel will attempt to load an `.env.[APP_ENV]` file if it exists. If it does not exist, the default `.env` file will be loaded.
+Before loading your application's environment variables, Laravel determines if an `APP_ENV` environment variable has been externally provided or if the `--env` CLI argument has been specified. If so, Laravel will attempt to load an `.env.[APP_ENV]` file if it exists. If it does not exist, the default `.env` file will be loaded.
### Environment Variable Types
All variables in your `.env` files are typically parsed as strings, so some reserved values have been created to allow you to return a wider range of types from the `env()` function:
-`.env` Value | `env()` Value
-------------- | -------------
-true | (bool) true
-(true) | (bool) true
-false | (bool) false
-(false) | (bool) false
-empty | (string) ''
-(empty) | (string) ''
-null | (null) null
-(null) | (null) null
+
+
+| `.env` Value | `env()` Value |
+| ------------ | ------------- |
+| true | (bool) true |
+| (true) | (bool) true |
+| false | (bool) false |
+| (false) | (bool) false |
+| empty | (string) '' |
+| (empty) | (string) '' |
+| null | (null) null |
+| (null) | (null) null |
+
+
If you need to define an environment variable with a value that contains spaces, you may do so by enclosing the value in double quotes:
@@ -65,46 +95,138 @@ APP_NAME="My Application"
### Retrieving Environment Configuration
-All of the variables listed in this file will be loaded into the `$_ENV` PHP super-global when your application receives a request. However, you may use the `env` helper to retrieve values from these variables in your configuration files. In fact, if you review the Laravel configuration files, you will notice many of the options are already using this helper:
+All of the variables listed in the `.env` file will be loaded into the `$_ENV` PHP super-global when your application receives a request. However, you may use the `env` function to retrieve values from these variables in your configuration files. In fact, if you review the Laravel configuration files, you will notice many of the options are already using this function:
- 'debug' => env('APP_DEBUG', false),
+```php
+'debug' => (bool) env('APP_DEBUG', false),
+```
The second value passed to the `env` function is the "default value". This value will be returned if no environment variable exists for the given key.
-### Determining The Current Environment
+### Determining the Current Environment
The current application environment is determined via the `APP_ENV` variable from your `.env` file. You may access this value via the `environment` method on the `App` [facade](/docs/{{version}}/facades):
- use Illuminate\Support\Facades\App;
+```php
+use Illuminate\Support\Facades\App;
- $environment = App::environment();
+$environment = App::environment();
+```
You may also pass arguments to the `environment` method to determine if the environment matches a given value. The method will return `true` if the environment matches any of the given values:
- if (App::environment('local')) {
- // The environment is local
- }
+```php
+if (App::environment('local')) {
+ // The environment is local
+}
+
+if (App::environment(['local', 'staging'])) {
+ // The environment is either local OR staging...
+}
+```
+
+> [!NOTE]
+> The current application environment detection can be overridden by defining a server-level `APP_ENV` environment variable.
+
+
+### Encrypting Environment Files
+
+Unencrypted environment files should never be stored in source control. However, Laravel allows you to encrypt your environment files so that they may safely be added to source control with the rest of your application.
+
+
+#### Encryption
+
+To encrypt an environment file, you may use the `env:encrypt` command:
+
+```shell
+php artisan env:encrypt
+```
+
+Running the `env:encrypt` command will encrypt your `.env` file and place the encrypted contents in an `.env.encrypted` file. The decryption key is presented in the output of the command and should be stored in a secure password manager. If you would like to provide your own encryption key you may use the `--key` option when invoking the command:
+
+```shell
+php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF
+```
+
+> [!NOTE]
+> The length of the key provided should match the key length required by the encryption cipher being used. By default, Laravel will use the `AES-256-CBC` cipher which requires a 32 character key. You are free to use any cipher supported by Laravel's [encrypter](/docs/{{version}}/encryption) by passing the `--cipher` option when invoking the command.
+
+If your application has multiple environment files, such as `.env` and `.env.staging`, you may specify the environment file that should be encrypted by providing the environment name via the `--env` option:
+
+```shell
+php artisan env:encrypt --env=staging
+```
+
+
+#### Decryption
+
+To decrypt an environment file, you may use the `env:decrypt` command. This command requires a decryption key, which Laravel will retrieve from the `LARAVEL_ENV_ENCRYPTION_KEY` environment variable:
+
+```shell
+php artisan env:decrypt
+```
+
+Or, the key may be provided directly to the command via the `--key` option:
+
+```shell
+php artisan env:decrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF
+```
+
+When the `env:decrypt` command is invoked, Laravel will decrypt the contents of the `.env.encrypted` file and place the decrypted contents in the `.env` file.
+
+The `--cipher` option may be provided to the `env:decrypt` command in order to use a custom encryption cipher:
+
+```shell
+php artisan env:decrypt --key=qUWuNRdfuImXcKxZ --cipher=AES-128-CBC
+```
+
+If your application has multiple environment files, such as `.env` and `.env.staging`, you may specify the environment file that should be decrypted by providing the environment name via the `--env` option:
+
+```shell
+php artisan env:decrypt --env=staging
+```
- if (App::environment(['local', 'staging'])) {
- // The environment is either local OR staging...
- }
+In order to overwrite an existing environment file, you may provide the `--force` option to the `env:decrypt` command:
-> {tip} The current application environment detection can be overridden by defining a server-level `APP_ENV` environment variable.
+```shell
+php artisan env:decrypt --force
+```
## Accessing Configuration Values
-You may easily access your configuration values using the global `config` helper function from anywhere in your application. The configuration values may be accessed using "dot" syntax, which includes the name of the file and option you wish to access. A default value may also be specified and will be returned if the configuration option does not exist:
+You may easily access your configuration values using the `Config` facade or global `config` function from anywhere in your application. The configuration values may be accessed using "dot" syntax, which includes the name of the file and option you wish to access. A default value may also be specified and will be returned if the configuration option does not exist:
+
+```php
+use Illuminate\Support\Facades\Config;
- $value = config('app.timezone');
+$value = Config::get('app.timezone');
- // Retrieve a default value if the configuration value does not exist...
- $value = config('app.timezone', 'Asia/Seoul');
+$value = config('app.timezone');
-To set configuration values at runtime, pass an array to the `config` helper:
+// Retrieve a default value if the configuration value does not exist...
+$value = config('app.timezone', 'Asia/Seoul');
+```
+
+To set configuration values at runtime, you may invoke the `Config` facade's `set` method or pass an array to the `config` function:
- config(['app.timezone' => 'America/Chicago']);
+```php
+Config::set('app.timezone', 'America/Chicago');
+
+config(['app.timezone' => 'America/Chicago']);
+```
+
+To assist with static analysis, the `Config` facade also provides typed configuration retrieval methods. If the retrieved configuration value does not match the expected type, an exception will be thrown:
+
+```php
+Config::string('config-key');
+Config::integer('config-key');
+Config::float('config-key');
+Config::boolean('config-key');
+Config::array('config-key');
+Config::collection('config-key');
+```
## Configuration Caching
@@ -113,14 +235,39 @@ To give your application a speed boost, you should cache all of your configurati
You should typically run the `php artisan config:cache` command as part of your production deployment process. The command should not be run during local development as configuration options will frequently need to be changed during the course of your application's development.
-> {note} If you execute the `config:cache` command during your deployment process, you should be sure that you are only calling the `env` function from within your configuration files. Once the configuration has been cached, the `.env` file will not be loaded; therefore, the `env` function will only return external, system level environment variables.
+Once the configuration has been cached, your application's `.env` file will not be loaded by the framework during requests or Artisan commands; therefore, the `env` function will only return external, system level environment variables.
+
+For this reason, you should ensure you are only calling the `env` function from within your application's configuration (`config`) files. You can see many examples of this by examining Laravel's default configuration files. Configuration values may be accessed from anywhere in your application using the `config` function [described above](#accessing-configuration-values).
+
+The `config:clear` command may be used to purge the cached configuration:
+
+```shell
+php artisan config:clear
+```
+
+> [!WARNING]
+> If you execute the `config:cache` command during your deployment process, you should be sure that you are only calling the `env` function from within your configuration files. Once the configuration has been cached, the `.env` file will not be loaded; therefore, the `env` function will only return external, system level environment variables.
+
+
+## Configuration Publishing
+
+Most of Laravel's configuration files are already published in your application's `config` directory; however, certain configuration files like `cors.php` and `view.php` are not published by default, as most applications will never need to modify them.
+
+However, you may use the `config:publish` Artisan command to publish any configuration files that are not published by default:
+
+```shell
+php artisan config:publish
+
+php artisan config:publish --all
+```
## Debug Mode
The `debug` option in your `config/app.php` configuration file determines how much information about an error is actually displayed to the user. By default, this option is set to respect the value of the `APP_DEBUG` environment variable, which is stored in your `.env` file.
-For local development, you should set the `APP_DEBUG` environment variable to `true`. **In your production environment, this value should always be `false`. If the variable is set to `true` in production, you risk exposing sensitive configuration values to your application's end users.**
+> [!WARNING]
+> For local development, you should set the `APP_DEBUG` environment variable to `true`. **In your production environment, this value should always be `false`. If the variable is set to `true` in production, you risk exposing sensitive configuration values to your application's end users.**
## Maintenance Mode
@@ -148,7 +295,7 @@ php artisan down --retry=60
#### Bypassing Maintenance Mode
-Even while in maintenance mode, you may use the `secret` option to specify a maintenance mode bypass token:
+To allow maintenance mode to be bypassed using a secret token, you may use the `secret` option to specify a maintenance mode bypass token:
```shell
php artisan down --secret="1630542a-246b-4b66-afa1-dd72a4c43515"
@@ -160,12 +307,31 @@ After placing the application in maintenance mode, you may navigate to the appli
https://example.com/1630542a-246b-4b66-afa1-dd72a4c43515
```
+If you would like Laravel to generate the secret token for you, you may use the `with-secret` option. The secret will be displayed to you once the application is in maintenance mode:
+
+```shell
+php artisan down --with-secret
+```
+
When accessing this hidden route, you will then be redirected to the `/` route of the application. Once the cookie has been issued to your browser, you will be able to browse the application normally as if it was not in maintenance mode.
-> {tip} Your maintenance mode secret should typically consist of alpha-numeric characters and, optionally, dashes. You should avoid using characters that have special meaning in URLs such as `?`.
+> [!NOTE]
+> Your maintenance mode secret should typically consist of alpha-numeric characters and, optionally, dashes. You should avoid using characters that have special meaning in URLs such as `?` or `&`.
+
+
+#### Maintenance Mode on Multiple Servers
+
+By default, Laravel determines if your application is in maintenance mode using a file-based system. This means to activate maintenance mode, the `php artisan down` command has to be executed on each server hosting your application.
+
+Alternatively, Laravel offers a cache-based method for handling maintenance mode. This method requires running the `php artisan down` command on just one server. To use this approach, modify the maintenance mode variables in your application's `.env` file. You should select a cache `store` that is accessible by all of your servers. This ensures the maintenance mode status is consistently maintained across every server:
+
+```ini
+APP_MAINTENANCE_DRIVER=cache
+APP_MAINTENANCE_STORE=database
+```
-#### Pre-Rendering The Maintenance Mode View
+#### Pre-Rendering the Maintenance Mode View
If you utilize the `php artisan down` command during deployment, your users may still occasionally encounter errors if they access the application while your Composer dependencies or other infrastructure components are updating. This occurs because a significant part of the Laravel framework must boot in order to determine your application is in maintenance mode and render the maintenance mode view using the templating engine.
@@ -193,14 +359,15 @@ To disable maintenance mode, use the `up` command:
php artisan up
```
-> {tip} You may customize the default maintenance mode template by defining your own template at `resources/views/errors/503.blade.php`.
+> [!NOTE]
+> You may customize the default maintenance mode template by defining your own template at `resources/views/errors/503.blade.php`.
-#### Maintenance Mode & Queues
+#### Maintenance Mode and Queues
While your application is in maintenance mode, no [queued jobs](/docs/{{version}}/queues) will be handled. The jobs will continue to be handled as normal once the application is out of maintenance mode.
-#### Alternatives To Maintenance Mode
+#### Alternatives to Maintenance Mode
-Since maintenance mode requires your application to have several seconds of downtime, consider alternatives like [Laravel Vapor](https://vapor.laravel.com) and [Envoyer](https://envoyer.io) to accomplish zero-downtime deployment with Laravel.
+Since maintenance mode requires your application to have several seconds of downtime, consider running your applications on a fully-managed platform like [Laravel Cloud](https://cloud.laravel.com) to accomplish zero-downtime deployment with Laravel.
diff --git a/console-tests.md b/console-tests.md
index 871ab7fb204..a020c22c253 100644
--- a/console-tests.md
+++ b/console-tests.md
@@ -3,6 +3,7 @@
- [Introduction](#introduction)
- [Success / Failure Expectations](#success-failure-expectations)
- [Input / Output Expectations](#input-output-expectations)
+- [Console Events](#console-events)
## Introduction
@@ -14,79 +15,211 @@ In addition to simplifying HTTP testing, Laravel provides a simple API for testi
To get started, let's explore how to make assertions regarding an Artisan command's exit code. To accomplish this, we will use the `artisan` method to invoke an Artisan command from our test. Then, we will use the `assertExitCode` method to assert that the command completed with a given exit code:
- /**
- * Test a console command.
- *
- * @return void
- */
- public function test_console_command()
- {
- $this->artisan('inspire')->assertExitCode(0);
- }
+```php tab=Pest
+test('console command', function () {
+ $this->artisan('inspire')->assertExitCode(0);
+});
+```
+
+```php tab=PHPUnit
+/**
+ * Test a console command.
+ */
+public function test_console_command(): void
+{
+ $this->artisan('inspire')->assertExitCode(0);
+}
+```
You may use the `assertNotExitCode` method to assert that the command did not exit with a given exit code:
- $this->artisan('inspire')->assertNotExitCode(1);
+```php
+$this->artisan('inspire')->assertNotExitCode(1);
+```
Of course, all terminal commands typically exit with a status code of `0` when they are successful and a non-zero exit code when they are not successful. Therefore, for convenience, you may utilize the `assertSuccessful` and `assertFailed` assertions to assert that a given command exited with a successful exit code or not:
- $this->artisan('inspire')->assertSuccessful();
+```php
+$this->artisan('inspire')->assertSuccessful();
- $this->artisan('inspire')->assertFailed();
+$this->artisan('inspire')->assertFailed();
+```
## Input / Output Expectations
Laravel allows you to easily "mock" user input for your console commands using the `expectsQuestion` method. In addition, you may specify the exit code and text that you expect to be output by the console command using the `assertExitCode` and `expectsOutput` methods. For example, consider the following console command:
- Artisan::command('question', function () {
- $name = $this->ask('What is your name?');
-
- $language = $this->choice('Which language do you prefer?', [
- 'PHP',
- 'Ruby',
- 'Python',
- ]);
-
- $this->line('Your name is '.$name.' and you prefer '.$language.'.');
- });
-
-You may test this command with the following test which utilizes the `expectsQuestion`, `expectsOutput`, `doesntExpectOutput`, and `assertExitCode` methods:
-
- /**
- * Test a console command.
- *
- * @return void
- */
- public function test_console_command()
- {
- $this->artisan('question')
- ->expectsQuestion('What is your name?', 'Taylor Otwell')
- ->expectsQuestion('Which language do you prefer?', 'PHP')
- ->expectsOutput('Your name is Taylor Otwell and you prefer PHP.')
- ->doesntExpectOutput('Your name is Taylor Otwell and you prefer Ruby.')
- ->assertExitCode(0);
- }
+```php
+Artisan::command('question', function () {
+ $name = $this->ask('What is your name?');
+
+ $language = $this->choice('Which language do you prefer?', [
+ 'PHP',
+ 'Ruby',
+ 'Python',
+ ]);
+
+ $this->line('Your name is '.$name.' and you prefer '.$language.'.');
+});
+```
+
+You may test this command with the following test:
+
+```php tab=Pest
+test('console command', function () {
+ $this->artisan('question')
+ ->expectsQuestion('What is your name?', 'Taylor Otwell')
+ ->expectsQuestion('Which language do you prefer?', 'PHP')
+ ->expectsOutput('Your name is Taylor Otwell and you prefer PHP.')
+ ->doesntExpectOutput('Your name is Taylor Otwell and you prefer Ruby.')
+ ->assertExitCode(0);
+});
+```
+
+```php tab=PHPUnit
+/**
+ * Test a console command.
+ */
+public function test_console_command(): void
+{
+ $this->artisan('question')
+ ->expectsQuestion('What is your name?', 'Taylor Otwell')
+ ->expectsQuestion('Which language do you prefer?', 'PHP')
+ ->expectsOutput('Your name is Taylor Otwell and you prefer PHP.')
+ ->doesntExpectOutput('Your name is Taylor Otwell and you prefer Ruby.')
+ ->assertExitCode(0);
+}
+```
+
+If you are utilizing the `search` or `multisearch` functions provided by [Laravel Prompts](/docs/{{version}}/prompts), you may use the `expectsSearch` assertion to mock the user's input, search results, and selection:
+
+```php tab=Pest
+test('console command', function () {
+ $this->artisan('example')
+ ->expectsSearch('What is your name?', search: 'Tay', answers: [
+ 'Taylor Otwell',
+ 'Taylor Swift',
+ 'Darian Taylor'
+ ], answer: 'Taylor Otwell')
+ ->assertExitCode(0);
+});
+```
+
+```php tab=PHPUnit
+/**
+ * Test a console command.
+ */
+public function test_console_command(): void
+{
+ $this->artisan('example')
+ ->expectsSearch('What is your name?', search: 'Tay', answers: [
+ 'Taylor Otwell',
+ 'Taylor Swift',
+ 'Darian Taylor'
+ ], answer: 'Taylor Otwell')
+ ->assertExitCode(0);
+}
+```
+
+You may also assert that a console command does not generate any output using the `doesntExpectOutput` method:
+
+```php tab=Pest
+test('console command', function () {
+ $this->artisan('example')
+ ->doesntExpectOutput()
+ ->assertExitCode(0);
+});
+```
+
+```php tab=PHPUnit
+/**
+ * Test a console command.
+ */
+public function test_console_command(): void
+{
+ $this->artisan('example')
+ ->doesntExpectOutput()
+ ->assertExitCode(0);
+}
+```
+
+The `expectsOutputToContain` and `doesntExpectOutputToContain` methods may be used to make assertions against a portion of the output:
+
+```php tab=Pest
+test('console command', function () {
+ $this->artisan('example')
+ ->expectsOutputToContain('Taylor')
+ ->assertExitCode(0);
+});
+```
+
+```php tab=PHPUnit
+/**
+ * Test a console command.
+ */
+public function test_console_command(): void
+{
+ $this->artisan('example')
+ ->expectsOutputToContain('Taylor')
+ ->assertExitCode(0);
+}
+```
#### Confirmation Expectations
When writing a command which expects confirmation in the form of a "yes" or "no" answer, you may utilize the `expectsConfirmation` method:
- $this->artisan('module:import')
- ->expectsConfirmation('Do you really wish to run this command?', 'no')
- ->assertExitCode(1);
+```php
+$this->artisan('module:import')
+ ->expectsConfirmation('Do you really wish to run this command?', 'no')
+ ->assertExitCode(1);
+```
#### Table Expectations
If your command displays a table of information using Artisan's `table` method, it can be cumbersome to write output expectations for the entire table. Instead, you may use the `expectsTable` method. This method accepts the table's headers as its first argument and the table's data as its second argument:
- $this->artisan('users:all')
- ->expectsTable([
- 'ID',
- 'Email',
- ], [
- [1, 'taylor@example.com'],
- [2, 'abigail@example.com'],
- ]);
+```php
+$this->artisan('users:all')
+ ->expectsTable([
+ 'ID',
+ 'Email',
+ ], [
+ [1, 'taylor@example.com'],
+ [2, 'abigail@example.com'],
+ ]);
+```
+
+
+## Console Events
+
+By default, the `Illuminate\Console\Events\CommandStarting` and `Illuminate\Console\Events\CommandFinished` events are not dispatched while running your application's tests. However, you can enable these events for a given test class by adding the `Illuminate\Foundation\Testing\WithConsoleEvents` trait to the class:
+
+```php tab=Pest
+use(WithConsoleEvents::class);
+
+// ...
+```
+
+```php tab=PHPUnit
+
@@ -25,49 +27,36 @@ The Laravel service container is a powerful tool for managing class dependencies
Let's look at a simple example:
- users = $users;
- }
-
- /**
- * Show the profile for the given user.
- *
- * @param int $id
- * @return Response
- */
- public function show($id)
- {
- $user = $this->users->find($id);
-
- return view('user.profile', ['user' => $user]);
- }
+ return view('podcasts.show', [
+ 'podcast' => $this->apple->findPodcast($id)
+ ]);
}
+}
+```
-In this example, the `UserController` needs to retrieve users from a data source. So, we will **inject** a service that is able to retrieve users. In this context, our `UserRepository` most likely uses [Eloquent](/docs/{{version}}/eloquent) to retrieve user information from the database. However, since the repository is injected, we are able to easily swap it out with another implementation. We are also able to easily "mock", or create a dummy implementation of the `UserRepository` when testing our application.
+In this example, the `PodcastController` needs to retrieve podcasts from a data source such as Apple Music. So, we will **inject** a service that is able to retrieve podcasts. Since the service is injected, we are able to easily "mock", or create a dummy implementation of the `AppleMusic` service when testing our application.
A deep understanding of the Laravel service container is essential to building a powerful, large application, as well as for contributing to the Laravel core itself.
@@ -76,31 +65,35 @@ A deep understanding of the Laravel service container is essential to building a
If a class has no dependencies or only depends on other concrete classes (not interfaces), the container does not need to be instructed on how to resolve that class. For example, you may place the following code in your `routes/web.php` file:
-
-### When To Use The Container
+### When to Utilize the Container
Thanks to zero configuration resolution, you will often type-hint dependencies on routes, controllers, event listeners, and elsewhere without ever manually interacting with the container. For example, you might type-hint the `Illuminate\Http\Request` object on your route definition so that you can easily access the current request. Even though we never have to interact with the container to write this code, it is managing the injection of these dependencies behind the scenes:
- use Illuminate\Http\Request;
+```php
+use Illuminate\Http\Request;
- Route::get('/', function (Request $request) {
- // ...
- });
+Route::get('/', function (Request $request) {
+ // ...
+});
+```
In many cases, thanks to automatic dependency injection and [facades](/docs/{{version}}/facades), you can build Laravel applications without **ever** manually binding or resolving anything from the container. **So, when would you ever manually interact with the container?** Let's examine two situations.
@@ -119,231 +112,486 @@ Almost all of your service container bindings will be registered within [service
Within a service provider, you always have access to the container via the `$this->app` property. We can register a binding using the `bind` method, passing the class or interface name that we wish to register along with a closure that returns an instance of the class:
- use App\Services\Transistor;
- use App\Services\PodcastParser;
+```php
+use App\Services\Transistor;
+use App\Services\PodcastParser;
+use Illuminate\Contracts\Foundation\Application;
- $this->app->bind(Transistor::class, function ($app) {
- return new Transistor($app->make(PodcastParser::class));
- });
+$this->app->bind(Transistor::class, function (Application $app) {
+ return new Transistor($app->make(PodcastParser::class));
+});
+```
Note that we receive the container itself as an argument to the resolver. We can then use the container to resolve sub-dependencies of the object we are building.
As mentioned, you will typically be interacting with the container within service providers; however, if you would like to interact with the container outside of a service provider, you may do so via the `App` [facade](/docs/{{version}}/facades):
- use App\Services\Transistor;
- use Illuminate\Support\Facades\App;
+```php
+use App\Services\Transistor;
+use Illuminate\Contracts\Foundation\Application;
+use Illuminate\Support\Facades\App;
- App::bind(Transistor::class, function ($app) {
- // ...
- });
+App::bind(Transistor::class, function (Application $app) {
+ // ...
+});
+```
+
+You may use the `bindIf` method to register a container binding only if a binding has not already been registered for the given type:
+
+```php
+$this->app->bindIf(Transistor::class, function (Application $app) {
+ return new Transistor($app->make(PodcastParser::class));
+});
+```
-> {tip} There is no need to bind classes into the container if they do not depend on any interfaces. The container does not need to be instructed on how to build these objects, since it can automatically resolve these objects using reflection.
+For convenience, you may omit providing the class or interface name that you wish to register as a separate argument and instead allow Laravel to infer the type from the return type of the closure you provide to the `bind` method:
+
+```php
+App::bind(function (Application $app): Transistor {
+ return new Transistor($app->make(PodcastParser::class));
+});
+```
+
+> [!NOTE]
+> There is no need to bind classes into the container if they do not depend on any interfaces. The container does not need to be instructed on how to build these objects, since it can automatically resolve these objects using reflection.
#### Binding A Singleton
The `singleton` method binds a class or interface into the container that should only be resolved one time. Once a singleton binding is resolved, the same object instance will be returned on subsequent calls into the container:
- use App\Services\Transistor;
- use App\Services\PodcastParser;
+```php
+use App\Services\Transistor;
+use App\Services\PodcastParser;
+use Illuminate\Contracts\Foundation\Application;
- $this->app->singleton(Transistor::class, function ($app) {
- return new Transistor($app->make(PodcastParser::class));
- });
+$this->app->singleton(Transistor::class, function (Application $app) {
+ return new Transistor($app->make(PodcastParser::class));
+});
+```
+
+You may use the `singletonIf` method to register a singleton container binding only if a binding has not already been registered for the given type:
+
+```php
+$this->app->singletonIf(Transistor::class, function (Application $app) {
+ return new Transistor($app->make(PodcastParser::class));
+});
+```
+
+
+#### Singleton Attribute
+
+Alternatively, you may mark an interface or class with the `#[Singleton]` attribute to indicate to the container that it should be resolved one time:
+
+```php
+
#### Binding Scoped Singletons
The `scoped` method binds a class or interface into the container that should only be resolved one time within a given Laravel request / job lifecycle. While this method is similar to the `singleton` method, instances registered using the `scoped` method will be flushed whenever the Laravel application starts a new "lifecycle", such as when a [Laravel Octane](/docs/{{version}}/octane) worker processes a new request or when a Laravel [queue worker](/docs/{{version}}/queues) processes a new job:
- use App\Services\Transistor;
- use App\Services\PodcastParser;
+```php
+use App\Services\Transistor;
+use App\Services\PodcastParser;
+use Illuminate\Contracts\Foundation\Application;
- $this->app->scoped(Transistor::class, function ($app) {
- return new Transistor($app->make(PodcastParser::class));
- });
+$this->app->scoped(Transistor::class, function (Application $app) {
+ return new Transistor($app->make(PodcastParser::class));
+});
+```
+
+You may use the `scopedIf` method to register a scoped container binding only if a binding has not already been registered for the given type:
+
+```php
+$this->app->scopedIf(Transistor::class, function (Application $app) {
+ return new Transistor($app->make(PodcastParser::class));
+});
+```
+
+
+#### Scoped Attribute
+
+Alternatively, you may mark an interface or class with the `#[Scoped]` attribute to indicate to the container that it should be resolved one time within a given Laravel request / job lifecycle:
+
+```php
+
#### Binding Instances
You may also bind an existing object instance into the container using the `instance` method. The given instance will always be returned on subsequent calls into the container:
- use App\Services\Transistor;
- use App\Services\PodcastParser;
+```php
+use App\Services\Transistor;
+use App\Services\PodcastParser;
- $service = new Transistor(new PodcastParser);
+$service = new Transistor(new PodcastParser);
- $this->app->instance(Transistor::class, $service);
+$this->app->instance(Transistor::class, $service);
+```
-### Binding Interfaces To Implementations
+### Binding Interfaces to Implementations
A very powerful feature of the service container is its ability to bind an interface to a given implementation. For example, let's assume we have an `EventPusher` interface and a `RedisEventPusher` implementation. Once we have coded our `RedisEventPusher` implementation of this interface, we can register it with the service container like so:
- use App\Contracts\EventPusher;
- use App\Services\RedisEventPusher;
+```php
+use App\Contracts\EventPusher;
+use App\Services\RedisEventPusher;
- $this->app->bind(EventPusher::class, RedisEventPusher::class);
+$this->app->bind(EventPusher::class, RedisEventPusher::class);
+```
This statement tells the container that it should inject the `RedisEventPusher` when a class needs an implementation of `EventPusher`. Now we can type-hint the `EventPusher` interface in the constructor of a class that is resolved by the container. Remember, controllers, event listeners, middleware, and various other types of classes within Laravel applications are always resolved using the container:
- use App\Contracts\EventPusher;
+```php
+use App\Contracts\EventPusher;
- /**
- * Create a new class instance.
- *
- * @param \App\Contracts\EventPusher $pusher
- * @return void
- */
- public function __construct(EventPusher $pusher)
- {
- $this->pusher = $pusher;
- }
+/**
+ * Create a new class instance.
+ */
+public function __construct(
+ protected EventPusher $pusher,
+) {}
+```
+
+
+#### Bind Attribute
+
+Laravel also provides a `Bind` attribute for added convenience. You can apply this attribute to any interface to tell Laravel which implementation should be automatically injected whenever that interface is requested. When using the `Bind` attribute, there is no need to perform any additional service registration in your application's service providers.
+
+In addition, multiple `Bind` attributes may be placed on an interface in order to configure a different implementation that should be injected for a given set of environments:
+
+```php
+
### Contextual Binding
Sometimes you may have two classes that utilize the same interface, but you wish to inject different implementations into each class. For example, two controllers may depend on different implementations of the `Illuminate\Contracts\Filesystem\Filesystem` [contract](/docs/{{version}}/contracts). Laravel provides a simple, fluent interface for defining this behavior:
- use App\Http\Controllers\PhotoController;
- use App\Http\Controllers\UploadController;
- use App\Http\Controllers\VideoController;
- use Illuminate\Contracts\Filesystem\Filesystem;
- use Illuminate\Support\Facades\Storage;
+```php
+use App\Http\Controllers\PhotoController;
+use App\Http\Controllers\UploadController;
+use App\Http\Controllers\VideoController;
+use Illuminate\Contracts\Filesystem\Filesystem;
+use Illuminate\Support\Facades\Storage;
+
+$this->app->when(PhotoController::class)
+ ->needs(Filesystem::class)
+ ->give(function () {
+ return Storage::disk('local');
+ });
+
+$this->app->when([VideoController::class, UploadController::class])
+ ->needs(Filesystem::class)
+ ->give(function () {
+ return Storage::disk('s3');
+ });
+```
+
+
+### Contextual Attributes
+
+Since contextual binding is often used to inject implementations of drivers or configuration values, Laravel offers a variety of contextual binding attributes that allow to inject these types of values without manually defining the contextual bindings in your service providers.
+
+For example, the `Storage` attribute may be used to inject a specific [storage disk](/docs/{{version}}/filesystem):
+
+```php
+middleware('auth');
+```
+
+
+#### Defining Custom Attributes
+
+You can create your own contextual attributes by implementing the `Illuminate\Contracts\Container\ContextualAttribute` contract. The container will call your attribute's `resolve` method, which should resolve the value that should be injected into the class utilizing the attribute. In the example below, we will re-implement Laravel's built-in `Config` attribute:
+
+```php
+app->when(PhotoController::class)
- ->needs(Filesystem::class)
- ->give(function () {
- return Storage::disk('local');
- });
+namespace App\Attributes;
- $this->app->when([VideoController::class, UploadController::class])
- ->needs(Filesystem::class)
- ->give(function () {
- return Storage::disk('s3');
- });
+use Attribute;
+use Illuminate\Contracts\Container\Container;
+use Illuminate\Contracts\Container\ContextualAttribute;
+
+#[Attribute(Attribute::TARGET_PARAMETER)]
+class Config implements ContextualAttribute
+{
+ /**
+ * Create a new attribute instance.
+ */
+ public function __construct(public string $key, public mixed $default = null)
+ {
+ }
+
+ /**
+ * Resolve the configuration value.
+ *
+ * @param self $attribute
+ * @param \Illuminate\Contracts\Container\Container $container
+ * @return mixed
+ */
+ public static function resolve(self $attribute, Container $container)
+ {
+ return $container->make('config')->get($attribute->key, $attribute->default);
+ }
+}
+```
### Binding Primitives
Sometimes you may have a class that receives some injected classes, but also needs an injected primitive value such as an integer. You may easily use contextual binding to inject any value your class may need:
- $this->app->when('App\Http\Controllers\UserController')
- ->needs('$variableName')
- ->give($value);
+```php
+use App\Http\Controllers\UserController;
+
+$this->app->when(UserController::class)
+ ->needs('$variableName')
+ ->give($value);
+```
Sometimes a class may depend on an array of [tagged](#tagging) instances. Using the `giveTagged` method, you may easily inject all of the container bindings with that tag:
- $this->app->when(ReportAggregator::class)
- ->needs('$reports')
- ->giveTagged('reports');
+```php
+$this->app->when(ReportAggregator::class)
+ ->needs('$reports')
+ ->giveTagged('reports');
+```
If you need to inject a value from one of your application's configuration files, you may use the `giveConfig` method:
- $this->app->when(ReportAggregator::class)
- ->needs('$timezone')
- ->giveConfig('app.timezone');
+```php
+$this->app->when(ReportAggregator::class)
+ ->needs('$timezone')
+ ->giveConfig('app.timezone');
+```
### Binding Typed Variadics
Occasionally, you may have a class that receives an array of typed objects using a variadic constructor argument:
- logger = $logger;
- $this->filters = $filters;
- }
+class Firewall
+{
+ /**
+ * The filter instances.
+ *
+ * @var array
+ */
+ protected $filters;
+
+ /**
+ * Create a new class instance.
+ */
+ public function __construct(
+ protected Logger $logger,
+ Filter ...$filters,
+ ) {
+ $this->filters = $filters;
}
+}
+```
Using contextual binding, you may resolve this dependency by providing the `give` method with a closure that returns an array of resolved `Filter` instances:
- $this->app->when(Firewall::class)
- ->needs(Filter::class)
- ->give(function ($app) {
- return [
- $app->make(NullFilter::class),
- $app->make(ProfanityFilter::class),
- $app->make(TooLongFilter::class),
- ];
- });
+```php
+$this->app->when(Firewall::class)
+ ->needs(Filter::class)
+ ->give(function (Application $app) {
+ return [
+ $app->make(NullFilter::class),
+ $app->make(ProfanityFilter::class),
+ $app->make(TooLongFilter::class),
+ ];
+ });
+```
For convenience, you may also just provide an array of class names to be resolved by the container whenever `Firewall` needs `Filter` instances:
- $this->app->when(Firewall::class)
- ->needs(Filter::class)
- ->give([
- NullFilter::class,
- ProfanityFilter::class,
- TooLongFilter::class,
- ]);
+```php
+$this->app->when(Firewall::class)
+ ->needs(Filter::class)
+ ->give([
+ NullFilter::class,
+ ProfanityFilter::class,
+ TooLongFilter::class,
+ ]);
+```
#### Variadic Tag Dependencies
Sometimes a class may have a variadic dependency that is type-hinted as a given class (`Report ...$reports`). Using the `needs` and `giveTagged` methods, you may easily inject all of the container bindings with that [tag](#tagging) for the given dependency:
- $this->app->when(ReportAggregator::class)
- ->needs(Report::class)
- ->giveTagged('reports');
+```php
+$this->app->when(ReportAggregator::class)
+ ->needs(Report::class)
+ ->giveTagged('reports');
+```
### Tagging
Occasionally, you may need to resolve all of a certain "category" of binding. For example, perhaps you are building a report analyzer that receives an array of many different `Report` interface implementations. After registering the `Report` implementations, you can assign them a tag using the `tag` method:
- $this->app->bind(CpuReport::class, function () {
- //
- });
+```php
+$this->app->bind(CpuReport::class, function () {
+ // ...
+});
- $this->app->bind(MemoryReport::class, function () {
- //
- });
+$this->app->bind(MemoryReport::class, function () {
+ // ...
+});
- $this->app->tag([CpuReport::class, MemoryReport::class], 'reports');
+$this->app->tag([CpuReport::class, MemoryReport::class], 'reports');
+```
Once the services have been tagged, you may easily resolve them all via the container's `tagged` method:
- $this->app->bind(ReportAnalyzer::class, function ($app) {
- return new ReportAnalyzer($app->tagged('reports'));
- });
+```php
+$this->app->bind(ReportAnalyzer::class, function (Application $app) {
+ return new ReportAnalyzer($app->tagged('reports'));
+});
+```
### Extending Bindings
-The `extend` method allows the modification of resolved services. For example, when a service is resolved, you may run additional code to decorate or configure the service. The `extend` method accepts a closure, which should return the modified service, as its only argument. The closure receives the service being resolved and the container instance:
+The `extend` method allows the modification of resolved services. For example, when a service is resolved, you may run additional code to decorate or configure the service. The `extend` method accepts two arguments, the service class you're extending and a closure that should return the modified service. The closure receives the service being resolved and the container instance:
- $this->app->extend(Service::class, function ($service, $app) {
- return new DecoratedService($service);
- });
+```php
+$this->app->extend(Service::class, function (Service $service, Application $app) {
+ return new DecoratedService($service);
+});
+```
## Resolving
@@ -353,153 +601,189 @@ The `extend` method allows the modification of resolved services. For example, w
You may use the `make` method to resolve a class instance from the container. The `make` method accepts the name of the class or interface you wish to resolve:
- use App\Services\Transistor;
+```php
+use App\Services\Transistor;
- $transistor = $this->app->make(Transistor::class);
+$transistor = $this->app->make(Transistor::class);
+```
-If some of your class' dependencies are not resolvable via the container, you may inject them by passing them as an associative array into the `makeWith` method. For example, we may manually pass the `$id` constructor argument required by the `Transistor` service:
+If some of your class's dependencies are not resolvable via the container, you may inject them by passing them as an associative array into the `makeWith` method. For example, we may manually pass the `$id` constructor argument required by the `Transistor` service:
- use App\Services\Transistor;
+```php
+use App\Services\Transistor;
- $transistor = $this->app->makeWith(Transistor::class, ['id' => 1]);
+$transistor = $this->app->makeWith(Transistor::class, ['id' => 1]);
+```
-If you are outside of a service provider in a location of your code that does not have access to the `$app` variable, you may use the `App` [facade](/docs/{{version}}/facades) to resolve a class instance from the container:
+The `bound` method may be used to determine if a class or interface has been explicitly bound in the container:
- use App\Services\Transistor;
- use Illuminate\Support\Facades\App;
+```php
+if ($this->app->bound(Transistor::class)) {
+ // ...
+}
+```
- $transistor = App::make(Transistor::class);
+If you are outside of a service provider in a location of your code that does not have access to the `$app` variable, you may use the `App` [facade](/docs/{{version}}/facades) or the `app` [helper](/docs/{{version}}/helpers#method-app) to resolve a class instance from the container:
-If you would like to have the Laravel container instance itself injected into a class that is being resolved by the container, you may type-hint the `Illuminate\Container\Container` class on your class' constructor:
+```php
+use App\Services\Transistor;
+use Illuminate\Support\Facades\App;
- use Illuminate\Container\Container;
+$transistor = App::make(Transistor::class);
- /**
- * Create a new class instance.
- *
- * @param \Illuminate\Container\Container $container
- * @return void
- */
- public function __construct(Container $container)
- {
- $this->container = $container;
- }
+$transistor = app(Transistor::class);
+```
+
+If you would like to have the Laravel container instance itself injected into a class that is being resolved by the container, you may type-hint the `Illuminate\Container\Container` class on your class's constructor:
+
+```php
+use Illuminate\Container\Container;
+
+/**
+ * Create a new class instance.
+ */
+public function __construct(
+ protected Container $container,
+) {}
+```
### Automatic Injection
Alternatively, and importantly, you may type-hint the dependency in the constructor of a class that is resolved by the container, including [controllers](/docs/{{version}}/controllers), [event listeners](/docs/{{version}}/events), [middleware](/docs/{{version}}/middleware), and more. Additionally, you may type-hint dependencies in the `handle` method of [queued jobs](/docs/{{version}}/queues). In practice, this is how most of your objects should be resolved by the container.
-For example, you may type-hint a repository defined by your application in a controller's constructor. The repository will automatically be resolved and injected into the class:
+For example, you may type-hint a service defined by your application in a controller's constructor. The service will automatically be resolved and injected into the class:
- users = $users;
- }
-
- /**
- * Show the user with the given ID.
- *
- * @param int $id
- * @return \Illuminate\Http\Response
- */
- public function show($id)
- {
- //
- }
+ return $this->apple->findPodcast($id);
}
+}
+```
-## Method Invocation & Injection
+## Method Invocation and Injection
Sometimes you may wish to invoke a method on an object instance while allowing the container to automatically inject that method's dependencies. For example, given the following class:
-
## Container Events
The service container fires an event each time it resolves an object. You may listen to this event using the `resolving` method:
- use App\Services\Transistor;
+```php
+use App\Services\Transistor;
+use Illuminate\Contracts\Foundation\Application;
- $this->app->resolving(Transistor::class, function ($transistor, $app) {
- // Called when container resolves objects of type "Transistor"...
- });
+$this->app->resolving(Transistor::class, function (Transistor $transistor, Application $app) {
+ // Called when container resolves objects of type "Transistor"...
+});
- $this->app->resolving(function ($object, $app) {
- // Called when container resolves object of any type...
- });
+$this->app->resolving(function (mixed $object, Application $app) {
+ // Called when container resolves object of any type...
+});
+```
As you can see, the object being resolved will be passed to the callback, allowing you to set any additional properties on the object before it is given to its consumer.
+
+### Rebinding
+
+The `rebinding` method allows you to listen for when a service is re-bound to the container, meaning it is registered again or overridden after its initial binding. This can be useful when you need to update dependencies or modify behavior each time a specific binding is updated:
+
+```php
+use App\Contracts\PodcastPublisher;
+use App\Services\SpotifyPublisher;
+use App\Services\TransistorPublisher;
+use Illuminate\Contracts\Foundation\Application;
+
+$this->app->bind(PodcastPublisher::class, SpotifyPublisher::class);
+
+$this->app->rebinding(
+ PodcastPublisher::class,
+ function (Application $app, PodcastPublisher $newInstance) {
+ //
+ },
+);
+
+// New binding will trigger rebinding closure...
+$this->app->bind(PodcastPublisher::class, TransistorPublisher::class);
+```
+
## PSR-11
Laravel's service container implements the [PSR-11](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-11-container.md) interface. Therefore, you may type-hint the PSR-11 container interface to obtain an instance of the Laravel container:
- use App\Services\Transistor;
- use Psr\Container\ContainerInterface;
+```php
+use App\Services\Transistor;
+use Psr\Container\ContainerInterface;
- Route::get('/', function (ContainerInterface $container) {
- $service = $container->get(Transistor::class);
+Route::get('/', function (ContainerInterface $container) {
+ $service = $container->get(Transistor::class);
- //
- });
+ // ...
+});
+```
An exception is thrown if the given identifier can't be resolved. The exception will be an instance of `Psr\Container\NotFoundExceptionInterface` if the identifier was never bound. If the identifier was bound but was unable to be resolved, an instance of `Psr\Container\ContainerExceptionInterface` will be thrown.
diff --git a/context.md b/context.md
new file mode 100644
index 00000000000..4ccf8c03576
--- /dev/null
+++ b/context.md
@@ -0,0 +1,453 @@
+# Context
+
+- [Introduction](#introduction)
+ - [How it Works](#how-it-works)
+- [Capturing Context](#capturing-context)
+ - [Stacks](#stacks)
+- [Retrieving Context](#retrieving-context)
+ - [Determining Item Existence](#determining-item-existence)
+- [Removing Context](#removing-context)
+- [Hidden Context](#hidden-context)
+- [Events](#events)
+ - [Dehydrating](#dehydrating)
+ - [Hydrated](#hydrated)
+
+
+## Introduction
+
+Laravel's "context" capabilities enable you to capture, retrieve, and share information throughout requests, jobs, and commands executing within your application. This captured information is also included in logs written by your application, giving you deeper insight into the surrounding code execution history that occurred before a log entry was written and allowing you to trace execution flows throughout a distributed system.
+
+
+### How it Works
+
+The best way to understand Laravel's context capabilities is to see it in action using the built-in logging features. To get started, you may [add information to the context](#capturing-context) using the `Context` facade. In this example, we will use a [middleware](/docs/{{version}}/middleware) to add the request URL and a unique trace ID to the context on every incoming request:
+
+```php
+url());
+ Context::add('trace_id', Str::uuid()->toString());
+
+ return $next($request);
+ }
+}
+```
+
+Information added to the context is automatically appended as metadata to any [log entries](/docs/{{version}}/logging) that are written throughout the request. Appending context as metadata allows information passed to individual log entries to be differentiated from the information shared via `Context`. For example, imagine we write the following log entry:
+
+```php
+Log::info('User authenticated.', ['auth_id' => Auth::id()]);
+```
+
+The written log will contain the `auth_id` passed to the log entry, but it will also contain the context's `url` and `trace_id` as metadata:
+
+```text
+User authenticated. {"auth_id":27} {"url":"https://example.com/login","trace_id":"e04e1a11-e75c-4db3-b5b5-cfef4ef56697"}
+```
+
+Information added to the context is also made available to jobs dispatched to the queue. For example, imagine we dispatch a `ProcessPodcast` job to the queue after adding some information to the context:
+
+```php
+// In our middleware...
+Context::add('url', $request->url());
+Context::add('trace_id', Str::uuid()->toString());
+
+// In our controller...
+ProcessPodcast::dispatch($podcast);
+```
+
+When the job is dispatched, any information currently stored in the context is captured and shared with the job. The captured information is then hydrated back into the current context while the job is executing. So, if our job's handle method was to write to the log:
+
+```php
+class ProcessPodcast implements ShouldQueue
+{
+ use Queueable;
+
+ // ...
+
+ /**
+ * Execute the job.
+ */
+ public function handle(): void
+ {
+ Log::info('Processing podcast.', [
+ 'podcast_id' => $this->podcast->id,
+ ]);
+
+ // ...
+ }
+}
+```
+
+The resulting log entry would contain the information that was added to the context during the request that originally dispatched the job:
+
+```text
+Processing podcast. {"podcast_id":95} {"url":"https://example.com/login","trace_id":"e04e1a11-e75c-4db3-b5b5-cfef4ef56697"}
+```
+
+Although we have focused on the built-in logging related features of Laravel's context, the following documentation will illustrate how context allows you to share information across the HTTP request / queued job boundary and even how to add [hidden context data](#hidden-context) that is not written with log entries.
+
+
+## Capturing Context
+
+You may store information in the current context using the `Context` facade's `add` method:
+
+```php
+use Illuminate\Support\Facades\Context;
+
+Context::add('key', 'value');
+```
+
+To add multiple items at once, you may pass an associative array to the `add` method:
+
+```php
+Context::add([
+ 'first_key' => 'value',
+ 'second_key' => 'value',
+]);
+```
+
+The `add` method will override any existing value that shares the same key. If you only wish to add information to the context if the key does not already exist, you may use the `addIf` method:
+
+```php
+Context::add('key', 'first');
+
+Context::get('key');
+// "first"
+
+Context::addIf('key', 'second');
+
+Context::get('key');
+// "first"
+```
+
+Context also provides convenient methods for incrementing or decrementing a given key. Both of these methods accept at least one argument: the key to track. A second argument may be provided to specify the amount by which the key should be incremented or decremented:
+
+```php
+Context::increment('records_added');
+Context::increment('records_added', 5);
+
+Context::decrement('records_added');
+Context::decrement('records_added', 5);
+```
+
+
+#### Conditional Context
+
+The `when` method may be used to add data to the context based on a given condition. The first closure provided to the `when` method will be invoked if the given condition evaluates to `true`, while the second closure will be invoked if the condition evaluates to `false`:
+
+```php
+use Illuminate\Support\Facades\Auth;
+use Illuminate\Support\Facades\Context;
+
+Context::when(
+ Auth::user()->isAdmin(),
+ fn ($context) => $context->add('permissions', Auth::user()->permissions),
+ fn ($context) => $context->add('permissions', []),
+);
+```
+
+
+#### Scoped Context
+
+The `scope` method provides a way to temporarily modify the context during the execution of a given callback and restore the context to its original state when the callback finishes executing. Additionally, you can pass extra data that should be merged into the context (as the second and third arguments) while the closure executes.
+
+```php
+use Illuminate\Support\Facades\Context;
+use Illuminate\Support\Facades\Log;
+
+Context::add('trace_id', 'abc-999');
+Context::addHidden('user_id', 123);
+
+Context::scope(
+ function () {
+ Context::add('action', 'adding_friend');
+
+ $userId = Context::getHidden('user_id');
+
+ Log::debug("Adding user [{$userId}] to friends list.");
+ // Adding user [987] to friends list. {"trace_id":"abc-999","user_name":"taylor_otwell","action":"adding_friend"}
+ },
+ data: ['user_name' => 'taylor_otwell'],
+ hidden: ['user_id' => 987],
+);
+
+Context::all();
+// [
+// 'trace_id' => 'abc-999',
+// ]
+
+Context::allHidden();
+// [
+// 'user_id' => 123,
+// ]
+```
+
+> [!WARNING]
+> If an object within the context is modified inside the scoped closure, that mutation will be reflected outside of the scope.
+
+
+### Stacks
+
+Context offers the ability to create "stacks", which are lists of data stored in the order that they were added. You can add information to a stack by invoking the `push` method:
+
+```php
+use Illuminate\Support\Facades\Context;
+
+Context::push('breadcrumbs', 'first_value');
+
+Context::push('breadcrumbs', 'second_value', 'third_value');
+
+Context::get('breadcrumbs');
+// [
+// 'first_value',
+// 'second_value',
+// 'third_value',
+// ]
+```
+
+Stacks can be useful to capture historical information about a request, such as events that are happening throughout your application. For example, you could create an event listener to push to a stack every time a query is executed, capturing the query SQL and duration as a tuple:
+
+```php
+use Illuminate\Support\Facades\Context;
+use Illuminate\Support\Facades\DB;
+
+// In AppServiceProvider.php...
+DB::listen(function ($event) {
+ Context::push('queries', [$event->time, $event->sql]);
+});
+```
+
+You may determine if a value is in a stack using the `stackContains` and `hiddenStackContains` methods:
+
+```php
+if (Context::stackContains('breadcrumbs', 'first_value')) {
+ //
+}
+
+if (Context::hiddenStackContains('secrets', 'first_value')) {
+ //
+}
+```
+
+The `stackContains` and `hiddenStackContains` methods also accept a closure as their second argument, allowing more control over the value comparison operation:
+
+```php
+use Illuminate\Support\Facades\Context;
+use Illuminate\Support\Str;
+
+return Context::stackContains('breadcrumbs', function ($value) {
+ return Str::startsWith($value, 'query_');
+});
+```
+
+
+## Retrieving Context
+
+You may retrieve information from the context using the `Context` facade's `get` method:
+
+```php
+use Illuminate\Support\Facades\Context;
+
+$value = Context::get('key');
+```
+
+The `only` and `except` methods may be used to retrieve a subset of the information in the context:
+
+```php
+$data = Context::only(['first_key', 'second_key']);
+
+$data = Context::except(['first_key']);
+```
+
+The `pull` method may be used to retrieve information from the context and immediately remove it from the context:
+
+```php
+$value = Context::pull('key');
+```
+
+If context data is stored in a [stack](#stacks), you may pop items from the stack using the `pop` method:
+
+```php
+Context::push('breadcrumbs', 'first_value', 'second_value');
+
+Context::pop('breadcrumbs');
+// second_value
+
+Context::get('breadcrumbs');
+// ['first_value']
+```
+
+The `remember` and `rememberHidden` methods may be used to retrieve information from the context, while setting the context value to the value returned by the given closure if the requested information doesn't exist:
+
+```php
+$permissions = Context::remember(
+ 'user-permissions',
+ fn () => $user->permissions,
+);
+```
+
+If you would like to retrieve all of the information stored in the context, you may invoke the `all` method:
+
+```php
+$data = Context::all();
+```
+
+
+### Determining Item Existence
+
+You may use the `has` and `missing` methods to determine if the context has any value stored for the given key:
+
+```php
+use Illuminate\Support\Facades\Context;
+
+if (Context::has('key')) {
+ // ...
+}
+
+if (Context::missing('key')) {
+ // ...
+}
+```
+
+The `has` method will return `true` regardless of the value stored. So, for example, a key with a `null` value will be considered present:
+
+```php
+Context::add('key', null);
+
+Context::has('key');
+// true
+```
+
+
+## Removing Context
+
+The `forget` method may be used to remove a key and its value from the current context:
+
+```php
+use Illuminate\Support\Facades\Context;
+
+Context::add(['first_key' => 1, 'second_key' => 2]);
+
+Context::forget('first_key');
+
+Context::all();
+
+// ['second_key' => 2]
+```
+
+You may forget several keys at once by providing an array to the `forget` method:
+
+```php
+Context::forget(['first_key', 'second_key']);
+```
+
+
+## Hidden Context
+
+Context offers the ability to store "hidden" data. This hidden information is not appended to logs, and is not accessible via the data retrieval methods documented above. Context provides a different set of methods to interact with hidden context information:
+
+```php
+use Illuminate\Support\Facades\Context;
+
+Context::addHidden('key', 'value');
+
+Context::getHidden('key');
+// 'value'
+
+Context::get('key');
+// null
+```
+
+The "hidden" methods mirror the functionality of the non-hidden methods documented above:
+
+```php
+Context::addHidden(/* ... */);
+Context::addHiddenIf(/* ... */);
+Context::pushHidden(/* ... */);
+Context::getHidden(/* ... */);
+Context::pullHidden(/* ... */);
+Context::popHidden(/* ... */);
+Context::onlyHidden(/* ... */);
+Context::exceptHidden(/* ... */);
+Context::allHidden(/* ... */);
+Context::hasHidden(/* ... */);
+Context::missingHidden(/* ... */);
+Context::forgetHidden(/* ... */);
+```
+
+
+## Events
+
+Context dispatches two events that allow you to hook into the hydration and dehydration process of the context.
+
+To illustrate how these events may be used, imagine that in a middleware of your application you set the `app.locale` configuration value based on the incoming HTTP request's `Accept-Language` header. Context's events allow you to capture this value during the request and restore it on the queue, ensuring notifications sent on the queue have the correct `app.locale` value. We can use context's events and [hidden](#hidden-context) data to achieve this, which the following documentation will illustrate.
+
+
+### Dehydrating
+
+Whenever a job is dispatched to the queue the data in the context is "dehydrated" and captured alongside the job's payload. The `Context::dehydrating` method allows you to register a closure that will be invoked during the dehydration process. Within this closure, you may make changes to the data that will be shared with the queued job.
+
+Typically, you should register `dehydrating` callbacks within the `boot` method of your application's `AppServiceProvider` class:
+
+```php
+use Illuminate\Log\Context\Repository;
+use Illuminate\Support\Facades\Config;
+use Illuminate\Support\Facades\Context;
+
+/**
+ * Bootstrap any application services.
+ */
+public function boot(): void
+{
+ Context::dehydrating(function (Repository $context) {
+ $context->addHidden('locale', Config::get('app.locale'));
+ });
+}
+```
+
+> [!NOTE]
+> You should not use the `Context` facade within the `dehydrating` callback, as that will change the context of the current process. Ensure you only make changes to the repository passed to the callback.
+
+
+### Hydrated
+
+Whenever a queued job begins executing on the queue, any context that was shared with the job will be "hydrated" back into the current context. The `Context::hydrated` method allows you to register a closure that will be invoked during the hydration process.
+
+Typically, you should register `hydrated` callbacks within the `boot` method of your application's `AppServiceProvider` class:
+
+```php
+use Illuminate\Log\Context\Repository;
+use Illuminate\Support\Facades\Config;
+use Illuminate\Support\Facades\Context;
+
+/**
+ * Bootstrap any application services.
+ */
+public function boot(): void
+{
+ Context::hydrated(function (Repository $context) {
+ if ($context->hasHidden('locale')) {
+ Config::set('app.locale', $context->getHidden('locale'));
+ }
+ });
+}
+```
+
+> [!NOTE]
+> You should not use the `Context` facade within the `hydrated` callback and instead ensure you only make changes to the repository passed to the callback.
diff --git a/contracts.md b/contracts.md
index 635c7eba54c..f33ad86969a 100644
--- a/contracts.md
+++ b/contracts.md
@@ -1,9 +1,9 @@
# Contracts
- [Introduction](#introduction)
- - [Contracts Vs. Facades](#contracts-vs-facades)
-- [When To Use Contracts](#when-to-use-contracts)
-- [How To Use Contracts](#how-to-use-contracts)
+ - [Contracts vs. Facades](#contracts-vs-facades)
+- [When to Use Contracts](#when-to-use-contracts)
+- [How to Use Contracts](#how-to-use-contracts)
- [Contract Reference](#contract-reference)
@@ -11,26 +11,26 @@
Laravel's "contracts" are a set of interfaces that define the core services provided by the framework. For example, an `Illuminate\Contracts\Queue\Queue` contract defines the methods needed for queueing jobs, while the `Illuminate\Contracts\Mail\Mailer` contract defines the methods needed for sending e-mail.
-Each contract has a corresponding implementation provided by the framework. For example, Laravel provides a queue implementation with a variety of drivers, and a mailer implementation that is powered by [Symfony Mailer](https://symfony.com/doc/6.0/mailer.html).
+Each contract has a corresponding implementation provided by the framework. For example, Laravel provides a queue implementation with a variety of drivers, and a mailer implementation that is powered by [Symfony Mailer](https://symfony.com/doc/current/mailer.html).
All of the Laravel contracts live in [their own GitHub repository](https://github.com/illuminate/contracts). This provides a quick reference point for all available contracts, as well as a single, decoupled package that may be utilized when building packages that interact with Laravel services.
-### Contracts Vs. Facades
+### Contracts vs. Facades
Laravel's [facades](/docs/{{version}}/facades) and helper functions provide a simple way of utilizing Laravel's services without needing to type-hint and resolve contracts out of the service container. In most cases, each facade has an equivalent contract.
Unlike facades, which do not require you to require them in your class' constructor, contracts allow you to define explicit dependencies for your classes. Some developers prefer to explicitly define their dependencies in this way and therefore prefer to use contracts, while other developers enjoy the convenience of facades. **In general, most applications can use facades without issue during development.**
-## When To Use Contracts
+## When to Use Contracts
The decision to use contracts or facades will come down to personal taste and the tastes of your development team. Both contracts and facades can be used to create robust, well-tested Laravel applications. Contracts and facades are not mutually exclusive. Some parts of your applications may use facades while others depend on contracts. As long as you are keeping your class' responsibilities focused, you will notice very few practical differences between using contracts and facades.
In general, most applications can use facades without issue during development. If you are building a package that integrates with multiple PHP frameworks you may wish to use the `illuminate/contracts` package to define your integration with Laravel's services without the need to require Laravel's concrete implementations in your package's `composer.json` file.
-## How To Use Contracts
+## How to Use Contracts
So, how do you get an implementation of a contract? It's actually quite simple.
@@ -38,45 +38,33 @@ Many types of classes in Laravel are resolved through the [service container](/d
For example, take a look at this event listener:
- redis = $redis;
- }
-
- /**
- * Handle the event.
- *
- * @param \App\Events\OrderWasPlaced $event
- * @return void
- */
- public function handle(OrderWasPlaced $event)
- {
- //
- }
+ // ...
}
+}
+```
When the event listener is resolved, the service container will read the type-hints on the constructor of the class, and inject the appropriate value. To learn more about registering things in the service container, check out [its documentation](/docs/{{version}}/container).
@@ -85,84 +73,87 @@ When the event listener is resolved, the service container will read the type-hi
This table provides a quick reference to all of the Laravel contracts and their equivalent facades:
-Contract | References Facade
-------------- | -------------
-[Illuminate\Contracts\Auth\Access\Authorizable](https://github.com/illuminate/contracts/blob/{{version}}/Auth/Access/Authorizable.php) |
-[Illuminate\Contracts\Auth\Access\Gate](https://github.com/illuminate/contracts/blob/{{version}}/Auth/Access/Gate.php) | `Gate`
-[Illuminate\Contracts\Auth\Authenticatable](https://github.com/illuminate/contracts/blob/{{version}}/Auth/Authenticatable.php) |
-[Illuminate\Contracts\Auth\CanResetPassword](https://github.com/illuminate/contracts/blob/{{version}}/Auth/CanResetPassword.php) |
-[Illuminate\Contracts\Auth\Factory](https://github.com/illuminate/contracts/blob/{{version}}/Auth/Factory.php) | `Auth`
-[Illuminate\Contracts\Auth\Guard](https://github.com/illuminate/contracts/blob/{{version}}/Auth/Guard.php) | `Auth::guard()`
-[Illuminate\Contracts\Auth\PasswordBroker](https://github.com/illuminate/contracts/blob/{{version}}/Auth/PasswordBroker.php) | `Password::broker()`
-[Illuminate\Contracts\Auth\PasswordBrokerFactory](https://github.com/illuminate/contracts/blob/{{version}}/Auth/PasswordBrokerFactory.php) | `Password`
-[Illuminate\Contracts\Auth\StatefulGuard](https://github.com/illuminate/contracts/blob/{{version}}/Auth/StatefulGuard.php) |
-[Illuminate\Contracts\Auth\SupportsBasicAuth](https://github.com/illuminate/contracts/blob/{{version}}/Auth/SupportsBasicAuth.php) |
-[Illuminate\Contracts\Auth\UserProvider](https://github.com/illuminate/contracts/blob/{{version}}/Auth/UserProvider.php) |
-[Illuminate\Contracts\Bus\Dispatcher](https://github.com/illuminate/contracts/blob/{{version}}/Bus/Dispatcher.php) | `Bus`
-[Illuminate\Contracts\Bus\QueueingDispatcher](https://github.com/illuminate/contracts/blob/{{version}}/Bus/QueueingDispatcher.php) | `Bus::dispatchToQueue()`
-[Illuminate\Contracts\Broadcasting\Factory](https://github.com/illuminate/contracts/blob/{{version}}/Broadcasting/Factory.php) | `Broadcast`
-[Illuminate\Contracts\Broadcasting\Broadcaster](https://github.com/illuminate/contracts/blob/{{version}}/Broadcasting/Broadcaster.php) | `Broadcast::connection()`
-[Illuminate\Contracts\Broadcasting\ShouldBroadcast](https://github.com/illuminate/contracts/blob/{{version}}/Broadcasting/ShouldBroadcast.php) |
-[Illuminate\Contracts\Broadcasting\ShouldBroadcastNow](https://github.com/illuminate/contracts/blob/{{version}}/Broadcasting/ShouldBroadcastNow.php) |
-[Illuminate\Contracts\Cache\Factory](https://github.com/illuminate/contracts/blob/{{version}}/Cache/Factory.php) | `Cache`
-[Illuminate\Contracts\Cache\Lock](https://github.com/illuminate/contracts/blob/{{version}}/Cache/Lock.php) |
-[Illuminate\Contracts\Cache\LockProvider](https://github.com/illuminate/contracts/blob/{{version}}/Cache/LockProvider.php) |
-[Illuminate\Contracts\Cache\Repository](https://github.com/illuminate/contracts/blob/{{version}}/Cache/Repository.php) | `Cache::driver()`
-[Illuminate\Contracts\Cache\Store](https://github.com/illuminate/contracts/blob/{{version}}/Cache/Store.php) |
-[Illuminate\Contracts\Config\Repository](https://github.com/illuminate/contracts/blob/{{version}}/Config/Repository.php) | `Config`
-[Illuminate\Contracts\Console\Application](https://github.com/illuminate/contracts/blob/{{version}}/Console/Application.php) |
-[Illuminate\Contracts\Console\Kernel](https://github.com/illuminate/contracts/blob/{{version}}/Console/Kernel.php) | `Artisan`
-[Illuminate\Contracts\Container\Container](https://github.com/illuminate/contracts/blob/{{version}}/Container/Container.php) | `App`
-[Illuminate\Contracts\Cookie\Factory](https://github.com/illuminate/contracts/blob/{{version}}/Cookie/Factory.php) | `Cookie`
-[Illuminate\Contracts\Cookie\QueueingFactory](https://github.com/illuminate/contracts/blob/{{version}}/Cookie/QueueingFactory.php) | `Cookie::queue()`
-[Illuminate\Contracts\Database\ModelIdentifier](https://github.com/illuminate/contracts/blob/{{version}}/Database/ModelIdentifier.php) |
-[Illuminate\Contracts\Debug\ExceptionHandler](https://github.com/illuminate/contracts/blob/{{version}}/Debug/ExceptionHandler.php) |
-[Illuminate\Contracts\Encryption\Encrypter](https://github.com/illuminate/contracts/blob/{{version}}/Encryption/Encrypter.php) | `Crypt`
-[Illuminate\Contracts\Events\Dispatcher](https://github.com/illuminate/contracts/blob/{{version}}/Events/Dispatcher.php) | `Event`
-[Illuminate\Contracts\Filesystem\Cloud](https://github.com/illuminate/contracts/blob/{{version}}/Filesystem/Cloud.php) | `Storage::cloud()`
-[Illuminate\Contracts\Filesystem\Factory](https://github.com/illuminate/contracts/blob/{{version}}/Filesystem/Factory.php) | `Storage`
-[Illuminate\Contracts\Filesystem\Filesystem](https://github.com/illuminate/contracts/blob/{{version}}/Filesystem/Filesystem.php) | `Storage::disk()`
-[Illuminate\Contracts\Foundation\Application](https://github.com/illuminate/contracts/blob/{{version}}/Foundation/Application.php) | `App`
-[Illuminate\Contracts\Hashing\Hasher](https://github.com/illuminate/contracts/blob/{{version}}/Hashing/Hasher.php) | `Hash`
-[Illuminate\Contracts\Http\Kernel](https://github.com/illuminate/contracts/blob/{{version}}/Http/Kernel.php) |
-[Illuminate\Contracts\Mail\MailQueue](https://github.com/illuminate/contracts/blob/{{version}}/Mail/MailQueue.php) | `Mail::queue()`
-[Illuminate\Contracts\Mail\Mailable](https://github.com/illuminate/contracts/blob/{{version}}/Mail/Mailable.php) |
-[Illuminate\Contracts\Mail\Mailer](https://github.com/illuminate/contracts/blob/{{version}}/Mail/Mailer.php) | `Mail`
-[Illuminate\Contracts\Notifications\Dispatcher](https://github.com/illuminate/contracts/blob/{{version}}/Notifications/Dispatcher.php) | `Notification`
-[Illuminate\Contracts\Notifications\Factory](https://github.com/illuminate/contracts/blob/{{version}}/Notifications/Factory.php) | `Notification`
-[Illuminate\Contracts\Pagination\LengthAwarePaginator](https://github.com/illuminate/contracts/blob/{{version}}/Pagination/LengthAwarePaginator.php) |
-[Illuminate\Contracts\Pagination\Paginator](https://github.com/illuminate/contracts/blob/{{version}}/Pagination/Paginator.php) |
-[Illuminate\Contracts\Pipeline\Hub](https://github.com/illuminate/contracts/blob/{{version}}/Pipeline/Hub.php) |
-[Illuminate\Contracts\Pipeline\Pipeline](https://github.com/illuminate/contracts/blob/{{version}}/Pipeline/Pipeline.php) |
-[Illuminate\Contracts\Queue\EntityResolver](https://github.com/illuminate/contracts/blob/{{version}}/Queue/EntityResolver.php) |
-[Illuminate\Contracts\Queue\Factory](https://github.com/illuminate/contracts/blob/{{version}}/Queue/Factory.php) | `Queue`
-[Illuminate\Contracts\Queue\Job](https://github.com/illuminate/contracts/blob/{{version}}/Queue/Job.php) |
-[Illuminate\Contracts\Queue\Monitor](https://github.com/illuminate/contracts/blob/{{version}}/Queue/Monitor.php) | `Queue`
-[Illuminate\Contracts\Queue\Queue](https://github.com/illuminate/contracts/blob/{{version}}/Queue/Queue.php) | `Queue::connection()`
-[Illuminate\Contracts\Queue\QueueableCollection](https://github.com/illuminate/contracts/blob/{{version}}/Queue/QueueableCollection.php) |
-[Illuminate\Contracts\Queue\QueueableEntity](https://github.com/illuminate/contracts/blob/{{version}}/Queue/QueueableEntity.php) |
-[Illuminate\Contracts\Queue\ShouldQueue](https://github.com/illuminate/contracts/blob/{{version}}/Queue/ShouldQueue.php) |
-[Illuminate\Contracts\Redis\Factory](https://github.com/illuminate/contracts/blob/{{version}}/Redis/Factory.php) | `Redis`
-[Illuminate\Contracts\Routing\BindingRegistrar](https://github.com/illuminate/contracts/blob/{{version}}/Routing/BindingRegistrar.php) | `Route`
-[Illuminate\Contracts\Routing\Registrar](https://github.com/illuminate/contracts/blob/{{version}}/Routing/Registrar.php) | `Route`
-[Illuminate\Contracts\Routing\ResponseFactory](https://github.com/illuminate/contracts/blob/{{version}}/Routing/ResponseFactory.php) | `Response`
-[Illuminate\Contracts\Routing\UrlGenerator](https://github.com/illuminate/contracts/blob/{{version}}/Routing/UrlGenerator.php) | `URL`
-[Illuminate\Contracts\Routing\UrlRoutable](https://github.com/illuminate/contracts/blob/{{version}}/Routing/UrlRoutable.php) |
-[Illuminate\Contracts\Session\Session](https://github.com/illuminate/contracts/blob/{{version}}/Session/Session.php) | `Session::driver()`
-[Illuminate\Contracts\Support\Arrayable](https://github.com/illuminate/contracts/blob/{{version}}/Support/Arrayable.php) |
-[Illuminate\Contracts\Support\Htmlable](https://github.com/illuminate/contracts/blob/{{version}}/Support/Htmlable.php) |
-[Illuminate\Contracts\Support\Jsonable](https://github.com/illuminate/contracts/blob/{{version}}/Support/Jsonable.php) |
-[Illuminate\Contracts\Support\MessageBag](https://github.com/illuminate/contracts/blob/{{version}}/Support/MessageBag.php) |
-[Illuminate\Contracts\Support\MessageProvider](https://github.com/illuminate/contracts/blob/{{version}}/Support/MessageProvider.php) |
-[Illuminate\Contracts\Support\Renderable](https://github.com/illuminate/contracts/blob/{{version}}/Support/Renderable.php) |
-[Illuminate\Contracts\Support\Responsable](https://github.com/illuminate/contracts/blob/{{version}}/Support/Responsable.php) |
-[Illuminate\Contracts\Translation\Loader](https://github.com/illuminate/contracts/blob/{{version}}/Translation/Loader.php) |
-[Illuminate\Contracts\Translation\Translator](https://github.com/illuminate/contracts/blob/{{version}}/Translation/Translator.php) | `Lang`
-[Illuminate\Contracts\Validation\Factory](https://github.com/illuminate/contracts/blob/{{version}}/Validation/Factory.php) | `Validator`
-[Illuminate\Contracts\Validation\ImplicitRule](https://github.com/illuminate/contracts/blob/{{version}}/Validation/ImplicitRule.php) |
-[Illuminate\Contracts\Validation\Rule](https://github.com/illuminate/contracts/blob/{{version}}/Validation/Rule.php) |
-[Illuminate\Contracts\Validation\ValidatesWhenResolved](https://github.com/illuminate/contracts/blob/{{version}}/Validation/ValidatesWhenResolved.php) |
-[Illuminate\Contracts\Validation\Validator](https://github.com/illuminate/contracts/blob/{{version}}/Validation/Validator.php) | `Validator::make()`
-[Illuminate\Contracts\View\Engine](https://github.com/illuminate/contracts/blob/{{version}}/View/Engine.php) |
-[Illuminate\Contracts\View\Factory](https://github.com/illuminate/contracts/blob/{{version}}/View/Factory.php) | `View`
-[Illuminate\Contracts\View\View](https://github.com/illuminate/contracts/blob/{{version}}/View/View.php) | `View::make()`
+
+
+| Contract | References Facade |
+| --- | --- |
+| [Illuminate\Contracts\Auth\Access\Authorizable](https://github.com/illuminate/contracts/blob/{{version}}/Auth/Access/Authorizable.php) | |
+| [Illuminate\Contracts\Auth\Access\Gate](https://github.com/illuminate/contracts/blob/{{version}}/Auth/Access/Gate.php) | `Gate` |
+| [Illuminate\Contracts\Auth\Authenticatable](https://github.com/illuminate/contracts/blob/{{version}}/Auth/Authenticatable.php) | |
+| [Illuminate\Contracts\Auth\CanResetPassword](https://github.com/illuminate/contracts/blob/{{version}}/Auth/CanResetPassword.php) | |
+| [Illuminate\Contracts\Auth\Factory](https://github.com/illuminate/contracts/blob/{{version}}/Auth/Factory.php) | `Auth` |
+| [Illuminate\Contracts\Auth\Guard](https://github.com/illuminate/contracts/blob/{{version}}/Auth/Guard.php) | `Auth::guard()` |
+| [Illuminate\Contracts\Auth\PasswordBroker](https://github.com/illuminate/contracts/blob/{{version}}/Auth/PasswordBroker.php) | `Password::broker()` |
+| [Illuminate\Contracts\Auth\PasswordBrokerFactory](https://github.com/illuminate/contracts/blob/{{version}}/Auth/PasswordBrokerFactory.php) | `Password` |
+| [Illuminate\Contracts\Auth\StatefulGuard](https://github.com/illuminate/contracts/blob/{{version}}/Auth/StatefulGuard.php) | |
+| [Illuminate\Contracts\Auth\SupportsBasicAuth](https://github.com/illuminate/contracts/blob/{{version}}/Auth/SupportsBasicAuth.php) | |
+| [Illuminate\Contracts\Auth\UserProvider](https://github.com/illuminate/contracts/blob/{{version}}/Auth/UserProvider.php) | |
+| [Illuminate\Contracts\Broadcasting\Broadcaster](https://github.com/illuminate/contracts/blob/{{version}}/Broadcasting/Broadcaster.php) | `Broadcast::connection()` |
+| [Illuminate\Contracts\Broadcasting\Factory](https://github.com/illuminate/contracts/blob/{{version}}/Broadcasting/Factory.php) | `Broadcast` |
+| [Illuminate\Contracts\Broadcasting\ShouldBroadcast](https://github.com/illuminate/contracts/blob/{{version}}/Broadcasting/ShouldBroadcast.php) | |
+| [Illuminate\Contracts\Broadcasting\ShouldBroadcastNow](https://github.com/illuminate/contracts/blob/{{version}}/Broadcasting/ShouldBroadcastNow.php) | |
+| [Illuminate\Contracts\Bus\Dispatcher](https://github.com/illuminate/contracts/blob/{{version}}/Bus/Dispatcher.php) | `Bus` |
+| [Illuminate\Contracts\Bus\QueueingDispatcher](https://github.com/illuminate/contracts/blob/{{version}}/Bus/QueueingDispatcher.php) | `Bus::dispatchToQueue()` |
+| [Illuminate\Contracts\Cache\Factory](https://github.com/illuminate/contracts/blob/{{version}}/Cache/Factory.php) | `Cache` |
+| [Illuminate\Contracts\Cache\Lock](https://github.com/illuminate/contracts/blob/{{version}}/Cache/Lock.php) | |
+| [Illuminate\Contracts\Cache\LockProvider](https://github.com/illuminate/contracts/blob/{{version}}/Cache/LockProvider.php) | |
+| [Illuminate\Contracts\Cache\Repository](https://github.com/illuminate/contracts/blob/{{version}}/Cache/Repository.php) | `Cache::driver()` |
+| [Illuminate\Contracts\Cache\Store](https://github.com/illuminate/contracts/blob/{{version}}/Cache/Store.php) | |
+| [Illuminate\Contracts\Config\Repository](https://github.com/illuminate/contracts/blob/{{version}}/Config/Repository.php) | `Config` |
+| [Illuminate\Contracts\Console\Application](https://github.com/illuminate/contracts/blob/{{version}}/Console/Application.php) | |
+| [Illuminate\Contracts\Console\Kernel](https://github.com/illuminate/contracts/blob/{{version}}/Console/Kernel.php) | `Artisan` |
+| [Illuminate\Contracts\Container\Container](https://github.com/illuminate/contracts/blob/{{version}}/Container/Container.php) | `App` |
+| [Illuminate\Contracts\Cookie\Factory](https://github.com/illuminate/contracts/blob/{{version}}/Cookie/Factory.php) | `Cookie` |
+| [Illuminate\Contracts\Cookie\QueueingFactory](https://github.com/illuminate/contracts/blob/{{version}}/Cookie/QueueingFactory.php) | `Cookie::queue()` |
+| [Illuminate\Contracts\Database\ModelIdentifier](https://github.com/illuminate/contracts/blob/{{version}}/Database/ModelIdentifier.php) | |
+| [Illuminate\Contracts\Debug\ExceptionHandler](https://github.com/illuminate/contracts/blob/{{version}}/Debug/ExceptionHandler.php) | |
+| [Illuminate\Contracts\Encryption\Encrypter](https://github.com/illuminate/contracts/blob/{{version}}/Encryption/Encrypter.php) | `Crypt` |
+| [Illuminate\Contracts\Events\Dispatcher](https://github.com/illuminate/contracts/blob/{{version}}/Events/Dispatcher.php) | `Event` |
+| [Illuminate\Contracts\Filesystem\Cloud](https://github.com/illuminate/contracts/blob/{{version}}/Filesystem/Cloud.php) | `Storage::cloud()` |
+| [Illuminate\Contracts\Filesystem\Factory](https://github.com/illuminate/contracts/blob/{{version}}/Filesystem/Factory.php) | `Storage` |
+| [Illuminate\Contracts\Filesystem\Filesystem](https://github.com/illuminate/contracts/blob/{{version}}/Filesystem/Filesystem.php) | `Storage::disk()` |
+| [Illuminate\Contracts\Foundation\Application](https://github.com/illuminate/contracts/blob/{{version}}/Foundation/Application.php) | `App` |
+| [Illuminate\Contracts\Hashing\Hasher](https://github.com/illuminate/contracts/blob/{{version}}/Hashing/Hasher.php) | `Hash` |
+| [Illuminate\Contracts\Http\Kernel](https://github.com/illuminate/contracts/blob/{{version}}/Http/Kernel.php) | |
+| [Illuminate\Contracts\Mail\Mailable](https://github.com/illuminate/contracts/blob/{{version}}/Mail/Mailable.php) | |
+| [Illuminate\Contracts\Mail\Mailer](https://github.com/illuminate/contracts/blob/{{version}}/Mail/Mailer.php) | `Mail` |
+| [Illuminate\Contracts\Mail\MailQueue](https://github.com/illuminate/contracts/blob/{{version}}/Mail/MailQueue.php) | `Mail::queue()` |
+| [Illuminate\Contracts\Notifications\Dispatcher](https://github.com/illuminate/contracts/blob/{{version}}/Notifications/Dispatcher.php) | `Notification`|
+| [Illuminate\Contracts\Notifications\Factory](https://github.com/illuminate/contracts/blob/{{version}}/Notifications/Factory.php) | `Notification` |
+| [Illuminate\Contracts\Pagination\LengthAwarePaginator](https://github.com/illuminate/contracts/blob/{{version}}/Pagination/LengthAwarePaginator.php) | |
+| [Illuminate\Contracts\Pagination\Paginator](https://github.com/illuminate/contracts/blob/{{version}}/Pagination/Paginator.php) | |
+| [Illuminate\Contracts\Pipeline\Hub](https://github.com/illuminate/contracts/blob/{{version}}/Pipeline/Hub.php) | |
+| [Illuminate\Contracts\Pipeline\Pipeline](https://github.com/illuminate/contracts/blob/{{version}}/Pipeline/Pipeline.php) | `Pipeline` |
+| [Illuminate\Contracts\Queue\EntityResolver](https://github.com/illuminate/contracts/blob/{{version}}/Queue/EntityResolver.php) | |
+| [Illuminate\Contracts\Queue\Factory](https://github.com/illuminate/contracts/blob/{{version}}/Queue/Factory.php) | `Queue` |
+| [Illuminate\Contracts\Queue\Job](https://github.com/illuminate/contracts/blob/{{version}}/Queue/Job.php) | |
+| [Illuminate\Contracts\Queue\Monitor](https://github.com/illuminate/contracts/blob/{{version}}/Queue/Monitor.php) | `Queue` |
+| [Illuminate\Contracts\Queue\Queue](https://github.com/illuminate/contracts/blob/{{version}}/Queue/Queue.php) | `Queue::connection()` |
+| [Illuminate\Contracts\Queue\QueueableCollection](https://github.com/illuminate/contracts/blob/{{version}}/Queue/QueueableCollection.php) | |
+| [Illuminate\Contracts\Queue\QueueableEntity](https://github.com/illuminate/contracts/blob/{{version}}/Queue/QueueableEntity.php) | |
+| [Illuminate\Contracts\Queue\ShouldQueue](https://github.com/illuminate/contracts/blob/{{version}}/Queue/ShouldQueue.php) | |
+| [Illuminate\Contracts\Redis\Factory](https://github.com/illuminate/contracts/blob/{{version}}/Redis/Factory.php) | `Redis` |
+| [Illuminate\Contracts\Routing\BindingRegistrar](https://github.com/illuminate/contracts/blob/{{version}}/Routing/BindingRegistrar.php) | `Route` |
+| [Illuminate\Contracts\Routing\Registrar](https://github.com/illuminate/contracts/blob/{{version}}/Routing/Registrar.php) | `Route` |
+| [Illuminate\Contracts\Routing\ResponseFactory](https://github.com/illuminate/contracts/blob/{{version}}/Routing/ResponseFactory.php) | `Response` |
+| [Illuminate\Contracts\Routing\UrlGenerator](https://github.com/illuminate/contracts/blob/{{version}}/Routing/UrlGenerator.php) | `URL` |
+| [Illuminate\Contracts\Routing\UrlRoutable](https://github.com/illuminate/contracts/blob/{{version}}/Routing/UrlRoutable.php) | |
+| [Illuminate\Contracts\Session\Session](https://github.com/illuminate/contracts/blob/{{version}}/Session/Session.php) | `Session::driver()` |
+| [Illuminate\Contracts\Support\Arrayable](https://github.com/illuminate/contracts/blob/{{version}}/Support/Arrayable.php) | |
+| [Illuminate\Contracts\Support\Htmlable](https://github.com/illuminate/contracts/blob/{{version}}/Support/Htmlable.php) | |
+| [Illuminate\Contracts\Support\Jsonable](https://github.com/illuminate/contracts/blob/{{version}}/Support/Jsonable.php) | |
+| [Illuminate\Contracts\Support\MessageBag](https://github.com/illuminate/contracts/blob/{{version}}/Support/MessageBag.php) | |
+| [Illuminate\Contracts\Support\MessageProvider](https://github.com/illuminate/contracts/blob/{{version}}/Support/MessageProvider.php) | |
+| [Illuminate\Contracts\Support\Renderable](https://github.com/illuminate/contracts/blob/{{version}}/Support/Renderable.php) | |
+| [Illuminate\Contracts\Support\Responsable](https://github.com/illuminate/contracts/blob/{{version}}/Support/Responsable.php) | |
+| [Illuminate\Contracts\Translation\Loader](https://github.com/illuminate/contracts/blob/{{version}}/Translation/Loader.php) | |
+| [Illuminate\Contracts\Translation\Translator](https://github.com/illuminate/contracts/blob/{{version}}/Translation/Translator.php) | `Lang` |
+| [Illuminate\Contracts\Validation\Factory](https://github.com/illuminate/contracts/blob/{{version}}/Validation/Factory.php) | `Validator` |
+| [Illuminate\Contracts\Validation\ValidatesWhenResolved](https://github.com/illuminate/contracts/blob/{{version}}/Validation/ValidatesWhenResolved.php) | |
+| [Illuminate\Contracts\Validation\ValidationRule](https://github.com/illuminate/contracts/blob/{{version}}/Validation/ValidationRule.php) | |
+| [Illuminate\Contracts\Validation\Validator](https://github.com/illuminate/contracts/blob/{{version}}/Validation/Validator.php) | `Validator::make()` |
+| [Illuminate\Contracts\View\Engine](https://github.com/illuminate/contracts/blob/{{version}}/View/Engine.php) | |
+| [Illuminate\Contracts\View\Factory](https://github.com/illuminate/contracts/blob/{{version}}/View/Factory.php) | `View` |
+| [Illuminate\Contracts\View\View](https://github.com/illuminate/contracts/blob/{{version}}/View/View.php) | `View::make()` |
+
+
diff --git a/contributions.md b/contributions.md
index 2e6720e1342..3f76bc0bf21 100644
--- a/contributions.md
+++ b/contributions.md
@@ -14,12 +14,14 @@
## Bug Reports
-To encourage active collaboration, Laravel strongly encourages pull requests, not just bug reports. "Bug reports" may also be sent in the form of a pull request containing a failing test. Pull requests will only be reviewed when marked as "ready for review" (not in the "draft" state) and all tests for new features are passing. Lingering, non-active pull requests left in the "draft" state will be closed after a few days.
+To encourage active collaboration, Laravel strongly encourages pull requests, not just bug reports. Pull requests will only be reviewed when marked as "ready for review" (not in the "draft" state) and all tests for new features are passing. Lingering, non-active pull requests left in the "draft" state will be closed after a few days.
However, if you file a bug report, your issue should contain a title and a clear description of the issue. You should also include as much relevant information as possible and a code sample that demonstrates the issue. The goal of a bug report is to make it easy for yourself - and others - to replicate the bug and develop a fix.
Remember, bug reports are created in the hope that others with the same problem will be able to collaborate with you on solving it. Do not expect that the bug report will automatically see any activity or that others will jump to fix it. Creating a bug report serves to help yourself and others start on the path of fixing the problem. If you want to chip in, you can help out by fixing [any bugs listed in our issue trackers](https://github.com/issues?q=is%3Aopen+is%3Aissue+label%3Abug+user%3Alaravel). You must be authenticated with GitHub to view all of Laravel's issues.
+If you notice improper DocBlock, PHPStan, or IDE warnings while using Laravel, do not create a GitHub issue. Instead, please submit a pull request to fix the problem.
+
The Laravel source code is managed on GitHub, and there are repositories for each of the Laravel projects:
@@ -32,18 +34,23 @@ The Laravel source code is managed on GitHub, and there are repositories for eac
- [Laravel Cashier Paddle](https://github.com/laravel/cashier-paddle)
- [Laravel Echo](https://github.com/laravel/echo)
- [Laravel Envoy](https://github.com/laravel/envoy)
+- [Laravel Folio](https://github.com/laravel/folio)
- [Laravel Framework](https://github.com/laravel/framework)
-- [Laravel Homestead](https://github.com/laravel/homestead)
-- [Laravel Homestead Build Scripts](https://github.com/laravel/settler)
+- [Laravel Homestead](https://github.com/laravel/homestead) ([Build Scripts](https://github.com/laravel/settler))
- [Laravel Horizon](https://github.com/laravel/horizon)
-- [Laravel Jetstream](https://github.com/laravel/jetstream)
- [Laravel Passport](https://github.com/laravel/passport)
+- [Laravel Pennant](https://github.com/laravel/pennant)
+- [Laravel Pint](https://github.com/laravel/pint)
+- [Laravel Prompts](https://github.com/laravel/prompts)
+- [Laravel Reverb](https://github.com/laravel/reverb)
- [Laravel Sail](https://github.com/laravel/sail)
- [Laravel Sanctum](https://github.com/laravel/sanctum)
- [Laravel Scout](https://github.com/laravel/scout)
- [Laravel Socialite](https://github.com/laravel/socialite)
- [Laravel Telescope](https://github.com/laravel/telescope)
-- [Laravel Website](https://github.com/laravel/laravel.com-next)
+- [Laravel Livewire Starter Kit](https://github.com/laravel/livewire-starter-kit)
+- [Laravel React Starter Kit](https://github.com/laravel/react-starter-kit)
+- [Laravel Vue Starter Kit](https://github.com/laravel/vue-starter-kit)
@@ -74,13 +81,11 @@ Informal discussion regarding bugs, new features, and implementation of existing
## Which Branch?
-**All** bug fixes should be sent to the latest stable branch. Bug fixes should **never** be sent to the `master` branch unless they fix features that exist only in the upcoming release.
-
-**Minor** features that are **fully backward compatible** with the current release may be sent to the latest stable branch.
+**All** bug fixes should be sent to the latest version that supports bug fixes (currently `12.x`). Bug fixes should **never** be sent to the `master` branch unless they fix features that exist only in the upcoming release.
-**Major** new features should always be sent to the `master` branch, which contains the upcoming release.
+**Minor** features that are **fully backward compatible** with the current release may be sent to the latest stable branch (currently `12.x`).
-If you are unsure if your feature qualifies as a major or minor, please ask Taylor Otwell in the `#internals` channel of the [Laravel Discord server](https://discord.gg/laravel).
+**Major** new features or features with breaking changes should always be sent to the `master` branch, which contains the upcoming release.
## Compiled Assets
@@ -102,20 +107,50 @@ Laravel follows the [PSR-2](https://github.com/php-fig/fig-standards/blob/master
Below is an example of a valid Laravel documentation block. Note that the `@param` attribute is followed by two spaces, the argument type, two more spaces, and finally the variable name:
- /**
- * Register a binding with the container.
- *
- * @param string|array $abstract
- * @param \Closure|string|null $concrete
- * @param bool $shared
- * @return void
- *
- * @throws \Exception
- */
- public function bind($abstract, $concrete = null, $shared = false)
- {
- //
- }
+```php
+/**
+ * Register a binding with the container.
+ *
+ * @param string|array $abstract
+ * @param \Closure|string|null $concrete
+ * @param bool $shared
+ * @return void
+ *
+ * @throws \Exception
+ */
+public function bind($abstract, $concrete = null, $shared = false)
+{
+ // ...
+}
+```
+
+When the `@param` or `@return` attributes are redundant due to the use of native types, they can be removed:
+
+```php
+/**
+ * Execute the job.
+ */
+public function handle(AudioProcessor $processor): void
+{
+ //
+}
+```
+
+However, when the native type is generic, please specify the generic type through the use of the `@param` or `@return` attributes:
+
+```php
+/**
+ * Get the attachments for the message.
+ *
+ * @return array
+
+| Verb | URI | Action | Route Name |
+| --------- | ---------------------- | ------- | -------------- |
+| GET | `/photos` | index | photos.index |
+| GET | `/photos/create` | create | photos.create |
+| POST | `/photos` | store | photos.store |
+| GET | `/photos/{photo}` | show | photos.show |
+| GET | `/photos/{photo}/edit` | edit | photos.edit |
+| PUT/PATCH | `/photos/{photo}` | update | photos.update |
+| DELETE | `/photos/{photo}` | destroy | photos.destroy |
+
+
#### Customizing Missing Model Behavior
-Typically, a 404 HTTP response will be generated if an implicitly bound resource model is not found. However, you may customize this behavior by calling the `missing` method when defining your resource route. The `missing` method accepts a closure that will be invoked if an implicitly bound model can not be found for any of the resource's routes:
+Typically, a 404 HTTP response will be generated if an implicitly bound resource model is not found. However, you may customize this behavior by calling the `missing` method when defining your resource route. The `missing` method accepts a closure that will be invoked if an implicitly bound model cannot be found for any of the resource's routes:
+
+```php
+use App\Http\Controllers\PhotoController;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Redirect;
+
+Route::resource('photos', PhotoController::class)
+ ->missing(function (Request $request) {
+ return Redirect::route('photos.index');
+ });
+```
+
+
+#### Soft Deleted Models
+
+Typically, implicit model binding will not retrieve models that have been [soft deleted](/docs/{{version}}/eloquent#soft-deleting), and will instead return a 404 HTTP response. However, you can instruct the framework to allow soft deleted models by invoking the `withTrashed` method when defining your resource route:
- use App\Http\Controllers\PhotoController;
- use Illuminate\Http\Request;
- use Illuminate\Support\Facades\Redirect;
+```php
+use App\Http\Controllers\PhotoController;
- Route::resource('photos', PhotoController::class)
- ->missing(function (Request $request) {
- return Redirect::route('photos.index');
- });
+Route::resource('photos', PhotoController::class)->withTrashed();
+```
+
+Calling `withTrashed` with no arguments will allow soft deleted models for the `show`, `edit`, and `update` resource routes. You may specify a subset of these routes by passing an array to the `withTrashed` method:
+
+```php
+Route::resource('photos', PhotoController::class)->withTrashed(['show']);
+```
-#### Specifying The Resource Model
+#### Specifying the Resource Model
If you are using [route model binding](/docs/{{version}}/routing#route-model-binding) and would like the resource controller's methods to type-hint a model instance, you may use the `--model` option when generating the controller:
@@ -206,34 +278,40 @@ php artisan make:controller PhotoController --model=Photo --resource --requests
When declaring a resource route, you may specify a subset of actions the controller should handle instead of the full set of default actions:
- use App\Http\Controllers\PhotoController;
+```php
+use App\Http\Controllers\PhotoController;
- Route::resource('photos', PhotoController::class)->only([
- 'index', 'show'
- ]);
+Route::resource('photos', PhotoController::class)->only([
+ 'index', 'show'
+]);
- Route::resource('photos', PhotoController::class)->except([
- 'create', 'store', 'update', 'destroy'
- ]);
+Route::resource('photos', PhotoController::class)->except([
+ 'create', 'store', 'update', 'destroy'
+]);
+```
#### API Resource Routes
When declaring resource routes that will be consumed by APIs, you will commonly want to exclude routes that present HTML templates such as `create` and `edit`. For convenience, you may use the `apiResource` method to automatically exclude these two routes:
- use App\Http\Controllers\PhotoController;
+```php
+use App\Http\Controllers\PhotoController;
- Route::apiResource('photos', PhotoController::class);
+Route::apiResource('photos', PhotoController::class);
+```
You may register many API resource controllers at once by passing an array to the `apiResources` method:
- use App\Http\Controllers\PhotoController;
- use App\Http\Controllers\PostController;
+```php
+use App\Http\Controllers\PhotoController;
+use App\Http\Controllers\PostController;
- Route::apiResources([
- 'photos' => PhotoController::class,
- 'posts' => PostController::class,
- ]);
+Route::apiResources([
+ 'photos' => PhotoController::class,
+ 'posts' => PostController::class,
+]);
+```
To quickly generate an API resource controller that does not include the `create` or `edit` methods, use the `--api` switch when executing the `make:controller` command:
@@ -246,13 +324,17 @@ php artisan make:controller PhotoController --api
Sometimes you may need to define routes to a nested resource. For example, a photo resource may have multiple comments that may be attached to the photo. To nest the resource controllers, you may use "dot" notation in your route declaration:
- use App\Http\Controllers\PhotoCommentController;
+```php
+use App\Http\Controllers\PhotoCommentController;
- Route::resource('photos.comments', PhotoCommentController::class);
+Route::resource('photos.comments', PhotoCommentController::class);
+```
This route will register a nested resource that may be accessed with URIs like the following:
- /photos/{photo}/comments/{comment}
+```text
+/photos/{photo}/comments/{comment}
+```
#### Scoping Nested Resources
@@ -264,188 +346,350 @@ Laravel's [implicit model binding](/docs/{{version}}/routing#implicit-model-bind
Often, it is not entirely necessary to have both the parent and the child IDs within a URI since the child ID is already a unique identifier. When using unique identifiers such as auto-incrementing primary keys to identify your models in URI segments, you may choose to use "shallow nesting":
- use App\Http\Controllers\CommentController;
+```php
+use App\Http\Controllers\CommentController;
- Route::resource('photos.comments', CommentController::class)->shallow();
+Route::resource('photos.comments', CommentController::class)->shallow();
+```
This route definition will define the following routes:
-Verb | URI | Action | Route Name
-----------|-----------------------------------|--------------|---------------------
-GET | `/photos/{photo}/comments` | index | photos.comments.index
-GET | `/photos/{photo}/comments/create` | create | photos.comments.create
-POST | `/photos/{photo}/comments` | store | photos.comments.store
-GET | `/comments/{comment}` | show | comments.show
-GET | `/comments/{comment}/edit` | edit | comments.edit
-PUT/PATCH | `/comments/{comment}` | update | comments.update
-DELETE | `/comments/{comment}` | destroy | comments.destroy
+
+
+| Verb | URI | Action | Route Name |
+| --------- | --------------------------------- | ------- | ---------------------- |
+| GET | `/photos/{photo}/comments` | index | photos.comments.index |
+| GET | `/photos/{photo}/comments/create` | create | photos.comments.create |
+| POST | `/photos/{photo}/comments` | store | photos.comments.store |
+| GET | `/comments/{comment}` | show | comments.show |
+| GET | `/comments/{comment}/edit` | edit | comments.edit |
+| PUT/PATCH | `/comments/{comment}` | update | comments.update |
+| DELETE | `/comments/{comment}` | destroy | comments.destroy |
+
+
### Naming Resource Routes
By default, all resource controller actions have a route name; however, you can override these names by passing a `names` array with your desired route names:
- use App\Http\Controllers\PhotoController;
+```php
+use App\Http\Controllers\PhotoController;
- Route::resource('photos', PhotoController::class)->names([
- 'create' => 'photos.build'
- ]);
+Route::resource('photos', PhotoController::class)->names([
+ 'create' => 'photos.build'
+]);
+```
### Naming Resource Route Parameters
By default, `Route::resource` will create the route parameters for your resource routes based on the "singularized" version of the resource name. You can easily override this on a per resource basis using the `parameters` method. The array passed into the `parameters` method should be an associative array of resource names and parameter names:
- use App\Http\Controllers\AdminUserController;
+```php
+use App\Http\Controllers\AdminUserController;
- Route::resource('users', AdminUserController::class)->parameters([
- 'users' => 'admin_user'
- ]);
+Route::resource('users', AdminUserController::class)->parameters([
+ 'users' => 'admin_user'
+]);
+```
- The example above generates the following URI for the resource's `show` route:
+The example above generates the following URI for the resource's `show` route:
- /users/{admin_user}
+```text
+/users/{admin_user}
+```
### Scoping Resource Routes
Laravel's [scoped implicit model binding](/docs/{{version}}/routing#implicit-model-binding-scoping) feature can automatically scope nested bindings such that the resolved child model is confirmed to belong to the parent model. By using the `scoped` method when defining your nested resource, you may enable automatic scoping as well as instruct Laravel which field the child resource should be retrieved by:
- use App\Http\Controllers\PhotoCommentController;
+```php
+use App\Http\Controllers\PhotoCommentController;
- Route::resource('photos.comments', PhotoCommentController::class)->scoped([
- 'comment' => 'slug',
- ]);
+Route::resource('photos.comments', PhotoCommentController::class)->scoped([
+ 'comment' => 'slug',
+]);
+```
This route will register a scoped nested resource that may be accessed with URIs like the following:
- /photos/{photo}/comments/{comment:slug}
+```text
+/photos/{photo}/comments/{comment:slug}
+```
When using a custom keyed implicit binding as a nested route parameter, Laravel will automatically scope the query to retrieve the nested model by its parent using conventions to guess the relationship name on the parent. In this case, it will be assumed that the `Photo` model has a relationship named `comments` (the plural of the route parameter name) which can be used to retrieve the `Comment` model.
### Localizing Resource URIs
-By default, `Route::resource` will create resource URIs using English verbs. If you need to localize the `create` and `edit` action verbs, you may use the `Route::resourceVerbs` method. This may be done at the beginning of the `boot` method within your application's `App\Providers\RouteServiceProvider`:
-
- /**
- * Define your route model bindings, pattern filters, etc.
- *
- * @return void
- */
- public function boot()
- {
- Route::resourceVerbs([
- 'create' => 'crear',
- 'edit' => 'editar',
- ]);
-
- // ...
- }
+By default, `Route::resource` will create resource URIs using English verbs and plural rules. If you need to localize the `create` and `edit` action verbs, you may use the `Route::resourceVerbs` method. This may be done at the beginning of the `boot` method within your application's `App\Providers\AppServiceProvider`:
+
+```php
+/**
+ * Bootstrap any application services.
+ */
+public function boot(): void
+{
+ Route::resourceVerbs([
+ 'create' => 'crear',
+ 'edit' => 'editar',
+ ]);
+}
+```
-Once the verbs have been customized, a resource route registration such as `Route::resource('fotos', PhotoController::class)` will produce the following URIs:
+Laravel's pluralizer supports [several different languages which you may configure based on your needs](/docs/{{version}}/localization#pluralization-language). Once the verbs and pluralization language have been customized, a resource route registration such as `Route::resource('publicacion', PublicacionController::class)` will produce the following URIs:
- /fotos/crear
+```text
+/publicacion/crear
- /fotos/{foto}/editar
+/publicacion/{publicaciones}/editar
+```
### Supplementing Resource Controllers
If you need to add additional routes to a resource controller beyond the default set of resource routes, you should define those routes before your call to the `Route::resource` method; otherwise, the routes defined by the `resource` method may unintentionally take precedence over your supplemental routes:
- use App\Http\Controller\PhotoController;
+```php
+use App\Http\Controller\PhotoController;
- Route::get('/photos/popular', [PhotoController::class, 'popular']);
- Route::resource('photos', PhotoController::class);
+Route::get('/photos/popular', [PhotoController::class, 'popular']);
+Route::resource('photos', PhotoController::class);
+```
+
+> [!NOTE]
+> Remember to keep your controllers focused. If you find yourself routinely needing methods outside of the typical set of resource actions, consider splitting your controller into two, smaller controllers.
+
+
+### Singleton Resource Controllers
+
+Sometimes, your application will have resources that may only have a single instance. For example, a user's "profile" can be edited or updated, but a user may not have more than one "profile". Likewise, an image may have a single "thumbnail". These resources are called "singleton resources", meaning one and only one instance of the resource may exist. In these scenarios, you may register a "singleton" resource controller:
+
+```php
+use App\Http\Controllers\ProfileController;
+use Illuminate\Support\Facades\Route;
+
+Route::singleton('profile', ProfileController::class);
+```
+
+The singleton resource definition above will register the following routes. As you can see, "creation" routes are not registered for singleton resources, and the registered routes do not accept an identifier since only one instance of the resource may exist:
+
+
+
+| Verb | URI | Action | Route Name |
+| --------- | --------------- | ------ | -------------- |
+| GET | `/profile` | show | profile.show |
+| GET | `/profile/edit` | edit | profile.edit |
+| PUT/PATCH | `/profile` | update | profile.update |
+
+
+
+Singleton resources may also be nested within a standard resource:
+
+```php
+Route::singleton('photos.thumbnail', ThumbnailController::class);
+```
+
+In this example, the `photos` resource would receive all of the [standard resource routes](#actions-handled-by-resource-controllers); however, the `thumbnail` resource would be a singleton resource with the following routes:
+
+
+
+| Verb | URI | Action | Route Name |
+| --------- | -------------------------------- | ------ | ----------------------- |
+| GET | `/photos/{photo}/thumbnail` | show | photos.thumbnail.show |
+| GET | `/photos/{photo}/thumbnail/edit` | edit | photos.thumbnail.edit |
+| PUT/PATCH | `/photos/{photo}/thumbnail` | update | photos.thumbnail.update |
+
+
+
+
+#### Creatable Singleton Resources
+
+Occasionally, you may want to define creation and storage routes for a singleton resource. To accomplish this, you may invoke the `creatable` method when registering the singleton resource route:
+
+```php
+Route::singleton('photos.thumbnail', ThumbnailController::class)->creatable();
+```
+
+In this example, the following routes will be registered. As you can see, a `DELETE` route will also be registered for creatable singleton resources:
+
+
+
+| Verb | URI | Action | Route Name |
+| --------- | ---------------------------------- | ------- | ------------------------ |
+| GET | `/photos/{photo}/thumbnail/create` | create | photos.thumbnail.create |
+| POST | `/photos/{photo}/thumbnail` | store | photos.thumbnail.store |
+| GET | `/photos/{photo}/thumbnail` | show | photos.thumbnail.show |
+| GET | `/photos/{photo}/thumbnail/edit` | edit | photos.thumbnail.edit |
+| PUT/PATCH | `/photos/{photo}/thumbnail` | update | photos.thumbnail.update |
+| DELETE | `/photos/{photo}/thumbnail` | destroy | photos.thumbnail.destroy |
+
+
+
+If you would like Laravel to register the `DELETE` route for a singleton resource but not register the creation or storage routes, you may utilize the `destroyable` method:
+
+```php
+Route::singleton(...)->destroyable();
+```
+
+
+#### API Singleton Resources
+
+The `apiSingleton` method may be used to register a singleton resource that will be manipulated via an API, thus rendering the `create` and `edit` routes unnecessary:
+
+```php
+Route::apiSingleton('profile', ProfileController::class);
+```
+
+Of course, API singleton resources may also be `creatable`, which will register `store` and `destroy` routes for the resource:
+
+```php
+Route::apiSingleton('photos.thumbnail', ProfileController::class)->creatable();
+```
+
+### Middleware and Resource Controllers
-> {tip} Remember to keep your controllers focused. If you find yourself routinely needing methods outside of the typical set of resource actions, consider splitting your controller into two, smaller controllers.
+Laravel allows you to assign middleware to all, or only specific, methods of resource routes using the `middleware`, `middlewareFor`, and `withoutMiddlewareFor` methods. These methods provide fine-grained control over which middleware is applied to each resource action.
+
+#### Applying Middleware to all Methods
+
+You may use the `middleware` method to assign middleware to all routes generated by a resource or singleton resource route:
+
+```php
+Route::resource('users', UserController::class)
+ ->middleware(['auth', 'verified']);
+
+Route::singleton('profile', ProfileController::class)
+ ->middleware('auth');
+```
+
+#### Applying Middleware to Specific Methods
+
+You may use the `middlewareFor` method to assign middleware to one or more specific methods of a given resource controller:
+
+```php
+Route::resource('users', UserController::class)
+ ->middlewareFor('show', 'auth');
+
+Route::apiResource('users', UserController::class)
+ ->middlewareFor(['show', 'update'], 'auth');
+
+Route::resource('users', UserController::class)
+ ->middlewareFor('show', 'auth')
+ ->middlewareFor('update', 'auth');
+
+Route::apiResource('users', UserController::class)
+ ->middlewareFor(['show', 'update'], ['auth', 'verified']);
+```
+
+The `middlewareFor` method may also be used in conjunction with singleton and API singleton resource controllers:
+
+```php
+Route::singleton('profile', ProfileController::class)
+ ->middlewareFor('show', 'auth');
+
+Route::apiSingleton('profile', ProfileController::class)
+ ->middlewareFor(['show', 'update'], 'auth');
+```
+
+#### Excluding Middleware from Specific Methods
+
+You may use the `withoutMiddlewareFor` method to exclude middleware from specific methods of a resource controller:
+
+```php
+Route::middleware(['auth', 'verified', 'subscribed'])->group(function () {
+ Route::resource('users', UserController::class)
+ ->withoutMiddlewareFor('index', ['auth', 'verified'])
+ ->withoutMiddlewareFor(['create', 'store'], 'verified')
+ ->withoutMiddlewareFor('destroy', 'subscribed');
+});
+```
-## Dependency Injection & Controllers
+## Dependency Injection and Controllers
#### Constructor Injection
The Laravel [service container](/docs/{{version}}/container) is used to resolve all Laravel controllers. As a result, you are able to type-hint any dependencies your controller may need in its constructor. The declared dependencies will automatically be resolved and injected into the controller instance:
- users = $users;
- }
- }
+class UserController extends Controller
+{
+ /**
+ * Create a new controller instance.
+ */
+ public function __construct(
+ protected UserRepository $users,
+ ) {}
+}
+```
#### Method Injection
In addition to constructor injection, you may also type-hint dependencies on your controller's methods. A common use-case for method injection is injecting the `Illuminate\Http\Request` instance into your controller methods:
- name;
-
- //
- }
+ $name = $request->name;
+
+ // Store the user...
+
+ return redirect('/users');
}
+}
+```
If your controller method is also expecting input from a route parameter, list your route arguments after your other dependencies. For example, if your route is defined like so:
- use App\Http\Controllers\UserController;
+```php
+use App\Http\Controllers\UserController;
- Route::put('/user/{id}', [UserController::class, 'update']);
+Route::put('/user/{id}', [UserController::class, 'update']);
+```
You may still type-hint the `Illuminate\Http\Request` and access your `id` parameter by defining your controller method as follows:
-
-#### An Explanation Of The Vulnerability
+#### An Explanation of the Vulnerability
In case you're not familiar with cross-site request forgeries, let's discuss an example of how this vulnerability can be exploited. Imagine your application has a `/user/email` route that accepts a `POST` request to change the authenticated user's email address. Most likely, this route expects an `email` input field to contain the email address the user would like to begin using.
@@ -28,9 +28,9 @@ Without CSRF protection, a malicious website could create an HTML form that poin
```
- If the malicious website automatically submits the form when the page is loaded, the malicious user only needs to lure an unsuspecting user of your application to visit their website and their email address will be changed in your application.
+If the malicious website automatically submits the form when the page is loaded, the malicious user only needs to lure an unsuspecting user of your application to visit their website and their email address will be changed in your application.
- To prevent this vulnerability, we need to inspect every incoming `POST`, `PUT`, `PATCH`, or `DELETE` request for a secret session value that the malicious application is unable to access.
+To prevent this vulnerability, we need to inspect every incoming `POST`, `PUT`, `PATCH`, or `DELETE` request for a secret session value that the malicious application is unable to access.
## Preventing CSRF Requests
@@ -39,15 +39,17 @@ Laravel automatically generates a CSRF "token" for each active [user session](/d
The current session's CSRF token can be accessed via the request's session or via the `csrf_token` helper function:
- use Illuminate\Http\Request;
+```php
+use Illuminate\Http\Request;
- Route::get('/token', function (Request $request) {
- $token = $request->session()->token();
+Route::get('/token', function (Request $request) {
+ $token = $request->session()->token();
- $token = csrf_token();
+ $token = csrf_token();
- // ...
- });
+ // ...
+});
+```
Anytime you define a "POST", "PUT", "PATCH", or "DELETE" HTML form in your application, you should include a hidden CSRF `_token` field in the form so that the CSRF protection middleware can validate the request. For convenience, you may use the `@csrf` Blade directive to generate the hidden token input field:
@@ -60,7 +62,7 @@ Anytime you define a "POST", "PUT", "PATCH", or "DELETE" HTML form in your appli
```
-The `App\Http\Middleware\VerifyCsrfToken` [middleware](/docs/{{version}}/middleware), which is included in the `web` middleware group by default, will automatically verify that the token in the request input matches the token stored in the session. When these two tokens match, we know that the authenticated user is the one initiating the request.
+The `Illuminate\Foundation\Http\Middleware\ValidateCsrfToken` [middleware](/docs/{{version}}/middleware), which is included in the `web` middleware group by default, will automatically verify that the token in the request input matches the token stored in the session. When these two tokens match, we know that the authenticated user is the one initiating the request.
### CSRF Tokens & SPAs
@@ -72,34 +74,25 @@ If you are building an SPA that is utilizing Laravel as an API backend, you shou
Sometimes you may wish to exclude a set of URIs from CSRF protection. For example, if you are using [Stripe](https://stripe.com) to process payments and are utilizing their webhook system, you will need to exclude your Stripe webhook handler route from CSRF protection since Stripe will not know what CSRF token to send to your routes.
-Typically, you should place these kinds of routes outside of the `web` middleware group that the `App\Providers\RouteServiceProvider` applies to all routes in the `routes/web.php` file. However, you may also exclude the routes by adding their URIs to the `$except` property of the `VerifyCsrfToken` middleware:
-
- withMiddleware(function (Middleware $middleware): void {
+ $middleware->validateCsrfTokens(except: [
+ 'stripe/*',
+ 'http://example.com/foo/bar',
+ 'http://example.com/foo/*',
+ ]);
+})
+```
-> {tip} For convenience, the CSRF middleware is automatically disabled for all routes when [running tests](/docs/{{version}}/testing).
+> [!NOTE]
+> For convenience, the CSRF middleware is automatically disabled for all routes when [running tests](/docs/{{version}}/testing).
## X-CSRF-TOKEN
-In addition to checking for the CSRF token as a POST parameter, the `App\Http\Middleware\VerifyCsrfToken` middleware will also check for the `X-CSRF-TOKEN` request header. You could, for example, store the token in an HTML `meta` tag:
+In addition to checking for the CSRF token as a POST parameter, the `Illuminate\Foundation\Http\Middleware\ValidateCsrfToken` middleware, which is included in the `web` middleware group by default, will also check for the `X-CSRF-TOKEN` request header. You could, for example, store the token in an HTML `meta` tag:
```blade
@@ -122,4 +115,5 @@ Laravel stores the current CSRF token in an encrypted `XSRF-TOKEN` cookie that i
This cookie is primarily sent as a developer convenience since some JavaScript frameworks and libraries, like Angular and Axios, automatically place its value in the `X-XSRF-TOKEN` header on same-origin requests.
-> {tip} By default, the `resources/js/bootstrap.js` file includes the Axios HTTP library which will automatically send the `X-XSRF-TOKEN` header for you.
+> [!NOTE]
+> By default, the `resources/js/bootstrap.js` file includes the Axios HTTP library which will automatically send the `X-XSRF-TOKEN` header for you.
diff --git a/database-testing.md b/database-testing.md
index 1032b4180f9..8f1a7715bec 100644
--- a/database-testing.md
+++ b/database-testing.md
@@ -1,22 +1,8 @@
# Database Testing
- [Introduction](#introduction)
- - [Resetting The Database After Each Test](#resetting-the-database-after-each-test)
-- [Defining Model Factories](#defining-model-factories)
- - [Concept Overview](#concept-overview)
- - [Generating Factories](#generating-factories)
- - [Factory States](#factory-states)
- - [Factory Callbacks](#factory-callbacks)
-- [Creating Models Using Factories](#creating-models-using-factories)
- - [Instantiating Models](#instantiating-models)
- - [Persisting Models](#persisting-models)
- - [Sequences](#sequences)
-- [Factory Relationships](#factory-relationships)
- - [Has Many Relationships](#has-many-relationships)
- - [Belongs To Relationships](#belongs-to-relationships)
- - [Many To Many Relationships](#many-to-many-relationships)
- - [Polymorphic Relationships](#polymorphic-relationships)
- - [Defining Relationships Within Factories](#defining-relationships-within-factories)
+ - [Resetting the Database After Each Test](#resetting-the-database-after-each-test)
+- [Model Factories](#model-factories)
- [Running Seeders](#running-seeders)
- [Available Assertions](#available-assertions)
@@ -26,642 +12,280 @@
Laravel provides a variety of helpful tools and assertions to make it easier to test your database driven applications. In addition, Laravel model factories and seeders make it painless to create test database records using your application's Eloquent models and relationships. We'll discuss all of these powerful features in the following documentation.
-### Resetting The Database After Each Test
+### Resetting the Database After Each Test
Before proceeding much further, let's discuss how to reset your database after each of your tests so that data from a previous test does not interfere with subsequent tests. Laravel's included `Illuminate\Foundation\Testing\RefreshDatabase` trait will take care of this for you. Simply use the trait on your test class:
- use(RefreshDatabase::class);
- class ExampleTest extends TestCase
- {
- use RefreshDatabase;
-
- /**
- * A basic functional test example.
- *
- * @return void
- */
- public function test_basic_example()
- {
- $response = $this->get('/');
-
- // ...
- }
- }
-
-The `Illuminate\Foundation\Testing\RefreshDatabase` trait does not migrate your database if your schema is up to date. Instead, it will only execute the test within a database transaction. Therefore, any records added to the database by test cases that do not use this trait may still exist in the database.
-
-If you would like to totally reset the database using migrations, you may use the `Illuminate\Foundation\Testing\DatabaseMigrations` trait instead. However, the `DatabaseMigrations` trait is significantly slower than the `RefreshDatabase` trait.
-
-
-## Defining Model Factories
-
-
-### Concept Overview
-
-First, let's talk about Eloquent model factories. When testing, you may need to insert a few records into your database before executing your test. Instead of manually specifying the value of each column when you create this test data, Laravel allows you to define a set of default attributes for each of your [Eloquent models](/docs/{{version}}/eloquent) using model factories.
-
-To see an example of how to write a factory, take a look at the `database/factories/UserFactory.php` file in your application. This factory is included with all new Laravel applications and contains the following factory definition:
+test('basic example', function () {
+ $response = $this->get('/');
- namespace Database\Factories;
-
- use Illuminate\Database\Eloquent\Factories\Factory;
- use Illuminate\Support\Str;
-
- class UserFactory extends Factory
- {
- /**
- * Define the model's default state.
- *
- * @return array
- */
- public function definition()
- {
- return [
- 'name' => $this->faker->name(),
- 'email' => $this->faker->unique()->safeEmail(),
- 'email_verified_at' => now(),
- 'password' => '$2y$10$92IXUNpkjO0rOQ5byMi.Ye4oKoEa3Ro9llC/.og/at2.uheWG/igi', // password
- 'remember_token' => Str::random(10),
- ];
- }
- }
-
-As you can see, in their most basic form, factories are classes that extend Laravel's base factory class and define `definition` method. The `definition` method returns the default set of attribute values that should be applied when creating a model using the factory.
-
-Via the `faker` property, factories have access to the [Faker](https://github.com/FakerPHP/Faker) PHP library, which allows you to conveniently generate various kinds of random data for testing.
-
-> {tip} You can set your application's Faker locale by adding a `faker_locale` option to your `config/app.php` configuration file.
-
-
-### Generating Factories
-
-To create a factory, execute the `make:factory` [Artisan command](/docs/{{version}}/artisan):
-
-```shell
-php artisan make:factory PostFactory
+ // ...
+});
```
-The new factory class will be placed in your `database/factories` directory.
-
-
-#### Model & Factory Discovery Conventions
+```php tab=PHPUnit
+
-### Factory States
-
-State manipulation methods allow you to define discrete modifications that can be applied to your model factories in any combination. For example, your `Database\Factories\UserFactory` factory might contain a `suspended` state method that modifies one of its default attribute values.
-
-State transformation methods typically call the `state` method provided by Laravel's base factory class. The `state` method accepts a closure which will receive the array of raw attributes defined for the factory and should return an array of attributes to modify:
-
- /**
- * Indicate that the user is suspended.
- *
- * @return \Illuminate\Database\Eloquent\Factories\Factory
- */
- public function suspended()
- {
- return $this->state(function (array $attributes) {
- return [
- 'account_status' => 'suspended',
- ];
- });
- }
-
-
-### Factory Callbacks
-
-Factory callbacks are registered using the `afterMaking` and `afterCreating` methods and allow you to perform additional tasks after making or creating a model. You should register these callbacks by defining a `configure` method on your factory class. This method will be automatically called by Laravel when the factory is instantiated:
-
- namespace Database\Factories;
-
- use App\Models\User;
- use Illuminate\Database\Eloquent\Factories\Factory;
- use Illuminate\Support\Str;
-
- class UserFactory extends Factory
- {
- /**
- * Configure the model factory.
- *
- * @return $this
- */
- public function configure()
- {
- return $this->afterMaking(function (User $user) {
- //
- })->afterCreating(function (User $user) {
- //
- });
- }
+ $response = $this->get('/');
// ...
}
+}
+```
-
-## Creating Models Using Factories
-
-
-### Instantiating Models
-
-Once you have defined your factories, you may use the static `factory` method provided to your models by the `Illuminate\Database\Eloquent\Factories\HasFactory` trait in order to instantiate a factory instance for that model. Let's take a look at a few examples of creating models. First, we'll use the `make` method to create models without persisting them to the database:
-
- use App\Models\User;
-
- public function test_models_can_be_instantiated()
- {
- $user = User::factory()->make();
-
- // Use model in tests...
- }
-
-You may create a collection of many models using the `count` method:
-
- $users = User::factory()->count(3)->make();
-
-
-#### Applying States
-
-You may also apply any of your [states](#factory-states) to the models. If you would like to apply multiple state transformations to the models, you may simply call the state transformation methods directly:
-
- $users = User::factory()->count(5)->suspended()->make();
-
-
-#### Overriding Attributes
-
-If you would like to override some of the default values of your models, you may pass an array of values to the `make` method. Only the specified attributes will be replaced while the rest of the attributes remain set to their default values as specified by the factory:
-
- $user = User::factory()->make([
- 'name' => 'Abigail Otwell',
- ]);
-
-Alternatively, the `state` method may be called directly on the factory instance to perform an inline state transformation:
-
- $user = User::factory()->state([
- 'name' => 'Abigail Otwell',
- ])->make();
-
-> {tip} [Mass assignment protection](/docs/{{version}}/eloquent#mass-assignment) is automatically disabled when creating models using factories.
-
-
-### Persisting Models
-
-The `create` method instantiates model instances and persists them to the database using Eloquent's `save` method:
-
- use App\Models\User;
-
- public function test_models_can_be_persisted()
- {
- // Create a single App\Models\User instance...
- $user = User::factory()->create();
-
- // Create three App\Models\User instances...
- $users = User::factory()->count(3)->create();
-
- // Use model in tests...
- }
-
-You may override the factory's default model attributes by passing an array of attributes to the `create` method:
-
- $user = User::factory()->create([
- 'name' => 'Abigail',
- ]);
-
-
-### Sequences
-
-Sometimes you may wish to alternate the value of a given model attribute for each created model. You may accomplish this by defining a state transformation as a sequence. For example, you may wish to alternate the value of an `admin` column between `Y` and `N` for each created user:
-
- use App\Models\User;
- use Illuminate\Database\Eloquent\Factories\Sequence;
-
- $users = User::factory()
- ->count(10)
- ->state(new Sequence(
- ['admin' => 'Y'],
- ['admin' => 'N'],
- ))
- ->create();
-
-In this example, five users will be created with an `admin` value of `Y` and five users will be created with an `admin` value of `N`.
-
-If necessary, you may include a closure as a sequence value. The closure will be invoked each time the sequence needs a new value:
-
- $users = User::factory()
- ->count(10)
- ->state(new Sequence(
- fn ($sequence) => ['role' => UserRoles::all()->random()],
- ))
- ->create();
-
-Within a sequence closure, you may access the `$index` or `$count` properties on the sequence instance that is injected into the closure. The `$index` property contains the number of iterations through the sequence that have occurred thus far, while the `$count` property contains the total number of times the sequence will be invoked:
-
- $users = User::factory()
- ->count(10)
- ->sequence(fn ($sequence) => ['name' => 'Name '.$sequence->index])
- ->create();
-
-
-## Factory Relationships
-
-
-### Has Many Relationships
-
-Next, let's explore building Eloquent model relationships using Laravel's fluent factory methods. First, let's assume our application has an `App\Models\User` model and an `App\Models\Post` model. Also, let's assume that the `User` model defines a `hasMany` relationship with `Post`. We can create a user that has three posts using the `has` method provided by the Laravel's factories. The `has` method accepts a factory instance:
-
- use App\Models\Post;
- use App\Models\User;
-
- $user = User::factory()
- ->has(Post::factory()->count(3))
- ->create();
-
-By convention, when passing a `Post` model to the `has` method, Laravel will assume that the `User` model must have a `posts` method that defines the relationship. If necessary, you may explicitly specify the name of the relationship that you would like to manipulate:
-
- $user = User::factory()
- ->has(Post::factory()->count(3), 'posts')
- ->create();
-
-Of course, you may perform state manipulations on the related models. In addition, you may pass a closure based state transformation if your state change requires access to the parent model:
-
- $user = User::factory()
- ->has(
- Post::factory()
- ->count(3)
- ->state(function (array $attributes, User $user) {
- return ['user_type' => $user->type];
- })
- )
- ->create();
-
-
-#### Using Magic Methods
-
-For convenience, you may use Laravel's magic factory relationship methods to build relationships. For example, the following example will use convention to determine that the related models should be created via a `posts` relationship method on the `User` model:
-
- $user = User::factory()
- ->hasPosts(3)
- ->create();
-
-When using magic methods to create factory relationships, you may pass an array of attributes to override on the related models:
-
- $user = User::factory()
- ->hasPosts(3, [
- 'published' => false,
- ])
- ->create();
-
-You may provide a closure based state transformation if your state change requires access to the parent model:
-
- $user = User::factory()
- ->hasPosts(3, function (array $attributes, User $user) {
- return ['user_type' => $user->type];
- })
- ->create();
+The `Illuminate\Foundation\Testing\RefreshDatabase` trait does not migrate your database if your schema is up to date. Instead, it will only execute the test within a database transaction. Therefore, any records added to the database by test cases that do not use this trait may still exist in the database.
-
-### Belongs To Relationships
+If you would like to totally reset the database, you may use the `Illuminate\Foundation\Testing\DatabaseMigrations` or `Illuminate\Foundation\Testing\DatabaseTruncation` traits instead. However, both of these options are significantly slower than the `RefreshDatabase` trait.
-Now that we have explored how to build "has many" relationships using factories, let's explore the inverse of the relationship. The `for` method may be used to define the parent model that factory created models belong to. For example, we can create three `App\Models\Post` model instances that belong to a single user:
+
+## Model Factories
- use App\Models\Post;
- use App\Models\User;
+When testing, you may need to insert a few records into your database before executing your test. Instead of manually specifying the value of each column when you create this test data, Laravel allows you to define a set of default attributes for each of your [Eloquent models](/docs/{{version}}/eloquent) using [model factories](/docs/{{version}}/eloquent-factories).
- $posts = Post::factory()
- ->count(3)
- ->for(User::factory()->state([
- 'name' => 'Jessica Archer',
- ]))
- ->create();
+To learn more about creating and utilizing model factories to create models, please consult the complete [model factory documentation](/docs/{{version}}/eloquent-factories). Once you have defined a model factory, you may utilize the factory within your test to create models:
-If you already have a parent model instance that should be associated with the models you are creating, you may pass the model instance to the `for` method:
+```php tab=Pest
+use App\Models\User;
+test('models can be instantiated', function () {
$user = User::factory()->create();
- $posts = Post::factory()
- ->count(3)
- ->for($user)
- ->create();
-
-
-#### Using Magic Methods
-
-For convenience, you may use Laravel's magic factory relationship methods to define "belongs to" relationships. For example, the following example will use convention to determine that the three posts should belong to the `user` relationship on the `Post` model:
-
- $posts = Post::factory()
- ->count(3)
- ->forUser([
- 'name' => 'Jessica Archer',
- ])
- ->create();
-
-
-### Many To Many Relationships
-
-Like [has many relationships](#has-many-relationships), "many to many" relationships may be created using the `has` method:
-
- use App\Models\Role;
- use App\Models\User;
-
- $user = User::factory()
- ->has(Role::factory()->count(3))
- ->create();
-
-
-#### Pivot Table Attributes
-
-If you need to define attributes that should be set on the pivot / intermediate table linking the models, you may use the `hasAttached` method. This method accepts an array of pivot table attribute names and values as its second argument:
-
- use App\Models\Role;
- use App\Models\User;
-
- $user = User::factory()
- ->hasAttached(
- Role::factory()->count(3),
- ['active' => true]
- )
- ->create();
-
-You may provide a closure based state transformation if your state change requires access to the related model:
-
- $user = User::factory()
- ->hasAttached(
- Role::factory()
- ->count(3)
- ->state(function (array $attributes, User $user) {
- return ['name' => $user->name.' Role'];
- }),
- ['active' => true]
- )
- ->create();
-
-If you already have model instances that you would like to be attached to the models you are creating, you may pass the model instances to the `hasAttached` method. In this example, the same three roles will be attached to all three users:
-
- $roles = Role::factory()->count(3)->create();
-
- $user = User::factory()
- ->count(3)
- ->hasAttached($roles, ['active' => true])
- ->create();
-
-
-#### Using Magic Methods
-
-For convenience, you may use Laravel's magic factory relationship methods to define many to many relationships. For example, the following example will use convention to determine that the related models should be created via a `roles` relationship method on the `User` model:
-
- $user = User::factory()
- ->hasRoles(1, [
- 'name' => 'Editor'
- ])
- ->create();
-
-
-### Polymorphic Relationships
-
-[Polymorphic relationships](/docs/{{version}}/eloquent-relationships#polymorphic-relationships) may also be created using factories. Polymorphic "morph many" relationships are created in the same way as typical "has many" relationships. For example, if a `App\Models\Post` model has a `morphMany` relationship with a `App\Models\Comment` model:
+ // ...
+});
+```
- use App\Models\Post;
+```php tab=PHPUnit
+use App\Models\User;
- $post = Post::factory()->hasComments(3)->create();
+public function test_models_can_be_instantiated(): void
+{
+ $user = User::factory()->create();
-
-#### Morph To Relationships
+ // ...
+}
+```
-Magic methods may not be used to create `morphTo` relationships. Instead, the `for` method must be used directly and the name of the relationship must be explicitly provided. For example, imagine that the `Comment` model has a `commentable` method that defines a `morphTo` relationship. In this situation, we may create three comments that belong to a single post by using the `for` method directly:
+
+## Running Seeders
- $comments = Comment::factory()->count(3)->for(
- Post::factory(), 'commentable'
- )->create();
+If you would like to use [database seeders](/docs/{{version}}/seeding) to populate your database during a feature test, you may invoke the `seed` method. By default, the `seed` method will execute the `DatabaseSeeder`, which should execute all of your other seeders. Alternatively, you pass a specific seeder class name to the `seed` method:
-
-#### Polymorphic Many To Many Relationships
+```php tab=Pest
+use(RefreshDatabase::class);
- $videos = Video::factory()
- ->hasAttached(
- Tag::factory()->count(3),
- ['public' => true]
- )
- ->create();
+test('orders can be created', function () {
+ // Run the DatabaseSeeder...
+ $this->seed();
-Of course, the magic `has` method may also be used to create polymorphic "many to many" relationships:
+ // Run a specific seeder...
+ $this->seed(OrderStatusSeeder::class);
- $videos = Video::factory()
- ->hasTags(3, ['public' => true])
- ->create();
+ // ...
-
-### Defining Relationships Within Factories
+ // Run an array of specific seeders...
+ $this->seed([
+ OrderStatusSeeder::class,
+ TransactionStatusSeeder::class,
+ // ...
+ ]);
+});
+```
-To define a relationship within your model factory, you will typically assign a new factory instance to the foreign key of the relationship. This is normally done for the "inverse" relationships such as `belongsTo` and `morphTo` relationships. For example, if you would like to create a new user when creating a post, you may do the following:
+```php tab=PHPUnit
+ User::factory(),
- 'title' => $this->faker->title(),
- 'content' => $this->faker->paragraph(),
- ];
- }
+use Database\Seeders\OrderStatusSeeder;
+use Database\Seeders\TransactionStatusSeeder;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Tests\TestCase;
-If the relationship's columns depend on the factory that defines it you may assign a closure to an attribute. The closure will receive the factory's evaluated attribute array:
+class ExampleTest extends TestCase
+{
+ use RefreshDatabase;
/**
- * Define the model's default state.
- *
- * @return array
+ * Test creating a new order.
*/
- public function definition()
- {
- return [
- 'user_id' => User::factory(),
- 'user_type' => function (array $attributes) {
- return User::find($attributes['user_id'])->type;
- },
- 'title' => $this->faker->title(),
- 'content' => $this->faker->paragraph(),
- ];
- }
-
-
-## Running Seeders
-
-If you would like to use [database seeders](/docs/{{version}}/seeding) to populate your database during a feature test, you may invoke the `seed` method. By default, the `seed` method will execute the `DatabaseSeeder`, which should execute all of your other seeders. Alternatively, you pass a specific seeder class name to the `seed` method:
-
- seed();
- /**
- * Test creating a new order.
- *
- * @return void
- */
- public function test_orders_can_be_created()
- {
- // Run the DatabaseSeeder...
- $this->seed();
+ // Run a specific seeder...
+ $this->seed(OrderStatusSeeder::class);
- // Run a specific seeder...
- $this->seed(OrderStatusSeeder::class);
+ // ...
+ // Run an array of specific seeders...
+ $this->seed([
+ OrderStatusSeeder::class,
+ TransactionStatusSeeder::class,
// ...
-
- // Run an array of specific seeders...
- $this->seed([
- OrderStatusSeeder::class,
- TransactionStatusSeeder::class,
- // ...
- ]);
- }
+ ]);
}
+}
+```
Alternatively, you may instruct Laravel to automatically seed the database before each test that uses the `RefreshDatabase` trait. You may accomplish this by defining a `$seed` property on your base test class:
-
## Available Assertions
-Laravel provides several database assertions for your [PHPUnit](https://phpunit.de/) feature tests. We'll discuss each of these assertions below.
+Laravel provides several database assertions for your [Pest](https://pestphp.com) or [PHPUnit](https://phpunit.de) feature tests. We'll discuss each of these assertions below.
#### assertDatabaseCount
Assert that a table in the database contains the given number of records:
- $this->assertDatabaseCount('users', 5);
+```php
+$this->assertDatabaseCount('users', 5);
+```
+
+
+#### assertDatabaseEmpty
+
+Assert that a table in the database contains no records:
+
+```php
+$this->assertDatabaseEmpty('users');
+```
#### assertDatabaseHas
Assert that a table in the database contains records matching the given key / value query constraints:
- $this->assertDatabaseHas('users', [
- 'email' => 'sally@example.com',
- ]);
+```php
+$this->assertDatabaseHas('users', [
+ 'email' => 'sally@example.com',
+]);
+```
#### assertDatabaseMissing
Assert that a table in the database does not contain records matching the given key / value query constraints:
- $this->assertDatabaseMissing('users', [
- 'email' => 'sally@example.com',
- ]);
+```php
+$this->assertDatabaseMissing('users', [
+ 'email' => 'sally@example.com',
+]);
+```
#### assertSoftDeleted
The `assertSoftDeleted` method may be used to assert a given Eloquent model has been "soft deleted":
- $this->assertSoftDeleted($user);
+```php
+$this->assertSoftDeleted($user);
+```
+
+
+#### assertNotSoftDeleted
+
+The `assertNotSoftDeleted` method may be used to assert a given Eloquent model hasn't been "soft deleted":
+
+```php
+$this->assertNotSoftDeleted($user);
+```
#### assertModelExists
-Assert that a given model exists in the database:
+Assert that a given model or collection of models exist in the database:
- use App\Models\User;
+```php
+use App\Models\User;
- $user = User::factory()->create();
+$user = User::factory()->create();
- $this->assertModelExists($user);
+$this->assertModelExists($user);
+```
#### assertModelMissing
-Assert that a given model does not exist in the database:
+Assert that a given model or collection of models do not exist in the database:
- use App\Models\User;
+```php
+use App\Models\User;
- $user = User::factory()->create();
+$user = User::factory()->create();
- $user->delete();
+$user->delete();
- $this->assertModelMissing($user);
+$this->assertModelMissing($user);
+```
+
+
+#### expectsDatabaseQueryCount
+
+The `expectsDatabaseQueryCount` method may be invoked at the beginning of your test to specify the total number of database queries that you expect to be run during the test. If the actual number of executed queries does not exactly match this expectation, the test will fail:
+
+```php
+$this->expectsDatabaseQueryCount(5);
+
+// Test...
+```
diff --git a/database.md b/database.md
index 26553e78656..040145ef7ec 100644
--- a/database.md
+++ b/database.md
@@ -2,27 +2,33 @@
- [Introduction](#introduction)
- [Configuration](#configuration)
- - [Read & Write Connections](#read-and-write-connections)
+ - [Read and Write Connections](#read-and-write-connections)
- [Running SQL Queries](#running-queries)
- [Using Multiple Database Connections](#using-multiple-database-connections)
- - [Listening For Query Events](#listening-for-query-events)
+ - [Listening for Query Events](#listening-for-query-events)
+ - [Monitoring Cumulative Query Time](#monitoring-cumulative-query-time)
- [Database Transactions](#database-transactions)
-- [Connecting To The Database CLI](#connecting-to-the-database-cli)
+- [Connecting to the Database CLI](#connecting-to-the-database-cli)
+- [Inspecting Your Databases](#inspecting-your-databases)
+- [Monitoring Your Databases](#monitoring-your-databases)
## Introduction
-Almost every modern web application interacts with a database. Laravel makes interacting with databases extremely simple across a variety of supported databases using raw SQL, a [fluent query builder](/docs/{{version}}/queries), and the [Eloquent ORM](/docs/{{version}}/eloquent). Currently, Laravel provides first-party support for four databases:
+Almost every modern web application interacts with a database. Laravel makes interacting with databases extremely simple across a variety of supported databases using raw SQL, a [fluent query builder](/docs/{{version}}/queries), and the [Eloquent ORM](/docs/{{version}}/eloquent). Currently, Laravel provides first-party support for five databases:
+- MariaDB 10.3+ ([Version Policy](https://mariadb.org/about/#maintenance-policy))
- MySQL 5.7+ ([Version Policy](https://en.wikipedia.org/wiki/MySQL#Release_history))
-- PostgreSQL 9.6+ ([Version Policy](https://www.postgresql.org/support/versioning/))
-- SQLite 3.8.8+
+- PostgreSQL 10.0+ ([Version Policy](https://www.postgresql.org/support/versioning/))
+- SQLite 3.26.0+
- SQL Server 2017+ ([Version Policy](https://docs.microsoft.com/en-us/lifecycle/products/?products=sql-server))
+Additionally, MongoDB is supported via the `mongodb/laravel-mongodb` package, which is officially maintained by MongoDB. Check out the [Laravel MongoDB](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/) documentation for more information.
+
### Configuration
@@ -40,12 +46,15 @@ DB_CONNECTION=sqlite
DB_DATABASE=/absolute/path/to/database.sqlite
```
-To enable foreign key constraints for SQLite connections, you should set the `DB_FOREIGN_KEYS` environment variable to `true`:
+By default, foreign key constraints are enabled for SQLite connections. If you would like to disable them, you should set the `DB_FOREIGN_KEYS` environment variable to `false`:
```ini
-DB_FOREIGN_KEYS=true
+DB_FOREIGN_KEYS=false
```
+> [!NOTE]
+> If you use the [Laravel installer](/docs/{{version}}/installation#creating-a-laravel-project) to create your Laravel application and select SQLite as your database, Laravel will automatically create a `database/database.sqlite` file and run the default [database migrations](/docs/{{version}}/migrations) for you.
+
#### Microsoft SQL Server Configuration
@@ -68,36 +77,45 @@ These URLs typically follow a standard schema convention:
driver://username:password@host:port/database?options
```
-For convenience, Laravel supports these URLs as an alternative to configuring your database with multiple configuration options. If the `url` (or corresponding `DATABASE_URL` environment variable) configuration option is present, it will be used to extract the database connection and credential information.
+For convenience, Laravel supports these URLs as an alternative to configuring your database with multiple configuration options. If the `url` (or corresponding `DB_URL` environment variable) configuration option is present, it will be used to extract the database connection and credential information.
-### Read & Write Connections
+### Read and Write Connections
Sometimes you may wish to use one database connection for SELECT statements, and another for INSERT, UPDATE, and DELETE statements. Laravel makes this a breeze, and the proper connections will always be used whether you are using raw queries, the query builder, or the Eloquent ORM.
To see how read / write connections should be configured, let's look at this example:
- 'mysql' => [
- 'read' => [
- 'host' => [
- '192.168.1.1',
- '196.168.1.2',
- ],
+```php
+'mysql' => [
+ 'read' => [
+ 'host' => [
+ '192.168.1.1',
+ '196.168.1.2',
],
- 'write' => [
- 'host' => [
- '196.168.1.3',
- ],
+ ],
+ 'write' => [
+ 'host' => [
+ '196.168.1.3',
],
- 'sticky' => true,
- 'driver' => 'mysql',
- 'database' => 'database',
- 'username' => 'root',
- 'password' => '',
- 'charset' => 'utf8mb4',
- 'collation' => 'utf8mb4_unicode_ci',
- 'prefix' => '',
],
+ 'sticky' => true,
+
+ 'database' => env('DB_DATABASE', 'laravel'),
+ 'username' => env('DB_USERNAME', 'root'),
+ 'password' => env('DB_PASSWORD', ''),
+ 'unix_socket' => env('DB_SOCKET', ''),
+ 'charset' => env('DB_CHARSET', 'utf8mb4'),
+ 'collation' => env('DB_COLLATION', 'utf8mb4_unicode_ci'),
+ 'prefix' => '',
+ 'prefix_indexes' => true,
+ 'strict' => true,
+ 'engine' => null,
+ 'options' => extension_loaded('pdo_mysql') ? array_filter([
+ PDO::MYSQL_ATTR_SSL_CA => env('MYSQL_ATTR_SSL_CA'),
+ ]) : [],
+],
+```
Note that three keys have been added to the configuration array: `read`, `write` and `sticky`. The `read` and `write` keys have array values containing a single key: `host`. The rest of the database options for the `read` and `write` connections will be merged from the main `mysql` configuration array.
@@ -114,103 +132,142 @@ The `sticky` option is an *optional* value that can be used to allow the immedia
Once you have configured your database connection, you may run queries using the `DB` facade. The `DB` facade provides methods for each type of query: `select`, `update`, `insert`, `delete`, and `statement`.
-#### Running A Select Query
+#### Running a Select Query
To run a basic SELECT query, you may use the `select` method on the `DB` facade:
- $users]);
- }
+ $users = DB::select('select * from users where active = ?', [1]);
+
+ return view('user.index', ['users' => $users]);
}
+}
+```
The first argument passed to the `select` method is the SQL query, while the second argument is any parameter bindings that need to be bound to the query. Typically, these are the values of the `where` clause constraints. Parameter binding provides protection against SQL injection.
The `select` method will always return an `array` of results. Each result within the array will be a PHP `stdClass` object representing a record from the database:
- use Illuminate\Support\Facades\DB;
+```php
+use Illuminate\Support\Facades\DB;
- $users = DB::select('select * from users');
+$users = DB::select('select * from users');
- foreach ($users as $user) {
- echo $user->name;
- }
+foreach ($users as $user) {
+ echo $user->name;
+}
+```
+
+
+#### Selecting Scalar Values
+
+Sometimes your database query may result in a single, scalar value. Instead of being required to retrieve the query's scalar result from a record object, Laravel allows you to retrieve this value directly using the `scalar` method:
+
+```php
+$burgers = DB::scalar(
+ "select count(case when food = 'burger' then 1 end) as burgers from menu"
+);
+```
+
+
+#### Selecting Multiple Result Sets
+
+If your application calls stored procedures that return multiple result sets, you may use the `selectResultSets` method to retrieve all of the result sets returned by the stored procedure:
+
+```php
+[$options, $notifications] = DB::selectResultSets(
+ "CALL get_user_options_and_notifications(?)", $request->user()->id
+);
+```
#### Using Named Bindings
Instead of using `?` to represent your parameter bindings, you may execute a query using named bindings:
- $results = DB::select('select * from users where id = :id', ['id' => 1]);
+```php
+$results = DB::select('select * from users where id = :id', ['id' => 1]);
+```
-#### Running An Insert Statement
+#### Running an Insert Statement
To execute an `insert` statement, you may use the `insert` method on the `DB` facade. Like `select`, this method accepts the SQL query as its first argument and bindings as its second argument:
- use Illuminate\Support\Facades\DB;
+```php
+use Illuminate\Support\Facades\DB;
- DB::insert('insert into users (id, name) values (?, ?)', [1, 'Marc']);
+DB::insert('insert into users (id, name) values (?, ?)', [1, 'Marc']);
+```
-#### Running An Update Statement
+#### Running an Update Statement
The `update` method should be used to update existing records in the database. The number of rows affected by the statement is returned by the method:
- use Illuminate\Support\Facades\DB;
+```php
+use Illuminate\Support\Facades\DB;
- $affected = DB::update(
- 'update users set votes = 100 where name = ?',
- ['Anita']
- );
+$affected = DB::update(
+ 'update users set votes = 100 where name = ?',
+ ['Anita']
+);
+```
-#### Running A Delete Statement
+#### Running a Delete Statement
The `delete` method should be used to delete records from the database. Like `update`, the number of rows affected will be returned by the method:
- use Illuminate\Support\Facades\DB;
+```php
+use Illuminate\Support\Facades\DB;
- $deleted = DB::delete('delete from users');
+$deleted = DB::delete('delete from users');
+```
-#### Running A General Statement
+#### Running a General Statement
Some database statements do not return any value. For these types of operations, you may use the `statement` method on the `DB` facade:
- DB::statement('drop table users');
+```php
+DB::statement('drop table users');
+```
-#### Running An Unprepared Statement
+#### Running an Unprepared Statement
Sometimes you may want to execute an SQL statement without binding any values. You may use the `DB` facade's `unprepared` method to accomplish this:
- DB::unprepared('update users set votes = 100 where name = "Dries"');
+```php
+DB::unprepared('update users set votes = 100 where name = "Dries"');
+```
-> {note} Since unprepared statements do not bind parameters, they may be vulnerable to SQL injection. You should never allow user controlled values within an unprepared statement.
+> [!WARNING]
+> Since unprepared statements do not bind parameters, they may be vulnerable to SQL injection. You should never allow user controlled values within an unprepared statement.
#### Implicit Commits
When using the `DB` facade's `statement` and `unprepared` methods within transactions you must be careful to avoid statements that cause [implicit commits](https://dev.mysql.com/doc/refman/8.0/en/implicit-commit.html). These statements will cause the database engine to indirectly commit the entire transaction, leaving Laravel unaware of the database's transaction level. An example of such a statement is creating a database table:
- DB::unprepared('create table a (col varchar(1) null)');
+```php
+DB::unprepared('create table a (col varchar(1) null)');
+```
Please refer to the MySQL manual for [a list of all statements](https://dev.mysql.com/doc/refman/8.0/en/implicit-commit.html) that trigger implicit commits.
@@ -219,100 +276,152 @@ Please refer to the MySQL manual for [a list of all statements](https://dev.mysq
If your application defines multiple connections in your `config/database.php` configuration file, you may access each connection via the `connection` method provided by the `DB` facade. The connection name passed to the `connection` method should correspond to one of the connections listed in your `config/database.php` configuration file or configured at runtime using the `config` helper:
- use Illuminate\Support\Facades\DB;
+```php
+use Illuminate\Support\Facades\DB;
- $users = DB::connection('sqlite')->select(...);
+$users = DB::connection('sqlite')->select(/* ... */);
+```
You may access the raw, underlying PDO instance of a connection using the `getPdo` method on a connection instance:
- $pdo = DB::connection()->getPdo();
+```php
+$pdo = DB::connection()->getPdo();
+```
-### Listening For Query Events
+### Listening for Query Events
If you would like to specify a closure that is invoked for each SQL query executed by your application, you may use the `DB` facade's `listen` method. This method can be useful for logging queries or debugging. You may register your query listener closure in the `boot` method of a [service provider](/docs/{{version}}/providers):
- sql;
+ // $query->bindings;
+ // $query->time;
+ // $query->toRawSql();
+ });
+ }
+}
+```
+
+
+### Monitoring Cumulative Query Time
- namespace App\Providers;
+A common performance bottleneck of modern web applications is the amount of time they spend querying databases. Thankfully, Laravel can invoke a closure or callback of your choice when it spends too much time querying the database during a single request. To get started, provide a query time threshold (in milliseconds) and closure to the `whenQueryingForLongerThan` method. You may invoke this method in the `boot` method of a [service provider](/docs/{{version}}/providers):
- use Illuminate\Support\Facades\DB;
- use Illuminate\Support\ServiceProvider;
+```php
+sql;
- // $query->bindings;
- // $query->time;
- });
- }
+ DB::whenQueryingForLongerThan(500, function (Connection $connection, QueryExecuted $event) {
+ // Notify development team...
+ });
}
+}
+```
## Database Transactions
You may use the `transaction` method provided by the `DB` facade to run a set of operations within a database transaction. If an exception is thrown within the transaction closure, the transaction will automatically be rolled back and the exception is re-thrown. If the closure executes successfully, the transaction will automatically be committed. You don't need to worry about manually rolling back or committing while using the `transaction` method:
- use Illuminate\Support\Facades\DB;
+```php
+use Illuminate\Support\Facades\DB;
- DB::transaction(function () {
- DB::update('update users set votes = 1');
+DB::transaction(function () {
+ DB::update('update users set votes = 1');
- DB::delete('delete from posts');
- });
+ DB::delete('delete from posts');
+});
+```
#### Handling Deadlocks
The `transaction` method accepts an optional second argument which defines the number of times a transaction should be retried when a deadlock occurs. Once these attempts have been exhausted, an exception will be thrown:
- use Illuminate\Support\Facades\DB;
+```php
+use Illuminate\Support\Facades\DB;
- DB::transaction(function () {
- DB::update('update users set votes = 1');
+DB::transaction(function () {
+ DB::update('update users set votes = 1');
- DB::delete('delete from posts');
- }, 5);
+ DB::delete('delete from posts');
+}, attempts: 5);
+```
#### Manually Using Transactions
If you would like to begin a transaction manually and have complete control over rollbacks and commits, you may use the `beginTransaction` method provided by the `DB` facade:
- use Illuminate\Support\Facades\DB;
+```php
+use Illuminate\Support\Facades\DB;
- DB::beginTransaction();
+DB::beginTransaction();
+```
You can rollback the transaction via the `rollBack` method:
- DB::rollBack();
+```php
+DB::rollBack();
+```
Lastly, you can commit a transaction via the `commit` method:
- DB::commit();
+```php
+DB::commit();
+```
-> {tip} The `DB` facade's transaction methods control the transactions for both the [query builder](/docs/{{version}}/queries) and [Eloquent ORM](/docs/{{version}}/eloquent).
+> [!NOTE]
+> The `DB` facade's transaction methods control the transactions for both the [query builder](/docs/{{version}}/queries) and [Eloquent ORM](/docs/{{version}}/eloquent).
-## Connecting To The Database CLI
+## Connecting to the Database CLI
If you would like to connect to your database's CLI, you may use the `db` Artisan command:
@@ -326,3 +435,84 @@ If needed, you may specify a database connection name to connect to a database c
php artisan db mysql
```
+
+## Inspecting Your Databases
+
+Using the `db:show` and `db:table` Artisan commands, you can get valuable insight into your database and its associated tables. To see an overview of your database, including its size, type, number of open connections, and a summary of its tables, you may use the `db:show` command:
+
+```shell
+php artisan db:show
+```
+
+You may specify which database connection should be inspected by providing the database connection name to the command via the `--database` option:
+
+```shell
+php artisan db:show --database=pgsql
+```
+
+If you would like to include table row counts and database view details within the output of the command, you may provide the `--counts` and `--views` options, respectively. On large databases, retrieving row counts and view details can be slow:
+
+```shell
+php artisan db:show --counts --views
+```
+
+In addition, you may use the following `Schema` methods to inspect your database:
+
+```php
+use Illuminate\Support\Facades\Schema;
+
+$tables = Schema::getTables();
+$views = Schema::getViews();
+$columns = Schema::getColumns('users');
+$indexes = Schema::getIndexes('users');
+$foreignKeys = Schema::getForeignKeys('users');
+```
+
+If you would like to inspect a database connection that is not your application's default connection, you may use the `connection` method:
+
+```php
+$columns = Schema::connection('sqlite')->getColumns('users');
+```
+
+
+#### Table Overview
+
+If you would like to get an overview of an individual table within your database, you may execute the `db:table` Artisan command. This command provides a general overview of a database table, including its columns, types, attributes, keys, and indexes:
+
+```shell
+php artisan db:table users
+```
+
+
+## Monitoring Your Databases
+
+Using the `db:monitor` Artisan command, you can instruct Laravel to dispatch an `Illuminate\Database\Events\DatabaseBusy` event if your database is managing more than a specified number of open connections.
+
+To get started, you should schedule the `db:monitor` command to [run every minute](/docs/{{version}}/scheduling). The command accepts the names of the database connection configurations that you wish to monitor as well as the maximum number of open connections that should be tolerated before dispatching an event:
+
+```shell
+php artisan db:monitor --databases=mysql,pgsql --max=100
+```
+
+Scheduling this command alone is not enough to trigger a notification alerting you of the number of open connections. When the command encounters a database that has an open connection count that exceeds your threshold, a `DatabaseBusy` event will be dispatched. You should listen for this event within your application's `AppServiceProvider` in order to send a notification to you or your development team:
+
+```php
+use App\Notifications\DatabaseApproachingMaxConnections;
+use Illuminate\Database\Events\DatabaseBusy;
+use Illuminate\Support\Facades\Event;
+use Illuminate\Support\Facades\Notification;
+
+/**
+ * Bootstrap any application services.
+ */
+public function boot(): void
+{
+ Event::listen(function (DatabaseBusy $event) {
+ Notification::route('mail', 'dev@example.com')
+ ->notify(new DatabaseApproachingMaxConnections(
+ $event->connectionName,
+ $event->connections
+ ));
+ });
+}
+```
diff --git a/deployment.md b/deployment.md
index 5f67cef82af..292e0be0221 100644
--- a/deployment.md
+++ b/deployment.md
@@ -4,13 +4,16 @@
- [Server Requirements](#server-requirements)
- [Server Configuration](#server-configuration)
- [Nginx](#nginx)
+ - [FrankenPHP](#frankenphp)
+ - [Directory Permissions](#directory-permissions)
- [Optimization](#optimization)
- - [Autoloader Optimization](#autoloader-optimization)
- - [Optimizing Configuration Loading](#optimizing-configuration-loading)
- - [Optimizing Route Loading](#optimizing-route-loading)
- - [Optimizing View Loading](#optimizing-view-loading)
+ - [Caching Configuration](#optimizing-configuration-loading)
+ - [Caching Events](#caching-events)
+ - [Caching Routes](#optimizing-route-loading)
+ - [Caching Views](#optimizing-view-loading)
- [Debug Mode](#debug-mode)
-- [Deploying With Forge / Vapor](#deploying-with-forge-or-vapor)
+- [The Health Route](#the-health-route)
+- [Deploying With Laravel Cloud or Forge](#deploying-with-cloud-or-forge)
## Introduction
@@ -24,16 +27,18 @@ The Laravel framework has a few system requirements. You should ensure that your
-- PHP >= 8.0
-- BCMath PHP Extension
+- PHP >= 8.2
- Ctype PHP Extension
+- cURL PHP Extension
- DOM PHP Extension
- Fileinfo PHP Extension
-- JSON PHP Extension
+- Filter PHP Extension
+- Hash PHP Extension
- Mbstring PHP Extension
- OpenSSL PHP Extension
- PCRE PHP Extension
- PDO PHP Extension
+- Session PHP Extension
- Tokenizer PHP Extension
- XML PHP Extension
@@ -45,7 +50,7 @@ The Laravel framework has a few system requirements. You should ensure that your
### Nginx
-If you are deploying your application to a server that is running Nginx, you may use the following configuration file as a starting point for configuring your web server. Most likely, this file will need to be customized depending on your server's configuration. **If you would like assistance in managing your server, consider using a first-party Laravel server management and deployment service such as [Laravel Forge](https://forge.laravel.com).**
+If you are deploying your application to a server that is running Nginx, you may use the following configuration file as a starting point for configuring your web server. Most likely, this file will need to be customized depending on your server's configuration. **If you would like assistance in managing your server, consider using a fully-managed Laravel platform like [Laravel Cloud](https://cloud.laravel.com).**
Please ensure, like the configuration below, your web server directs all requests to your application's `public/index.php` file. You should never attempt to move the `index.php` file to your project's root, as serving the application from the project root will expose many sensitive configuration files to the public Internet:
@@ -72,10 +77,11 @@ server {
error_page 404 /index.php;
- location ~ \.php$ {
- fastcgi_pass unix:/var/run/php/php8.0-fpm.sock;
+ location ~ ^/index\.php(/|$) {
+ fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
include fastcgi_params;
+ fastcgi_hide_header X-Powered-By;
}
location ~ /\.(?!well-known).* {
@@ -84,22 +90,41 @@ server {
}
```
+
+### FrankenPHP
+
+[FrankenPHP](https://frankenphp.dev/) may also be used to serve your Laravel applications. FrankenPHP is a modern PHP application server written in Go. To serve a Laravel PHP application using FrankenPHP, you may simply invoke its `php-server` command:
+
+```shell
+frankenphp php-server -r public/
+```
+
+To take advantage of more powerful features supported by FrankenPHP, such as its [Laravel Octane](/docs/{{version}}/octane) integration, HTTP/3, modern compression, or the ability to package Laravel applications as standalone binaries, please consult FrankenPHP's [Laravel documentation](https://frankenphp.dev/docs/laravel/).
+
+
+### Directory Permissions
+
+Laravel will need to write to the `bootstrap/cache` and `storage` directories, so you should ensure the web server process owner has permission to write to these directories.
+
## Optimization
-
-### Autoloader Optimization
+When deploying your application to production, there are a variety of files that should be cached, including your configuration, events, routes, and views. Laravel provides a single, convenient `optimize` Artisan command that will cache all of these files. This command should typically be invoked as part of your application's deployment process:
+
+```shell
+php artisan optimize
+```
-When deploying to production, make sure that you are optimizing Composer's class autoloader map so Composer can quickly find the proper file to load for a given class:
+The `optimize:clear` method may be used to remove all of the cache files generated by the `optimize` command as well as all keys in the default cache driver:
```shell
-composer install --optimize-autoloader --no-dev
+php artisan optimize:clear
```
-> {tip} In addition to optimizing the autoloader, you should always be sure to include a `composer.lock` file in your project's source control repository. Your project's dependencies can be installed much faster when a `composer.lock` file is present.
+In the following documentation, we will discuss each of the granular optimization commands that are executed by the `optimize` command.
-### Optimizing Configuration Loading
+### Caching Configuration
When deploying your application to production, you should make sure that you run the `config:cache` Artisan command during your deployment process:
@@ -109,10 +134,20 @@ php artisan config:cache
This command will combine all of Laravel's configuration files into a single, cached file, which greatly reduces the number of trips the framework must make to the filesystem when loading your configuration values.
-> {note} If you execute the `config:cache` command during your deployment process, you should be sure that you are only calling the `env` function from within your configuration files. Once the configuration has been cached, the `.env` file will not be loaded and all calls to the `env` function for `.env` variables will return `null`.
+> [!WARNING]
+> If you execute the `config:cache` command during your deployment process, you should be sure that you are only calling the `env` function from within your configuration files. Once the configuration has been cached, the `.env` file will not be loaded and all calls to the `env` function for `.env` variables will return `null`.
+
+
+### Caching Events
+
+You should cache your application's auto-discovered event to listener mappings during your deployment process. This can be accomplished by invoking the `event:cache` Artisan command during deployment:
+
+```shell
+php artisan event:cache
+```
-### Optimizing Route Loading
+### Caching Routes
If you are building a large application with many routes, you should make sure that you are running the `route:cache` Artisan command during your deployment process:
@@ -123,7 +158,7 @@ php artisan route:cache
This command reduces all of your route registrations into a single method call within a cached file, improving the performance of route registration when registering hundreds of routes.
-### Optimizing View Loading
+### Caching Views
When deploying your application to production, you should make sure that you run the `view:cache` Artisan command during your deployment process:
@@ -136,21 +171,42 @@ This command precompiles all your Blade views so they are not compiled on demand
## Debug Mode
-The debug option in your config/app.php configuration file determines how much information about an error is actually displayed to the user. By default, this option is set to respect the value of the APP_DEBUG environment variable, which is stored in your .env file.
+The debug option in your `config/app.php` configuration file determines how much information about an error is actually displayed to the user. By default, this option is set to respect the value of the `APP_DEBUG` environment variable, which is stored in your application's `.env` file.
+
+> [!WARNING]
+> **In your production environment, this value should always be `false`. If the `APP_DEBUG` variable is set to `true` in production, you risk exposing sensitive configuration values to your application's end users.**
+
+
+## The Health Route
-**In your production environment, this value should always be `false`. If the `APP_DEBUG` variable is set to `true` in production, you risk exposing sensitive configuration values to your application's end users.**
+Laravel includes a built-in health check route that can be used to monitor the status of your application. In production, this route may be used to report the status of your application to an uptime monitor, load balancer, or orchestration system such as Kubernetes.
+
+By default, the health check route is served at `/up` and will return a 200 HTTP response if the application has booted without exceptions. Otherwise, a 500 HTTP response will be returned. You may configure the URI for this route in your application's `bootstrap/app` file:
+
+```php
+->withRouting(
+ web: __DIR__.'/../routes/web.php',
+ commands: __DIR__.'/../routes/console.php',
+ health: '/up', // [tl! remove]
+ health: '/status', // [tl! add]
+)
+```
-
-## Deploying With Forge / Vapor
+When HTTP requests are made to this route, Laravel will also dispatch a `Illuminate\Foundation\Events\DiagnosingHealth` event, allowing you to perform additional health checks relevant to your application. Within a [listener](/docs/{{version}}/events) for this event, you may check your application's database or cache status. If you detect a problem with your application, you may simply throw an exception from the listener.
+
+
+## Deploying With Laravel Cloud or Forge
+
+
+#### Laravel Cloud
+
+If you would like a fully-managed, auto-scaling deployment platform tuned for Laravel, check out [Laravel Cloud](https://cloud.laravel.com). Laravel Cloud is a robust deployment platform for Laravel, offering managed compute, databases, caches, and object storage.
+
+Launch your Laravel application on Cloud and fall in love with the scalable simplicity. Laravel Cloud is fine-tuned by Laravel's creators to work seamlessly with the framework so you can keep writing your Laravel applications exactly like you're used to.
#### Laravel Forge
-If you aren't quite ready to manage your own server configuration or aren't comfortable configuring all of the various services needed to run a robust Laravel application, [Laravel Forge](https://forge.laravel.com) is a wonderful alternative.
+If you prefer to manage your own servers but aren't comfortable configuring all of the various services needed to run a robust Laravel application, [Laravel Forge](https://forge.laravel.com) is a VPS server management platform for Laravel applications.
Laravel Forge can create servers on various infrastructure providers such as DigitalOcean, Linode, AWS, and more. In addition, Forge installs and manages all of the tools needed to build robust Laravel applications, such as Nginx, MySQL, Redis, Memcached, Beanstalk, and more.
-
-
-#### Laravel Vapor
-
-If you would like a totally serverless, auto-scaling deployment platform tuned for Laravel, check out [Laravel Vapor](https://vapor.laravel.com). Laravel Vapor is a serverless deployment platform for Laravel, powered by AWS. Launch your Laravel infrastructure on Vapor and fall in love with the scalable simplicity of serverless. Laravel Vapor is fine-tuned by Laravel's creators to work seamlessly with the framework so you can keep writing your Laravel applications exactly like you're used to.
diff --git a/documentation.md b/documentation.md
index 5da7f822cba..933c8531f59 100644
--- a/documentation.md
+++ b/documentation.md
@@ -6,6 +6,7 @@
- [Installation](/docs/{{version}}/installation)
- [Configuration](/docs/{{version}}/configuration)
- [Directory Structure](/docs/{{version}}/structure)
+ - [Frontend](/docs/{{version}}/frontend)
- [Starter Kits](/docs/{{version}}/starter-kits)
- [Deployment](/docs/{{version}}/deployment)
- ## Architecture Concepts
@@ -22,6 +23,7 @@
- [Responses](/docs/{{version}}/responses)
- [Views](/docs/{{version}}/views)
- [Blade Templates](/docs/{{version}}/blade)
+ - [Asset Bundling](/docs/{{version}}/vite)
- [URL Generation](/docs/{{version}}/urls)
- [Session](/docs/{{version}}/session)
- [Validation](/docs/{{version}}/validation)
@@ -32,7 +34,8 @@
- [Broadcasting](/docs/{{version}}/broadcasting)
- [Cache](/docs/{{version}}/cache)
- [Collections](/docs/{{version}}/collections)
- - [Compiling Assets](/docs/{{version}}/mix)
+ - [Concurrency](/docs/{{version}}/concurrency)
+ - [Context](/docs/{{version}}/context)
- [Contracts](/docs/{{version}}/contracts)
- [Events](/docs/{{version}}/events)
- [File Storage](/docs/{{version}}/filesystem)
@@ -42,8 +45,10 @@
- [Mail](/docs/{{version}}/mail)
- [Notifications](/docs/{{version}}/notifications)
- [Package Development](/docs/{{version}}/packages)
+ - [Processes](/docs/{{version}}/processes)
- [Queues](/docs/{{version}}/queues)
- [Rate Limiting](/docs/{{version}}/rate-limiting)
+ - [Strings](/docs/{{version}}/strings)
- [Task Scheduling](/docs/{{version}}/scheduling)
- ## Security
- [Authentication](/docs/{{version}}/authentication)
@@ -59,6 +64,7 @@
- [Migrations](/docs/{{version}}/migrations)
- [Seeding](/docs/{{version}}/seeding)
- [Redis](/docs/{{version}}/redis)
+ - [MongoDB](/docs/{{version}}/mongodb)
- ## Eloquent ORM
- [Getting Started](/docs/{{version}}/eloquent)
- [Relationships](/docs/{{version}}/eloquent-relationships)
@@ -66,6 +72,7 @@
- [Mutators / Casts](/docs/{{version}}/eloquent-mutators)
- [API Resources](/docs/{{version}}/eloquent-resources)
- [Serialization](/docs/{{version}}/eloquent-serialization)
+ - [Factories](/docs/{{version}}/eloquent-factories)
- ## Testing
- [Getting Started](/docs/{{version}}/testing)
- [HTTP Tests](/docs/{{version}}/http-tests)
@@ -74,21 +81,28 @@
- [Database](/docs/{{version}}/database-testing)
- [Mocking](/docs/{{version}}/mocking)
- ## Packages
- - [Breeze](/docs/{{version}}/starter-kits#laravel-breeze)
- [Cashier (Stripe)](/docs/{{version}}/billing)
- [Cashier (Paddle)](/docs/{{version}}/cashier-paddle)
- [Dusk](/docs/{{version}}/dusk)
- [Envoy](/docs/{{version}}/envoy)
- [Fortify](/docs/{{version}}/fortify)
+ - [Folio](/docs/{{version}}/folio)
- [Homestead](/docs/{{version}}/homestead)
- [Horizon](/docs/{{version}}/horizon)
- - [Jetstream](https://jetstream.laravel.com)
+ - [MCP](/docs/{{version}}/mcp)
+ - [Mix](/docs/{{version}}/mix)
- [Octane](/docs/{{version}}/octane)
- [Passport](/docs/{{version}}/passport)
+ - [Pennant](/docs/{{version}}/pennant)
+ - [Pint](/docs/{{version}}/pint)
+ - [Precognition](/docs/{{version}}/precognition)
+ - [Prompts](/docs/{{version}}/prompts)
+ - [Pulse](/docs/{{version}}/pulse)
+ - [Reverb](/docs/{{version}}/reverb)
- [Sail](/docs/{{version}}/sail)
- [Sanctum](/docs/{{version}}/sanctum)
- [Scout](/docs/{{version}}/scout)
- [Socialite](/docs/{{version}}/socialite)
- [Telescope](/docs/{{version}}/telescope)
- [Valet](/docs/{{version}}/valet)
-- [API Documentation](/api/9.x)
+- [API Documentation](https://api.laravel.com/docs/12.x)
diff --git a/dusk.md b/dusk.md
index 7990b33cbc5..4cd5416a295 100644
--- a/dusk.md
+++ b/dusk.md
@@ -6,7 +6,7 @@
- [Using Other Browsers](#using-other-browsers)
- [Getting Started](#getting-started)
- [Generating Tests](#generating-tests)
- - [Database Migrations](#migrations)
+ - [Resetting the Database After Each Test](#resetting-the-database-after-each-test)
- [Running Tests](#running-tests)
- [Environment Handling](#environment-handling)
- [Browser Basics](#browser-basics)
@@ -17,27 +17,28 @@
- [Authentication](#authentication)
- [Cookies](#cookies)
- [Executing JavaScript](#executing-javascript)
- - [Taking A Screenshot](#taking-a-screenshot)
- - [Storing Console Output To Disk](#storing-console-output-to-disk)
- - [Storing Page Source To Disk](#storing-page-source-to-disk)
+ - [Taking a Screenshot](#taking-a-screenshot)
+ - [Storing Console Output to Disk](#storing-console-output-to-disk)
+ - [Storing Page Source to Disk](#storing-page-source-to-disk)
- [Interacting With Elements](#interacting-with-elements)
- [Dusk Selectors](#dusk-selectors)
- - [Text, Values, & Attributes](#text-values-and-attributes)
+ - [Text, Values, and Attributes](#text-values-and-attributes)
- [Interacting With Forms](#interacting-with-forms)
- [Attaching Files](#attaching-files)
- [Pressing Buttons](#pressing-buttons)
- [Clicking Links](#clicking-links)
- - [Using The Keyboard](#using-the-keyboard)
- - [Using The Mouse](#using-the-mouse)
+ - [Using the Keyboard](#using-the-keyboard)
+ - [Using the Mouse](#using-the-mouse)
- [JavaScript Dialogs](#javascript-dialogs)
+ - [Interacting With Inline Frames](#interacting-with-iframes)
- [Scoping Selectors](#scoping-selectors)
- - [Waiting For Elements](#waiting-for-elements)
- - [Scrolling An Element Into View](#scrolling-an-element-into-view)
+ - [Waiting for Elements](#waiting-for-elements)
+ - [Scrolling an Element Into View](#scrolling-an-element-into-view)
- [Available Assertions](#available-assertions)
- [Pages](#pages)
- [Generating Pages](#generating-pages)
- [Configuring Pages](#configuring-pages)
- - [Navigating To Pages](#navigating-to-pages)
+ - [Navigating to Pages](#navigating-to-pages)
- [Shorthand Selectors](#shorthand-selectors)
- [Page Methods](#page-methods)
- [Components](#components)
@@ -47,10 +48,14 @@
- [Heroku CI](#running-tests-on-heroku-ci)
- [Travis CI](#running-tests-on-travis-ci)
- [GitHub Actions](#running-tests-on-github-actions)
+ - [Chipper CI](#running-tests-on-chipper-ci)
## Introduction
+> [!WARNING]
+> [Pest 4](https://pestphp.com/) now includes automated browser testing which offers significant performance and usability improvements compared to Laravel Dusk. For new projects, we recommend using Pest for browser testing.
+
[Laravel Dusk](https://github.com/laravel/dusk) provides an expressive, easy-to-use browser automation and testing API. By default, Dusk does not require you to install JDK or Selenium on your local computer. Instead, Dusk uses a standalone [ChromeDriver](https://sites.google.com/chromium.org/driver) installation. However, you are free to utilize any other Selenium compatible driver you wish.
@@ -59,12 +64,13 @@
To get started, you should install [Google Chrome](https://www.google.com/chrome) and add the `laravel/dusk` Composer dependency to your project:
```shell
-composer require --dev laravel/dusk
+composer require laravel/dusk --dev
```
-> {note} If you are manually registering Dusk's service provider, you should **never** register it in your production environment, as doing so could lead to arbitrary users being able to authenticate with your application.
+> [!WARNING]
+> If you are manually registering Dusk's service provider, you should **never** register it in your production environment, as doing so could lead to arbitrary users being able to authenticate with your application.
-After installing the Dusk package, execute the `dusk:install` Artisan command. The `dusk:install` command will create a `tests/Browser` directory and an example Dusk test:
+After installing the Dusk package, execute the `dusk:install` Artisan command. The `dusk:install` command will create a `tests/Browser` directory, an example Dusk test, and install the Chrome Driver binary for your operating system:
```shell
php artisan dusk:install
@@ -72,12 +78,13 @@ php artisan dusk:install
Next, set the `APP_URL` environment variable in your application's `.env` file. This value should match the URL you use to access your application in a browser.
-> {tip} If you are using [Laravel Sail](/docs/{{version}}/sail) to manage your local development environment, please also consult the Sail documentation on [configuring and running Dusk tests](/docs/{{version}}/sail#laravel-dusk).
+> [!NOTE]
+> If you are using [Laravel Sail](/docs/{{version}}/sail) to manage your local development environment, please also consult the Sail documentation on [configuring and running Dusk tests](/docs/{{version}}/sail#laravel-dusk).
### Managing ChromeDriver Installations
-If you would like to install a different version of ChromeDriver than what is included with Laravel Dusk, you may use the `dusk:chrome-driver` command:
+If you would like to install a different version of ChromeDriver than what is installed by Laravel Dusk via the `dusk:install` command, you may use the `dusk:chrome-driver` command:
```shell
# Install the latest version of ChromeDriver for your OS...
@@ -93,7 +100,8 @@ php artisan dusk:chrome-driver --all
php artisan dusk:chrome-driver --detect
```
-> {note} Dusk requires the `chromedriver` binaries to be executable. If you're having problems running Dusk, you should ensure the binaries are executable using the following command: `chmod -R 0755 vendor/laravel/dusk/bin/`.
+> [!WARNING]
+> Dusk requires the `chromedriver` binaries to be executable. If you're having problems running Dusk, you should ensure the binaries are executable using the following command: `chmod -R 0755 vendor/laravel/dusk/bin/`.
### Using Other Browsers
@@ -102,30 +110,33 @@ By default, Dusk uses Google Chrome and a standalone [ChromeDriver](https://site
To get started, open your `tests/DuskTestCase.php` file, which is the base Dusk test case for your application. Within this file, you can remove the call to the `startChromeDriver` method. This will stop Dusk from automatically starting the ChromeDriver:
- /**
- * Prepare for Dusk test execution.
- *
- * @beforeClass
- * @return void
- */
- public static function prepare()
- {
- // static::startChromeDriver();
- }
+```php
+/**
+ * Prepare for Dusk test execution.
+ *
+ * @beforeClass
+ */
+public static function prepare(): void
+{
+ // static::startChromeDriver();
+}
+```
Next, you may modify the `driver` method to connect to the URL and port of your choice. In addition, you may modify the "desired capabilities" that should be passed to the WebDriver:
- /**
- * Create the RemoteWebDriver instance.
- *
- * @return \Facebook\WebDriver\Remote\RemoteWebDriver
- */
- protected function driver()
- {
- return RemoteWebDriver::create(
- 'http://localhost:4444/wd/hub', DesiredCapabilities::phantomjs()
- );
- }
+```php
+use Facebook\WebDriver\Remote\RemoteWebDriver;
+
+/**
+ * Create the RemoteWebDriver instance.
+ */
+protected function driver(): RemoteWebDriver
+{
+ return RemoteWebDriver::create(
+ 'http://localhost:4444/wd/hub', DesiredCapabilities::phantomjs()
+ );
+}
+```
## Getting Started
@@ -139,26 +150,136 @@ To generate a Dusk test, use the `dusk:make` Artisan command. The generated test
php artisan dusk:make LoginTest
```
-
-### Database Migrations
+
+### Resetting the Database After Each Test
-Most of the tests you write will interact with pages that retrieve data from your application's database; however, your Dusk tests should never use the `RefreshDatabase `trait. The `RefreshDatabase` trait leverages database transactions which will not be applicable or available across HTTP requests. Instead, use the `DatabaseMigrations` trait, which re-migrates the database for each test:
+Most of the tests you write will interact with pages that retrieve data from your application's database; however, your Dusk tests should never use the `RefreshDatabase` trait. The `RefreshDatabase` trait leverages database transactions which will not be applicable or available across HTTP requests. Instead, you have two options: the `DatabaseMigrations` trait and the `DatabaseTruncation` trait.
-
+#### Using Database Migrations
- namespace Tests\Browser;
+The `DatabaseMigrations` trait will run your database migrations before each test. However, dropping and re-creating your database tables for each test is typically slower than truncating the tables:
- use App\Models\User;
- use Illuminate\Foundation\Testing\DatabaseMigrations;
- use Laravel\Dusk\Chrome;
- use Tests\DuskTestCase;
+```php tab=Pest
+use(DatabaseMigrations::class);
+
+//
+```
+
+```php tab=PHPUnit
+ [!WARNING]
+> SQLite in-memory databases may not be used when executing Dusk tests. Since the browser executes within its own process, it will not be able to access the in-memory databases of other processes.
+
+
+#### Using Database Truncation
+
+The `DatabaseTruncation` trait will migrate your database on the first test in order to ensure your database tables have been properly created. However, on subsequent tests, the database's tables will simply be truncated - providing a speed boost over re-running all of your database migrations:
+
+```php tab=Pest
+ {note} SQLite in-memory databases may not be used when executing Dusk tests. Since the browser executes within its own process, it will not be able to access the in-memory databases of other processes.
+pest()->use(DatabaseTruncation::class);
+
+//
+```
+
+```php tab=PHPUnit
+ [!NOTE]
+> If you are using Pest, you should define properties or methods on the base `DuskTestCase` class or on any class your test file extends.
+
+```php
+/**
+ * Indicates which tables should be truncated.
+ *
+ * @var array
+ */
+protected $tablesToTruncate = ['users'];
+```
+
+Alternatively, you may define an `$exceptTables` property on your test class to specify which tables should be excluded from truncation:
+
+```php
+/**
+ * Indicates which tables should be excluded from truncation.
+ *
+ * @var array
+ */
+protected $exceptTables = ['users'];
+```
+
+To specify the database connections that should have their tables truncated, you may define a `$connectionsToTruncate` property on your test class:
+
+```php
+/**
+ * Indicates which connections should have their tables truncated.
+ *
+ * @var array
+ */
+protected $connectionsToTruncate = ['mysql'];
+```
+
+If you would like to execute code before or after database truncation is performed, you may define `beforeTruncatingDatabase` or `afterTruncatingDatabase` methods on your test class:
+
+```php
+/**
+ * Perform any work that should take place before the database has started truncating.
+ */
+protected function beforeTruncatingDatabase(): void
+{
+ //
+}
+
+/**
+ * Perform any work that should take place after the database has finished truncating.
+ */
+protected function afterTruncatingDatabase(): void
+{
+ //
+}
+```
### Running Tests
@@ -175,43 +296,47 @@ If you had test failures the last time you ran the `dusk` command, you may save
php artisan dusk:fails
```
-The `dusk` command accepts any argument that is normally accepted by the PHPUnit test runner, such as allowing you to only run the tests for a given [group](https://phpunit.de/manual/current/en/appendixes.annotations.html#appendixes.annotations.group):
+The `dusk` command accepts any argument that is normally accepted by the Pest / PHPUnit test runner, such as allowing you to only run the tests for a given [group](https://docs.phpunit.de/en/10.5/annotations.html#group):
```shell
php artisan dusk --group=foo
```
-> {tip} If you are using [Laravel Sail](/docs/{{version}}/sail) to manage your local development environment, please consult the Sail documentation on [configuring and running Dusk tests](/docs/{{version}}/sail#laravel-dusk).
+> [!NOTE]
+> If you are using [Laravel Sail](/docs/{{version}}/sail) to manage your local development environment, please consult the Sail documentation on [configuring and running Dusk tests](/docs/{{version}}/sail#laravel-dusk).
#### Manually Starting ChromeDriver
By default, Dusk will automatically attempt to start ChromeDriver. If this does not work for your particular system, you may manually start ChromeDriver before running the `dusk` command. If you choose to start ChromeDriver manually, you should comment out the following line of your `tests/DuskTestCase.php` file:
- /**
- * Prepare for Dusk test execution.
- *
- * @beforeClass
- * @return void
- */
- public static function prepare()
- {
- // static::startChromeDriver();
- }
+```php
+/**
+ * Prepare for Dusk test execution.
+ *
+ * @beforeClass
+ */
+public static function prepare(): void
+{
+ // static::startChromeDriver();
+}
+```
In addition, if you start ChromeDriver on a port other than 9515, you should modify the `driver` method of the same class to reflect the correct port:
- /**
- * Create the RemoteWebDriver instance.
- *
- * @return \Facebook\WebDriver\Remote\RemoteWebDriver
- */
- protected function driver()
- {
- return RemoteWebDriver::create(
- 'http://localhost:9515/', DesiredCapabilities::chrome()
- );
- }
+```php
+use Facebook\WebDriver\Remote\RemoteWebDriver;
+
+/**
+ * Create the RemoteWebDriver instance.
+ */
+protected function driver(): RemoteWebDriver
+{
+ return RemoteWebDriver::create(
+ 'http://localhost:9515/', DesiredCapabilities::chrome()
+ );
+}
+```
### Environment Handling
@@ -228,39 +353,63 @@ When running tests, Dusk will back-up your `.env` file and rename your Dusk envi
To get started, let's write a test that verifies we can log into our application. After generating a test, we can modify it to navigate to the login page, enter some credentials, and click the "Login" button. To create a browser instance, you may call the `browse` method from within your Dusk test:
- use(DatabaseMigrations::class);
- class ExampleTest extends DuskTestCase
- {
- use DatabaseMigrations;
-
- /**
- * A basic browser test example.
- *
- * @return void
- */
- public function test_basic_example()
- {
- $user = User::factory()->create([
- 'email' => 'taylor@laravel.com',
- ]);
+test('basic example', function () {
+ $user = User::factory()->create([
+ 'email' => 'taylor@laravel.com',
+ ]);
- $this->browse(function ($browser) use ($user) {
- $browser->visit('/login')
- ->type('email', $user->email)
- ->type('password', 'password')
- ->press('Login')
- ->assertPathIs('/home');
- });
- }
+ $this->browse(function (Browser $browser) use ($user) {
+ $browser->visit('/login')
+ ->type('email', $user->email)
+ ->type('password', 'password')
+ ->press('Login')
+ ->assertPathIs('/home');
+ });
+});
+```
+
+```php tab=PHPUnit
+create([
+ 'email' => 'taylor@laravel.com',
+ ]);
+
+ $this->browse(function (Browser $browser) use ($user) {
+ $browser->visit('/login')
+ ->type('email', $user->email)
+ ->type('password', 'password')
+ ->press('Login')
+ ->assertPathIs('/home');
+ });
}
+}
+```
As you can see in the example above, the `browse` method accepts a closure. A browser instance will automatically be passed to this closure by Dusk and is the main object used to interact with and make assertions against your application.
@@ -269,169 +418,221 @@ As you can see in the example above, the `browse` method accepts a closure. A br
Sometimes you may need multiple browsers in order to properly carry out a test. For example, multiple browsers may be needed to test a chat screen that interacts with websockets. To create multiple browsers, simply add more browser arguments to the signature of the closure given to the `browse` method:
- $this->browse(function ($first, $second) {
- $first->loginAs(User::find(1))
- ->visit('/home')
- ->waitForText('Message');
-
- $second->loginAs(User::find(2))
- ->visit('/home')
- ->waitForText('Message')
- ->type('message', 'Hey Taylor')
- ->press('Send');
-
- $first->waitForText('Hey Taylor')
- ->assertSee('Jeffrey Way');
- });
+```php
+$this->browse(function (Browser $first, Browser $second) {
+ $first->loginAs(User::find(1))
+ ->visit('/home')
+ ->waitForText('Message');
+
+ $second->loginAs(User::find(2))
+ ->visit('/home')
+ ->waitForText('Message')
+ ->type('message', 'Hey Taylor')
+ ->press('Send');
+
+ $first->waitForText('Hey Taylor')
+ ->assertSee('Jeffrey Way');
+});
+```
### Navigation
The `visit` method may be used to navigate to a given URI within your application:
- $browser->visit('/login');
+```php
+$browser->visit('/login');
+```
You may use the `visitRoute` method to navigate to a [named route](/docs/{{version}}/routing#named-routes):
- $browser->visitRoute('login');
+```php
+$browser->visitRoute($routeName, $parameters);
+```
You may navigate "back" and "forward" using the `back` and `forward` methods:
- $browser->back();
+```php
+$browser->back();
- $browser->forward();
+$browser->forward();
+```
You may use the `refresh` method to refresh the page:
- $browser->refresh();
+```php
+$browser->refresh();
+```
### Resizing Browser Windows
You may use the `resize` method to adjust the size of the browser window:
- $browser->resize(1920, 1080);
+```php
+$browser->resize(1920, 1080);
+```
The `maximize` method may be used to maximize the browser window:
- $browser->maximize();
+```php
+$browser->maximize();
+```
The `fitContent` method will resize the browser window to match the size of its content:
- $browser->fitContent();
+```php
+$browser->fitContent();
+```
When a test fails, Dusk will automatically resize the browser to fit the content prior to taking a screenshot. You may disable this feature by calling the `disableFitOnFailure` method within your test:
- $browser->disableFitOnFailure();
+```php
+$browser->disableFitOnFailure();
+```
You may use the `move` method to move the browser window to a different position on your screen:
- $browser->move($x = 100, $y = 100);
+```php
+$browser->move($x = 100, $y = 100);
+```
### Browser Macros
If you would like to define a custom browser method that you can re-use in a variety of your tests, you may use the `macro` method on the `Browser` class. Typically, you should call this method from a [service provider's](/docs/{{version}}/providers) `boot` method:
- script("$('html, body').animate({ scrollTop: $('$element').offset().top }, 0);");
-
- return $this;
- });
- }
+ Browser::macro('scrollToElement', function (string $element = null) {
+ $this->script("$('html, body').animate({ scrollTop: $('$element').offset().top }, 0);");
+
+ return $this;
+ });
}
+}
+```
The `macro` function accepts a name as its first argument, and a closure as its second. The macro's closure will be executed when calling the macro as a method on a `Browser` instance:
- $this->browse(function ($browser) use ($user) {
- $browser->visit('/pay')
- ->scrollToElement('#credit-card-details')
- ->assertSee('Enter Credit Card Details');
- });
+```php
+$this->browse(function (Browser $browser) use ($user) {
+ $browser->visit('/pay')
+ ->scrollToElement('#credit-card-details')
+ ->assertSee('Enter Credit Card Details');
+});
+```
### Authentication
Often, you will be testing pages that require authentication. You can use Dusk's `loginAs` method in order to avoid interacting with your application's login screen during every test. The `loginAs` method accepts a primary key associated with your authenticatable model or an authenticatable model instance:
- use App\Models\User;
+```php
+use App\Models\User;
+use Laravel\Dusk\Browser;
- $this->browse(function ($browser) {
- $browser->loginAs(User::find(1))
- ->visit('/home');
- });
+$this->browse(function (Browser $browser) {
+ $browser->loginAs(User::find(1))
+ ->visit('/home');
+});
+```
-> {note} After using the `loginAs` method, the user session will be maintained for all tests within the file.
+> [!WARNING]
+> After using the `loginAs` method, the user session will be maintained for all tests within the file.
### Cookies
You may use the `cookie` method to get or set an encrypted cookie's value. By default, all of the cookies created by Laravel are encrypted:
- $browser->cookie('name');
+```php
+$browser->cookie('name');
- $browser->cookie('name', 'Taylor');
+$browser->cookie('name', 'Taylor');
+```
You may use the `plainCookie` method to get or set an unencrypted cookie's value:
- $browser->plainCookie('name');
+```php
+$browser->plainCookie('name');
- $browser->plainCookie('name', 'Taylor');
+$browser->plainCookie('name', 'Taylor');
+```
You may use the `deleteCookie` method to delete the given cookie:
- $browser->deleteCookie('name');
+```php
+$browser->deleteCookie('name');
+```
### Executing JavaScript
You may use the `script` method to execute arbitrary JavaScript statements within the browser:
- $browser->script('document.documentElement.scrollTop = 0');
+```php
+$browser->script('document.documentElement.scrollTop = 0');
- $browser->script([
- 'document.body.scrollTop = 0',
- 'document.documentElement.scrollTop = 0',
- ]);
+$browser->script([
+ 'document.body.scrollTop = 0',
+ 'document.documentElement.scrollTop = 0',
+]);
- $output = $browser->script('return window.location.pathname');
+$output = $browser->script('return window.location.pathname');
+```
-### Taking A Screenshot
+### Taking a Screenshot
You may use the `screenshot` method to take a screenshot and store it with the given filename. All screenshots will be stored within the `tests/Browser/screenshots` directory:
- $browser->screenshot('filename');
+```php
+$browser->screenshot('filename');
+```
+
+The `responsiveScreenshots` method may be used to take a series of screenshots at various breakpoints:
+
+```php
+$browser->responsiveScreenshots('filename');
+```
+
+The `screenshotElement` method may be used to take a screenshot of a specific element on the page:
+
+```php
+$browser->screenshotElement('#selector', 'filename');
+```
-### Storing Console Output To Disk
+### Storing Console Output to Disk
You may use the `storeConsoleLog` method to write the current browser's console output to disk with the given filename. Console output will be stored within the `tests/Browser/console` directory:
- $browser->storeConsoleLog('filename');
+```php
+$browser->storeConsoleLog('filename');
+```
-### Storing Page Source To Disk
+### Storing Page Source to Disk
You may use the `storeSource` method to write the current page's source to disk with the given filename. The page source will be stored within the `tests/Browser/source` directory:
- $browser->storeSource('filename');
+```php
+$browser->storeSource('filename');
+```
## Interacting With Elements
@@ -441,55 +642,79 @@ You may use the `storeSource` method to write the current page's source to disk
Choosing good CSS selectors for interacting with elements is one of the hardest parts of writing Dusk tests. Over time, frontend changes can cause CSS selectors like the following to break your tests:
- // HTML...
+```html
+// HTML...
-
+
+```
- // Test...
+```php
+// Test...
- $browser->click('.login-page .container div > button');
+$browser->click('.login-page .container div > button');
+```
Dusk selectors allow you to focus on writing effective tests rather than remembering CSS selectors. To define a selector, add a `dusk` attribute to your HTML element. Then, when interacting with a Dusk browser, prefix the selector with `@` to manipulate the attached element within your test:
- // HTML...
+```html
+// HTML...
-
+
+```
- // Test...
+```php
+// Test...
- $browser->click('@login-button');
+$browser->click('@login-button');
+```
+
+If desired, you may customize the HTML attribute that the Dusk selector utilizes via the `selectorHtmlAttribute` method. Typically, this method should be called from the `boot` method of your application's `AppServiceProvider`:
+
+```php
+use Laravel\Dusk\Dusk;
+
+Dusk::selectorHtmlAttribute('data-dusk');
+```
-### Text, Values, & Attributes
+### Text, Values, and Attributes
-#### Retrieving & Setting Values
+#### Retrieving and Setting Values
Dusk provides several methods for interacting with the current value, display text, and attributes of elements on the page. For example, to get the "value" of an element that matches a given CSS or Dusk selector, use the `value` method:
- // Retrieve the value...
- $value = $browser->value('selector');
+```php
+// Retrieve the value...
+$value = $browser->value('selector');
- // Set the value...
- $browser->value('selector', 'value');
+// Set the value...
+$browser->value('selector', 'value');
+```
You may use the `inputValue` method to get the "value" of an input element that has a given field name:
- $value = $browser->inputValue('field');
+```php
+$value = $browser->inputValue('field');
+```
#### Retrieving Text
The `text` method may be used to retrieve the display text of an element that matches the given selector:
- $text = $browser->text('selector');
+```php
+$text = $browser->text('selector');
+```
#### Retrieving Attributes
Finally, the `attribute` method may be used to retrieve the value of an attribute of an element matching the given selector:
- $attribute = $browser->attribute('selector', 'value');
+```php
+$attribute = $browser->attribute('selector', 'value');
+```
### Interacting With Forms
@@ -499,225 +724,390 @@ Finally, the `attribute` method may be used to retrieve the value of an attribut
Dusk provides a variety of methods for interacting with forms and input elements. First, let's take a look at an example of typing text into an input field:
- $browser->type('email', 'taylor@laravel.com');
+```php
+$browser->type('email', 'taylor@laravel.com');
+```
Note that, although the method accepts one if necessary, we are not required to pass a CSS selector into the `type` method. If a CSS selector is not provided, Dusk will search for an `input` or `textarea` field with the given `name` attribute.
To append text to a field without clearing its content, you may use the `append` method:
- $browser->type('tags', 'foo')
- ->append('tags', ', bar, baz');
+```php
+$browser->type('tags', 'foo')
+ ->append('tags', ', bar, baz');
+```
You may clear the value of an input using the `clear` method:
- $browser->clear('email');
+```php
+$browser->clear('email');
+```
You can instruct Dusk to type slowly using the `typeSlowly` method. By default, Dusk will pause for 100 milliseconds between key presses. To customize the amount of time between key presses, you may pass the appropriate number of milliseconds as the third argument to the method:
- $browser->typeSlowly('mobile', '+1 (202) 555-5555');
+```php
+$browser->typeSlowly('mobile', '+1 (202) 555-5555');
- $browser->typeSlowly('mobile', '+1 (202) 555-5555', 300);
+$browser->typeSlowly('mobile', '+1 (202) 555-5555', 300);
+```
You may use the `appendSlowly` method to append text slowly:
- $browser->type('tags', 'foo')
- ->appendSlowly('tags', ', bar, baz');
+```php
+$browser->type('tags', 'foo')
+ ->appendSlowly('tags', ', bar, baz');
+```
#### Dropdowns
To select a value available on a `select` element, you may use the `select` method. Like the `type` method, the `select` method does not require a full CSS selector. When passing a value to the `select` method, you should pass the underlying option value instead of the display text:
- $browser->select('size', 'Large');
+```php
+$browser->select('size', 'Large');
+```
You may select a random option by omitting the second argument:
- $browser->select('size');
+```php
+$browser->select('size');
+```
By providing an array as the second argument to the `select` method, you can instruct the method to select multiple options:
- $browser->select('categories', ['Art', 'Music']);
+```php
+$browser->select('categories', ['Art', 'Music']);
+```
#### Checkboxes
To "check" a checkbox input, you may use the `check` method. Like many other input related methods, a full CSS selector is not required. If a CSS selector match can't be found, Dusk will search for a checkbox with a matching `name` attribute:
- $browser->check('terms');
+```php
+$browser->check('terms');
+```
The `uncheck` method may be used to "uncheck" a checkbox input:
- $browser->uncheck('terms');
+```php
+$browser->uncheck('terms');
+```
#### Radio Buttons
To "select" a `radio` input option, you may use the `radio` method. Like many other input related methods, a full CSS selector is not required. If a CSS selector match can't be found, Dusk will search for a `radio` input with matching `name` and `value` attributes:
- $browser->radio('size', 'large');
+```php
+$browser->radio('size', 'large');
+```
### Attaching Files
The `attach` method may be used to attach a file to a `file` input element. Like many other input related methods, a full CSS selector is not required. If a CSS selector match can't be found, Dusk will search for a `file` input with a matching `name` attribute:
- $browser->attach('photo', __DIR__.'/photos/mountains.png');
+```php
+$browser->attach('photo', __DIR__.'/photos/mountains.png');
+```
-> {note} The attach function requires the `Zip` PHP extension to be installed and enabled on your server.
+> [!WARNING]
+> The attach function requires the `Zip` PHP extension to be installed and enabled on your server.
### Pressing Buttons
-The `press` method may be used to click a button element on the page. The first argument given to the `press` method may be either the display text of the button or a CSS / Dusk selector:
+The `press` method may be used to click a button element on the page. The argument given to the `press` method may be either the display text of the button or a CSS / Dusk selector:
- $browser->press('Login');
+```php
+$browser->press('Login');
+```
-When submitting forms, many application's disable the form's submission button after it is pressed and then re-enable the button when the form submission's HTTP request is complete. To press a button and wait for the button to be re-enabled, you may use the `pressAndWaitFor` method:
+When submitting forms, many applications disable the form's submission button after it is pressed and then re-enable the button when the form submission's HTTP request is complete. To press a button and wait for the button to be re-enabled, you may use the `pressAndWaitFor` method:
- // Press the button and wait a maximum of 5 seconds for it to be enabled...
- $browser->pressAndWaitFor('Save');
+```php
+// Press the button and wait a maximum of 5 seconds for it to be enabled...
+$browser->pressAndWaitFor('Save');
- // Press the button and wait a maximum of 1 second for it to be enabled...
- $browser->pressAndWaitFor('Save', 1);
+// Press the button and wait a maximum of 1 second for it to be enabled...
+$browser->pressAndWaitFor('Save', 1);
+```
### Clicking Links
To click a link, you may use the `clickLink` method on the browser instance. The `clickLink` method will click the link that has the given display text:
- $browser->clickLink($linkText);
+```php
+$browser->clickLink($linkText);
+```
You may use the `seeLink` method to determine if a link with the given display text is visible on the page:
- if ($browser->seeLink($linkText)) {
- // ...
- }
+```php
+if ($browser->seeLink($linkText)) {
+ // ...
+}
+```
-> {note} These methods interact with jQuery. If jQuery is not available on the page, Dusk will automatically inject it into the page so it is available for the test's duration.
+> [!WARNING]
+> These methods interact with jQuery. If jQuery is not available on the page, Dusk will automatically inject it into the page so it is available for the test's duration.
-### Using The Keyboard
+### Using the Keyboard
The `keys` method allows you to provide more complex input sequences to a given element than normally allowed by the `type` method. For example, you may instruct Dusk to hold modifier keys while entering values. In this example, the `shift` key will be held while `taylor` is entered into the element matching the given selector. After `taylor` is typed, `swift` will be typed without any modifier keys:
- $browser->keys('selector', ['{shift}', 'taylor'], 'swift');
+```php
+$browser->keys('selector', ['{shift}', 'taylor'], 'swift');
+```
Another valuable use case for the `keys` method is sending a "keyboard shortcut" combination to the primary CSS selector for your application:
- $browser->keys('.app', ['{command}', 'j']);
+```php
+$browser->keys('.app', ['{command}', 'j']);
+```
+
+> [!NOTE]
+> All modifier keys such as `{command}` are wrapped in `{}` characters, and match the constants defined in the `Facebook\WebDriver\WebDriverKeys` class, which can be [found on GitHub](https://github.com/php-webdriver/php-webdriver/blob/master/lib/WebDriverKeys.php).
+
+
+#### Fluent Keyboard Interactions
+
+Dusk also provides a `withKeyboard` method, allowing you to fluently perform complex keyboard interactions via the `Laravel\Dusk\Keyboard` class. The `Keyboard` class provides `press`, `release`, `type`, and `pause` methods:
+
+```php
+use Laravel\Dusk\Keyboard;
+
+$browser->withKeyboard(function (Keyboard $keyboard) {
+ $keyboard->press('c')
+ ->pause(1000)
+ ->release('c')
+ ->type(['c', 'e', 'o']);
+});
+```
+
+
+#### Keyboard Macros
+
+If you would like to define custom keyboard interactions that you can easily re-use throughout your test suite, you may use the `macro` method provided by the `Keyboard` class. Typically, you should call this method from a [service provider's](/docs/{{version}}/providers) `boot` method:
+
+```php
+type([
+ OperatingSystem::onMac() ? WebDriverKeys::META : WebDriverKeys::CONTROL, 'c',
+ ]);
+
+ return $this;
+ });
+
+ Keyboard::macro('paste', function (string $element = null) {
+ $this->type([
+ OperatingSystem::onMac() ? WebDriverKeys::META : WebDriverKeys::CONTROL, 'v',
+ ]);
+
+ return $this;
+ });
+ }
+}
+```
+
+The `macro` function accepts a name as its first argument and a closure as its second. The macro's closure will be executed when calling the macro as a method on a `Keyboard` instance:
-> {tip} All modifier keys such as `{command}` are wrapped in `{}` characters, and match the constants defined in the `Facebook\WebDriver\WebDriverKeys` class, which can be [found on GitHub](https://github.com/php-webdriver/php-webdriver/blob/master/lib/WebDriverKeys.php).
+```php
+$browser->click('@textarea')
+ ->withKeyboard(fn (Keyboard $keyboard) => $keyboard->copy())
+ ->click('@another-textarea')
+ ->withKeyboard(fn (Keyboard $keyboard) => $keyboard->paste());
+```
-### Using The Mouse
+### Using the Mouse
-#### Clicking On Elements
+#### Clicking on Elements
The `click` method may be used to click on an element matching the given CSS or Dusk selector:
- $browser->click('.selector');
+```php
+$browser->click('.selector');
+```
The `clickAtXPath` method may be used to click on an element matching the given XPath expression:
- $browser->clickAtXPath('//div[@class = "selector"]');
+```php
+$browser->clickAtXPath('//div[@class = "selector"]');
+```
The `clickAtPoint` method may be used to click on the topmost element at a given pair of coordinates relative to the viewable area of the browser:
- $browser->clickAtPoint($x = 0, $y = 0);
+```php
+$browser->clickAtPoint($x = 0, $y = 0);
+```
The `doubleClick` method may be used to simulate the double click of a mouse:
- $browser->doubleClick();
+```php
+$browser->doubleClick();
+
+$browser->doubleClick('.selector');
+```
The `rightClick` method may be used to simulate the right click of a mouse:
- $browser->rightClick();
+```php
+$browser->rightClick();
- $browser->rightClick('.selector');
+$browser->rightClick('.selector');
+```
The `clickAndHold` method may be used to simulate a mouse button being clicked and held down. A subsequent call to the `releaseMouse` method will undo this behavior and release the mouse button:
- $browser->clickAndHold()
- ->pause(1000)
- ->releaseMouse();
+```php
+$browser->clickAndHold('.selector');
+
+$browser->clickAndHold()
+ ->pause(1000)
+ ->releaseMouse();
+```
+
+The `controlClick` method may be used to simulate the `ctrl+click` event within the browser:
+
+```php
+$browser->controlClick();
+
+$browser->controlClick('.selector');
+```
#### Mouseover
The `mouseover` method may be used when you need to move the mouse over an element matching the given CSS or Dusk selector:
- $browser->mouseover('.selector');
+```php
+$browser->mouseover('.selector');
+```
-#### Drag & Drop
+#### Drag and Drop
The `drag` method may be used to drag an element matching the given selector to another element:
- $browser->drag('.from-selector', '.to-selector');
+```php
+$browser->drag('.from-selector', '.to-selector');
+```
Or, you may drag an element in a single direction:
- $browser->dragLeft('.selector', $pixels = 10);
- $browser->dragRight('.selector', $pixels = 10);
- $browser->dragUp('.selector', $pixels = 10);
- $browser->dragDown('.selector', $pixels = 10);
+```php
+$browser->dragLeft('.selector', $pixels = 10);
+$browser->dragRight('.selector', $pixels = 10);
+$browser->dragUp('.selector', $pixels = 10);
+$browser->dragDown('.selector', $pixels = 10);
+```
Finally, you may drag an element by a given offset:
- $browser->dragOffset('.selector', $x = 10, $y = 10);
+```php
+$browser->dragOffset('.selector', $x = 10, $y = 10);
+```
### JavaScript Dialogs
Dusk provides various methods to interact with JavaScript Dialogs. For example, you may use the `waitForDialog` method to wait for a JavaScript dialog to appear. This method accepts an optional argument indicating how many seconds to wait for the dialog to appear:
- $browser->waitForDialog($seconds = null);
+```php
+$browser->waitForDialog($seconds = null);
+```
The `assertDialogOpened` method may be used to assert that a dialog has been displayed and contains the given message:
- $browser->assertDialogOpened('Dialog message');
+```php
+$browser->assertDialogOpened('Dialog message');
+```
If the JavaScript dialog contains a prompt, you may use the `typeInDialog` method to type a value into the prompt:
- $browser->typeInDialog('Hello World');
+```php
+$browser->typeInDialog('Hello World');
+```
To close an open JavaScript dialog by clicking the "OK" button, you may invoke the `acceptDialog` method:
- $browser->acceptDialog();
+```php
+$browser->acceptDialog();
+```
To close an open JavaScript dialog by clicking the "Cancel" button, you may invoke the `dismissDialog` method:
- $browser->dismissDialog();
+```php
+$browser->dismissDialog();
+```
+
+
+### Interacting With Inline Frames
+
+If you need to interact with elements within an iframe, you may use the `withinFrame` method. All element interactions that take place within the closure provided to the `withinFrame` method will be scoped to the context of the specified iframe:
+
+```php
+$browser->withinFrame('#credit-card-details', function ($browser) {
+ $browser->type('input[name="cardnumber"]', '4242424242424242')
+ ->type('input[name="exp-date"]', '1224')
+ ->type('input[name="cvc"]', '123')
+ ->press('Pay');
+});
+```
### Scoping Selectors
Sometimes you may wish to perform several operations while scoping all of the operations within a given selector. For example, you may wish to assert that some text exists only within a table and then click a button within that table. You may use the `with` method to accomplish this. All operations performed within the closure given to the `with` method will be scoped to the original selector:
- $browser->with('.table', function ($table) {
- $table->assertSee('Hello World')
- ->clickLink('Delete');
- });
+```php
+$browser->with('.table', function (Browser $table) {
+ $table->assertSee('Hello World')
+ ->clickLink('Delete');
+});
+```
You may occasionally need to execute assertions outside of the current scope. You may use the `elsewhere` and `elsewhereWhenAvailable` methods to accomplish this:
- $browser->with('.table', function ($table) {
- // Current scope is `body .table`...
+```php
+$browser->with('.table', function (Browser $table) {
+ // Current scope is `body .table`...
- $browser->elsewhere('.page-title', function ($title) {
- // Current scope is `body .page-title`...
- $title->assertSee('Hello World');
- });
+ $browser->elsewhere('.page-title', function (Browser $title) {
+ // Current scope is `body .page-title`...
+ $title->assertSee('Hello World');
+ });
- $browser->elsewhereWhenAvailable('.page-title', function ($title) {
- // Current scope is `body .page-title`...
- $title->assertSee('Hello World');
- });
- });
+ $browser->elsewhereWhenAvailable('.page-title', function (Browser $title) {
+ // Current scope is `body .page-title`...
+ $title->assertSee('Hello World');
+ });
+});
+```
-### Waiting For Elements
+### Waiting for Elements
When testing applications that use JavaScript extensively, it often becomes necessary to "wait" for certain elements or data to be available before proceeding with a test. Dusk makes this a cinch. Using a variety of methods, you may wait for elements to become visible on the page or even wait until a given JavaScript expression evaluates to `true`.
@@ -726,159 +1116,254 @@ When testing applications that use JavaScript extensively, it often becomes nece
If you just need to pause the test for a given number of milliseconds, use the `pause` method:
- $browser->pause(1000);
+```php
+$browser->pause(1000);
+```
+
+If you need to pause the test only if a given condition is `true`, use the `pauseIf` method:
+
+```php
+$browser->pauseIf(App::environment('production'), 1000);
+```
+
+Likewise, if you need to pause the test unless a given condition is `true`, you may use the `pauseUnless` method:
+
+```php
+$browser->pauseUnless(App::environment('testing'), 1000);
+```
-#### Waiting For Selectors
+#### Waiting for Selectors
The `waitFor` method may be used to pause the execution of the test until the element matching the given CSS or Dusk selector is displayed on the page. By default, this will pause the test for a maximum of five seconds before throwing an exception. If necessary, you may pass a custom timeout threshold as the second argument to the method:
- // Wait a maximum of five seconds for the selector...
- $browser->waitFor('.selector');
+```php
+// Wait a maximum of five seconds for the selector...
+$browser->waitFor('.selector');
- // Wait a maximum of one second for the selector...
- $browser->waitFor('.selector', 1);
+// Wait a maximum of one second for the selector...
+$browser->waitFor('.selector', 1);
+```
You may also wait until the element matching the given selector contains the given text:
- // Wait a maximum of five seconds for the selector to contain the given text...
- $browser->waitForTextIn('.selector', 'Hello World');
+```php
+// Wait a maximum of five seconds for the selector to contain the given text...
+$browser->waitForTextIn('.selector', 'Hello World');
- // Wait a maximum of one second for the selector to contain the given text...
- $browser->waitForTextIn('.selector', 'Hello World', 1);
+// Wait a maximum of one second for the selector to contain the given text...
+$browser->waitForTextIn('.selector', 'Hello World', 1);
+```
You may also wait until the element matching the given selector is missing from the page:
- // Wait a maximum of five seconds until the selector is missing...
- $browser->waitUntilMissing('.selector');
+```php
+// Wait a maximum of five seconds until the selector is missing...
+$browser->waitUntilMissing('.selector');
- // Wait a maximum of one second until the selector is missing...
- $browser->waitUntilMissing('.selector', 1);
+// Wait a maximum of one second until the selector is missing...
+$browser->waitUntilMissing('.selector', 1);
+```
Or, you may wait until the element matching the given selector is enabled or disabled:
- // Wait a maximum of five seconds until the selector is enabled...
- $browser->waitUntilEnabled('.selector');
+```php
+// Wait a maximum of five seconds until the selector is enabled...
+$browser->waitUntilEnabled('.selector');
- // Wait a maximum of one second until the selector is enabled...
- $browser->waitUntilEnabled('.selector', 1);
+// Wait a maximum of one second until the selector is enabled...
+$browser->waitUntilEnabled('.selector', 1);
- // Wait a maximum of five seconds until the selector is disabled...
- $browser->waitUntilDisabled('.selector');
+// Wait a maximum of five seconds until the selector is disabled...
+$browser->waitUntilDisabled('.selector');
- // Wait a maximum of one second until the selector is disabled...
- $browser->waitUntilDisabled('.selector', 1);
+// Wait a maximum of one second until the selector is disabled...
+$browser->waitUntilDisabled('.selector', 1);
+```
#### Scoping Selectors When Available
Occasionally, you may wish to wait for an element to appear that matches a given selector and then interact with the element. For example, you may wish to wait until a modal window is available and then press the "OK" button within the modal. The `whenAvailable` method may be used to accomplish this. All element operations performed within the given closure will be scoped to the original selector:
- $browser->whenAvailable('.modal', function ($modal) {
- $modal->assertSee('Hello World')
- ->press('OK');
- });
+```php
+$browser->whenAvailable('.modal', function (Browser $modal) {
+ $modal->assertSee('Hello World')
+ ->press('OK');
+});
+```
-#### Waiting For Text
+#### Waiting for Text
The `waitForText` method may be used to wait until the given text is displayed on the page:
- // Wait a maximum of five seconds for the text...
- $browser->waitForText('Hello World');
+```php
+// Wait a maximum of five seconds for the text...
+$browser->waitForText('Hello World');
- // Wait a maximum of one second for the text...
- $browser->waitForText('Hello World', 1);
+// Wait a maximum of one second for the text...
+$browser->waitForText('Hello World', 1);
+```
You may use the `waitUntilMissingText` method to wait until the displayed text has been removed from the page:
- // Wait a maximum of five seconds for the text to be removed...
- $browser->waitUntilMissingText('Hello World');
+```php
+// Wait a maximum of five seconds for the text to be removed...
+$browser->waitUntilMissingText('Hello World');
- // Wait a maximum of one second for the text to be removed...
- $browser->waitUntilMissingText('Hello World', 1);
+// Wait a maximum of one second for the text to be removed...
+$browser->waitUntilMissingText('Hello World', 1);
+```
-#### Waiting For Links
+#### Waiting for Links
The `waitForLink` method may be used to wait until the given link text is displayed on the page:
- // Wait a maximum of five seconds for the link...
- $browser->waitForLink('Create');
+```php
+// Wait a maximum of five seconds for the link...
+$browser->waitForLink('Create');
+
+// Wait a maximum of one second for the link...
+$browser->waitForLink('Create', 1);
+```
+
+
+#### Waiting for Inputs
- // Wait a maximum of one second for the link...
- $browser->waitForLink('Create', 1);
+The `waitForInput` method may be used to wait until the given input field is visible on the page:
+
+```php
+// Wait a maximum of five seconds for the input...
+$browser->waitForInput($field);
+
+// Wait a maximum of one second for the input...
+$browser->waitForInput($field, 1);
+```
-#### Waiting On The Page Location
+#### Waiting on the Page Location
When making a path assertion such as `$browser->assertPathIs('/home')`, the assertion can fail if `window.location.pathname` is being updated asynchronously. You may use the `waitForLocation` method to wait for the location to be a given value:
- $browser->waitForLocation('/secret');
+```php
+$browser->waitForLocation('/secret');
+```
The `waitForLocation` method can also be used to wait for the current window location to be a fully qualified URL:
- $browser->waitForLocation('https://example.com/path');
+```php
+$browser->waitForLocation('https://example.com/path');
+```
You may also wait for a [named route's](/docs/{{version}}/routing#named-routes) location:
- $browser->waitForRoute($routeName, $parameters);
+```php
+$browser->waitForRoute($routeName, $parameters);
+```
#### Waiting for Page Reloads
If you need to wait for a page to reload after performing an action, use the `waitForReload` method:
- use Laravel\Dusk\Browser;
+```php
+use Laravel\Dusk\Browser;
- $browser->waitForReload(function (Browser $browser) {
- $browser->press('Submit');
- })
- ->assertSee('Success!');
+$browser->waitForReload(function (Browser $browser) {
+ $browser->press('Submit');
+})
+->assertSee('Success!');
+```
Since the need to wait for the page to reload typically occurs after clicking a button, you may use the `clickAndWaitForReload` method for convenience:
- $browser->clickAndWaitForReload('.selector')
- ->assertSee('something');
+```php
+$browser->clickAndWaitForReload('.selector')
+ ->assertSee('something');
+```
-#### Waiting On JavaScript Expressions
+#### Waiting on JavaScript Expressions
Sometimes you may wish to pause the execution of a test until a given JavaScript expression evaluates to `true`. You may easily accomplish this using the `waitUntil` method. When passing an expression to this method, you do not need to include the `return` keyword or an ending semi-colon:
- // Wait a maximum of five seconds for the expression to be true...
- $browser->waitUntil('App.data.servers.length > 0');
+```php
+// Wait a maximum of five seconds for the expression to be true...
+$browser->waitUntil('App.data.servers.length > 0');
- // Wait a maximum of one second for the expression to be true...
- $browser->waitUntil('App.data.servers.length > 0', 1);
+// Wait a maximum of one second for the expression to be true...
+$browser->waitUntil('App.data.servers.length > 0', 1);
+```
-#### Waiting On Vue Expressions
+#### Waiting on Vue Expressions
The `waitUntilVue` and `waitUntilVueIsNot` methods may be used to wait until a [Vue component](https://vuejs.org) attribute has a given value:
- // Wait until the component attribute contains the given value...
- $browser->waitUntilVue('user.name', 'Taylor', '@user');
+```php
+// Wait until the component attribute contains the given value...
+$browser->waitUntilVue('user.name', 'Taylor', '@user');
+
+// Wait until the component attribute doesn't contain the given value...
+$browser->waitUntilVueIsNot('user.name', null, '@user');
+```
+
+
+#### Waiting for JavaScript Events
+
+The `waitForEvent` method can be used to pause the execution of a test until a JavaScript event occurs:
+
+```php
+$browser->waitForEvent('load');
+```
+
+The event listener is attached to the current scope, which is the `body` element by default. When using a scoped selector, the event listener will be attached to the matching element:
+
+```php
+$browser->with('iframe', function (Browser $iframe) {
+ // Wait for the iframe's load event...
+ $iframe->waitForEvent('load');
+});
+```
- // Wait until the component attribute doesn't contain the given value...
- $browser->waitUntilVueIsNot('user.name', null, '@user');
+You may also provide a selector as the second argument to the `waitForEvent` method to attach the event listener to a specific element:
+
+```php
+$browser->waitForEvent('load', '.selector');
+```
+
+You may also wait for events on the `document` and `window` objects:
+
+```php
+// Wait until the document is scrolled...
+$browser->waitForEvent('scroll', 'document');
+
+// Wait a maximum of five seconds until the window is resized...
+$browser->waitForEvent('resize', 'window', 5);
+```
-#### Waiting With A Callback
+#### Waiting With a Callback
Many of the "wait" methods in Dusk rely on the underlying `waitUsing` method. You may use this method directly to wait for a given closure to return `true`. The `waitUsing` method accepts the maximum number of seconds to wait, the interval at which the closure should be evaluated, the closure, and an optional failure message:
- $browser->waitUsing(10, 1, function () use ($something) {
- return $something->isReady();
- }, "Something wasn't ready in time.");
+```php
+$browser->waitUsing(10, 1, function () use ($something) {
+ return $something->isReady();
+}, "Something wasn't ready in time.");
+```
-### Scrolling An Element Into View
+### Scrolling an Element Into View
Sometimes you may not be able to click on an element because it is outside of the viewable area of the browser. The `scrollIntoView` method will scroll the browser window until the element at the given selector is within the view:
- $browser->scrollIntoView('.selector')
- ->click('.selector');
+```php
+$browser->scrollIntoView('.selector')
+ ->click('.selector');
+```
## Available Assertions
@@ -887,12 +1372,14 @@ Dusk provides a variety of assertions that you may make against your application
@@ -908,6 +1395,8 @@ Dusk provides a variety of assertions that you may make against your application
[assertPortIs](#assert-port-is)
[assertPortIsNot](#assert-port-is-not)
[assertPathBeginsWith](#assert-path-begins-with)
+[assertPathEndsWith](#assert-path-ends-with)
+[assertPathContains](#assert-path-contains)
[assertPathIs](#assert-path-is)
[assertPathIsNot](#assert-path-is-not)
[assertRouteIs](#assert-route-is)
@@ -928,6 +1417,7 @@ Dusk provides a variety of assertions that you may make against your application
[assertDontSeeIn](#assert-dont-see-in)
[assertSeeAnythingIn](#assert-see-anything-in)
[assertSeeNothingIn](#assert-see-nothing-in)
+[assertCount](#assert-count)
[assertScript](#assert-script)
[assertSourceHas](#assert-source-has)
[assertSourceMissing](#assert-source-missing)
@@ -937,6 +1427,7 @@ Dusk provides a variety of assertions that you may make against your application
[assertInputValueIsNot](#assert-input-value-is-not)
[assertChecked](#assert-checked)
[assertNotChecked](#assert-not-checked)
+[assertIndeterminate](#assert-indeterminate)
[assertRadioSelected](#assert-radio-selected)
[assertRadioNotSelected](#assert-radio-not-selected)
[assertSelected](#assert-selected)
@@ -948,7 +1439,9 @@ Dusk provides a variety of assertions that you may make against your application
[assertValue](#assert-value)
[assertValueIsNot](#assert-value-is-not)
[assertAttribute](#assert-attribute)
+[assertAttributeMissing](#assert-attribute-missing)
[assertAttributeContains](#assert-attribute-contains)
+[assertAttributeDoesntContain](#assert-attribute-doesnt-contain)
[assertAriaAttribute](#assert-aria-attribute)
[assertDataAttribute](#assert-data-attribute)
[assertVisible](#assert-visible)
@@ -970,7 +1463,7 @@ Dusk provides a variety of assertions that you may make against your application
[assertVue](#assert-vue)
[assertVueIsNot](#assert-vue-is-not)
[assertVueContains](#assert-vue-contains)
-[assertVueDoesNotContain](#assert-vue-does-not-contain)
+[assertVueDoesntContain](#assert-vue-doesnt-contain)
@@ -979,496 +1472,694 @@ Dusk provides a variety of assertions that you may make against your application
Assert that the page title matches the given text:
- $browser->assertTitle($title);
+```php
+$browser->assertTitle($title);
+```
#### assertTitleContains
Assert that the page title contains the given text:
- $browser->assertTitleContains($title);
+```php
+$browser->assertTitleContains($title);
+```
#### assertUrlIs
Assert that the current URL (without the query string) matches the given string:
- $browser->assertUrlIs($url);
+```php
+$browser->assertUrlIs($url);
+```
#### assertSchemeIs
Assert that the current URL scheme matches the given scheme:
- $browser->assertSchemeIs($scheme);
+```php
+$browser->assertSchemeIs($scheme);
+```
#### assertSchemeIsNot
Assert that the current URL scheme does not match the given scheme:
- $browser->assertSchemeIsNot($scheme);
+```php
+$browser->assertSchemeIsNot($scheme);
+```
#### assertHostIs
Assert that the current URL host matches the given host:
- $browser->assertHostIs($host);
+```php
+$browser->assertHostIs($host);
+```
#### assertHostIsNot
Assert that the current URL host does not match the given host:
- $browser->assertHostIsNot($host);
+```php
+$browser->assertHostIsNot($host);
+```
#### assertPortIs
Assert that the current URL port matches the given port:
- $browser->assertPortIs($port);
+```php
+$browser->assertPortIs($port);
+```
#### assertPortIsNot
Assert that the current URL port does not match the given port:
- $browser->assertPortIsNot($port);
+```php
+$browser->assertPortIsNot($port);
+```
#### assertPathBeginsWith
Assert that the current URL path begins with the given path:
- $browser->assertPathBeginsWith('/home');
+```php
+$browser->assertPathBeginsWith('/home');
+```
+
+
+#### assertPathEndsWith
+
+Assert that the current URL path ends with the given path:
+
+```php
+$browser->assertPathEndsWith('/home');
+```
+
+
+#### assertPathContains
+
+Assert that the current URL path contains the given path:
+
+```php
+$browser->assertPathContains('/home');
+```
#### assertPathIs
Assert that the current path matches the given path:
- $browser->assertPathIs('/home');
+```php
+$browser->assertPathIs('/home');
+```
#### assertPathIsNot
Assert that the current path does not match the given path:
- $browser->assertPathIsNot('/home');
+```php
+$browser->assertPathIsNot('/home');
+```
#### assertRouteIs
Assert that the current URL matches the given [named route's](/docs/{{version}}/routing#named-routes) URL:
- $browser->assertRouteIs($name, $parameters);
+```php
+$browser->assertRouteIs($name, $parameters);
+```
#### assertQueryStringHas
Assert that the given query string parameter is present:
- $browser->assertQueryStringHas($name);
+```php
+$browser->assertQueryStringHas($name);
+```
Assert that the given query string parameter is present and has a given value:
- $browser->assertQueryStringHas($name, $value);
+```php
+$browser->assertQueryStringHas($name, $value);
+```
#### assertQueryStringMissing
Assert that the given query string parameter is missing:
- $browser->assertQueryStringMissing($name);
+```php
+$browser->assertQueryStringMissing($name);
+```
#### assertFragmentIs
Assert that the URL's current hash fragment matches the given fragment:
- $browser->assertFragmentIs('anchor');
+```php
+$browser->assertFragmentIs('anchor');
+```
#### assertFragmentBeginsWith
Assert that the URL's current hash fragment begins with the given fragment:
- $browser->assertFragmentBeginsWith('anchor');
+```php
+$browser->assertFragmentBeginsWith('anchor');
+```
#### assertFragmentIsNot
Assert that the URL's current hash fragment does not match the given fragment:
- $browser->assertFragmentIsNot('anchor');
+```php
+$browser->assertFragmentIsNot('anchor');
+```
#### assertHasCookie
Assert that the given encrypted cookie is present:
- $browser->assertHasCookie($name);
+```php
+$browser->assertHasCookie($name);
+```
#### assertHasPlainCookie
Assert that the given unencrypted cookie is present:
- $browser->assertHasPlainCookie($name);
+```php
+$browser->assertHasPlainCookie($name);
+```
#### assertCookieMissing
Assert that the given encrypted cookie is not present:
- $browser->assertCookieMissing($name);
+```php
+$browser->assertCookieMissing($name);
+```
#### assertPlainCookieMissing
Assert that the given unencrypted cookie is not present:
- $browser->assertPlainCookieMissing($name);
+```php
+$browser->assertPlainCookieMissing($name);
+```
#### assertCookieValue
Assert that an encrypted cookie has a given value:
- $browser->assertCookieValue($name, $value);
+```php
+$browser->assertCookieValue($name, $value);
+```
#### assertPlainCookieValue
Assert that an unencrypted cookie has a given value:
- $browser->assertPlainCookieValue($name, $value);
+```php
+$browser->assertPlainCookieValue($name, $value);
+```
#### assertSee
Assert that the given text is present on the page:
- $browser->assertSee($text);
+```php
+$browser->assertSee($text);
+```
#### assertDontSee
Assert that the given text is not present on the page:
- $browser->assertDontSee($text);
+```php
+$browser->assertDontSee($text);
+```
#### assertSeeIn
Assert that the given text is present within the selector:
- $browser->assertSeeIn($selector, $text);
+```php
+$browser->assertSeeIn($selector, $text);
+```
#### assertDontSeeIn
Assert that the given text is not present within the selector:
- $browser->assertDontSeeIn($selector, $text);
+```php
+$browser->assertDontSeeIn($selector, $text);
+```
#### assertSeeAnythingIn
Assert that any text is present within the selector:
- $browser->assertSeeAnythingIn($selector);
+```php
+$browser->assertSeeAnythingIn($selector);
+```
#### assertSeeNothingIn
Assert that no text is present within the selector:
- $browser->assertSeeNothingIn($selector);
+```php
+$browser->assertSeeNothingIn($selector);
+```
+
+
+#### assertCount
+
+Assert that elements matching the given selector appear the specified number of times:
+
+```php
+$browser->assertCount($selector, $count);
+```
#### assertScript
Assert that the given JavaScript expression evaluates to the given value:
- $browser->assertScript('window.isLoaded')
- ->assertScript('document.readyState', 'complete');
+```php
+$browser->assertScript('window.isLoaded')
+ ->assertScript('document.readyState', 'complete');
+```
#### assertSourceHas
Assert that the given source code is present on the page:
- $browser->assertSourceHas($code);
+```php
+$browser->assertSourceHas($code);
+```
#### assertSourceMissing
Assert that the given source code is not present on the page:
- $browser->assertSourceMissing($code);
+```php
+$browser->assertSourceMissing($code);
+```
#### assertSeeLink
Assert that the given link is present on the page:
- $browser->assertSeeLink($linkText);
+```php
+$browser->assertSeeLink($linkText);
+```
#### assertDontSeeLink
Assert that the given link is not present on the page:
- $browser->assertDontSeeLink($linkText);
+```php
+$browser->assertDontSeeLink($linkText);
+```
#### assertInputValue
Assert that the given input field has the given value:
- $browser->assertInputValue($field, $value);
+```php
+$browser->assertInputValue($field, $value);
+```
#### assertInputValueIsNot
Assert that the given input field does not have the given value:
- $browser->assertInputValueIsNot($field, $value);
+```php
+$browser->assertInputValueIsNot($field, $value);
+```
#### assertChecked
Assert that the given checkbox is checked:
- $browser->assertChecked($field);
+```php
+$browser->assertChecked($field);
+```
#### assertNotChecked
Assert that the given checkbox is not checked:
- $browser->assertNotChecked($field);
+```php
+$browser->assertNotChecked($field);
+```
+
+
+#### assertIndeterminate
+
+Assert that the given checkbox is in an indeterminate state:
+
+```php
+$browser->assertIndeterminate($field);
+```
#### assertRadioSelected
Assert that the given radio field is selected:
- $browser->assertRadioSelected($field, $value);
+```php
+$browser->assertRadioSelected($field, $value);
+```
#### assertRadioNotSelected
Assert that the given radio field is not selected:
- $browser->assertRadioNotSelected($field, $value);
+```php
+$browser->assertRadioNotSelected($field, $value);
+```
#### assertSelected
Assert that the given dropdown has the given value selected:
- $browser->assertSelected($field, $value);
+```php
+$browser->assertSelected($field, $value);
+```
#### assertNotSelected
Assert that the given dropdown does not have the given value selected:
- $browser->assertNotSelected($field, $value);
+```php
+$browser->assertNotSelected($field, $value);
+```
#### assertSelectHasOptions
Assert that the given array of values are available to be selected:
- $browser->assertSelectHasOptions($field, $values);
+```php
+$browser->assertSelectHasOptions($field, $values);
+```
#### assertSelectMissingOptions
Assert that the given array of values are not available to be selected:
- $browser->assertSelectMissingOptions($field, $values);
+```php
+$browser->assertSelectMissingOptions($field, $values);
+```
#### assertSelectHasOption
Assert that the given value is available to be selected on the given field:
- $browser->assertSelectHasOption($field, $value);
+```php
+$browser->assertSelectHasOption($field, $value);
+```
#### assertSelectMissingOption
Assert that the given value is not available to be selected:
- $browser->assertSelectMissingOption($field, $value);
+```php
+$browser->assertSelectMissingOption($field, $value);
+```
#### assertValue
Assert that the element matching the given selector has the given value:
- $browser->assertValue($selector, $value);
+```php
+$browser->assertValue($selector, $value);
+```
#### assertValueIsNot
Assert that the element matching the given selector does not have the given value:
- $browser->assertValueIsNot($selector, $value);
+```php
+$browser->assertValueIsNot($selector, $value);
+```
#### assertAttribute
Assert that the element matching the given selector has the given value in the provided attribute:
- $browser->assertAttribute($selector, $attribute, $value);
+```php
+$browser->assertAttribute($selector, $attribute, $value);
+```
+
+
+#### assertAttributeMissing
+
+Assert that the element matching the given selector is missing the provided attribute:
+
+```php
+$browser->assertAttributeMissing($selector, $attribute);
+```
#### assertAttributeContains
Assert that the element matching the given selector contains the given value in the provided attribute:
- $browser->assertAttributeContains($selector, $attribute, $value);
+```php
+$browser->assertAttributeContains($selector, $attribute, $value);
+```
+
+
+#### assertAttributeDoesntContain
+
+Assert that the element matching the given selector does not contain the given value in the provided attribute:
+
+```php
+$browser->assertAttributeDoesntContain($selector, $attribute, $value);
+```
#### assertAriaAttribute
Assert that the element matching the given selector has the given value in the provided aria attribute:
- $browser->assertAriaAttribute($selector, $attribute, $value);
+```php
+$browser->assertAriaAttribute($selector, $attribute, $value);
+```
For example, given the markup ``, you may assert against the `aria-label` attribute like so:
- $browser->assertAriaAttribute('button', 'label', 'Add')
+```php
+$browser->assertAriaAttribute('button', 'label', 'Add')
+```
#### assertDataAttribute
Assert that the element matching the given selector has the given value in the provided data attribute:
- $browser->assertDataAttribute($selector, $attribute, $value);
+```php
+$browser->assertDataAttribute($selector, $attribute, $value);
+```
For example, given the markup `
+
+ */
+ public function newCollection(array $models = []): Collection
{
- /**
- * Create a new Eloquent Collection instance.
- *
- * @param array $models
- * @return \Illuminate\Database\Eloquent\Collection
- */
- public function newCollection(array $models = [])
- {
- return new UserCollection($models);
+ $collection = new UserCollection($models);
+
+ if (Model::isAutomaticallyEagerLoadingRelationships()) {
+ $collection->withRelationshipAutoloading();
}
+
+ return $collection;
}
+}
+```
+
+Once you have defined a `newCollection` method or added the `CollectedBy` attribute to your model, you will receive an instance of your custom collection anytime Eloquent would normally return an `Illuminate\Database\Eloquent\Collection` instance.
-Once you have defined a `newCollection` method, you will receive an instance of your custom collection anytime Eloquent would normally return an `Illuminate\Database\Eloquent\Collection` instance. If you would like to use a custom collection for every model in your application, you should define the `newCollection` method on a base model class that is extended by all of your application's models.
+If you would like to use a custom collection for every model in your application, you should define the `newCollection` method on a base model class that is extended by all of your application's models.
diff --git a/eloquent-factories.md b/eloquent-factories.md
new file mode 100644
index 00000000000..67ca396a541
--- /dev/null
+++ b/eloquent-factories.md
@@ -0,0 +1,639 @@
+# Eloquent: Factories
+
+- [Introduction](#introduction)
+- [Defining Model Factories](#defining-model-factories)
+ - [Generating Factories](#generating-factories)
+ - [Factory States](#factory-states)
+ - [Factory Callbacks](#factory-callbacks)
+- [Creating Models Using Factories](#creating-models-using-factories)
+ - [Instantiating Models](#instantiating-models)
+ - [Persisting Models](#persisting-models)
+ - [Sequences](#sequences)
+- [Factory Relationships](#factory-relationships)
+ - [Has Many Relationships](#has-many-relationships)
+ - [Belongs To Relationships](#belongs-to-relationships)
+ - [Many to Many Relationships](#many-to-many-relationships)
+ - [Polymorphic Relationships](#polymorphic-relationships)
+ - [Defining Relationships Within Factories](#defining-relationships-within-factories)
+ - [Recycling an Existing Model for Relationships](#recycling-an-existing-model-for-relationships)
+
+
+## Introduction
+
+When testing your application or seeding your database, you may need to insert a few records into your database. Instead of manually specifying the value of each column, Laravel allows you to define a set of default attributes for each of your [Eloquent models](/docs/{{version}}/eloquent) using model factories.
+
+To see an example of how to write a factory, take a look at the `database/factories/UserFactory.php` file in your application. This factory is included with all new Laravel applications and contains the following factory definition:
+
+```php
+namespace Database\Factories;
+
+use Illuminate\Database\Eloquent\Factories\Factory;
+use Illuminate\Support\Facades\Hash;
+use Illuminate\Support\Str;
+
+/**
+ * @extends \Illuminate\Database\Eloquent\Factories\Factory<\App\Models\User>
+ */
+class UserFactory extends Factory
+{
+ /**
+ * The current password being used by the factory.
+ */
+ protected static ?string $password;
+
+ /**
+ * Define the model's default state.
+ *
+ * @return array
+ */
+ public function definition(): array
+ {
+ return [
+ 'name' => fake()->name(),
+ 'email' => fake()->unique()->safeEmail(),
+ 'email_verified_at' => now(),
+ 'password' => static::$password ??= Hash::make('password'),
+ 'remember_token' => Str::random(10),
+ ];
+ }
+
+ /**
+ * Indicate that the model's email address should be unverified.
+ */
+ public function unverified(): static
+ {
+ return $this->state(fn (array $attributes) => [
+ 'email_verified_at' => null,
+ ]);
+ }
+}
+```
+
+As you can see, in their most basic form, factories are classes that extend Laravel's base factory class and define a `definition` method. The `definition` method returns the default set of attribute values that should be applied when creating a model using the factory.
+
+Via the `fake` helper, factories have access to the [Faker](https://github.com/FakerPHP/Faker) PHP library, which allows you to conveniently generate various kinds of random data for testing and seeding.
+
+> [!NOTE]
+> You can change your application's Faker locale by updating the `faker_locale` option in your `config/app.php` configuration file.
+
+
+## Defining Model Factories
+
+
+### Generating Factories
+
+To create a factory, execute the `make:factory` [Artisan command](/docs/{{version}}/artisan):
+
+```shell
+php artisan make:factory PostFactory
+```
+
+The new factory class will be placed in your `database/factories` directory.
+
+
+#### Model and Factory Discovery Conventions
+
+Once you have defined your factories, you may use the static `factory` method provided to your models by the `Illuminate\Database\Eloquent\Factories\HasFactory` trait in order to instantiate a factory instance for that model.
+
+The `HasFactory` trait's `factory` method will use conventions to determine the proper factory for the model the trait is assigned to. Specifically, the method will look for a factory in the `Database\Factories` namespace that has a class name matching the model name and is suffixed with `Factory`. If these conventions do not apply to your particular application or factory, you may overwrite the `newFactory` method on your model to return an instance of the model's corresponding factory directly:
+
+```php
+use Database\Factories\Administration\FlightFactory;
+
+/**
+ * Create a new factory instance for the model.
+ */
+protected static function newFactory()
+{
+ return FlightFactory::new();
+}
+```
+
+Then, define a `model` property on the corresponding factory:
+
+```php
+use App\Administration\Flight;
+use Illuminate\Database\Eloquent\Factories\Factory;
+
+class FlightFactory extends Factory
+{
+ /**
+ * The name of the factory's corresponding model.
+ *
+ * @var class-string<\Illuminate\Database\Eloquent\Model>
+ */
+ protected $model = Flight::class;
+}
+```
+
+
+### Factory States
+
+State manipulation methods allow you to define discrete modifications that can be applied to your model factories in any combination. For example, your `Database\Factories\UserFactory` factory might contain a `suspended` state method that modifies one of its default attribute values.
+
+State transformation methods typically call the `state` method provided by Laravel's base factory class. The `state` method accepts a closure which will receive the array of raw attributes defined for the factory and should return an array of attributes to modify:
+
+```php
+use Illuminate\Database\Eloquent\Factories\Factory;
+
+/**
+ * Indicate that the user is suspended.
+ */
+public function suspended(): Factory
+{
+ return $this->state(function (array $attributes) {
+ return [
+ 'account_status' => 'suspended',
+ ];
+ });
+}
+```
+
+
+#### "Trashed" State
+
+If your Eloquent model can be [soft deleted](/docs/{{version}}/eloquent#soft-deleting), you may invoke the built-in `trashed` state method to indicate that the created model should already be "soft deleted". You do not need to manually define the `trashed` state as it is automatically available to all factories:
+
+```php
+use App\Models\User;
+
+$user = User::factory()->trashed()->create();
+```
+
+
+### Factory Callbacks
+
+Factory callbacks are registered using the `afterMaking` and `afterCreating` methods and allow you to perform additional tasks after making or creating a model. You should register these callbacks by defining a `configure` method on your factory class. This method will be automatically called by Laravel when the factory is instantiated:
+
+```php
+namespace Database\Factories;
+
+use App\Models\User;
+use Illuminate\Database\Eloquent\Factories\Factory;
+
+class UserFactory extends Factory
+{
+ /**
+ * Configure the model factory.
+ */
+ public function configure(): static
+ {
+ return $this->afterMaking(function (User $user) {
+ // ...
+ })->afterCreating(function (User $user) {
+ // ...
+ });
+ }
+
+ // ...
+}
+```
+
+You may also register factory callbacks within state methods to perform additional tasks that are specific to a given state:
+
+```php
+use App\Models\User;
+use Illuminate\Database\Eloquent\Factories\Factory;
+
+/**
+ * Indicate that the user is suspended.
+ */
+public function suspended(): Factory
+{
+ return $this->state(function (array $attributes) {
+ return [
+ 'account_status' => 'suspended',
+ ];
+ })->afterMaking(function (User $user) {
+ // ...
+ })->afterCreating(function (User $user) {
+ // ...
+ });
+}
+```
+
+
+## Creating Models Using Factories
+
+
+### Instantiating Models
+
+Once you have defined your factories, you may use the static `factory` method provided to your models by the `Illuminate\Database\Eloquent\Factories\HasFactory` trait in order to instantiate a factory instance for that model. Let's take a look at a few examples of creating models. First, we'll use the `make` method to create models without persisting them to the database:
+
+```php
+use App\Models\User;
+
+$user = User::factory()->make();
+```
+
+You may create a collection of many models using the `count` method:
+
+```php
+$users = User::factory()->count(3)->make();
+```
+
+
+#### Applying States
+
+You may also apply any of your [states](#factory-states) to the models. If you would like to apply multiple state transformations to the models, you may simply call the state transformation methods directly:
+
+```php
+$users = User::factory()->count(5)->suspended()->make();
+```
+
+
+#### Overriding Attributes
+
+If you would like to override some of the default values of your models, you may pass an array of values to the `make` method. Only the specified attributes will be replaced while the rest of the attributes remain set to their default values as specified by the factory:
+
+```php
+$user = User::factory()->make([
+ 'name' => 'Abigail Otwell',
+]);
+```
+
+Alternatively, the `state` method may be called directly on the factory instance to perform an inline state transformation:
+
+```php
+$user = User::factory()->state([
+ 'name' => 'Abigail Otwell',
+])->make();
+```
+
+> [!NOTE]
+> [Mass assignment protection](/docs/{{version}}/eloquent#mass-assignment) is automatically disabled when creating models using factories.
+
+
+### Persisting Models
+
+The `create` method instantiates model instances and persists them to the database using Eloquent's `save` method:
+
+```php
+use App\Models\User;
+
+// Create a single App\Models\User instance...
+$user = User::factory()->create();
+
+// Create three App\Models\User instances...
+$users = User::factory()->count(3)->create();
+```
+
+You may override the factory's default model attributes by passing an array of attributes to the `create` method:
+
+```php
+$user = User::factory()->create([
+ 'name' => 'Abigail',
+]);
+```
+
+
+### Sequences
+
+Sometimes you may wish to alternate the value of a given model attribute for each created model. You may accomplish this by defining a state transformation as a sequence. For example, you may wish to alternate the value of an `admin` column between `Y` and `N` for each created user:
+
+```php
+use App\Models\User;
+use Illuminate\Database\Eloquent\Factories\Sequence;
+
+$users = User::factory()
+ ->count(10)
+ ->state(new Sequence(
+ ['admin' => 'Y'],
+ ['admin' => 'N'],
+ ))
+ ->create();
+```
+
+In this example, five users will be created with an `admin` value of `Y` and five users will be created with an `admin` value of `N`.
+
+If necessary, you may include a closure as a sequence value. The closure will be invoked each time the sequence needs a new value:
+
+```php
+use Illuminate\Database\Eloquent\Factories\Sequence;
+
+$users = User::factory()
+ ->count(10)
+ ->state(new Sequence(
+ fn (Sequence $sequence) => ['role' => UserRoles::all()->random()],
+ ))
+ ->create();
+```
+
+Within a sequence closure, you may access the `$index` property on the sequence instance that is injected into the closure. The `$index` property contains the number of iterations through the sequence that have occurred thus far:
+
+```php
+$users = User::factory()
+ ->count(10)
+ ->state(new Sequence(
+ fn (Sequence $sequence) => ['name' => 'Name '.$sequence->index],
+ ))
+ ->create();
+```
+
+For convenience, sequences may also be applied using the `sequence` method, which simply invokes the `state` method internally. The `sequence` method accepts a closure or arrays of sequenced attributes:
+
+```php
+$users = User::factory()
+ ->count(2)
+ ->sequence(
+ ['name' => 'First User'],
+ ['name' => 'Second User'],
+ )
+ ->create();
+```
+
+
+## Factory Relationships
+
+
+### Has Many Relationships
+
+Next, let's explore building Eloquent model relationships using Laravel's fluent factory methods. First, let's assume our application has an `App\Models\User` model and an `App\Models\Post` model. Also, let's assume that the `User` model defines a `hasMany` relationship with `Post`. We can create a user that has three posts using the `has` method provided by the Laravel's factories. The `has` method accepts a factory instance:
+
+```php
+use App\Models\Post;
+use App\Models\User;
+
+$user = User::factory()
+ ->has(Post::factory()->count(3))
+ ->create();
+```
+
+By convention, when passing a `Post` model to the `has` method, Laravel will assume that the `User` model must have a `posts` method that defines the relationship. If necessary, you may explicitly specify the name of the relationship that you would like to manipulate:
+
+```php
+$user = User::factory()
+ ->has(Post::factory()->count(3), 'posts')
+ ->create();
+```
+
+Of course, you may perform state manipulations on the related models. In addition, you may pass a closure-based state transformation if your state change requires access to the parent model:
+
+```php
+$user = User::factory()
+ ->has(
+ Post::factory()
+ ->count(3)
+ ->state(function (array $attributes, User $user) {
+ return ['user_type' => $user->type];
+ })
+ )
+ ->create();
+```
+
+
+#### Using Magic Methods
+
+For convenience, you may use Laravel's magic factory relationship methods to build relationships. For example, the following example will use convention to determine that the related models should be created via a `posts` relationship method on the `User` model:
+
+```php
+$user = User::factory()
+ ->hasPosts(3)
+ ->create();
+```
+
+When using magic methods to create factory relationships, you may pass an array of attributes to override on the related models:
+
+```php
+$user = User::factory()
+ ->hasPosts(3, [
+ 'published' => false,
+ ])
+ ->create();
+```
+
+You may provide a closure-based state transformation if your state change requires access to the parent model:
+
+```php
+$user = User::factory()
+ ->hasPosts(3, function (array $attributes, User $user) {
+ return ['user_type' => $user->type];
+ })
+ ->create();
+```
+
+
+### Belongs To Relationships
+
+Now that we have explored how to build "has many" relationships using factories, let's explore the inverse of the relationship. The `for` method may be used to define the parent model that factory created models belong to. For example, we can create three `App\Models\Post` model instances that belong to a single user:
+
+```php
+use App\Models\Post;
+use App\Models\User;
+
+$posts = Post::factory()
+ ->count(3)
+ ->for(User::factory()->state([
+ 'name' => 'Jessica Archer',
+ ]))
+ ->create();
+```
+
+If you already have a parent model instance that should be associated with the models you are creating, you may pass the model instance to the `for` method:
+
+```php
+$user = User::factory()->create();
+
+$posts = Post::factory()
+ ->count(3)
+ ->for($user)
+ ->create();
+```
+
+
+#### Using Magic Methods
+
+For convenience, you may use Laravel's magic factory relationship methods to define "belongs to" relationships. For example, the following example will use convention to determine that the three posts should belong to the `user` relationship on the `Post` model:
+
+```php
+$posts = Post::factory()
+ ->count(3)
+ ->forUser([
+ 'name' => 'Jessica Archer',
+ ])
+ ->create();
+```
+
+
+### Many to Many Relationships
+
+Like [has many relationships](#has-many-relationships), "many to many" relationships may be created using the `has` method:
+
+```php
+use App\Models\Role;
+use App\Models\User;
+
+$user = User::factory()
+ ->has(Role::factory()->count(3))
+ ->create();
+```
+
+
+#### Pivot Table Attributes
+
+If you need to define attributes that should be set on the pivot / intermediate table linking the models, you may use the `hasAttached` method. This method accepts an array of pivot table attribute names and values as its second argument:
+
+```php
+use App\Models\Role;
+use App\Models\User;
+
+$user = User::factory()
+ ->hasAttached(
+ Role::factory()->count(3),
+ ['active' => true]
+ )
+ ->create();
+```
+
+You may provide a closure-based state transformation if your state change requires access to the related model:
+
+```php
+$user = User::factory()
+ ->hasAttached(
+ Role::factory()
+ ->count(3)
+ ->state(function (array $attributes, User $user) {
+ return ['name' => $user->name.' Role'];
+ }),
+ ['active' => true]
+ )
+ ->create();
+```
+
+If you already have model instances that you would like to be attached to the models you are creating, you may pass the model instances to the `hasAttached` method. In this example, the same three roles will be attached to all three users:
+
+```php
+$roles = Role::factory()->count(3)->create();
+
+$users = User::factory()
+ ->count(3)
+ ->hasAttached($roles, ['active' => true])
+ ->create();
+```
+
+
+#### Using Magic Methods
+
+For convenience, you may use Laravel's magic factory relationship methods to define many to many relationships. For example, the following example will use convention to determine that the related models should be created via a `roles` relationship method on the `User` model:
+
+```php
+$user = User::factory()
+ ->hasRoles(1, [
+ 'name' => 'Editor'
+ ])
+ ->create();
+```
+
+
+### Polymorphic Relationships
+
+[Polymorphic relationships](/docs/{{version}}/eloquent-relationships#polymorphic-relationships) may also be created using factories. Polymorphic "morph many" relationships are created in the same way as typical "has many" relationships. For example, if an `App\Models\Post` model has a `morphMany` relationship with an `App\Models\Comment` model:
+
+```php
+use App\Models\Post;
+
+$post = Post::factory()->hasComments(3)->create();
+```
+
+
+#### Morph To Relationships
+
+Magic methods may not be used to create `morphTo` relationships. Instead, the `for` method must be used directly and the name of the relationship must be explicitly provided. For example, imagine that the `Comment` model has a `commentable` method that defines a `morphTo` relationship. In this situation, we may create three comments that belong to a single post by using the `for` method directly:
+
+```php
+$comments = Comment::factory()->count(3)->for(
+ Post::factory(), 'commentable'
+)->create();
+```
+
+
+#### Polymorphic Many to Many Relationships
+
+Polymorphic "many to many" (`morphToMany` / `morphedByMany`) relationships may be created just like non-polymorphic "many to many" relationships:
+
+```php
+use App\Models\Tag;
+use App\Models\Video;
+
+$video = Video::factory()
+ ->hasAttached(
+ Tag::factory()->count(3),
+ ['public' => true]
+ )
+ ->create();
+```
+
+Of course, the magic `has` method may also be used to create polymorphic "many to many" relationships:
+
+```php
+$video = Video::factory()
+ ->hasTags(3, ['public' => true])
+ ->create();
+```
+
+
+### Defining Relationships Within Factories
+
+To define a relationship within your model factory, you will typically assign a new factory instance to the foreign key of the relationship. This is normally done for the "inverse" relationships such as `belongsTo` and `morphTo` relationships. For example, if you would like to create a new user when creating a post, you may do the following:
+
+```php
+use App\Models\User;
+
+/**
+ * Define the model's default state.
+ *
+ * @return array
+ */
+public function definition(): array
+{
+ return [
+ 'user_id' => User::factory(),
+ 'title' => fake()->title(),
+ 'content' => fake()->paragraph(),
+ ];
+}
+```
+
+If the relationship's columns depend on the factory that defines it you may assign a closure to an attribute. The closure will receive the factory's evaluated attribute array:
+
+```php
+/**
+ * Define the model's default state.
+ *
+ * @return array
+ */
+public function definition(): array
+{
+ return [
+ 'user_id' => User::factory(),
+ 'user_type' => function (array $attributes) {
+ return User::find($attributes['user_id'])->type;
+ },
+ 'title' => fake()->title(),
+ 'content' => fake()->paragraph(),
+ ];
+}
+```
+
+
+### Recycling an Existing Model for Relationships
+
+If you have models that share a common relationship with another model, you may use the `recycle` method to ensure a single instance of the related model is recycled for all of the relationships created by the factory.
+
+For example, imagine you have `Airline`, `Flight`, and `Ticket` models, where the ticket belongs to an airline and a flight, and the flight also belongs to an airline. When creating tickets, you will probably want the same airline for both the ticket and the flight, so you may pass an airline instance to the `recycle` method:
+
+```php
+Ticket::factory()
+ ->recycle(Airline::factory()->create())
+ ->create();
+```
+
+You may find the `recycle` method particularly useful if you have models belonging to a common user or team.
+
+The `recycle` method also accepts a collection of existing models. When a collection is provided to the `recycle` method, a random model from the collection will be chosen when the factory needs a model of that type:
+
+```php
+Ticket::factory()
+ ->recycle($airlines)
+ ->create();
+```
diff --git a/eloquent-mutators.md b/eloquent-mutators.md
index c112ebd8c1f..f8ef3c27789 100644
--- a/eloquent-mutators.md
+++ b/eloquent-mutators.md
@@ -1,11 +1,11 @@
# Eloquent: Mutators & Casting
- [Introduction](#introduction)
-- [Accessors & Mutators](#accessors-and-mutators)
- - [Defining An Accessor](#defining-an-accessor)
- - [Defining A Mutator](#defining-a-mutator)
+- [Accessors and Mutators](#accessors-and-mutators)
+ - [Defining an Accessor](#defining-an-accessor)
+ - [Defining a Mutator](#defining-a-mutator)
- [Attribute Casting](#attribute-casting)
- - [Array & JSON Casting](#array-and-json-casting)
+ - [Array and JSON Casting](#array-and-json-casting)
- [Date Casting](#date-casting)
- [Enum Casting](#enum-casting)
- [Encrypted Casting](#encrypted-casting)
@@ -15,6 +15,7 @@
- [Array / JSON Serialization](#array-json-serialization)
- [Inbound Casting](#inbound-casting)
- [Cast Parameters](#cast-parameters)
+ - [Comparing Cast Values](#comparing-cast-values)
- [Castables](#castables)
@@ -23,48 +24,51 @@
Accessors, mutators, and attribute casting allow you to transform Eloquent attribute values when you retrieve or set them on model instances. For example, you may want to use the [Laravel encrypter](/docs/{{version}}/encryption) to encrypt a value while it is stored in the database, and then automatically decrypt the attribute when you access it on an Eloquent model. Or, you may want to convert a JSON string that is stored in your database to an array when it is accessed via your Eloquent model.
-## Accessors & Mutators
+## Accessors and Mutators
-### Defining An Accessor
+### Defining an Accessor
An accessor transforms an Eloquent attribute value when it is accessed. To define an accessor, create a protected method on your model to represent the accessible attribute. This method name should correspond to the "camel case" representation of the true underlying model attribute / database column when applicable.
In this example, we'll define an accessor for the `first_name` attribute. The accessor will automatically be called by Eloquent when attempting to retrieve the value of the `first_name` attribute. All attribute accessor / mutator methods must declare a return type-hint of `Illuminate\Database\Eloquent\Casts\Attribute`:
- ucfirst($value),
- );
- }
+ return Attribute::make(
+ get: fn (string $value) => ucfirst($value),
+ );
}
+}
+```
All accessor methods return an `Attribute` instance which defines how the attribute will be accessed and, optionally, mutated. In this example, we are only defining how the attribute will be accessed. To do so, we supply the `get` argument to the `Attribute` class constructor.
As you can see, the original value of the column is passed to the accessor, allowing you to manipulate and return the value. To access the value of the accessor, you may simply access the `first_name` attribute on a model instance:
- use App\Models\User;
+```php
+use App\Models\User;
- $user = User::find(1);
+$user = User::find(1);
- $firstName = $user->first_name;
+$firstName = $user->first_name;
+```
-> {tip} If you would like these computed values to be added to the array / JSON representations of your model, [you will need to append them](/docs/{{version}}/eloquent-serialization#appending-values-to-json).
+> [!NOTE]
+> If you would like these computed values to be added to the array / JSON representations of your model, [you will need to append them](/docs/{{version}}/eloquent-serialization#appending-values-to-json).
#### Building Value Objects From Multiple Attributes
@@ -77,13 +81,11 @@ use Illuminate\Database\Eloquent\Casts\Attribute;
/**
* Interact with the user's address.
- *
- * @return \Illuminate\Database\Eloquent\Casts\Attribute
*/
-public function address(): Attribute
+protected function address(): Attribute
{
- return new Attribute(
- get: fn ($value, $attributes) => new Address(
+ return Attribute::make(
+ get: fn (mixed $value, array $attributes) => new Address(
$attributes['address_line_one'],
$attributes['address_line_two'],
),
@@ -91,74 +93,89 @@ public function address(): Attribute
}
```
-When returning value objects from accessors, any changes made to the value object will automatically be synced back to the model before the model is saved. This is possible because Eloquent retains instances returned by accessors so it can be return the same instance each time the accessor is invoked:
+
+#### Accessor Caching
+
+When returning value objects from accessors, any changes made to the value object will automatically be synced back to the model before the model is saved. This is possible because Eloquent retains instances returned by accessors so it can return the same instance each time the accessor is invoked:
+
+```php
+use App\Models\User;
- use App\Models\User;
+$user = User::find(1);
- $user = User::find(1);
+$user->address->lineOne = 'Updated Address Line 1 Value';
+$user->address->lineTwo = 'Updated Address Line 2 Value';
- $user->address->lineOne = 'Updated Address Line 1 Value';
- $user->address->lineTwo = 'Updated Address Line 2 Value';
+$user->save();
+```
- $user->save();
+However, you may sometimes wish to enable caching for primitive values like strings and booleans, particularly if they are computationally intensive. To accomplish this, you may invoke the `shouldCache` method when defining your accessor:
+
+```php
+protected function hash(): Attribute
+{
+ return Attribute::make(
+ get: fn (string $value) => bcrypt(gzuncompress($value)),
+ )->shouldCache();
+}
+```
If you would like to disable the object caching behavior of attributes, you may invoke the `withoutObjectCaching` method when defining the attribute:
```php
/**
* Interact with the user's address.
- *
- * @return \Illuminate\Database\Eloquent\Casts\Attribute
*/
-public function address(): Attribute
+protected function address(): Attribute
{
- return (new Attribute(
- get: fn ($value, $attributes) => new Address(
+ return Attribute::make(
+ get: fn (mixed $value, array $attributes) => new Address(
$attributes['address_line_one'],
$attributes['address_line_two'],
),
- ))->withoutObjectCaching();
+ )->withoutObjectCaching();
}
```
-### Defining A Mutator
+### Defining a Mutator
A mutator transforms an Eloquent attribute value when it is set. To define a mutator, you may provide the `set` argument when defining your attribute. Let's define a mutator for the `first_name` attribute. This mutator will be automatically called when we attempt to set the value of the `first_name` attribute on the model:
- ucfirst($value),
- set: fn ($value) => strtolower($value),
- );
- }
+ return Attribute::make(
+ get: fn (string $value) => ucfirst($value),
+ set: fn (string $value) => strtolower($value),
+ );
}
+}
+```
The mutator closure will receive the value that is being set on the attribute, allowing you to manipulate the value and return the manipulated value. To use our mutator, we only need to set the `first_name` attribute on an Eloquent model:
- use App\Models\User;
+```php
+use App\Models\User;
- $user = User::find(1);
+$user = User::find(1);
- $user->first_name = 'Sally';
+$user->first_name = 'Sally';
+```
-In this example, the `set` callback will be called with the value `Sally`. The mutator will then apply the `strtolower` function to the name and set its resulting value in model's the internal `$attributes` array.
+In this example, the `set` callback will be called with the value `Sally`. The mutator will then apply the `strtolower` function to the name and set its resulting value in the model's internal `$attributes` array.
#### Mutating Multiple Attributes
@@ -171,13 +188,11 @@ use Illuminate\Database\Eloquent\Casts\Attribute;
/**
* Interact with the user's address.
- *
- * @return \Illuminate\Database\Eloquent\Casts\Attribute
*/
-public function address(): Attribute
+protected function address(): Attribute
{
- return new Attribute(
- get: fn ($value, $attributes) => new Address(
+ return Attribute::make(
+ get: fn (mixed $value, array $attributes) => new Address(
$attributes['address_line_one'],
$attributes['address_line_two'],
),
@@ -192,27 +207,30 @@ public function address(): Attribute
## Attribute Casting
-Attribute casting provides functionality similar to accessors and mutators without requiring you to define any additional methods on your model. Instead, your model's `$casts` property provides a convenient method of converting attributes to common data types.
+Attribute casting provides functionality similar to accessors and mutators without requiring you to define any additional methods on your model. Instead, your model's `casts` method provides a convenient way of converting attributes to common data types.
-The `$casts` property should be an array where the key is the name of the attribute being cast and the value is the type you wish to cast the column to. The supported cast types are:
+The `casts` method should return an array where the key is the name of the attribute being cast and the value is the type you wish to cast the column to. The supported cast types are:
@@ -261,30 +176,39 @@ Laravel includes a variety of global "helper" PHP functions. Many of these funct
[bcrypt](#method-bcrypt)
[blank](#method-blank)
[broadcast](#method-broadcast)
+[broadcast_if](#method-broadcast-if)
+[broadcast_unless](#method-broadcast-unless)
[cache](#method-cache)
[class_uses_recursive](#method-class-uses-recursive)
[collect](#method-collect)
[config](#method-config)
+[context](#method-context)
[cookie](#method-cookie)
[csrf_field](#method-csrf-field)
[csrf_token](#method-csrf-token)
[decrypt](#method-decrypt)
[dd](#method-dd)
[dispatch](#method-dispatch)
+[dispatch_sync](#method-dispatch-sync)
[dump](#method-dump)
[encrypt](#method-encrypt)
[env](#method-env)
[event](#method-event)
+[fake](#method-fake)
[filled](#method-filled)
[info](#method-info)
+[literal](#method-literal)
[logger](#method-logger)
[method_field](#method-method-field)
[now](#method-now)
[old](#method-old)
+[once](#method-once)
[optional](#method-optional)
[policy](#method-policy)
[redirect](#method-redirect)
[report](#method-report)
+[report_if](#method-report-if)
+[report_unless](#method-report-unless)
[request](#method-request)
[rescue](#method-rescue)
[resolve](#method-resolve)
@@ -301,22 +225,10 @@ Laravel includes a variety of global "helper" PHP functions. Many of these funct
[value](#method-value)
[view](#method-view)
[with](#method-with)
+[when](#method-when)
+[append](#method-append)
[contains](#method-contains)
[diff](#method-diff)
[except](#method-except)
[find](#method-find)
+[findOrFail](#method-find-or-fail)
[fresh](#method-fresh)
[intersect](#method-intersect)
[load](#method-load)
@@ -72,155 +80,272 @@ In addition, the `Illuminate\Database\Eloquent\Collection` class provides a supe
[makeVisible](#method-makeVisible)
[makeHidden](#method-makeHidden)
[only](#method-only)
+[partition](#method-partition)
+[setVisible](#method-setVisible)
+[setHidden](#method-setHidden)
[toQuery](#method-toquery)
[unique](#method-unique)
+
+#### `append($attributes)` {.collection-method .first-collection-method}
+
+The `append` method may be used to indicate that an attribute should be [appended](/docs/{{version}}/eloquent-serialization#appending-values-to-json) for every model in the collection. This method accepts an array of attributes or a single attribute:
+
+```php
+$users->append('team');
+
+$users->append(['team', 'is_admin']);
+```
+
-#### `contains($key, $operator = null, $value = null)` {.collection-method .first-collection-method}
+#### `contains($key, $operator = null, $value = null)` {.collection-method}
The `contains` method may be used to determine if a given model instance is contained by the collection. This method accepts a primary key or a model instance:
- $users->contains(1);
+```php
+$users->contains(1);
- $users->contains(User::find(1));
+$users->contains(User::find(1));
+```
#### `diff($items)` {.collection-method}
The `diff` method returns all of the models that are not present in the given collection:
- use App\Models\User;
+```php
+use App\Models\User;
- $users = $users->diff(User::whereIn('id', [1, 2, 3])->get());
+$users = $users->diff(User::whereIn('id', [1, 2, 3])->get());
+```
#### `except($keys)` {.collection-method}
The `except` method returns all of the models that do not have the given primary keys:
- $users = $users->except([1, 2, 3]);
+```php
+$users = $users->except([1, 2, 3]);
+```
#### `find($key)` {.collection-method}
The `find` method returns the model that has a primary key matching the given key. If `$key` is a model instance, `find` will attempt to return a model matching the primary key. If `$key` is an array of keys, `find` will return all models which have a primary key in the given array:
- $users = User::all();
+```php
+$users = User::all();
+
+$user = $users->find(1);
+```
+
+
+#### `findOrFail($key)` {.collection-method}
+
+The `findOrFail` method returns the model that has a primary key matching the given key or throws an `Illuminate\Database\Eloquent\ModelNotFoundException` exception if no matching model can be found in the collection:
- $user = $users->find(1);
+```php
+$users = User::all();
+
+$user = $users->findOrFail(1);
+```
#### `fresh($with = [])` {.collection-method}
The `fresh` method retrieves a fresh instance of each model in the collection from the database. In addition, any specified relationships will be eager loaded:
- $users = $users->fresh();
+```php
+$users = $users->fresh();
- $users = $users->fresh('comments');
+$users = $users->fresh('comments');
+```
#### `intersect($items)` {.collection-method}
The `intersect` method returns all of the models that are also present in the given collection:
- use App\Models\User;
+```php
+use App\Models\User;
- $users = $users->intersect(User::whereIn('id', [1, 2, 3])->get());
+$users = $users->intersect(User::whereIn('id', [1, 2, 3])->get());
+```
#### `load($relations)` {.collection-method}
The `load` method eager loads the given relationships for all models in the collection:
- $users->load(['comments', 'posts']);
+```php
+$users->load(['comments', 'posts']);
+
+$users->load('comments.author');
- $users->load('comments.author');
+$users->load(['comments', 'posts' => fn ($query) => $query->where('active', 1)]);
+```
#### `loadMissing($relations)` {.collection-method}
The `loadMissing` method eager loads the given relationships for all models in the collection if the relationships are not already loaded:
- $users->loadMissing(['comments', 'posts']);
+```php
+$users->loadMissing(['comments', 'posts']);
- $users->loadMissing('comments.author');
+$users->loadMissing('comments.author');
+
+$users->loadMissing(['comments', 'posts' => fn ($query) => $query->where('active', 1)]);
+```
#### `modelKeys()` {.collection-method}
The `modelKeys` method returns the primary keys for all models in the collection:
- $users->modelKeys();
+```php
+$users->modelKeys();
- // [1, 2, 3, 4, 5]
+// [1, 2, 3, 4, 5]
+```
#### `makeVisible($attributes)` {.collection-method}
The `makeVisible` method [makes attributes visible](/docs/{{version}}/eloquent-serialization#hiding-attributes-from-json) that are typically "hidden" on each model in the collection:
- $users = $users->makeVisible(['address', 'phone_number']);
+```php
+$users = $users->makeVisible(['address', 'phone_number']);
+```
#### `makeHidden($attributes)` {.collection-method}
The `makeHidden` method [hides attributes](/docs/{{version}}/eloquent-serialization#hiding-attributes-from-json) that are typically "visible" on each model in the collection:
- $users = $users->makeHidden(['address', 'phone_number']);
+```php
+$users = $users->makeHidden(['address', 'phone_number']);
+```
#### `only($keys)` {.collection-method}
The `only` method returns all of the models that have the given primary keys:
- $users = $users->only([1, 2, 3]);
+```php
+$users = $users->only([1, 2, 3]);
+```
+
+
+#### `partition` {.collection-method}
+
+The `partition` method returns an instance of `Illuminate\Support\Collection` containing `Illuminate\Database\Eloquent\Collection` collection instances:
+
+```php
+$partition = $users->partition(fn ($user) => $user->age > 18);
+
+dump($partition::class); // Illuminate\Support\Collection
+dump($partition[0]::class); // Illuminate\Database\Eloquent\Collection
+dump($partition[1]::class); // Illuminate\Database\Eloquent\Collection
+```
+
+
+#### `setVisible($attributes)` {.collection-method}
+
+The `setVisible` method [temporarily overrides](/docs/{{version}}/eloquent-serialization#temporarily-modifying-attribute-visibility) all of the visible attributes on each model in the collection:
+
+```php
+$users = $users->setVisible(['id', 'name']);
+```
+
+
+#### `setHidden($attributes)` {.collection-method}
+
+The `setHidden` method [temporarily overrides](/docs/{{version}}/eloquent-serialization#temporarily-modifying-attribute-visibility) all of the hidden attributes on each model in the collection:
+
+```php
+$users = $users->setHidden(['email', 'password', 'remember_token']);
+```
#### `toQuery()` {.collection-method}
The `toQuery` method returns an Eloquent query builder instance containing a `whereIn` constraint on the collection model's primary keys:
- use App\Models\User;
+```php
+use App\Models\User;
- $users = User::where('status', 'VIP')->get();
+$users = User::where('status', 'VIP')->get();
- $users->toQuery()->update([
- 'status' => 'Administrator',
- ]);
+$users->toQuery()->update([
+ 'status' => 'Administrator',
+]);
+```
#### `unique($key = null, $strict = false)` {.collection-method}
-The `unique` method returns all of the unique models in the collection. Any models of the same type with the same primary key as another model in the collection are removed:
+The `unique` method returns all of the unique models in the collection. Any models with the same primary key as another model in the collection are removed:
- $users = $users->unique();
+```php
+$users = $users->unique();
+```
## Custom Collections
-If you would like to use a custom `Collection` object when interacting with a given model, you may define a `newCollection` method on your model:
+If you would like to use a custom `Collection` object when interacting with a given model, you may add the `CollectedBy` attribute to your model:
+
+```php
+ $models
+ * @return \Illuminate\Database\Eloquent\Collection
- `array`
+- `AsFluent::class`
- `AsStringable::class`
+- `AsUri::class`
- `boolean`
- `collection`
- `date`
- `datetime`
- `immutable_date`
- `immutable_datetime`
-- `decimal:`
+ */
+protected function casts(): array
+{
+ return [
+ 'options' => 'json:unicode',
+ ];
+}
+```
-#### Array Object & Collection Casting
+#### Array Object and Collection Casting
Although the standard `array` cast is sufficient for many applications, it does have some disadvantages. Since the `array` cast returns a primitive type, it is not possible to mutate an offset of the array directly. For example, the following code will trigger a PHP error:
- $user = User::find(1);
+```php
+$user = User::find(1);
- $user->options['key'] = $value;
+$user->options['key'] = $value;
+```
To solve this, Laravel offers an `AsArrayObject` cast that casts your JSON attribute to an [ArrayObject](https://www.php.net/manual/en/class.arrayobject.php) class. This feature is implemented using Laravel's [custom cast](#custom-casts) implementation, which allows Laravel to intelligently cache and transform the mutated object such that individual offsets may be modified without triggering a PHP error. To use the `AsArrayObject` cast, simply assign it to an attribute:
- use Illuminate\Database\Eloquent\Casts\AsArrayObject;
+```php
+use Illuminate\Database\Eloquent\Casts\AsArrayObject;
- /**
- * The attributes that should be cast.
- *
- * @var array
- */
- protected $casts = [
+/**
+ * Get the attributes that should be cast.
+ *
+ * @return array
+ */
+protected function casts(): array
+{
+ return [
'options' => AsArrayObject::class,
];
+}
+```
Similarly, Laravel offers an `AsCollection` cast that casts your JSON attribute to a Laravel [Collection](/docs/{{version}}/collections) instance:
- use Illuminate\Database\Eloquent\Casts\AsCollection;
+```php
+use Illuminate\Database\Eloquent\Casts\AsCollection;
+
+/**
+ * Get the attributes that should be cast.
+ *
+ * @return array
+ */
+protected function casts(): array
+{
+ return [
+ 'options' => AsCollection::class,
+ ];
+}
+```
+
+If you would like the `AsCollection` cast to instantiate a custom collection class instead of Laravel's base collection class, you may provide the collection class name as a cast argument:
+
+```php
+use App\Collections\OptionCollection;
+use Illuminate\Database\Eloquent\Casts\AsCollection;
+
+/**
+ * Get the attributes that should be cast.
+ *
+ * @return array
+ */
+protected function casts(): array
+{
+ return [
+ 'options' => AsCollection::using(OptionCollection::class),
+ ];
+}
+```
+
+The `of` method may be used to indicate collection items should be mapped into a given class via the collection's [mapInto method](/docs/{{version}}/collections#method-mapinto):
+
+```php
+use App\ValueObjects\Option;
+use Illuminate\Database\Eloquent\Casts\AsCollection;
+
+/**
+ * Get the attributes that should be cast.
+ *
+ * @return array
+ */
+protected function casts(): array
+{
+ return [
+ 'options' => AsCollection::of(Option::class)
+ ];
+}
+```
+
+When mapping collections to objects, the object should implement the `Illuminate\Contracts\Support\Arrayable` and `JsonSerializable` interfaces to define how their instances should be serialized into the database as JSON:
+
+```php
+name = $data['name'];
+ $this->value = $data['value'];
+ $this->isLocked = $data['is_locked'];
+ }
+
+ /**
+ * Get the instance as an array.
+ *
+ * @return array{name: string, data: string, is_locked: bool}
+ */
+ public function toArray(): array
+ {
+ return [
+ 'name' => $this->name,
+ 'value' => $this->value,
+ 'is_locked' => $this->isLocked,
+ ];
+ }
/**
- * The attributes that should be cast.
+ * Specify the data which should be serialized to JSON.
*
- * @var array
+ * @return array{name: string, data: string, is_locked: bool}
*/
- protected $casts = [
- 'options' => AsCollection::class,
- ];
+ public function jsonSerialize(): array
+ {
+ return $this->toArray();
+ }
+}
+```
### Date Casting
-By default, Eloquent will cast the `created_at` and `updated_at` columns to instances of [Carbon](https://github.com/briannesbitt/Carbon), which extends the PHP `DateTime` class and provides an assortment of helpful methods. You may cast additional date attributes by defining additional date casts within your model's `$casts` property array. Typically, dates should be cast using the `datetime` or `immutable_datetime` cast types.
+By default, Eloquent will cast the `created_at` and `updated_at` columns to instances of [Carbon](https://github.com/briannesbitt/Carbon), which extends the PHP `DateTime` class and provides an assortment of helpful methods. You may cast additional date attributes by defining additional date casts within your model's `casts` method. Typically, dates should be cast using the `datetime` or `immutable_datetime` cast types.
When defining a `date` or `datetime` cast, you may also specify the date's format. This format will be used when the [model is serialized to an array or JSON](/docs/{{version}}/eloquent-serialization):
- /**
- * The attributes that should be cast.
- *
- * @var array
- */
- protected $casts = [
+```php
+/**
+ * Get the attributes that should be cast.
+ *
+ * @return array
+ */
+protected function casts(): array
+{
+ return [
'created_at' => 'datetime:Y-m-d',
];
+}
+```
When a column is cast as a date, you may set the corresponding model attribute value to a UNIX timestamp, date string (`Y-m-d`), date-time string, or a `DateTime` / `Carbon` instance. The date's value will be correctly converted and stored in your database.
You may customize the default serialization format for all of your model's dates by defining a `serializeDate` method on your model. This method does not affect how your dates are formatted for storage in the database:
- /**
- * Prepare a date for array / JSON serialization.
- *
- * @param \DateTimeInterface $date
- * @return string
- */
- protected function serializeDate(DateTimeInterface $date)
- {
- return $date->format('Y-m-d');
- }
+```php
+/**
+ * Prepare a date for array / JSON serialization.
+ */
+protected function serializeDate(DateTimeInterface $date): string
+{
+ return $date->format('Y-m-d');
+}
+```
To specify the format that should be used when actually storing a model's dates within your database, you should define a `$dateFormat` property on your model:
- /**
- * The storage format of the model's date columns.
- *
- * @var string
- */
- protected $dateFormat = 'U';
+```php
+/**
+ * The storage format of the model's date columns.
+ *
+ * @var string
+ */
+protected $dateFormat = 'U';
+```
-#### Date Casting, Serialization, & Timezones
+#### Date Casting, Serialization, and Timezones
-By default, the `date` and `datetime` casts will serialize dates to a UTC ISO-8601 date string (`1986-05-28T21:05:54.000000Z`), regardless of the timezone specified in your application's `timezone` configuration option. You are strongly encouraged to always use this serialization format, as well as to store your application's dates in the UTC timezone by not changing your application's `timezone` configuration option from its default `UTC` value. Consistently using the UTC timezone throughout your application will provide the maximum level of interoperability with other date manipulation libraries written in PHP and JavaScript.
+By default, the `date` and `datetime` casts will serialize dates to a UTC ISO-8601 date string (`YYYY-MM-DDTHH:MM:SS.uuuuuuZ`), regardless of the timezone specified in your application's `timezone` configuration option. You are strongly encouraged to always use this serialization format, as well as to store your application's dates in the UTC timezone by not changing your application's `timezone` configuration option from its default `UTC` value. Consistently using the UTC timezone throughout your application will provide the maximum level of interoperability with other date manipulation libraries written in PHP and JavaScript.
-If a custom format is applied to the `date` or `datetime` cast, such as `datetime:Y-m-d H:i:s`, the inner timezone of the Carbon instance will be used during date serialization. Typically, this will be the timezone specified in your application's `timezone` configuration option.
+If a custom format is applied to the `date` or `datetime` cast, such as `datetime:Y-m-d H:i:s`, the inner timezone of the Carbon instance will be used during date serialization. Typically, this will be the timezone specified in your application's `timezone` configuration option. However, it's important to note that `timestamp` columns such as `created_at` and `updated_at` are exempt from this behavior and are always formatted in UTC, regardless of the application's timezone setting.
### Enum Casting
-> {note} Enum casting is only available for PHP 8.1+.
-
-Eloquent also allows you to cast your attribute values to PHP ["backed" enums](https://www.php.net/manual/en/language.enumerations.backed.php). To accomplish this, you may specify the attribute and enum you wish to cast in your model's `$casts` property array:
+Eloquent also allows you to cast your attribute values to PHP [Enums](https://www.php.net/manual/en/language.enumerations.backed.php). To accomplish this, you may specify the attribute and enum you wish to cast in your model's `casts` method:
- use App\Enums\ServerStatus;
+```php
+use App\Enums\ServerStatus;
- /**
- * The attributes that should be cast.
- *
- * @var array
- */
- protected $casts = [
+/**
+ * Get the attributes that should be cast.
+ *
+ * @return array
+ */
+protected function casts(): array
+{
+ return [
'status' => ServerStatus::class,
];
+}
+```
Once you have defined the cast on your model, the specified attribute will be automatically cast to and from an enum when you interact with the attribute:
- if ($server->status == ServerStatus::provisioned) {
- $server->status = ServerStatus::ready;
+```php
+if ($server->status == ServerStatus::Provisioned) {
+ $server->status = ServerStatus::Ready;
- $server->save();
- }
+ $server->save();
+}
+```
+
+
+#### Casting Arrays of Enums
+
+Sometimes you may need your model to store an array of enum values within a single column. To accomplish this, you may utilize the `AsEnumArrayObject` or `AsEnumCollection` casts provided by Laravel:
+
+```php
+use App\Enums\ServerStatus;
+use Illuminate\Database\Eloquent\Casts\AsEnumCollection;
+
+/**
+ * Get the attributes that should be cast.
+ *
+ * @return array
+ */
+protected function casts(): array
+{
+ return [
+ 'statuses' => AsEnumCollection::of(ServerStatus::class),
+ ];
+}
+```
### Encrypted Casting
@@ -440,162 +636,207 @@ The `encrypted` cast will encrypt a model's attribute value using Laravel's buil
As the final length of the encrypted text is not predictable and is longer than its plain text counterpart, make sure the associated database column is of `TEXT` type or larger. In addition, since the values are encrypted in the database, you will not be able to query or search encrypted attribute values.
+
+#### Key Rotation
+
+As you may know, Laravel encrypts strings using the `key` configuration value specified in your application's `app` configuration file. Typically, this value corresponds to the value of the `APP_KEY` environment variable. If you need to rotate your application's encryption key, you will need to manually re-encrypt your encrypted attributes using the new key.
+
### Query Time Casting
Sometimes you may need to apply casts while executing a query, such as when selecting a raw value from a table. For example, consider the following query:
- use App\Models\Post;
- use App\Models\User;
-
- $users = User::select([
- 'users.*',
- 'last_posted_at' => Post::selectRaw('MAX(created_at)')
- ->whereColumn('user_id', 'users.id')
- ])->get();
+```php
+use App\Models\Post;
+use App\Models\User;
+
+$users = User::select([
+ 'users.*',
+ 'last_posted_at' => Post::selectRaw('MAX(created_at)')
+ ->whereColumn('user_id', 'users.id')
+])->get();
+```
The `last_posted_at` attribute on the results of this query will be a simple string. It would be wonderful if we could apply a `datetime` cast to this attribute when executing the query. Thankfully, we may accomplish this using the `withCasts` method:
- $users = User::select([
- 'users.*',
- 'last_posted_at' => Post::selectRaw('MAX(created_at)')
- ->whereColumn('user_id', 'users.id')
- ])->withCasts([
- 'last_posted_at' => 'datetime'
- ])->get();
+```php
+$users = User::select([
+ 'users.*',
+ 'last_posted_at' => Post::selectRaw('MAX(created_at)')
+ ->whereColumn('user_id', 'users.id')
+])->withCasts([
+ 'last_posted_at' => 'datetime'
+])->get();
+```
## Custom Casts
-Laravel has a variety of built-in, helpful cast types; however, you may occasionally need to define your own cast types. You may accomplish this by defining a class that implements the `CastsAttributes` interface.
+Laravel has a variety of built-in, helpful cast types; however, you may occasionally need to define your own cast types. To create a cast, execute the `make:cast` Artisan command. The new cast class will be placed in your `app/Casts` directory:
-Classes that implement this interface must define a `get` and `set` method. The `get` method is responsible for transforming a raw value from the database into a cast value, while the `set` method should transform a cast value into a raw value that can be stored in the database. As an example, we will re-implement the built-in `json` cast type as a custom cast type:
+```shell
+php artisan make:cast AsJson
+```
- $attributes
+ * @return array
+ */
+ public function get(
+ Model $model,
+ string $key,
+ mixed $value,
+ array $attributes,
+ ): array {
+ return json_decode($value, true);
}
+ /**
+ * Prepare the given value for storage.
+ *
+ * @param array $attributes
+ */
+ public function set(
+ Model $model,
+ string $key,
+ mixed $value,
+ array $attributes,
+ ): string {
+ return json_encode($value);
+ }
+}
+```
+
Once you have defined a custom cast type, you may attach it to a model attribute using its class name:
-
+ */
+ protected function casts(): array
{
- /**
- * The attributes that should be cast.
- *
- * @var array
- */
- protected $casts = [
- 'options' => Json::class,
+ return [
+ 'options' => AsJson::class,
];
}
+}
+```
### Value Object Casting
-You are not limited to casting values to primitive types. You may also cast values to objects. Defining custom casts that cast values to objects is very similar to casting to primitive types; however, the `set` method should return an array of key / value pairs that will be used to set raw, storable values on the model.
+You are not limited to casting values to primitive types. You may also cast values to objects. Defining custom casts that cast values to objects is very similar to casting to primitive types; however, if your value object encompasses more than one database column, the `set` method must return an array of key / value pairs that will be used to set raw, storable values on the model. If your value object only affects a single column, you should simply return the storable value.
-As an example, we will define a custom cast class that casts multiple model values into a single `Address` value object. We will assume the `Address` value has two public properties: `lineOne` and `lineTwo`:
+As an example, we will define a custom cast class that casts multiple model values into a single `Address` value object. We will assume the `Address` value object has two public properties: `lineOne` and `lineTwo`:
- $attributes
+ */
+ public function get(
+ Model $model,
+ string $key,
+ mixed $value,
+ array $attributes,
+ ): Address {
+ return new Address(
+ $attributes['address_line_one'],
+ $attributes['address_line_two']
+ );
+ }
- return [
- 'address_line_one' => $value->lineOne,
- 'address_line_two' => $value->lineTwo,
- ];
+ /**
+ * Prepare the given value for storage.
+ *
+ * @param array $attributes
+ * @return array
+ */
+ public function set(
+ Model $model,
+ string $key,
+ mixed $value,
+ array $attributes,
+ ): array {
+ if (! $value instanceof Address) {
+ throw new InvalidArgumentException('The given value is not an Address instance.');
}
+
+ return [
+ 'address_line_one' => $value->lineOne,
+ 'address_line_two' => $value->lineTwo,
+ ];
}
+}
+```
When casting to value objects, any changes made to the value object will automatically be synced back to the model before the model is saved:
- use App\Models\User;
+```php
+use App\Models\User;
+
+$user = User::find(1);
+
+$user->address->lineOne = 'Updated Address Value';
- $user = User::find(1);
+$user->save();
+```
+
+> [!NOTE]
+> If you plan to serialize your Eloquent models containing value objects to JSON or arrays, you should implement the `Illuminate\Contracts\Support\Arrayable` and `JsonSerializable` interfaces on the value object.
+
+
+#### Value Object Caching
- $user->address->lineOne = 'Updated Address Value';
+When attributes that are cast to value objects are resolved, they are cached by Eloquent. Therefore, the same object instance will be returned if the attribute is accessed again.
- $user->save();
+If you would like to disable the object caching behavior of custom cast classes, you may declare a public `withoutObjectCaching` property on your custom cast class:
-> {tip} If you plan to serialize your Eloquent models containing value objects to JSON or arrays, you should implement the `Illuminate\Contracts\Support\Arrayable` and `JsonSerializable` interfaces on the value object.
+```php
+class AsAddress implements CastsAttributes
+{
+ public bool $withoutObjectCaching = true;
+
+ // ...
+}
+```
### Array / JSON Serialization
@@ -604,165 +845,219 @@ When an Eloquent model is converted to an array or JSON using the `toArray` and
Therefore, you may specify that your custom cast class will be responsible for serializing the value object. To do so, your custom cast class should implement the `Illuminate\Contracts\Database\Eloquent\SerializesCastableAttributes` interface. This interface states that your class should contain a `serialize` method which should return the serialized form of your value object:
- /**
- * Get the serialized representation of the value.
- *
- * @param \Illuminate\Database\Eloquent\Model $model
- * @param string $key
- * @param mixed $value
- * @param array $attributes
- * @return mixed
- */
- public function serialize($model, string $key, $value, array $attributes)
- {
- return (string) $value;
- }
+```php
+/**
+ * Get the serialized representation of the value.
+ *
+ * @param array $attributes
+ */
+public function serialize(
+ Model $model,
+ string $key,
+ mixed $value,
+ array $attributes,
+): string {
+ return (string) $value;
+}
+```
### Inbound Casting
-Occasionally, you may need to write a custom cast that only transforms values that are being set on the model and does not perform any operations when attributes are being retrieved from the model. A classic example of an inbound only cast is a "hashing" cast. Inbound only custom casts should implement the `CastsInboundAttributes` interface, which only requires a `set` method to be defined.
+Occasionally, you may need to write a custom cast class that only transforms values that are being set on the model and does not perform any operations when attributes are being retrieved from the model.
- algorithm = $algorithm;
- }
+```php
+algorithm)
- ? bcrypt($value)
- : hash($this->algorithm, $value);
- }
+namespace App\Casts;
+
+use Illuminate\Contracts\Database\Eloquent\CastsInboundAttributes;
+use Illuminate\Database\Eloquent\Model;
+
+class AsHash implements CastsInboundAttributes
+{
+ /**
+ * Create a new cast class instance.
+ */
+ public function __construct(
+ protected string|null $algorithm = null,
+ ) {}
+
+ /**
+ * Prepare the given value for storage.
+ *
+ * @param array $attributes
+ */
+ public function set(
+ Model $model,
+ string $key,
+ mixed $value,
+ array $attributes,
+ ): string {
+ return is_null($this->algorithm)
+ ? bcrypt($value)
+ : hash($this->algorithm, $value);
}
+}
+```
### Cast Parameters
When attaching a custom cast to a model, cast parameters may be specified by separating them from the class name using a `:` character and comma-delimiting multiple parameters. The parameters will be passed to the constructor of the cast class:
- /**
- * The attributes that should be cast.
- *
- * @var array
- */
- protected $casts = [
- 'secret' => Hash::class.':sha256',
+```php
+/**
+ * Get the attributes that should be cast.
+ *
+ * @return array
+ */
+protected function casts(): array
+{
+ return [
+ 'secret' => AsHash::class.':sha256',
];
+}
+```
+
+
+### Comparing Cast Values
+
+If you would like to define how two given cast values should be compared to determine if they have been changed, your custom cast class may implement the `Illuminate\Contracts\Database\Eloquent\ComparesCastableAttributes` interface. This allows you to have fine-grained control over which values Eloquent considers changed and thus saves to the database when a model is updated.
+
+This interface states that your class should contain a `compare` method which should return `true` if the given values are considered equal:
+
+```php
+/**
+ * Determine if the given values are equal.
+ *
+ * @param \Illuminate\Database\Eloquent\Model $model
+ * @param string $key
+ * @param mixed $firstValue
+ * @param mixed $secondValue
+ * @return bool
+ */
+public function compare(
+ Model $model,
+ string $key,
+ mixed $firstValue,
+ mixed $secondValue
+): bool {
+ return $firstValue === $secondValue;
+}
+```
### Castables
You may want to allow your application's value objects to define their own custom cast classes. Instead of attaching the custom cast class to your model, you may alternatively attach a value object class that implements the `Illuminate\Contracts\Database\Eloquent\Castable` interface:
- use App\Models\Address;
+```php
+use App\ValueObjects\Address;
- protected $casts = [
+protected function casts(): array
+{
+ return [
'address' => Address::class,
];
+}
+```
Objects that implement the `Castable` interface must define a `castUsing` method that returns the class name of the custom caster class that is responsible for casting to and from the `Castable` class:
- $arguments
+ */
+ public static function castUsing(array $arguments): string
{
- /**
- * Get the name of the caster class to use when casting from / to this cast target.
- *
- * @param array $arguments
- * @return string
- */
- public static function castUsing(array $arguments)
- {
- return AddressCast::class;
- }
+ return AsAddress::class;
}
+}
+```
-When using `Castable` classes, you may still provide arguments in the `$casts` definition. The arguments will be passed to the `castUsing` method:
+When using `Castable` classes, you may still provide arguments in the `casts` method definition. The arguments will be passed to the `castUsing` method:
- use App\Models\Address;
+```php
+use App\ValueObjects\Address;
- protected $casts = [
+protected function casts(): array
+{
+ return [
'address' => Address::class.':argument',
];
+}
+```
#### Castables & Anonymous Cast Classes
By combining "castables" with PHP's [anonymous classes](https://www.php.net/manual/en/language.oop5.anonymous.php), you may define a value object and its casting logic as a single castable object. To accomplish this, return an anonymous class from your value object's `castUsing` method. The anonymous class should implement the `CastsAttributes` interface:
- $arguments
+ */
+ public static function castUsing(array $arguments): CastsAttributes
{
- // ...
-
- /**
- * Get the caster class to use when casting from / to this cast target.
- *
- * @param array $arguments
- * @return object|string
- */
- public static function castUsing(array $arguments)
+ return new class implements CastsAttributes
{
- return new class implements CastsAttributes
- {
- public function get($model, $key, $value, $attributes)
- {
- return new Address(
- $attributes['address_line_one'],
- $attributes['address_line_two']
- );
- }
-
- public function set($model, $key, $value, $attributes)
- {
- return [
- 'address_line_one' => $value->lineOne,
- 'address_line_two' => $value->lineTwo,
- ];
- }
- };
- }
+ public function get(
+ Model $model,
+ string $key,
+ mixed $value,
+ array $attributes,
+ ): Address {
+ return new Address(
+ $attributes['address_line_one'],
+ $attributes['address_line_two']
+ );
+ }
+
+ public function set(
+ Model $model,
+ string $key,
+ mixed $value,
+ array $attributes,
+ ): array {
+ return [
+ 'address_line_one' => $value->lineOne,
+ 'address_line_two' => $value->lineTwo,
+ ];
+ }
+ };
}
+}
+```
diff --git a/eloquent-relationships.md b/eloquent-relationships.md
index 4cf9c689ada..8bcbe480622 100644
--- a/eloquent-relationships.md
+++ b/eloquent-relationships.md
@@ -2,41 +2,44 @@
- [Introduction](#introduction)
- [Defining Relationships](#defining-relationships)
- - [One To One](#one-to-one)
- - [One To Many](#one-to-many)
- - [One To Many (Inverse) / Belongs To](#one-to-many-inverse)
- - [Has One Of Many](#has-one-of-many)
+ - [One to One / Has One](#one-to-one)
+ - [One to Many / Has Many](#one-to-many)
+ - [One to Many (Inverse) / Belongs To](#one-to-many-inverse)
+ - [Has One of Many](#has-one-of-many)
- [Has One Through](#has-one-through)
- [Has Many Through](#has-many-through)
-- [Many To Many Relationships](#many-to-many)
+- [Scoped Relationships](#scoped-relationships)
+- [Many to Many Relationships](#many-to-many)
- [Retrieving Intermediate Table Columns](#retrieving-intermediate-table-columns)
- - [Filtering Queries Via Intermediate Table Columns](#filtering-queries-via-intermediate-table-columns)
+ - [Filtering Queries via Intermediate Table Columns](#filtering-queries-via-intermediate-table-columns)
+ - [Ordering Queries via Intermediate Table Columns](#ordering-queries-via-intermediate-table-columns)
- [Defining Custom Intermediate Table Models](#defining-custom-intermediate-table-models)
- [Polymorphic Relationships](#polymorphic-relationships)
- - [One To One](#one-to-one-polymorphic-relations)
- - [One To Many](#one-to-many-polymorphic-relations)
- - [One Of Many](#one-of-many-polymorphic-relations)
- - [Many To Many](#many-to-many-polymorphic-relations)
+ - [One to One](#one-to-one-polymorphic-relations)
+ - [One to Many](#one-to-many-polymorphic-relations)
+ - [One of Many](#one-of-many-polymorphic-relations)
+ - [Many to Many](#many-to-many-polymorphic-relations)
- [Custom Polymorphic Types](#custom-polymorphic-types)
- [Dynamic Relationships](#dynamic-relationships)
- [Querying Relations](#querying-relations)
- - [Relationship Methods Vs. Dynamic Properties](#relationship-methods-vs-dynamic-properties)
+ - [Relationship Methods vs. Dynamic Properties](#relationship-methods-vs-dynamic-properties)
- [Querying Relationship Existence](#querying-relationship-existence)
- [Querying Relationship Absence](#querying-relationship-absence)
- [Querying Morph To Relationships](#querying-morph-to-relationships)
- [Aggregating Related Models](#aggregating-related-models)
- [Counting Related Models](#counting-related-models)
- [Other Aggregate Functions](#other-aggregate-functions)
- - [Counting Related Models On Morph To Relationships](#counting-related-models-on-morph-to-relationships)
+ - [Counting Related Models on Morph To Relationships](#counting-related-models-on-morph-to-relationships)
- [Eager Loading](#eager-loading)
- [Constraining Eager Loads](#constraining-eager-loads)
- [Lazy Eager Loading](#lazy-eager-loading)
+ - [Automatic Eager Loading](#automatic-eager-loading)
- [Preventing Lazy Loading](#preventing-lazy-loading)
-- [Inserting & Updating Related Models](#inserting-and-updating-related-models)
+- [Inserting and Updating Related Models](#inserting-and-updating-related-models)
- [The `save` Method](#the-save-method)
- [The `create` Method](#the-create-method)
- [Belongs To Relationships](#updating-belongs-to-relationships)
- - [Many To Many Relationships](#updating-many-to-many-relationships)
+ - [Many to Many Relationships](#updating-many-to-many-relationships)
- [Touching Parent Timestamps](#touching-parent-timestamps)
@@ -62,163 +65,244 @@ Database tables are often related to one another. For example, a blog post may h
Eloquent relationships are defined as methods on your Eloquent model classes. Since relationships also serve as powerful [query builders](/docs/{{version}}/queries), defining relationships as methods provides powerful method chaining and querying capabilities. For example, we may chain additional query constraints on this `posts` relationship:
- $user->posts()->where('active', 1)->get();
+```php
+$user->posts()->where('active', 1)->get();
+```
But, before diving too deep into using relationships, let's learn how to define each type of relationship supported by Eloquent.
-### One To One
+### One to One / Has One
A one-to-one relationship is a very basic type of database relationship. For example, a `User` model might be associated with one `Phone` model. To define this relationship, we will place a `phone` method on the `User` model. The `phone` method should call the `hasOne` method and return its result. The `hasOne` method is available to your model via the model's `Illuminate\Database\Eloquent\Model` base class:
- hasOne(Phone::class);
- }
+ return $this->hasOne(Phone::class);
}
+}
+```
The first argument passed to the `hasOne` method is the name of the related model class. Once the relationship is defined, we may retrieve the related record using Eloquent's dynamic properties. Dynamic properties allow you to access relationship methods as if they were properties defined on the model:
- $phone = User::find(1)->phone;
+```php
+$phone = User::find(1)->phone;
+```
Eloquent determines the foreign key of the relationship based on the parent model name. In this case, the `Phone` model is automatically assumed to have a `user_id` foreign key. If you wish to override this convention, you may pass a second argument to the `hasOne` method:
- return $this->hasOne(Phone::class, 'foreign_key');
+```php
+return $this->hasOne(Phone::class, 'foreign_key');
+```
Additionally, Eloquent assumes that the foreign key should have a value matching the primary key column of the parent. In other words, Eloquent will look for the value of the user's `id` column in the `user_id` column of the `Phone` record. If you would like the relationship to use a primary key value other than `id` or your model's `$primaryKey` property, you may pass a third argument to the `hasOne` method:
- return $this->hasOne(Phone::class, 'foreign_key', 'local_key');
+```php
+return $this->hasOne(Phone::class, 'foreign_key', 'local_key');
+```
-#### Defining The Inverse Of The Relationship
+#### Defining the Inverse of the Relationship
So, we can access the `Phone` model from our `User` model. Next, let's define a relationship on the `Phone` model that will let us access the user that owns the phone. We can define the inverse of a `hasOne` relationship using the `belongsTo` method:
- belongsTo(User::class);
- }
+ return $this->belongsTo(User::class);
}
+}
+```
When invoking the `user` method, Eloquent will attempt to find a `User` model that has an `id` which matches the `user_id` column on the `Phone` model.
Eloquent determines the foreign key name by examining the name of the relationship method and suffixing the method name with `_id`. So, in this case, Eloquent assumes that the `Phone` model has a `user_id` column. However, if the foreign key on the `Phone` model is not `user_id`, you may pass a custom key name as the second argument to the `belongsTo` method:
- /**
- * Get the user that owns the phone.
- */
- public function user()
- {
- return $this->belongsTo(User::class, 'foreign_key');
- }
+```php
+/**
+ * Get the user that owns the phone.
+ */
+public function user(): BelongsTo
+{
+ return $this->belongsTo(User::class, 'foreign_key');
+}
+```
If the parent model does not use `id` as its primary key, or you wish to find the associated model using a different column, you may pass a third argument to the `belongsTo` method specifying the parent table's custom key:
- /**
- * Get the user that owns the phone.
- */
- public function user()
- {
- return $this->belongsTo(User::class, 'foreign_key', 'owner_key');
- }
+```php
+/**
+ * Get the user that owns the phone.
+ */
+public function user(): BelongsTo
+{
+ return $this->belongsTo(User::class, 'foreign_key', 'owner_key');
+}
+```
-### One To Many
+### One to Many / Has Many
A one-to-many relationship is used to define relationships where a single model is the parent to one or more child models. For example, a blog post may have an infinite number of comments. Like all other Eloquent relationships, one-to-many relationships are defined by defining a method on your Eloquent model:
- hasMany(Comment::class);
- }
+ return $this->hasMany(Comment::class);
}
+}
+```
Remember, Eloquent will automatically determine the proper foreign key column for the `Comment` model. By convention, Eloquent will take the "snake case" name of the parent model and suffix it with `_id`. So, in this example, Eloquent will assume the foreign key column on the `Comment` model is `post_id`.
Once the relationship method has been defined, we can access the [collection](/docs/{{version}}/eloquent-collections) of related comments by accessing the `comments` property. Remember, since Eloquent provides "dynamic relationship properties", we can access relationship methods as if they were defined as properties on the model:
- use App\Models\Post;
+```php
+use App\Models\Post;
- $comments = Post::find(1)->comments;
+$comments = Post::find(1)->comments;
- foreach ($comments as $comment) {
- //
- }
+foreach ($comments as $comment) {
+ // ...
+}
+```
Since all relationships also serve as query builders, you may add further constraints to the relationship query by calling the `comments` method and continuing to chain conditions onto the query:
- $comment = Post::find(1)->comments()
- ->where('title', 'foo')
- ->first();
+```php
+$comment = Post::find(1)->comments()
+ ->where('title', 'foo')
+ ->first();
+```
Like the `hasOne` method, you may also override the foreign and local keys by passing additional arguments to the `hasMany` method:
- return $this->hasMany(Comment::class, 'foreign_key');
+```php
+return $this->hasMany(Comment::class, 'foreign_key');
- return $this->hasMany(Comment::class, 'foreign_key', 'local_key');
+return $this->hasMany(Comment::class, 'foreign_key', 'local_key');
+```
+
+
+#### Automatically Hydrating Parent Models on Children
+
+Even when utilizing Eloquent eager loading, "N + 1" query problems can arise if you try to access the parent model from a child model while looping through the child models:
+
+```php
+$posts = Post::with('comments')->get();
+
+foreach ($posts as $post) {
+ foreach ($post->comments as $comment) {
+ echo $comment->post->title;
+ }
+}
+```
+
+In the example above, an "N + 1" query problem has been introduced because, even though comments were eager loaded for every `Post` model, Eloquent does not automatically hydrate the parent `Post` on each child `Comment` model.
+
+If you would like Eloquent to automatically hydrate parent models onto their children, you may invoke the `chaperone` method when defining a `hasMany` relationship:
+
+```php
+hasMany(Comment::class)->chaperone();
+ }
+}
+```
+
+Or, if you would like to opt-in to automatic parent hydration at run time, you may invoke the `chaperone` model when eager loading the relationship:
+
+```php
+use App\Models\Post;
+
+$posts = Post::with([
+ 'comments' => fn ($comments) => $comments->chaperone(),
+])->get();
+```
-### One To Many (Inverse) / Belongs To
+### One to Many (Inverse) / Belongs To
Now that we can access all of a post's comments, let's define a relationship to allow a comment to access its parent post. To define the inverse of a `hasMany` relationship, define a relationship method on the child model which calls the `belongsTo` method:
- belongsTo(Post::class);
- }
+ return $this->belongsTo(Post::class);
}
+}
+```
Once the relationship has been defined, we can retrieve a comment's parent post by accessing the `post` "dynamic relationship property":
- use App\Models\Comment;
+```php
+use App\Models\Comment;
- $comment = Comment::find(1);
+$comment = Comment::find(1);
- return $comment->post->title;
+return $comment->post->title;
+```
In the example above, Eloquent will attempt to find a `Post` model that has an `id` which matches the `post_id` column on the `Comment` model.
@@ -226,78 +310,100 @@ Eloquent determines the default foreign key name by examining the name of the re
However, if the foreign key for your relationship does not follow these conventions, you may pass a custom foreign key name as the second argument to the `belongsTo` method:
- /**
- * Get the post that owns the comment.
- */
- public function post()
- {
- return $this->belongsTo(Post::class, 'foreign_key');
- }
+```php
+/**
+ * Get the post that owns the comment.
+ */
+public function post(): BelongsTo
+{
+ return $this->belongsTo(Post::class, 'foreign_key');
+}
+```
If your parent model does not use `id` as its primary key, or you wish to find the associated model using a different column, you may pass a third argument to the `belongsTo` method specifying your parent table's custom key:
- /**
- * Get the post that owns the comment.
- */
- public function post()
- {
- return $this->belongsTo(Post::class, 'foreign_key', 'owner_key');
- }
+```php
+/**
+ * Get the post that owns the comment.
+ */
+public function post(): BelongsTo
+{
+ return $this->belongsTo(Post::class, 'foreign_key', 'owner_key');
+}
+```
#### Default Models
The `belongsTo`, `hasOne`, `hasOneThrough`, and `morphOne` relationships allow you to define a default model that will be returned if the given relationship is `null`. This pattern is often referred to as the [Null Object pattern](https://en.wikipedia.org/wiki/Null_Object_pattern) and can help remove conditional checks in your code. In the following example, the `user` relation will return an empty `App\Models\User` model if no user is attached to the `Post` model:
- /**
- * Get the author of the post.
- */
- public function user()
- {
- return $this->belongsTo(User::class)->withDefault();
- }
+```php
+/**
+ * Get the author of the post.
+ */
+public function user(): BelongsTo
+{
+ return $this->belongsTo(User::class)->withDefault();
+}
+```
To populate the default model with attributes, you may pass an array or closure to the `withDefault` method:
- /**
- * Get the author of the post.
- */
- public function user()
- {
- return $this->belongsTo(User::class)->withDefault([
- 'name' => 'Guest Author',
- ]);
- }
+```php
+/**
+ * Get the author of the post.
+ */
+public function user(): BelongsTo
+{
+ return $this->belongsTo(User::class)->withDefault([
+ 'name' => 'Guest Author',
+ ]);
+}
- /**
- * Get the author of the post.
- */
- public function user()
- {
- return $this->belongsTo(User::class)->withDefault(function ($user, $post) {
- $user->name = 'Guest Author';
- });
- }
+/**
+ * Get the author of the post.
+ */
+public function user(): BelongsTo
+{
+ return $this->belongsTo(User::class)->withDefault(function (User $user, Post $post) {
+ $user->name = 'Guest Author';
+ });
+}
+```
#### Querying Belongs To Relationships
When querying for the children of a "belongs to" relationship, you may manually build the `where` clause to retrieve the corresponding Eloquent models:
- use App\Models\Post;
+```php
+use App\Models\Post;
- $posts = Post::where('user_id', $user->id)->get();
+$posts = Post::where('user_id', $user->id)->get();
+```
However, you may find it more convenient to use the `whereBelongsTo` method, which will automatically determine the proper relationship and foreign key for the given model:
- $posts = Post::whereBelongsTo($user)->get();
+```php
+$posts = Post::whereBelongsTo($user)->get();
+```
+
+You may also provide a [collection](/docs/{{version}}/eloquent-collections) instance to the `whereBelongsTo` method. When doing so, Laravel will retrieve models that belong to any of the parent models within the collection:
+
+```php
+$users = User::where('vip', true)->get();
+
+$posts = Post::whereBelongsTo($users)->get();
+```
By default, Laravel will determine the relationship associated with the given model based on the class name of the model; however, you may specify the relationship name manually by providing it as the second argument to the `whereBelongsTo` method:
- $posts = Post::whereBelongsTo($user, 'author')->get();
+```php
+$posts = Post::whereBelongsTo($user, 'author')->get();
+```
-### Has One Of Many
+### Has One of Many
Sometimes a model may have many related models, yet you want to easily retrieve the "latest" or "oldest" related model of the relationship. For example, a `User` model may be related to many `Order` models, but you want to define a convenient way to interact with the most recent order the user has placed. You may accomplish this using the `hasOne` relationship type combined with the `ofMany` methods:
@@ -305,7 +411,7 @@ Sometimes a model may have many related models, yet you want to easily retrieve
/**
* Get the user's most recent order.
*/
-public function latestOrder()
+public function latestOrder(): HasOne
{
return $this->hasOne(Order::class)->latestOfMany();
}
@@ -317,7 +423,7 @@ Likewise, you may define a method to retrieve the "oldest", or first, related mo
/**
* Get the user's oldest order.
*/
-public function oldestOrder()
+public function oldestOrder(): HasOne
{
return $this->hasOne(Order::class)->oldestOfMany();
}
@@ -331,18 +437,51 @@ For example, using the `ofMany` method, you may retrieve the user's most expensi
/**
* Get the user's largest order.
*/
-public function largestOrder()
+public function largestOrder(): HasOne
{
return $this->hasOne(Order::class)->ofMany('price', 'max');
}
```
-> {note} Because PostgreSQL does not support executing the `MAX` function against UUID columns, it is not currently possible to use one-of-many relationships in combination with PostgreSQL UUID columns.
+> [!WARNING]
+> Because PostgreSQL does not support executing the `MAX` function against UUID columns, it is not currently possible to use one-of-many relationships in combination with PostgreSQL UUID columns.
+
+
+#### Converting "Many" Relationships to Has One Relationships
+
+Often, when retrieving a single model using the `latestOfMany`, `oldestOfMany`, or `ofMany` methods, you already have a "has many" relationship defined for the same model. For convenience, Laravel allows you to easily convert this relationship into a "has one" relationship by invoking the `one` method on the relationship:
+
+```php
+/**
+ * Get the user's orders.
+ */
+public function orders(): HasMany
+{
+ return $this->hasMany(Order::class);
+}
+
+/**
+ * Get the user's largest order.
+ */
+public function largestOrder(): HasOne
+{
+ return $this->orders()->one()->ofMany('price', 'max');
+}
+```
+
+You may also use the `one` method to convert `HasManyThrough` relationships to `HasOneThrough` relationships:
+
+```php
+public function latestDeployment(): HasOneThrough
+{
+ return $this->deployments()->one()->latestOfMany();
+}
+```
-#### Advanced Has One Of Many Relationships
+#### Advanced Has One of Many Relationships
-It is possible to construct more advanced "has one of many" relationships. For example, A `Product` model may have many associated `Price` models that are retained in the system even after new pricing is published. In addition, new pricing data for the product may be able to be published in advance to take effect at a future date via a `published_at` column.
+It is possible to construct more advanced "has one of many" relationships. For example, a `Product` model may have many associated `Price` models that are retained in the system even after new pricing is published. In addition, new pricing data for the product may be able to be published in advance to take effect at a future date via a `published_at` column.
So, in summary, we need to retrieve the latest published pricing where the published date is not in the future. In addition, if two prices have the same published date, we will prefer the price with the greatest ID. To accomplish this, we must pass an array to the `ofMany` method that contains the sortable columns which determine the latest price. In addition, a closure will be provided as the second argument to the `ofMany` method. This closure will be responsible for adding additional publish date constraints to the relationship query:
@@ -350,12 +489,12 @@ So, in summary, we need to retrieve the latest published pricing where the publi
/**
* Get the current pricing for the product.
*/
-public function currentPricing()
+public function currentPricing(): HasOne
{
return $this->hasOne(Price::class)->ofMany([
'published_at' => 'max',
'id' => 'max',
- ], function ($query) {
+ ], function (Builder $query) {
$query->where('published_at', '<', now());
});
}
@@ -368,128 +507,241 @@ The "has-one-through" relationship defines a one-to-one relationship with anothe
For example, in a vehicle repair shop application, each `Mechanic` model may be associated with one `Car` model, and each `Car` model may be associated with one `Owner` model. While the mechanic and the owner have no direct relationship within the database, the mechanic can access the owner _through_ the `Car` model. Let's look at the tables necessary to define this relationship:
- mechanics
- id - integer
- name - string
+```text
+mechanics
+ id - integer
+ name - string
- cars
- id - integer
- model - string
- mechanic_id - integer
+cars
+ id - integer
+ model - string
+ mechanic_id - integer
- owners
- id - integer
- name - string
- car_id - integer
+owners
+ id - integer
+ name - string
+ car_id - integer
+```
Now that we have examined the table structure for the relationship, let's define the relationship on the `Mechanic` model:
- hasOneThrough(Owner::class, Car::class);
- }
+ return $this->hasOneThrough(Owner::class, Car::class);
}
+}
+```
The first argument passed to the `hasOneThrough` method is the name of the final model we wish to access, while the second argument is the name of the intermediate model.
+Or, if the relevant relationships have already been defined on all of the models involved in the relationship, you may fluently define a "has-one-through" relationship by invoking the `through` method and supplying the names of those relationships. For example, if the `Mechanic` model has a `cars` relationship and the `Car` model has an `owner` relationship, you may define a "has-one-through" relationship connecting the mechanic and the owner like so:
+
+```php
+// String based syntax...
+return $this->through('cars')->has('owner');
+
+// Dynamic syntax...
+return $this->throughCars()->hasOwner();
+```
+
#### Key Conventions
Typical Eloquent foreign key conventions will be used when performing the relationship's queries. If you would like to customize the keys of the relationship, you may pass them as the third and fourth arguments to the `hasOneThrough` method. The third argument is the name of the foreign key on the intermediate model. The fourth argument is the name of the foreign key on the final model. The fifth argument is the local key, while the sixth argument is the local key of the intermediate model:
- class Mechanic extends Model
+```php
+class Mechanic extends Model
+{
+ /**
+ * Get the car's owner.
+ */
+ public function carOwner(): HasOneThrough
{
- /**
- * Get the car's owner.
- */
- public function carOwner()
- {
- return $this->hasOneThrough(
- Owner::class,
- Car::class,
- 'mechanic_id', // Foreign key on the cars table...
- 'car_id', // Foreign key on the owners table...
- 'id', // Local key on the mechanics table...
- 'id' // Local key on the cars table...
- );
- }
+ return $this->hasOneThrough(
+ Owner::class,
+ Car::class,
+ 'mechanic_id', // Foreign key on the cars table...
+ 'car_id', // Foreign key on the owners table...
+ 'id', // Local key on the mechanics table...
+ 'id' // Local key on the cars table...
+ );
}
+}
+```
+
+Or, as discussed earlier, if the relevant relationships have already been defined on all of the models involved in the relationship, you may fluently define a "has-one-through" relationship by invoking the `through` method and supplying the names of those relationships. This approach offers the advantage of reusing the key conventions already defined on the existing relationships:
+
+```php
+// String based syntax...
+return $this->through('cars')->has('owner');
+
+// Dynamic syntax...
+return $this->throughCars()->hasOwner();
+```
### Has Many Through
-The "has-many-through" relationship provides a convenient way to access distant relations via an intermediate relation. For example, let's assume we are building a deployment platform like [Laravel Vapor](https://vapor.laravel.com). A `Project` model might access many `Deployment` models through an intermediate `Environment` model. Using this example, you could easily gather all deployments for a given project. Let's look at the tables required to define this relationship:
+The "has-many-through" relationship provides a convenient way to access distant relations via an intermediate relation. For example, let's assume we are building a deployment platform like [Laravel Cloud](https://cloud.laravel.com). An `Application` model might access many `Deployment` models through an intermediate `Environment` model. Using this example, you could easily gather all deployments for a given application. Let's look at the tables required to define this relationship:
- projects
- id - integer
- name - string
+```text
+applications
+ id - integer
+ name - string
- environments
- id - integer
- project_id - integer
- name - string
+environments
+ id - integer
+ application_id - integer
+ name - string
- deployments
- id - integer
- environment_id - integer
- commit_hash - string
+deployments
+ id - integer
+ environment_id - integer
+ commit_hash - string
+```
-Now that we have examined the table structure for the relationship, let's define the relationship on the `Project` model:
+Now that we have examined the table structure for the relationship, let's define the relationship on the `Application` model:
- hasManyThrough(Deployment::class, Environment::class);
- }
+ return $this->hasManyThrough(Deployment::class, Environment::class);
}
+}
+```
The first argument passed to the `hasManyThrough` method is the name of the final model we wish to access, while the second argument is the name of the intermediate model.
-Though the `Deployment` model's table does not contain a `project_id` column, the `hasManyThrough` relation provides access to a project's deployments via `$project->deployments`. To retrieve these models, Eloquent inspects the `project_id` column on the intermediate `Environment` model's table. After finding the relevant environment IDs, they are used to query the `Deployment` model's table.
+Or, if the relevant relationships have already been defined on all of the models involved in the relationship, you may fluently define a "has-many-through" relationship by invoking the `through` method and supplying the names of those relationships. For example, if the `Application` model has a `environments` relationship and the `Environment` model has a `deployments` relationship, you may define a "has-many-through" relationship connecting the application and the deployments like so:
+
+```php
+// String based syntax...
+return $this->through('environments')->has('deployments');
+
+// Dynamic syntax...
+return $this->throughEnvironments()->hasDeployments();
+```
+
+Though the `Deployment` model's table does not contain a `application_id` column, the `hasManyThrough` relation provides access to a application's deployments via `$application->deployments`. To retrieve these models, Eloquent inspects the `application_id` column on the intermediate `Environment` model's table. After finding the relevant environment IDs, they are used to query the `Deployment` model's table.
#### Key Conventions
Typical Eloquent foreign key conventions will be used when performing the relationship's queries. If you would like to customize the keys of the relationship, you may pass them as the third and fourth arguments to the `hasManyThrough` method. The third argument is the name of the foreign key on the intermediate model. The fourth argument is the name of the foreign key on the final model. The fifth argument is the local key, while the sixth argument is the local key of the intermediate model:
- class Project extends Model
+```php
+class Application extends Model
+{
+ public function deployments(): HasManyThrough
{
- public function deployments()
- {
- return $this->hasManyThrough(
- Deployment::class,
- Environment::class,
- 'project_id', // Foreign key on the environments table...
- 'environment_id', // Foreign key on the deployments table...
- 'id', // Local key on the projects table...
- 'id' // Local key on the environments table...
- );
- }
+ return $this->hasManyThrough(
+ Deployment::class,
+ Environment::class,
+ 'application_id', // Foreign key on the environments table...
+ 'environment_id', // Foreign key on the deployments table...
+ 'id', // Local key on the applications table...
+ 'id' // Local key on the environments table...
+ );
+ }
+}
+```
+
+Or, as discussed earlier, if the relevant relationships have already been defined on all of the models involved in the relationship, you may fluently define a "has-many-through" relationship by invoking the `through` method and supplying the names of those relationships. This approach offers the advantage of reusing the key conventions already defined on the existing relationships:
+
+```php
+// String based syntax...
+return $this->through('environments')->has('deployments');
+
+// Dynamic syntax...
+return $this->throughEnvironments()->hasDeployments();
+```
+
+
+### Scoped Relationships
+
+It's common to add additional methods to models that constrain relationships. For example, you might add a `featuredPosts` method to a `User` model which constrains the broader `posts` relationship with an additional `where` constraint:
+
+```php
+hasMany(Post::class)->latest();
+ }
+
+ /**
+ * Get the user's featured posts.
+ */
+ public function featuredPosts(): HasMany
+ {
+ return $this->posts()->where('featured', true);
}
+}
+```
+
+However, if you attempt to create a model via the `featuredPosts` method, its `featured` attribute would not be set to `true`. If you would like to create models via relationship methods and also specify attributes that should be added to all models created via that relationship, you may use the `withAttributes` method when building the relationship query:
+
+```php
+/**
+ * Get the user's featured posts.
+ */
+public function featuredPosts(): HasMany
+{
+ return $this->posts()->withAttributes(['featured' => true]);
+}
+```
+
+The `withAttributes` method will add `where` conditions to the query using the given attributes, and it will also add the given attributes to any models created via the relationship method:
+
+```php
+$post = $user->featuredPosts()->create(['title' => 'Featured Post']);
+
+$post->featured; // true
+```
+
+To instruct the `withAttributes` method to not add `where` conditions to the query, you may set the `asConditions` argument to `false`:
+
+```php
+return $this->posts()->withAttributes(['featured' => true], asConditions: false);
+```
-## Many To Many Relationships
+## Many to Many Relationships
Many-to-many relations are slightly more complicated than `hasOne` and `hasMany` relationships. An example of a many-to-many relationship is a user that has many roles and those roles are also shared by other users in the application. For example, a user may be assigned the role of "Author" and "Editor"; however, those roles may also be assigned to other users as well. So, a user has many roles and a role has many users.
@@ -500,83 +752,99 @@ To define this relationship, three database tables are needed: `users`, `roles`,
Remember, since a role can belong to many users, we cannot simply place a `user_id` column on the `roles` table. This would mean that a role could only belong to a single user. In order to provide support for roles being assigned to multiple users, the `role_user` table is needed. We can summarize the relationship's table structure like so:
- users
- id - integer
- name - string
+```text
+users
+ id - integer
+ name - string
- roles
- id - integer
- name - string
+roles
+ id - integer
+ name - string
- role_user
- user_id - integer
- role_id - integer
+role_user
+ user_id - integer
+ role_id - integer
+```
#### Model Structure
Many-to-many relationships are defined by writing a method that returns the result of the `belongsToMany` method. The `belongsToMany` method is provided by the `Illuminate\Database\Eloquent\Model` base class that is used by all of your application's Eloquent models. For example, let's define a `roles` method on our `User` model. The first argument passed to this method is the name of the related model class:
- belongsToMany(Role::class);
- }
+ return $this->belongsToMany(Role::class);
}
+}
+```
Once the relationship is defined, you may access the user's roles using the `roles` dynamic relationship property:
- use App\Models\User;
+```php
+use App\Models\User;
- $user = User::find(1);
+$user = User::find(1);
- foreach ($user->roles as $role) {
- //
- }
+foreach ($user->roles as $role) {
+ // ...
+}
+```
Since all relationships also serve as query builders, you may add further constraints to the relationship query by calling the `roles` method and continuing to chain conditions onto the query:
- $roles = User::find(1)->roles()->orderBy('name')->get();
+```php
+$roles = User::find(1)->roles()->orderBy('name')->get();
+```
To determine the table name of the relationship's intermediate table, Eloquent will join the two related model names in alphabetical order. However, you are free to override this convention. You may do so by passing a second argument to the `belongsToMany` method:
- return $this->belongsToMany(Role::class, 'role_user');
+```php
+return $this->belongsToMany(Role::class, 'role_user');
+```
In addition to customizing the name of the intermediate table, you may also customize the column names of the keys on the table by passing additional arguments to the `belongsToMany` method. The third argument is the foreign key name of the model on which you are defining the relationship, while the fourth argument is the foreign key name of the model that you are joining to:
- return $this->belongsToMany(Role::class, 'role_user', 'user_id', 'role_id');
+```php
+return $this->belongsToMany(Role::class, 'role_user', 'user_id', 'role_id');
+```
-#### Defining The Inverse Of The Relationship
+#### Defining the Inverse of the Relationship
To define the "inverse" of a many-to-many relationship, you should define a method on the related model which also returns the result of the `belongsToMany` method. To complete our user / role example, let's define the `users` method on the `Role` model:
- belongsToMany(User::class);
- }
+ return $this->belongsToMany(User::class);
}
+}
+```
As you can see, the relationship is defined exactly the same as its `User` model counterpart with the exception of referencing the `App\Models\User` model. Since we're reusing the `belongsToMany` method, all of the usual table and key customization options are available when defining the "inverse" of many-to-many relationships.
@@ -585,125 +853,164 @@ As you can see, the relationship is defined exactly the same as its `User` model
As you have already learned, working with many-to-many relations requires the presence of an intermediate table. Eloquent provides some very helpful ways of interacting with this table. For example, let's assume our `User` model has many `Role` models that it is related to. After accessing this relationship, we may access the intermediate table using the `pivot` attribute on the models:
- use App\Models\User;
+```php
+use App\Models\User;
- $user = User::find(1);
+$user = User::find(1);
- foreach ($user->roles as $role) {
- echo $role->pivot->created_at;
- }
+foreach ($user->roles as $role) {
+ echo $role->pivot->created_at;
+}
+```
Notice that each `Role` model we retrieve is automatically assigned a `pivot` attribute. This attribute contains a model representing the intermediate table.
By default, only the model keys will be present on the `pivot` model. If your intermediate table contains extra attributes, you must specify them when defining the relationship:
- return $this->belongsToMany(Role::class)->withPivot('active', 'created_by');
+```php
+return $this->belongsToMany(Role::class)->withPivot('active', 'created_by');
+```
If you would like your intermediate table to have `created_at` and `updated_at` timestamps that are automatically maintained by Eloquent, call the `withTimestamps` method when defining the relationship:
- return $this->belongsToMany(Role::class)->withTimestamps();
+```php
+return $this->belongsToMany(Role::class)->withTimestamps();
+```
-> {note} Intermediate tables that utilize Eloquent's automatically maintained timestamps are required to have both `created_at` and `updated_at` timestamp columns.
+> [!WARNING]
+> Intermediate tables that utilize Eloquent's automatically maintained timestamps are required to have both `created_at` and `updated_at` timestamp columns.
-#### Customizing The `pivot` Attribute Name
+#### Customizing the `pivot` Attribute Name
As noted previously, attributes from the intermediate table may be accessed on models via the `pivot` attribute. However, you are free to customize the name of this attribute to better reflect its purpose within your application.
For example, if your application contains users that may subscribe to podcasts, you likely have a many-to-many relationship between users and podcasts. If this is the case, you may wish to rename your intermediate table attribute to `subscription` instead of `pivot`. This can be done using the `as` method when defining the relationship:
- return $this->belongsToMany(Podcast::class)
- ->as('subscription')
- ->withTimestamps();
+```php
+return $this->belongsToMany(Podcast::class)
+ ->as('subscription')
+ ->withTimestamps();
+```
Once the custom intermediate table attribute has been specified, you may access the intermediate table data using the customized name:
- $users = User::with('podcasts')->get();
+```php
+$users = User::with('podcasts')->get();
- foreach ($users->flatMap->podcasts as $podcast) {
- echo $podcast->subscription->created_at;
- }
+foreach ($users->flatMap->podcasts as $podcast) {
+ echo $podcast->subscription->created_at;
+}
+```
-### Filtering Queries Via Intermediate Table Columns
+### Filtering Queries via Intermediate Table Columns
You can also filter the results returned by `belongsToMany` relationship queries using the `wherePivot`, `wherePivotIn`, `wherePivotNotIn`, `wherePivotBetween`, `wherePivotNotBetween`, `wherePivotNull`, and `wherePivotNotNull` methods when defining the relationship:
- return $this->belongsToMany(Role::class)
- ->wherePivot('approved', 1);
+```php
+return $this->belongsToMany(Role::class)
+ ->wherePivot('approved', 1);
+
+return $this->belongsToMany(Role::class)
+ ->wherePivotIn('priority', [1, 2]);
+
+return $this->belongsToMany(Role::class)
+ ->wherePivotNotIn('priority', [1, 2]);
+
+return $this->belongsToMany(Podcast::class)
+ ->as('subscriptions')
+ ->wherePivotBetween('created_at', ['2020-01-01 00:00:00', '2020-12-31 00:00:00']);
+
+return $this->belongsToMany(Podcast::class)
+ ->as('subscriptions')
+ ->wherePivotNotBetween('created_at', ['2020-01-01 00:00:00', '2020-12-31 00:00:00']);
+
+return $this->belongsToMany(Podcast::class)
+ ->as('subscriptions')
+ ->wherePivotNull('expired_at');
- return $this->belongsToMany(Role::class)
- ->wherePivotIn('priority', [1, 2]);
+return $this->belongsToMany(Podcast::class)
+ ->as('subscriptions')
+ ->wherePivotNotNull('expired_at');
+```
- return $this->belongsToMany(Role::class)
- ->wherePivotNotIn('priority', [1, 2]);
+The `wherePivot` adds a where clause constraint to the query, but does not add the specified value when creating new models via the defined relationship. If you need to both query and create relationships with a particular pivot value, you may use the `withPivotValue` method:
- return $this->belongsToMany(Podcast::class)
- ->as('subscriptions')
- ->wherePivotBetween('created_at', ['2020-01-01 00:00:00', '2020-12-31 00:00:00']);
+```php
+return $this->belongsToMany(Role::class)
+ ->withPivotValue('approved', 1);
+```
- return $this->belongsToMany(Podcast::class)
- ->as('subscriptions')
- ->wherePivotNotBetween('created_at', ['2020-01-01 00:00:00', '2020-12-31 00:00:00']);
+
+### Ordering Queries via Intermediate Table Columns
- return $this->belongsToMany(Podcast::class)
- ->as('subscriptions')
- ->wherePivotNull('expired_at');
+You can order the results returned by `belongsToMany` relationship queries using the `orderByPivot` method. In the following example, we will retrieve all of the latest badges for the user:
- return $this->belongsToMany(Podcast::class)
- ->as('subscriptions')
- ->wherePivotNotNull('expired_at');
+```php
+return $this->belongsToMany(Badge::class)
+ ->where('rank', 'gold')
+ ->orderByPivot('created_at', 'desc');
+```
### Defining Custom Intermediate Table Models
-If you would like to define a custom model to represent the intermediate table of your many-to-many relationship, you may call the `using` method when defining the relationship. Custom pivot models give you the opportunity to define additional methods on the pivot model.
+If you would like to define a custom model to represent the intermediate table of your many-to-many relationship, you may call the `using` method when defining the relationship. Custom pivot models give you the opportunity to define additional behavior on the pivot model, such as methods and casts.
Custom many-to-many pivot models should extend the `Illuminate\Database\Eloquent\Relations\Pivot` class while custom polymorphic many-to-many pivot models should extend the `Illuminate\Database\Eloquent\Relations\MorphPivot` class. For example, we may define a `Role` model which uses a custom `RoleUser` pivot model:
- belongsToMany(User::class)->using(RoleUser::class);
- }
+ return $this->belongsToMany(User::class)->using(RoleUser::class);
}
+}
+```
When defining the `RoleUser` model, you should extend the `Illuminate\Database\Eloquent\Relations\Pivot` class:
- {note} Pivot models may not use the `SoftDeletes` trait. If you need to soft delete pivot records consider converting your pivot model to an actual Eloquent model.
+> [!WARNING]
+> Pivot models may not use the `SoftDeletes` trait. If you need to soft delete pivot records consider converting your pivot model to an actual Eloquent model.
-#### Custom Pivot Models And Incrementing IDs
+#### Custom Pivot Models and Incrementing IDs
If you have defined a many-to-many relationship that uses a custom pivot model, and that pivot model has an auto-incrementing primary key, you should ensure your custom pivot model class defines an `incrementing` property that is set to `true`.
- /**
- * Indicates if the IDs are auto-incrementing.
- *
- * @var bool
- */
- public $incrementing = true;
+```php
+/**
+ * Indicates if the IDs are auto-incrementing.
+ *
+ * @var bool
+ */
+public $incrementing = true;
+```
## Polymorphic Relationships
@@ -711,26 +1018,28 @@ If you have defined a many-to-many relationship that uses a custom pivot model,
A polymorphic relationship allows the child model to belong to more than one type of model using a single association. For example, imagine you are building an application that allows users to share blog posts and videos. In such an application, a `Comment` model might belong to both the `Post` and `Video` models.
-### One To One (Polymorphic)
+### One to One (Polymorphic)
#### Table Structure
A one-to-one polymorphic relation is similar to a typical one-to-one relation; however, the child model can belong to more than one type of model using a single association. For example, a blog `Post` and a `User` may share a polymorphic relation to an `Image` model. Using a one-to-one polymorphic relation allows you to have a single table of unique images that may be associated with posts and users. First, let's examine the table structure:
- posts
- id - integer
- name - string
+```text
+posts
+ id - integer
+ name - string
- users
- id - integer
- name - string
+users
+ id - integer
+ name - string
- images
- id - integer
- url - string
- imageable_id - integer
- imageable_type - string
+images
+ id - integer
+ url - string
+ imageable_id - integer
+ imageable_type - string
+```
Note the `imageable_id` and `imageable_type` columns on the `images` table. The `imageable_id` column will contain the ID value of the post or user, while the `imageable_type` column will contain the class name of the parent model. The `imageable_type` column is used by Eloquent to determine which "type" of parent model to return when accessing the `imageable` relation. In this case, the column would contain either `App\Models\Post` or `App\Models\User`.
@@ -739,63 +1048,76 @@ Note the `imageable_id` and `imageable_type` columns on the `images` table. The
Next, let's examine the model definitions needed to build this relationship:
- morphTo();
- }
+ return $this->morphTo();
}
+}
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\MorphOne;
- class Post extends Model
+class Post extends Model
+{
+ /**
+ * Get the post's image.
+ */
+ public function image(): MorphOne
{
- /**
- * Get the post's image.
- */
- public function image()
- {
- return $this->morphOne(Image::class, 'imageable');
- }
+ return $this->morphOne(Image::class, 'imageable');
}
+}
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\MorphOne;
- class User extends Model
+class User extends Model
+{
+ /**
+ * Get the user's image.
+ */
+ public function image(): MorphOne
{
- /**
- * Get the user's image.
- */
- public function image()
- {
- return $this->morphOne(Image::class, 'imageable');
- }
+ return $this->morphOne(Image::class, 'imageable');
}
+}
+```
-#### Retrieving The Relationship
+#### Retrieving the Relationship
Once your database table and models are defined, you may access the relationships via your models. For example, to retrieve the image for a post, we can access the `image` dynamic relationship property:
- use App\Models\Post;
+```php
+use App\Models\Post;
- $post = Post::find(1);
+$post = Post::find(1);
- $image = $post->image;
+$image = $post->image;
+```
You may retrieve the parent of the polymorphic model by accessing the name of the method that performs the call to `morphTo`. In this case, that is the `imageable` method on the `Image` model. So, we will access that method as a dynamic relationship property:
- use App\Models\Image;
+```php
+use App\Models\Image;
- $image = Image::find(1);
+$image = Image::find(1);
- $imageable = $image->imageable;
+$imageable = $image->imageable;
+```
The `imageable` relation on the `Image` model will return either a `Post` or `User` instance, depending on which type of model owns the image.
@@ -804,107 +1126,166 @@ The `imageable` relation on the `Image` model will return either a `Post` or `Us
If necessary, you may specify the name of the "id" and "type" columns utilized by your polymorphic child model. If you do so, ensure that you always pass the name of the relationship as the first argument to the `morphTo` method. Typically, this value should match the method name, so you may use PHP's `__FUNCTION__` constant:
- /**
- * Get the model that the image belongs to.
- */
- public function imageable()
- {
- return $this->morphTo(__FUNCTION__, 'imageable_type', 'imageable_id');
- }
+```php
+/**
+ * Get the model that the image belongs to.
+ */
+public function imageable(): MorphTo
+{
+ return $this->morphTo(__FUNCTION__, 'imageable_type', 'imageable_id');
+}
+```
-### One To Many (Polymorphic)
+### One to Many (Polymorphic)
#### Table Structure
A one-to-many polymorphic relation is similar to a typical one-to-many relation; however, the child model can belong to more than one type of model using a single association. For example, imagine users of your application can "comment" on posts and videos. Using polymorphic relationships, you may use a single `comments` table to contain comments for both posts and videos. First, let's examine the table structure required to build this relationship:
- posts
- id - integer
- title - string
- body - text
-
- videos
- id - integer
- title - string
- url - string
-
- comments
- id - integer
- body - text
- commentable_id - integer
- commentable_type - string
+```text
+posts
+ id - integer
+ title - string
+ body - text
+
+videos
+ id - integer
+ title - string
+ url - string
+
+comments
+ id - integer
+ body - text
+ commentable_id - integer
+ commentable_type - string
+```
#### Model Structure
Next, let's examine the model definitions needed to build this relationship:
- morphTo();
- }
+ return $this->morphTo();
}
+}
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\MorphMany;
- class Post extends Model
+class Post extends Model
+{
+ /**
+ * Get all of the post's comments.
+ */
+ public function comments(): MorphMany
{
- /**
- * Get all of the post's comments.
- */
- public function comments()
- {
- return $this->morphMany(Comment::class, 'commentable');
- }
+ return $this->morphMany(Comment::class, 'commentable');
}
+}
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\MorphMany;
- class Video extends Model
+class Video extends Model
+{
+ /**
+ * Get all of the video's comments.
+ */
+ public function comments(): MorphMany
{
- /**
- * Get all of the video's comments.
- */
- public function comments()
- {
- return $this->morphMany(Comment::class, 'commentable');
- }
+ return $this->morphMany(Comment::class, 'commentable');
}
+}
+```
-#### Retrieving The Relationship
+#### Retrieving the Relationship
Once your database table and models are defined, you may access the relationships via your model's dynamic relationship properties. For example, to access all of the comments for a post, we can use the `comments` dynamic property:
- use App\Models\Post;
+```php
+use App\Models\Post;
- $post = Post::find(1);
+$post = Post::find(1);
- foreach ($post->comments as $comment) {
- //
- }
+foreach ($post->comments as $comment) {
+ // ...
+}
+```
You may also retrieve the parent of a polymorphic child model by accessing the name of the method that performs the call to `morphTo`. In this case, that is the `commentable` method on the `Comment` model. So, we will access that method as a dynamic relationship property in order to access the comment's parent model:
- use App\Models\Comment;
+```php
+use App\Models\Comment;
- $comment = Comment::find(1);
+$comment = Comment::find(1);
- $commentable = $comment->commentable;
+$commentable = $comment->commentable;
+```
The `commentable` relation on the `Comment` model will return either a `Post` or `Video` instance, depending on which type of model is the comment's parent.
+
+#### Automatically Hydrating Parent Models on Children
+
+Even when utilizing Eloquent eager loading, "N + 1" query problems can arise if you try to access the parent model from a child model while looping through the child models:
+
+```php
+$posts = Post::with('comments')->get();
+
+foreach ($posts as $post) {
+ foreach ($post->comments as $comment) {
+ echo $comment->commentable->title;
+ }
+}
+```
+
+In the example above, an "N + 1" query problem has been introduced because, even though comments were eager loaded for every `Post` model, Eloquent does not automatically hydrate the parent `Post` on each child `Comment` model.
+
+If you would like Eloquent to automatically hydrate parent models onto their children, you may invoke the `chaperone` method when defining a `morphMany` relationship:
+
+```php
+class Post extends Model
+{
+ /**
+ * Get all of the post's comments.
+ */
+ public function comments(): MorphMany
+ {
+ return $this->morphMany(Comment::class, 'commentable')->chaperone();
+ }
+}
+```
+
+Or, if you would like to opt-in to automatic parent hydration at run time, you may invoke the `chaperone` model when eager loading the relationship:
+
+```php
+use App\Models\Post;
+
+$posts = Post::with([
+ 'comments' => fn ($comments) => $comments->chaperone(),
+])->get();
+```
+
-### One Of Many (Polymorphic)
+### One of Many (Polymorphic)
Sometimes a model may have many related models, yet you want to easily retrieve the "latest" or "oldest" related model of the relationship. For example, a `User` model may be related to many `Image` models, but you want to define a convenient way to interact with the most recent image the user has uploaded. You may accomplish this using the `morphOne` relationship type combined with the `ofMany` methods:
@@ -912,7 +1293,7 @@ Sometimes a model may have many related models, yet you want to easily retrieve
/**
* Get the user's most recent image.
*/
-public function latestImage()
+public function latestImage(): MorphOne
{
return $this->morphOne(Image::class, 'imageable')->latestOfMany();
}
@@ -924,7 +1305,7 @@ Likewise, you may define a method to retrieve the "oldest", or first, related mo
/**
* Get the user's oldest image.
*/
-public function oldestImage()
+public function oldestImage(): MorphOne
{
return $this->morphOne(Image::class, 'imageable')->oldestOfMany();
}
@@ -938,40 +1319,44 @@ For example, using the `ofMany` method, you may retrieve the user's most "liked"
/**
* Get the user's most popular image.
*/
-public function bestImage()
+public function bestImage(): MorphOne
{
return $this->morphOne(Image::class, 'imageable')->ofMany('likes', 'max');
}
```
-> {tip} It is possible to construct more advanced "one of many" relationships. For more information, please consult the [has one of many documentation](#advanced-has-one-of-many-relationships).
+> [!NOTE]
+> It is possible to construct more advanced "one of many" relationships. For more information, please consult the [has one of many documentation](#advanced-has-one-of-many-relationships).
-### Many To Many (Polymorphic)
+### Many to Many (Polymorphic)
#### Table Structure
Many-to-many polymorphic relations are slightly more complicated than "morph one" and "morph many" relationships. For example, a `Post` model and `Video` model could share a polymorphic relation to a `Tag` model. Using a many-to-many polymorphic relation in this situation would allow your application to have a single table of unique tags that may be associated with posts or videos. First, let's examine the table structure required to build this relationship:
- posts
- id - integer
- name - string
+```text
+posts
+ id - integer
+ name - string
- videos
- id - integer
- name - string
+videos
+ id - integer
+ name - string
- tags
- id - integer
- name - string
+tags
+ id - integer
+ name - string
- taggables
- tag_id - integer
- taggable_id - integer
- taggable_type - string
+taggables
+ tag_id - integer
+ taggable_id - integer
+ taggable_type - string
+```
-> {tip} Before diving into polymorphic many-to-many relationships, you may benefit from reading the documentation on typical [many-to-many relationships](#many-to-many).
+> [!NOTE]
+> Before diving into polymorphic many-to-many relationships, you may benefit from reading the documentation on typical [many-to-many relationships](#many-to-many).
#### Model Structure
@@ -980,81 +1365,91 @@ Next, we're ready to define the relationships on the models. The `Post` and `Vid
The `morphToMany` method accepts the name of the related model as well as the "relationship name". Based on the name we assigned to our intermediate table name and the keys it contains, we will refer to the relationship as "taggable":
- morphToMany(Tag::class, 'taggable');
- }
+ return $this->morphToMany(Tag::class, 'taggable');
}
+}
+```
-#### Defining The Inverse Of The Relationship
+#### Defining the Inverse of the Relationship
Next, on the `Tag` model, you should define a method for each of its possible parent models. So, in this example, we will define a `posts` method and a `videos` method. Both of these methods should return the result of the `morphedByMany` method.
The `morphedByMany` method accepts the name of the related model as well as the "relationship name". Based on the name we assigned to our intermediate table name and the keys it contains, we will refer to the relationship as "taggable":
- morphedByMany(Post::class, 'taggable');
- }
+ return $this->morphedByMany(Post::class, 'taggable');
+ }
- /**
- * Get all of the videos that are assigned this tag.
- */
- public function videos()
- {
- return $this->morphedByMany(Video::class, 'taggable');
- }
+ /**
+ * Get all of the videos that are assigned this tag.
+ */
+ public function videos(): MorphToMany
+ {
+ return $this->morphedByMany(Video::class, 'taggable');
}
+}
+```
-#### Retrieving The Relationship
+#### Retrieving the Relationship
Once your database table and models are defined, you may access the relationships via your models. For example, to access all of the tags for a post, you may use the `tags` dynamic relationship property:
- use App\Models\Post;
+```php
+use App\Models\Post;
- $post = Post::find(1);
+$post = Post::find(1);
- foreach ($post->tags as $tag) {
- //
- }
+foreach ($post->tags as $tag) {
+ // ...
+}
+```
You may retrieve the parent of a polymorphic relation from the polymorphic child model by accessing the name of the method that performs the call to `morphedByMany`. In this case, that is the `posts` or `videos` methods on the `Tag` model:
- use App\Models\Tag;
+```php
+use App\Models\Tag;
- $tag = Tag::find(1);
+$tag = Tag::find(1);
- foreach ($tag->posts as $post) {
- //
- }
+foreach ($tag->posts as $post) {
+ // ...
+}
- foreach ($tag->videos as $video) {
- //
- }
+foreach ($tag->videos as $video) {
+ // ...
+}
+```
### Custom Polymorphic Types
@@ -1063,24 +1458,29 @@ By default, Laravel will use the fully qualified class name to store the "type"
For example, instead of using the model names as the "type", we may use simple strings such as `post` and `video`. By doing so, the polymorphic "type" column values in our database will remain valid even if the models are renamed:
- use Illuminate\Database\Eloquent\Relations\Relation;
+```php
+use Illuminate\Database\Eloquent\Relations\Relation;
- Relation::enforceMorphMap([
- 'post' => 'App\Models\Post',
- 'video' => 'App\Models\Video',
- ]);
+Relation::enforceMorphMap([
+ 'post' => 'App\Models\Post',
+ 'video' => 'App\Models\Video',
+]);
+```
You may call the `enforceMorphMap` method in the `boot` method of your `App\Providers\AppServiceProvider` class or create a separate service provider if you wish.
You may determine the morph alias of a given model at runtime using the model's `getMorphClass` method. Conversely, you may determine the fully-qualified class name associated with a morph alias using the `Relation::getMorphedModel` method:
- use Illuminate\Database\Eloquent\Relations\Relation;
+```php
+use Illuminate\Database\Eloquent\Relations\Relation;
- $alias = $post->getMorphClass();
+$alias = $post->getMorphClass();
- $class = Relation::getMorphedModel($alias);
+$class = Relation::getMorphedModel($alias);
+```
-> {note} When adding a "morph map" to your existing application, every morphable `*_type` column value in your database that still contains a fully-qualified class will need to be converted to its "map" name.
+> [!WARNING]
+> When adding a "morph map" to your existing application, every morphable `*_type` column value in your database that still contains a fully-qualified class will need to be converted to its "map" name.
### Dynamic Relationships
@@ -1089,14 +1489,17 @@ You may use the `resolveRelationUsing` method to define relations between Eloque
The `resolveRelationUsing` method accepts the desired relationship name as its first argument. The second argument passed to the method should be a closure that accepts the model instance and returns a valid Eloquent relationship definition. Typically, you should configure dynamic relationships within the boot method of a [service provider](/docs/{{version}}/providers):
- use App\Models\Order;
- use App\Models\Customer;
+```php
+use App\Models\Order;
+use App\Models\Customer;
- Order::resolveRelationUsing('customer', function ($orderModel) {
- return $orderModel->belongsTo(Customer::class, 'customer_id');
- });
+Order::resolveRelationUsing('customer', function (Order $orderModel) {
+ return $orderModel->belongsTo(Customer::class, 'customer_id');
+});
+```
-> {note} When defining dynamic relationships, always provide explicit key name arguments to the Eloquent relationship methods.
+> [!WARNING]
+> When defining dynamic relationships, always provide explicit key name arguments to the Eloquent relationship methods.
## Querying Relations
@@ -1105,30 +1508,35 @@ Since all Eloquent relationships are defined via methods, you may call those met
For example, imagine a blog application in which a `User` model has many associated `Post` models:
- hasMany(Post::class);
- }
+ return $this->hasMany(Post::class);
}
+}
+```
You may query the `posts` relationship and add additional constraints to the relationship like so:
- use App\Models\User;
+```php
+use App\Models\User;
- $user = User::find(1);
+$user = User::find(1);
- $user->posts()->where('active', 1)->get();
+$user->posts()->where('active', 1)->get();
+```
You are able to use any of the Laravel [query builder's](/docs/{{version}}/queries) methods on the relationship, so be sure to explore the query builder documentation to learn about all of the methods that are available to you.
@@ -1137,12 +1545,14 @@ You are able to use any of the Laravel [query builder's](/docs/{{version}}/queri
As demonstrated in the example above, you are free to add additional constraints to relationships when querying them. However, use caution when chaining `orWhere` clauses onto a relationship, as the `orWhere` clauses will be logically grouped at the same level as the relationship constraint:
- $user->posts()
- ->where('active', 1)
- ->orWhere('votes', '>=', 100)
- ->get();
+```php
+$user->posts()
+ ->where('active', 1)
+ ->orWhere('votes', '>=', 100)
+ ->get();
+```
-The example above will generate the following SQL. As you can see, the `or` clause instructs the query to return _any_ user with greater than 100 votes. The query is no longer constrained to a specific user:
+The example above will generate the following SQL. As you can see, the `or` clause instructs the query to return _any_ post with greater than 100 votes. The query is no longer constrained to a specific user:
```sql
select *
@@ -1152,14 +1562,16 @@ where user_id = ? and active = 1 or votes >= 100
In most situations, you should use [logical groups](/docs/{{version}}/queries#logical-grouping) to group the conditional checks between parentheses:
- use Illuminate\Database\Eloquent\Builder;
-
- $user->posts()
- ->where(function (Builder $query) {
- return $query->where('active', 1)
- ->orWhere('votes', '>=', 100);
- })
- ->get();
+```php
+use Illuminate\Database\Eloquent\Builder;
+
+$user->posts()
+ ->where(function (Builder $query) {
+ return $query->where('active', 1)
+ ->orWhere('votes', '>=', 100);
+ })
+ ->get();
+```
The example above will produce the following SQL. Note that the logical grouping has properly grouped the constraints and the query remains constrained to a specific user:
@@ -1170,17 +1582,19 @@ where user_id = ? and (active = 1 or votes >= 100)
```
-### Relationship Methods Vs. Dynamic Properties
+### Relationship Methods vs. Dynamic Properties
If you do not need to add additional constraints to an Eloquent relationship query, you may access the relationship as if it were a property. For example, continuing to use our `User` and `Post` example models, we may access all of a user's posts like so:
- use App\Models\User;
+```php
+use App\Models\User;
- $user = User::find(1);
+$user = User::find(1);
- foreach ($user->posts as $post) {
- //
- }
+foreach ($user->posts as $post) {
+ // ...
+}
+```
Dynamic relationship properties perform "lazy loading", meaning they will only load their relationship data when you actually access them. Because of this, developers often use [eager loading](#eager-loading) to pre-load relationships they know will be accessed after loading the model. Eager loading provides a significant reduction in SQL queries that must be executed to load a model's relations.
@@ -1189,129 +1603,179 @@ Dynamic relationship properties perform "lazy loading", meaning they will only l
When retrieving model records, you may wish to limit your results based on the existence of a relationship. For example, imagine you want to retrieve all blog posts that have at least one comment. To do so, you may pass the name of the relationship to the `has` and `orHas` methods:
- use App\Models\Post;
+```php
+use App\Models\Post;
- // Retrieve all posts that have at least one comment...
- $posts = Post::has('comments')->get();
+// Retrieve all posts that have at least one comment...
+$posts = Post::has('comments')->get();
+```
You may also specify an operator and count value to further customize the query:
- // Retrieve all posts that have three or more comments...
- $posts = Post::has('comments', '>=', 3)->get();
+```php
+// Retrieve all posts that have three or more comments...
+$posts = Post::has('comments', '>=', 3)->get();
+```
Nested `has` statements may be constructed using "dot" notation. For example, you may retrieve all posts that have at least one comment that has at least one image:
- // Retrieve posts that have at least one comment with images...
- $posts = Post::has('comments.images')->get();
+```php
+// Retrieve posts that have at least one comment with images...
+$posts = Post::has('comments.images')->get();
+```
If you need even more power, you may use the `whereHas` and `orWhereHas` methods to define additional query constraints on your `has` queries, such as inspecting the content of a comment:
- use Illuminate\Database\Eloquent\Builder;
+```php
+use Illuminate\Database\Eloquent\Builder;
+
+// Retrieve posts with at least one comment containing words like code%...
+$posts = Post::whereHas('comments', function (Builder $query) {
+ $query->where('content', 'like', 'code%');
+})->get();
+
+// Retrieve posts with at least ten comments containing words like code%...
+$posts = Post::whereHas('comments', function (Builder $query) {
+ $query->where('content', 'like', 'code%');
+}, '>=', 10)->get();
+```
+
+> [!WARNING]
+> Eloquent does not currently support querying for relationship existence across databases. The relationships must exist within the same database.
+
+
+#### Many to Many Relationship Existence Queries
+
+The `whereAttachedTo` method may be used to query for models that have a many to many attachment to a model or collection of models:
+
+```php
+$users = User::whereAttachedTo($role)->get();
+```
- // Retrieve posts with at least one comment containing words like code%...
- $posts = Post::whereHas('comments', function (Builder $query) {
- $query->where('content', 'like', 'code%');
- })->get();
+You may also provide a [collection](/docs/{{version}}/eloquent-collections) instance to the `whereAttachedTo` method. When doing so, Laravel will retrieve models that are attached to any of the models within the collection:
- // Retrieve posts with at least ten comments containing words like code%...
- $posts = Post::whereHas('comments', function (Builder $query) {
- $query->where('content', 'like', 'code%');
- }, '>=', 10)->get();
+```php
+$tags = Tag::whereLike('name', '%laravel%')->get();
-> {note} Eloquent does not currently support querying for relationship existence across databases. The relationships must exist within the same database.
+$posts = Post::whereAttachedTo($tags)->get();
+```
#### Inline Relationship Existence Queries
-If you would like to query for a relationship's existence with a single, simple where condition attached to the relationship query, you may find it more convenient to use the `whereRelation` and `whereMorphRelation` methods. For example, we may query for all posts that have unapproved comments:
+If you would like to query for a relationship's existence with a single, simple where condition attached to the relationship query, you may find it more convenient to use the `whereRelation`, `orWhereRelation`, `whereMorphRelation`, and `orWhereMorphRelation` methods. For example, we may query for all posts that have unapproved comments:
- use App\Models\Post;
+```php
+use App\Models\Post;
- $posts = Post::whereRelation('comments', 'is_approved', false)->get();
+$posts = Post::whereRelation('comments', 'is_approved', false)->get();
+```
Of course, like calls to the query builder's `where` method, you may also specify an operator:
- $posts = Post::whereRelation(
- 'comments', 'created_at', '>=', now()->subHour()
- )->get();
+```php
+$posts = Post::whereRelation(
+ 'comments', 'created_at', '>=', now()->subHour()
+)->get();
+```
### Querying Relationship Absence
When retrieving model records, you may wish to limit your results based on the absence of a relationship. For example, imagine you want to retrieve all blog posts that **don't** have any comments. To do so, you may pass the name of the relationship to the `doesntHave` and `orDoesntHave` methods:
- use App\Models\Post;
+```php
+use App\Models\Post;
- $posts = Post::doesntHave('comments')->get();
+$posts = Post::doesntHave('comments')->get();
+```
If you need even more power, you may use the `whereDoesntHave` and `orWhereDoesntHave` methods to add additional query constraints to your `doesntHave` queries, such as inspecting the content of a comment:
- use Illuminate\Database\Eloquent\Builder;
+```php
+use Illuminate\Database\Eloquent\Builder;
- $posts = Post::whereDoesntHave('comments', function (Builder $query) {
- $query->where('content', 'like', 'code%');
- })->get();
+$posts = Post::whereDoesntHave('comments', function (Builder $query) {
+ $query->where('content', 'like', 'code%');
+})->get();
+```
-You may use "dot" notation to execute a query against a nested relationship. For example, the following query will retrieve all posts that do not have comments; however, posts that have comments from authors that are not banned will be included in the results:
+You may use "dot" notation to execute a query against a nested relationship. For example, the following query will retrieve all posts that do not have comments as well as posts that have comments where none of the comments are from banned users:
- use Illuminate\Database\Eloquent\Builder;
+```php
+use Illuminate\Database\Eloquent\Builder;
- $posts = Post::whereDoesntHave('comments.author', function (Builder $query) {
- $query->where('banned', 0);
- })->get();
+$posts = Post::whereDoesntHave('comments.author', function (Builder $query) {
+ $query->where('banned', 1);
+})->get();
+```
### Querying Morph To Relationships
-To query the existence of "morph to" relationships, you may use the `whereHasMorph` and `whereDoesntHaveMorph` methods. These methods accept the name of the relationship as their first argument. Next, the methods accept the names of the related models that you wish to include in the query. Finally, you may provide a closure which customizes the relationship query:
+To query the existence of "morph to" relationships, you may use the `whereHasMorph` and `whereDoesntHaveMorph` methods. These methods accept the name of the relationship as their first argument. Next, the methods accept the names of the related models that you wish to include in the query. Finally, you may provide a closure which customizes the relationship query:
+
+```php
+use App\Models\Comment;
+use App\Models\Post;
+use App\Models\Video;
+use Illuminate\Database\Eloquent\Builder;
+
+// Retrieve comments associated to posts or videos with a title like code%...
+$comments = Comment::whereHasMorph(
+ 'commentable',
+ [Post::class, Video::class],
+ function (Builder $query) {
+ $query->where('title', 'like', 'code%');
+ }
+)->get();
+
+// Retrieve comments associated to posts with a title not like code%...
+$comments = Comment::whereDoesntHaveMorph(
+ 'commentable',
+ Post::class,
+ function (Builder $query) {
+ $query->where('title', 'like', 'code%');
+ }
+)->get();
+```
+
+You may occasionally need to add query constraints based on the "type" of the related polymorphic model. The closure passed to the `whereHasMorph` method may receive a `$type` value as its second argument. This argument allows you to inspect the "type" of the query that is being built:
- use App\Models\Comment;
- use App\Models\Post;
- use App\Models\Video;
- use Illuminate\Database\Eloquent\Builder;
-
- // Retrieve comments associated to posts or videos with a title like code%...
- $comments = Comment::whereHasMorph(
- 'commentable',
- [Post::class, Video::class],
- function (Builder $query) {
- $query->where('title', 'like', 'code%');
- }
- )->get();
-
- // Retrieve comments associated to posts with a title not like code%...
- $comments = Comment::whereDoesntHaveMorph(
- 'commentable',
- Post::class,
- function (Builder $query) {
- $query->where('title', 'like', 'code%');
- }
- )->get();
+```php
+use Illuminate\Database\Eloquent\Builder;
-You may occasionally need to add query constraints based on the "type" of the related polymorphic model. The closure passed to the `whereHasMorph` method may receive a `$type` value as its second argument. This argument allows you to inspect the "type" of the query that is being built:
+$comments = Comment::whereHasMorph(
+ 'commentable',
+ [Post::class, Video::class],
+ function (Builder $query, string $type) {
+ $column = $type === Post::class ? 'content' : 'title';
- use Illuminate\Database\Eloquent\Builder;
+ $query->where($column, 'like', 'code%');
+ }
+)->get();
+```
- $comments = Comment::whereHasMorph(
- 'commentable',
- [Post::class, Video::class],
- function (Builder $query, $type) {
- $column = $type === Post::class ? 'content' : 'title';
+Sometimes you may want to query for the children of a "morph to" relationship's parent. You may accomplish this using the `whereMorphedTo` and `whereNotMorphedTo` methods, which will automatically determine the proper morph type mapping for the given model. These methods accept the name of the `morphTo` relationship as their first argument and the related parent model as their second argument:
- $query->where($column, 'like', 'code%');
- }
- )->get();
+```php
+$comments = Comment::whereMorphedTo('commentable', $post)
+ ->orWhereMorphedTo('commentable', $video)
+ ->get();
+```
#### Querying All Related Models
Instead of passing an array of possible polymorphic models, you may provide `*` as a wildcard value. This will instruct Laravel to retrieve all of the possible polymorphic types from the database. Laravel will execute an additional query in order to perform this operation:
- use Illuminate\Database\Eloquent\Builder;
+```php
+use Illuminate\Database\Eloquent\Builder;
- $comments = Comment::whereHasMorph('commentable', '*', function (Builder $query) {
- $query->where('title', 'like', 'foo%');
- })->get();
+$comments = Comment::whereHasMorph('commentable', '*', function (Builder $query) {
+ $query->where('title', 'like', 'foo%');
+})->get();
+```
## Aggregating Related Models
@@ -1321,98 +1785,118 @@ Instead of passing an array of possible polymorphic models, you may provide `*`
Sometimes you may want to count the number of related models for a given relationship without actually loading the models. To accomplish this, you may use the `withCount` method. The `withCount` method will place a `{relation}_count` attribute on the resulting models:
- use App\Models\Post;
+```php
+use App\Models\Post;
- $posts = Post::withCount('comments')->get();
+$posts = Post::withCount('comments')->get();
- foreach ($posts as $post) {
- echo $post->comments_count;
- }
+foreach ($posts as $post) {
+ echo $post->comments_count;
+}
+```
By passing an array to the `withCount` method, you may add the "counts" for multiple relations as well as add additional constraints to the queries:
- use Illuminate\Database\Eloquent\Builder;
+```php
+use Illuminate\Database\Eloquent\Builder;
- $posts = Post::withCount(['votes', 'comments' => function (Builder $query) {
- $query->where('content', 'like', 'code%');
- }])->get();
+$posts = Post::withCount(['votes', 'comments' => function (Builder $query) {
+ $query->where('content', 'like', 'code%');
+}])->get();
- echo $posts[0]->votes_count;
- echo $posts[0]->comments_count;
+echo $posts[0]->votes_count;
+echo $posts[0]->comments_count;
+```
You may also alias the relationship count result, allowing multiple counts on the same relationship:
- use Illuminate\Database\Eloquent\Builder;
+```php
+use Illuminate\Database\Eloquent\Builder;
- $posts = Post::withCount([
- 'comments',
- 'comments as pending_comments_count' => function (Builder $query) {
- $query->where('approved', false);
- },
- ])->get();
+$posts = Post::withCount([
+ 'comments',
+ 'comments as pending_comments_count' => function (Builder $query) {
+ $query->where('approved', false);
+ },
+])->get();
- echo $posts[0]->comments_count;
- echo $posts[0]->pending_comments_count;
+echo $posts[0]->comments_count;
+echo $posts[0]->pending_comments_count;
+```
#### Deferred Count Loading
Using the `loadCount` method, you may load a relationship count after the parent model has already been retrieved:
- $book = Book::first();
+```php
+$book = Book::first();
- $book->loadCount('genres');
+$book->loadCount('genres');
+```
If you need to set additional query constraints on the count query, you may pass an array keyed by the relationships you wish to count. The array values should be closures which receive the query builder instance:
- $book->loadCount(['reviews' => function ($query) {
- $query->where('rating', 5);
- }])
+```php
+$book->loadCount(['reviews' => function (Builder $query) {
+ $query->where('rating', 5);
+}])
+```
-#### Relationship Counting & Custom Select Statements
+#### Relationship Counting and Custom Select Statements
If you're combining `withCount` with a `select` statement, ensure that you call `withCount` after the `select` method:
- $posts = Post::select(['title', 'body'])
- ->withCount('comments')
- ->get();
+```php
+$posts = Post::select(['title', 'body'])
+ ->withCount('comments')
+ ->get();
+```
### Other Aggregate Functions
In addition to the `withCount` method, Eloquent provides `withMin`, `withMax`, `withAvg`, `withSum`, and `withExists` methods. These methods will place a `{relation}_{function}_{column}` attribute on your resulting models:
- use App\Models\Post;
+```php
+use App\Models\Post;
- $posts = Post::withSum('comments', 'votes')->get();
+$posts = Post::withSum('comments', 'votes')->get();
- foreach ($posts as $post) {
- echo $post->comments_sum_votes;
- }
+foreach ($posts as $post) {
+ echo $post->comments_sum_votes;
+}
+```
If you wish to access the result of the aggregate function using another name, you may specify your own alias:
- $posts = Post::withSum('comments as total_comments', 'votes')->get();
+```php
+$posts = Post::withSum('comments as total_comments', 'votes')->get();
- foreach ($posts as $post) {
- echo $post->total_comments;
- }
+foreach ($posts as $post) {
+ echo $post->total_comments;
+}
+```
Like the `loadCount` method, deferred versions of these methods are also available. These additional aggregate operations may be performed on Eloquent models that have already been retrieved:
- $post = Post::first();
+```php
+$post = Post::first();
- $post->loadSum('comments', 'votes');
+$post->loadSum('comments', 'votes');
+```
If you're combining these aggregate methods with a `select` statement, ensure that you call the aggregate methods after the `select` method:
- $posts = Post::select(['title', 'body'])
- ->withExists('comments')
- ->get();
+```php
+$posts = Post::select(['title', 'body'])
+ ->withExists('comments')
+ ->get();
+```
-### Counting Related Models On Morph To Relationships
+### Counting Related Models on Morph To Relationships
If you would like to eager load a "morph to" relationship, as well as related model counts for the various entities that may be returned by that relationship, you may utilize the `with` method in combination with the `morphTo` relationship's `morphWithCount` method.
@@ -1420,69 +1904,80 @@ In this example, let's assume that `Photo` and `Post` models may create `Activit
Now, let's imagine we want to retrieve `ActivityFeed` instances and eager load the `parentable` parent models for each `ActivityFeed` instance. In addition, we want to retrieve the number of tags that are associated with each parent photo and the number of comments that are associated with each parent post:
- use Illuminate\Database\Eloquent\Relations\MorphTo;
+```php
+use Illuminate\Database\Eloquent\Relations\MorphTo;
- $activities = ActivityFeed::with([
- 'parentable' => function (MorphTo $morphTo) {
- $morphTo->morphWithCount([
- Photo::class => ['tags'],
- Post::class => ['comments'],
- ]);
- }])->get();
+$activities = ActivityFeed::with([
+ 'parentable' => function (MorphTo $morphTo) {
+ $morphTo->morphWithCount([
+ Photo::class => ['tags'],
+ Post::class => ['comments'],
+ ]);
+ }])->get();
+```
#### Deferred Count Loading
Let's assume we have already retrieved a set of `ActivityFeed` models and now we would like to load the nested relationship counts for the various `parentable` models associated with the activity feeds. You may use the `loadMorphCount` method to accomplish this:
- $activities = ActivityFeed::with('parentable')->get();
+```php
+$activities = ActivityFeed::with('parentable')->get();
- $activities->loadMorphCount('parentable', [
- Photo::class => ['tags'],
- Post::class => ['comments'],
- ]);
+$activities->loadMorphCount('parentable', [
+ Photo::class => ['tags'],
+ Post::class => ['comments'],
+]);
+```
## Eager Loading
When accessing Eloquent relationships as properties, the related models are "lazy loaded". This means the relationship data is not actually loaded until you first access the property. However, Eloquent can "eager load" relationships at the time you query the parent model. Eager loading alleviates the "N + 1" query problem. To illustrate the N + 1 query problem, consider a `Book` model that "belongs to" to an `Author` model:
- belongsTo(Author::class);
- }
+ return $this->belongsTo(Author::class);
}
+}
+```
Now, let's retrieve all books and their authors:
- use App\Models\Book;
+```php
+use App\Models\Book;
- $books = Book::all();
+$books = Book::all();
- foreach ($books as $book) {
- echo $book->author->name;
- }
+foreach ($books as $book) {
+ echo $book->author->name;
+}
+```
This loop will execute one query to retrieve all of the books within the database table, then another query for each book in order to retrieve the book's author. So, if we have 25 books, the code above would run 26 queries: one for the original book, and 25 additional queries to retrieve the author of each book.
Thankfully, we can use eager loading to reduce this operation to just two queries. When building a query, you may specify which relationships should be eager loaded using the `with` method:
- $books = Book::with('author')->get();
+```php
+$books = Book::with('author')->get();
- foreach ($books as $book) {
- echo $book->author->name;
- }
+foreach ($books as $book) {
+ echo $book->author->name;
+}
+```
For this operation, only two queries will be executed - one query to retrieve all of the books and one query to retrieve all of the authors for all of the books:
@@ -1497,200 +1992,304 @@ select * from authors where id in (1, 2, 3, 4, 5, ...)
Sometimes you may need to eager load several different relationships. To do so, just pass an array of relationships to the `with` method:
- $books = Book::with(['author', 'publisher'])->get();
+```php
+$books = Book::with(['author', 'publisher'])->get();
+```
#### Nested Eager Loading
To eager load a relationship's relationships, you may use "dot" syntax. For example, let's eager load all of the book's authors and all of the author's personal contacts:
- $books = Book::with('author.contacts')->get();
+```php
+$books = Book::with('author.contacts')->get();
+```
+
+Alternatively, you may specify nested eager loaded relationships by providing a nested array to the `with` method, which can be convenient when eager loading multiple nested relationships:
+
+```php
+$books = Book::with([
+ 'author' => [
+ 'contacts',
+ 'publisher',
+ ],
+])->get();
+```
#### Nested Eager Loading `morphTo` Relationships
If you would like to eager load a `morphTo` relationship, as well as nested relationships on the various entities that may be returned by that relationship, you may use the `with` method in combination with the `morphTo` relationship's `morphWith` method. To help illustrate this method, let's consider the following model:
- morphTo();
- }
+ return $this->morphTo();
}
+}
+```
In this example, let's assume `Event`, `Photo`, and `Post` models may create `ActivityFeed` models. Additionally, let's assume that `Event` models belong to a `Calendar` model, `Photo` models are associated with `Tag` models, and `Post` models belong to an `Author` model.
Using these model definitions and relationships, we may retrieve `ActivityFeed` model instances and eager load all `parentable` models and their respective nested relationships:
- use Illuminate\Database\Eloquent\Relations\MorphTo;
+```php
+use Illuminate\Database\Eloquent\Relations\MorphTo;
- $activities = ActivityFeed::query()
- ->with(['parentable' => function (MorphTo $morphTo) {
- $morphTo->morphWith([
- Event::class => ['calendar'],
- Photo::class => ['tags'],
- Post::class => ['author'],
- ]);
- }])->get();
+$activities = ActivityFeed::query()
+ ->with(['parentable' => function (MorphTo $morphTo) {
+ $morphTo->morphWith([
+ Event::class => ['calendar'],
+ Photo::class => ['tags'],
+ Post::class => ['author'],
+ ]);
+ }])->get();
+```
#### Eager Loading Specific Columns
You may not always need every column from the relationships you are retrieving. For this reason, Eloquent allows you to specify which columns of the relationship you would like to retrieve:
- $books = Book::with('author:id,name,book_id')->get();
+```php
+$books = Book::with('author:id,name,book_id')->get();
+```
-> {note} When using this feature, you should always include the `id` column and any relevant foreign key columns in the list of columns you wish to retrieve.
+> [!WARNING]
+> When using this feature, you should always include the `id` column and any relevant foreign key columns in the list of columns you wish to retrieve.
-#### Eager Loading By Default
+#### Eager Loading by Default
Sometimes you might want to always load some relationships when retrieving a model. To accomplish this, you may define a `$with` property on the model:
- belongsTo(Author::class);
- }
+ return $this->belongsTo(Author::class);
+ }
- /**
- * Get the genre of the book.
- */
- public function genre()
- {
- return $this->belongsTo(Genre::class);
- }
+ /**
+ * Get the genre of the book.
+ */
+ public function genre(): BelongsTo
+ {
+ return $this->belongsTo(Genre::class);
}
+}
+```
If you would like to remove an item from the `$with` property for a single query, you may use the `without` method:
- $books = Book::without('author')->get();
+```php
+$books = Book::without('author')->get();
+```
If you would like to override all items within the `$with` property for a single query, you may use the `withOnly` method:
- $books = Book::withOnly('genre')->get();
+```php
+$books = Book::withOnly('genre')->get();
+```
### Constraining Eager Loads
Sometimes you may wish to eager load a relationship but also specify additional query conditions for the eager loading query. You can accomplish this by passing an array of relationships to the `with` method where the array key is a relationship name and the array value is a closure that adds additional constraints to the eager loading query:
- use App\Models\User;
+```php
+use App\Models\User;
+use Illuminate\Database\Eloquent\Builder;
- $users = User::with(['posts' => function ($query) {
- $query->where('title', 'like', '%code%');
- }])->get();
+$users = User::with(['posts' => function (Builder $query) {
+ $query->where('title', 'like', '%code%');
+}])->get();
+```
In this example, Eloquent will only eager load posts where the post's `title` column contains the word `code`. You may call other [query builder](/docs/{{version}}/queries) methods to further customize the eager loading operation:
- $users = User::with(['posts' => function ($query) {
- $query->orderBy('created_at', 'desc');
- }])->get();
-
-> {note} The `limit` and `take` query builder methods may not be used when constraining eager loads.
+```php
+$users = User::with(['posts' => function (Builder $query) {
+ $query->orderBy('created_at', 'desc');
+}])->get();
+```
-#### Constraining Eager Loading Of `morphTo` Relationships
+#### Constraining Eager Loading of `morphTo` Relationships
If you are eager loading a `morphTo` relationship, Eloquent will run multiple queries to fetch each type of related model. You may add additional constraints to each of these queries using the `MorphTo` relation's `constrain` method:
- use Illuminate\Database\Eloquent\Builder;
- use Illuminate\Database\Eloquent\Relations\MorphTo;
-
- $comments = Comment::with(['commentable' => function (MorphTo $morphTo) {
- $morphTo->constrain([
- Post::class => function (Builder $query) {
- $query->whereNull('hidden_at');
- },
- Video::class => function (Builder $query) {
- $query->where('type', 'educational');
- },
- ]);
- }])->get();
+```php
+use Illuminate\Database\Eloquent\Relations\MorphTo;
+
+$comments = Comment::with(['commentable' => function (MorphTo $morphTo) {
+ $morphTo->constrain([
+ Post::class => function ($query) {
+ $query->whereNull('hidden_at');
+ },
+ Video::class => function ($query) {
+ $query->where('type', 'educational');
+ },
+ ]);
+}])->get();
+```
-In this example, Eloquent will only eager load posts that have not been hidden and videos have a `type` value of "educational".
+In this example, Eloquent will only eager load posts that have not been hidden and videos that have a `type` value of "educational".
+
+
+#### Constraining Eager Loads With Relationship Existence
+
+You may sometimes find yourself needing to check for the existence of a relationship while simultaneously loading the relationship based on the same conditions. For example, you may wish to only retrieve `User` models that have child `Post` models matching a given query condition while also eager loading the matching posts. You may accomplish this using the `withWhereHas` method:
+
+```php
+use App\Models\User;
+
+$users = User::withWhereHas('posts', function ($query) {
+ $query->where('featured', true);
+})->get();
+```
### Lazy Eager Loading
Sometimes you may need to eager load a relationship after the parent model has already been retrieved. For example, this may be useful if you need to dynamically decide whether to load related models:
- use App\Models\Book;
+```php
+use App\Models\Book;
- $books = Book::all();
+$books = Book::all();
- if ($someCondition) {
- $books->load('author', 'publisher');
- }
+if ($condition) {
+ $books->load('author', 'publisher');
+}
+```
If you need to set additional query constraints on the eager loading query, you may pass an array keyed by the relationships you wish to load. The array values should be closure instances which receive the query instance:
- $author->load(['books' => function ($query) {
- $query->orderBy('published_date', 'asc');
- }]);
+```php
+$author->load(['books' => function (Builder $query) {
+ $query->orderBy('published_date', 'asc');
+}]);
+```
To load a relationship only when it has not already been loaded, use the `loadMissing` method:
- $book->loadMissing('author');
+```php
+$book->loadMissing('author');
+```
-#### Nested Lazy Eager Loading & `morphTo`
+#### Nested Lazy Eager Loading and `morphTo`
If you would like to eager load a `morphTo` relationship, as well as nested relationships on the various entities that may be returned by that relationship, you may use the `loadMorph` method.
This method accepts the name of the `morphTo` relationship as its first argument, and an array of model / relationship pairs as its second argument. To help illustrate this method, let's consider the following model:
- morphTo();
- }
+ return $this->morphTo();
}
+}
+```
In this example, let's assume `Event`, `Photo`, and `Post` models may create `ActivityFeed` models. Additionally, let's assume that `Event` models belong to a `Calendar` model, `Photo` models are associated with `Tag` models, and `Post` models belong to an `Author` model.
Using these model definitions and relationships, we may retrieve `ActivityFeed` model instances and eager load all `parentable` models and their respective nested relationships:
- $activities = ActivityFeed::with('parentable')
- ->get()
- ->loadMorph('parentable', [
- Event::class => ['calendar'],
- Photo::class => ['tags'],
- Post::class => ['author'],
- ]);
+```php
+$activities = ActivityFeed::with('parentable')
+ ->get()
+ ->loadMorph('parentable', [
+ Event::class => ['calendar'],
+ Photo::class => ['tags'],
+ Post::class => ['author'],
+ ]);
+```
+
+
+### Automatic Eager Loading
+
+> [!WARNING]
+> This feature is currently in beta in order to gather community feedback. The behavior and functionality of this feature may change even on patch releases.
+
+In many cases, Laravel can automatically eager load the relationships you access. To enable automatic eager loading, you should invoke the `Model::automaticallyEagerLoadRelationships` method within the `boot` method of your application's `AppServiceProvider`:
+
+```php
+use Illuminate\Database\Eloquent\Model;
+
+/**
+ * Bootstrap any application services.
+ */
+public function boot(): void
+{
+ Model::automaticallyEagerLoadRelationships();
+}
+```
+
+When this feature is enabled, Laravel will attempt to automatically load any relationships you access that have not been previously loaded. For example, consider the following scenario:
+
+```php
+use App\Models\User;
+
+$users = User::all();
+
+foreach ($users as $user) {
+ foreach ($user->posts as $post) {
+ foreach ($post->comments as $comment) {
+ echo $comment->content;
+ }
+ }
+}
+```
+
+Typically, the code above would execute a query for each user in order to retrieve their posts, as well as a query for each post to retrieve its comments. However, when the `automaticallyEagerLoadRelationships` feature has been enabled, Laravel will automatically [lazy eager load](#lazy-eager-loading) the posts for all users in the user collection when you attempt to access the posts on any of the retrieved users. Likewise, when you attempt to access the comments for any retrieved post, all comments will be lazy eager loaded for all posts that were originally retrieved.
+
+If you do not want to globally enable automatic eager loading, you can still enable this feature for a single Eloquent collection instance by invoking the `withRelationshipAutoloading` method on the collection:
+
+```php
+$users = User::where('vip', true)->get();
+
+return $users->withRelationshipAutoloading();
+```
### Preventing Lazy Loading
@@ -1704,10 +2303,8 @@ use Illuminate\Database\Eloquent\Model;
/**
* Bootstrap any application services.
- *
- * @return void
*/
-public function boot()
+public function boot(): void
{
Model::preventLazyLoading(! $this->app->isProduction());
}
@@ -1718,180 +2315,247 @@ After preventing lazy loading, Eloquent will throw a `Illuminate\Database\LazyLo
You may customize the behavior of lazy loading violations using the `handleLazyLoadingViolationsUsing` method. For example, using this method, you may instruct lazy loading violations to only be logged instead of interrupting the application's execution with exceptions:
```php
-Model::handleLazyLoadingViolationUsing(function ($model, $relation) {
- $class = get_class($model);
+Model::handleLazyLoadingViolationUsing(function (Model $model, string $relation) {
+ $class = $model::class;
info("Attempted to lazy load [{$relation}] on model [{$class}].");
});
```
-## Inserting & Updating Related Models
+## Inserting and Updating Related Models
### The `save` Method
Eloquent provides convenient methods for adding new models to relationships. For example, perhaps you need to add a new comment to a post. Instead of manually setting the `post_id` attribute on the `Comment` model you may insert the comment using the relationship's `save` method:
- use App\Models\Comment;
- use App\Models\Post;
+```php
+use App\Models\Comment;
+use App\Models\Post;
- $comment = new Comment(['message' => 'A new comment.']);
+$comment = new Comment(['message' => 'A new comment.']);
- $post = Post::find(1);
+$post = Post::find(1);
- $post->comments()->save($comment);
+$post->comments()->save($comment);
+```
Note that we did not access the `comments` relationship as a dynamic property. Instead, we called the `comments` method to obtain an instance of the relationship. The `save` method will automatically add the appropriate `post_id` value to the new `Comment` model.
If you need to save multiple related models, you may use the `saveMany` method:
- $post = Post::find(1);
+```php
+$post = Post::find(1);
- $post->comments()->saveMany([
- new Comment(['message' => 'A new comment.']),
- new Comment(['message' => 'Another new comment.']),
- ]);
+$post->comments()->saveMany([
+ new Comment(['message' => 'A new comment.']),
+ new Comment(['message' => 'Another new comment.']),
+]);
+```
The `save` and `saveMany` methods will persist the given model instances, but will not add the newly persisted models to any in-memory relationships that are already loaded onto the parent model. If you plan on accessing the relationship after using the `save` or `saveMany` methods, you may wish to use the `refresh` method to reload the model and its relationships:
- $post->comments()->save($comment);
+```php
+$post->comments()->save($comment);
- $post->refresh();
+$post->refresh();
- // All comments, including the newly saved comment...
- $post->comments;
+// All comments, including the newly saved comment...
+$post->comments;
+```
-#### Recursively Saving Models & Relationships
+#### Recursively Saving Models and Relationships
If you would like to `save` your model and all of its associated relationships, you may use the `push` method. In this example, the `Post` model will be saved as well as its comments and the comment's authors:
- $post = Post::find(1);
+```php
+$post = Post::find(1);
+
+$post->comments[0]->message = 'Message';
+$post->comments[0]->author->name = 'Author Name';
+
+$post->push();
+```
- $post->comments[0]->message = 'Message';
- $post->comments[0]->author->name = 'Author Name';
+The `pushQuietly` method may be used to save a model and its associated relationships without raising any events:
- $post->push();
+```php
+$post->pushQuietly();
+```
### The `create` Method
In addition to the `save` and `saveMany` methods, you may also use the `create` method, which accepts an array of attributes, creates a model, and inserts it into the database. The difference between `save` and `create` is that `save` accepts a full Eloquent model instance while `create` accepts a plain PHP `array`. The newly created model will be returned by the `create` method:
- use App\Models\Post;
+```php
+use App\Models\Post;
- $post = Post::find(1);
+$post = Post::find(1);
- $comment = $post->comments()->create([
- 'message' => 'A new comment.',
- ]);
+$comment = $post->comments()->create([
+ 'message' => 'A new comment.',
+]);
+```
You may use the `createMany` method to create multiple related models:
- $post = Post::find(1);
+```php
+$post = Post::find(1);
- $post->comments()->createMany([
- ['message' => 'A new comment.'],
- ['message' => 'Another new comment.'],
- ]);
+$post->comments()->createMany([
+ ['message' => 'A new comment.'],
+ ['message' => 'Another new comment.'],
+]);
+```
+
+The `createQuietly` and `createManyQuietly` methods may be used to create a model(s) without dispatching any events:
+
+```php
+$user = User::find(1);
+
+$user->posts()->createQuietly([
+ 'title' => 'Post title.',
+]);
+
+$user->posts()->createManyQuietly([
+ ['title' => 'First post.'],
+ ['title' => 'Second post.'],
+]);
+```
You may also use the `findOrNew`, `firstOrNew`, `firstOrCreate`, and `updateOrCreate` methods to [create and update models on relationships](/docs/{{version}}/eloquent#upserts).
-> {tip} Before using the `create` method, be sure to review the [mass assignment](/docs/{{version}}/eloquent#mass-assignment) documentation.
+> [!NOTE]
+> Before using the `create` method, be sure to review the [mass assignment](/docs/{{version}}/eloquent#mass-assignment) documentation.
### Belongs To Relationships
If you would like to assign a child model to a new parent model, you may use the `associate` method. In this example, the `User` model defines a `belongsTo` relationship to the `Account` model. This `associate` method will set the foreign key on the child model:
- use App\Models\Account;
+```php
+use App\Models\Account;
- $account = Account::find(10);
+$account = Account::find(10);
- $user->account()->associate($account);
+$user->account()->associate($account);
- $user->save();
+$user->save();
+```
To remove a parent model from a child model, you may use the `dissociate` method. This method will set the relationship's foreign key to `null`:
- $user->account()->dissociate();
+```php
+$user->account()->dissociate();
- $user->save();
+$user->save();
+```
-### Many To Many Relationships
+### Many to Many Relationships
#### Attaching / Detaching
Eloquent also provides methods to make working with many-to-many relationships more convenient. For example, let's imagine a user can have many roles and a role can have many users. You may use the `attach` method to attach a role to a user by inserting a record in the relationship's intermediate table:
- use App\Models\User;
+```php
+use App\Models\User;
- $user = User::find(1);
+$user = User::find(1);
- $user->roles()->attach($roleId);
+$user->roles()->attach($roleId);
+```
When attaching a relationship to a model, you may also pass an array of additional data to be inserted into the intermediate table:
- $user->roles()->attach($roleId, ['expires' => $expires]);
+```php
+$user->roles()->attach($roleId, ['expires' => $expires]);
+```
Sometimes it may be necessary to remove a role from a user. To remove a many-to-many relationship record, use the `detach` method. The `detach` method will delete the appropriate record out of the intermediate table; however, both models will remain in the database:
- // Detach a single role from the user...
- $user->roles()->detach($roleId);
+```php
+// Detach a single role from the user...
+$user->roles()->detach($roleId);
- // Detach all roles from the user...
- $user->roles()->detach();
+// Detach all roles from the user...
+$user->roles()->detach();
+```
For convenience, `attach` and `detach` also accept arrays of IDs as input:
- $user = User::find(1);
+```php
+$user = User::find(1);
- $user->roles()->detach([1, 2, 3]);
+$user->roles()->detach([1, 2, 3]);
- $user->roles()->attach([
- 1 => ['expires' => $expires],
- 2 => ['expires' => $expires],
- ]);
+$user->roles()->attach([
+ 1 => ['expires' => $expires],
+ 2 => ['expires' => $expires],
+]);
+```
#### Syncing Associations
You may also use the `sync` method to construct many-to-many associations. The `sync` method accepts an array of IDs to place on the intermediate table. Any IDs that are not in the given array will be removed from the intermediate table. So, after this operation is complete, only the IDs in the given array will exist in the intermediate table:
- $user->roles()->sync([1, 2, 3]);
+```php
+$user->roles()->sync([1, 2, 3]);
+```
You may also pass additional intermediate table values with the IDs:
- $user->roles()->sync([1 => ['expires' => true], 2, 3]);
+```php
+$user->roles()->sync([1 => ['expires' => true], 2, 3]);
+```
If you would like to insert the same intermediate table values with each of the synced model IDs, you may use the `syncWithPivotValues` method:
- $user->roles()->syncWithPivotValues([1, 2, 3], ['active' => true]);
+```php
+$user->roles()->syncWithPivotValues([1, 2, 3], ['active' => true]);
+```
If you do not want to detach existing IDs that are missing from the given array, you may use the `syncWithoutDetaching` method:
- $user->roles()->syncWithoutDetaching([1, 2, 3]);
+```php
+$user->roles()->syncWithoutDetaching([1, 2, 3]);
+```
#### Toggling Associations
The many-to-many relationship also provides a `toggle` method which "toggles" the attachment status of the given related model IDs. If the given ID is currently attached, it will be detached. Likewise, if it is currently detached, it will be attached:
- $user->roles()->toggle([1, 2, 3]);
+```php
+$user->roles()->toggle([1, 2, 3]);
+```
+
+You may also pass additional intermediate table values with the IDs:
+
+```php
+$user->roles()->toggle([
+ 1 => ['expires' => true],
+ 2 => ['expires' => true],
+]);
+```
-#### Updating A Record On The Intermediate Table
+#### Updating a Record on the Intermediate Table
If you need to update an existing row in your relationship's intermediate table, you may use the `updateExistingPivot` method. This method accepts the intermediate record foreign key and an array of attributes to update:
- $user = User::find(1);
+```php
+$user = User::find(1);
- $user->roles()->updateExistingPivot($roleId, [
- 'active' => false,
- ]);
+$user->roles()->updateExistingPivot($roleId, [
+ 'active' => false,
+]);
+```
## Touching Parent Timestamps
@@ -1900,28 +2564,32 @@ When a model defines a `belongsTo` or `belongsToMany` relationship to another mo
For example, when a `Comment` model is updated, you may want to automatically "touch" the `updated_at` timestamp of the owning `Post` so that it is set to the current date and time. To accomplish this, you may add a `touches` property to your child model containing the names of the relationships that should have their `updated_at` timestamps updated when the child model is updated:
- belongsTo(Post::class);
- }
+ return $this->belongsTo(Post::class);
}
+}
+```
-> {note} Parent model timestamps will only be updated if the child model is updated using Eloquent's `save` method.
+> [!WARNING]
+> Parent model timestamps will only be updated if the child model is updated using Eloquent's `save` method.
diff --git a/eloquent-resources.md b/eloquent-resources.md
index d5b2759f643..efc2619fb5f 100644
--- a/eloquent-resources.md
+++ b/eloquent-resources.md
@@ -44,60 +44,86 @@ php artisan make:resource UserCollection
## Concept Overview
-> {tip} This is a high-level overview of resources and resource collections. You are highly encouraged to read the other sections of this documentation to gain a deeper understanding of the customization and power offered to you by resources.
+> [!NOTE]
+> This is a high-level overview of resources and resource collections. You are highly encouraged to read the other sections of this documentation to gain a deeper understanding of the customization and power offered to you by resources.
Before diving into all of the options available to you when writing resources, let's first take a high-level look at how resources are used within Laravel. A resource class represents a single model that needs to be transformed into a JSON structure. For example, here is a simple `UserResource` resource class:
-
+ */
+ public function toArray(Request $request): array
{
- /**
- * Transform the resource into an array.
- *
- * @param \Illuminate\Http\Request $request
- * @return array
- */
- public function toArray($request)
- {
- return [
- 'id' => $this->id,
- 'name' => $this->name,
- 'email' => $this->email,
- 'created_at' => $this->created_at,
- 'updated_at' => $this->updated_at,
- ];
- }
+ return [
+ 'id' => $this->id,
+ 'name' => $this->name,
+ 'email' => $this->email,
+ 'created_at' => $this->created_at,
+ 'updated_at' => $this->updated_at,
+ ];
}
+}
+```
Every resource class defines a `toArray` method which returns the array of attributes that should be converted to JSON when the resource is returned as a response from a route or controller method.
Note that we can access model properties directly from the `$this` variable. This is because a resource class will automatically proxy property and method access down to the underlying model for convenient access. Once the resource is defined, it may be returned from a route or controller. The resource accepts the underlying model instance via its constructor:
- use App\Http\Resources\UserResource;
- use App\Models\User;
+```php
+use App\Http\Resources\UserResource;
+use App\Models\User;
+
+Route::get('/user/{id}', function (string $id) {
+ return new UserResource(User::findOrFail($id));
+});
+```
+
+For convenience, you may use the model's `toResource` method, which will use framework conventions to automatically discover the model's underlying resource:
- Route::get('/user/{id}', function ($id) {
- return new UserResource(User::findOrFail($id));
- });
+```php
+return User::findOrFail($id)->toResource();
+```
+
+When invoking the `toResource` method, Laravel will attempt to locate a resource that matches the model's name and is optionally suffixed with `Resource` within the `Http\Resources` namespace closest to the model's namespace.
### Resource Collections
If you are returning a collection of resources or a paginated response, you should use the `collection` method provided by your resource class when creating the resource instance in your route or controller:
- use App\Http\Resources\UserResource;
- use App\Models\User;
+```php
+use App\Http\Resources\UserResource;
+use App\Models\User;
+
+Route::get('/users', function () {
+ return UserResource::collection(User::all());
+});
+```
+
+Or, for convenience, you may use the Eloquent collection's `toResourceCollection` method, which will use framework conventions to automatically discover the model's underlying resource collection:
- Route::get('/users', function () {
- return UserResource::collection(User::all());
- });
+```php
+return User::all()->toResourceCollection();
+```
+
+When invoking the `toResourceCollection` method, Laravel will attempt to locate a resource collection that matches the model's name and is suffixed with `Collection` within the `Http\Resources` namespace closest to the model's namespace.
+
+
+#### Custom Resource Collections
-Note that this does not allow any addition of custom meta data that may need to be returned with your collection. If you would like to customize the resource collection response, you may create a dedicated resource to represent the collection:
+By default, resource collections do not allow any addition of custom meta data that may need to be returned with your collection. If you would like to customize the resource collection response, you may create a dedicated resource to represent the collection:
```shell
php artisan make:resource UserCollection
@@ -105,209 +131,247 @@ php artisan make:resource UserCollection
Once the resource collection class has been generated, you may easily define any meta data that should be included with the response:
-
+ */
+ public function toArray(Request $request): array
{
- /**
- * Transform the resource collection into an array.
- *
- * @param \Illuminate\Http\Request $request
- * @return array
- */
- public function toArray($request)
- {
- return [
- 'data' => $this->collection,
- 'links' => [
- 'self' => 'link-value',
- ],
- ];
- }
+ return [
+ 'data' => $this->collection,
+ 'links' => [
+ 'self' => 'link-value',
+ ],
+ ];
}
+}
+```
After defining your resource collection, it may be returned from a route or controller:
- use App\Http\Resources\UserCollection;
- use App\Models\User;
+```php
+use App\Http\Resources\UserCollection;
+use App\Models\User;
+
+Route::get('/users', function () {
+ return new UserCollection(User::all());
+});
+```
+
+Or, for convenience, you may use the Eloquent collection's `toResourceCollection` method, which will use framework conventions to automatically discover the model's underlying resource collection:
+
+```php
+return User::all()->toResourceCollection();
+```
- Route::get('/users', function () {
- return new UserCollection(User::all());
- });
+When invoking the `toResourceCollection` method, Laravel will attempt to locate a resource collection that matches the model's name and is suffixed with `Collection` within the `Http\Resources` namespace closest to the model's namespace.
#### Preserving Collection Keys
When returning a resource collection from a route, Laravel resets the collection's keys so that they are in numerical order. However, you may add a `preserveKeys` property to your resource class indicating whether a collection's original keys should be preserved:
- keyBy->id);
- });
+Route::get('/users', function () {
+ return UserResource::collection(User::all()->keyBy->id);
+});
+```
-#### Customizing The Underlying Resource Class
+#### Customizing the Underlying Resource Class
Typically, the `$this->collection` property of a resource collection is automatically populated with the result of mapping each item of the collection to its singular resource class. The singular resource class is assumed to be the collection's class name without the trailing `Collection` portion of the class name. In addition, depending on your personal preference, the singular resource class may or may not be suffixed with `Resource`.
For example, `UserCollection` will attempt to map the given user instances into the `UserResource` resource. To customize this behavior, you may override the `$collects` property of your resource collection:
-
## Writing Resources
-> {tip} If you have not read the [concept overview](#concept-overview), you are highly encouraged to do so before proceeding with this documentation.
+> [!NOTE]
+> If you have not read the [concept overview](#concept-overview), you are highly encouraged to do so before proceeding with this documentation.
-In essence, resources are simple. They only need to transform a given model into an array. So, each resource contains a `toArray` method which translates your model's attributes into an API friendly array that can be returned from your application's routes or controllers:
+Resources only need to transform a given model into an array. So, each resource contains a `toArray` method which translates your model's attributes into an API friendly array that can be returned from your application's routes or controllers:
- $this->id,
- 'name' => $this->name,
- 'email' => $this->email,
- 'created_at' => $this->created_at,
- 'updated_at' => $this->updated_at,
- ];
- }
- }
-
-Once a resource has been defined, it may be returned directly from a route or controller:
-
- use App\Http\Resources\UserResource;
- use App\Models\User;
-
- Route::get('/user/{id}', function ($id) {
- return new UserResource(User::findOrFail($id));
- });
-
-
-#### Relationships
-
-If you would like to include related resources in your response, you may add them to the array returned by your resource's `toArray` method. In this example, we will use the `PostResource` resource's `collection` method to add the user's blog posts to the resource response:
-
- use App\Http\Resources\PostResource;
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+class UserResource extends JsonResource
+{
/**
* Transform the resource into an array.
*
- * @param \Illuminate\Http\Request $request
- * @return array
+ * @return array
*/
- public function toArray($request)
+ public function toArray(Request $request): array
{
return [
'id' => $this->id,
'name' => $this->name,
'email' => $this->email,
- 'posts' => PostResource::collection($this->posts),
'created_at' => $this->created_at,
'updated_at' => $this->updated_at,
];
}
+}
+```
+
+Once a resource has been defined, it may be returned directly from a route or controller:
+
+```php
+use App\Models\User;
+
+Route::get('/user/{id}', function (string $id) {
+ return User::findOrFail($id)->toUserResource();
+});
+```
+
+
+#### Relationships
+
+If you would like to include related resources in your response, you may add them to the array returned by your resource's `toArray` method. In this example, we will use the `PostResource` resource's `collection` method to add the user's blog posts to the resource response:
+
+```php
+use App\Http\Resources\PostResource;
+use Illuminate\Http\Request;
+
+/**
+ * Transform the resource into an array.
+ *
+ * @return array
+ */
+public function toArray(Request $request): array
+{
+ return [
+ 'id' => $this->id,
+ 'name' => $this->name,
+ 'email' => $this->email,
+ 'posts' => PostResource::collection($this->posts),
+ 'created_at' => $this->created_at,
+ 'updated_at' => $this->updated_at,
+ ];
+}
+```
-> {tip} If you would like to include relationships only when they have already been loaded, check out the documentation on [conditional relationships](#conditional-relationships).
+> [!NOTE]
+> If you would like to include relationships only when they have already been loaded, check out the documentation on [conditional relationships](#conditional-relationships).
#### Resource Collections
-While resources transform a single model into an array, resource collections transform a collection of models into an array. However, it is not absolutely necessary to define a resource collection class for each one of your models since all resources provide a `collection` method to generate an "ad-hoc" resource collection on the fly:
+While resources transform a single model into an array, resource collections transform a collection of models into an array. However, it is not absolutely necessary to define a resource collection class for each one of your models since all Eloquent model collections provide a `toResourceCollection` method to generate an "ad-hoc" resource collection on the fly:
- use App\Http\Resources\UserResource;
- use App\Models\User;
+```php
+use App\Models\User;
- Route::get('/users', function () {
- return UserResource::collection(User::all());
- });
+Route::get('/users', function () {
+ return User::all()->toResourceCollection();
+});
+```
However, if you need to customize the meta data returned with the collection, it is necessary to define your own resource collection:
-
+ */
+ public function toArray(Request $request): array
{
- /**
- * Transform the resource collection into an array.
- *
- * @param \Illuminate\Http\Request $request
- * @return array
- */
- public function toArray($request)
- {
- return [
- 'data' => $this->collection,
- 'links' => [
- 'self' => 'link-value',
- ],
- ];
- }
+ return [
+ 'data' => $this->collection,
+ 'links' => [
+ 'self' => 'link-value',
+ ],
+ ];
}
+}
+```
Like singular resources, resource collections may be returned directly from routes or controllers:
- use App\Http\Resources\UserCollection;
- use App\Models\User;
+```php
+use App\Http\Resources\UserCollection;
+use App\Models\User;
+
+Route::get('/users', function () {
+ return new UserCollection(User::all());
+});
+```
- Route::get('/users', function () {
- return new UserCollection(User::all());
- });
+Or, for convenience, you may use the Eloquent collection's `toResourceCollection` method, which will use framework conventions to automatically discover the model's underlying resource collection:
+
+```php
+return User::all()->toResourceCollection();
+```
+
+When invoking the `toResourceCollection` method, Laravel will attempt to locate a resource collection that matches the model's name and is suffixed with `Collection` within the `Http\Resources` namespace closest to the model's namespace.
### Data Wrapping
@@ -320,68 +384,49 @@ By default, your outermost resource is wrapped in a `data` key when the resource
{
"id": 1,
"name": "Eladio Schroeder Sr.",
- "email": "therese28@example.com",
+ "email": "therese28@example.com"
},
{
"id": 2,
"name": "Liliana Mayert",
- "email": "evandervort@example.com",
+ "email": "evandervort@example.com"
}
]
}
```
-If you would like to use a custom key instead of `data`, you may define a `$wrap` attribute on the resource class:
+If you would like to disable the wrapping of the outermost resource, you should invoke the `withoutWrapping` method on the base `Illuminate\Http\Resources\Json\JsonResource` class. Typically, you should call this method from your `AppServiceProvider` or another [service provider](/docs/{{version}}/providers) that is loaded on every request to your application:
- {note} The `withoutWrapping` method only affects the outermost response and will not remove `data` keys that you manually add to your own resource collections.
+> [!WARNING]
+> The `withoutWrapping` method only affects the outermost response and will not remove `data` keys that you manually add to your own resource collections.
#### Wrapping Nested Resources
@@ -390,28 +435,29 @@ You have total freedom to determine how your resource's relationships are wrappe
You may be wondering if this will cause your outermost resource to be wrapped in two `data` keys. Don't worry, Laravel will never let your resources be accidentally double-wrapped, so you don't have to be concerned about the nesting level of the resource collection you are transforming:
-
+ */
+ public function toArray(Request $request): array
{
- /**
- * Transform the resource collection into an array.
- *
- * @param \Illuminate\Http\Request $request
- * @return array
- */
- public function toArray($request)
- {
- return ['data' => $this->collection];
- }
+ return ['data' => $this->collection];
}
+}
+```
-#### Data Wrapping And Pagination
+#### Data Wrapping and Pagination
When returning paginated collections via a resource response, Laravel will wrap your resource data in a `data` key even if the `withoutWrapping` method has been called. This is because paginated responses always contain `meta` and `links` keys with information about the paginator's state:
@@ -421,17 +467,17 @@ When returning paginated collections via a resource response, Laravel will wrap
{
"id": 1,
"name": "Eladio Schroeder Sr.",
- "email": "therese28@example.com",
+ "email": "therese28@example.com"
},
{
"id": 2,
"name": "Liliana Mayert",
- "email": "evandervort@example.com",
+ "email": "evandervort@example.com"
}
],
"links":{
- "first": "http://example.com/pagination?page=1",
- "last": "http://example.com/pagination?page=1",
+ "first": "http://example.com/users?page=1",
+ "last": "http://example.com/users?page=1",
"prev": null,
"next": null
},
@@ -439,7 +485,7 @@ When returning paginated collections via a resource response, Laravel will wrap
"current_page": 1,
"from": 1,
"last_page": 1,
- "path": "http://example.com/pagination",
+ "path": "http://example.com/users",
"per_page": 15,
"to": 10,
"total": 10
@@ -452,12 +498,20 @@ When returning paginated collections via a resource response, Laravel will wrap
You may pass a Laravel paginator instance to the `collection` method of a resource or to a custom resource collection:
- use App\Http\Resources\UserCollection;
- use App\Models\User;
+```php
+use App\Http\Resources\UserCollection;
+use App\Models\User;
- Route::get('/users', function () {
- return new UserCollection(User::paginate());
- });
+Route::get('/users', function () {
+ return new UserCollection(User::paginate());
+});
+```
+
+Or, for convenience, you may use the paginator's `toResourceCollection` method, which will use framework conventions to automatically discover the paginated model's underlying resource collection:
+
+```php
+return User::paginate()->toResourceCollection();
+```
Paginated responses always contain `meta` and `links` keys with information about the paginator's state:
@@ -467,17 +521,17 @@ Paginated responses always contain `meta` and `links` keys with information abou
{
"id": 1,
"name": "Eladio Schroeder Sr.",
- "email": "therese28@example.com",
+ "email": "therese28@example.com"
},
{
"id": 2,
"name": "Liliana Mayert",
- "email": "evandervort@example.com",
+ "email": "evandervort@example.com"
}
],
"links":{
- "first": "http://example.com/pagination?page=1",
- "last": "http://example.com/pagination?page=1",
+ "first": "http://example.com/users?page=1",
+ "last": "http://example.com/users?page=1",
"prev": null,
"next": null
},
@@ -485,7 +539,7 @@ Paginated responses always contain `meta` and `links` keys with information abou
"current_page": 1,
"from": 1,
"last_page": 1,
- "path": "http://example.com/pagination",
+ "path": "http://example.com/users",
"per_page": 15,
"to": 10,
"total": 10
@@ -493,68 +547,105 @@ Paginated responses always contain `meta` and `links` keys with information abou
}
```
+
+#### Customizing the Pagination Information
+
+If you would like to customize the information included in the `links` or `meta` keys of the pagination response, you may define a `paginationInformation` method on the resource. This method will receive the `$paginated` data and the array of `$default` information, which is an array containing the `links` and `meta` keys:
+
+```php
+/**
+ * Customize the pagination information for the resource.
+ *
+ * @param \Illuminate\Http\Request $request
+ * @param array $paginated
+ * @param array $default
+ * @return array
+ */
+public function paginationInformation($request, $paginated, $default)
+{
+ $default['links']['custom'] = 'https://example.com/';
+
+ return $default;
+}
+```
+
### Conditional Attributes
Sometimes you may wish to only include an attribute in a resource response if a given condition is met. For example, you may wish to only include a value if the current user is an "administrator". Laravel provides a variety of helper methods to assist you in this situation. The `when` method may be used to conditionally add an attribute to a resource response:
- use Illuminate\Support\Facades\Auth;
-
- /**
- * Transform the resource into an array.
- *
- * @param \Illuminate\Http\Request $request
- * @return array
- */
- public function toArray($request)
- {
- return [
- 'id' => $this->id,
- 'name' => $this->name,
- 'email' => $this->email,
- 'secret' => $this->when(Auth::user()->isAdmin(), 'secret-value'),
- 'created_at' => $this->created_at,
- 'updated_at' => $this->updated_at,
- ];
- }
+```php
+/**
+ * Transform the resource into an array.
+ *
+ * @return array
+ */
+public function toArray(Request $request): array
+{
+ return [
+ 'id' => $this->id,
+ 'name' => $this->name,
+ 'email' => $this->email,
+ 'secret' => $this->when($request->user()->isAdmin(), 'secret-value'),
+ 'created_at' => $this->created_at,
+ 'updated_at' => $this->updated_at,
+ ];
+}
+```
In this example, the `secret` key will only be returned in the final resource response if the authenticated user's `isAdmin` method returns `true`. If the method returns `false`, the `secret` key will be removed from the resource response before it is sent to the client. The `when` method allows you to expressively define your resources without resorting to conditional statements when building the array.
The `when` method also accepts a closure as its second argument, allowing you to calculate the resulting value only if the given condition is `true`:
- 'secret' => $this->when(Auth::user()->isAdmin(), function () {
- return 'secret-value';
- }),
+```php
+'secret' => $this->when($request->user()->isAdmin(), function () {
+ return 'secret-value';
+}),
+```
+
+The `whenHas` method may be used to include an attribute if it is actually present on the underlying model:
+
+```php
+'name' => $this->whenHas('name'),
+```
+
+Additionally, the `whenNotNull` method may be used to include an attribute in the resource response if the attribute is not null:
+
+```php
+'name' => $this->whenNotNull($this->name),
+```
#### Merging Conditional Attributes
Sometimes you may have several attributes that should only be included in the resource response based on the same condition. In this case, you may use the `mergeWhen` method to include the attributes in the response only when the given condition is `true`:
- /**
- * Transform the resource into an array.
- *
- * @param \Illuminate\Http\Request $request
- * @return array
- */
- public function toArray($request)
- {
- return [
- 'id' => $this->id,
- 'name' => $this->name,
- 'email' => $this->email,
- $this->mergeWhen(Auth::user()->isAdmin(), [
- 'first-secret' => 'value',
- 'second-secret' => 'value',
- ]),
- 'created_at' => $this->created_at,
- 'updated_at' => $this->updated_at,
- ];
- }
+```php
+/**
+ * Transform the resource into an array.
+ *
+ * @return array
+ */
+public function toArray(Request $request): array
+{
+ return [
+ 'id' => $this->id,
+ 'name' => $this->name,
+ 'email' => $this->email,
+ $this->mergeWhen($request->user()->isAdmin(), [
+ 'first-secret' => 'value',
+ 'second-secret' => 'value',
+ ]),
+ 'created_at' => $this->created_at,
+ 'updated_at' => $this->updated_at,
+ ];
+}
+```
Again, if the given condition is `false`, these attributes will be removed from the resource response before it is sent to the client.
-> {note} The `mergeWhen` method should not be used within arrays that mix string and numeric keys. Furthermore, it should not be used within arrays with numeric keys that are not ordered sequentially.
+> [!WARNING]
+> The `mergeWhen` method should not be used within arrays that mix string and numeric keys. Furthermore, it should not be used within arrays with numeric keys that are not ordered sequentially.
### Conditional Relationships
@@ -563,95 +654,142 @@ In addition to conditionally loading attributes, you may conditionally include r
The `whenLoaded` method may be used to conditionally load a relationship. In order to avoid unnecessarily loading relationships, this method accepts the name of the relationship instead of the relationship itself:
- use App\Http\Resources\PostResource;
+```php
+use App\Http\Resources\PostResource;
- /**
- * Transform the resource into an array.
- *
- * @param \Illuminate\Http\Request $request
- * @return array
- */
- public function toArray($request)
- {
- return [
- 'id' => $this->id,
- 'name' => $this->name,
- 'email' => $this->email,
- 'posts' => PostResource::collection($this->whenLoaded('posts')),
- 'created_at' => $this->created_at,
- 'updated_at' => $this->updated_at,
- ];
- }
+/**
+ * Transform the resource into an array.
+ *
+ * @return array
+ */
+public function toArray(Request $request): array
+{
+ return [
+ 'id' => $this->id,
+ 'name' => $this->name,
+ 'email' => $this->email,
+ 'posts' => PostResource::collection($this->whenLoaded('posts')),
+ 'created_at' => $this->created_at,
+ 'updated_at' => $this->updated_at,
+ ];
+}
+```
In this example, if the relationship has not been loaded, the `posts` key will be removed from the resource response before it is sent to the client.
+
+#### Conditional Relationship Counts
+
+In addition to conditionally including relationships, you may conditionally include relationship "counts" on your resource responses based on if the relationship's count has been loaded on the model:
+
+```php
+new UserResource($user->loadCount('posts'));
+```
+
+The `whenCounted` method may be used to conditionally include a relationship's count in your resource response. This method avoids unnecessarily including the attribute if the relationships' count is not present:
+
+```php
+/**
+ * Transform the resource into an array.
+ *
+ * @return array
+ */
+public function toArray(Request $request): array
+{
+ return [
+ 'id' => $this->id,
+ 'name' => $this->name,
+ 'email' => $this->email,
+ 'posts_count' => $this->whenCounted('posts'),
+ 'created_at' => $this->created_at,
+ 'updated_at' => $this->updated_at,
+ ];
+}
+```
+
+In this example, if the `posts` relationship's count has not been loaded, the `posts_count` key will be removed from the resource response before it is sent to the client.
+
+Other types of aggregates, such as `avg`, `sum`, `min`, and `max` may also be conditionally loaded using the `whenAggregated` method:
+
+```php
+'words_avg' => $this->whenAggregated('posts', 'words', 'avg'),
+'words_sum' => $this->whenAggregated('posts', 'words', 'sum'),
+'words_min' => $this->whenAggregated('posts', 'words', 'min'),
+'words_max' => $this->whenAggregated('posts', 'words', 'max'),
+```
+
#### Conditional Pivot Information
In addition to conditionally including relationship information in your resource responses, you may conditionally include data from the intermediate tables of many-to-many relationships using the `whenPivotLoaded` method. The `whenPivotLoaded` method accepts the name of the pivot table as its first argument. The second argument should be a closure that returns the value to be returned if the pivot information is available on the model:
- /**
- * Transform the resource into an array.
- *
- * @param \Illuminate\Http\Request $request
- * @return array
- */
- public function toArray($request)
- {
- return [
- 'id' => $this->id,
- 'name' => $this->name,
- 'expires_at' => $this->whenPivotLoaded('role_user', function () {
- return $this->pivot->expires_at;
- }),
- ];
- }
+```php
+/**
+ * Transform the resource into an array.
+ *
+ * @return array
+ */
+public function toArray(Request $request): array
+{
+ return [
+ 'id' => $this->id,
+ 'name' => $this->name,
+ 'expires_at' => $this->whenPivotLoaded('role_user', function () {
+ return $this->pivot->expires_at;
+ }),
+ ];
+}
+```
If your relationship is using a [custom intermediate table model](/docs/{{version}}/eloquent-relationships#defining-custom-intermediate-table-models), you may pass an instance of the intermediate table model as the first argument to the `whenPivotLoaded` method:
- 'expires_at' => $this->whenPivotLoaded(new Membership, function () {
- return $this->pivot->expires_at;
- }),
+```php
+'expires_at' => $this->whenPivotLoaded(new Membership, function () {
+ return $this->pivot->expires_at;
+}),
+```
If your intermediate table is using an accessor other than `pivot`, you may use the `whenPivotLoadedAs` method:
- /**
- * Transform the resource into an array.
- *
- * @param \Illuminate\Http\Request $request
- * @return array
- */
- public function toArray($request)
- {
- return [
- 'id' => $this->id,
- 'name' => $this->name,
- 'expires_at' => $this->whenPivotLoadedAs('subscription', 'role_user', function () {
- return $this->subscription->expires_at;
- }),
- ];
- }
+```php
+/**
+ * Transform the resource into an array.
+ *
+ * @return array
+ */
+public function toArray(Request $request): array
+{
+ return [
+ 'id' => $this->id,
+ 'name' => $this->name,
+ 'expires_at' => $this->whenPivotLoadedAs('subscription', 'role_user', function () {
+ return $this->subscription->expires_at;
+ }),
+ ];
+}
+```
### Adding Meta Data
-Some JSON API standards require the addition of meta data to your resource and resource collections responses. This often includes things like `links` to the resource or related resources, or meta data about the resource itself. If you need to return additional meta data about a resource, include it in your `toArray` method. For example, you might include `link` information when transforming a resource collection:
+Some JSON API standards require the addition of meta data to your resource and resource collections responses. This often includes things like `links` to the resource or related resources, or meta data about the resource itself. If you need to return additional meta data about a resource, include it in your `toArray` method. For example, you might include `links` information when transforming a resource collection:
- /**
- * Transform the resource into an array.
- *
- * @param \Illuminate\Http\Request $request
- * @return array
- */
- public function toArray($request)
- {
- return [
- 'data' => $this->collection,
- 'links' => [
- 'self' => 'link-value',
- ],
- ];
- }
+```php
+/**
+ * Transform the resource into an array.
+ *
+ * @return array
+ */
+public function toArray(Request $request): array
+{
+ return [
+ 'data' => $this->collection,
+ 'links' => [
+ 'self' => 'link-value',
+ ],
+ ];
+}
+```
When returning additional meta data from your resources, you never have to worry about accidentally overriding the `links` or `meta` keys that are automatically added by Laravel when returning paginated responses. Any additional `links` you define will be merged with the links provided by the paginator.
@@ -660,106 +798,113 @@ When returning additional meta data from your resources, you never have to worry
Sometimes you may wish to only include certain meta data with a resource response if the resource is the outermost resource being returned. Typically, this includes meta information about the response as a whole. To define this meta data, add a `with` method to your resource class. This method should return an array of meta data to be included with the resource response only when the resource is the outermost resource being transformed:
-
+ */
+ public function toArray(Request $request): array
{
- /**
- * Transform the resource collection into an array.
- *
- * @param \Illuminate\Http\Request $request
- * @return array
- */
- public function toArray($request)
- {
- return parent::toArray($request);
- }
+ return parent::toArray($request);
+ }
- /**
- * Get additional data that should be returned with the resource array.
- *
- * @param \Illuminate\Http\Request $request
- * @return array
- */
- public function with($request)
- {
- return [
- 'meta' => [
- 'key' => 'value',
- ],
- ];
- }
+ /**
+ * Get additional data that should be returned with the resource array.
+ *
+ * @return array
+ */
+ public function with(Request $request): array
+ {
+ return [
+ 'meta' => [
+ 'key' => 'value',
+ ],
+ ];
}
+}
+```
#### Adding Meta Data When Constructing Resources
You may also add top-level data when constructing resource instances in your route or controller. The `additional` method, which is available on all resources, accepts an array of data that should be added to the resource response:
- return (new UserCollection(User::all()->load('roles')))
- ->additional(['meta' => [
- 'key' => 'value',
- ]]);
+```php
+return User::all()
+ ->load('roles')
+ ->toResourceCollection()
+ ->additional(['meta' => [
+ 'key' => 'value',
+ ]]);
+```
## Resource Responses
As you have already read, resources may be returned directly from routes and controllers:
- use App\Http\Resources\UserResource;
- use App\Models\User;
+```php
+use App\Models\User;
- Route::get('/user/{id}', function ($id) {
- return new UserResource(User::findOrFail($id));
- });
+Route::get('/user/{id}', function (string $id) {
+ return User::findOrFail($id)->toResource();
+});
+```
However, sometimes you may need to customize the outgoing HTTP response before it is sent to the client. There are two ways to accomplish this. First, you may chain the `response` method onto the resource. This method will return an `Illuminate\Http\JsonResponse` instance, giving you full control over the response's headers:
- use App\Http\Resources\UserResource;
- use App\Models\User;
+```php
+use App\Http\Resources\UserResource;
+use App\Models\User;
- Route::get('/user', function () {
- return (new UserResource(User::find(1)))
- ->response()
- ->header('X-Value', 'True');
- });
+Route::get('/user', function () {
+ return User::find(1)
+ ->toResource()
+ ->response()
+ ->header('X-Value', 'True');
+});
+```
Alternatively, you may define a `withResponse` method within the resource itself. This method will be called when the resource is returned as the outermost resource in a response:
-
+ */
+ public function toArray(Request $request): array
{
- /**
- * Transform the resource into an array.
- *
- * @param \Illuminate\Http\Request $request
- * @return array
- */
- public function toArray($request)
- {
- return [
- 'id' => $this->id,
- ];
- }
+ return [
+ 'id' => $this->id,
+ ];
+ }
- /**
- * Customize the outgoing response for the resource.
- *
- * @param \Illuminate\Http\Request $request
- * @param \Illuminate\Http\Response $response
- * @return void
- */
- public function withResponse($request, $response)
- {
- $response->header('X-Value', 'True');
- }
+ /**
+ * Customize the outgoing response for the resource.
+ */
+ public function withResponse(Request $request, JsonResponse $response): void
+ {
+ $response->header('X-Value', 'True');
}
+}
+```
diff --git a/eloquent-serialization.md b/eloquent-serialization.md
index 3b7dac91dd3..91606b6d606 100644
--- a/eloquent-serialization.md
+++ b/eloquent-serialization.md
@@ -1,11 +1,11 @@
# Eloquent: Serialization
- [Introduction](#introduction)
-- [Serializing Models & Collections](#serializing-models-and-collections)
- - [Serializing To Arrays](#serializing-to-arrays)
- - [Serializing To JSON](#serializing-to-json)
+- [Serializing Models and Collections](#serializing-models-and-collections)
+ - [Serializing to Arrays](#serializing-to-arrays)
+ - [Serializing to JSON](#serializing-to-json)
- [Hiding Attributes From JSON](#hiding-attributes-from-json)
-- [Appending Values To JSON](#appending-values-to-json)
+- [Appending Values to JSON](#appending-values-to-json)
- [Date Serialization](#date-serialization)
@@ -13,56 +13,69 @@
When building APIs using Laravel, you will often need to convert your models and relationships to arrays or JSON. Eloquent includes convenient methods for making these conversions, as well as controlling which attributes are included in the serialized representation of your models.
-> {tip} For an even more robust way of handling Eloquent model and collection JSON serialization, check out the documentation on [Eloquent API resources](/docs/{{version}}/eloquent-resources).
+> [!NOTE]
+> For an even more robust way of handling Eloquent model and collection JSON serialization, check out the documentation on [Eloquent API resources](/docs/{{version}}/eloquent-resources).
-## Serializing Models & Collections
+## Serializing Models and Collections
-### Serializing To Arrays
+### Serializing to Arrays
To convert a model and its loaded [relationships](/docs/{{version}}/eloquent-relationships) to an array, you should use the `toArray` method. This method is recursive, so all attributes and all relations (including the relations of relations) will be converted to arrays:
- use App\Models\User;
+```php
+use App\Models\User;
- $user = User::with('roles')->first();
+$user = User::with('roles')->first();
- return $user->toArray();
+return $user->toArray();
+```
The `attributesToArray` method may be used to convert a model's attributes to an array but not its relationships:
- $user = User::first();
+```php
+$user = User::first();
- return $user->attributesToArray();
+return $user->attributesToArray();
+```
You may also convert entire [collections](/docs/{{version}}/eloquent-collections) of models to arrays by calling the `toArray` method on the collection instance:
- $users = User::all();
+```php
+$users = User::all();
- return $users->toArray();
+return $users->toArray();
+```
-### Serializing To JSON
+### Serializing to JSON
To convert a model to JSON, you should use the `toJson` method. Like `toArray`, the `toJson` method is recursive, so all attributes and relations will be converted to JSON. You may also specify any JSON encoding options that are [supported by PHP](https://secure.php.net/manual/en/function.json-encode.php):
- use App\Models\User;
+```php
+use App\Models\User;
- $user = User::find(1);
+$user = User::find(1);
- return $user->toJson();
+return $user->toJson();
- return $user->toJson(JSON_PRETTY_PRINT);
+return $user->toJson(JSON_PRETTY_PRINT);
+```
Alternatively, you may cast a model or collection to a string, which will automatically call the `toJson` method on the model or collection:
- return (string) User::find(1);
+```php
+return (string) User::find(1);
+```
Since models and collections are converted to JSON when cast to a string, you can return Eloquent objects directly from your application's routes or controllers. Laravel will automatically serialize your Eloquent models and collections to JSON when they are returned from routes or controllers:
- Route::get('users', function () {
- return User::all();
- });
+```php
+Route::get('/users', function () {
+ return User::all();
+});
+```
#### Relationships
@@ -72,136 +85,167 @@ When an Eloquent model is converted to JSON, its loaded relationships will autom
## Hiding Attributes From JSON
-Sometimes you may wish to limit the attributes, such as passwords, that are included in your model's array or JSON representation. To do so, add a `$hidden` property to your model. In attributes that are listed in the `$hidden` property's array will not be included in the serialized representation of your model:
+Sometimes you may wish to limit the attributes, such as passwords, that are included in your model's array or JSON representation. To do so, add a `$hidden` property to your model. Attributes that are listed in the `$hidden` property's array will not be included in the serialized representation of your model:
-
+ */
+ protected $hidden = ['password'];
+}
+```
-> {tip} To hide relationships, add the relationship's method name to your Eloquent model's `$hidden` property.
+> [!NOTE]
+> To hide relationships, add the relationship's method name to your Eloquent model's `$hidden` property.
Alternatively, you may use the `visible` property to define an "allow list" of attributes that should be included in your model's array and JSON representation. All attributes that are not present in the `$visible` array will be hidden when the model is converted to an array or JSON:
-
#### Temporarily Modifying Attribute Visibility
-If you would like to make some typically hidden attributes visible on a given model instance, you may use the `makeVisible` method. The `makeVisible` method returns the model instance:
+If you would like to make some typically hidden attributes visible on a given model instance, you may use the `makeVisible` or `mergeVisible` methods. The `makeVisible` method returns the model instance:
+
+```php
+return $user->makeVisible('attribute')->toArray();
+
+return $user->mergeVisible(['name', 'email'])->toArray();
+```
+
+Likewise, if you would like to hide some attributes that are typically visible, you may use the `makeHidden` or `mergeHidden` methods:
+
+```php
+return $user->makeHidden('attribute')->toArray();
- return $user->makeVisible('attribute')->toArray();
+return $user->mergeHidden(['name', 'email'])->toArray();
+```
-Likewise, if you would like to hide some attributes that are typically visible, you may use the `makeHidden` method.
+If you wish to temporarily override all of the visible or hidden attributes, you may use the `setVisible` and `setHidden` methods respectively:
- return $user->makeHidden('attribute')->toArray();
+```php
+return $user->setVisible(['id', 'name'])->toArray();
+
+return $user->setHidden(['email', 'password', 'remember_token'])->toArray();
+```
-## Appending Values To JSON
+## Appending Values to JSON
Occasionally, when converting models to arrays or JSON, you may wish to add attributes that do not have a corresponding column in your database. To do so, first define an [accessor](/docs/{{version}}/eloquent-mutators) for the value:
- 'yes',
- );
- }
+ return new Attribute(
+ get: fn () => 'yes',
+ );
}
+}
+```
-After creating the accessor, add the attribute name to the `appends` property of your model. Note that attribute names are typically referenced using their "snake case" serialized representation, even though the accessor's PHP method is defined using "camel case":
+If you would like the accessor to always be appended to your model's array and JSON representations, you may add the attribute name to the `appends` property of your model. Note that attribute names are typically referenced using their "snake case" serialized representation, even though the accessor's PHP method is defined using "camel case":
-
-#### Appending At Run Time
+#### Appending at Run Time
+
+At runtime, you may instruct a model instance to append additional attributes using the `append` or `mergeAppends` methods. Or, you may use the `setAppends` method to override the entire array of appended properties for a given model instance:
-At runtime, you may instruct a model instance to append additional attributes using the `append` method. Or, you may use the `setAppends` method to override the entire array of appended properties for a given model instance:
+```php
+return $user->append('is_admin')->toArray();
- return $user->append('is_admin')->toArray();
+return $user->mergeAppends(['is_admin', 'status'])->toArray();
- return $user->setAppends(['is_admin'])->toArray();
+return $user->setAppends(['is_admin'])->toArray();
+```
## Date Serialization
-#### Customizing The Default Date Format
+#### Customizing the Default Date Format
You may customize the default serialization format by overriding the `serializeDate` method. This method does not affect how your dates are formatted for storage in the database:
- /**
- * Prepare a date for array / JSON serialization.
- *
- * @param \DateTimeInterface $date
- * @return string
- */
- protected function serializeDate(DateTimeInterface $date)
- {
- return $date->format('Y-m-d');
- }
+```php
+/**
+ * Prepare a date for array / JSON serialization.
+ */
+protected function serializeDate(DateTimeInterface $date): string
+{
+ return $date->format('Y-m-d');
+}
+```
-#### Customizing The Date Format Per Attribute
+#### Customizing the Date Format per Attribute
You may customize the serialization format of individual Eloquent date attributes by specifying the date format in the model's [cast declarations](/docs/{{version}}/eloquent-mutators#attribute-casting):
- protected $casts = [
+```php
+protected function casts(): array
+{
+ return [
'birthday' => 'date:Y-m-d',
'joined_at' => 'datetime:Y-m-d H:00',
];
+}
+```
diff --git a/eloquent.md b/eloquent.md
index b378ad1caa9..c8356bf2a14 100644
--- a/eloquent.md
+++ b/eloquent.md
@@ -5,9 +5,11 @@
- [Eloquent Model Conventions](#eloquent-model-conventions)
- [Table Names](#table-names)
- [Primary Keys](#primary-keys)
+ - [UUID and ULID Keys](#uuid-and-ulid-keys)
- [Timestamps](#timestamps)
- [Database Connections](#database-connections)
- [Default Attribute Values](#default-attribute-values)
+ - [Configuring Eloquent Strictness](#configuring-eloquent-strictness)
- [Retrieving Models](#retrieving-models)
- [Collections](#collections)
- [Chunking Results](#chunking-results)
@@ -15,9 +17,9 @@
- [Cursors](#cursors)
- [Advanced Subqueries](#advanced-subqueries)
- [Retrieving Single Models / Aggregates](#retrieving-single-models)
- - [Retrieving Or Creating Models](#retrieving-or-creating-models)
+ - [Retrieving or Creating Models](#retrieving-or-creating-models)
- [Retrieving Aggregates](#retrieving-aggregates)
-- [Inserting & Updating Models](#inserting-and-updating-models)
+- [Inserting and Updating Models](#inserting-and-updating-models)
- [Inserts](#inserts)
- [Updates](#updates)
- [Mass Assignment](#mass-assignment)
@@ -30,6 +32,7 @@
- [Query Scopes](#query-scopes)
- [Global Scopes](#global-scopes)
- [Local Scopes](#local-scopes)
+ - [Pending Attributes](#pending-attributes)
- [Comparing Models](#comparing-models)
- [Events](#events)
- [Using Closures](#events-using-closures)
@@ -41,7 +44,8 @@
Laravel includes Eloquent, an object-relational mapper (ORM) that makes it enjoyable to interact with your database. When using Eloquent, each database table has a corresponding "Model" that is used to interact with that table. In addition to retrieving records from the database table, Eloquent models allow you to insert, update, and delete records from the table as well.
-> {tip} Before getting started, be sure to configure a database connection in your application's `config/database.php` configuration file. For more information on configuring your database, check out [the database configuration documentation](/docs/{{version}}/database#configuration).
+> [!NOTE]
+> Before getting started, be sure to configure a database connection in your application's `config/database.php` configuration file. For more information on configuring your database, check out [the database configuration documentation](/docs/{{version}}/database#configuration).
## Generating Model Classes
@@ -85,9 +89,20 @@ php artisan make:model Flight -mfsc
# Shortcut to generate a model, migration, factory, seeder, policy, controller, and form requests...
php artisan make:model Flight --all
+php artisan make:model Flight -a
# Generate a pivot model...
php artisan make:model Member --pivot
+php artisan make:model Member -p
+```
+
+
+#### Inspecting Models
+
+Sometimes it can be difficult to determine all of a model's available attributes and relationships just by skimming its code. Instead, try the `model:show` Artisan command, which provides a convenient overview of all the model's attributes and relations:
+
+```shell
+php artisan model:show Flight
```
@@ -95,16 +110,18 @@ php artisan make:model Member --pivot
Models generated by the `make:model` command will be placed in the `app/Models` directory. Let's examine a basic model class and discuss some of Eloquent's key conventions:
-
### Table Names
@@ -113,210 +130,336 @@ After glancing at the example above, you may have noticed that we did not tell E
If your model's corresponding database table does not fit this convention, you may manually specify the model's table name by defining a `table` property on the model:
-
### Primary Keys
Eloquent will also assume that each model's corresponding database table has a primary key column named `id`. If necessary, you may define a protected `$primaryKey` property on your model to specify a different column that serves as your model's primary key:
-
#### "Composite" Primary Keys
Eloquent requires each model to have at least one uniquely identifying "ID" that can serve as its primary key. "Composite" primary keys are not supported by Eloquent models. However, you are free to add additional multi-column, unique indexes to your database tables in addition to the table's uniquely identifying primary key.
+
+### UUID and ULID Keys
+
+Instead of using auto-incrementing integers as your Eloquent model's primary keys, you may choose to use UUIDs instead. UUIDs are universally unique alpha-numeric identifiers that are 36 characters long.
+
+If you would like a model to use a UUID key instead of an auto-incrementing integer key, you may use the `Illuminate\Database\Eloquent\Concerns\HasUuids` trait on the model. Of course, you should ensure that the model has a [UUID equivalent primary key column](/docs/{{version}}/migrations#column-method-uuid):
+
+```php
+use Illuminate\Database\Eloquent\Concerns\HasUuids;
+use Illuminate\Database\Eloquent\Model;
+
+class Article extends Model
+{
+ use HasUuids;
+
+ // ...
+}
+
+$article = Article::create(['title' => 'Traveling to Europe']);
+
+$article->id; // "8f8e8478-9035-4d23-b9a7-62f4d2612ce5"
+```
+
+By default, The `HasUuids` trait will generate ["ordered" UUIDs](/docs/{{version}}/strings#method-str-ordered-uuid) for your models. These UUIDs are more efficient for indexed database storage because they can be sorted lexicographically.
+
+You can override the UUID generation process for a given model by defining a `newUniqueId` method on the model. In addition, you may specify which columns should receive UUIDs by defining a `uniqueIds` method on the model:
+
+```php
+use Ramsey\Uuid\Uuid;
+
+/**
+ * Generate a new UUID for the model.
+ */
+public function newUniqueId(): string
+{
+ return (string) Uuid::uuid4();
+}
+
+/**
+ * Get the columns that should receive a unique identifier.
+ *
+ * @return array
+ */
+public function uniqueIds(): array
+{
+ return ['id', 'discount_code'];
+}
+```
+
+If you wish, you may choose to utilize "ULIDs" instead of UUIDs. ULIDs are similar to UUIDs; however, they are only 26 characters in length. Like ordered UUIDs, ULIDs are lexicographically sortable for efficient database indexing. To utilize ULIDs, you should use the `Illuminate\Database\Eloquent\Concerns\HasUlids` trait on your model. You should also ensure that the model has a [ULID equivalent primary key column](/docs/{{version}}/migrations#column-method-ulid):
+
+```php
+use Illuminate\Database\Eloquent\Concerns\HasUlids;
+use Illuminate\Database\Eloquent\Model;
+
+class Article extends Model
+{
+ use HasUlids;
+
+ // ...
+}
+
+$article = Article::create(['title' => 'Traveling to Asia']);
+
+$article->id; // "01gd4d3tgrrfqeda94gdbtdk5c"
+```
+
### Timestamps
-By default, Eloquent expects `created_at` and `updated_at` columns to exist on your model's corresponding database table. Eloquent will automatically set these column's values when models are created or updated. If you do not want these columns to be automatically managed by Eloquent, you should define a `$timestamps` property on your model with a value of `false`:
+By default, Eloquent expects `created_at` and `updated_at` columns to exist on your model's corresponding database table. Eloquent will automatically set these column's values when models are created or updated. If you do not want these columns to be automatically managed by Eloquent, you should define a `$timestamps` property on your model with a value of `false`:
- $post->increment('reads'));
+```
### Database Connections
By default, all Eloquent models will use the default database connection that is configured for your application. If you would like to specify a different connection that should be used when interacting with a particular model, you should define a `$connection` property on the model:
-
### Default Attribute Values
-By default, a newly instantiated model instance will not contain any attribute values. If you would like to define the default values for some of your model's attributes, you may define an `$attributes` property on your model:
+By default, a newly instantiated model instance will not contain any attribute values. If you would like to define the default values for some of your model's attributes, you may define an `$attributes` property on your model. Attribute values placed in the `$attributes` array should be in their raw, "storable" format as if they were just read from the database:
- false,
- ];
- }
+class Flight extends Model
+{
+ /**
+ * The model's default values for attributes.
+ *
+ * @var array
+ */
+ protected $attributes = [
+ 'options' => '[]',
+ 'delayed' => false,
+ ];
+}
+```
+
+
+### Configuring Eloquent Strictness
+
+Laravel offers several methods that allow you to configure Eloquent's behavior and "strictness" in a variety of situations.
+
+First, the `preventLazyLoading` method accepts an optional boolean argument that indicates if lazy loading should be prevented. For example, you may wish to only disable lazy loading in non-production environments so that your production environment will continue to function normally even if a lazy loaded relationship is accidentally present in production code. Typically, this method should be invoked in the `boot` method of your application's `AppServiceProvider`:
+
+```php
+use Illuminate\Database\Eloquent\Model;
+
+/**
+ * Bootstrap any application services.
+ */
+public function boot(): void
+{
+ Model::preventLazyLoading(! $this->app->isProduction());
+}
+```
+
+Also, you may instruct Laravel to throw an exception when attempting to fill an unfillable attribute by invoking the `preventSilentlyDiscardingAttributes` method. This can help prevent unexpected errors during local development when attempting to set an attribute that has not been added to the model's `fillable` array:
+
+```php
+Model::preventSilentlyDiscardingAttributes(! $this->app->isProduction());
+```
## Retrieving Models
-Once you have created a model and [its associated database table](/docs/{{version}}/migrations#writing-migrations), you are ready to start retrieving data from your database. You can think of each Eloquent model as a powerful [query builder](/docs/{{version}}/queries) allowing you to fluently query the database table associated with the model. The model's `all` method will retrieve all of the records from the model's associated database table:
+Once you have created a model and [its associated database table](/docs/{{version}}/migrations#generating-migrations), you are ready to start retrieving data from your database. You can think of each Eloquent model as a powerful [query builder](/docs/{{version}}/queries) allowing you to fluently query the database table associated with the model. The model's `all` method will retrieve all of the records from the model's associated database table:
- use App\Models\Flight;
+```php
+use App\Models\Flight;
- foreach (Flight::all() as $flight) {
- echo $flight->name;
- }
+foreach (Flight::all() as $flight) {
+ echo $flight->name;
+}
+```
#### Building Queries
The Eloquent `all` method will return all of the results in the model's table. However, since each Eloquent model serves as a [query builder](/docs/{{version}}/queries), you may add additional constraints to queries and then invoke the `get` method to retrieve the results:
- $flights = Flight::where('active', 1)
- ->orderBy('name')
- ->take(10)
- ->get();
+```php
+$flights = Flight::where('active', 1)
+ ->orderBy('name')
+ ->limit(10)
+ ->get();
+```
-> {tip} Since Eloquent models are query builders, you should review all of the methods provided by Laravel's [query builder](/docs/{{version}}/queries). You may use any of these methods when writing your Eloquent queries.
+> [!NOTE]
+> Since Eloquent models are query builders, you should review all of the methods provided by Laravel's [query builder](/docs/{{version}}/queries). You may use any of these methods when writing your Eloquent queries.
#### Refreshing Models
If you already have an instance of an Eloquent model that was retrieved from the database, you can "refresh" the model using the `fresh` and `refresh` methods. The `fresh` method will re-retrieve the model from the database. The existing model instance will not be affected:
- $flight = Flight::where('number', 'FR 900')->first();
+```php
+$flight = Flight::where('number', 'FR 900')->first();
- $freshFlight = $flight->fresh();
+$freshFlight = $flight->fresh();
+```
The `refresh` method will re-hydrate the existing model using fresh data from the database. In addition, all of its loaded relationships will be refreshed as well:
- $flight = Flight::where('number', 'FR 900')->first();
+```php
+$flight = Flight::where('number', 'FR 900')->first();
- $flight->number = 'FR 456';
+$flight->number = 'FR 456';
- $flight->refresh();
+$flight->refresh();
- $flight->number; // "FR 900"
+$flight->number; // "FR 900"
+```
### Collections
@@ -328,7 +471,7 @@ The Eloquent `Collection` class extends Laravel's base `Illuminate\Support\Colle
```php
$flights = Flight::where('destination', 'Paris')->get();
-$flights = $flights->reject(function ($flight) {
+$flights = $flights->reject(function (Flight $flight) {
return $flight->cancelled;
});
```
@@ -352,10 +495,11 @@ The `chunk` method will retrieve a subset of Eloquent models, passing them to a
```php
use App\Models\Flight;
+use Illuminate\Database\Eloquent\Collection;
-Flight::chunk(200, function ($flights) {
+Flight::chunk(200, function (Collection $flights) {
foreach ($flights as $flight) {
- //
+ // ...
}
});
```
@@ -366,21 +510,34 @@ If you are filtering the results of the `chunk` method based on a column that yo
```php
Flight::where('departed', true)
- ->chunkById(200, function ($flights) {
+ ->chunkById(200, function (Collection $flights) {
$flights->each->update(['departed' => false]);
- }, $column = 'id');
+ }, column: 'id');
+```
+
+Since the `chunkById` and `lazyById` methods add their own "where" conditions to the query being executed, you should typically [logically group](/docs/{{version}}/queries#logical-grouping) your own conditions within a closure:
+
+```php
+Flight::where(function ($query) {
+ $query->where('delayed', true)->orWhere('cancelled', true);
+})->chunkById(200, function (Collection $flights) {
+ $flights->each->update([
+ 'departed' => false,
+ 'cancelled' => true
+ ]);
+}, column: 'id');
```
### Chunking Using Lazy Collections
-The `lazy` method works similarly to [the `chunk` method](#chunking-results) in the sense that, behind the scenes, it executes the query in chunks. However, instead of passing each chunk directly into a callback as is, the `lazy` method returns a flattened [`LazyCollection`](/docs/{{version}}/collections#lazy-collections) of Eloquent models, which lets you interact with the results as a single stream:
+The `lazy` method works similarly to [the `chunk` method](#chunking-results) in the sense that, behind the scenes, it executes the query in chunks. However, instead of passing each chunk directly into a callback as is, the `lazy` method returns a flattened [LazyCollection](/docs/{{version}}/collections#lazy-collections) of Eloquent models, which lets you interact with the results as a single stream:
```php
use App\Models\Flight;
foreach (Flight::lazy() as $flight) {
- //
+ // ...
}
```
@@ -388,7 +545,7 @@ If you are filtering the results of the `lazy` method based on a column that you
```php
Flight::where('departed', true)
- ->lazyById(200, $column = 'id')
+ ->lazyById(200, column: 'id')
->each->update(['departed' => false]);
```
@@ -401,7 +558,8 @@ Similar to the `lazy` method, the `cursor` method may be used to significantly r
The `cursor` method will only execute a single database query; however, the individual Eloquent models will not be hydrated until they are actually iterated over. Therefore, only one Eloquent model is kept in memory at any given time while iterating over the cursor.
-> {note} Since the `cursor` method only ever holds a single Eloquent model in memory at a time, it cannot eager load relationships. If you need to eager load relationships, consider using [the `lazy` method](#streaming-results-lazily) instead.
+> [!WARNING]
+> Since the `cursor` method only ever holds a single Eloquent model in memory at a time, it cannot eager load relationships. If you need to eager load relationships, consider using [the `lazy` method](#chunking-using-lazy-collections) instead.
Internally, the `cursor` method uses PHP [generators](https://www.php.net/manual/en/language.generators.overview.php) to implement this functionality:
@@ -409,7 +567,7 @@ Internally, the `cursor` method uses PHP [generators](https://www.php.net/manual
use App\Models\Flight;
foreach (Flight::where('destination', 'Zurich')->cursor() as $flight) {
- //
+ // ...
}
```
@@ -418,7 +576,7 @@ The `cursor` returns an `Illuminate\Support\LazyCollection` instance. [Lazy coll
```php
use App\Models\User;
-$users = User::cursor()->filter(function ($user) {
+$users = User::cursor()->filter(function (User $user) {
return $user->id > 500;
});
@@ -427,7 +585,7 @@ foreach ($users as $user) {
}
```
-Although the `cursor` method uses far less memory than a regular query (by only holding a single Eloquent model in memory at a time), it will still eventually run out of memory. This is [due to PHP's PDO driver internally caching all raw query results in its buffer](https://www.php.net/manual/en/mysqlinfo.concepts.buffering.php). If you're dealing with a very large number of Eloquent records, consider using [the `lazy` method](#streaming-results-lazily) instead.
+Although the `cursor` method uses far less memory than a regular query (by only holding a single Eloquent model in memory at a time), it will still eventually run out of memory. This is [due to PHP's PDO driver internally caching all raw query results in its buffer](https://www.php.net/manual/en/mysqlinfo.concepts.buffering.php). If you're dealing with a very large number of Eloquent records, consider using [the `lazy` method](#chunking-using-lazy-collections) instead.
### Advanced Subqueries
@@ -439,151 +597,174 @@ Eloquent also offers advanced subquery support, which allows you to pull informa
Using the subquery functionality available to the query builder's `select` and `addSelect` methods, we can select all of the `destinations` and the name of the flight that most recently arrived at that destination using a single query:
- use App\Models\Destination;
- use App\Models\Flight;
+```php
+use App\Models\Destination;
+use App\Models\Flight;
- return Destination::addSelect(['last_flight' => Flight::select('name')
- ->whereColumn('destination_id', 'destinations.id')
- ->orderByDesc('arrived_at')
- ->limit(1)
- ])->get();
+return Destination::addSelect(['last_flight' => Flight::select('name')
+ ->whereColumn('destination_id', 'destinations.id')
+ ->orderByDesc('arrived_at')
+ ->limit(1)
+])->get();
+```
#### Subquery Ordering
In addition, the query builder's `orderBy` function supports subqueries. Continuing to use our flight example, we may use this functionality to sort all destinations based on when the last flight arrived at that destination. Again, this may be done while executing a single database query:
- return Destination::orderByDesc(
- Flight::select('arrived_at')
- ->whereColumn('destination_id', 'destinations.id')
- ->orderByDesc('arrived_at')
- ->limit(1)
- )->get();
+```php
+return Destination::orderByDesc(
+ Flight::select('arrived_at')
+ ->whereColumn('destination_id', 'destinations.id')
+ ->orderByDesc('arrived_at')
+ ->limit(1)
+)->get();
+```
## Retrieving Single Models / Aggregates
In addition to retrieving all of the records matching a given query, you may also retrieve single records using the `find`, `first`, or `firstWhere` methods. Instead of returning a collection of models, these methods return a single model instance:
- use App\Models\Flight;
+```php
+use App\Models\Flight;
- // Retrieve a model by its primary key...
- $flight = Flight::find(1);
+// Retrieve a model by its primary key...
+$flight = Flight::find(1);
- // Retrieve the first model matching the query constraints...
- $flight = Flight::where('active', 1)->first();
+// Retrieve the first model matching the query constraints...
+$flight = Flight::where('active', 1)->first();
- // Alternative to retrieving the first model matching the query constraints...
- $flight = Flight::firstWhere('active', 1);
+// Alternative to retrieving the first model matching the query constraints...
+$flight = Flight::firstWhere('active', 1);
+```
-Sometimes you may wish to retrieve the first result of a query or perform some other action if no results are found. The `firstOr` method will return the first result matching the query or, if no results are found, execute the given closure. The value returned by the closure will be considered the result of the `firstOr` method:
+Sometimes you may wish to perform some other action if no results are found. The `findOr` and `firstOr` methods will return a single model instance or, if no results are found, execute the given closure. The value returned by the closure will be considered the result of the method:
- $model = Flight::where('legs', '>', 3)->firstOr(function () {
- // ...
- });
+```php
+$flight = Flight::findOr(1, function () {
+ // ...
+});
+
+$flight = Flight::where('legs', '>', 3)->firstOr(function () {
+ // ...
+});
+```
#### Not Found Exceptions
Sometimes you may wish to throw an exception if a model is not found. This is particularly useful in routes or controllers. The `findOrFail` and `firstOrFail` methods will retrieve the first result of the query; however, if no result is found, an `Illuminate\Database\Eloquent\ModelNotFoundException` will be thrown:
- $flight = Flight::findOrFail(1);
+```php
+$flight = Flight::findOrFail(1);
- $flight = Flight::where('legs', '>', 3)->firstOrFail();
+$flight = Flight::where('legs', '>', 3)->firstOrFail();
+```
If the `ModelNotFoundException` is not caught, a 404 HTTP response is automatically sent back to the client:
- use App\Models\Flight;
+```php
+use App\Models\Flight;
- Route::get('/api/flights/{id}', function ($id) {
- return Flight::findOrFail($id);
- });
+Route::get('/api/flights/{id}', function (string $id) {
+ return Flight::findOrFail($id);
+});
+```
-### Retrieving Or Creating Models
+### Retrieving or Creating Models
-The `firstOrCreate` method will attempt to locate a database record using the given column / value pairs. If the model can not be found in the database, a record will be inserted with the attributes resulting from merging the first array argument with the optional second array argument:
+The `firstOrCreate` method will attempt to locate a database record using the given column / value pairs. If the model cannot be found in the database, a record will be inserted with the attributes resulting from merging the first array argument with the optional second array argument.
The `firstOrNew` method, like `firstOrCreate`, will attempt to locate a record in the database matching the given attributes. However, if a model is not found, a new model instance will be returned. Note that the model returned by `firstOrNew` has not yet been persisted to the database. You will need to manually call the `save` method to persist it:
- use App\Models\Flight;
-
- // Retrieve flight by name or create it if it doesn't exist...
- $flight = Flight::firstOrCreate([
- 'name' => 'London to Paris'
- ]);
-
- // Retrieve flight by name or create it with the name, delayed, and arrival_time attributes...
- $flight = Flight::firstOrCreate(
- ['name' => 'London to Paris'],
- ['delayed' => 1, 'arrival_time' => '11:30']
- );
-
- // Retrieve flight by name or instantiate a new Flight instance...
- $flight = Flight::firstOrNew([
- 'name' => 'London to Paris'
- ]);
+```php
+use App\Models\Flight;
- // Retrieve flight by name or instantiate with the name, delayed, and arrival_time attributes...
- $flight = Flight::firstOrNew(
- ['name' => 'Tokyo to Sydney'],
- ['delayed' => 1, 'arrival_time' => '11:30']
- );
+// Retrieve flight by name or create it if it doesn't exist...
+$flight = Flight::firstOrCreate([
+ 'name' => 'London to Paris'
+]);
+
+// Retrieve flight by name or create it with the name, delayed, and arrival_time attributes...
+$flight = Flight::firstOrCreate(
+ ['name' => 'London to Paris'],
+ ['delayed' => 1, 'arrival_time' => '11:30']
+);
+
+// Retrieve flight by name or instantiate a new Flight instance...
+$flight = Flight::firstOrNew([
+ 'name' => 'London to Paris'
+]);
+
+// Retrieve flight by name or instantiate with the name, delayed, and arrival_time attributes...
+$flight = Flight::firstOrNew(
+ ['name' => 'Tokyo to Sydney'],
+ ['delayed' => 1, 'arrival_time' => '11:30']
+);
+```
### Retrieving Aggregates
When interacting with Eloquent models, you may also use the `count`, `sum`, `max`, and other [aggregate methods](/docs/{{version}}/queries#aggregates) provided by the Laravel [query builder](/docs/{{version}}/queries). As you might expect, these methods return a scalar value instead of an Eloquent model instance:
- $count = Flight::where('active', 1)->count();
+```php
+$count = Flight::where('active', 1)->count();
- $max = Flight::where('active', 1)->max('price');
+$max = Flight::where('active', 1)->max('price');
+```
-## Inserting & Updating Models
+## Inserting and Updating Models
### Inserts
Of course, when using Eloquent, we don't only need to retrieve models from the database. We also need to insert new records. Thankfully, Eloquent makes it simple. To insert a new record into the database, you should instantiate a new model instance and set attributes on the model. Then, call the `save` method on the model instance:
- name = $request->name;
-
- $flight->save();
- }
+ // Validate the request...
+
+ $flight = new Flight;
+
+ $flight->name = $request->name;
+
+ $flight->save();
+
+ return redirect('/flights');
}
+}
+```
In this example, we assign the `name` field from the incoming HTTP request to the `name` attribute of the `App\Models\Flight` model instance. When we call the `save` method, a record will be inserted into the database. The model's `created_at` and `updated_at` timestamps will automatically be set when the `save` method is called, so there is no need to set them manually.
Alternatively, you may use the `create` method to "save" a new model using a single PHP statement. The inserted model instance will be returned to you by the `create` method:
- use App\Models\Flight;
+```php
+use App\Models\Flight;
- $flight = Flight::create([
- 'name' => 'London to Paris',
- ]);
+$flight = Flight::create([
+ 'name' => 'London to Paris',
+]);
+```
However, before using the `create` method, you will need to specify either a `fillable` or `guarded` property on your model class. These properties are required because all Eloquent models are protected against mass assignment vulnerabilities by default. To learn more about mass assignment, please consult the [mass assignment documentation](#mass-assignment).
@@ -592,100 +773,168 @@ However, before using the `create` method, you will need to specify either a `fi
The `save` method may also be used to update models that already exist in the database. To update a model, you should retrieve it and set any attributes you wish to update. Then, you should call the model's `save` method. Again, the `updated_at` timestamp will automatically be updated, so there is no need to manually set its value:
- use App\Models\Flight;
+```php
+use App\Models\Flight;
+
+$flight = Flight::find(1);
+
+$flight->name = 'Paris to London';
+
+$flight->save();
+```
+
+Occasionally, you may need to update an existing model or create a new model if no matching model exists. Like the `firstOrCreate` method, the `updateOrCreate` method persists the model, so there's no need to manually call the `save` method.
+
+In the example below, if a flight exists with a `departure` location of `Oakland` and a `destination` location of `San Diego`, its `price` and `discounted` columns will be updated. If no such flight exists, a new flight will be created which has the attributes resulting from merging the first argument array with the second argument array:
+
+```php
+$flight = Flight::updateOrCreate(
+ ['departure' => 'Oakland', 'destination' => 'San Diego'],
+ ['price' => 99, 'discounted' => 1]
+);
+```
- $flight = Flight::find(1);
+When using methods such as `firstOrCreate` or `updateOrCreate`, you may not know whether a new model has been created or an existing one has been updated. The `wasRecentlyCreated` property indicates if the model was created during its current lifecycle:
- $flight->name = 'Paris to London';
+```php
+$flight = Flight::updateOrCreate(
+ // ...
+);
- $flight->save();
+if ($flight->wasRecentlyCreated) {
+ // New flight record was inserted...
+}
+```
#### Mass Updates
Updates can also be performed against models that match a given query. In this example, all flights that are `active` and have a `destination` of `San Diego` will be marked as delayed:
- Flight::where('active', 1)
- ->where('destination', 'San Diego')
- ->update(['delayed' => 1]);
+```php
+Flight::where('active', 1)
+ ->where('destination', 'San Diego')
+ ->update(['delayed' => 1]);
+```
The `update` method expects an array of column and value pairs representing the columns that should be updated. The `update` method returns the number of affected rows.
-> {note} When issuing a mass update via Eloquent, the `saving`, `saved`, `updating`, and `updated` model events will not be fired for the updated models. This is because the models are never actually retrieved when issuing a mass update.
+> [!WARNING]
+> When issuing a mass update via Eloquent, the `saving`, `saved`, `updating`, and `updated` model events will not be fired for the updated models. This is because the models are never actually retrieved when issuing a mass update.
#### Examining Attribute Changes
Eloquent provides the `isDirty`, `isClean`, and `wasChanged` methods to examine the internal state of your model and determine how its attributes have changed from when the model was originally retrieved.
-The `isDirty` method determines if any of the model's attributes have been changed since the model was retrieved. You may pass a specific attribute name or an array of attributes to the `isDirty` method to determine if any of the attributes are "dirty". The `isClean` will determine if an attribute has remained unchanged since the model was retrieved. This method also accepts an optional attribute argument:
+The `isDirty` method determines if any of the model's attributes have been changed since the model was retrieved. You may pass a specific attribute name or an array of attributes to the `isDirty` method to determine if any of the attributes are "dirty". The `isClean` method will determine if an attribute has remained unchanged since the model was retrieved. This method also accepts an optional attribute argument:
- use App\Models\User;
+```php
+use App\Models\User;
- $user = User::create([
- 'first_name' => 'Taylor',
- 'last_name' => 'Otwell',
- 'title' => 'Developer',
- ]);
+$user = User::create([
+ 'first_name' => 'Taylor',
+ 'last_name' => 'Otwell',
+ 'title' => 'Developer',
+]);
- $user->title = 'Painter';
+$user->title = 'Painter';
- $user->isDirty(); // true
- $user->isDirty('title'); // true
- $user->isDirty('first_name'); // false
- $user->isDirty(['first_name', 'title']); // true
+$user->isDirty(); // true
+$user->isDirty('title'); // true
+$user->isDirty('first_name'); // false
+$user->isDirty(['first_name', 'title']); // true
- $user->isClean(); // false
- $user->isClean('title'); // false
- $user->isClean('first_name'); // true
- $user->isClean(['first_name', 'title']); // false
+$user->isClean(); // false
+$user->isClean('title'); // false
+$user->isClean('first_name'); // true
+$user->isClean(['first_name', 'title']); // false
- $user->save();
+$user->save();
- $user->isDirty(); // false
- $user->isClean(); // true
+$user->isDirty(); // false
+$user->isClean(); // true
+```
The `wasChanged` method determines if any attributes were changed when the model was last saved within the current request cycle. If needed, you may pass an attribute name to see if a particular attribute was changed:
- $user = User::create([
- 'first_name' => 'Taylor',
- 'last_name' => 'Otwell',
- 'title' => 'Developer',
- ]);
+```php
+$user = User::create([
+ 'first_name' => 'Taylor',
+ 'last_name' => 'Otwell',
+ 'title' => 'Developer',
+]);
- $user->title = 'Painter';
+$user->title = 'Painter';
- $user->save();
+$user->save();
- $user->wasChanged(); // true
- $user->wasChanged('title'); // true
- $user->wasChanged(['title', 'slug']); // true
- $user->wasChanged('first_name'); // false
- $user->wasChanged(['first_name', 'title']); // true
+$user->wasChanged(); // true
+$user->wasChanged('title'); // true
+$user->wasChanged(['title', 'slug']); // true
+$user->wasChanged('first_name'); // false
+$user->wasChanged(['first_name', 'title']); // true
+```
The `getOriginal` method returns an array containing the original attributes of the model regardless of any changes to the model since it was retrieved. If needed, you may pass a specific attribute name to get the original value of a particular attribute:
- $user = User::find(1);
+```php
+$user = User::find(1);
+
+$user->name; // John
+$user->email; // john@example.com
+
+$user->name = 'Jack';
+$user->name; // Jack
+
+$user->getOriginal('name'); // John
+$user->getOriginal(); // Array of original attributes...
+```
+
+The `getChanges` method returns an array containing the attributes that changed when the model was last saved, while the `getPrevious` method returns an array containing the original attribute values before the model was last saved:
+
+```php
+$user = User::find(1);
+
+$user->name; // John
+$user->email; // john@example.com
- $user->name; // John
- $user->email; // john@example.com
+$user->update([
+ 'name' => 'Jack',
+ 'email' => 'jack@example.com',
+]);
- $user->name = "Jack";
- $user->name; // Jack
+$user->getChanges();
- $user->getOriginal('name'); // John
- $user->getOriginal(); // Array of original attributes...
+/*
+ [
+ 'name' => 'Jack',
+ 'email' => 'jack@example.com',
+ ]
+*/
+
+$user->getPrevious();
+
+/*
+ [
+ 'name' => 'John',
+ 'email' => 'john@example.com',
+ ]
+*/
+```
### Mass Assignment
You may use the `create` method to "save" a new model using a single PHP statement. The inserted model instance will be returned to you by the method:
- use App\Models\Flight;
+```php
+use App\Models\Flight;
- $flight = Flight::create([
- 'name' => 'London to Paris',
- ]);
+$flight = Flight::create([
+ 'name' => 'London to Paris',
+]);
+```
However, before using the `create` method, you will need to specify either a `fillable` or `guarded` property on your model class. These properties are required because all Eloquent models are protected against mass assignment vulnerabilities by default.
@@ -693,181 +942,239 @@ A mass assignment vulnerability occurs when a user passes an unexpected HTTP req
So, to get started, you should define which model attributes you want to make mass assignable. You may do this using the `$fillable` property on the model. For example, let's make the `name` attribute of our `Flight` model mass assignable:
-
+ */
+ protected $fillable = ['name'];
+}
+```
Once you have specified which attributes are mass assignable, you may use the `create` method to insert a new record in the database. The `create` method returns the newly created model instance:
- $flight = Flight::create(['name' => 'London to Paris']);
+```php
+$flight = Flight::create(['name' => 'London to Paris']);
+```
If you already have a model instance, you may use the `fill` method to populate it with an array of attributes:
- $flight->fill(['name' => 'Amsterdam to Frankfurt']);
+```php
+$flight->fill(['name' => 'Amsterdam to Frankfurt']);
+```
-#### Mass Assignment & JSON Columns
+#### Mass Assignment and JSON Columns
When assigning JSON columns, each column's mass assignable key must be specified in your model's `$fillable` array. For security, Laravel does not support updating nested JSON attributes when using the `guarded` property:
- /**
- * The attributes that are mass assignable.
- *
- * @var array
- */
- protected $fillable = [
- 'options->enabled',
- ];
+```php
+/**
+ * The attributes that are mass assignable.
+ *
+ * @var array
+ */
+protected $fillable = [
+ 'options->enabled',
+];
+```
#### Allowing Mass Assignment
If you would like to make all of your attributes mass assignable, you may define your model's `$guarded` property as an empty array. If you choose to unguard your model, you should take special care to always hand-craft the arrays passed to Eloquent's `fill`, `create`, and `update` methods:
- /**
- * The attributes that aren't mass assignable.
- *
- * @var array
- */
- protected $guarded = [];
+```php
+/**
+ * The attributes that aren't mass assignable.
+ *
+ * @var array|bool
+ */
+protected $guarded = [];
+```
-
-### Upserts
+
+#### Mass Assignment Exceptions
-Occasionally, you may need to update an existing model or create a new model if no matching model exists. Like the `firstOrCreate` method, the `updateOrCreate` method persists the model, so there's no need to manually call the `save` method.
+By default, attributes that are not included in the `$fillable` array are silently discarded when performing mass-assignment operations. In production, this is expected behavior; however, during local development it can lead to confusion as to why model changes are not taking effect.
-In the example below, if a flight exists with a `departure` location of `Oakland` and a `destination` location of `San Diego`, its `price` and `discounted` columns will be updated. If no such flight exists, a new flight will be created which has the attributes resulting from merging the first argument array with the second argument array:
+If you wish, you may instruct Laravel to throw an exception when attempting to fill an unfillable attribute by invoking the `preventSilentlyDiscardingAttributes` method. Typically, this method should be invoked in the `boot` method of your application's `AppServiceProvider` class:
- $flight = Flight::updateOrCreate(
- ['departure' => 'Oakland', 'destination' => 'San Diego'],
- ['price' => 99, 'discounted' => 1]
- );
+```php
+use Illuminate\Database\Eloquent\Model;
+
+/**
+ * Bootstrap any application services.
+ */
+public function boot(): void
+{
+ Model::preventSilentlyDiscardingAttributes($this->app->isLocal());
+}
+```
-If you would like to perform multiple "upserts" in a single query, then you should use the `upsert` method instead. The method's first argument consists of the values to insert or update, while the second argument lists the column(s) that uniquely identify records within the associated table. The method's third and final argument is an array of the columns that should be updated if a matching record already exists in the database. The `upsert` method will automatically set the `created_at` and `updated_at` timestamps if timestamps are enabled on the model:
+
+### Upserts
+
+Eloquent's `upsert` method may be used to update or create records in a single, atomic operation. The method's first argument consists of the values to insert or update, while the second argument lists the column(s) that uniquely identify records within the associated table. The method's third and final argument is an array of the columns that should be updated if a matching record already exists in the database. The `upsert` method will automatically set the `created_at` and `updated_at` timestamps if timestamps are enabled on the model:
- Flight::upsert([
- ['departure' => 'Oakland', 'destination' => 'San Diego', 'price' => 99],
- ['departure' => 'Chicago', 'destination' => 'New York', 'price' => 150]
- ], ['departure', 'destination'], ['price']);
+```php
+Flight::upsert([
+ ['departure' => 'Oakland', 'destination' => 'San Diego', 'price' => 99],
+ ['departure' => 'Chicago', 'destination' => 'New York', 'price' => 150]
+], uniqueBy: ['departure', 'destination'], update: ['price']);
+```
+
+> [!WARNING]
+> All databases except SQL Server require the columns in the second argument of the `upsert` method to have a "primary" or "unique" index. In addition, the MariaDB and MySQL database drivers ignore the second argument of the `upsert` method and always use the "primary" and "unique" indexes of the table to detect existing records.
## Deleting Models
To delete a model, you may call the `delete` method on the model instance:
- use App\Models\Flight;
+```php
+use App\Models\Flight;
- $flight = Flight::find(1);
+$flight = Flight::find(1);
- $flight->delete();
+$flight->delete();
+```
-You may call the `truncate` method to delete all of the model's associated database records. The `truncate` operation will also reset any auto-incrementing IDs on the model's associated table:
+
+#### Deleting an Existing Model by its Primary Key
- Flight::truncate();
+In the example above, we are retrieving the model from the database before calling the `delete` method. However, if you know the primary key of the model, you may delete the model without explicitly retrieving it by calling the `destroy` method. In addition to accepting the single primary key, the `destroy` method will accept multiple primary keys, an array of primary keys, or a [collection](/docs/{{version}}/collections) of primary keys:
-
-#### Deleting An Existing Model By Its Primary Key
+```php
+Flight::destroy(1);
-In the example above, we are retrieving the model from the database before calling the `delete` method. However, if you know the primary key of the model, you may delete the model without explicitly retrieving it by calling the `destroy` method. In addition to accepting the single primary key, the `destroy` method will accept multiple primary keys, an array of primary keys, or a [collection](/docs/{{version}}/collections) of primary keys:
+Flight::destroy(1, 2, 3);
- Flight::destroy(1);
+Flight::destroy([1, 2, 3]);
- Flight::destroy(1, 2, 3);
+Flight::destroy(collect([1, 2, 3]));
+```
- Flight::destroy([1, 2, 3]);
+If you are utilizing [soft deleting models](#soft-deleting), you may permanently delete models via the `forceDestroy` method:
- Flight::destroy(collect([1, 2, 3]));
+```php
+Flight::forceDestroy(1);
+```
-> {note} The `destroy` method loads each model individually and calls the `delete` method so that the `deleting` and `deleted` events are properly dispatched for each model.
+> [!WARNING]
+> The `destroy` method loads each model individually and calls the `delete` method so that the `deleting` and `deleted` events are properly dispatched for each model.
#### Deleting Models Using Queries
Of course, you may build an Eloquent query to delete all models matching your query's criteria. In this example, we will delete all flights that are marked as inactive. Like mass updates, mass deletes will not dispatch model events for the models that are deleted:
- $deleted = Flight::where('active', 0)->delete();
+```php
+$deleted = Flight::where('active', 0)->delete();
+```
+
+To delete all models in a table, you should execute a query without adding any conditions:
-> {note} When executing a mass delete statement via Eloquent, the `deleting` and `deleted` model events will not be dispatched for the deleted models. This is because the models are never actually retrieved when executing the delete statement.
+```php
+$deleted = Flight::query()->delete();
+```
+
+> [!WARNING]
+> When executing a mass delete statement via Eloquent, the `deleting` and `deleted` model events will not be dispatched for the deleted models. This is because the models are never actually retrieved when executing the delete statement.
### Soft Deleting
In addition to actually removing records from your database, Eloquent can also "soft delete" models. When models are soft deleted, they are not actually removed from your database. Instead, a `deleted_at` attribute is set on the model indicating the date and time at which the model was "deleted". To enable soft deletes for a model, add the `Illuminate\Database\Eloquent\SoftDeletes` trait to the model:
- {tip} The `SoftDeletes` trait will automatically cast the `deleted_at` attribute to a `DateTime` / `Carbon` instance for you.
+> [!NOTE]
+> The `SoftDeletes` trait will automatically cast the `deleted_at` attribute to a `DateTime` / `Carbon` instance for you.
You should also add the `deleted_at` column to your database table. The Laravel [schema builder](/docs/{{version}}/migrations) contains a helper method to create this column:
- use Illuminate\Database\Schema\Blueprint;
- use Illuminate\Support\Facades\Schema;
+```php
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
- Schema::table('flights', function (Blueprint $table) {
- $table->softDeletes();
- });
+Schema::table('flights', function (Blueprint $table) {
+ $table->softDeletes();
+});
- Schema::table('flights', function (Blueprint $table) {
- $table->dropSoftDeletes();
- });
+Schema::table('flights', function (Blueprint $table) {
+ $table->dropSoftDeletes();
+});
+```
Now, when you call the `delete` method on the model, the `deleted_at` column will be set to the current date and time. However, the model's database record will be left in the table. When querying a model that uses soft deletes, the soft deleted models will automatically be excluded from all query results.
To determine if a given model instance has been soft deleted, you may use the `trashed` method:
- if ($flight->trashed()) {
- //
- }
+```php
+if ($flight->trashed()) {
+ // ...
+}
+```
#### Restoring Soft Deleted Models
Sometimes you may wish to "un-delete" a soft deleted model. To restore a soft deleted model, you may call the `restore` method on a model instance. The `restore` method will set the model's `deleted_at` column to `null`:
- $flight->restore();
+```php
+$flight->restore();
+```
You may also use the `restore` method in a query to restore multiple models. Again, like other "mass" operations, this will not dispatch any model events for the models that are restored:
- Flight::withTrashed()
- ->where('airline_id', 1)
- ->restore();
+```php
+Flight::withTrashed()
+ ->where('airline_id', 1)
+ ->restore();
+```
The `restore` method may also be used when building [relationship](/docs/{{version}}/eloquent-relationships) queries:
- $flight->history()->restore();
+```php
+$flight->history()->restore();
+```
#### Permanently Deleting Models
Sometimes you may need to truly remove a model from your database. You may use the `forceDelete` method to permanently remove a soft deleted model from the database table:
- $flight->forceDelete();
+```php
+$flight->forceDelete();
+```
You may also use the `forceDelete` method when building Eloquent relationship queries:
- $flight->history()->forceDelete();
+```php
+$flight->history()->forceDelete();
+```
### Querying Soft Deleted Models
@@ -877,88 +1184,94 @@ You may also use the `forceDelete` method when building Eloquent relationship qu
As noted above, soft deleted models will automatically be excluded from query results. However, you may force soft deleted models to be included in a query's results by calling the `withTrashed` method on the query:
- use App\Models\Flight;
+```php
+use App\Models\Flight;
- $flights = Flight::withTrashed()
- ->where('account_id', 1)
- ->get();
+$flights = Flight::withTrashed()
+ ->where('account_id', 1)
+ ->get();
+```
The `withTrashed` method may also be called when building a [relationship](/docs/{{version}}/eloquent-relationships) query:
- $flight->history()->withTrashed()->get();
+```php
+$flight->history()->withTrashed()->get();
+```
#### Retrieving Only Soft Deleted Models
The `onlyTrashed` method will retrieve **only** soft deleted models:
- $flights = Flight::onlyTrashed()
- ->where('airline_id', 1)
- ->get();
+```php
+$flights = Flight::onlyTrashed()
+ ->where('airline_id', 1)
+ ->get();
+```
## Pruning Models
Sometimes you may want to periodically delete models that are no longer needed. To accomplish this, you may add the `Illuminate\Database\Eloquent\Prunable` or `Illuminate\Database\Eloquent\MassPrunable` trait to the models you would like to periodically prune. After adding one of the traits to the model, implement a `prunable` method which returns an Eloquent query builder that resolves the models that are no longer needed:
- subMonth());
- }
- }
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Prunable;
-When marking models as `Prunable`, you may also define a `pruning` method on the model. This method will be called before the model is deleted. This method can be useful for deleting any additional resources associated with the model, such as stored files, before the model is permanently removed from the database:
+class Flight extends Model
+{
+ use Prunable;
/**
- * Prepare the model for pruning.
- *
- * @return void
+ * Get the prunable model query.
*/
- protected function pruning()
+ public function prunable(): Builder
{
- //
+ return static::where('created_at', '<=', now()->subMonth());
}
+}
+```
-After configuring your prunable model, you should schedule the `model:prune` Artisan command in your application's `App\Console\Kernel` class. You are free to choose the appropriate interval at which this command should be run:
+When marking models as `Prunable`, you may also define a `pruning` method on the model. This method will be called before the model is deleted. This method can be useful for deleting any additional resources associated with the model, such as stored files, before the model is permanently removed from the database:
- /**
- * Define the application's command schedule.
- *
- * @param \Illuminate\Console\Scheduling\Schedule $schedule
- * @return void
- */
- protected function schedule(Schedule $schedule)
- {
- $schedule->command('model:prune')->daily();
- }
+```php
+/**
+ * Prepare the model for pruning.
+ */
+protected function pruning(): void
+{
+ // ...
+}
+```
+
+After configuring your prunable model, you should schedule the `model:prune` Artisan command in your application's `routes/console.php` file. You are free to choose the appropriate interval at which this command should be run:
+
+```php
+use Illuminate\Support\Facades\Schedule;
+
+Schedule::command('model:prune')->daily();
+```
Behind the scenes, the `model:prune` command will automatically detect "Prunable" models within your application's `app/Models` directory. If your models are in a different location, you may use the `--model` option to specify the model class names:
- $schedule->command('model:prune', [
- '--model' => [Address::class, Flight::class],
- ])->daily();
+```php
+Schedule::command('model:prune', [
+ '--model' => [Address::class, Flight::class],
+])->daily();
+```
If you wish to exclude certain models from being pruned while pruning all other detected models, you may use the `--except` option:
- $schedule->command('model:prune', [
- '--except' => [Address::class, Flight::class],
- ])->daily();
+```php
+Schedule::command('model:prune', [
+ '--except' => [Address::class, Flight::class],
+])->daily();
+```
You may test your `prunable` query by executing the `model:prune` command with the `--pretend` option. When pretending, the `model:prune` command will simply report how many records would be pruned if the command were to actually run:
@@ -966,69 +1279,75 @@ You may test your `prunable` query by executing the `model:prune` command with t
php artisan model:prune --pretend
```
-> {note} Soft deleting models will be permanently deleted (`forceDelete`) if they match the prunable query.
+> [!WARNING]
+> Soft deleting models will be permanently deleted (`forceDelete`) if they match the prunable query.
#### Mass Pruning
When models are marked with the `Illuminate\Database\Eloquent\MassPrunable` trait, models are deleted from the database using mass-deletion queries. Therefore, the `pruning` method will not be invoked, nor will the `deleting` and `deleted` model events be dispatched. This is because the models are never actually retrieved before deletion, thus making the pruning process much more efficient:
- subMonth());
- }
+ return static::where('created_at', '<=', now()->subMonth());
}
+}
+```
## Replicating Models
You may create an unsaved copy of an existing model instance using the `replicate` method. This method is particularly useful when you have model instances that share many of the same attributes:
- use App\Models\Address;
+```php
+use App\Models\Address;
- $shipping = Address::create([
- 'type' => 'shipping',
- 'line_1' => '123 Example Street',
- 'city' => 'Victorville',
- 'state' => 'CA',
- 'postcode' => '90001',
- ]);
+$shipping = Address::create([
+ 'type' => 'shipping',
+ 'line_1' => '123 Example Street',
+ 'city' => 'Victorville',
+ 'state' => 'CA',
+ 'postcode' => '90001',
+]);
- $billing = $shipping->replicate()->fill([
- 'type' => 'billing'
- ]);
+$billing = $shipping->replicate()->fill([
+ 'type' => 'billing'
+]);
- $billing->save();
+$billing->save();
+```
To exclude one or more attributes from being replicated to the new model, you may pass an array to the `replicate` method:
- $flight = Flight::create([
- 'destination' => 'LAX',
- 'origin' => 'LHR',
- 'last_flown' => '2020-03-04 11:00:00',
- 'last_pilot_id' => 747,
- ]);
-
- $flight = $flight->replicate([
- 'last_flown',
- 'last_pilot_id'
- ]);
+```php
+$flight = Flight::create([
+ 'destination' => 'LAX',
+ 'origin' => 'LHR',
+ 'last_flown' => '2020-03-04 11:00:00',
+ 'last_pilot_id' => 747,
+]);
+
+$flight = $flight->replicate([
+ 'last_flown',
+ 'last_pilot_id'
+]);
+```
## Query Scopes
@@ -1038,62 +1357,85 @@ To exclude one or more attributes from being replicated to the new model, you ma
Global scopes allow you to add constraints to all queries for a given model. Laravel's own [soft delete](#soft-deleting) functionality utilizes global scopes to only retrieve "non-deleted" models from the database. Writing your own global scopes can provide a convenient, easy way to make sure every query for a given model receives certain constraints.
+
+#### Generating Scopes
+
+To generate a new global scope, you may invoke the `make:scope` Artisan command, which will place the generated scope in your application's `app/Models/Scopes` directory:
+
+```shell
+php artisan make:scope AncientScope
+```
+
#### Writing Global Scopes
-Writing a global scope is simple. First, define a class that implements the `Illuminate\Database\Eloquent\Scope` interface. Laravel does not have a conventional location where you should place scope classes, so you are free to place this class in any directory that you wish.
+Writing a global scope is simple. First, use the `make:scope` command to generate a class that implements the `Illuminate\Database\Eloquent\Scope` interface. The `Scope` interface requires you to implement one method: `apply`. The `apply` method may add `where` constraints or other types of clauses to the query as needed:
-The `Scope` interface requires you to implement one method: `apply`. The `apply` method may add `where` constraints or other types of clauses to the query as needed:
-
- where('created_at', '<', now()->subYears(2000));
- }
+ $builder->where('created_at', '<', now()->subYears(2000));
}
+}
+```
-> {tip} If your global scope is adding columns to the select clause of the query, you should use the `addSelect` method instead of `select`. This will prevent the unintentional replacement of the query's existing select clause.
+> [!NOTE]
+> If your global scope is adding columns to the select clause of the query, you should use the `addSelect` method instead of `select`. This will prevent the unintentional replacement of the query's existing select clause.
#### Applying Global Scopes
-To assign a global scope to a model, you should override the model's `booted` method and invoke the model's `addGlobalScope` method. The `addGlobalScope` method accepts an instance of your scope as its only argument:
+To assign a global scope to a model, you may simply place the `ScopedBy` attribute on the model:
+
+```php
+where('created_at', '<', now()->subYears(2000));
- });
- }
+ static::addGlobalScope('ancient', function (Builder $builder) {
+ $builder->where('created_at', '<', now()->subYears(2000));
+ });
}
+}
+```
#### Removing Global Scopes
If you would like to remove a global scope for a given query, you may use the `withoutGlobalScope` method. This method accepts the class name of the global scope as its only argument:
- User::withoutGlobalScope(AncientScope::class)->get();
+```php
+User::withoutGlobalScope(AncientScope::class)->get();
+```
Or, if you defined the global scope using a closure, you should pass the string name that you assigned to the global scope:
- User::withoutGlobalScope('ancient')->get();
-
-If you would like to remove several or even all of the query's global scopes, you may use the `withoutGlobalScopes` method:
+```php
+User::withoutGlobalScope('ancient')->get();
+```
- // Remove all of the global scopes...
- User::withoutGlobalScopes()->get();
+If you would like to remove several or even all of the query's global scopes, you may use the `withoutGlobalScopes` and `withoutGlobalScopesExcept` methods:
- // Remove some of the global scopes...
- User::withoutGlobalScopes([
- FirstScope::class, SecondScope::class
- ])->get();
+```php
+// Remove all of the global scopes...
+User::withoutGlobalScopes()->get();
+
+// Remove some of the global scopes...
+User::withoutGlobalScopes([
+ FirstScope::class, SecondScope::class
+])->get();
+
+// Remove all global scopes except the given ones...
+User::withoutGlobalScopesExcept([
+ SecondScope::class,
+])->get();
+```
### Local Scopes
-Local scopes allow you to define common sets of query constraints that you may easily re-use throughout your application. For example, you may need to frequently retrieve all users that are considered "popular". To define a scope, prefix an Eloquent model method with `scope`.
+Local scopes allow you to define common sets of query constraints that you may easily re-use throughout your application. For example, you may need to frequently retrieve all users that are considered "popular". To define a scope, add the `Scope` attribute to an Eloquent method.
Scopes should always return the same query builder instance or `void`:
- where('votes', '>', 100);
+ }
- class User extends Model
+ /**
+ * Scope a query to only include active users.
+ */
+ #[Scope]
+ protected function active(Builder $query): void
{
- /**
- * Scope a query to only include popular users.
- *
- * @param \Illuminate\Database\Eloquent\Builder $query
- * @return \Illuminate\Database\Eloquent\Builder
- */
- public function scopePopular($query)
- {
- return $query->where('votes', '>', 100);
- }
-
- /**
- * Scope a query to only include active users.
- *
- * @param \Illuminate\Database\Eloquent\Builder $query
- * @return void
- */
- public function scopeActive($query)
- {
- $query->where('active', 1);
- }
+ $query->where('active', 1);
}
+}
+```
-#### Utilizing A Local Scope
+#### Utilizing a Local Scope
-Once the scope has been defined, you may call the scope methods when querying the model. However, you should not include the `scope` prefix when calling the method. You can even chain calls to various scopes:
+Once the scope has been defined, you may call the scope methods when querying the model. You can even chain calls to various scopes:
- use App\Models\User;
+```php
+use App\Models\User;
- $users = User::popular()->active()->orderBy('created_at')->get();
+$users = User::popular()->active()->orderBy('created_at')->get();
+```
Combining multiple Eloquent model scopes via an `or` query operator may require the use of closures to achieve the correct [logical grouping](/docs/{{version}}/queries#logical-grouping):
- $users = User::popular()->orWhere(function (Builder $query) {
- $query->active();
- })->get();
+```php
+$users = User::popular()->orWhere(function (Builder $query) {
+ $query->active();
+})->get();
+```
However, since this can be cumbersome, Laravel provides a "higher order" `orWhere` method that allows you to fluently chain scopes together without the use of closures:
- $users = App\Models\User::popular()->orWhere->active()->get();
+```php
+$users = User::popular()->orWhere->active()->get();
+```
#### Dynamic Scopes
Sometimes you may wish to define a scope that accepts parameters. To get started, just add your additional parameters to your scope method's signature. Scope parameters should be defined after the `$query` parameter:
- where('type', $type);
- }
+ $query->where('type', $type);
}
+}
+```
Once the expected arguments have been added to your scope method's signature, you may pass the arguments when calling the scope:
- $users = User::ofType('admin')->get();
+```php
+$users = User::ofType('admin')->get();
+```
+
+
+### Pending Attributes
+
+If you would like to use scopes to create models that have the same attributes as those used to constrain the scope, you may use the `withAttributes` method when building the scope query:
+
+```php
+withAttributes([
+ 'hidden' => true,
+ ]);
+ }
+}
+```
+
+The `withAttributes` method will add `where` conditions to the query using the given attributes, and it will also add the given attributes to any models created via the scope:
+
+```php
+$draft = Post::draft()->create(['title' => 'In Progress']);
+
+$draft->hidden; // true
+```
+
+To instruct the `withAttributes` method to not add `where` conditions to the query, you may set the `asConditions` argument to `false`:
+
+```php
+$query->withAttributes([
+ 'hidden' => true,
+], asConditions: false);
+```
## Comparing Models
Sometimes you may need to determine if two models are the "same" or not. The `is` and `isNot` methods may be used to quickly verify two models have the same primary key, table, and database connection or not:
- if ($post->is($anotherPost)) {
- //
- }
+```php
+if ($post->is($anotherPost)) {
+ // ...
+}
- if ($post->isNot($anotherPost)) {
- //
- }
+if ($post->isNot($anotherPost)) {
+ // ...
+}
+```
The `is` and `isNot` methods are also available when using the `belongsTo`, `hasOne`, `morphTo`, and `morphOne` [relationships](/docs/{{version}}/eloquent-relationships). This method is particularly helpful when you would like to compare a related model without issuing a query to retrieve that model:
- if ($post->author()->is($user)) {
- //
- }
+```php
+if ($post->author()->is($user)) {
+ // ...
+}
+```
## Events
-> {tip} Want to broadcast your Eloquent events directly to your client-side application? Check out Laravel's [model event broadcasting](/docs/{{version}}/broadcasting#model-broadcasting).
+> [!NOTE]
+> Want to broadcast your Eloquent events directly to your client-side application? Check out Laravel's [model event broadcasting](/docs/{{version}}/broadcasting#model-broadcasting).
-Eloquent models dispatch several events, allowing you to hook into the following moments in a model's lifecycle: `retrieved`, `creating`, `created`, `updating`, `updated`, `saving`, `saved`, `deleting`, `deleted`, `restoring`, `restored`, and `replicating`.
+Eloquent models dispatch several events, allowing you to hook into the following moments in a model's lifecycle: `retrieved`, `creating`, `created`, `updating`, `updated`, `saving`, `saved`, `deleting`, `deleted`, `trashed`, `forceDeleting`, `forceDeleted`, `restoring`, `restored`, and `replicating`.
The `retrieved` event will dispatch when an existing model is retrieved from the database. When a new model is saved for the first time, the `creating` and `created` events will dispatch. The `updating` / `updated` events will dispatch when an existing model is modified and the `save` method is called. The `saving` / `saved` events will dispatch when a model is created or updated - even if the model's attributes have not been changed. Event names ending with `-ing` are dispatched before any changes to the model are persisted, while events ending with `-ed` are dispatched after the changes to the model are persisted.
To start listening to model events, define a `$dispatchesEvents` property on your Eloquent model. This property maps various points of the Eloquent model's lifecycle to your own [event classes](/docs/{{version}}/events). Each model event class should expect to receive an instance of the affected model via its constructor:
- UserSaved::class,
- 'deleted' => UserDeleted::class,
- ];
- }
+class User extends Authenticatable
+{
+ use Notifiable;
+
+ /**
+ * The event map for the model.
+ *
+ * @var array
+ */
+ protected $dispatchesEvents = [
+ 'saved' => UserSaved::class,
+ 'deleted' => UserDeleted::class,
+ ];
+}
+```
After defining and mapping your Eloquent events, you may use [event listeners](/docs/{{version}}/events#defining-listeners) to handle the events.
-> {note} When issuing a mass update or delete query via Eloquent, the `saved`, `updated`, `deleting`, and `deleted` model events will not be dispatched for the affected models. This is because the models are never actually retrieved when performing mass updates or deletes.
+> [!WARNING]
+> When issuing a mass update or delete query via Eloquent, the `saved`, `updated`, `deleting`, and `deleted` model events will not be dispatched for the affected models. This is because the models are never actually retrieved when performing mass updates or deletes.
### Using Closures
Instead of using custom event classes, you may register closures that execute when various model events are dispatched. Typically, you should register these closures in the `booted` method of your model:
-
### Observers
@@ -1339,144 +1757,147 @@ If you are listening for many events on a given model, you may use observers to
php artisan make:observer UserObserver --model=User
```
-This command will place the new observer in your `App/Observers` directory. If this directory does not exist, Artisan will create it for you. Your fresh observer will look like the following:
+This command will place the new observer in your `app/Observers` directory. If this directory does not exist, Artisan will create it for you. Your fresh observer will look like the following:
- [UserObserver::class],
- ];
+ public function forceDeleted(User $user): void
+ {
+ // ...
+ }
+}
+```
+
+To register an observer, you may place the `ObservedBy` attribute on the corresponding model:
+
+```php
+use App\Observers\UserObserver;
+use Illuminate\Database\Eloquent\Attributes\ObservedBy;
+
+#[ObservedBy([UserObserver::class])]
+class User extends Authenticatable
+{
+ //
+}
+```
+
+Or, you may manually register an observer by invoking the `observe` method on the model you wish to observe. You may register observers in the `boot` method of your application's `AppServiceProvider` class:
+
+```php
+use App\Models\User;
+use App\Observers\UserObserver;
+
+/**
+ * Bootstrap any application services.
+ */
+public function boot(): void
+{
+ User::observe(UserObserver::class);
+}
+```
-> {tip} There are additional events an observer can listen to, such as `saving` and `retrieved`. These events are described within the [events](#events) documentation.
+> [!NOTE]
+> There are additional events an observer can listen to, such as `saving` and `retrieved`. These events are described within the [events](#events) documentation.
-#### Observers & Database Transactions
+#### Observers and Database Transactions
-When models are being created within a database transaction, you may want to instruct an observer to only execute its event handlers after the database transaction is committed. You may accomplish this by defining an `$afterCommit` property on the observer. If a database transaction is not in progress, the event handlers will execute immediately:
+When models are being created within a database transaction, you may want to instruct an observer to only execute its event handlers after the database transaction is committed. You may accomplish this by implementing the `ShouldHandleEventsAfterCommit` interface on your observer. If a database transaction is not in progress, the event handlers will execute immediately:
-
### Muting Events
You may occasionally need to temporarily "mute" all events fired by a model. You may achieve this using the `withoutEvents` method. The `withoutEvents` method accepts a closure as its only argument. Any code executed within this closure will not dispatch model events, and any value returned by the closure will be returned by the `withoutEvents` method:
- use App\Models\User;
+```php
+use App\Models\User;
- $user = User::withoutEvents(function () use () {
- User::findOrFail(1)->delete();
+$user = User::withoutEvents(function () {
+ User::findOrFail(1)->delete();
- return User::find(2);
- });
+ return User::find(2);
+});
+```
-#### Saving A Single Model Without Events
+#### Saving a Single Model Without Events
Sometimes you may wish to "save" a given model without dispatching any events. You may accomplish this using the `saveQuietly` method:
- $user = User::findOrFail(1);
+```php
+$user = User::findOrFail(1);
+
+$user->name = 'Victoria Faith';
- $user->name = 'Victoria Faith';
+$user->saveQuietly();
+```
+
+You may also "update", "delete", "soft delete", "restore", and "replicate" a given model without dispatching any events:
- $user->saveQuietly();
+```php
+$user->deleteQuietly();
+$user->forceDeleteQuietly();
+$user->restoreQuietly();
+```
diff --git a/encryption.md b/encryption.md
index 42cc97df4d1..6123a6ce6bc 100644
--- a/encryption.md
+++ b/encryption.md
@@ -2,61 +2,80 @@
- [Introduction](#introduction)
- [Configuration](#configuration)
-- [Using The Encrypter](#using-the-encrypter)
+ - [Gracefully Rotating Encryption Keys](#gracefully-rotating-encryption-keys)
+- [Using the Encrypter](#using-the-encrypter)
## Introduction
-Laravel's encryption services provide a simple, convenient interface for encrypting and decrypting text via OpenSSL using AES-256 and AES-128 encryption. All of Laravel's encrypted values are signed using a message authentication code (MAC) so that their underlying value can not be modified or tampered with once encrypted.
+Laravel's encryption services provide a simple, convenient interface for encrypting and decrypting text via OpenSSL using AES-256 and AES-128 encryption. All of Laravel's encrypted values are signed using a message authentication code (MAC) so that their underlying value cannot be modified or tampered with once encrypted.
## Configuration
Before using Laravel's encrypter, you must set the `key` configuration option in your `config/app.php` configuration file. This configuration value is driven by the `APP_KEY` environment variable. You should use the `php artisan key:generate` command to generate this variable's value since the `key:generate` command will use PHP's secure random bytes generator to build a cryptographically secure key for your application. Typically, the value of the `APP_KEY` environment variable will be generated for you during [Laravel's installation](/docs/{{version}}/installation).
+
+### Gracefully Rotating Encryption Keys
+
+If you change your application's encryption key, all authenticated user sessions will be logged out of your application. This is because every cookie, including session cookies, are encrypted by Laravel. In addition, it will no longer be possible to decrypt any data that was encrypted with your previous encryption key.
+
+To mitigate this issue, Laravel allows you to list your previous encryption keys in your application's `APP_PREVIOUS_KEYS` environment variable. This variable may contain a comma-delimited list of all of your previous encryption keys:
+
+```ini
+APP_KEY="base64:J63qRTDLub5NuZvP+kb8YIorGS6qFYHKVo6u7179stY="
+APP_PREVIOUS_KEYS="base64:2nLsGFGzyoae2ax3EF2Lyq/hH6QghBGLIq5uL+Gp8/w="
+```
+
+When you set this environment variable, Laravel will always use the "current" encryption key when encrypting values. However, when decrypting values, Laravel will first try the current key, and if decryption fails using the current key, Laravel will try all previous keys until one of the keys is able to decrypt the value.
+
+This approach to graceful decryption allows users to keep using your application uninterrupted even if your encryption key is rotated.
+
-## Using The Encrypter
+## Using the Encrypter
-#### Encrypting A Value
+#### Encrypting a Value
You may encrypt a value using the `encryptString` method provided by the `Crypt` facade. All encrypted values are encrypted using OpenSSL and the AES-256-CBC cipher. Furthermore, all encrypted values are signed with a message authentication code (MAC). The integrated message authentication code will prevent the decryption of any values that have been tampered with by malicious users:
- user()->fill([
- 'token' => Crypt::encryptString($request->token),
- ])->save();
- }
+ $request->user()->fill([
+ 'token' => Crypt::encryptString($request->token),
+ ])->save();
+
+ return redirect('/secrets');
}
+}
+```
-#### Decrypting A Value
+#### Decrypting a Value
-You may decrypt values using the `decryptString` method provided by the `Crypt` facade. If the value can not be properly decrypted, such as when the message authentication code is invalid, an `Illuminate\Contracts\Encryption\DecryptException` will be thrown:
+You may decrypt values using the `decryptString` method provided by the `Crypt` facade. If the value cannot be properly decrypted, such as when the message authentication code is invalid, an `Illuminate\Contracts\Encryption\DecryptException` will be thrown:
- use Illuminate\Contracts\Encryption\DecryptException;
- use Illuminate\Support\Facades\Crypt;
+```php
+use Illuminate\Contracts\Encryption\DecryptException;
+use Illuminate\Support\Facades\Crypt;
- try {
- $decrypted = Crypt::decryptString($encryptedValue);
- } catch (DecryptException $e) {
- //
- }
+try {
+ $decrypted = Crypt::decryptString($encryptedValue);
+} catch (DecryptException $e) {
+ // ...
+}
+```
diff --git a/envoy.md b/envoy.md
index 88483b61e31..89c0af51c6f 100644
--- a/envoy.md
+++ b/envoy.md
@@ -323,7 +323,7 @@ Envoy also supports sending notifications to [Telegram](https://telegram.org) af
### Microsoft Teams
-Envoy also supports sending notifications to [Microsoft Teams](https://www.microsoft.com/en-us/microsoft-teams) after each task is executed. The `@microsoftTeams` directive accepts a Teams Webhook (required), a message, theme color (success, info, warning, error), and an array of options. You may retrieve your Teams Webook by creating a new [incoming webhook](https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook). The Teams API has many other attributes to customize your message box like title, summary, and sections. You can find more information on the [Microsoft Teams documentation](https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using?tabs=cURL#example-of-connector-message). You should pass the entire Webhook URL into the `@microsoftTeams` directive:
+Envoy also supports sending notifications to [Microsoft Teams](https://www.microsoft.com/en-us/microsoft-teams) after each task is executed. The `@microsoftTeams` directive accepts a Teams Webhook (required), a message, theme color (success, info, warning, error), and an array of options. You may retrieve your Teams Webhook by creating a new [incoming webhook](https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook). The Teams API has many other attributes to customize your message box like title, summary, and sections. You can find more information on the [Microsoft Teams documentation](https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using?tabs=cURL#example-of-connector-message). You should pass the entire Webhook URL into the `@microsoftTeams` directive:
```blade
@finished
diff --git a/errors.md b/errors.md
index 94295e68cb4..dc6e7ea0584 100644
--- a/errors.md
+++ b/errors.md
@@ -2,18 +2,22 @@
- [Introduction](#introduction)
- [Configuration](#configuration)
-- [The Exception Handler](#the-exception-handler)
+- [Handling Exceptions](#handling-exceptions)
- [Reporting Exceptions](#reporting-exceptions)
- - [Ignoring Exceptions By Type](#ignoring-exceptions-by-type)
+ - [Exception Log Levels](#exception-log-levels)
+ - [Ignoring Exceptions by Type](#ignoring-exceptions-by-type)
- [Rendering Exceptions](#rendering-exceptions)
- - [Reportable & Renderable Exceptions](#renderable-exceptions)
+ - [Reportable and Renderable Exceptions](#renderable-exceptions)
+- [Throttling Reported Exceptions](#throttling-reported-exceptions)
- [HTTP Exceptions](#http-exceptions)
- [Custom HTTP Error Pages](#custom-http-error-pages)
## Introduction
-When you start a new Laravel project, error and exception handling is already configured for you. The `App\Exceptions\Handler` class is where all exceptions thrown by your application are logged and then rendered to the user. We'll dive deeper into this class throughout this documentation.
+When you start a new Laravel project, error and exception handling is already configured for you; however, at any point, you may use the `withExceptions` method in your application's `bootstrap/app.php` to manage how exceptions are reported and rendered by your application.
+
+The `$exceptions` object provided to the `withExceptions` closure is an instance of `Illuminate\Foundation\Configuration\Exceptions` and is responsible for managing exception handling in your application. We'll dive deeper into this object throughout this documentation.
## Configuration
@@ -22,239 +26,459 @@ The `debug` option in your `config/app.php` configuration file determines how mu
During local development, you should set the `APP_DEBUG` environment variable to `true`. **In your production environment, this value should always be `false`. If the value is set to `true` in production, you risk exposing sensitive configuration values to your application's end users.**
-
-## The Exception Handler
+
+## Handling Exceptions
### Reporting Exceptions
-All exceptions are handled by the `App\Exceptions\Handler` class. This class contains a `register` method where you may register custom exception reporting and rendering callbacks. We'll examine each of these concepts in detail. Exception reporting is used to log exceptions or send them to an external service like [Flare](https://flareapp.io), [Bugsnag](https://bugsnag.com) or [Sentry](https://github.com/getsentry/sentry-laravel). By default, exceptions will be logged based on your [logging](/docs/{{version}}/logging) configuration. However, you are free to log exceptions however you wish.
+In Laravel, exception reporting is used to log exceptions or send them to an external service like [Sentry](https://github.com/getsentry/sentry-laravel) or [Flare](https://flareapp.io). By default, exceptions will be logged based on your [logging](/docs/{{version}}/logging) configuration. However, you are free to log exceptions however you wish.
-For example, if you need to report different types of exceptions in different ways, you may use the `reportable` method to register a closure that should be executed when an exception of a given type needs to be reported. Laravel will deduce what type of exception the closure reports by examining the type-hint of the closure:
+If you need to report different types of exceptions in different ways, you may use the `report` exception method in your application's `bootstrap/app.php` to register a closure that should be executed when an exception of a given type needs to be reported. Laravel will determine what type of exception the closure reports by examining the type-hint of the closure:
- use App\Exceptions\InvalidOrderException;
+```php
+use App\Exceptions\InvalidOrderException;
- /**
- * Register the exception handling callbacks for the application.
- *
- * @return void
- */
- public function register()
- {
- $this->reportable(function (InvalidOrderException $e) {
- //
- });
- }
+->withExceptions(function (Exceptions $exceptions): void {
+ $exceptions->report(function (InvalidOrderException $e) {
+ // ...
+ });
+})
+```
+
+When you register a custom exception reporting callback using the `report` method, Laravel will still log the exception using the default logging configuration for the application. If you wish to stop the propagation of the exception to the default logging stack, you may use the `stop` method when defining your reporting callback or return `false` from the callback:
-When you register a custom exception reporting callback using the `reportable` method, Laravel will still log the exception using the default logging configuration for the application. If you wish to stop the propagation of the exception to the default logging stack, you may use the `stop` method when defining your reporting callback or return `false` from the callback:
+```php
+use App\Exceptions\InvalidOrderException;
- $this->reportable(function (InvalidOrderException $e) {
- //
+->withExceptions(function (Exceptions $exceptions): void {
+ $exceptions->report(function (InvalidOrderException $e) {
+ // ...
})->stop();
- $this->reportable(function (InvalidOrderException $e) {
+ $exceptions->report(function (InvalidOrderException $e) {
return false;
});
+})
+```
-> {tip} To customize the exception reporting for a given exception, you may also utilize [reportable exceptions](/docs/{{version}}/errors#renderable-exceptions).
+> [!NOTE]
+> To customize the exception reporting for a given exception, you may also utilize [reportable exceptions](/docs/{{version}}/errors#renderable-exceptions).
#### Global Log Context
-If available, Laravel automatically adds the current user's ID to every exception's log message as contextual data. You may define your own global contextual data by overriding the `context` method of your application's `App\Exceptions\Handler` class. This information will be included in every exception's log message written by your application:
+If available, Laravel automatically adds the current user's ID to every exception's log message as contextual data. You may define your own global contextual data using the `context` exception method in your application's `bootstrap/app.php` file. This information will be included in every exception's log message written by your application:
- /**
- * Get the default context variables for logging.
- *
- * @return array
- */
- protected function context()
- {
- return array_merge(parent::context(), [
- 'foo' => 'bar',
- ]);
- }
+```php
+->withExceptions(function (Exceptions $exceptions): void {
+ $exceptions->context(fn () => [
+ 'foo' => 'bar',
+ ]);
+})
+```
#### Exception Log Context
-While adding context to every log message can be useful, sometimes a particular exception may have unique context that you would like to include in your logs. By defining a `context` method on one of your application's custom exceptions, you may specify any data relevant to that exception that should be added to the exception's log entry:
+While adding context to every log message can be useful, sometimes a particular exception may have unique context that you would like to include in your logs. By defining a `context` method on one of your application's exceptions, you may specify any data relevant to that exception that should be added to the exception's log entry:
- $this->orderId];
- }
+ /**
+ * Get the exception's context information.
+ *
+ * @return array
+ */
+ public function context(): array
+ {
+ return ['order_id' => $this->orderId];
}
+}
+```
#### The `report` Helper
-Sometimes you may need to report an exception but continue handling the current request. The `report` helper function allows you to quickly report an exception via the exception handler without rendering an error page to the user:
+Sometimes you may need to report an exception but continue handling the current request. The `report` helper function allows you to quickly report an exception without rendering an error page to the user:
- public function isValid($value)
- {
- try {
- // Validate the value...
- } catch (Throwable $e) {
- report($e);
+```php
+public function isValid(string $value): bool
+{
+ try {
+ // Validate the value...
+ } catch (Throwable $e) {
+ report($e);
- return false;
- }
+ return false;
}
+}
+```
+
+
+#### Deduplicating Reported Exceptions
+
+If you are using the `report` function throughout your application, you may occasionally report the same exception multiple times, creating duplicate entries in your logs.
+
+If you would like to ensure that a single instance of an exception is only ever reported once, you may invoke the `dontReportDuplicates` exception method in your application's `bootstrap/app.php` file:
+
+```php
+->withExceptions(function (Exceptions $exceptions): void {
+ $exceptions->dontReportDuplicates();
+})
+```
+
+Now, when the `report` helper is called with the same instance of an exception, only the first call will be reported:
+
+```php
+$original = new RuntimeException('Whoops!');
+
+report($original); // reported
+
+try {
+ throw $original;
+} catch (Throwable $caught) {
+ report($caught); // ignored
+}
+
+report($original); // ignored
+report($caught); // ignored
+```
+
+
+### Exception Log Levels
+
+When messages are written to your application's [logs](/docs/{{version}}/logging), the messages are written at a specified [log level](/docs/{{version}}/logging#log-levels), which indicates the severity or importance of the message being logged.
+
+As noted above, even when you register a custom exception reporting callback using the `report` method, Laravel will still log the exception using the default logging configuration for the application; however, since the log level can sometimes influence the channels on which a message is logged, you may wish to configure the log level that certain exceptions are logged at.
+
+To accomplish this, you may use the `level` exception method in your application's `bootstrap/app.php` file. This method receives the exception type as its first argument and the log level as its second argument:
+
+```php
+use PDOException;
+use Psr\Log\LogLevel;
+
+->withExceptions(function (Exceptions $exceptions): void {
+ $exceptions->level(PDOException::class, LogLevel::CRITICAL);
+})
+```
-### Ignoring Exceptions By Type
+### Ignoring Exceptions by Type
-When building your application, there will be some types of exceptions you simply want to ignore and never report. Your application's exception handler contains a `$dontReport` property which is initialized to an empty array. Any classes that you add to this property will never be reported; however, they may still have custom rendering logic:
+When building your application, there will be some types of exceptions you never want to report. To ignore these exceptions, you may use the `dontReport` exception method in your application's `bootstrap/app.php` file. Any class provided to this method will never be reported; however, they may still have custom rendering logic:
- use App\Exceptions\InvalidOrderException;
+```php
+use App\Exceptions\InvalidOrderException;
- /**
- * A list of the exception types that should not be reported.
- *
- * @var array
- */
- protected $dontReport = [
+->withExceptions(function (Exceptions $exceptions): void {
+ $exceptions->dontReport([
InvalidOrderException::class,
- ];
+ ]);
+})
+```
+
+Alternatively, you may simply "mark" an exception class with the `Illuminate\Contracts\Debug\ShouldntReport` interface. When an exception is marked with this interface, it will never be reported by Laravel's exception handler:
+
+```php
+ {tip} Behind the scenes, Laravel already ignores some types of errors for you, such as exceptions resulting from 404 HTTP "not found" errors or 419 HTTP responses generated by invalid CSRF tokens.
+```php
+use App\Exceptions\InvalidOrderException;
+use Throwable;
+
+->withExceptions(function (Exceptions $exceptions): void {
+ $exceptions->dontReportWhen(function (Throwable $e) {
+ return $e instanceof PodcastProcessingException &&
+ $e->reason() === 'Subscription expired';
+ });
+})
+```
+
+Internally, Laravel already ignores some types of errors for you, such as exceptions resulting from 404 HTTP errors or 419 HTTP responses generated by invalid CSRF tokens. If you would like to instruct Laravel to stop ignoring a given type of exception, you may use the `stopIgnoring` exception method in your application's `bootstrap/app.php` file:
+
+```php
+use Symfony\Component\HttpKernel\Exception\HttpException;
+
+->withExceptions(function (Exceptions $exceptions): void {
+ $exceptions->stopIgnoring(HttpException::class);
+})
+```
### Rendering Exceptions
-By default, the Laravel exception handler will convert exceptions into an HTTP response for you. However, you are free to register a custom rendering closure for exceptions of a given type. You may accomplish this via the `renderable` method of your exception handler.
+By default, the Laravel exception handler will convert exceptions into an HTTP response for you. However, you are free to register a custom rendering closure for exceptions of a given type. You may accomplish this by using the `render` exception method in your application's `bootstrap/app.php` file.
-The closure passed to the `renderable` method should return an instance of `Illuminate\Http\Response`, which may be generated via the `response` helper. Laravel will deduce what type of exception the closure renders by examining the type-hint of the closure:
+The closure passed to the `render` method should return an instance of `Illuminate\Http\Response`, which may be generated via the `response` helper. Laravel will determine what type of exception the closure renders by examining the type-hint of the closure:
- use App\Exceptions\InvalidOrderException;
+```php
+use App\Exceptions\InvalidOrderException;
+use Illuminate\Http\Request;
- /**
- * Register the exception handling callbacks for the application.
- *
- * @return void
- */
- public function register()
- {
- $this->renderable(function (InvalidOrderException $e, $request) {
- return response()->view('errors.invalid-order', [], 500);
- });
- }
+->withExceptions(function (Exceptions $exceptions): void {
+ $exceptions->render(function (InvalidOrderException $e, Request $request) {
+ return response()->view('errors.invalid-order', status: 500);
+ });
+})
+```
-You may also use the `renderable` method to override the rendering behavior for built-in Laravel or Symfony exceptions such as `NotFoundHttpException`. If the closure given to the `renderable` method does not return a value, Laravel's default exception rendering will be utilized:
+You may also use the `render` method to override the rendering behavior for built-in Laravel or Symfony exceptions such as `NotFoundHttpException`. If the closure given to the `render` method does not return a value, Laravel's default exception rendering will be utilized:
- use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
+```php
+use Illuminate\Http\Request;
+use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
- /**
- * Register the exception handling callbacks for the application.
- *
- * @return void
- */
- public function register()
- {
- $this->renderable(function (NotFoundHttpException $e, $request) {
- if ($request->is('api/*')) {
- return response()->json([
- 'message' => 'Record not found.'
- ], 404);
- }
- });
- }
+->withExceptions(function (Exceptions $exceptions): void {
+ $exceptions->render(function (NotFoundHttpException $e, Request $request) {
+ if ($request->is('api/*')) {
+ return response()->json([
+ 'message' => 'Record not found.'
+ ], 404);
+ }
+ });
+})
+```
-
-### Reportable & Renderable Exceptions
+
+#### Rendering Exceptions as JSON
+
+When rendering an exception, Laravel will automatically determine if the exception should be rendered as an HTML or JSON response based on the `Accept` header of the request. If you would like to customize how Laravel determines whether to render HTML or JSON exception responses, you may utilize the `shouldRenderJsonWhen` method:
-Instead of type-checking exceptions in the exception handler's `register` method, you may define `report` and `render` methods directly on your custom exceptions. When these methods exist, they will be automatically called by the framework:
+```php
+use Illuminate\Http\Request;
+use Throwable;
- withExceptions(function (Exceptions $exceptions): void {
+ $exceptions->shouldRenderJsonWhen(function (Request $request, Throwable $e) {
+ if ($request->is('admin/*')) {
+ return true;
+ }
- namespace App\Exceptions;
+ return $request->expectsJson();
+ });
+})
+```
- use Exception;
+
+#### Customizing the Exception Response
- class InvalidOrderException extends Exception
- {
- /**
- * Report the exception.
- *
- * @return bool|null
- */
- public function report()
- {
- //
- }
+Rarely, you may need to customize the entire HTTP response rendered by Laravel's exception handler. To accomplish this, you may register a response customization closure using the `respond` method:
- /**
- * Render the exception into an HTTP response.
- *
- * @param \Illuminate\Http\Request $request
- * @return \Illuminate\Http\Response
- */
- public function render($request)
- {
- return response(...);
+```php
+use Symfony\Component\HttpFoundation\Response;
+
+->withExceptions(function (Exceptions $exceptions): void {
+ $exceptions->respond(function (Response $response) {
+ if ($response->getStatusCode() === 419) {
+ return back()->with([
+ 'message' => 'The page expired, please try again.',
+ ]);
}
- }
-If your exception extends an exception that is already renderable, such as a built-in Laravel or Symfony exception, you may return `false` from the exception's `render` method to render the exception's default HTTP response:
+ return $response;
+ });
+})
+```
+
+
+### Reportable and Renderable Exceptions
+
+Instead of defining custom reporting and rendering behavior in your application's `bootstrap/app.php` file, you may define `report` and `render` methods directly on your application's exceptions. When these methods exist, they will automatically be called by the framework:
+
+```php
+ {tip} You may type-hint any required dependencies of the `report` method and they will automatically be injected into the method by Laravel's [service container](/docs/{{version}}/container).
+ return false;
+}
+```
+
+> [!NOTE]
+> You may type-hint any required dependencies of the `report` method and they will automatically be injected into the method by Laravel's [service container](/docs/{{version}}/container).
+
+
+### Throttling Reported Exceptions
+
+If your application reports a very large number of exceptions, you may want to throttle how many exceptions are actually logged or sent to your application's external error tracking service.
+
+To take a random sample rate of exceptions, you may use the `throttle` exception method in your application's `bootstrap/app.php` file. The `throttle` method receives a closure that should return a `Lottery` instance:
+
+```php
+use Illuminate\Support\Lottery;
+use Throwable;
+
+->withExceptions(function (Exceptions $exceptions): void {
+ $exceptions->throttle(function (Throwable $e) {
+ return Lottery::odds(1, 1000);
+ });
+})
+```
+
+It is also possible to conditionally sample based on the exception type. If you would like to only sample instances of a specific exception class, you may return a `Lottery` instance only for that class:
+
+```php
+use App\Exceptions\ApiMonitoringException;
+use Illuminate\Support\Lottery;
+use Throwable;
+
+->withExceptions(function (Exceptions $exceptions): void {
+ $exceptions->throttle(function (Throwable $e) {
+ if ($e instanceof ApiMonitoringException) {
+ return Lottery::odds(1, 1000);
+ }
+ });
+})
+```
+
+You may also rate limit exceptions logged or sent to an external error tracking service by returning a `Limit` instance instead of a `Lottery`. This is useful if you want to protect against sudden bursts of exceptions flooding your logs, for example, when a third-party service used by your application is down:
+
+```php
+use Illuminate\Broadcasting\BroadcastException;
+use Illuminate\Cache\RateLimiting\Limit;
+use Throwable;
+
+->withExceptions(function (Exceptions $exceptions): void {
+ $exceptions->throttle(function (Throwable $e) {
+ if ($e instanceof BroadcastException) {
+ return Limit::perMinute(300);
+ }
+ });
+})
+```
+
+By default, limits will use the exception's class as the rate limit key. You can customize this by specifying your own key using the `by` method on the `Limit`:
+
+```php
+use Illuminate\Broadcasting\BroadcastException;
+use Illuminate\Cache\RateLimiting\Limit;
+use Throwable;
+
+->withExceptions(function (Exceptions $exceptions): void {
+ $exceptions->throttle(function (Throwable $e) {
+ if ($e instanceof BroadcastException) {
+ return Limit::perMinute(300)->by($e->getMessage());
+ }
+ });
+})
+```
+
+Of course, you may return a mixture of `Lottery` and `Limit` instances for different exceptions:
+
+```php
+use App\Exceptions\ApiMonitoringException;
+use Illuminate\Broadcasting\BroadcastException;
+use Illuminate\Cache\RateLimiting\Limit;
+use Illuminate\Support\Lottery;
+use Throwable;
+
+->withExceptions(function (Exceptions $exceptions): void {
+ $exceptions->throttle(function (Throwable $e) {
+ return match (true) {
+ $e instanceof BroadcastException => Limit::perMinute(300),
+ $e instanceof ApiMonitoringException => Lottery::odds(1, 1000),
+ default => Limit::none(),
+ };
+ });
+})
+```
## HTTP Exceptions
-Some exceptions describe HTTP error codes from the server. For example, this may be a "page not found" error (404), an "unauthorized error" (401) or even a developer generated 500 error. In order to generate such a response from anywhere in your application, you may use the `abort` helper:
+Some exceptions describe HTTP error codes from the server. For example, this may be a "page not found" error (404), an "unauthorized error" (401), or even a developer generated 500 error. In order to generate such a response from anywhere in your application, you may use the `abort` helper:
- abort(404);
+```php
+abort(404);
+```
### Custom HTTP Error Pages
-Laravel makes it easy to display custom error pages for various HTTP status codes. For example, if you wish to customize the error page for 404 HTTP status codes, create a `resources/views/errors/404.blade.php` view template. This view will be rendered on all 404 errors generated by your application. The views within this directory should be named to match the HTTP status code they correspond to. The `Symfony\Component\HttpKernel\Exception\HttpException` instance raised by the `abort` function will be passed to the view as an `$exception` variable:
+Laravel makes it easy to display custom error pages for various HTTP status codes. For example, to customize the error page for 404 HTTP status codes, create a `resources/views/errors/404.blade.php` view template. This view will be rendered for all 404 errors generated by your application. The views within this directory should be named to match the HTTP status code they correspond to. The `Symfony\Component\HttpKernel\Exception\HttpException` instance raised by the `abort` function will be passed to the view as an `$exception` variable:
-
+ */
+public function backoff(OrderShipped $event): array
+{
+ return [1, 5, 10];
+}
+```
+
+
+#### Specifying Queued Listener Max Exceptions
+
+Sometimes you may wish to specify that a queued listener may be attempted many times, but should fail if the retries are triggered by a given number of unhandled exceptions (as opposed to being released by the `release` method directly). To accomplish this, you may define a `maxExceptions` property on your listener class:
+
+```php
+addMinutes(5);
+ // Process the event...
}
+}
+```
+
+In this example, the listener will be retried up to 25 times. However, the listener will fail if three unhandled exceptions are thrown by the listener.
+
+
+#### Specifying Queued Listener Timeout
+
+Often, you know roughly how long you expect your queued listeners to take. For this reason, Laravel allows you to specify a "timeout" value. If a listener is processing for longer than the number of seconds specified by the timeout value, the worker processing the listener will exit with an error. You may define the maximum number of seconds a listener should be allowed to run by defining a `timeout` property on your listener class:
+
+```php
+
## Dispatching Events
To dispatch an event, you may call the static `dispatch` method on the event. This method is made available on the event by the `Illuminate\Foundation\Events\Dispatchable` trait. Any arguments passed to the `dispatch` method will be passed to the event's constructor:
- order_id);
-
- // Order shipment logic...
-
- OrderShipped::dispatch($order);
- }
+ $order = Order::findOrFail($request->order_id);
+
+ // Order shipment logic...
+
+ OrderShipped::dispatch($order);
+
+ return redirect('/orders');
}
+}
+```
+
+If you would like to conditionally dispatch an event, you may use the `dispatchIf` and `dispatchUnless` methods:
+
+```php
+OrderShipped::dispatchIf($condition, $order);
+
+OrderShipped::dispatchUnless($condition, $order);
+```
+
+> [!NOTE]
+> When testing, it can be helpful to assert that certain events were dispatched without actually triggering their listeners. Laravel's [built-in testing helpers](#testing) make it a cinch.
+
+
+### Dispatching Events After Database Transactions
+
+Sometimes, you may want to instruct Laravel to only dispatch an event after the active database transaction has committed. To do so, you may implement the `ShouldDispatchAfterCommit` interface on the event class.
+
+This interface instructs Laravel to not dispatch the event until the current database transaction is committed. If the transaction fails, the event will be discarded. If no database transaction is in progress when the event is dispatched, the event will be dispatched immediately:
+
+```php
+
+### Deferring Events
+
+Deferred events allow you to delay the dispatching of model events and execution of event listeners until after a specific block of code has completed. This is particularly useful when you need to ensure that all related records are created before event listeners are triggered.
-> {tip} When testing, it can be helpful to assert that certain events were dispatched without actually triggering their listeners. Laravel's [built-in testing helpers](/docs/{{version}}/mocking#event-fake) makes it a cinch.
+To defer events, provide a closure to the `Event::defer()` method:
+
+```php
+use App\Models\User;
+use Illuminate\Support\Facades\Event;
+
+Event::defer(function () {
+ $user = User::create(['name' => 'Victoria Otwell']);
+
+ $user->posts()->create(['title' => 'My first post!']);
+});
+```
+
+All events triggered within the closure will be dispatched after the closure is executed. This ensures that event listeners have access to all related records that were created during the deferred execution. If an exception occurs within the closure, the deferred events will not be dispatched.
+
+To defer only specific events, pass an array of events as the second argument to the `defer` method:
+
+```php
+use App\Models\User;
+use Illuminate\Support\Facades\Event;
+
+Event::defer(function () {
+ $user = User::create(['name' => 'Victoria Otwell']);
+
+ $user->posts()->create(['title' => 'My first post!']);
+}, ['eloquent.created: '.User::class]);
+```
## Event Subscribers
@@ -561,112 +839,314 @@ To dispatch an event, you may call the static `dispatch` method on the event. Th
### Writing Event Subscribers
-Event subscribers are classes that may subscribe to multiple events from within the subscriber class itself, allowing you to define several event handlers within a single class. Subscribers should define a `subscribe` method, which will be passed an event dispatcher instance. You may call the `listen` method on the given dispatcher to register event listeners:
+Event subscribers are classes that may subscribe to multiple events from within the subscriber class itself, allowing you to define several event handlers within a single class. Subscribers should define a `subscribe` method, which receives an event dispatcher instance. You may call the `listen` method on the given dispatcher to register event listeners:
+
+```php
+listen(
- Login::class,
- [UserEventSubscriber::class, 'handleUserLogin']
- );
-
- $events->listen(
- Logout::class,
- [UserEventSubscriber::class, 'handleUserLogout']
- );
- }
+ $events->listen(
+ Login::class,
+ [UserEventSubscriber::class, 'handleUserLogin']
+ );
+
+ $events->listen(
+ Logout::class,
+ [UserEventSubscriber::class, 'handleUserLogout']
+ );
}
+}
+```
If your event listener methods are defined within the subscriber itself, you may find it more convenient to return an array of events and method names from the subscriber's `subscribe` method. Laravel will automatically determine the subscriber's class name when registering the event listeners:
-
+ */
+ public function subscribe(Dispatcher $events): array
{
- /**
- * Handle user login events.
- */
- public function handleUserLogin($event) {}
-
- /**
- * Handle user logout events.
- */
- public function handleUserLogout($event) {}
-
- /**
- * Register the listeners for the subscriber.
- *
- * @param \Illuminate\Events\Dispatcher $events
- * @return array
- */
- public function subscribe($events)
- {
- return [
- Login::class => 'handleUserLogin',
- Logout::class => 'handleUserLogout',
- ];
- }
+ return [
+ Login::class => 'handleUserLogin',
+ Logout::class => 'handleUserLogout',
+ ];
}
+}
+```
### Registering Event Subscribers
-After writing the subscriber, you are ready to register it with the event dispatcher. You may register subscribers using the `$subscribe` property on the `EventServiceProvider`. For example, let's add the `UserEventSubscriber` to the list:
+After writing the subscriber, Laravel will automatically register handler methods within the subscriber if they follow Laravel's [event discovery conventions](#event-discovery). Otherwise, you may manually register your subscriber using the `subscribe` method of the `Event` facade. Typically, this should be done within the `boot` method of your application's `AppServiceProvider`:
-
+## Testing
+
+When testing code that dispatches events, you may wish to instruct Laravel to not actually execute the event's listeners, since the listener's code can be tested directly and separately of the code that dispatches the corresponding event. Of course, to test the listener itself, you may instantiate a listener instance and invoke the `handle` method directly in your test.
+
+Using the `Event` facade's `fake` method, you may prevent listeners from executing, execute the code under test, and then assert which events were dispatched by your application using the `assertDispatched`, `assertNotDispatched`, and `assertNothingDispatched` methods:
+
+```php tab=Pest
+order->id === $order->id;
+});
+```
+
+If you would simply like to assert that an event listener is listening to a given event, you may use the `assertListening` method:
+
+```php
+Event::assertListening(
+ OrderShipped::class,
+ SendShipmentNotification::class
+);
+```
+
+> [!WARNING]
+> After calling `Event::fake()`, no event listeners will be executed. So, if your tests use model factories that rely on events, such as creating a UUID during a model's `creating` event, you should call `Event::fake()` **after** using your factories.
+
+
+### Faking a Subset of Events
+
+If you only want to fake event listeners for a specific set of events, you may pass them to the `fake` or `fakeFor` method:
+
+```php tab=Pest
+test('orders can be processed', function () {
+ Event::fake([
+ OrderCreated::class,
+ ]);
+
+ $order = Order::factory()->create();
+
+ Event::assertDispatched(OrderCreated::class);
+
+ // Other events are dispatched as normal...
+ $order->update([
+ // ...
+ ]);
+});
+```
+
+```php tab=PHPUnit
+/**
+ * Test order process.
+ */
+public function test_orders_can_be_processed(): void
+{
+ Event::fake([
+ OrderCreated::class,
+ ]);
+
+ $order = Order::factory()->create();
+
+ Event::assertDispatched(OrderCreated::class);
+
+ // Other events are dispatched as normal...
+ $order->update([
+ // ...
+ ]);
+}
+```
+
+You may fake all events except for a set of specified events using the `except` method:
+
+```php
+Event::fake()->except([
+ OrderCreated::class,
+]);
+```
+
+
+### Scoped Event Fakes
+
+If you only want to fake event listeners for a portion of your test, you may use the `fakeFor` method:
+
+```php tab=Pest
+create();
+
+ Event::assertDispatched(OrderCreated::class);
+
+ return $order;
+ });
+
+ // Events are dispatched as normal and observers will run...
+ $order->update([
+ // ...
+ ]);
+});
+```
+
+```php tab=PHPUnit
+create();
+
+ Event::assertDispatched(OrderCreated::class);
+
+ return $order;
+ });
+
+ // Events are dispatched as normal and observers will run...
+ $order->update([
+ // ...
+ ]);
}
+}
+```
diff --git a/facades.md b/facades.md
index 2b4aec683fa..6371f913dae 100644
--- a/facades.md
+++ b/facades.md
@@ -1,9 +1,9 @@
# Facades
- [Introduction](#introduction)
-- [When To Use Facades](#when-to-use-facades)
- - [Facades Vs. Dependency Injection](#facades-vs-dependency-injection)
- - [Facades Vs. Helper Functions](#facades-vs-helper-functions)
+- [When to Utilize Facades](#when-to-use-facades)
+ - [Facades vs. Dependency Injection](#facades-vs-dependency-injection)
+ - [Facades vs. Helper Functions](#facades-vs-helper-functions)
- [How Facades Work](#how-facades-work)
- [Real-Time Facades](#real-time-facades)
- [Facade Class Reference](#facade-class-reference)
@@ -13,16 +13,18 @@
Throughout the Laravel documentation, you will see examples of code that interacts with Laravel's features via "facades". Facades provide a "static" interface to classes that are available in the application's [service container](/docs/{{version}}/container). Laravel ships with many facades which provide access to almost all of Laravel's features.
-Laravel facades serve as "static proxies" to underlying classes in the service container, providing the benefit of a terse, expressive syntax while maintaining more testability and flexibility than traditional static methods. It's perfectly fine if you don't totally understand how facades work under the hood - just go with the flow and continue learning about Laravel.
+Laravel facades serve as "static proxies" to underlying classes in the service container, providing the benefit of a terse, expressive syntax while maintaining more testability and flexibility than traditional static methods. It's perfectly fine if you don't totally understand how facades work - just go with the flow and continue learning about Laravel.
All of Laravel's facades are defined in the `Illuminate\Support\Facades` namespace. So, we can easily access a facade like so:
- use Illuminate\Support\Facades\Cache;
- use Illuminate\Support\Facades\Route;
+```php
+use Illuminate\Support\Facades\Cache;
+use Illuminate\Support\Facades\Route;
- Route::get('/cache', function () {
- return Cache::get('key');
- });
+Route::get('/cache', function () {
+ return Cache::get('key');
+});
+```
Throughout the Laravel documentation, many of the examples will use facades to demonstrate various features of the framework.
@@ -33,94 +35,116 @@ To complement facades, Laravel offers a variety of global "helper functions" tha
For example, instead of using the `Illuminate\Support\Facades\Response` facade to generate a JSON response, we may simply use the `response` function. Because helper functions are globally available, you do not need to import any classes in order to use them:
- use Illuminate\Support\Facades\Response;
+```php
+use Illuminate\Support\Facades\Response;
- Route::get('/users', function () {
- return Response::json([
- // ...
- ]);
- });
+Route::get('/users', function () {
+ return Response::json([
+ // ...
+ ]);
+});
- Route::get('/users', function () {
- return response()->json([
- // ...
- ]);
- });
+Route::get('/users', function () {
+ return response()->json([
+ // ...
+ ]);
+});
+```
-## When To Use Facades
+## When to Utilize Facades
Facades have many benefits. They provide a terse, memorable syntax that allows you to use Laravel's features without remembering long class names that must be injected or configured manually. Furthermore, because of their unique usage of PHP's dynamic methods, they are easy to test.
However, some care must be taken when using facades. The primary danger of facades is class "scope creep". Since facades are so easy to use and do not require injection, it can be easy to let your classes continue to grow and use many facades in a single class. Using dependency injection, this potential is mitigated by the visual feedback a large constructor gives you that your class is growing too large. So, when using facades, pay special attention to the size of your class so that its scope of responsibility stays narrow. If your class is getting too large, consider splitting it into multiple smaller classes.
-### Facades Vs. Dependency Injection
+### Facades vs. Dependency Injection
One of the primary benefits of dependency injection is the ability to swap implementations of the injected class. This is useful during testing since you can inject a mock or stub and assert that various methods were called on the stub.
Typically, it would not be possible to mock or stub a truly static class method. However, since facades use dynamic methods to proxy method calls to objects resolved from the service container, we actually can test facades just as we would test an injected class instance. For example, given the following route:
- use Illuminate\Support\Facades\Cache;
+```php
+use Illuminate\Support\Facades\Cache;
- Route::get('/cache', function () {
- return Cache::get('key');
- });
+Route::get('/cache', function () {
+ return Cache::get('key');
+});
+```
Using Laravel's facade testing methods, we can write the following test to verify that the `Cache::get` method was called with the argument we expected:
- use Illuminate\Support\Facades\Cache;
+```php tab=Pest
+use Illuminate\Support\Facades\Cache;
- /**
- * A basic functional test example.
- *
- * @return void
- */
- public function testBasicExample()
- {
- Cache::shouldReceive('get')
- ->with('key')
- ->andReturn('value');
+test('basic example', function () {
+ Cache::shouldReceive('get')
+ ->with('key')
+ ->andReturn('value');
- $response = $this->get('/cache');
+ $response = $this->get('/cache');
- $response->assertSee('value');
- }
+ $response->assertSee('value');
+});
+```
+
+```php tab=PHPUnit
+use Illuminate\Support\Facades\Cache;
+
+/**
+ * A basic functional test example.
+ */
+public function test_basic_example(): void
+{
+ Cache::shouldReceive('get')
+ ->with('key')
+ ->andReturn('value');
+
+ $response = $this->get('/cache');
+
+ $response->assertSee('value');
+}
+```
-### Facades Vs. Helper Functions
+### Facades vs. Helper Functions
In addition to facades, Laravel includes a variety of "helper" functions which can perform common tasks like generating views, firing events, dispatching jobs, or sending HTTP responses. Many of these helper functions perform the same function as a corresponding facade. For example, this facade call and helper call are equivalent:
- return Illuminate\Support\Facades\View::make('profile');
+```php
+return Illuminate\Support\Facades\View::make('profile');
- return view('profile');
+return view('profile');
+```
There is absolutely no practical difference between facades and helper functions. When using helper functions, you may still test them exactly as you would the corresponding facade. For example, given the following route:
- Route::get('/cache', function () {
- return cache('key');
- });
+```php
+Route::get('/cache', function () {
+ return cache('key');
+});
+```
-Under the hood, the `cache` helper is going to call the `get` method on the class underlying the `Cache` facade. So, even though we are using the helper function, we can write the following test to verify that the method was called with the argument we expected:
+The `cache` helper is going to call the `get` method on the class underlying the `Cache` facade. So, even though we are using the helper function, we can write the following test to verify that the method was called with the argument we expected:
- use Illuminate\Support\Facades\Cache;
+```php
+use Illuminate\Support\Facades\Cache;
- /**
- * A basic functional test example.
- *
- * @return void
- */
- public function testBasicExample()
- {
- Cache::shouldReceive('get')
- ->with('key')
- ->andReturn('value');
+/**
+ * A basic functional test example.
+ */
+public function test_basic_example(): void
+{
+ Cache::shouldReceive('get')
+ ->with('key')
+ ->andReturn('value');
- $response = $this->get('/cache');
+ $response = $this->get('/cache');
- $response->assertSee('value');
- }
+ $response->assertSee('value');
+}
+```
## How Facades Work
@@ -129,42 +153,44 @@ In a Laravel application, a facade is a class that provides access to an object
The `Facade` base class makes use of the `__callStatic()` magic-method to defer calls from your facade to an object resolved from the container. In the example below, a call is made to the Laravel cache system. By glancing at this code, one might assume that the static `get` method is being called on the `Cache` class:
- $user]);
- }
+ $user = Cache::get('user:'.$id);
+
+ return view('profile', ['user' => $user]);
}
+}
+```
Notice that near the top of the file we are "importing" the `Cache` facade. This facade serves as a proxy for accessing the underlying implementation of the `Illuminate\Contracts\Cache\Factory` interface. Any calls we make using the facade will be passed to the underlying instance of Laravel's cache service.
If we look at that `Illuminate\Support\Facades\Cache` class, you'll see that there is no static method `get`:
- class Cache extends Facade
+```php
+class Cache extends Facade
+{
+ /**
+ * Get the registered name of the component.
+ */
+ protected static function getFacadeAccessor(): string
{
- /**
- * Get the registered name of the component.
- *
- * @return string
- */
- protected static function getFacadeAccessor() { return 'cache'; }
+ return 'cache';
}
+}
+```
Instead, the `Cache` facade extends the base `Facade` class and defines the method `getFacadeAccessor()`. This method's job is to return the name of a service container binding. When a user references any static method on the `Cache` facade, Laravel resolves the `cache` binding from the [service container](/docs/{{version}}/container) and runs the requested method (in this case, `get`) against that object.
@@ -173,134 +199,166 @@ Instead, the `Cache` facade extends the base `Facade` class and defines the meth
Using real-time facades, you may treat any class in your application as if it was a facade. To illustrate how this can be used, let's first examine some code that does not use real-time facades. For example, let's assume our `Podcast` model has a `publish` method. However, in order to publish the podcast, we need to inject a `Publisher` instance:
- update(['publishing' => now()]);
-
- $publisher->publish($this);
- }
+ $this->update(['publishing' => now()]);
+
+ $publisher->publish($this);
}
+}
+```
Injecting a publisher implementation into the method allows us to easily test the method in isolation since we can mock the injected publisher. However, it requires us to always pass a publisher instance each time we call the `publish` method. Using real-time facades, we can maintain the same testability while not being required to explicitly pass a `Publisher` instance. To generate a real-time facade, prefix the namespace of the imported class with `Facades`:
- update(['publishing' => now()]);
-
- Publisher::publish($this);
- }
+ $this->update(['publishing' => now()]);
+
+ $publisher->publish($this); // [tl! remove]
+ Publisher::publish($this); // [tl! add]
}
+}
+```
When the real-time facade is used, the publisher implementation will be resolved out of the service container using the portion of the interface or class name that appears after the `Facades` prefix. When testing, we can use Laravel's built-in facade testing helpers to mock this method call:
- use(RefreshDatabase::class);
- class PodcastTest extends TestCase
- {
- use RefreshDatabase;
+test('podcast can be published', function () {
+ $podcast = Podcast::factory()->create();
+
+ Publisher::shouldReceive('publish')->once()->with($podcast);
- /**
- * A test example.
- *
- * @return void
- */
- public function test_podcast_can_be_published()
- {
- $podcast = Podcast::factory()->create();
+ $podcast->publish();
+});
+```
+
+```php tab=PHPUnit
+create();
- Publisher::shouldReceive('publish')->once()->with($podcast);
+ Publisher::shouldReceive('publish')->once()->with($podcast);
- $podcast->publish();
- }
+ $podcast->publish();
}
+}
+```
## Facade Class Reference
Below you will find every facade and its underlying class. This is a useful tool for quickly digging into the API documentation for a given facade root. The [service container binding](/docs/{{version}}/container) key is also included where applicable.
-Facade | Class | Service Container Binding
-------------- | ------------- | -------------
-App | [Illuminate\Foundation\Application](https://laravel.com/api/{{version}}/Illuminate/Foundation/Application.html) | `app`
-Artisan | [Illuminate\Contracts\Console\Kernel](https://laravel.com/api/{{version}}/Illuminate/Contracts/Console/Kernel.html) | `artisan`
-Auth | [Illuminate\Auth\AuthManager](https://laravel.com/api/{{version}}/Illuminate/Auth/AuthManager.html) | `auth`
-Auth (Instance) | [Illuminate\Contracts\Auth\Guard](https://laravel.com/api/{{version}}/Illuminate/Contracts/Auth/Guard.html) | `auth.driver`
-Blade | [Illuminate\View\Compilers\BladeCompiler](https://laravel.com/api/{{version}}/Illuminate/View/Compilers/BladeCompiler.html) | `blade.compiler`
-Broadcast | [Illuminate\Contracts\Broadcasting\Factory](https://laravel.com/api/{{version}}/Illuminate/Contracts/Broadcasting/Factory.html) |
-Broadcast (Instance) | [Illuminate\Contracts\Broadcasting\Broadcaster](https://laravel.com/api/{{version}}/Illuminate/Contracts/Broadcasting/Broadcaster.html) |
-Bus | [Illuminate\Contracts\Bus\Dispatcher](https://laravel.com/api/{{version}}/Illuminate/Contracts/Bus/Dispatcher.html) |
-Cache | [Illuminate\Cache\CacheManager](https://laravel.com/api/{{version}}/Illuminate/Cache/CacheManager.html) | `cache`
-Cache (Instance) | [Illuminate\Cache\Repository](https://laravel.com/api/{{version}}/Illuminate/Cache/Repository.html) | `cache.store`
-Config | [Illuminate\Config\Repository](https://laravel.com/api/{{version}}/Illuminate/Config/Repository.html) | `config`
-Cookie | [Illuminate\Cookie\CookieJar](https://laravel.com/api/{{version}}/Illuminate/Cookie/CookieJar.html) | `cookie`
-Crypt | [Illuminate\Encryption\Encrypter](https://laravel.com/api/{{version}}/Illuminate/Encryption/Encrypter.html) | `encrypter`
-Date | [Illuminate\Support\DateFactory](https://laravel.com/api/{{version}}/Illuminate/Support/DateFactory.html) | `date`
-DB | [Illuminate\Database\DatabaseManager](https://laravel.com/api/{{version}}/Illuminate/Database/DatabaseManager.html) | `db`
-DB (Instance) | [Illuminate\Database\Connection](https://laravel.com/api/{{version}}/Illuminate/Database/Connection.html) | `db.connection`
-Event | [Illuminate\Events\Dispatcher](https://laravel.com/api/{{version}}/Illuminate/Events/Dispatcher.html) | `events`
-File | [Illuminate\Filesystem\Filesystem](https://laravel.com/api/{{version}}/Illuminate/Filesystem/Filesystem.html) | `files`
-Gate | [Illuminate\Contracts\Auth\Access\Gate](https://laravel.com/api/{{version}}/Illuminate/Contracts/Auth/Access/Gate.html) |
-Hash | [Illuminate\Contracts\Hashing\Hasher](https://laravel.com/api/{{version}}/Illuminate/Contracts/Hashing/Hasher.html) | `hash`
-Http | [Illuminate\Http\Client\Factory](https://laravel.com/api/{{version}}/Illuminate/Http/Client/Factory.html) |
-Lang | [Illuminate\Translation\Translator](https://laravel.com/api/{{version}}/Illuminate/Translation/Translator.html) | `translator`
-Log | [Illuminate\Log\LogManager](https://laravel.com/api/{{version}}/Illuminate/Log/LogManager.html) | `log`
-Mail | [Illuminate\Mail\Mailer](https://laravel.com/api/{{version}}/Illuminate/Mail/Mailer.html) | `mailer`
-Notification | [Illuminate\Notifications\ChannelManager](https://laravel.com/api/{{version}}/Illuminate/Notifications/ChannelManager.html) |
-Password | [Illuminate\Auth\Passwords\PasswordBrokerManager](https://laravel.com/api/{{version}}/Illuminate/Auth/Passwords/PasswordBrokerManager.html) | `auth.password`
-Password (Instance) | [Illuminate\Auth\Passwords\PasswordBroker](https://laravel.com/api/{{version}}/Illuminate/Auth/Passwords/PasswordBroker.html) | `auth.password.broker`
-Queue | [Illuminate\Queue\QueueManager](https://laravel.com/api/{{version}}/Illuminate/Queue/QueueManager.html) | `queue`
-Queue (Instance) | [Illuminate\Contracts\Queue\Queue](https://laravel.com/api/{{version}}/Illuminate/Contracts/Queue/Queue.html) | `queue.connection`
-Queue (Base Class) | [Illuminate\Queue\Queue](https://laravel.com/api/{{version}}/Illuminate/Queue/Queue.html) |
-Redirect | [Illuminate\Routing\Redirector](https://laravel.com/api/{{version}}/Illuminate/Routing/Redirector.html) | `redirect`
-Redis | [Illuminate\Redis\RedisManager](https://laravel.com/api/{{version}}/Illuminate/Redis/RedisManager.html) | `redis`
-Redis (Instance) | [Illuminate\Redis\Connections\Connection](https://laravel.com/api/{{version}}/Illuminate/Redis/Connections/Connection.html) | `redis.connection`
-Request | [Illuminate\Http\Request](https://laravel.com/api/{{version}}/Illuminate/Http/Request.html) | `request`
-Response | [Illuminate\Contracts\Routing\ResponseFactory](https://laravel.com/api/{{version}}/Illuminate/Contracts/Routing/ResponseFactory.html) |
-Response (Instance) | [Illuminate\Http\Response](https://laravel.com/api/{{version}}/Illuminate/Http/Response.html) |
-Route | [Illuminate\Routing\Router](https://laravel.com/api/{{version}}/Illuminate/Routing/Router.html) | `router`
-Schema | [Illuminate\Database\Schema\Builder](https://laravel.com/api/{{version}}/Illuminate/Database/Schema/Builder.html) |
-Session | [Illuminate\Session\SessionManager](https://laravel.com/api/{{version}}/Illuminate/Session/SessionManager.html) | `session`
-Session (Instance) | [Illuminate\Session\Store](https://laravel.com/api/{{version}}/Illuminate/Session/Store.html) | `session.store`
-Storage | [Illuminate\Filesystem\FilesystemManager](https://laravel.com/api/{{version}}/Illuminate/Filesystem/FilesystemManager.html) | `filesystem`
-Storage (Instance) | [Illuminate\Contracts\Filesystem\Filesystem](https://laravel.com/api/{{version}}/Illuminate/Contracts/Filesystem/Filesystem.html) | `filesystem.disk`
-URL | [Illuminate\Routing\UrlGenerator](https://laravel.com/api/{{version}}/Illuminate/Routing/UrlGenerator.html) | `url`
-Validator | [Illuminate\Validation\Factory](https://laravel.com/api/{{version}}/Illuminate/Validation/Factory.html) | `validator`
-Validator (Instance) | [Illuminate\Validation\Validator](https://laravel.com/api/{{version}}/Illuminate/Validation/Validator.html) |
-View | [Illuminate\View\Factory](https://laravel.com/api/{{version}}/Illuminate/View/Factory.html) | `view`
-View (Instance) | [Illuminate\View\View](https://laravel.com/api/{{version}}/Illuminate/View/View.html) |
+
+AWS_SECRET_ACCESS_KEY=
+AWS_DEFAULT_REGION=us-east-1
+AWS_BUCKET=
+AWS_USE_PATH_STYLE_ENDPOINT=false
```
-The S3 driver configuration information is located in your `config/filesystems.php` configuration file. This file contains an example configuration array for an S3 driver. You are free to modify this array with your own S3 configuration and credentials. For convenience, these environment variables match the naming convention used by the AWS CLI.
+For convenience, these environment variables match the naming convention used by the AWS CLI.
#### FTP Driver Configuration
@@ -89,21 +118,23 @@ Before using the FTP driver, you will need to install the Flysystem FTP package
composer require league/flysystem-ftp "^3.0"
```
-Laravel's Flysystem integrations work great with FTP; however, a sample configuration is not included with the framework's default `filesystems.php` configuration file. If you need to configure an FTP filesystem, you may use the configuration example below:
+Laravel's Flysystem integrations work great with FTP; however, a sample configuration is not included with the framework's default `config/filesystems.php` configuration file. If you need to configure an FTP filesystem, you may use the configuration example below:
- 'ftp' => [
- 'driver' => 'ftp',
- 'host' => env('FTP_HOST'),
- 'username' => env('FTP_USERNAME'),
- 'password' => env('FTP_PASSWORD'),
-
- // Optional FTP Settings...
- // 'port' => env('FTP_PORT', 21),
- // 'root' => env('FTP_ROOT'),
- // 'passive' => true,
- // 'ssl' => true,
- // 'timeout' => 30,
- ],
+```php
+'ftp' => [
+ 'driver' => 'ftp',
+ 'host' => env('FTP_HOST'),
+ 'username' => env('FTP_USERNAME'),
+ 'password' => env('FTP_PASSWORD'),
+
+ // Optional FTP Settings...
+ // 'port' => env('FTP_PORT', 21),
+ // 'root' => env('FTP_ROOT'),
+ // 'passive' => true,
+ // 'ssl' => true,
+ // 'timeout' => 30,
+],
+```
#### SFTP Driver Configuration
@@ -114,47 +145,110 @@ Before using the SFTP driver, you will need to install the Flysystem SFTP packag
composer require league/flysystem-sftp-v3 "^3.0"
```
-Laravel's Flysystem integrations work great with SFTP; however, a sample configuration is not included with the framework's default `filesystems.php` configuration file. If you need to configure an SFTP filesystem, you may use the configuration example below:
+Laravel's Flysystem integrations work great with SFTP; however, a sample configuration is not included with the framework's default `config/filesystems.php` configuration file. If you need to configure an SFTP filesystem, you may use the configuration example below:
- 'sftp' => [
- 'driver' => 'sftp',
- 'host' => env('SFTP_HOST'),
-
- // Settings for basic authentication...
- 'username' => env('SFTP_USERNAME'),
- 'password' => env('SFTP_PASSWORD'),
+```php
+'sftp' => [
+ 'driver' => 'sftp',
+ 'host' => env('SFTP_HOST'),
+
+ // Settings for basic authentication...
+ 'username' => env('SFTP_USERNAME'),
+ 'password' => env('SFTP_PASSWORD'),
+
+ // Settings for SSH key-based authentication with encryption password...
+ 'privateKey' => env('SFTP_PRIVATE_KEY'),
+ 'passphrase' => env('SFTP_PASSPHRASE'),
+
+ // Settings for file / directory permissions...
+ 'visibility' => 'private', // `private` = 0600, `public` = 0644
+ 'directory_visibility' => 'private', // `private` = 0700, `public` = 0755
+
+ // Optional SFTP Settings...
+ // 'hostFingerprint' => env('SFTP_HOST_FINGERPRINT'),
+ // 'maxTries' => 4,
+ // 'passphrase' => env('SFTP_PASSPHRASE'),
+ // 'port' => env('SFTP_PORT', 22),
+ // 'root' => env('SFTP_ROOT', ''),
+ // 'timeout' => 30,
+ // 'useAgent' => true,
+],
+```
- // Settings for SSH key based authentication with encryption password...
- 'privateKey' => env('SFTP_PRIVATE_KEY'),
- 'password' => env('SFTP_PASSWORD'),
+
+### Scoped and Read-Only Filesystems
- // Optional SFTP Settings...
- // 'port' => env('SFTP_PORT', 22),
- // 'root' => env('SFTP_ROOT', ''),
- // 'timeout' => 30,
- ],
+Scoped disks allow you to define a filesystem where all paths are automatically prefixed with a given path prefix. Before creating a scoped filesystem disk, you will need to install an additional Flysystem package via the Composer package manager:
+
+```shell
+composer require league/flysystem-path-prefixing "^3.0"
+```
+
+You may create a path scoped instance of any existing filesystem disk by defining a disk that utilizes the `scoped` driver. For example, you may create a disk which scopes your existing `s3` disk to a specific path prefix, and then every file operation using your scoped disk will utilize the specified prefix:
+
+```php
+'s3-videos' => [
+ 'driver' => 'scoped',
+ 'disk' => 's3',
+ 'prefix' => 'path/to/videos',
+],
+```
+
+"Read-only" disks allow you to create filesystem disks that do not allow write operations. Before using the `read-only` configuration option, you will need to install an additional Flysystem package via the Composer package manager:
+
+```shell
+composer require league/flysystem-read-only "^3.0"
+```
+
+Next, you may include the `read-only` configuration option in one or more of your disk's configuration arrays:
+
+```php
+'s3-videos' => [
+ 'driver' => 's3',
+ // ...
+ 'read-only' => true,
+],
+```
### Amazon S3 Compatible Filesystems
-By default, your application's `filesystems` configuration file contains a disk configuration for the `s3` disk. In addition to using this disk to interact with Amazon S3, you may use it to interact with any S3 compatible file storage service such as [MinIO](https://github.com/minio/minio) or [DigitalOcean Spaces](https://www.digitalocean.com/products/spaces/).
+By default, your application's `filesystems` configuration file contains a disk configuration for the `s3` disk. In addition to using this disk to interact with [Amazon S3](https://aws.amazon.com/s3/), you may use it to interact with any S3-compatible file storage service such as [MinIO](https://github.com/minio/minio), [DigitalOcean Spaces](https://www.digitalocean.com/products/spaces/), [Vultr Object Storage](https://www.vultr.com/products/object-storage/), [Cloudflare R2](https://www.cloudflare.com/developer-platform/products/r2/), or [Hetzner Cloud Storage](https://www.hetzner.com/storage/object-storage/).
+
+Typically, after updating the disk's credentials to match the credentials of the service you are planning to use, you only need to update the value of the `endpoint` configuration option. This option's value is typically defined via the `AWS_ENDPOINT` environment variable:
+
+```php
+'endpoint' => env('AWS_ENDPOINT', 'https://minio:9000/'),
+```
+
+
+#### MinIO
+
+In order for Laravel's Flysystem integration to generate proper URLs when using MinIO, you should define the `AWS_URL` environment variable so that it matches your application's local URL and includes the bucket name in the URL path:
-Typically, after updating the disk's credentials to match the credentials of the service you are planning to use, you only need to update the value of the `url` configuration option. This option's value is typically defined via the `AWS_ENDPOINT` environment variable:
+```ini
+AWS_URL=http://localhost:9000/local
+```
- 'endpoint' => env('AWS_ENDPOINT', 'https://minio:9000/'),
+> [!WARNING]
+> Generating temporary storage URLs via the `temporaryUrl` method may not work when using MinIO if the `endpoint` is not accessible by the client.
## Obtaining Disk Instances
The `Storage` facade may be used to interact with any of your configured disks. For example, you may use the `put` method on the facade to store an avatar on the default disk. If you call methods on the `Storage` facade without first calling the `disk` method, the method will automatically be passed to the default disk:
- use Illuminate\Support\Facades\Storage;
+```php
+use Illuminate\Support\Facades\Storage;
- Storage::put('avatars/1', $content);
+Storage::put('avatars/1', $content);
+```
If your application interacts with multiple disks, you may use the `disk` method on the `Storage` facade to work with files on a particular disk:
- Storage::disk('s3')->put('avatars/1', $content);
+```php
+Storage::disk('s3')->put('avatars/1', $content);
+```
### On-Demand Disks
@@ -177,260 +271,381 @@ $disk->put('image.jpg', $content);
The `get` method may be used to retrieve the contents of a file. The raw string contents of the file will be returned by the method. Remember, all file paths should be specified relative to the disk's "root" location:
- $contents = Storage::get('file.jpg');
+```php
+$contents = Storage::get('file.jpg');
+```
+
+If the file you are retrieving contains JSON, you may use the `json` method to retrieve the file and decode its contents:
+
+```php
+$orders = Storage::json('orders.json');
+```
The `exists` method may be used to determine if a file exists on the disk:
- if (Storage::disk('s3')->exists('file.jpg')) {
- // ...
- }
+```php
+if (Storage::disk('s3')->exists('file.jpg')) {
+ // ...
+}
+```
The `missing` method may be used to determine if a file is missing from the disk:
- if (Storage::disk('s3')->missing('file.jpg')) {
- // ...
- }
+```php
+if (Storage::disk('s3')->missing('file.jpg')) {
+ // ...
+}
+```
### Downloading Files
The `download` method may be used to generate a response that forces the user's browser to download the file at the given path. The `download` method accepts a filename as the second argument to the method, which will determine the filename that is seen by the user downloading the file. Finally, you may pass an array of HTTP headers as the third argument to the method:
- return Storage::download('file.jpg');
+```php
+return Storage::download('file.jpg');
- return Storage::download('file.jpg', $name, $headers);
+return Storage::download('file.jpg', $name, $headers);
+```
### File URLs
You may use the `url` method to get the URL for a given file. If you are using the `local` driver, this will typically just prepend `/storage` to the given path and return a relative URL to the file. If you are using the `s3` driver, the fully qualified remote URL will be returned:
- use Illuminate\Support\Facades\Storage;
+```php
+use Illuminate\Support\Facades\Storage;
- $url = Storage::url('https://github.com/file.jpg');
+$url = Storage::url('https://github.com/file.jpg');
+```
When using the `local` driver, all files that should be publicly accessible should be placed in the `storage/app/public` directory. Furthermore, you should [create a symbolic link](#the-public-disk) at `public/storage` which points to the `storage/app/public` directory.
-> {note} When using the `local` driver, the return value of `url` is not URL encoded. For this reason, we recommend always storing your files using names that will create valid URLs.
+> [!WARNING]
+> When using the `local` driver, the return value of `url` is not URL encoded. For this reason, we recommend always storing your files using names that will create valid URLs.
+
+
+#### URL Host Customization
+
+If you would like to modify the host for URLs generated using the `Storage` facade, you may add or change the `url` option in the disk's configuration array:
+
+```php
+'public' => [
+ 'driver' => 'local',
+ 'root' => storage_path('app/public'),
+ 'url' => env('APP_URL').'/storage',
+ 'visibility' => 'public',
+ 'throw' => false,
+],
+```
-#### Temporary URLs
+### Temporary URLs
+
+Using the `temporaryUrl` method, you may create temporary URLs to files stored using the `local` and `s3` drivers. This method accepts a path and a `DateTime` instance specifying when the URL should expire:
+
+```php
+use Illuminate\Support\Facades\Storage;
+
+$url = Storage::temporaryUrl(
+ 'file.jpg', now()->addMinutes(5)
+);
+```
+
+
+#### Enabling Local Temporary URLs
-Using the `temporaryUrl` method, you may create temporary URLs to files stored using the `s3` driver. This method accepts a path and a `DateTime` instance specifying when the URL should expire:
+If you started developing your application before support for temporary URLs was introduced to the `local` driver, you may need to enable local temporary URLs. To do so, add the `serve` option to your `local` disk's configuration array within the `config/filesystems.php` configuration file:
- use Illuminate\Support\Facades\Storage;
+```php
+'local' => [
+ 'driver' => 'local',
+ 'root' => storage_path('app/private'),
+ 'serve' => true, // [tl! add]
+ 'throw' => false,
+],
+```
- $url = Storage::temporaryUrl(
- 'file.jpg', now()->addMinutes(5)
- );
+
+#### S3 Request Parameters
If you need to specify additional [S3 request parameters](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectGET.html#RESTObjectGET-requests), you may pass the array of request parameters as the third argument to the `temporaryUrl` method:
- $url = Storage::temporaryUrl(
- 'file.jpg',
- now()->addMinutes(5),
- [
- 'ResponseContentType' => 'application/octet-stream',
- 'ResponseContentDisposition' => 'attachment; filename=file2.jpg',
- ]
- );
+```php
+$url = Storage::temporaryUrl(
+ 'file.jpg',
+ now()->addMinutes(5),
+ [
+ 'ResponseContentType' => 'application/octet-stream',
+ 'ResponseContentDisposition' => 'attachment; filename=file2.jpg',
+ ]
+);
+```
-If you need to customize how temporary URLs are created for a specific storage disk, you can use the `buildTemporaryUrlsUsing` method. For example, this can be useful if you have a controller that allows you to download files stored via a disk that doesn't typically support temporary URLs. Usually, this method should be called from the `boot` method of a service provider:
+
+#### Customizing Temporary URLs
- buildTemporaryUrlsUsing(function ($path, $expiration, $options) {
+ Storage::disk('local')->buildTemporaryUrlsUsing(
+ function (string $path, DateTime $expiration, array $options) {
return URL::temporarySignedRoute(
'files.download',
$expiration,
array_merge($options, ['path' => $path])
);
- });
- }
+ }
+ );
}
+}
+```
-
-#### URL Host Customization
+
+#### Temporary Upload URLs
-If you would like to pre-define the host for URLs generated using the `Storage` facade, you may add a `url` option to the disk's configuration array:
+> [!WARNING]
+> The ability to generate temporary upload URLs is only supported by the `s3` driver.
- 'public' => [
- 'driver' => 'local',
- 'root' => storage_path('app/public'),
- 'url' => env('APP_URL').'/storage',
- 'visibility' => 'public',
- ],
+If you need to generate a temporary URL that can be used to upload a file directly from your client-side application, you may use the `temporaryUploadUrl` method. This method accepts a path and a `DateTime` instance specifying when the URL should expire. The `temporaryUploadUrl` method returns an associative array which may be destructured into the upload URL and the headers that should be included with the upload request:
+
+```php
+use Illuminate\Support\Facades\Storage;
+
+['url' => $url, 'headers' => $headers] = Storage::temporaryUploadUrl(
+ 'file.jpg', now()->addMinutes(5)
+);
+```
+
+This method is primarily useful in serverless environments that require the client-side application to directly upload files to a cloud storage system such as Amazon S3.
### File Metadata
In addition to reading and writing files, Laravel can also provide information about the files themselves. For example, the `size` method may be used to get the size of a file in bytes:
- use Illuminate\Support\Facades\Storage;
+```php
+use Illuminate\Support\Facades\Storage;
- $size = Storage::size('file.jpg');
+$size = Storage::size('file.jpg');
+```
The `lastModified` method returns the UNIX timestamp of the last time the file was modified:
- $time = Storage::lastModified('file.jpg');
+```php
+$time = Storage::lastModified('file.jpg');
+```
+
+The MIME type of a given file may be obtained via the `mimeType` method:
+
+```php
+$mime = Storage::mimeType('file.jpg');
+```
#### File Paths
You may use the `path` method to get the path for a given file. If you are using the `local` driver, this will return the absolute path to the file. If you are using the `s3` driver, this method will return the relative path to the file in the S3 bucket:
- use Illuminate\Support\Facades\Storage;
+```php
+use Illuminate\Support\Facades\Storage;
- $path = Storage::path('file.jpg');
+$path = Storage::path('file.jpg');
+```
## Storing Files
The `put` method may be used to store file contents on a disk. You may also pass a PHP `resource` to the `put` method, which will use Flysystem's underlying stream support. Remember, all file paths should be specified relative to the "root" location configured for the disk:
- use Illuminate\Support\Facades\Storage;
-
- Storage::put('file.jpg', $contents);
-
- Storage::put('file.jpg', $resource);
-
-
-#### Automatic Streaming
+```php
+use Illuminate\Support\Facades\Storage;
-Streaming files to storage offers significantly reduced memory usage. If you would like Laravel to automatically manage streaming a given file to your storage location, you may use the `putFile` or `putFileAs` method. This method accepts either an `Illuminate\Http\File` or `Illuminate\Http\UploadedFile` instance and will automatically stream the file to your desired location:
+Storage::put('file.jpg', $contents);
- use Illuminate\Http\File;
- use Illuminate\Support\Facades\Storage;
+Storage::put('file.jpg', $resource);
+```
- // Automatically generate a unique ID for filename...
- $path = Storage::putFile('photos', new File('/path/to/photo'));
+
+#### Failed Writes
- // Manually specify a filename...
- $path = Storage::putFileAs('photos', new File('/path/to/photo'), 'photo.jpg');
+If the `put` method (or other "write" operations) is unable to write the file to disk, `false` will be returned:
-There are a few important things to note about the `putFile` method. Note that we only specified a directory name and not a filename. By default, the `putFile` method will generate a unique ID to serve as the filename. The file's extension will be determined by examining the file's MIME type. The path to the file will be returned by the `putFile` method so you can store the path, including the generated filename, in your database.
+```php
+if (! Storage::put('file.jpg', $contents)) {
+ // The file could not be written to disk...
+}
+```
-The `putFile` and `putFileAs` methods also accept an argument to specify the "visibility" of the stored file. This is particularly useful if you are storing the file on a cloud disk such as Amazon S3 and would like the file to be publicly accessible via generated URLs:
+If you wish, you may define the `throw` option within your filesystem disk's configuration array. When this option is defined as `true`, "write" methods such as `put` will throw an instance of `League\Flysystem\UnableToWriteFile` when write operations fail:
- Storage::putFile('photos', new File('/path/to/photo'), 'public');
+```php
+'public' => [
+ 'driver' => 'local',
+ // ...
+ 'throw' => true,
+],
+```
-#### Prepending & Appending To Files
+### Prepending and Appending To Files
The `prepend` and `append` methods allow you to write to the beginning or end of a file:
- Storage::prepend('file.log', 'Prepended Text');
+```php
+Storage::prepend('file.log', 'Prepended Text');
- Storage::append('file.log', 'Appended Text');
+Storage::append('file.log', 'Appended Text');
+```
-#### Copying & Moving Files
+### Copying and Moving Files
The `copy` method may be used to copy an existing file to a new location on the disk, while the `move` method may be used to rename or move an existing file to a new location:
- Storage::copy('old/file.jpg', 'new/file.jpg');
+```php
+Storage::copy('old/file.jpg', 'new/file.jpg');
+
+Storage::move('old/file.jpg', 'new/file.jpg');
+```
+
+
+### Automatic Streaming
+
+Streaming files to storage offers significantly reduced memory usage. If you would like Laravel to automatically manage streaming a given file to your storage location, you may use the `putFile` or `putFileAs` method. This method accepts either an `Illuminate\Http\File` or `Illuminate\Http\UploadedFile` instance and will automatically stream the file to your desired location:
- Storage::move('old/file.jpg', 'new/file.jpg');
+```php
+use Illuminate\Http\File;
+use Illuminate\Support\Facades\Storage;
+
+// Automatically generate a unique ID for filename...
+$path = Storage::putFile('photos', new File('/path/to/photo'));
+
+// Manually specify a filename...
+$path = Storage::putFileAs('photos', new File('/path/to/photo'), 'photo.jpg');
+```
+
+There are a few important things to note about the `putFile` method. Note that we only specified a directory name and not a filename. By default, the `putFile` method will generate a unique ID to serve as the filename. The file's extension will be determined by examining the file's MIME type. The path to the file will be returned by the `putFile` method so you can store the path, including the generated filename, in your database.
+
+The `putFile` and `putFileAs` methods also accept an argument to specify the "visibility" of the stored file. This is particularly useful if you are storing the file on a cloud disk such as Amazon S3 and would like the file to be publicly accessible via generated URLs:
+
+```php
+Storage::putFile('photos', new File('/path/to/photo'), 'public');
+```
### File Uploads
In web applications, one of the most common use-cases for storing files is storing user uploaded files such as photos and documents. Laravel makes it very easy to store uploaded files using the `store` method on an uploaded file instance. Call the `store` method with the path at which you wish to store the uploaded file:
- file('avatar')->store('avatars');
-
- return $path;
- }
+ $path = $request->file('avatar')->store('avatars');
+
+ return $path;
}
+}
+```
There are a few important things to note about this example. Note that we only specified a directory name, not a filename. By default, the `store` method will generate a unique ID to serve as the filename. The file's extension will be determined by examining the file's MIME type. The path to the file will be returned by the `store` method so you can store the path, including the generated filename, in your database.
You may also call the `putFile` method on the `Storage` facade to perform the same file storage operation as the example above:
- $path = Storage::putFile('avatars', $request->file('avatar'));
+```php
+$path = Storage::putFile('avatars', $request->file('avatar'));
+```
-#### Specifying A File Name
+#### Specifying a File Name
If you do not want a filename to be automatically assigned to your stored file, you may use the `storeAs` method, which receives the path, the filename, and the (optional) disk as its arguments:
- $path = $request->file('avatar')->storeAs(
- 'avatars', $request->user()->id
- );
+```php
+$path = $request->file('avatar')->storeAs(
+ 'avatars', $request->user()->id
+);
+```
You may also use the `putFileAs` method on the `Storage` facade, which will perform the same file storage operation as the example above:
- $path = Storage::putFileAs(
- 'avatars', $request->file('avatar'), $request->user()->id
- );
+```php
+$path = Storage::putFileAs(
+ 'avatars', $request->file('avatar'), $request->user()->id
+);
+```
-> {note} Unprintable and invalid unicode characters will automatically be removed from file paths. Therefore, you may wish to sanitize your file paths before passing them to Laravel's file storage methods. File paths are normalized using the `League\Flysystem\Util::normalizePath` method.
+> [!WARNING]
+> Unprintable and invalid unicode characters will automatically be removed from file paths. Therefore, you may wish to sanitize your file paths before passing them to Laravel's file storage methods. File paths are normalized using the `League\Flysystem\WhitespacePathNormalizer::normalizePath` method.
-#### Specifying A Disk
+#### Specifying a Disk
By default, this uploaded file's `store` method will use your default disk. If you would like to specify another disk, pass the disk name as the second argument to the `store` method:
- $path = $request->file('avatar')->store(
- 'avatars/'.$request->user()->id, 's3'
- );
+```php
+$path = $request->file('avatar')->store(
+ 'avatars/'.$request->user()->id, 's3'
+);
+```
If you are using the `storeAs` method, you may pass the disk name as the third argument to the method:
- $path = $request->file('avatar')->storeAs(
- 'avatars',
- $request->user()->id,
- 's3'
- );
+```php
+$path = $request->file('avatar')->storeAs(
+ 'avatars',
+ $request->user()->id,
+ 's3'
+);
+```
#### Other Uploaded File Information
If you would like to get the original name and extension of the uploaded file, you may do so using the `getClientOriginalName` and `getClientOriginalExtension` methods:
- $file = $request->file('avatar');
+```php
+$file = $request->file('avatar');
- $name = $file->getClientOriginalName();
- $extension = $file->getClientOriginalExtension();
+$name = $file->getClientOriginalName();
+$extension = $file->getClientOriginalExtension();
+```
However, keep in mind that the `getClientOriginalName` and `getClientOriginalExtension` methods are considered unsafe, as the file name and extension may be tampered with by a malicious user. For this reason, you should typically prefer the `hashName` and `extension` methods to get a name and an extension for the given file upload:
- $file = $request->file('avatar');
+```php
+$file = $request->file('avatar');
- $name = $file->hashName(); // Generate a unique, random name...
- $extension = $file->extension(); // Determine the file's extension based on the file's MIME type...
+$name = $file->hashName(); // Generate a unique, random name...
+$extension = $file->extension(); // Determine the file's extension based on the file's MIME type...
+```
### File Visibility
@@ -439,99 +654,197 @@ In Laravel's Flysystem integration, "visibility" is an abstraction of file permi
You can set the visibility when writing the file via the `put` method:
- use Illuminate\Support\Facades\Storage;
+```php
+use Illuminate\Support\Facades\Storage;
- Storage::put('file.jpg', $contents, 'public');
+Storage::put('file.jpg', $contents, 'public');
+```
If the file has already been stored, its visibility can be retrieved and set via the `getVisibility` and `setVisibility` methods:
- $visibility = Storage::getVisibility('file.jpg');
+```php
+$visibility = Storage::getVisibility('file.jpg');
- Storage::setVisibility('file.jpg', 'public');
+Storage::setVisibility('file.jpg', 'public');
+```
When interacting with uploaded files, you may use the `storePublicly` and `storePubliclyAs` methods to store the uploaded file with `public` visibility:
- $path = $request->file('avatar')->storePublicly('avatars', 's3');
+```php
+$path = $request->file('avatar')->storePublicly('avatars', 's3');
- $path = $request->file('avatar')->storePubliclyAs(
- 'avatars',
- $request->user()->id,
- 's3'
- );
+$path = $request->file('avatar')->storePubliclyAs(
+ 'avatars',
+ $request->user()->id,
+ 's3'
+);
+```
-#### Local Files & Visibility
+#### Local Files and Visibility
When using the `local` driver, `public` [visibility](#file-visibility) translates to `0755` permissions for directories and `0644` permissions for files. You can modify the permissions mappings in your application's `filesystems` configuration file:
- 'local' => [
- 'driver' => 'local',
- 'root' => storage_path('app'),
- 'permissions' => [
- 'file' => [
- 'public' => 0644,
- 'private' => 0600,
- ],
- 'dir' => [
- 'public' => 0755,
- 'private' => 0700,
- ],
+```php
+'local' => [
+ 'driver' => 'local',
+ 'root' => storage_path('app'),
+ 'permissions' => [
+ 'file' => [
+ 'public' => 0644,
+ 'private' => 0600,
+ ],
+ 'dir' => [
+ 'public' => 0755,
+ 'private' => 0700,
],
],
+ 'throw' => false,
+],
+```
## Deleting Files
The `delete` method accepts a single filename or an array of files to delete:
- use Illuminate\Support\Facades\Storage;
+```php
+use Illuminate\Support\Facades\Storage;
- Storage::delete('file.jpg');
+Storage::delete('file.jpg');
- Storage::delete(['file.jpg', 'file2.jpg']);
+Storage::delete(['file.jpg', 'file2.jpg']);
+```
If necessary, you may specify the disk that the file should be deleted from:
- use Illuminate\Support\Facades\Storage;
+```php
+use Illuminate\Support\Facades\Storage;
- Storage::disk('s3')->delete('path/file.jpg');
+Storage::disk('s3')->delete('path/file.jpg');
+```
## Directories
-#### Get All Files Within A Directory
+#### Get All Files Within a Directory
-The `files` method returns an array of all of the files in a given directory. If you would like to retrieve a list of all files within a given directory including all subdirectories, you may use the `allFiles` method:
+The `files` method returns an array of all files within a given directory. If you would like to retrieve a list of all files within a given directory including subdirectories, you may use the `allFiles` method:
- use Illuminate\Support\Facades\Storage;
+```php
+use Illuminate\Support\Facades\Storage;
- $files = Storage::files($directory);
+$files = Storage::files($directory);
- $files = Storage::allFiles($directory);
+$files = Storage::allFiles($directory);
+```
-#### Get All Directories Within A Directory
+#### Get All Directories Within a Directory
-The `directories` method returns an array of all the directories within a given directory. Additionally, you may use the `allDirectories` method to get a list of all directories within a given directory and all of its subdirectories:
+The `directories` method returns an array of all directories within a given directory. If you would like to retrieve a list of all directories within a given directory including subdirectories, you may use the `allDirectories` method:
- $directories = Storage::directories($directory);
+```php
+$directories = Storage::directories($directory);
- $directories = Storage::allDirectories($directory);
+$directories = Storage::allDirectories($directory);
+```
-#### Create A Directory
+#### Create a Directory
The `makeDirectory` method will create the given directory, including any needed subdirectories:
- Storage::makeDirectory($directory);
+```php
+Storage::makeDirectory($directory);
+```
-#### Delete A Directory
+#### Delete a Directory
Finally, the `deleteDirectory` method may be used to remove a directory and all of its files:
- Storage::deleteDirectory($directory);
+```php
+Storage::deleteDirectory($directory);
+```
+
+
+## Testing
+
+The `Storage` facade's `fake` method allows you to easily generate a fake disk that, combined with the file generation utilities of the `Illuminate\Http\UploadedFile` class, greatly simplifies the testing of file uploads. For example:
+
+```php tab=Pest
+json('POST', '/photos', [
+ UploadedFile::fake()->image('photo1.jpg'),
+ UploadedFile::fake()->image('photo2.jpg')
+ ]);
+
+ // Assert one or more files were stored...
+ Storage::disk('photos')->assertExists('photo1.jpg');
+ Storage::disk('photos')->assertExists(['photo1.jpg', 'photo2.jpg']);
+
+ // Assert one or more files were not stored...
+ Storage::disk('photos')->assertMissing('missing.jpg');
+ Storage::disk('photos')->assertMissing(['missing.jpg', 'non-existing.jpg']);
+
+ // Assert that the number of files in a given directory matches the expected count...
+ Storage::disk('photos')->assertCount('/wallpapers', 2);
+
+ // Assert that a given directory is empty...
+ Storage::disk('photos')->assertDirectoryEmpty('/wallpapers');
+});
+```
+
+```php tab=PHPUnit
+json('POST', '/photos', [
+ UploadedFile::fake()->image('photo1.jpg'),
+ UploadedFile::fake()->image('photo2.jpg')
+ ]);
+
+ // Assert one or more files were stored...
+ Storage::disk('photos')->assertExists('photo1.jpg');
+ Storage::disk('photos')->assertExists(['photo1.jpg', 'photo2.jpg']);
+
+ // Assert one or more files were not stored...
+ Storage::disk('photos')->assertMissing('missing.jpg');
+ Storage::disk('photos')->assertMissing(['missing.jpg', 'non-existing.jpg']);
+
+ // Assert that the number of files in a given directory matches the expected count...
+ Storage::disk('photos')->assertCount('/wallpapers', 2);
+
+ // Assert that a given directory is empty...
+ Storage::disk('photos')->assertDirectoryEmpty('/wallpapers');
+ }
+}
+```
+
+By default, the `fake` method will delete all files in its temporary directory. If you would like to keep these files, you may use the "persistentFake" method instead. For more information on testing file uploads, you may consult the [HTTP testing documentation's information on file uploads](/docs/{{version}}/http-tests#testing-file-uploads).
+
+> [!WARNING]
+> The `image` method requires the [GD extension](https://www.php.net/manual/en/book.image.php).
## Custom Filesystems
@@ -546,49 +859,48 @@ composer require spatie/flysystem-dropbox
Next, you can register the driver within the `boot` method of one of your application's [service providers](/docs/{{version}}/providers). To accomplish this, you should use the `extend` method of the `Storage` facade:
-
+## Introduction
+
+[Laravel Folio](https://github.com/laravel/folio) is a powerful page based router designed to simplify routing in Laravel applications. With Laravel Folio, generating a route becomes as effortless as creating a Blade template within your application's `resources/views/pages` directory.
+
+For example, to create a page that is accessible at the `/greeting` URL, just create a `greeting.blade.php` file in your application's `resources/views/pages` directory:
+
+```php
+
-
-### Strings
-
-<digits>
+- decimal:<precision>
- `double`
- `encrypted`
- `encrypted:array`
- `encrypted:collection`
- `encrypted:object`
- `float`
+- `hashed`
- `integer`
- `object`
- `real`
@@ -223,215 +241,393 @@ The `$casts` property should be an array where the key is the name of the attrib
To demonstrate attribute casting, let's cast the `is_admin` attribute, which is stored in our database as an integer (`0` or `1`) to a boolean value:
-
+ */
+ protected function casts(): array
{
- /**
- * The attributes that should be cast.
- *
- * @var array
- */
- protected $casts = [
+ return [
'is_admin' => 'boolean',
];
}
+}
+```
After defining the cast, the `is_admin` attribute will always be cast to a boolean when you access it, even if the underlying value is stored in the database as an integer:
- $user = App\Models\User::find(1);
+```php
+$user = App\Models\User::find(1);
- if ($user->is_admin) {
- //
- }
+if ($user->is_admin) {
+ // ...
+}
+```
If you need to add a new, temporary cast at runtime, you may use the `mergeCasts` method. These cast definitions will be added to any of the casts already defined on the model:
- $user->mergeCasts([
- 'is_admin' => 'integer',
- 'options' => 'object',
- ]);
+```php
+$user->mergeCasts([
+ 'is_admin' => 'integer',
+ 'options' => 'object',
+]);
+```
-> {note} Attributes that are `null` will not be cast. In addition, you should never define a cast (or an attribute) that has the same name as a relationship.
+> [!WARNING]
+> Attributes that are `null` will not be cast. In addition, you should never define a cast (or an attribute) that has the same name as a relationship or assign a cast to the model's primary key.
#### Stringable Casting
-You may use the `Illuminate\Database\Eloquent\Casts\AsStringable` cast class to cast a model attribute to a [fluent `Illuminate\Support\Stringable` object](/docs/{{version}}/helpers#fluent-strings-method-list):
+You may use the `Illuminate\Database\Eloquent\Casts\AsStringable` cast class to cast a model attribute to a [fluent Illuminate\Support\Stringable object](/docs/{{version}}/strings#fluent-strings-method-list):
-
+ */
+ protected function casts(): array
{
- /**
- * The attributes that should be cast.
- *
- * @var array
- */
- protected $casts = [
+ return [
'directory' => AsStringable::class,
];
}
+}
+```
-### Array & JSON Casting
+### Array and JSON Casting
The `array` cast is particularly useful when working with columns that are stored as serialized JSON. For example, if your database has a `JSON` or `TEXT` field type that contains serialized JSON, adding the `array` cast to that attribute will automatically deserialize the attribute to a PHP array when you access it on your Eloquent model:
-
+ */
+ protected function casts(): array
{
- /**
- * The attributes that should be cast.
- *
- * @var array
- */
- protected $casts = [
+ return [
'options' => 'array',
];
}
+}
+```
Once the cast is defined, you may access the `options` attribute and it will automatically be deserialized from JSON into a PHP array. When you set the value of the `options` attribute, the given array will automatically be serialized back into JSON for storage:
- use App\Models\User;
+```php
+use App\Models\User;
- $user = User::find(1);
+$user = User::find(1);
- $options = $user->options;
+$options = $user->options;
- $options['key'] = 'value';
+$options['key'] = 'value';
- $user->options = $options;
+$user->options = $options;
- $user->save();
+$user->save();
+```
-To update a single field of a JSON attribute with a more terse syntax, you may use the `->` operator when calling the `update` method:
+To update a single field of a JSON attribute with a more terse syntax, you may [make the attribute mass assignable](/docs/{{version}}/eloquent#mass-assignment-json-columns) and use the `->` operator when calling the `update` method:
- $user = User::find(1);
+```php
+$user = User::find(1);
- $user->update(['options->key' => 'value']);
+$user->update(['options->key' => 'value']);
+```
+
+
+#### JSON and Unicode
+
+If you would like to store an array attribute as JSON with unescaped Unicode characters, you may use the `json:unicode` cast:
+
+```php
+/**
+ * Get the attributes that should be cast.
+ *
+ * @return array{{ $exception->getMessage() }}
+```blade +{{ $exception->getMessage() }}
+``` You may publish Laravel's default error page templates using the `vendor:publish` Artisan command. Once the templates have been published, you may customize them to your liking: @@ -266,3 +490,5 @@ php artisan vendor:publish --tag=laravel-errors #### Fallback HTTP Error Pages You may also define a "fallback" error page for a given series of HTTP status codes. This page will be rendered if there is not a corresponding page for the specific HTTP status code that occurred. To accomplish this, define a `4xx.blade.php` template and a `5xx.blade.php` template in your application's `resources/views/errors` directory. + +When defining fallback error pages, the fallback pages will not affect `404`, `500`, and `503` error responses since Laravel has internal, dedicated pages for these status codes. To customize the pages rendered for these status codes, you should define a custom error page for each of them individually. diff --git a/events.md b/events.md index 653d4424a82..a5d0d189e9d 100644 --- a/events.md +++ b/events.md @@ -1,20 +1,28 @@ # Events - [Introduction](#introduction) -- [Registering Events & Listeners](#registering-events-and-listeners) - - [Generating Events & Listeners](#generating-events-and-listeners) - - [Manually Registering Events](#manually-registering-events) +- [Generating Events and Listeners](#generating-events-and-listeners) +- [Registering Events and Listeners](#registering-events-and-listeners) - [Event Discovery](#event-discovery) + - [Manually Registering Events](#manually-registering-events) + - [Closure Listeners](#closure-listeners) - [Defining Events](#defining-events) - [Defining Listeners](#defining-listeners) - [Queued Event Listeners](#queued-event-listeners) - - [Manually Interacting With The Queue](#manually-interacting-with-the-queue) - - [Queued Event Listeners & Database Transactions](#queued-event-listeners-and-database-transactions) + - [Manually Interacting With the Queue](#manually-interacting-with-the-queue) + - [Queued Event Listeners and Database Transactions](#queued-event-listeners-and-database-transactions) + - [Queued Listener Middleware](#queued-listener-middleware) + - [Encrypted Queued Listeners](#encrypted-queued-listeners) - [Handling Failed Jobs](#handling-failed-jobs) - [Dispatching Events](#dispatching-events) + - [Dispatching Events After Database Transactions](#dispatching-events-after-database-transactions) + - [Deferring Events](#deferring-events) - [Event Subscribers](#event-subscribers) - [Writing Event Subscribers](#writing-event-subscribers) - [Registering Event Subscribers](#registering-event-subscribers) +- [Testing](#testing) + - [Faking a Subset of Events](#faking-a-subset-of-events) + - [Scoped Events Fakes](#scoped-event-fakes) ## Introduction @@ -23,248 +31,251 @@ Laravel's events provide a simple observer pattern implementation, allowing you Events serve as a great way to decouple various aspects of your application, since a single event can have multiple listeners that do not depend on each other. For example, you may wish to send a Slack notification to your user each time an order has shipped. Instead of coupling your order processing code to your Slack notification code, you can raise an `App\Events\OrderShipped` event which a listener can receive and use to dispatch a Slack notification. - -## Registering Events & Listeners - -The `App\Providers\EventServiceProvider` included with your Laravel application provides a convenient place to register all of your application's event listeners. The `listen` property contains an array of all events (keys) and their listeners (values). You may add as many events to this array as your application requires. For example, let's add an `OrderShipped` event: - - use App\Events\OrderShipped; - use App\Listeners\SendShipmentNotification; - - /** - * The event listener mappings for the application. - * - * @var array - */ - protected $listen = [ - OrderShipped::class => [ - SendShipmentNotification::class, - ], - ]; - -> {tip} The `event:list` command may be used to display a list of all events and listeners registered by your application. - -### Generating Events & Listeners +## Generating Events and Listeners -Of course, manually creating the files for each event and listener is cumbersome. Instead, add listeners and events to your `EventServiceProvider` and use the `event:generate` Artisan command. This command will generate any events or listeners that are listed in your `EventServiceProvider` that do not already exist: +To quickly generate events and listeners, you may use the `make:event` and `make:listener` Artisan commands: ```shell -php artisan event:generate +php artisan make:event PodcastProcessed + +php artisan make:listener SendPodcastNotification --event=PodcastProcessed ``` -Alternatively, you may use the `make:event` and `make:listener` Artisan commands to generate individual events and listeners: +For convenience, you may also invoke the `make:event` and `make:listener` Artisan commands without additional arguments. When you do so, Laravel will automatically prompt you for the class name and, when creating a listener, the event it should listen to: ```shell -php artisan make:event PodcastProcessed +php artisan make:event -php artisan make:listener SendPodcastNotification --event=PodcastProcessed +php artisan make:listener ``` - -### Manually Registering Events + +## Registering Events and Listeners -Typically, events should be registered via the `EventServiceProvider` `$listen` array; however, you may also register class or closure based event listeners manually in the `boot` method of your `EventServiceProvider`: + +### Event Discovery - use App\Events\PodcastProcessed; - use App\Listeners\SendPodcastNotification; - use Illuminate\Support\Facades\Event; +By default, Laravel will automatically find and register your event listeners by scanning your application's `Listeners` directory. When Laravel finds any listener class method that begins with `handle` or `__invoke`, Laravel will register those methods as event listeners for the event that is type-hinted in the method's signature: +```php +use App\Events\PodcastProcessed; + +class SendPodcastNotification +{ /** - * Register any other events for your application. - * - * @return void + * Handle the event. */ - public function boot() + public function handle(PodcastProcessed $event): void { - Event::listen( - PodcastProcessed::class, - [SendPodcastNotification::class, 'handle'] - ); - - Event::listen(function (PodcastProcessed $event) { - // - }); + // ... } +} +``` - -#### Queueable Anonymous Event Listeners +You may listen to multiple events using PHP's union types: -When registering closure based event listeners manually, you may wrap the listener closure within the `Illuminate\Events\queueable` function to instruct Laravel to execute the listener using the [queue](/docs/{{version}}/queues): +```php +/** + * Handle the event. + */ +public function handle(PodcastProcessed|PodcastPublished $event): void +{ + // ... +} +``` - use App\Events\PodcastProcessed; - use function Illuminate\Events\queueable; - use Illuminate\Support\Facades\Event; +If you plan to store your listeners in a different directory or within multiple directories, you may instruct Laravel to scan those directories using the `withEvents` method in your application's `bootstrap/app.php` file: - /** - * Register any other events for your application. - * - * @return void - */ - public function boot() - { - Event::listen(queueable(function (PodcastProcessed $event) { - // - })); - } +```php +->withEvents(discover: [ + __DIR__.'/../app/Domain/Orders/Listeners', +]) +``` -Like queued jobs, you may use the `onConnection`, `onQueue`, and `delay` methods to customize the execution of the queued listener: +You may scan for listeners in multiple similar directories using the `*` character as a wildcard: - Event::listen(queueable(function (PodcastProcessed $event) { - // - })->onConnection('redis')->onQueue('podcasts')->delay(now()->addSeconds(10))); +```php +->withEvents(discover: [ + __DIR__.'/../app/Domain/*/Listeners', +]) +``` -If you would like to handle anonymous queued listener failures, you may provide a closure to the `catch` method while defining the `queueable` listener. This closure will receive the event instance and the `Throwable` instance that caused the listener's failure: +The `event:list` command may be used to list all of the listeners registered within your application: - use App\Events\PodcastProcessed; - use function Illuminate\Events\queueable; - use Illuminate\Support\Facades\Event; - use Throwable; +```shell +php artisan event:list +``` - Event::listen(queueable(function (PodcastProcessed $event) { - // - })->catch(function (PodcastProcessed $event, Throwable $e) { - // The queued listener failed... - })); + +#### Event Discovery in Production - -#### Wildcard Event Listeners +To give your application a speed boost, you should cache a manifest of all of your application's listeners using the `optimize` or `event:cache` Artisan commands. Typically, this command should be run as part of your application's [deployment process](/docs/{{version}}/deployment#optimization). This manifest will be used by the framework to speed up the event registration process. The `event:clear` command may be used to destroy the event cache. + + +### Manually Registering Events + +Using the `Event` facade, you may manually register events and their corresponding listeners within the `boot` method of your application's `AppServiceProvider`: + +```php +use App\Domain\Orders\Events\PodcastProcessed; +use App\Domain\Orders\Listeners\SendPodcastNotification; +use Illuminate\Support\Facades\Event; + +/** + * Bootstrap any application services. + */ +public function boot(): void +{ + Event::listen( + PodcastProcessed::class, + SendPodcastNotification::class, + ); +} +``` + +The `event:list` command may be used to list all of the listeners registered within your application: + +```shell +php artisan event:list +``` -You may even register listeners using the `*` as a wildcard parameter, allowing you to catch multiple events on the same listener. Wildcard listeners receive the event name as their first argument and the entire event data array as their second argument: + +### Closure Listeners - Event::listen('event.*', function ($eventName, array $data) { - // +Typically, listeners are defined as classes; however, you may also manually register closure-based event listeners in the `boot` method of your application's `AppServiceProvider`: + +```php +use App\Events\PodcastProcessed; +use Illuminate\Support\Facades\Event; + +/** + * Bootstrap any application services. + */ +public function boot(): void +{ + Event::listen(function (PodcastProcessed $event) { + // ... }); +} +``` - -### Event Discovery + +#### Queueable Anonymous Event Listeners -Instead of registering events and listeners manually in the `$listen` array of the `EventServiceProvider`, you can enable automatic event discovery. When event discovery is enabled, Laravel will automatically find and register your events and listeners by scanning your application's `Listeners` directory. In addition, any explicitly defined events listed in the `EventServiceProvider` will still be registered. +When registering closure-based event listeners, you may wrap the listener closure within the `Illuminate\Events\queueable` function to instruct Laravel to execute the listener using the [queue](/docs/{{version}}/queues): -Laravel finds event listeners by scanning the listener classes using PHP's reflection services. When Laravel finds any listener class method that begins with `handle` or `__invoke`, Laravel will register those methods as event listeners for the event that is type-hinted in the method's signature: +```php +use App\Events\PodcastProcessed; +use function Illuminate\Events\queueable; +use Illuminate\Support\Facades\Event; - use App\Events\PodcastProcessed; +/** + * Bootstrap any application services. + */ +public function boot(): void +{ + Event::listen(queueable(function (PodcastProcessed $event) { + // ... + })); +} +``` - class SendPodcastNotification - { - /** - * Handle the given event. - * - * @param \App\Events\PodcastProcessed $event - * @return void - */ - public function handle(PodcastProcessed $event) - { - // - } - } +Like queued jobs, you may use the `onConnection`, `onQueue`, and `delay` methods to customize the execution of the queued listener: -Event discovery is disabled by default, but you can enable it by overriding the `shouldDiscoverEvents` method of your application's `EventServiceProvider`: +```php +Event::listen(queueable(function (PodcastProcessed $event) { + // ... +})->onConnection('redis')->onQueue('podcasts')->delay(now()->addSeconds(10))); +``` - /** - * Determine if events and listeners should be automatically discovered. - * - * @return bool - */ - public function shouldDiscoverEvents() - { - return true; - } +If you would like to handle anonymous queued listener failures, you may provide a closure to the `catch` method while defining the `queueable` listener. This closure will receive the event instance and the `Throwable` instance that caused the listener's failure: -By default, all listeners within your application's `app/Listeners` directory will be scanned. If you would like to define additional directories to scan, you may override the `discoverEventsWithin` method in your `EventServiceProvider`: +```php +use App\Events\PodcastProcessed; +use function Illuminate\Events\queueable; +use Illuminate\Support\Facades\Event; +use Throwable; + +Event::listen(queueable(function (PodcastProcessed $event) { + // ... +})->catch(function (PodcastProcessed $event, Throwable $e) { + // The queued listener failed... +})); +``` - /** - * Get the listener directories that should be used to discover events. - * - * @return array - */ - protected function discoverEventsWithin() - { - return [ - $this->app->path('Listeners'), - ]; - } + +#### Wildcard Event Listeners - -#### Event Discovery In Production +You may also register listeners using the `*` character as a wildcard parameter, allowing you to catch multiple events on the same listener. Wildcard listeners receive the event name as their first argument and the entire event data array as their second argument: -In production, it is not efficient for the framework to scan all of your listeners on every request. Therefore, during your deployment process, you should run the `event:cache` Artisan command to cache a manifest of all of your application's events and listeners. This manifest will be used by the framework to speed up the event registration process. The `event:clear` command may be used to destroy the cache. +```php +Event::listen('event.*', function (string $eventName, array $data) { + // ... +}); +``` ## Defining Events An event class is essentially a data container which holds the information related to the event. For example, let's assume an `App\Events\OrderShipped` event receives an [Eloquent ORM](/docs/{{version}}/eloquent) object: - order = $order; - } - } +class OrderShipped +{ + use Dispatchable, InteractsWithSockets, SerializesModels; + + /** + * Create a new event instance. + */ + public function __construct( + public Order $order, + ) {} +} +``` As you can see, this event class contains no logic. It is a container for the `App\Models\Order` instance that was purchased. The `SerializesModels` trait used by the event will gracefully serialize any Eloquent models if the event object is serialized using PHP's `serialize` function, such as when utilizing [queued listeners](#queued-event-listeners). ## Defining Listeners -Next, let's take a look at the listener for our example event. Event listeners receive event instances in their `handle` method. The `event:generate` and `make:listener` Artisan commands will automatically import the proper event class and type-hint the event on the `handle` method. Within the `handle` method, you may perform any actions necessary to respond to the event: +Next, let's take a look at the listener for our example event. Event listeners receive event instances in their `handle` method. The `make:listener` Artisan command, when invoked with the `--event` option, will automatically import the proper event class and type-hint the event in the `handle` method. Within the `handle` method, you may perform any actions necessary to respond to the event: - order... - } + /** + * Handle the event. + */ + public function handle(OrderShipped $event): void + { + // Access the order using $event->order... } +} +``` -> {tip} Your event listeners may also type-hint any dependencies they need on their constructors. All event listeners are resolved via the Laravel [service container](/docs/{{version}}/container), so dependencies will be injected automatically. +> [!NOTE] +> Your event listeners may also type-hint any dependencies they need on their constructors. All event listeners are resolved via the Laravel [service container](/docs/{{version}}/container), so dependencies will be injected automatically. #### Stopping The Propagation Of An Event @@ -276,284 +287,551 @@ Sometimes, you may wish to stop the propagation of an event to other listeners. Queueing listeners can be beneficial if your listener is going to perform a slow task such as sending an email or making an HTTP request. Before using queued listeners, make sure to [configure your queue](/docs/{{version}}/queues) and start a queue worker on your server or local development environment. -To specify that a listener should be queued, add the `ShouldQueue` interface to the listener class. Listeners generated by the `event:generate` and `make:listener` Artisan commands already have this interface imported into the current namespace so you can use it immediately: +To specify that a listener should be queued, add the `ShouldQueue` interface to the listener class. Listeners generated by the `make:listener` Artisan commands already have this interface imported into the current namespace so you can use it immediately: - -#### Customizing The Queue Connection & Queue Name +#### Customizing The Queue Connection, Name, & Delay If you would like to customize the queue connection, queue name, or queue delay time of an event listener, you may define the `$connection`, `$queue`, or `$delay` properties on your listener class: - highPriority ? 0 : 60; +} +``` #### Conditionally Queueing Listeners -Sometimes, you may need to determine whether a listener should be queued based on some data that are only available at runtime. To accomplish this, a `shouldQueue` method may be added to a listener to determine whether the listener should be queued. If the `shouldQueue` method returns `false`, the listener will not be executed: +Sometimes, you may need to determine whether a listener should be queued based on some data that are only available at runtime. To accomplish this, a `shouldQueue` method may be added to a listener to determine whether the listener should be queued. If the `shouldQueue` method returns `false`, the listener will not be queued: - order->subtotal >= 5000; - } + /** + * Determine whether the listener should be queued. + */ + public function shouldQueue(OrderCreated $event): bool + { + return $event->order->subtotal >= 5000; } +} +``` -### Manually Interacting With The Queue +### Manually Interacting With the Queue If you need to manually access the listener's underlying queue job's `delete` and `release` methods, you may do so using the `Illuminate\Queue\InteractsWithQueue` trait. This trait is imported by default on generated listeners and provides access to these methods: - release(30); - } + if ($condition) { + $this->release(30); } } +} +``` -### Queued Event Listeners & Database Transactions +### Queued Event Listeners and Database Transactions When queued listeners are dispatched within database transactions, they may be processed by the queue before the database transaction has committed. When this happens, any updates you have made to models or database records during the database transaction may not yet be reflected in the database. In addition, any models or database records created within the transaction may not exist in the database. If your listener depends on these models, unexpected errors can occur when the job that dispatches the queued listener is processed. -If your queue connection's `after_commit` configuration option is set to `false`, you may still indicate that a particular queued listener should be dispatched after all open database transactions have been committed by defining an `$afterCommit` property on the listener class: +If your queue connection's `after_commit` configuration option is set to `false`, you may still indicate that a particular queued listener should be dispatched after all open database transactions have been committed by implementing the `ShouldQueueAfterCommit` interface on the listener class: - [!NOTE] +> To learn more about working around these issues, please review the documentation regarding [queued jobs and database transactions](/docs/{{version}}/queues#jobs-and-database-transactions). + + +### Queued Listener Middleware + +Queued listeners can also utilize [job middleware](/docs/{{version}}/queues#job-middleware). Job middleware allow you to wrap custom logic around the execution of queued listeners, reducing boilerplate in the listeners themselves. After creating job middleware, they may be attached to a listener by returning them from the listener's `middleware` method: + +```php + + */ + public function middleware(OrderShipped $event): array + { + return [new RateLimited]; } +} +``` + + +#### Encrypted Queued Listeners -> {tip} To learn more about working around these issues, please review the documentation regarding [queued jobs and database transactions](/docs/{{version}}/queues#jobs-and-database-transactions). +Laravel allows you to ensure the privacy and integrity of a queued listener's data via [encryption](/docs/{{version}}/encryption). To get started, simply add the `ShouldBeEncrypted` interface to the listener class. Once this interface has been added to the class, Laravel will automatically encrypt your listener before pushing it onto a queue: + +```php + ### Handling Failed Jobs -Sometimes your queued event listeners may fail. If queued listener exceeds the maximum number of attempts as defined by your queue worker, the `failed` method will be called on your listener. The `failed` method receives the event instance and the `Throwable` that caused the failure: +Sometimes your queued event listeners may fail. If the queued listener exceeds the maximum number of attempts as defined by your queue worker, the `failed` method will be called on your listener. The `failed` method receives the event instance and the `Throwable` that caused the failure: - #### Specifying Queued Listener Maximum Attempts If one of your queued listeners is encountering an error, you likely do not want it to keep retrying indefinitely. Therefore, Laravel provides various ways to specify how many times or for how long a listener may be attempted. -You may define `$tries` property on your listener class to specify how many times the listener may be attempted before it is considered to have failed: +You may define a `tries` property or method on your listener class to specify how many times the listener may be attempted before it is considered to have failed: - addMinutes(5); +} +``` + +If both `retryUntil` and `tries` are defined, Laravel gives precedence to the `retryUntil` method. + + +#### Specifying Queued Listener Backoff + +If you would like to configure how many seconds Laravel should wait before retrying a listener that has encountered an exception, you may do so by defining a `backoff` property on your listener class: + +```php +/** + * The number of seconds to wait before retrying the queued listener. + * + * @var int + */ +public $backoff = 3; +``` + +If you require more complex logic for determining the listeners's backoff time, you may define a `backoff` method on your listener class: + +```php +/** + * Calculate the number of seconds to wait before retrying the queued listener. + */ +public function backoff(OrderShipped $event): int +{ + return 3; +} +``` + +You may easily configure "exponential" backoffs by returning an array of backoff values from the `backoff` method. In this example, the retry delay will be 1 second for the first retry, 5 seconds for the second retry, 10 seconds for the third retry, and 10 seconds for every subsequent retry if there are more attempts remaining: + +```php +/** + * Calculate the number of seconds to wait before retrying the queued listener. + * + * @return list
+
+| Facade | Class | Service Container Binding |
+| --- | --- | --- |
+| App | [Illuminate\Foundation\Application](https://api.laravel.com/docs/{{version}}/Illuminate/Foundation/Application.html) | `app` |
+| Artisan | [Illuminate\Contracts\Console\Kernel](https://api.laravel.com/docs/{{version}}/Illuminate/Contracts/Console/Kernel.html) | `artisan` |
+| Auth (Instance) | [Illuminate\Contracts\Auth\Guard](https://api.laravel.com/docs/{{version}}/Illuminate/Contracts/Auth/Guard.html) | `auth.driver` |
+| Auth | [Illuminate\Auth\AuthManager](https://api.laravel.com/docs/{{version}}/Illuminate/Auth/AuthManager.html) | `auth` |
+| Blade | [Illuminate\View\Compilers\BladeCompiler](https://api.laravel.com/docs/{{version}}/Illuminate/View/Compilers/BladeCompiler.html) | `blade.compiler` |
+| Broadcast (Instance) | [Illuminate\Contracts\Broadcasting\Broadcaster](https://api.laravel.com/docs/{{version}}/Illuminate/Contracts/Broadcasting/Broadcaster.html) | |
+| Broadcast | [Illuminate\Contracts\Broadcasting\Factory](https://api.laravel.com/docs/{{version}}/Illuminate/Contracts/Broadcasting/Factory.html) | |
+| Bus | [Illuminate\Contracts\Bus\Dispatcher](https://api.laravel.com/docs/{{version}}/Illuminate/Contracts/Bus/Dispatcher.html) | |
+| Cache (Instance) | [Illuminate\Cache\Repository](https://api.laravel.com/docs/{{version}}/Illuminate/Cache/Repository.html) | `cache.store` |
+| Cache | [Illuminate\Cache\CacheManager](https://api.laravel.com/docs/{{version}}/Illuminate/Cache/CacheManager.html) | `cache` |
+| Config | [Illuminate\Config\Repository](https://api.laravel.com/docs/{{version}}/Illuminate/Config/Repository.html) | `config` |
+| Context | [Illuminate\Log\Context\Repository](https://api.laravel.com/docs/{{version}}/Illuminate/Log/Context/Repository.html) | |
+| Cookie | [Illuminate\Cookie\CookieJar](https://api.laravel.com/docs/{{version}}/Illuminate/Cookie/CookieJar.html) | `cookie` |
+| Crypt | [Illuminate\Encryption\Encrypter](https://api.laravel.com/docs/{{version}}/Illuminate/Encryption/Encrypter.html) | `encrypter` |
+| Date | [Illuminate\Support\DateFactory](https://api.laravel.com/docs/{{version}}/Illuminate/Support/DateFactory.html) | `date` |
+| DB (Instance) | [Illuminate\Database\Connection](https://api.laravel.com/docs/{{version}}/Illuminate/Database/Connection.html) | `db.connection` |
+| DB | [Illuminate\Database\DatabaseManager](https://api.laravel.com/docs/{{version}}/Illuminate/Database/DatabaseManager.html) | `db` |
+| Event | [Illuminate\Events\Dispatcher](https://api.laravel.com/docs/{{version}}/Illuminate/Events/Dispatcher.html) | `events` |
+| Exceptions (Instance) | [Illuminate\Contracts\Debug\ExceptionHandler](https://api.laravel.com/docs/{{version}}/Illuminate/Contracts/Debug/ExceptionHandler.html) | |
+| Exceptions | [Illuminate\Foundation\Exceptions\Handler](https://api.laravel.com/docs/{{version}}/Illuminate/Foundation/Exceptions/Handler.html) | |
+| File | [Illuminate\Filesystem\Filesystem](https://api.laravel.com/docs/{{version}}/Illuminate/Filesystem/Filesystem.html) | `files` |
+| Gate | [Illuminate\Contracts\Auth\Access\Gate](https://api.laravel.com/docs/{{version}}/Illuminate/Contracts/Auth/Access/Gate.html) | |
+| Hash | [Illuminate\Contracts\Hashing\Hasher](https://api.laravel.com/docs/{{version}}/Illuminate/Contracts/Hashing/Hasher.html) | `hash` |
+| Http | [Illuminate\Http\Client\Factory](https://api.laravel.com/docs/{{version}}/Illuminate/Http/Client/Factory.html) | |
+| Lang | [Illuminate\Translation\Translator](https://api.laravel.com/docs/{{version}}/Illuminate/Translation/Translator.html) | `translator` |
+| Log | [Illuminate\Log\LogManager](https://api.laravel.com/docs/{{version}}/Illuminate/Log/LogManager.html) | `log` |
+| Mail | [Illuminate\Mail\Mailer](https://api.laravel.com/docs/{{version}}/Illuminate/Mail/Mailer.html) | `mailer` |
+| Notification | [Illuminate\Notifications\ChannelManager](https://api.laravel.com/docs/{{version}}/Illuminate/Notifications/ChannelManager.html) | |
+| Password (Instance) | [Illuminate\Auth\Passwords\PasswordBroker](https://api.laravel.com/docs/{{version}}/Illuminate/Auth/Passwords/PasswordBroker.html) | `auth.password.broker` |
+| Password | [Illuminate\Auth\Passwords\PasswordBrokerManager](https://api.laravel.com/docs/{{version}}/Illuminate/Auth/Passwords/PasswordBrokerManager.html) | `auth.password` |
+| Pipeline (Instance) | [Illuminate\Pipeline\Pipeline](https://api.laravel.com/docs/{{version}}/Illuminate/Pipeline/Pipeline.html) | |
+| Process | [Illuminate\Process\Factory](https://api.laravel.com/docs/{{version}}/Illuminate/Process/Factory.html) | |
+| Queue (Base Class) | [Illuminate\Queue\Queue](https://api.laravel.com/docs/{{version}}/Illuminate/Queue/Queue.html) | |
+| Queue (Instance) | [Illuminate\Contracts\Queue\Queue](https://api.laravel.com/docs/{{version}}/Illuminate/Contracts/Queue/Queue.html) | `queue.connection` |
+| Queue | [Illuminate\Queue\QueueManager](https://api.laravel.com/docs/{{version}}/Illuminate/Queue/QueueManager.html) | `queue` |
+| RateLimiter | [Illuminate\Cache\RateLimiter](https://api.laravel.com/docs/{{version}}/Illuminate/Cache/RateLimiter.html) | |
+| Redirect | [Illuminate\Routing\Redirector](https://api.laravel.com/docs/{{version}}/Illuminate/Routing/Redirector.html) | `redirect` |
+| Redis (Instance) | [Illuminate\Redis\Connections\Connection](https://api.laravel.com/docs/{{version}}/Illuminate/Redis/Connections/Connection.html) | `redis.connection` |
+| Redis | [Illuminate\Redis\RedisManager](https://api.laravel.com/docs/{{version}}/Illuminate/Redis/RedisManager.html) | `redis` |
+| Request | [Illuminate\Http\Request](https://api.laravel.com/docs/{{version}}/Illuminate/Http/Request.html) | `request` |
+| Response (Instance) | [Illuminate\Http\Response](https://api.laravel.com/docs/{{version}}/Illuminate/Http/Response.html) | |
+| Response | [Illuminate\Contracts\Routing\ResponseFactory](https://api.laravel.com/docs/{{version}}/Illuminate/Contracts/Routing/ResponseFactory.html) | |
+| Route | [Illuminate\Routing\Router](https://api.laravel.com/docs/{{version}}/Illuminate/Routing/Router.html) | `router` |
+| Schedule | [Illuminate\Console\Scheduling\Schedule](https://api.laravel.com/docs/{{version}}/Illuminate/Console/Scheduling/Schedule.html) | |
+| Schema | [Illuminate\Database\Schema\Builder](https://api.laravel.com/docs/{{version}}/Illuminate/Database/Schema/Builder.html) | |
+| Session (Instance) | [Illuminate\Session\Store](https://api.laravel.com/docs/{{version}}/Illuminate/Session/Store.html) | `session.store` |
+| Session | [Illuminate\Session\SessionManager](https://api.laravel.com/docs/{{version}}/Illuminate/Session/SessionManager.html) | `session` |
+| Storage (Instance) | [Illuminate\Contracts\Filesystem\Filesystem](https://api.laravel.com/docs/{{version}}/Illuminate/Contracts/Filesystem/Filesystem.html) | `filesystem.disk` |
+| Storage | [Illuminate\Filesystem\FilesystemManager](https://api.laravel.com/docs/{{version}}/Illuminate/Filesystem/FilesystemManager.html) | `filesystem` |
+| URL | [Illuminate\Routing\UrlGenerator](https://api.laravel.com/docs/{{version}}/Illuminate/Routing/UrlGenerator.html) | `url` |
+| Validator (Instance) | [Illuminate\Validation\Validator](https://api.laravel.com/docs/{{version}}/Illuminate/Validation/Validator.html) | |
+| Validator | [Illuminate\Validation\Factory](https://api.laravel.com/docs/{{version}}/Illuminate/Validation/Factory.html) | `validator` |
+| View (Instance) | [Illuminate\View\View](https://api.laravel.com/docs/{{version}}/Illuminate/View/View.html) | |
+| View | [Illuminate\View\Factory](https://api.laravel.com/docs/{{version}}/Illuminate/View/Factory.html) | `view` |
+| Vite | [Illuminate\Foundation\Vite](https://api.laravel.com/docs/{{version}}/Illuminate/Foundation/Vite.html) | |
+
+
diff --git a/filesystem.md b/filesystem.md
index a4b724747aa..f6534104a72 100644
--- a/filesystem.md
+++ b/filesystem.md
@@ -5,18 +5,24 @@
- [The Local Driver](#the-local-driver)
- [The Public Disk](#the-public-disk)
- [Driver Prerequisites](#driver-prerequisites)
+ - [Scoped and Read-Only Filesystems](#scoped-and-read-only-filesystems)
- [Amazon S3 Compatible Filesystems](#amazon-s3-compatible-filesystems)
- [Obtaining Disk Instances](#obtaining-disk-instances)
- [On-Demand Disks](#on-demand-disks)
- [Retrieving Files](#retrieving-files)
- [Downloading Files](#downloading-files)
- [File URLs](#file-urls)
+ - [Temporary URLs](#temporary-urls)
- [File Metadata](#file-metadata)
- [Storing Files](#storing-files)
+ - [Prepending and Appending To Files](#prepending-appending-to-files)
+ - [Copying and Moving Files](#copying-moving-files)
+ - [Automatic Streaming](#automatic-streaming)
- [File Uploads](#file-uploads)
- [File Visibility](#file-visibility)
- [Deleting Files](#deleting-files)
- [Directories](#directories)
+- [Testing](#testing)
- [Custom Filesystems](#custom-filesystems)
@@ -29,25 +35,28 @@ Laravel provides a powerful filesystem abstraction thanks to the wonderful [Flys
Laravel's filesystem configuration file is located at `config/filesystems.php`. Within this file, you may configure all of your filesystem "disks". Each disk represents a particular storage driver and storage location. Example configurations for each supported driver are included in the configuration file so you can modify the configuration to reflect your storage preferences and credentials.
-The `local` driver interacts with files stored locally on the server running the Laravel application while the `s3` driver is used to write to Amazon's S3 cloud storage service.
+The `local` driver interacts with files stored locally on the server running the Laravel application, while the `sftp` storage driver is used for SSH key-based FTP. The `s3` driver is used to write to Amazon's S3 cloud storage service.
-> {tip} You may configure as many disks as you like and may even have multiple disks that use the same driver.
+> [!NOTE]
+> You may configure as many disks as you like and may even have multiple disks that use the same driver.
### The Local Driver
-When using the `local` driver, all file operations are relative to the `root` directory defined in your `filesystems` configuration file. By default, this value is set to the `storage/app` directory. Therefore, the following method would write to `storage/app/example.txt`:
+When using the `local` driver, all file operations are relative to the `root` directory defined in your `filesystems` configuration file. By default, this value is set to the `storage/app/private` directory. Therefore, the following method would write to `storage/app/private/example.txt`:
- use Illuminate\Support\Facades\Storage;
+```php
+use Illuminate\Support\Facades\Storage;
- Storage::disk('local')->put('example.txt', 'Contents');
+Storage::disk('local')->put('example.txt', 'Contents');
+```
### The Public Disk
The `public` disk included in your application's `filesystems` configuration file is intended for files that are going to be publicly accessible. By default, the `public` disk uses the `local` driver and stores its files in `storage/app/public`.
-To make these files accessible from the web, you should create a symbolic link from `public/storage` to `storage/app/public`. Utilizing this folder convention will keep your publicly accessible files in one directory that can be easily shared across deployments when using zero down-time deployment systems like [Envoyer](https://envoyer.io).
+If your `public` disk uses the `local` driver and you want to make these files accessible from the web, you should create a symbolic link from source directory `storage/app/public` to target directory `public/storage`:
To create the symbolic link, you may use the `storage:link` Artisan command:
@@ -57,14 +66,24 @@ php artisan storage:link
Once a file has been stored and the symbolic link has been created, you can create a URL to the files using the `asset` helper:
- echo asset('storage/file.txt');
+```php
+echo asset('storage/file.txt');
+```
You may configure additional symbolic links in your `filesystems` configuration file. Each of the configured links will be created when you run the `storage:link` command:
- 'links' => [
- public_path('storage') => storage_path('app/public'),
- public_path('images') => storage_path('app/images'),
- ],
+```php
+'links' => [
+ public_path('storage') => storage_path('app/public'),
+ public_path('images') => storage_path('app/images'),
+],
+```
+
+The `storage:unlink` command may be used to destroy your configured symbolic links:
+
+```shell
+php artisan storage:unlink
+```
### Driver Prerequisites
@@ -75,10 +94,20 @@ You may configure additional symbolic links in your `filesystems` configuration
Before using the S3 driver, you will need to install the Flysystem S3 package via the Composer package manager:
```shell
-composer require -W league/flysystem-aws-s3-v3 "^3.0"
+composer require league/flysystem-aws-s3-v3 "^3.0" --with-all-dependencies
+```
+
+An S3 disk configuration array is located in your `config/filesystems.php` configuration file. Typically, you should configure your S3 information and credentials using the following environment variables which are referenced by the `config/filesystems.php` configuration file:
+
+```ini
+AWS_ACCESS_KEY_ID=
+ Hello World
+
+```
+
+
+## Installation
+
+To get started, install Folio into your project using the Composer package manager:
+
+```shell
+composer require laravel/folio
+```
+
+After installing Folio, you may execute the `folio:install` Artisan command, which will install Folio's service provider into your application. This service provider registers the directory where Folio will search for routes / pages:
+
+```shell
+php artisan folio:install
+```
+
+
+### Page Paths / URIs
+
+By default, Folio serves pages from your application's `resources/views/pages` directory, but you may customize these directories in your Folio service provider's `boot` method.
+
+For example, sometimes it may be convenient to specify multiple Folio paths in the same Laravel application. You may wish to have a separate directory of Folio pages for your application's "admin" area, while using another directory for the rest of your application's pages.
+
+You may accomplish this using the `Folio::path` and `Folio::uri` methods. The `path` method registers a directory that Folio will scan for pages when routing incoming HTTP requests, while the `uri` method specifies the "base URI" for that directory of pages:
+
+```php
+use Laravel\Folio\Folio;
+
+Folio::path(resource_path('views/pages/guest'))->uri('/');
+
+Folio::path(resource_path('views/pages/admin'))
+ ->uri('/admin')
+ ->middleware([
+ '*' => [
+ 'auth',
+ 'verified',
+
+ // ...
+ ],
+ ]);
+```
+
+
+### Subdomain Routing
+
+You may also route to pages based on the incoming request's subdomain. For example, you may wish to route requests from `admin.example.com` to a different page directory than the rest of your Folio pages. You may accomplish this by invoking the `domain` method after invoking the `Folio::path` method:
+
+```php
+use Laravel\Folio\Folio;
+
+Folio::domain('admin.example.com')
+ ->path(resource_path('views/pages/admin'));
+```
+
+The `domain` method also allows you to capture parts of the domain or subdomain as parameters. These parameters will be injected into your page template:
+
+```php
+use Laravel\Folio\Folio;
+
+Folio::domain('{account}.example.com')
+ ->path(resource_path('views/pages/admin'));
+```
+
+
+## Creating Routes
+
+You may create a Folio route by placing a Blade template in any of your Folio mounted directories. By default, Folio mounts the `resources/views/pages` directory, but you may customize these directories in your Folio service provider's `boot` method.
+
+Once a Blade template has been placed in a Folio mounted directory, you may immediately access it via your browser. For example, a page placed in `pages/schedule.blade.php` may be accessed in your browser at `http://example.com/schedule`.
+
+To quickly view a list of all of your Folio pages / routes, you may invoke the `folio:list` Artisan command:
+
+```shell
+php artisan folio:list
+```
+
+
+### Nested Routes
+
+You may create a nested route by creating one or more directories within one of Folio's directories. For instance, to create a page that is accessible via `/user/profile`, create a `profile.blade.php` template within the `pages/user` directory:
+
+```shell
+php artisan folio:page user/profile
+
+# pages/user/profile.blade.php → /user/profile
+```
+
+
+### Index Routes
+
+Sometimes, you may wish to make a given page the "index" of a directory. By placing an `index.blade.php` template within a Folio directory, any requests to the root of that directory will be routed to that page:
+
+```shell
+php artisan folio:page index
+# pages/index.blade.php → /
+
+php artisan folio:page users/index
+# pages/users/index.blade.php → /users
+```
+
+
+## Route Parameters
+
+Often, you will need to have segments of the incoming request's URL injected into your page so that you can interact with them. For example, you may need to access the "ID" of the user whose profile is being displayed. To accomplish this, you may encapsulate a segment of the page's filename in square brackets:
+
+```shell
+php artisan folio:page "users/[id]"
+
+# pages/users/[id].blade.php → /users/1
+```
+
+Captured segments can be accessed as variables within your Blade template:
+
+```html
+
+ User {{ $id }}
+
+```
+
+To capture multiple segments, you can prefix the encapsulated segment with three dots `...`:
+
+```shell
+php artisan folio:page "users/[...ids]"
+
+# pages/users/[...ids].blade.php → /users/1/2/3
+```
+
+When capturing multiple segments, the captured segments will be injected into the page as an array:
+
+```html
+-
+ @foreach ($ids as $id)
+
- User {{ $id }} + @endforeach +
+ User {{ $user->id }}
+
+```
+
+#### Customizing the Key
+
+Sometimes you may wish to resolve bound Eloquent models using a column other than `id`. To do so, you may specify the column in the page's filename. For example, a page with the filename `[Post:slug].blade.php` will attempt to resolve the bound model via the `slug` column instead of the `id` column.
+
+On Windows, you should use `-` to separate the model name from the key: `[Post-slug].blade.php`.
+
+#### Model Location
+
+By default, Folio will search for your model within your application's `app/Models` directory. However, if needed, you may specify the fully-qualified model class name in your template's filename:
+
+```shell
+php artisan folio:page "users/[.App.Models.User]"
+
+# pages/users/[.App.Models.User].blade.php → /users/1
+```
+
+
+### Soft Deleted Models
+
+By default, models that have been soft deleted are not retrieved when resolving implicit model bindings. However, if you wish, you can instruct Folio to retrieve soft deleted models by invoking the `withTrashed` function within the page's template:
+
+```php
+
+
+
+ User {{ $user->id }}
+
+```
+
+
+## Render Hooks
+
+By default, Folio will return the content of the page's Blade template as the response to the incoming request. However, you may customize the response by invoking the `render` function within the page's template.
+
+The `render` function accepts a closure which will receive the `View` instance being rendered by Folio, allowing you to add additional data to the view or customize the entire response. In addition to receiving the `View` instance, any additional route parameters or model bindings will also be provided to the `render` closure:
+
+```php
+can('view', $post)) {
+ return response('Unauthorized', 403);
+ }
+
+ return $view->with('photos', $post->author->photos);
+}); ?>
+
+
+ {{ $post->content }}
+
+
+
+ This author has also taken {{ count($photos) }} photos.
+
+```
+
+
+## Named Routes
+
+You may specify a name for a given page's route using the `name` function:
+
+```php
+
+ All Users
+
+```
+
+If the page has parameters, you may simply pass their values to the `route` function:
+
+```php
+route('users.show', ['user' => $user]);
+```
+
+
+## Middleware
+
+You can apply middleware to a specific page by invoking the `middleware` function within the page's template:
+
+```php
+
+
+
+ Dashboard
+
+```
+
+Or, to assign middleware to a group of pages, you may chain the `middleware` method after invoking the `Folio::path` method.
+
+To specify which pages the middleware should be applied to, the array of middleware may be keyed using the corresponding URL patterns of the pages they should be applied to. The `*` character may be utilized as a wildcard character:
+
+```php
+use Laravel\Folio\Folio;
+
+Folio::path(resource_path('views/pages'))->middleware([
+ 'admin/*' => [
+ 'auth',
+ 'verified',
+
+ // ...
+ ],
+]);
+```
+
+You may include closures in the array of middleware to define inline, anonymous middleware:
+
+```php
+use Closure;
+use Illuminate\Http\Request;
+use Laravel\Folio\Folio;
+
+Folio::path(resource_path('views/pages'))->middleware([
+ 'admin/*' => [
+ 'auth',
+ 'verified',
+
+ function (Request $request, Closure $next) {
+ // ...
+
+ return $next($request);
+ },
+ ],
+]);
+```
+
+
+## Route Caching
+
+When using Folio, you should always take advantage of [Laravel's route caching capabilities](/docs/{{version}}/routing#route-caching). Folio listens for the `route:cache` Artisan command to ensure that Folio page definitions and route names are properly cached for maximum performance.
diff --git a/fortify.md b/fortify.md
index 50d9cfdb5b2..2293a45b04c 100644
--- a/fortify.md
+++ b/fortify.md
@@ -1,25 +1,24 @@
# Laravel Fortify
- [Introduction](#introduction)
- - [What Is Fortify?](#what-is-fortify)
+ - [What is Fortify?](#what-is-fortify)
- [When Should I Use Fortify?](#when-should-i-use-fortify)
- [Installation](#installation)
- - [The Fortify Service Provider](#the-fortify-service-provider)
- [Fortify Features](#fortify-features)
- [Disabling Views](#disabling-views)
- [Authentication](#authentication)
- [Customizing User Authentication](#customizing-user-authentication)
- - [Customizing The Authentication Pipeline](#customizing-the-authentication-pipeline)
+ - [Customizing the Authentication Pipeline](#customizing-the-authentication-pipeline)
- [Customizing Redirects](#customizing-authentication-redirects)
-- [Two Factor Authentication](#two-factor-authentication)
- - [Enabling Two Factor Authentication](#enabling-two-factor-authentication)
- - [Authenticating With Two Factor Authentication](#authenticating-with-two-factor-authentication)
- - [Disabling Two Factor Authentication](#disabling-two-factor-authentication)
+- [Two-Factor Authentication](#two-factor-authentication)
+ - [Enabling Two-Factor Authentication](#enabling-two-factor-authentication)
+ - [Authenticating With Two-Factor Authentication](#authenticating-with-two-factor-authentication)
+ - [Disabling Two-Factor Authentication](#disabling-two-factor-authentication)
- [Registration](#registration)
- [Customizing Registration](#customizing-registration)
- [Password Reset](#password-reset)
- - [Requesting A Password Reset Link](#requesting-a-password-reset-link)
- - [Resetting The Password](#resetting-the-password)
+ - [Requesting a Password Reset Link](#requesting-a-password-reset-link)
+ - [Resetting the Password](#resetting-the-password)
- [Customizing Password Resets](#customizing-password-resets)
- [Email Verification](#email-verification)
- [Protecting Routes](#protecting-routes)
@@ -32,23 +31,24 @@
Since Fortify does not provide its own user interface, it is meant to be paired with your own user interface which makes requests to the routes it registers. We will discuss exactly how to make requests to these routes in the remainder of this documentation.
-> {tip} Remember, Fortify is a package that is meant to give you a head start implementing Laravel's authentication features. **You are not required to use it.** You are always free to manually interact with Laravel's authentication services by following the documentation available in the [authentication](/docs/{{version}}/authentication), [password reset](/docs/{{version}}/passwords), and [email verification](/docs/{{version}}/verification) documentation.
+> [!NOTE]
+> Remember, Fortify is a package that is meant to give you a head start implementing Laravel's authentication features. **You are not required to use it.** You are always free to manually interact with Laravel's authentication services by following the documentation available in the [authentication](/docs/{{version}}/authentication), [password reset](/docs/{{version}}/passwords), and [email verification](/docs/{{version}}/verification) documentation.
-### What Is Fortify?
+### What is Fortify?
As mentioned previously, Laravel Fortify is a frontend agnostic authentication backend implementation for Laravel. Fortify registers the routes and controllers needed to implement all of Laravel's authentication features, including login, registration, password reset, email verification, and more.
**You are not required to use Fortify in order to use Laravel's authentication features.** You are always free to manually interact with Laravel's authentication services by following the documentation available in the [authentication](/docs/{{version}}/authentication), [password reset](/docs/{{version}}/passwords), and [email verification](/docs/{{version}}/verification) documentation.
-If you are new to Laravel, you may wish to explore the [Laravel Breeze](/docs/{{version}}/starter-kits) application starter kit before attempting to use Laravel Fortify. Laravel Breeze provides an authentication scaffolding for your application that includes a user interface built with [Tailwind CSS](https://tailwindcss.com). Unlike Fortify, Breeze publishes its routes and controllers directly into your application. This allows you to study and get comfortable with Laravel's authentication features before allowing Laravel Fortify to implement these features for you.
+If you are new to Laravel, you may wish to explore [our application starter kits](/docs/{{version}}/starter-kits). Laravel's application starter kits use Fortify internally to provide authentication scaffolding for your application that includes a user interface built with [Tailwind CSS](https://tailwindcss.com). This allows you to study and get comfortable with Laravel's authentication features.
-Laravel Fortify essentially takes the routes and controllers of Laravel Breeze and offers them as a package that does not include a user interface. This allows you to still quickly scaffold the backend implementation of your application's authentication layer without being tied to any particular frontend opinions.
+Laravel Fortify essentially takes the routes and controllers of our application starter kits and offers them as a package that does not include a user interface. This allows you to still quickly scaffold the backend implementation of your application's authentication layer without being tied to any particular frontend opinions.
### When Should I Use Fortify?
-You may be wondering when it is appropriate to use Laravel Fortify. First, if you are using one of Laravel's [application starter kits](/docs/{{version}}/starter-kits), you do not need to install Laravel Fortify since all of Laravel's application starter kits already provide a full authentication implementation.
+You may be wondering when it is appropriate to use Laravel Fortify. First, if you are using one of Laravel's [application starter kits](/docs/{{version}}/starter-kits), you do not need to install Laravel Fortify since all of Laravel's application starter kits use Fortify and already provide a full authentication implementation.
If you are not using an application starter kit and your application needs authentication features, you have two options: manually implement your application's authentication features or use Laravel Fortify to provide the backend implementation of these features.
@@ -57,7 +57,7 @@ If you choose to install Fortify, your user interface will make requests to Fort
If you choose to manually interact with Laravel's authentication services instead of using Fortify, you may do so by following the documentation available in the [authentication](/docs/{{version}}/authentication), [password reset](/docs/{{version}}/passwords), and [email verification](/docs/{{version}}/verification) documentation.
-#### Laravel Fortify & Laravel Sanctum
+#### Laravel Fortify and Laravel Sanctum
Some developers become confused regarding the difference between [Laravel Sanctum](/docs/{{version}}/sanctum) and Laravel Fortify. Because the two packages solve two different but related problems, Laravel Fortify and Laravel Sanctum are not mutually exclusive or competing packages.
@@ -74,13 +74,13 @@ To get started, install Fortify using the Composer package manager:
composer require laravel/fortify
```
-Next, publish Fortify's resources using the `vendor:publish` command:
+Next, publish Fortify's resources using the `fortify:install` Artisan command:
```shell
-php artisan vendor:publish --provider="Laravel\Fortify\FortifyServiceProvider"
+php artisan fortify:install
```
-This command will publish Fortify's actions to your `app/Actions` directory, which will be created if it does not exist. In addition, Fortify's configuration file and migrations will be published.
+This command will publish Fortify's actions to your `app/Actions` directory, which will be created if it does not exist. In addition, the `FortifyServiceProvider`, configuration file, and all necessary database migrations will be published.
Next, you should migrate your database:
@@ -88,17 +88,10 @@ Next, you should migrate your database:
php artisan migrate
```
-
-### The Fortify Service Provider
-
-The `vendor:publish` command discussed above will also publish the `App\Providers\FortifyServiceProvider` class. You should ensure this class is registered within the `providers` array of your application's `config/app.php` configuration file.
-
-The Fortify service provider registers the actions that Fortify published and instructs Fortify to use them when their respective tasks are executed by Fortify.
-
### Fortify Features
-The `fortify` configuration file contains a `features` configuration array. This array defines which backend routes / features Fortify will expose by default. If you are not using Fortify in combination with [Laravel Jetstream](https://jetstream.laravel.com), we recommend that you only enable the following features, which are the basic authentication features provided by most Laravel applications:
+The `fortify` configuration file contains a `features` configuration array. This array defines which backend routes / features Fortify will expose by default. We recommend that you only enable the following features, which are the basic authentication features provided by most Laravel applications:
```php
'features' => [
@@ -118,7 +111,7 @@ By default, Fortify defines routes that are intended to return views, such as a
```
-#### Disabling Views & Password Reset
+#### Disabling Views and Password Reset
If you choose to disable Fortify's views and you will be implementing password reset features for your application, you should still define a route named `password.reset` that is responsible for displaying your application's "reset password" view. This is necessary because Laravel's `Illuminate\Auth\Notifications\ResetPassword` notification will generate the password reset URL via the `password.reset` named route.
@@ -129,21 +122,21 @@ To get started, we need to instruct Fortify how to return our "login" view. Reme
All of the authentication view's rendering logic may be customized using the appropriate methods available via the `Laravel\Fortify\Fortify` class. Typically, you should call this method from the `boot` method of your application's `App\Providers\FortifyServiceProvider` class. Fortify will take care of defining the `/login` route that returns this view:
- use Laravel\Fortify\Fortify;
+```php
+use Laravel\Fortify\Fortify;
- /**
- * Bootstrap any application services.
- *
- * @return void
- */
- public function boot()
- {
- Fortify::loginView(function () {
- return view('auth.login');
- });
+/**
+ * Bootstrap any application services.
+ */
+public function boot(): void
+{
+ Fortify::loginView(function () {
+ return view('auth.login');
+ });
- // ...
- }
+ // ...
+}
+```
Your login template should include a form that makes a POST request to `/login`. The `/login` endpoint expects a string `email` / `username` and a `password`. The name of the email / username field should match the `username` value within the `config/fortify.php` configuration file. In addition, a boolean `remember` field may be provided to indicate that the user would like to use the "remember me" functionality provided by Laravel.
@@ -166,10 +159,8 @@ use Laravel\Fortify\Fortify;
/**
* Bootstrap any application services.
- *
- * @return void
*/
-public function boot()
+public function boot(): void
{
Fortify::authenticateUsing(function (Request $request) {
$user = User::where('email', $request->email)->first();
@@ -190,7 +181,7 @@ public function boot()
You may customize the authentication guard used by Fortify within your application's `fortify` configuration file. However, you should ensure that the configured guard is an implementation of `Illuminate\Contracts\Auth\StatefulGuard`. If you are attempting to use Laravel Fortify to authenticate an SPA, you should use Laravel's default `web` guard in combination with [Laravel Sanctum](https://laravel.com/docs/sanctum).
-### Customizing The Authentication Pipeline
+### Customizing the Authentication Pipeline
Laravel Fortify authenticates login requests through a pipeline of invokable classes. If you would like, you may define a custom pipeline of classes that login requests should be piped through. Each class should have an `__invoke` method which receives the incoming `Illuminate\Http\Request` instance and, like [middleware](/docs/{{version}}/middleware), a `$next` variable that is invoked in order to pass the request to the next class in the pipeline.
@@ -200,15 +191,18 @@ The example below contains the default pipeline definition that you may use as a
```php
use Laravel\Fortify\Actions\AttemptToAuthenticate;
+use Laravel\Fortify\Actions\CanonicalizeUsername;
use Laravel\Fortify\Actions\EnsureLoginIsNotThrottled;
use Laravel\Fortify\Actions\PrepareAuthenticatedSession;
use Laravel\Fortify\Actions\RedirectIfTwoFactorAuthenticatable;
+use Laravel\Fortify\Features;
use Laravel\Fortify\Fortify;
use Illuminate\Http\Request;
Fortify::authenticateThrough(function (Request $request) {
return array_filter([
config('fortify.limiters.login') ? null : EnsureLoginIsNotThrottled::class,
+ config('fortify.lowercase_usernames') ? CanonicalizeUsername::class : null,
Features::enabled(Features::twoFactorAuthentication()) ? RedirectIfTwoFactorAuthenticatable::class : null,
AttemptToAuthenticate::class,
PrepareAuthenticatedSession::class,
@@ -216,6 +210,15 @@ Fortify::authenticateThrough(function (Request $request) {
});
```
+#### Authentication Throttling
+
+By default, Fortify will throttle authentication attempts using the `EnsureLoginIsNotThrottled` middleware. This middleware throttles attempts that are unique to a username and IP address combination.
+
+Some applications may require a different approach to throttling authentication attempts, such as throttling by IP address alone. Therefore, Fortify allows you to specify your own [rate limiter](/docs/{{version}}/routing#rate-limiting) via the `fortify.limiters.login` configuration option. Of course, this configuration option is located in your application's `config/fortify.php` configuration file.
+
+> [!NOTE]
+> Utilizing a mixture of throttling, [two-factor authentication](/docs/{{version}}/fortify#two-factor-authentication), and an external web application firewall (WAF) will provide the most robust defense for your legitimate application users.
+
### Customizing Redirects
@@ -228,10 +231,8 @@ use Laravel\Fortify\Contracts\LogoutResponse;
/**
* Register any application services.
- *
- * @return void
*/
-public function register()
+public function register(): void
{
$this->app->instance(LogoutResponse::class, new class implements LogoutResponse {
public function toResponse($request)
@@ -243,9 +244,9 @@ public function register()
```
-## Two Factor Authentication
+## Two-Factor Authentication
-When Fortify's two factor authentication feature is enabled, the user is required to input a six digit numeric token during the authentication process. This token is generated using a time-based one-time password (TOTP) that can be retrieved from any TOTP compatible mobile authentication application such as Google Authenticator.
+When Fortify's two-factor authentication feature is enabled, the user is required to input a six digit numeric token during the authentication process. This token is generated using a time-based one-time password (TOTP) that can be retrieved from any TOTP compatible mobile authentication application such as Google Authenticator.
Before getting started, you should first ensure that your application's `App\Models\User` model uses the `Laravel\Fortify\TwoFactorAuthenticatable` trait:
@@ -262,37 +263,56 @@ class User extends Authenticatable
{
use Notifiable, TwoFactorAuthenticatable;
}
- ```
+```
-Next, you should build a screen within your application where users can manage their two factor authentication settings. This screen should allow the user to enable and disable two factor authentication, as well as regenerate their two factor authentication recovery codes.
+Next, you should build a screen within your application where users can manage their two-factor authentication settings. This screen should allow the user to enable and disable two-factor authentication, as well as regenerate their two-factor authentication recovery codes.
-> By default, the `features` array of the `fortify` configuration file instructs Fortify's two factor authentication settings to require password confirmation before modification. Therefore, your application should implement Fortify's [password confirmation](#password-confirmation) feature before continuing.
+> By default, the `features` array of the `fortify` configuration file instructs Fortify's two-factor authentication settings to require password confirmation before modification. Therefore, your application should implement Fortify's [password confirmation](#password-confirmation) feature before continuing.
-### Enabling Two Factor Authentication
+### Enabling Two-Factor Authentication
-To enable two factor authentication, your application should make a POST request to the `/user/two-factor-authentication` endpoint defined by Fortify. If the request is successful, the user will be redirected back to the previous URL and the `status` session variable will be set to `two-factor-authentication-enabled`. You may detect this `status` session variable within your templates to display the appropriate success message. If the request was an XHR request, `200` HTTP response will be returned:
+To begin enabling two-factor authentication, your application should make a POST request to the `/user/two-factor-authentication` endpoint defined by Fortify. If the request is successful, the user will be redirected back to the previous URL and the `status` session variable will be set to `two-factor-authentication-enabled`. You may detect this `status` session variable within your templates to display the appropriate success message. If the request was an XHR request, `200` HTTP response will be returned.
+
+After choosing to enable two-factor authentication, the user must still "confirm" their two-factor authentication configuration by providing a valid two-factor authentication code. So, your "success" message should instruct the user that two-factor authentication confirmation is still required:
```html
@if (session('status') == 'two-factor-authentication-enabled')
-
- Two factor authentication has been enabled.
+
+
+
+
+### Numbers
+
+
+ Please finish configuring two-factor authentication below.
@endif
```
-Next, you should display the two factor authentication QR code for the user to scan into their authenticator application. If you are using Blade to render your application's frontend, you may retrieve the QR code SVG using the `twoFactorQrCodeSvg` method available on the user instance:
+Next, you should display the two-factor authentication QR code for the user to scan into their authenticator application. If you are using Blade to render your application's frontend, you may retrieve the QR code SVG using the `twoFactorQrCodeSvg` method available on the user instance:
```php
$request->user()->twoFactorQrCodeSvg();
```
-If you are building a JavaScript powered frontend, you may make an XHR GET request to the `/user/two-factor-qr-code` endpoint to retrieve the user's two factor authentication QR code. This endpoint will return a JSON object containing an `svg` key.
+If you are building a JavaScript powered frontend, you may make an XHR GET request to the `/user/two-factor-qr-code` endpoint to retrieve the user's two-factor authentication QR code. This endpoint will return a JSON object containing an `svg` key.
+
+
+#### Confirming Two-Factor Authentication
+
+In addition to displaying the user's two-factor authentication QR code, you should provide a text input where the user can supply a valid authentication code to "confirm" their two-factor authentication configuration. This code should be provided to the Laravel application via a POST request to the `/user/confirmed-two-factor-authentication` endpoint defined by Fortify.
+
+If the request is successful, the user will be redirected back to the previous URL and the `status` session variable will be set to `two-factor-authentication-confirmed`:
+
+```html
+@if (session('status') == 'two-factor-authentication-confirmed')
+
+ Two-factor authentication confirmed and enabled successfully.
+
+@endif
+```
+
+If the request to the two-factor authentication confirmation endpoint was made via an XHR request, a `200` HTTP response will be returned.
-#### Displaying The Recovery Codes
+#### Displaying the Recovery Codes
-You should also display the user's two factor recovery codes. These recovery codes allow the user to authenticate if they lose access to their mobile device. If you are using Blade to render your application's frontend, you may access the recovery codes via the authenticated user instance:
+You should also display the user's two-factor recovery codes. These recovery codes allow the user to authenticate if they lose access to their mobile device. If you are using Blade to render your application's frontend, you may access the recovery codes via the authenticated user instance:
```php
(array) $request->user()->recoveryCodes()
@@ -303,21 +323,19 @@ If you are building a JavaScript powered frontend, you may make an XHR GET reque
To regenerate the user's recovery codes, your application should make a POST request to the `/user/two-factor-recovery-codes` endpoint.
-### Authenticating With Two Factor Authentication
+### Authenticating With Two-Factor Authentication
-During the authentication process, Fortify will automatically redirect the user to your application's two factor authentication challenge screen. However, if your application is making an XHR login request, the JSON response returned after a successful authentication attempt will contain a JSON object that has a `two_factor` boolean property. You should inspect this value to know whether you should redirect to your application's two factor authentication challenge screen.
+During the authentication process, Fortify will automatically redirect the user to your application's two-factor authentication challenge screen. However, if your application is making an XHR login request, the JSON response returned after a successful authentication attempt will contain a JSON object that has a `two_factor` boolean property. You should inspect this value to know whether you should redirect to your application's two-factor authentication challenge screen.
-To begin implementing two factor authentication functionality, we need to instruct Fortify how to return our two factor authentication challenge view. All of Fortify's authentication view rendering logic may be customized using the appropriate methods available via the `Laravel\Fortify\Fortify` class. Typically, you should call this method from the `boot` method of your application's `App\Providers\FortifyServiceProvider` class:
+To begin implementing two-factor authentication functionality, we need to instruct Fortify how to return our two-factor authentication challenge view. All of Fortify's authentication view rendering logic may be customized using the appropriate methods available via the `Laravel\Fortify\Fortify` class. Typically, you should call this method from the `boot` method of your application's `App\Providers\FortifyServiceProvider` class:
```php
use Laravel\Fortify\Fortify;
/**
* Bootstrap any application services.
- *
- * @return void
*/
-public function boot()
+public function boot(): void
{
Fortify::twoFactorChallengeView(function () {
return view('auth.two-factor-challenge');
@@ -331,29 +349,27 @@ Fortify will take care of defining the `/two-factor-challenge` route that return
If the login attempt is successful, Fortify will redirect the user to the URI configured via the `home` configuration option within your application's `fortify` configuration file. If the login request was an XHR request, a 204 HTTP response will be returned.
-If the request was not successful, the user will be redirected back to the two factor challenge screen and the validation errors will be available to you via the shared `$errors` [Blade template variable](/docs/{{version}}/validation#quick-displaying-the-validation-errors). Or, in the case of an XHR request, the validation errors will be returned with a 422 HTTP response.
+If the request was not successful, the user will be redirected back to the two-factor challenge screen and the validation errors will be available to you via the shared `$errors` [Blade template variable](/docs/{{version}}/validation#quick-displaying-the-validation-errors). Or, in the case of an XHR request, the validation errors will be returned with a 422 HTTP response.
-### Disabling Two Factor Authentication
+### Disabling Two-Factor Authentication
-To disable two factor authentication, your application should make a DELETE request to the `/user/two-factor-authentication` endpoint. Remember, Fortify's two factor authentication endpoints require [password confirmation](#password-confirmation) prior to being called.
+To disable two-factor authentication, your application should make a DELETE request to the `/user/two-factor-authentication` endpoint. Remember, Fortify's two-factor authentication endpoints require [password confirmation](#password-confirmation) prior to being called.
## Registration
To begin implementing our application's registration functionality, we need to instruct Fortify how to return our "register" view. Remember, Fortify is a headless authentication library. If you would like a frontend implementation of Laravel's authentication features that are already completed for you, you should use an [application starter kit](/docs/{{version}}/starter-kits).
-All of the Fortify's view rendering logic may be customized using the appropriate methods available via the `Laravel\Fortify\Fortify` class. Typically, you should call this method from the `boot` method of your `App\Providers\FortifyServiceProvider` class:
+All of Fortify's view rendering logic may be customized using the appropriate methods available via the `Laravel\Fortify\Fortify` class. Typically, you should call this method from the `boot` method of your `App\Providers\FortifyServiceProvider` class:
```php
use Laravel\Fortify\Fortify;
/**
* Bootstrap any application services.
- *
- * @return void
*/
-public function boot()
+public function boot(): void
{
Fortify::registerView(function () {
return view('auth.register');
@@ -367,7 +383,7 @@ Fortify will take care of defining the `/register` route that returns this view.
The `/register` endpoint expects a string `name`, string email address / username, `password`, and `password_confirmation` fields. The name of the email / username field should match the `username` configuration value defined within your application's `fortify` configuration file.
-If the registration attempt is successful, Fortify will redirect the user to the URI configured via the `home` configuration option within your application's `fortify` configuration file. If the login request was an XHR request, a 200 HTTP response will be returned.
+If the registration attempt is successful, Fortify will redirect the user to the URI configured via the `home` configuration option within your application's `fortify` configuration file. If the request was an XHR request, a 201 HTTP response will be returned.
If the request was not successful, the user will be redirected back to the registration screen and the validation errors will be available to you via the shared `$errors` [Blade template variable](/docs/{{version}}/validation#quick-displaying-the-validation-errors). Or, in the case of an XHR request, the validation errors will be returned with a 422 HTTP response.
@@ -380,7 +396,7 @@ The user validation and creation process may be customized by modifying the `App
## Password Reset
-### Requesting A Password Reset Link
+### Requesting a Password Reset Link
To begin implementing our application's password reset functionality, we need to instruct Fortify how to return our "forgot password" view. Remember, Fortify is a headless authentication library. If you would like a frontend implementation of Laravel's authentication features that are already completed for you, you should use an [application starter kit](/docs/{{version}}/starter-kits).
@@ -391,10 +407,8 @@ use Laravel\Fortify\Fortify;
/**
* Bootstrap any application services.
- *
- * @return void
*/
-public function boot()
+public function boot(): void
{
Fortify::requestPasswordResetLinkView(function () {
return view('auth.forgot-password');
@@ -409,11 +423,13 @@ Fortify will take care of defining the `/forgot-password` endpoint that returns
The `/forgot-password` endpoint expects a string `email` field. The name of this field / database column should match the `email` configuration value within your application's `fortify` configuration file.
-#### Handling The Password Reset Link Request Response
+#### Handling the Password Reset Link Request Response
If the password reset link request was successful, Fortify will redirect the user back to the `/forgot-password` endpoint and send an email to the user with a secure link they can use to reset their password. If the request was an XHR request, a 200 HTTP response will be returned.
-After being redirected back to the `/forgot-password` endpoint after a successful request, the `status` session variable may be used to display the status of the password reset link request attempt. The value of this session variable will match one of the translation strings defined within your application's `passwords` [language file](/docs/{{version}}/localization):
+After being redirected back to the `/forgot-password` endpoint after a successful request, the `status` session variable may be used to display the status of the password reset link request attempt.
+
+The value of the `$status` session variable will match one of the translation strings defined within your application's `passwords` [language file](/docs/{{version}}/localization). If you would like to customize this value and have not published Laravel's language files, you may do so via the `lang:publish` Artisan command:
```html
@if (session('status'))
@@ -426,7 +442,7 @@ After being redirected back to the `/forgot-password` endpoint after a successfu
If the request was not successful, the user will be redirected back to the request password reset link screen and the validation errors will be available to you via the shared `$errors` [Blade template variable](/docs/{{version}}/validation#quick-displaying-the-validation-errors). Or, in the case of an XHR request, the validation errors will be returned with a 422 HTTP response.
-### Resetting The Password
+### Resetting the Password
To finish implementing our application's password reset functionality, we need to instruct Fortify how to return our "reset password" view.
@@ -434,15 +450,14 @@ All of Fortify's view rendering logic may be customized using the appropriate me
```php
use Laravel\Fortify\Fortify;
+use Illuminate\Http\Request;
/**
* Bootstrap any application services.
- *
- * @return void
*/
-public function boot()
+public function boot(): void
{
- Fortify::resetPasswordView(function ($request) {
+ Fortify::resetPasswordView(function (Request $request) {
return view('auth.reset-password', ['request' => $request]);
});
@@ -455,7 +470,7 @@ Fortify will take care of defining the route to display this view. Your `reset-p
The `/reset-password` endpoint expects a string `email` field, a `password` field, a `password_confirmation` field, and a hidden field named `token` that contains the value of `request()->route('token')`. The name of the "email" field / database column should match the `email` configuration value defined within your application's `fortify` configuration file.
-#### Handling The Password Reset Response
+#### Handling the Password Reset Response
If the password reset request was successful, Fortify will redirect back to the `/login` route so that the user can log in with their new password. In addition, a `status` session variable will be set so that you may display the successful status of the reset on your login screen:
@@ -490,10 +505,8 @@ use Laravel\Fortify\Fortify;
/**
* Bootstrap any application services.
- *
- * @return void
*/
-public function boot()
+public function boot(): void
{
Fortify::verifyEmailView(function () {
return view('auth.verify-email');
@@ -525,7 +538,7 @@ If the request to resend the verification link email was successful, Fortify wil
### Protecting Routes
-To specify that a route or group of routes requires that the user has verified their email address, you should attach Laravel's built-in `verified` middleware to the route. This middleware is registered within your application's `App\Http\Kernel` class:
+To specify that a route or group of routes requires that the user has verified their email address, you should attach Laravel's built-in `verified` middleware to the route. The `verified` middleware alias is automatically registered by Laravel and serves as an alias for the `Illuminate\Auth\Middleware\EnsureEmailIsVerified` middleware:
```php
Route::get('/dashboard', function () {
@@ -547,10 +560,8 @@ use Laravel\Fortify\Fortify;
/**
* Bootstrap any application services.
- *
- * @return void
*/
-public function boot()
+public function boot(): void
{
Fortify::confirmPasswordView(function () {
return view('auth.confirm-password');
diff --git a/frontend.md b/frontend.md
new file mode 100644
index 00000000000..31da734876e
--- /dev/null
+++ b/frontend.md
@@ -0,0 +1,184 @@
+# Frontend
+
+- [Introduction](#introduction)
+- [Using PHP](#using-php)
+ - [PHP and Blade](#php-and-blade)
+ - [Livewire](#livewire)
+ - [Starter Kits](#php-starter-kits)
+- [Using React or Vue](#using-react-or-vue)
+ - [Inertia](#inertia)
+ - [Starter Kits](#inertia-starter-kits)
+- [Bundling Assets](#bundling-assets)
+
+
+## Introduction
+
+Laravel is a backend framework that provides all of the features you need to build modern web applications, such as [routing](/docs/{{version}}/routing), [validation](/docs/{{version}}/validation), [caching](/docs/{{version}}/cache), [queues](/docs/{{version}}/queues), [file storage](/docs/{{version}}/filesystem), and more. However, we believe it's important to offer developers a beautiful full-stack experience, including powerful approaches for building your application's frontend.
+
+There are two primary ways to tackle frontend development when building an application with Laravel, and which approach you choose is determined by whether you would like to build your frontend by leveraging PHP or by using JavaScript frameworks such as Vue and React. We'll discuss both of these options below so that you can make an informed decision regarding the best approach to frontend development for your application.
+
+
+## Using PHP
+
+
+### PHP and Blade
+
+In the past, most PHP applications rendered HTML to the browser using simple HTML templates interspersed with PHP `echo` statements which render data that was retrieved from a database during the request:
+
+```blade
+
+
+ Hello, name; ?>
+ +
+```
+
+In Laravel, this approach to rendering HTML can still be achieved using [views](/docs/{{version}}/views) and [Blade](/docs/{{version}}/blade). Blade is an extremely light-weight templating language that provides convenient, short syntax for displaying data, iterating over data, and more:
+
+```blade
++ +
+ @foreach ($users as $user)
+ Hello, {{ $user->name }}
+ @endforeach +
+```
+
+When building applications in this fashion, form submissions and other page interactions typically receive an entirely new HTML document from the server and the entire page is re-rendered by the browser. Even today, many applications may be perfectly suited to having their frontends constructed in this way using simple Blade templates.
+
+
+#### Growing Expectations
+
+However, as user expectations regarding web applications have matured, many developers have found the need to build more dynamic frontends with interactions that feel more polished. In light of this, some developers choose to begin building their application's frontend using JavaScript frameworks such as Vue and React.
+
+Others, preferring to stick with the backend language they are comfortable with, have developed solutions that allow the construction of modern web application UIs while still primarily utilizing their backend language of choice. For example, in the [Rails](https://rubyonrails.org/) ecosystem, this has spurred the creation of libraries such as [Turbo](https://turbo.hotwired.dev/) [Hotwire](https://hotwired.dev/), and [Stimulus](https://stimulus.hotwired.dev/).
+
+Within the Laravel ecosystem, the need to create modern, dynamic frontends by primarily using PHP has led to the creation of [Laravel Livewire](https://livewire.laravel.com) and [Alpine.js](https://alpinejs.dev/).
+
+
+### Livewire
+
+[Laravel Livewire](https://livewire.laravel.com) is a framework for building Laravel powered frontends that feel dynamic, modern, and alive just like frontends built with modern JavaScript frameworks like Vue and React.
+
+When using Livewire, you will create Livewire "components" that render a discrete portion of your UI and expose methods and data that can be invoked and interacted with from your application's frontend. For example, a simple "Counter" component might look like the following:
+
+```php
+count++;
+ }
+
+ public function render()
+ {
+ return view('livewire.counter');
+ }
+}
+```
+
+And, the corresponding template for the counter would be written like so:
+
+```blade
++ @endforeach +
+
+
+```
+
+As you can see, Livewire enables you to write new HTML attributes such as `wire:click` that connect your Laravel application's frontend and backend. In addition, you can render your component's current state using simple Blade expressions.
+
+For many, Livewire has revolutionized frontend development with Laravel, allowing them to stay within the comfort of Laravel while constructing modern, dynamic web applications. Typically, developers using Livewire will also utilize [Alpine.js](https://alpinejs.dev/) to "sprinkle" JavaScript onto their frontend only where it is needed, such as in order to render a dialog window.
+
+If you're new to Laravel, we recommend getting familiar with the basic usage of [views](/docs/{{version}}/views) and [Blade](/docs/{{version}}/blade). Then, consult the official [Laravel Livewire documentation](https://livewire.laravel.com/docs) to learn how to take your application to the next level with interactive Livewire components.
+
+
+### Starter Kits
+
+If you would like to build your frontend using PHP and Livewire, you can leverage our [Livewire starter kit](/docs/{{version}}/starter-kits) to jump-start your application's development.
+
+
+## Using React or Vue
+
+Although it's possible to build modern frontends using Laravel and Livewire, many developers still prefer to leverage the power of a JavaScript framework like React or Vue. This allows developers to take advantage of the rich ecosystem of JavaScript packages and tools available via NPM.
+
+However, without additional tooling, pairing Laravel with React or Vue would leave us needing to solve a variety of complicated problems such as client-side routing, data hydration, and authentication. Client-side routing is often simplified by using opinionated React / Vue frameworks such as [Next](https://nextjs.org/) and [Nuxt](https://nuxt.com/); however, data hydration and authentication remain complicated and cumbersome problems to solve when pairing a backend framework like Laravel with these frontend frameworks.
+
+In addition, developers are left maintaining two separate code repositories, often needing to coordinate maintenance, releases, and deployments across both repositories. While these problems are not insurmountable, we don't believe it's a productive or enjoyable way to develop applications.
+
+
+### Inertia
+
+Thankfully, Laravel offers the best of both worlds. [Inertia](https://inertiajs.com) bridges the gap between your Laravel application and your modern React or Vue frontend, allowing you to build full-fledged, modern frontends using React or Vue while leveraging Laravel routes and controllers for routing, data hydration, and authentication — all within a single code repository. With this approach, you can enjoy the full power of both Laravel and React / Vue without crippling the capabilities of either tool.
+
+After installing Inertia into your Laravel application, you will write routes and controllers like normal. However, instead of returning a Blade template from your controller, you will return an Inertia page:
+
+```php
+ User::findOrFail($id)
+ ]);
+ }
+}
+```
+
+An Inertia page corresponds to a React or Vue component, typically stored within the `resources/js/pages` directory of your application. The data given to the page via the `Inertia::render` method will be used to hydrate the "props" of the page component:
+
+```jsx
+import Layout from '@/layouts/authenticated';
+import { Head } from '@inertiajs/react';
+
+export default function Show({ user }) {
+ return (
+ {{ $count }}
+Welcome
+Hello {user.name}, welcome to Inertia.
+ + ) +} +``` + +As you can see, Inertia allows you to leverage the full power of React or Vue when building your frontend, while providing a light-weight bridge between your Laravel powered backend and your JavaScript powered frontend. + +#### Server-Side Rendering + +If you're concerned about diving into Inertia because your application requires server-side rendering, don't worry. Inertia offers [server-side rendering support](https://inertiajs.com/server-side-rendering). And, when deploying your application via [Laravel Cloud](https://cloud.laravel.com) or [Laravel Forge](https://forge.laravel.com), it's a breeze to ensure that Inertia's server-side rendering process is always running. + + +### Starter Kits + +If you would like to build your frontend using Inertia and Vue / React, you can leverage our [React or Vue application starter kits](/docs/{{version}}/starter-kits) to jump-start your application's development. Both of these starter kits scaffold your application's backend and frontend authentication flow using Inertia, Vue / React, [Tailwind](https://tailwindcss.com), and [Vite](https://vitejs.dev) so that you can start building your next big idea. + + +## Bundling Assets + +Regardless of whether you choose to develop your frontend using Blade and Livewire or Vue / React and Inertia, you will likely need to bundle your application's CSS into production-ready assets. Of course, if you choose to build your application's frontend with Vue or React, you will also need to bundle your components into browser ready JavaScript assets. + +By default, Laravel utilizes [Vite](https://vitejs.dev) to bundle your assets. Vite provides lightning-fast build times and near instantaneous Hot Module Replacement (HMR) during local development. In all new Laravel applications, including those using our [starter kits](/docs/{{version}}/starter-kits), you will find a `vite.config.js` file that loads our light-weight Laravel Vite plugin that makes Vite a joy to use with Laravel applications. + +The fastest way to get started with Laravel and Vite is by beginning your application's development using [our application starter kits](/docs/{{version}}/starter-kits), which jump-starts your application by providing frontend and backend authentication scaffolding. + +> [!NOTE] +> For more detailed documentation on utilizing Vite with Laravel, please see our [dedicated documentation on bundling and compiling your assets](/docs/{{version}}/vite). diff --git a/hashing.md b/hashing.md index 414362496d8..2210343cae5 100644 --- a/hashing.md +++ b/hashing.md @@ -4,8 +4,9 @@ - [Configuration](#configuration) - [Basic Usage](#basic-usage) - [Hashing Passwords](#hashing-passwords) - - [Verifying That A Password Matches A Hash](#verifying-that-a-password-matches-a-hash) - - [Determining If A Password Needs To Be Rehashed](#determining-if-a-password-needs-to-be-rehashed) + - [Verifying That a Password Matches a Hash](#verifying-that-a-password-matches-a-hash) + - [Determining if a Password Needs to be Rehashed](#determining-if-a-password-needs-to-be-rehashed) +- [Hash Algorithm Verification](#hash-algorithm-verification) ## Introduction @@ -17,7 +18,13 @@ Bcrypt is a great choice for hashing passwords because its "work factor" is adju ## Configuration -The default hashing driver for your application is configured in your application's `config/hashing.php` configuration file. There are currently several supported drivers: [Bcrypt](https://en.wikipedia.org/wiki/Bcrypt) and [Argon2](https://en.wikipedia.org/wiki/Argon2) (Argon2i and Argon2id variants). +By default, Laravel uses the `bcrypt` hashing driver when hashing data. However, several other hashing drivers are supported, including [argon](https://en.wikipedia.org/wiki/Argon2) and [argon2id](https://en.wikipedia.org/wiki/Argon2). + +You may specify your application's hashing driver using the `HASH_DRIVER` environment variable. But, if you want to customize all of Laravel's hashing driver options, you should publish the complete `hashing` configuration file using the `config:publish` Artisan command: + +```shell +php artisan config:publish hashing +``` ## Basic Usage @@ -27,68 +34,89 @@ The default hashing driver for your application is configured in your applicatio You may hash a password by calling the `make` method on the `Hash` facade: - user()->fill([ - 'password' => Hash::make($request->newPassword) - ])->save(); - } + // Validate the new password length... + + $request->user()->fill([ + 'password' => Hash::make($request->newPassword) + ])->save(); + + return redirect('/profile'); } +} +``` #### Adjusting The Bcrypt Work Factor If you are using the Bcrypt algorithm, the `make` method allows you to manage the work factor of the algorithm using the `rounds` option; however, the default work factor managed by Laravel is acceptable for most applications: - $hashed = Hash::make('password', [ - 'rounds' => 12, - ]); +```php +$hashed = Hash::make('password', [ + 'rounds' => 12, +]); +``` #### Adjusting The Argon2 Work Factor If you are using the Argon2 algorithm, the `make` method allows you to manage the work factor of the algorithm using the `memory`, `time`, and `threads` options; however, the default values managed by Laravel are acceptable for most applications: - $hashed = Hash::make('password', [ - 'memory' => 1024, - 'time' => 2, - 'threads' => 2, - ]); +```php +$hashed = Hash::make('password', [ + 'memory' => 1024, + 'time' => 2, + 'threads' => 2, +]); +``` -> {tip} For more information on these options, please refer to the [official PHP documentation regarding Argon hashing](https://secure.php.net/manual/en/function.password-hash.php). +> [!NOTE] +> For more information on these options, please refer to the [official PHP documentation regarding Argon hashing](https://secure.php.net/manual/en/function.password-hash.php). -### Verifying That A Password Matches A Hash +### Verifying That a Password Matches a Hash The `check` method provided by the `Hash` facade allows you to verify that a given plain-text string corresponds to a given hash: - if (Hash::check('plain-text', $hashedPassword)) { - // The passwords match... - } +```php +if (Hash::check('plain-text', $hashedPassword)) { + // The passwords match... +} +``` -### Determining If A Password Needs To Be Rehashed +### Determining if a Password Needs to be Rehashed The `needsRehash` method provided by the `Hash` facade allows you to determine if the work factor used by the hasher has changed since the password was hashed. Some applications choose to perform this check during the application's authentication process: - if (Hash::needsRehash($hashed)) { - $hashed = Hash::make('plain-text'); - } +```php +if (Hash::needsRehash($hashed)) { + $hashed = Hash::make('plain-text'); +} +``` + + +## Hash Algorithm Verification + +To prevent hash algorithm manipulation, Laravel's `Hash::check` method will first verify the given hash was generated using the application's selected hashing algorithm. If the algorithms are different, a `RuntimeException` exception will be thrown. + +This is the expected behavior for most applications, where the hashing algorithm is not expected to change and different algorithms can be an indication of a malicious attack. However, if you need to support multiple hashing algorithms within your application, such as when migrating from one algorithm to another, you can disable hash algorithm verification by setting the `HASH_VERIFY` environment variable to `false`: + +```ini +HASH_VERIFY=false +``` diff --git a/helpers.md b/helpers.md index d26757a8f99..0011b02b641 100644 --- a/helpers.md +++ b/helpers.md @@ -2,6 +2,15 @@ - [Introduction](#introduction) - [Available Methods](#available-methods) +- [Other Utilities](#other-utilities) + - [Benchmarking](#benchmarking) + - [Dates](#dates) + - [Deferred Functions](#deferred-functions) + - [Lottery](#lottery) + - [Pipeline](#pipeline) + - [Sleep](#sleep) + - [Timebox](#timebox) + - [URI](#uri) ## Introduction @@ -13,12 +22,14 @@ Laravel includes a variety of global "helper" PHP functions. Many of these funct @@ -29,32 +40,55 @@ Laravel includes a variety of global "helper" PHP functions. Many of these funct [Arr::accessible](#method-array-accessible) [Arr::add](#method-array-add) +[Arr::array](#method-array-array) +[Arr::boolean](#method-array-boolean) [Arr::collapse](#method-array-collapse) [Arr::crossJoin](#method-array-crossjoin) [Arr::divide](#method-array-divide) [Arr::dot](#method-array-dot) +[Arr::every](#method-array-every) [Arr::except](#method-array-except) [Arr::exists](#method-array-exists) [Arr::first](#method-array-first) [Arr::flatten](#method-array-flatten) +[Arr::float](#method-array-float) [Arr::forget](#method-array-forget) +[Arr::from](#method-array-from) [Arr::get](#method-array-get) [Arr::has](#method-array-has) +[Arr::hasAll](#method-array-hasall) [Arr::hasAny](#method-array-hasany) +[Arr::integer](#method-array-integer) [Arr::isAssoc](#method-array-isassoc) [Arr::isList](#method-array-islist) +[Arr::join](#method-array-join) +[Arr::keyBy](#method-array-keyby) [Arr::last](#method-array-last) +[Arr::map](#method-array-map) +[Arr::mapSpread](#method-array-map-spread) +[Arr::mapWithKeys](#method-array-map-with-keys) [Arr::only](#method-array-only) +[Arr::partition](#method-array-partition) [Arr::pluck](#method-array-pluck) [Arr::prepend](#method-array-prepend) +[Arr::prependKeysWith](#method-array-prependkeyswith) [Arr::pull](#method-array-pull) +[Arr::push](#method-array-push) [Arr::query](#method-array-query) [Arr::random](#method-array-random) +[Arr::reject](#method-array-reject) +[Arr::select](#method-array-select) [Arr::set](#method-array-set) [Arr::shuffle](#method-array-shuffle) +[Arr::sole](#method-array-sole) +[Arr::some](#method-array-some) [Arr::sort](#method-array-sort) +[Arr::sortDesc](#method-array-sort-desc) [Arr::sortRecursive](#method-array-sort-recursive) +[Arr::string](#method-array-string) +[Arr::take](#method-array-take) [Arr::toCssClasses](#method-array-to-css-classes) +[Arr::toCssStyles](#method-array-to-css-styles) [Arr::undot](#method-array-undot) [Arr::where](#method-array-where) [Arr::whereNotNull](#method-array-where-not-null) @@ -62,10 +96,39 @@ Laravel includes a variety of global "helper" PHP functions. Many of these funct [data_fill](#method-data-fill) [data_get](#method-data-get) [data_set](#method-data-set) +[data_forget](#method-data-forget) [head](#method-head) [last](#method-last)
+
+[Number::abbreviate](#method-number-abbreviate)
+[Number::clamp](#method-number-clamp)
+[Number::currency](#method-number-currency)
+[Number::defaultCurrency](#method-default-currency)
+[Number::defaultLocale](#method-default-locale)
+[Number::fileSize](#method-number-file-size)
+[Number::forHumans](#method-number-for-humans)
+[Number::format](#method-number-format)
+[Number::ordinal](#method-number-ordinal)
+[Number::pairs](#method-number-pairs)
+[Number::parseInt](#method-number-parse-int)
+[Number::parseFloat](#method-number-parse-float)
+[Number::percentage](#method-number-percentage)
+[Number::spell](#method-number-spell)
+[Number::spellOrdinal](#method-number-spell-ordinal)
+[Number::trim](#method-number-trim)
+[Number::useLocale](#method-number-use-locale)
+[Number::withLocale](#method-number-with-locale)
+[Number::useCurrency](#method-number-use-currency)
+[Number::withCurrency](#method-number-with-currency)
+
+
+
### Paths
@@ -75,163 +138,13 @@ Laravel includes a variety of global "helper" PHP functions. Many of these funct
[base_path](#method-base-path)
[config_path](#method-config-path)
[database_path](#method-database-path)
-[mix](#method-mix)
+[lang_path](#method-lang-path)
[public_path](#method-public-path)
[resource_path](#method-resource-path)
[storage_path](#method-storage-path)
-
-[\__](#method-__)
-[class_basename](#method-class-basename)
-[e](#method-e)
-[preg_replace_array](#method-preg-replace-array)
-[Str::after](#method-str-after)
-[Str::afterLast](#method-str-after-last)
-[Str::ascii](#method-str-ascii)
-[Str::before](#method-str-before)
-[Str::beforeLast](#method-str-before-last)
-[Str::between](#method-str-between)
-[Str::camel](#method-camel-case)
-[Str::contains](#method-str-contains)
-[Str::containsAll](#method-str-contains-all)
-[Str::endsWith](#method-ends-with)
-[Str::excerpt](#method-excerpt)
-[Str::finish](#method-str-finish)
-[Str::headline](#method-str-headline)
-[Str::is](#method-str-is)
-[Str::isAscii](#method-str-is-ascii)
-[Str::isUuid](#method-str-is-uuid)
-[Str::kebab](#method-kebab-case)
-[Str::length](#method-str-length)
-[Str::limit](#method-str-limit)
-[Str::lower](#method-str-lower)
-[Str::markdown](#method-str-markdown)
-[Str::mask](#method-str-mask)
-[Str::orderedUuid](#method-str-ordered-uuid)
-[Str::padBoth](#method-str-padboth)
-[Str::padLeft](#method-str-padleft)
-[Str::padRight](#method-str-padright)
-[Str::plural](#method-str-plural)
-[Str::pluralStudly](#method-str-plural-studly)
-[Str::random](#method-str-random)
-[Str::remove](#method-str-remove)
-[Str::replace](#method-str-replace)
-[Str::replaceArray](#method-str-replace-array)
-[Str::replaceFirst](#method-str-replace-first)
-[Str::replaceLast](#method-str-replace-last)
-[Str::reverse](#method-str-reverse)
-[Str::singular](#method-str-singular)
-[Str::slug](#method-str-slug)
-[Str::snake](#method-snake-case)
-[Str::start](#method-str-start)
-[Str::startsWith](#method-starts-with)
-[Str::studly](#method-studly-case)
-[Str::substr](#method-str-substr)
-[Str::substrCount](#method-str-substrcount)
-[Str::substrReplace](#method-str-substrreplace)
-[Str::swap](#method-str-swap)
-[Str::title](#method-title-case)
-[Str::toHtmlString](#method-str-to-html-string)
-[Str::ucfirst](#method-str-ucfirst)
-[Str::upper](#method-str-upper)
-[Str::uuid](#method-str-uuid)
-[Str::wordCount](#method-str-word-count)
-[Str::words](#method-str-words)
-[str](#method-str)
-[trans](#method-trans)
-[trans_choice](#method-trans-choice)
-
-
-
-
-### Fluent Strings
-
-
-
-[after](#method-fluent-str-after)
-[afterLast](#method-fluent-str-after-last)
-[append](#method-fluent-str-append)
-[ascii](#method-fluent-str-ascii)
-[basename](#method-fluent-str-basename)
-[before](#method-fluent-str-before)
-[beforeLast](#method-fluent-str-before-last)
-[between](#method-fluent-str-between)
-[camel](#method-fluent-str-camel)
-[contains](#method-fluent-str-contains)
-[containsAll](#method-fluent-str-contains-all)
-[dirname](#method-fluent-str-dirname)
-[endsWith](#method-fluent-str-ends-with)
-[excerpt](#method-fluent-str-excerpt)
-[exactly](#method-fluent-str-exactly)
-[explode](#method-fluent-str-explode)
-[finish](#method-fluent-str-finish)
-[is](#method-fluent-str-is)
-[isAscii](#method-fluent-str-is-ascii)
-[isEmpty](#method-fluent-str-is-empty)
-[isNotEmpty](#method-fluent-str-is-not-empty)
-[isUuid](#method-fluent-str-is-uuid)
-[kebab](#method-fluent-str-kebab)
-[length](#method-fluent-str-length)
-[limit](#method-fluent-str-limit)
-[lower](#method-fluent-str-lower)
-[ltrim](#method-fluent-str-ltrim)
-[markdown](#method-fluent-str-markdown)
-[mask](#method-fluent-str-mask)
-[match](#method-fluent-str-match)
-[matchAll](#method-fluent-str-match-all)
-[padBoth](#method-fluent-str-padboth)
-[padLeft](#method-fluent-str-padleft)
-[padRight](#method-fluent-str-padright)
-[pipe](#method-fluent-str-pipe)
-[plural](#method-fluent-str-plural)
-[prepend](#method-fluent-str-prepend)
-[remove](#method-fluent-str-remove)
-[replace](#method-fluent-str-replace)
-[replaceArray](#method-fluent-str-replace-array)
-[replaceFirst](#method-fluent-str-replace-first)
-[replaceLast](#method-fluent-str-replace-last)
-[replaceMatches](#method-fluent-str-replace-matches)
-[rtrim](#method-fluent-str-rtrim)
-[scan](#method-fluent-str-scan)
-[singular](#method-fluent-str-singular)
-[slug](#method-fluent-str-slug)
-[snake](#method-fluent-str-snake)
-[split](#method-fluent-str-split)
-[start](#method-fluent-str-start)
-[startsWith](#method-fluent-str-starts-with)
-[studly](#method-fluent-str-studly)
-[substr](#method-fluent-str-substr)
-[substrReplace](#method-fluent-str-substrreplace)
-[swap](#method-fluent-str-swap)
-[tap](#method-fluent-str-tap)
-[test](#method-fluent-str-test)
-[title](#method-fluent-str-title)
-[trim](#method-fluent-str-trim)
-[ucfirst](#method-fluent-str-ucfirst)
-[upper](#method-fluent-str-upper)
-[when](#method-fluent-str-when)
-[whenContains](#method-fluent-str-when-contains)
-[whenContainsAll](#method-fluent-str-when-contains-all)
-[whenEmpty](#method-fluent-str-when-empty)
-[whenNotEmpty](#method-fluent-str-when-not-empty)
-[whenStartsWith](#method-fluent-str-when-starts-with)
-[whenEndsWith](#method-fluent-str-when-ends-with)
-[whenExactly](#method-fluent-str-when-exactly)
-[whenIs](#method-fluent-str-when-is)
-[whenIsAscii](#method-fluent-str-when-is-ascii)
-[whenIsUuid](#method-fluent-str-when-is-uuid)
-[whenTest](#method-fluent-str-when-test)
-[wordCount](#method-fluent-str-word-count)
-[words](#method-fluent-str-words)
-
-
-
### URLs
@@ -242,7 +155,9 @@ Laravel includes a variety of global "helper" PHP functions. Many of these funct
[route](#method-route)
[secure_asset](#method-secure-asset)
[secure_url](#method-secure-url)
+[to_action](#method-to-action)
[to_route](#method-to-route)
+[uri](#method-uri)
[url](#method-url)
Laravel
+ +#### `Number::spell()` {.collection-method} - $html = Str::markdown('# Taylor Otwell', [ - 'html_input' => 'strip', - ]); +The `Number::spell` method transforms the given number into a string of words: - //Taylor Otwell
+```php +use Illuminate\Support\Number; - -#### `Str::mask()` {.collection-method} +$number = Number::spell(102); -The `Str::mask` method masks a portion of a string with a repeated character, and may be used to obfuscate segments of strings such as email addresses and phone numbers: +// one hundred and two - use Illuminate\Support\Str; +$number = Number::spell(88, locale: 'fr'); - $string = Str::mask('taylor@example.com', '*', 3); +// quatre-vingt-huit +``` - // tay*************** +The `after` argument allows you to specify a value after which all numbers should be spelled out: -If needed, you provide a negative number as the third argument to the `mask` method, which will instruct the method to begin masking at the given distance from the end of the string: +```php +$number = Number::spell(10, after: 10); - $string = Str::mask('taylor@example.com', '*', -15, 3); +// 10 - // tay***@example.com +$number = Number::spell(11, after: 10); - -#### `Str::orderedUuid()` {.collection-method} +// eleven +``` -The `Str::orderedUuid` method generates a "timestamp first" UUID that may be efficiently stored in an indexed database column. Each UUID that is generated using this method will be sorted after UUIDs previously generated using the method: +The `until` argument allows you to specify a value before which all numbers should be spelled out: - use Illuminate\Support\Str; +```php +$number = Number::spell(5, until: 10); - return (string) Str::orderedUuid(); +// five - -#### `Str::padBoth()` {.collection-method} +$number = Number::spell(10, until: 10); -The `Str::padBoth` method wraps PHP's `str_pad` function, padding both sides of a string with another string until the final string reaches a desired length: +// 10 +``` - use Illuminate\Support\Str; + +#### `Number::spellOrdinal()` {.collection-method} - $padded = Str::padBoth('James', 10, '_'); +The `Number::spellOrdinal` method returns the number's ordinal representation as a string of words: - // '__James___' +```php +use Illuminate\Support\Number; - $padded = Str::padBoth('James', 10); +$number = Number::spellOrdinal(1); - // ' James ' +// first - -#### `Str::padLeft()` {.collection-method} +$number = Number::spellOrdinal(2); -The `Str::padLeft` method wraps PHP's `str_pad` function, padding the left side of a string with another string until the final string reaches a desired length: +// second - use Illuminate\Support\Str; +$number = Number::spellOrdinal(21); - $padded = Str::padLeft('James', 10, '-='); +// twenty-first +``` - // '-=-=-James' + +#### `Number::trim()` {.collection-method} - $padded = Str::padLeft('James', 10); +The `Number::trim` method removes any trailing zero digits after the decimal point of the given number: - // ' James' +```php +use Illuminate\Support\Number; - -#### `Str::padRight()` {.collection-method} +$number = Number::trim(12.0); -The `Str::padRight` method wraps PHP's `str_pad` function, padding the right side of a string with another string until the final string reaches a desired length: +// 12 - use Illuminate\Support\Str; +$number = Number::trim(12.30); - $padded = Str::padRight('James', 10, '-'); +// 12.3 +``` - // 'James-----' + +#### `Number::useLocale()` {.collection-method} - $padded = Str::padRight('James', 10); +The `Number::useLocale` method sets the default number locale globally, which affects how numbers and currency are formatted by subsequent invocations to the `Number` class's methods: - // 'James ' +```php +use Illuminate\Support\Number; + +/** + * Bootstrap any application services. + */ +public function boot(): void +{ + Number::useLocale('de'); +} +``` - -#### `Str::plural()` {.collection-method} + +#### `Number::withLocale()` {.collection-method} -The `Str::plural` method converts a singular word string to its plural form. This function currently only supports the English language: +The `Number::withLocale` method executes the given closure using the specified locale and then restores the original locale after the callback has executed: - use Illuminate\Support\Str; +```php +use Illuminate\Support\Number; - $plural = Str::plural('car'); +$number = Number::withLocale('de', function () { + return Number::format(1500); +}); +``` - // cars + +#### `Number::useCurrency()` {.collection-method} - $plural = Str::plural('child'); +The `Number::useCurrency` method sets the default number currency globally, which affects how the currency is formatted by subsequent invocations to the `Number` class's methods: - // children +```php +use Illuminate\Support\Number; + +/** + * Bootstrap any application services. + */ +public function boot(): void +{ + Number::useCurrency('GBP'); +} +``` -You may provide an integer as a second argument to the function to retrieve the singular or plural form of the string: + +#### `Number::withCurrency()` {.collection-method} - use Illuminate\Support\Str; +The `Number::withCurrency` method executes the given closure using the specified currency and then restores the original currency after the callback has executed: - $plural = Str::plural('child', 2); +```php +use Illuminate\Support\Number; - // children +$number = Number::withCurrency('GBP', function () { + // ... +}); +``` - $singular = Str::plural('child', 1); + +## Paths - // child + +#### `app_path()` {.collection-method} - -#### `Str::pluralStudly()` {.collection-method} +The `app_path` function returns the fully qualified path to your application's `app` directory. You may also use the `app_path` function to generate a fully qualified path to a file relative to the application directory: -The `Str::pluralStudly` method converts a singular word string formatted in studly caps case to its plural form. This function currently only supports the English language: +```php +$path = app_path(); - use Illuminate\Support\Str; +$path = app_path('Http/Controllers/Controller.php'); +``` - $plural = Str::pluralStudly('VerifiedHuman'); + +#### `base_path()` {.collection-method} - // VerifiedHumans +The `base_path` function returns the fully qualified path to your application's root directory. You may also use the `base_path` function to generate a fully qualified path to a given file relative to the project root directory: - $plural = Str::pluralStudly('UserFeedback'); +```php +$path = base_path(); - // UserFeedback +$path = base_path('vendor/bin'); +``` -You may provide an integer as a second argument to the function to retrieve the singular or plural form of the string: + +#### `config_path()` {.collection-method} - use Illuminate\Support\Str; +The `config_path` function returns the fully qualified path to your application's `config` directory. You may also use the `config_path` function to generate a fully qualified path to a given file within the application's configuration directory: - $plural = Str::pluralStudly('VerifiedHuman', 2); +```php +$path = config_path(); - // VerifiedHumans +$path = config_path('app.php'); +``` - $singular = Str::pluralStudly('VerifiedHuman', 1); + +#### `database_path()` {.collection-method} - // VerifiedHuman +The `database_path` function returns the fully qualified path to your application's `database` directory. You may also use the `database_path` function to generate a fully qualified path to a given file within the database directory: - -#### `Str::random()` {.collection-method} +```php +$path = database_path(); -The `Str::random` method generates a random string of the specified length. This function uses PHP's `random_bytes` function: +$path = database_path('factories/UserFactory.php'); +``` - use Illuminate\Support\Str; + +#### `lang_path()` {.collection-method} - $random = Str::random(40); +The `lang_path` function returns the fully qualified path to your application's `lang` directory. You may also use the `lang_path` function to generate a fully qualified path to a given file within the directory: - -#### `Str::remove()` {.collection-method} +```php +$path = lang_path(); -The `Str::remove` method removes the given value or array of values from the string: +$path = lang_path('en/messages.php'); +``` - use Illuminate\Support\Str; +> [!NOTE] +> By default, the Laravel application skeleton does not include the `lang` directory. If you would like to customize Laravel's language files, you may publish them via the `lang:publish` Artisan command. - $string = 'Peter Piper picked a peck of pickled peppers.'; + +#### `public_path()` {.collection-method} - $removed = Str::remove('e', $string); +The `public_path` function returns the fully qualified path to your application's `public` directory. You may also use the `public_path` function to generate a fully qualified path to a given file within the public directory: - // Ptr Pipr pickd a pck of pickld ppprs. +```php +$path = public_path(); -You may also pass `false` as a third argument to the `remove` method to ignore case when removing strings. +$path = public_path('css/app.css'); +``` - -#### `Str::replace()` {.collection-method} + +#### `resource_path()` {.collection-method} -The `Str::replace` method replaces a given string within the string: +The `resource_path` function returns the fully qualified path to your application's `resources` directory. You may also use the `resource_path` function to generate a fully qualified path to a given file within the resources directory: - use Illuminate\Support\Str; +```php +$path = resource_path(); - $string = 'Laravel 8.x'; +$path = resource_path('sass/app.scss'); +``` - $replaced = Str::replace('8.x', '9.x', $string); - - // Laravel 9.x + +#### `storage_path()` {.collection-method} - -#### `Str::replaceArray()` {.collection-method} +The `storage_path` function returns the fully qualified path to your application's `storage` directory. You may also use the `storage_path` function to generate a fully qualified path to a given file within the storage directory: -The `Str::replaceArray` method replaces a given value in the string sequentially using an array: +```php +$path = storage_path(); - use Illuminate\Support\Str; +$path = storage_path('app/file.txt'); +``` - $string = 'The event will take place between ? and ?'; + +## URLs - $replaced = Str::replaceArray('?', ['8:30', '9:00'], $string); + +#### `action()` {.collection-method} - // The event will take place between 8:30 and 9:00 +The `action` function generates a URL for the given controller action: - -#### `Str::replaceFirst()` {.collection-method} +```php +use App\Http\Controllers\HomeController; -The `Str::replaceFirst` method replaces the first occurrence of a given value in a string: +$url = action([HomeController::class, 'index']); +``` - use Illuminate\Support\Str; +If the method accepts route parameters, you may pass them as the second argument to the method: - $replaced = Str::replaceFirst('the', 'a', 'the quick brown fox jumps over the lazy dog'); +```php +$url = action([UserController::class, 'profile'], ['id' => 1]); +``` - // a quick brown fox jumps over the lazy dog + +#### `asset()` {.collection-method} - -#### `Str::replaceLast()` {.collection-method} +The `asset` function generates a URL for an asset using the current scheme of the request (HTTP or HTTPS): -The `Str::replaceLast` method replaces the last occurrence of a given value in a string: +```php +$url = asset('img/photo.jpg'); +``` - use Illuminate\Support\Str; +You can configure the asset URL host by setting the `ASSET_URL` variable in your `.env` file. This can be useful if you host your assets on an external service like Amazon S3 or another CDN: - $replaced = Str::replaceLast('the', 'a', 'the quick brown fox jumps over the lazy dog'); +```php +// ASSET_URL=http://example.com/assets - // the quick brown fox jumps over a lazy dog +$url = asset('img/photo.jpg'); // http://example.com/assets/img/photo.jpg +``` + +#### `route()` {.collection-method} - -#### `Str::reverse()` {.collection-method} +The `route` function generates a URL for a given [named route](/docs/{{version}}/routing#named-routes): -The `Str::reverse` method reverses the given string: +```php +$url = route('route.name'); +``` - use Illuminate\Support\Str; +If the route accepts parameters, you may pass them as the second argument to the function: - $reversed = Str::reverse('Hello World'); +```php +$url = route('route.name', ['id' => 1]); +``` - // dlroW olleH +By default, the `route` function generates an absolute URL. If you wish to generate a relative URL, you may pass `false` as the third argument to the function: - -#### `Str::singular()` {.collection-method} +```php +$url = route('route.name', ['id' => 1], false); +``` -The `Str::singular` method converts a string to its singular form. This function currently only supports the English language: + +#### `secure_asset()` {.collection-method} - use Illuminate\Support\Str; +The `secure_asset` function generates a URL for an asset using HTTPS: - $singular = Str::singular('cars'); +```php +$url = secure_asset('img/photo.jpg'); +``` - // car + +#### `secure_url()` {.collection-method} - $singular = Str::singular('children'); +The `secure_url` function generates a fully qualified HTTPS URL to the given path. Additional URL segments may be passed in the function's second argument: - // child +```php +$url = secure_url('https://github.com/user/profile'); - -#### `Str::slug()` {.collection-method} +$url = secure_url('https://github.com/user/profile',%20[1]); +``` -The `Str::slug` method generates a URL friendly "slug" from the given string: + +#### `to_action()` {.collection-method} - use Illuminate\Support\Str; +The `to_action` function generates a [redirect HTTP response](/docs/{{version}}/responses#redirects) for a given controller action: - $slug = Str::slug('Laravel 5 Framework', '-'); +```php +use App\Http\Controllers\UserController; - // laravel-5-framework +return to_action([UserController::class, 'show'], ['user' => 1]); +``` - -#### `Str::snake()` {.collection-method} +If necessary, you may pass the HTTP status code that should be assigned to the redirect and any additional response headers as the third and fourth arguments to the `to_action` method: -The `Str::snake` method converts the given string to `snake_case`: +```php +return to_action( + [UserController::class, 'show'], + ['user' => 1], + 302, + ['X-Framework' => 'Laravel'] +); +``` - use Illuminate\Support\Str; + +#### `to_route()` {.collection-method} - $converted = Str::snake('fooBar'); +The `to_route` function generates a [redirect HTTP response](/docs/{{version}}/responses#redirects) for a given [named route](/docs/{{version}}/routing#named-routes): - // foo_bar +```php +return to_route('users.show', ['user' => 1]); +``` - $converted = Str::snake('fooBar', '-'); +If necessary, you may pass the HTTP status code that should be assigned to the redirect and any additional response headers as the third and fourth arguments to the `to_route` method: - // foo-bar +```php +return to_route('users.show', ['user' => 1], 302, ['X-Framework' => 'Laravel']); +``` - -#### `Str::start()` {.collection-method} + +#### `uri()` {.collection-method} -The `Str::start` method adds a single instance of the given value to a string if it does not already start with that value: +The `uri` function generates a [fluent URI instance](#uri) for the given URI: - use Illuminate\Support\Str; +```php +$uri = uri('https://example.com/') + ->withPath('/users') + ->withQuery(['page' => 1]); +``` - $adjusted = Str::start('this/string', '/'); +If the `uri` function is given an array containing a callable controller and method pair, the function will create a `Uri` instance for the controller method's route path: - // /this/string +```php +use App\Http\Controllers\UserController; - $adjusted = Str::start('/this/string', '/'); +$uri = uri([UserController::class, 'show'], ['user' => $user]); +``` - // /this/string +If the controller is invokable, you may simply provide the controller class name: - -#### `Str::startsWith()` {.collection-method} +```php +use App\Http\Controllers\UserIndexController; -The `Str::startsWith` method determines if the given string begins with the given value: +$uri = uri(UserIndexController::class); +``` - use Illuminate\Support\Str; +If the value given to the `uri` function matches the name of a [named route](/docs/{{version}}/routing#named-routes), a `Uri` instance will be generated for that route's path: - $result = Str::startsWith('This is my name', 'This'); +```php +$uri = uri('users.show', ['user' => $user]); +``` - // true + +#### `url()` {.collection-method} -If an array of possible values is passed, the `startsWith` method will return `true` if the string begins with any of the given values: +The `url` function generates a fully qualified URL to the given path: - $result = Str::startsWith('This is my name', ['This', 'That', 'There']); +```php +$url = url('https://github.com/user/profile'); - // true +$url = url('https://github.com/user/profile',%20[1]); +``` - -#### `Str::studly()` {.collection-method} +If no path is provided, an `Illuminate\Routing\UrlGenerator` instance is returned: -The `Str::studly` method converts the given string to `StudlyCase`: +```php +$current = url()->current(); - use Illuminate\Support\Str; +$full = url()->full(); - $converted = Str::studly('foo_bar'); +$previous = url()->previous(); +``` - // FooBar +For more information on working with the `url` function, consult the [URL generation documentation](/docs/{{version}}/urls#generating-urls). - -#### `Str::substr()` {.collection-method} + +## Miscellaneous -The `Str::substr` method returns the portion of string specified by the start and length parameters: + +#### `abort()` {.collection-method} - use Illuminate\Support\Str; +The `abort` function throws [an HTTP exception](/docs/{{version}}/errors#http-exceptions) which will be rendered by the [exception handler](/docs/{{version}}/errors#handling-exceptions): - $converted = Str::substr('The Laravel Framework', 4, 7); +```php +abort(403); +``` - // Laravel +You may also provide the exception's message and custom HTTP response headers that should be sent to the browser: - -#### `Str::substrCount()` {.collection-method} +```php +abort(403, 'Unauthorized.', $headers); +``` -The `Str::substrCount` method returns the number of occurrences of a given value in the given string: + +#### `abort_if()` {.collection-method} - use Illuminate\Support\Str; +The `abort_if` function throws an HTTP exception if a given boolean expression evaluates to `true`: - $count = Str::substrCount('If you like ice cream, you will like snow cones.', 'like'); +```php +abort_if(! Auth::user()->isAdmin(), 403); +``` - // 2 +Like the `abort` method, you may also provide the exception's response text as the third argument and an array of custom response headers as the fourth argument to the function. - -#### `Str::substrReplace()` {.collection-method} + +#### `abort_unless()` {.collection-method} -The `Str::substrReplace` method replaces text within a portion of a string, starting at the position specified by the third argument and replacing the number of characters specified by the fourth argument. Passing `0` to the method's fourth argument will insert the string at the specified position without replacing any of the existing characters in the string: +The `abort_unless` function throws an HTTP exception if a given boolean expression evaluates to `false`: - use Illuminate\Support\Str; +```php +abort_unless(Auth::user()->isAdmin(), 403); +``` - $result = Str::substrReplace('1300', ':', 2); - // 13: - - $result = Str::substrReplace('1300', ':', 2, 0); - // 13:00 +Like the `abort` method, you may also provide the exception's response text as the third argument and an array of custom response headers as the fourth argument to the function. - -#### `Str::swap()` {.collection-method} + +#### `app()` {.collection-method} -The `Str::swap` method replaces multiple values in the given string using PHP's `strtr` function: +The `app` function returns the [service container](/docs/{{version}}/container) instance: - use Illuminate\Support\Str; +```php +$container = app(); +``` - $string = Str::swap([ - 'Tacos' => 'Burritos', - 'great' => 'fantastic', - ], 'Tacos are great!'); +You may pass a class or interface name to resolve it from the container: - // Burritos are fantastic! +```php +$api = app('HelpSpot\API'); +``` - -#### `Str::title()` {.collection-method} + +#### `auth()` {.collection-method} -The `Str::title` method converts the given string to `Title Case`: +The `auth` function returns an [authenticator](/docs/{{version}}/authentication) instance. You may use it as an alternative to the `Auth` facade: - use Illuminate\Support\Str; +```php +$user = auth()->user(); +``` - $converted = Str::title('a nice title uses the correct case'); +If needed, you may specify which guard instance you would like to access: - // A Nice Title Uses The Correct Case +```php +$user = auth('admin')->user(); +``` - -#### `Str::toHtmlString()` {.collection-method} + +#### `back()` {.collection-method} -The `Str::toHtmlString` method converts the string instance to an instance of `Illuminate\Support\HtmlString`, which may be displayed in Blade templates: +The `back` function generates a [redirect HTTP response](/docs/{{version}}/responses#redirects) to the user's previous location: - use Illuminate\Support\Str; +```php +return back($status = 302, $headers = [], $fallback = '/'); - $htmlString = Str::of('Nuno Maduro')->toHtmlString(); +return back(); +``` - -#### `Str::ucfirst()` {.collection-method} + +#### `bcrypt()` {.collection-method} -The `Str::ucfirst` method returns the given string with the first character capitalized: +The `bcrypt` function [hashes](/docs/{{version}}/hashing) the given value using Bcrypt. You may use this function as an alternative to the `Hash` facade: - use Illuminate\Support\Str; +```php +$password = bcrypt('my-secret-password'); +``` - $string = Str::ucfirst('foo bar'); + +#### `blank()` {.collection-method} - // Foo bar +The `blank` function determines whether the given value is "blank": - -#### `Str::upper()` {.collection-method} +```php +blank(''); +blank(' '); +blank(null); +blank(collect()); -The `Str::upper` method converts the given string to uppercase: +// true - use Illuminate\Support\Str; +blank(0); +blank(true); +blank(false); - $string = Str::upper('laravel'); +// false +``` - // LARAVEL +For the inverse of `blank`, see the [filled](#method-filled) function. - -#### `Str::uuid()` {.collection-method} + +#### `broadcast()` {.collection-method} -The `Str::uuid` method generates a UUID (version 4): +The `broadcast` function [broadcasts](/docs/{{version}}/broadcasting) the given [event](/docs/{{version}}/events) to its listeners: - use Illuminate\Support\Str; +```php +broadcast(new UserRegistered($user)); - return (string) Str::uuid(); +broadcast(new UserRegistered($user))->toOthers(); +``` - -#### `Str::wordCount()` {.collection-method} + +#### `broadcast_if()` {.collection-method} -The `Str::wordCount` method returns the number of words that a string contains: +The `broadcast_if` function [broadcasts](/docs/{{version}}/broadcasting) the given [event](/docs/{{version}}/events) to its listeners if a given boolean expression evaluates to `true`: ```php -use Illuminate\Support\Str; +broadcast_if($user->isActive(), new UserRegistered($user)); -Str::wordCount('Hello, world!'); // 2 +broadcast_if($user->isActive(), new UserRegistered($user))->toOthers(); ``` - -#### `Str::words()` {.collection-method} + +#### `broadcast_unless()` {.collection-method} -The `Str::words` method limits the number of words in a string. An additional string may be passed to this method via its third argument to specify which string should be appended to the end of the truncated string: +The `broadcast_unless` function [broadcasts](/docs/{{version}}/broadcasting) the given [event](/docs/{{version}}/events) to its listeners if a given boolean expression evaluates to `false`: - use Illuminate\Support\Str; +```php +broadcast_unless($user->isBanned(), new UserRegistered($user)); - return Str::words('Perfectly balanced, as all things should be.', 3, ' >>>'); +broadcast_unless($user->isBanned(), new UserRegistered($user))->toOthers(); +``` - // Perfectly balanced, as >>> + +#### `cache()` {.collection-method} - -#### `str()` {.collection-method} +The `cache` function may be used to get values from the [cache](/docs/{{version}}/cache). If the given key does not exist in the cache, an optional default value will be returned: -The `str` function returns a new `Illuminate\Support\Stringable` instance of the given string. This function is equivalent to the `Str::of` method: +```php +$value = cache('key'); - $string = str('Taylor')->append(' Otwell'); +$value = cache('key', 'default'); +``` - // 'Taylor Otwell' +You may add items to the cache by passing an array of key / value pairs to the function. You should also pass the number of seconds or duration the cached value should be considered valid: -If no argument is provided to the `str` function, the function returns an instance of `Illuminate\Support\Str`: +```php +cache(['key' => 'value'], 300); - $snake = str()->snake('FooBar'); +cache(['key' => 'value'], now()->addSeconds(10)); +``` - // 'foo_bar' + +#### `class_uses_recursive()` {.collection-method} - -#### `trans()` {.collection-method} +The `class_uses_recursive` function returns all traits used by a class, including traits used by all of its parent classes: -The `trans` function translates the given translation key using your [localization files](/docs/{{version}}/localization): +```php +$traits = class_uses_recursive(App\Models\User::class); +``` - echo trans('messages.welcome'); + +#### `collect()` {.collection-method} -If the specified translation key does not exist, the `trans` function will return the given key. So, using the example above, the `trans` function would return `messages.welcome` if the translation key does not exist. +The `collect` function creates a [collection](/docs/{{version}}/collections) instance from the given value: - -#### `trans_choice()` {.collection-method} +```php +$collection = collect(['Taylor', 'Abigail']); +``` -The `trans_choice` function translates the given translation key with inflection: + +#### `config()` {.collection-method} - echo trans_choice('messages.notifications', $unreadCount); +The `config` function gets the value of a [configuration](/docs/{{version}}/configuration) variable. The configuration values may be accessed using "dot" syntax, which includes the name of the file and the option you wish to access. You may also provide a default value that will be returned if the configuration option does not exist: -If the specified translation key does not exist, the `trans_choice` function will return the given key. So, using the example above, the `trans_choice` function would return `messages.notifications` if the translation key does not exist. +```php +$value = config('app.timezone'); - -## Fluent Strings +$value = config('app.timezone', $default); +``` -Fluent strings provide a more fluent, object-oriented interface for working with string values, allowing you to chain multiple string operations together using a more readable syntax compared to traditional string operations. +You may set configuration variables at runtime by passing an array of key / value pairs. However, note that this function only affects the configuration value for the current request and does not update your actual configuration values: - -#### `after` {.collection-method} +```php +config(['app.debug' => true]); +``` -The `after` method returns everything after the given value in a string. The entire string will be returned if the value does not exist within the string: + +#### `context()` {.collection-method} - use Illuminate\Support\Str; +The `context` function gets the value from the current [context](/docs/{{version}}/context). You may also provide a default value that will be returned if the context key does not exist: - $slice = Str::of('This is my name')->after('This is'); +```php +$value = context('trace_id'); - // ' my name' +$value = context('trace_id', $default); +``` - -#### `afterLast` {.collection-method} +You may set context values by passing an array of key / value pairs: -The `afterLast` method returns everything after the last occurrence of the given value in a string. The entire string will be returned if the value does not exist within the string: +```php +use Illuminate\Support\Str; - use Illuminate\Support\Str; +context(['trace_id' => Str::uuid()->toString()]); +``` - $slice = Str::of('App\Http\Controllers\Controller')->afterLast('\\'); + +#### `cookie()` {.collection-method} - // 'Controller' +The `cookie` function creates a new [cookie](/docs/{{version}}/requests#cookies) instance: - -#### `append` {.collection-method} +```php +$cookie = cookie('name', 'value', $minutes); +``` -The `append` method appends the given values to the string: + +#### `csrf_field()` {.collection-method} - use Illuminate\Support\Str; +The `csrf_field` function generates an HTML `hidden` input field containing the value of the CSRF token. For example, using [Blade syntax](/docs/{{version}}/blade): - $string = Str::of('Taylor')->append(' Otwell'); +```blade +{{ csrf_field() }} +``` - // 'Taylor Otwell' + +#### `csrf_token()` {.collection-method} - -#### `ascii` {.collection-method} +The `csrf_token` function retrieves the value of the current CSRF token: -The `ascii` method will attempt to transliterate the string into an ASCII value: +```php +$token = csrf_token(); +``` - use Illuminate\Support\Str; + +#### `decrypt()` {.collection-method} - $string = Str::of('ü')->ascii(); +The `decrypt` function [decrypts](/docs/{{version}}/encryption) the given value. You may use this function as an alternative to the `Crypt` facade: - // 'u' +```php +$password = decrypt($value); +``` - -#### `basename` {.collection-method} +For the inverse of `decrypt`, see the [encrypt](#method-encrypt) function. -The `basename` method will return the trailing name component of the given string: + +#### `dd()` {.collection-method} - use Illuminate\Support\Str; +The `dd` function dumps the given variables and ends the execution of the script: - $string = Str::of('/foo/bar/baz')->basename(); +```php +dd($value); - // 'baz' +dd($value1, $value2, $value3, ...); +``` -If needed, you may provide an "extension" that will be removed from the trailing component: +If you do not want to halt the execution of your script, use the [dump](#method-dump) function instead. - use Illuminate\Support\Str; + +#### `dispatch()` {.collection-method} - $string = Str::of('/foo/bar/baz.jpg')->basename('.jpg'); +The `dispatch` function pushes the given [job](/docs/{{version}}/queues#creating-jobs) onto the Laravel [job queue](/docs/{{version}}/queues): - // 'baz' +```php +dispatch(new App\Jobs\SendEmails); +``` - -#### `before` {.collection-method} + +#### `dispatch_sync()` {.collection-method} -The `before` method returns everything before the given value in a string: +The `dispatch_sync` function pushes the given job to the [sync](/docs/{{version}}/queues#synchronous-dispatching) queue so that it is processed immediately: - use Illuminate\Support\Str; +```php +dispatch_sync(new App\Jobs\SendEmails); +``` - $slice = Str::of('This is my name')->before('my name'); + +#### `dump()` {.collection-method} - // 'This is ' +The `dump` function dumps the given variables: - -#### `beforeLast` {.collection-method} +```php +dump($value); -The `beforeLast` method returns everything before the last occurrence of the given value in a string: +dump($value1, $value2, $value3, ...); +``` - use Illuminate\Support\Str; +If you want to stop executing the script after dumping the variables, use the [dd](#method-dd) function instead. - $slice = Str::of('This is my name')->beforeLast('is'); + +#### `encrypt()` {.collection-method} - // 'This ' +The `encrypt` function [encrypts](/docs/{{version}}/encryption) the given value. You may use this function as an alternative to the `Crypt` facade: - -#### `between` {.collection-method} +```php +$secret = encrypt('my-secret-value'); +``` -The `between` method returns the portion of a string between two values: +For the inverse of `encrypt`, see the [decrypt](#method-decrypt) function. - use Illuminate\Support\Str; + +#### `env()` {.collection-method} - $converted = Str::of('This is my name')->between('This', 'name'); +The `env` function retrieves the value of an [environment variable](/docs/{{version}}/configuration#environment-configuration) or returns a default value: - // ' is my ' +```php +$env = env('APP_ENV'); - -#### `camel` {.collection-method} +$env = env('APP_ENV', 'production'); +``` -The `camel` method converts the given string to `camelCase`: +> [!WARNING] +> If you execute the `config:cache` command during your deployment process, you should be sure that you are only calling the `env` function from within your configuration files. Once the configuration has been cached, the `.env` file will not be loaded and all calls to the `env` function will return external environment variables such as server-level or system-level environment variables or `null`. - use Illuminate\Support\Str; + +#### `event()` {.collection-method} - $converted = Str::of('foo_bar')->camel(); +The `event` function dispatches the given [event](/docs/{{version}}/events) to its listeners: - // fooBar +```php +event(new UserRegistered($user)); +``` - -#### `contains` {.collection-method} + +#### `fake()` {.collection-method} -The `contains` method determines if the given string contains the given value. This method is case sensitive: +The `fake` function resolves a [Faker](https://github.com/FakerPHP/Faker) singleton from the container, which can be useful when creating fake data in model factories, database seeding, tests, and prototyping views: - use Illuminate\Support\Str; +```blade +@for ($i = 0; $i < 10; $i++) +-
+
- Name +
- {{ fake()->name() }} - $contains = Str::of('This is my name')->contains('my'); +
- {{ fake()->unique()->safeEmail() }} +
Laravel
+```php +return retry([100, 200], function () { + // Sleep for 100ms on first retry, 200ms on second retry... +}); +``` - $html = Str::of('# Taylor Otwell')->markdown([ - 'html_input' => 'strip', - ]); +To only retry under specific conditions, you may pass a closure as the fourth argument to the `retry` function: - //Taylor Otwell
+```php +use App\Exceptions\TemporaryException; +use Exception; + +return retry(5, function () { + // ... +}, 100, function (Exception $exception) { + return $exception instanceof TemporaryException; +}); +``` - -#### `mask` {.collection-method} + +#### `session()` {.collection-method} -The `mask` method masks a portion of a string with a repeated character, and may be used to obfuscate segments of strings such as email addresses and phone numbers: +The `session` function may be used to get or set [session](/docs/{{version}}/session) values: - use Illuminate\Support\Str; +```php +$value = session('key'); +``` - $string = Str::of('taylor@example.com')->mask('*', 3); +You may set values by passing an array of key / value pairs to the function: - // tay*************** +```php +session(['chairs' => 7, 'instruments' => 3]); +``` -If needed, you provide a negative number as the third argument to the `mask` method, which will instruct the method to begin masking at the given distance from the end of the string: +The session store will be returned if no value is passed to the function: - $string = Str::of('taylor@example.com')->mask('*', -15, 3); +```php +$value = session()->get('key'); - // tay***@example.com +session()->put('key', $value); +``` - -#### `match` {.collection-method} + +#### `tap()` {.collection-method} -The `match` method will return the portion of a string that matches a given regular expression pattern: +The `tap` function accepts two arguments: an arbitrary `$value` and a closure. The `$value` will be passed to the closure and then be returned by the `tap` function. The return value of the closure is irrelevant: - use Illuminate\Support\Str; +```php +$user = tap(User::first(), function (User $user) { + $user->name = 'Taylor'; - $result = Str::of('foo bar')->match('/bar/'); + $user->save(); +}); +``` - // 'bar' +If no closure is passed to the `tap` function, you may call any method on the given `$value`. The return value of the method you call will always be `$value`, regardless of what the method actually returns in its definition. For example, the Eloquent `update` method typically returns an integer. However, we can force the method to return the model itself by chaining the `update` method call through the `tap` function: - $result = Str::of('foo bar')->match('/foo (.*)/'); +```php +$user = tap($user)->update([ + 'name' => $name, + 'email' => $email, +]); +``` - // 'bar' +To add a `tap` method to a class, you may add the `Illuminate\Support\Traits\Tappable` trait to the class. The `tap` method of this trait accepts a Closure as its only argument. The object instance itself will be passed to the Closure and then be returned by the `tap` method: - -#### `matchAll` {.collection-method} +```php +return $user->tap(function (User $user) { + // ... +}); +``` -The `matchAll` method will return a collection containing the portions of a string that match a given regular expression pattern: + +#### `throw_if()` {.collection-method} - use Illuminate\Support\Str; +The `throw_if` function throws the given exception if a given boolean expression evaluates to `true`: - $result = Str::of('bar foo bar')->matchAll('/bar/'); +```php +throw_if(! Auth::user()->isAdmin(), AuthorizationException::class); - // collect(['bar', 'bar']) +throw_if( + ! Auth::user()->isAdmin(), + AuthorizationException::class, + 'You are not allowed to access this page.' +); +``` -If you specify a matching group within the expression, Laravel will return a collection of that group's matches: + +#### `throw_unless()` {.collection-method} - use Illuminate\Support\Str; +The `throw_unless` function throws the given exception if a given boolean expression evaluates to `false`: - $result = Str::of('bar fun bar fly')->matchAll('/f(\w*)/'); +```php +throw_unless(Auth::user()->isAdmin(), AuthorizationException::class); - // collect(['un', 'ly']); +throw_unless( + Auth::user()->isAdmin(), + AuthorizationException::class, + 'You are not allowed to access this page.' +); +``` -If no matches are found, an empty collection will be returned. + +#### `today()` {.collection-method} - -#### `padBoth` {.collection-method} +The `today` function creates a new `Illuminate\Support\Carbon` instance for the current date: -The `padBoth` method wraps PHP's `str_pad` function, padding both sides of a string with another string until the final string reaches the desired length: +```php +$today = today(); +``` - use Illuminate\Support\Str; + +#### `trait_uses_recursive()` {.collection-method} - $padded = Str::of('James')->padBoth(10, '_'); +The `trait_uses_recursive` function returns all traits used by a trait: - // '__James___' +```php +$traits = trait_uses_recursive(\Illuminate\Notifications\Notifiable::class); +``` - $padded = Str::of('James')->padBoth(10); + +#### `transform()` {.collection-method} - // ' James ' +The `transform` function executes a closure on a given value if the value is not [blank](#method-blank) and then returns the return value of the closure: - -#### `padLeft` {.collection-method} +```php +$callback = function (int $value) { + return $value * 2; +}; -The `padLeft` method wraps PHP's `str_pad` function, padding the left side of a string with another string until the final string reaches the desired length: +$result = transform(5, $callback); - use Illuminate\Support\Str; +// 10 +``` - $padded = Str::of('James')->padLeft(10, '-='); +A default value or closure may be passed as the third argument to the function. This value will be returned if the given value is blank: - // '-=-=-James' +```php +$result = transform(null, $callback, 'The value is blank'); - $padded = Str::of('James')->padLeft(10); +// The value is blank +``` - // ' James' + +#### `validator()` {.collection-method} - -#### `padRight` {.collection-method} +The `validator` function creates a new [validator](/docs/{{version}}/validation) instance with the given arguments. You may use it as an alternative to the `Validator` facade: -The `padRight` method wraps PHP's `str_pad` function, padding the right side of a string with another string until the final string reaches the desired length: +```php +$validator = validator($data, $rules, $messages); +``` - use Illuminate\Support\Str; + +#### `value()` {.collection-method} - $padded = Str::of('James')->padRight(10, '-'); +The `value` function returns the value it is given. However, if you pass a closure to the function, the closure will be executed and its returned value will be returned: - // 'James-----' +```php +$result = value(true); - $padded = Str::of('James')->padRight(10); +// true - // 'James ' +$result = value(function () { + return false; +}); - -#### `pipe` {.collection-method} +// false +``` -The `pipe` method allows you to transform the string by passing its current value to the given callable: +Additional arguments may be passed to the `value` function. If the first argument is a closure then the additional parameters will be passed to the closure as arguments, otherwise they will be ignored: - use Illuminate\Support\Str; +```php +$result = value(function (string $name) { + return $name; +}, 'Taylor'); - $hash = Str::of('Laravel')->pipe('md5')->prepend('Checksum: '); +// 'Taylor' +``` - // 'Checksum: a5c95b86291ea299fcbe64458ed12702' + +#### `view()` {.collection-method} - $closure = Str::of('foo')->pipe(function ($str) { - return 'bar'; - }); +The `view` function retrieves a [view](/docs/{{version}}/views) instance: - // 'bar' +```php +return view('auth.login'); +``` - -#### `plural` {.collection-method} + +#### `with()` {.collection-method} -The `plural` method converts a singular word string to its plural form. This function currently only supports the English language: +The `with` function returns the value it is given. If a closure is passed as the second argument to the function, the closure will be executed and its returned value will be returned: - use Illuminate\Support\Str; +```php +$callback = function (mixed $value) { + return is_numeric($value) ? $value * 2 : 0; +}; - $plural = Str::of('car')->plural(); +$result = with(5, $callback); - // cars +// 10 - $plural = Str::of('child')->plural(); +$result = with(null, $callback); - // children +// 0 -You may provide an integer as a second argument to the function to retrieve the singular or plural form of the string: +$result = with(5, null); - use Illuminate\Support\Str; +// 5 +``` - $plural = Str::of('child')->plural(2); + +#### `when()` {.collection-method} - // children +The `when` function returns the value it is given if a given condition evaluates to `true`. Otherwise, `null` is returned. If a closure is passed as the second argument to the function, the closure will be executed and its returned value will be returned: - $plural = Str::of('child')->plural(1); +```php +$value = when(true, 'Hello World'); - // child +$value = when(true, fn () => 'Hello World'); +``` - -#### `prepend` {.collection-method} +The `when` function is primarily useful for conditionally rendering HTML attributes: -The `prepend` method prepends the given values onto the string: +```blade +
+ ...
+
+```
- use Illuminate\Support\Str;
+
+## Other Utilities
- $string = Str::of('Framework')->prepend('Laravel ');
+
+### Benchmarking
- // Laravel Framework
+Sometimes you may wish to quickly test the performance of certain parts of your application. On those occasions, you may utilize the `Benchmark` support class to measure the number of milliseconds it takes for the given callbacks to complete:
-
-#### `remove` {.collection-method}
+```php
+ User::find(1)); // 0.1 ms
- $string = Str::of('Arkansas is quite beautiful!')->remove('quite');
+Benchmark::dd([
+ 'Scenario 1' => fn () => User::count(), // 0.5 ms
+ 'Scenario 2' => fn () => User::all()->count(), // 20.0 ms
+]);
+```
- // Arkansas is beautiful!
+By default, the given callbacks will be executed once (one iteration), and their duration will be displayed in the browser / console.
-You may also pass `false` as a second parameter to ignore case when removing strings.
+To invoke a callback more than once, you may specify the number of iterations that the callback should be invoked as the second argument to the method. When executing a callback more than once, the `Benchmark` class will return the average number of milliseconds it took to execute the callback across all iterations:
-
-#### `replace` {.collection-method}
+```php
+Benchmark::dd(fn () => User::count(), iterations: 10); // 0.5 ms
+```
-The `replace` method replaces a given string within the string:
+Sometimes, you may want to benchmark the execution of a callback while still obtaining the value returned by the callback. The `value` method will return a tuple containing the value returned by the callback and the number of milliseconds it took to execute the callback:
- use Illuminate\Support\Str;
+```php
+[$count, $duration] = Benchmark::value(fn () => User::count());
+```
- $replaced = Str::of('Laravel 6.x')->replace('6.x', '7.x');
+
+### Dates
- // Laravel 7.x
+Laravel includes [Carbon](https://carbon.nesbot.com/docs/), a powerful date and time manipulation library. To create a new `Carbon` instance, you may invoke the `now` function. This function is globally available within your Laravel application:
-
-#### `replaceArray` {.collection-method}
+```php
+$now = now();
+```
-The `replaceArray` method replaces a given value in the string sequentially using an array:
+Or, you may create a new `Carbon` instance using the `Illuminate\Support\Carbon` class:
- use Illuminate\Support\Str;
+```php
+use Illuminate\Support\Carbon;
- $string = 'The event will take place between ? and ?';
+$now = Carbon::now();
+```
- $replaced = Str::of($string)->replaceArray('?', ['8:30', '9:00']);
+For a thorough discussion of Carbon and its features, please consult the [official Carbon documentation](https://carbon.nesbot.com/docs/).
- // The event will take place between 8:30 and 9:00
+
+### Deferred Functions
-
-#### `replaceFirst` {.collection-method}
+While Laravel's [queued jobs](/docs/{{version}}/queues) allow you to queue tasks for background processing, sometimes you may have simple tasks you would like to defer without configuring or maintaining a long-running queue worker.
-The `replaceFirst` method replaces the first occurrence of a given value in a string:
+Deferred functions allow you to defer the execution of a closure until after the HTTP response has been sent to the user, keeping your application feeling fast and responsive. To defer the execution of a closure, simply pass the closure to the `Illuminate\Support\defer` function:
- use Illuminate\Support\Str;
+```php
+use App\Services\Metrics;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Route;
+use function Illuminate\Support\defer;
- $replaced = Str::of('the quick brown fox jumps over the lazy dog')->replaceFirst('the', 'a');
+Route::post('/orders', function (Request $request) {
+ // Create order...
- // a quick brown fox jumps over the lazy dog
+ defer(fn () => Metrics::reportOrder($order));
-
-#### `replaceLast` {.collection-method}
+ return $order;
+});
+```
-The `replaceLast` method replaces the last occurrence of a given value in a string:
+By default, deferred functions will only be executed if the HTTP response, Artisan command, or queued job from which `Illuminate\Support\defer` is invoked completes successfully. This means that deferred functions will not be executed if a request results in a `4xx` or `5xx` HTTP response. If you would like a deferred function to always execute, you may chain the `always` method onto your deferred function:
- use Illuminate\Support\Str;
+```php
+defer(fn () => Metrics::reportOrder($order))->always();
+```
- $replaced = Str::of('the quick brown fox jumps over the lazy dog')->replaceLast('the', 'a');
+> [!WARNING]
+> If you have the [Swoole PHP extension](https://www.php.net/manual/en/book.swoole.php) installed, Laravel's `defer` function may conflict with Swoole's own global `defer` function, leading to web server errors. Make sure you call Laravel's `defer` helper by explicitly namespacing it: `use function Illuminate\Support\defer;`
- // the quick brown fox jumps over a lazy dog
+
+#### Cancelling Deferred Functions
-
-#### `replaceMatches` {.collection-method}
+If you need to cancel a deferred function before it is executed, you can use the `forget` method to cancel the function by its name. To name a deferred function, provide a second argument to the `Illuminate\Support\defer` function:
-The `replaceMatches` method replaces all portions of a string matching a pattern with the given replacement string:
+```php
+defer(fn () => Metrics::report(), 'reportMetrics');
- use Illuminate\Support\Str;
+defer()->forget('reportMetrics');
+```
- $replaced = Str::of('(+1) 501-555-1000')->replaceMatches('/[^A-Za-z0-9]++/', '')
+
+#### Disabling Deferred Functions in Tests
- // '15015551000'
+When writing tests, it may be useful to disable deferred functions. You may call `withoutDefer` in your test to instruct Laravel to invoke all deferred functions immediately:
-The `replaceMatches` method also accepts a closure that will be invoked with each portion of the string matching the given pattern, allowing you to perform the replacement logic within the closure and return the replaced value:
+```php tab=Pest
+test('without defer', function () {
+ $this->withoutDefer();
- use Illuminate\Support\Str;
+ // ...
+});
+```
- $replaced = Str::of('123')->replaceMatches('/\d/', function ($match) {
- return '['.$match[0].']';
- });
+```php tab=PHPUnit
+use Tests\TestCase;
- // '[1][2][3]'
+class ExampleTest extends TestCase
+{
+ public function test_without_defer(): void
+ {
+ $this->withoutDefer();
-
-#### `rtrim` {.collection-method}
+ // ...
+ }
+}
+```
-The `rtrim` method trims the right side of the given string:
+If you would like to disable deferred functions for all tests within a test case, you may call the `withoutDefer` method from the `setUp` method on your base `TestCase` class:
- use Illuminate\Support\Str;
+```php
+rtrim();
+namespace Tests;
- // ' Laravel'
+use Illuminate\Foundation\Testing\TestCase as BaseTestCase;
- $string = Str::of('/Laravel/')->rtrim('/');
+abstract class TestCase extends BaseTestCase
+{
+ protected function setUp(): void// [tl! add:start]
+ {
+ parent::setUp();
- // '/Laravel'
+ $this->withoutDefer();
+ }// [tl! add:end]
+}
+```
-
-#### `scan` {.collection-method}
+
+### Lottery
-The `scan` method parses input from a string into a collection according to a format supported by the [`sscanf` PHP function](https://www.php.net/manual/en/function.sscanf.php):
+Laravel's lottery class may be used to execute callbacks based on a set of given odds. This can be particularly useful when you only want to execute code for a percentage of your incoming requests:
- use Illuminate\Support\Str;
+```php
+use Illuminate\Support\Lottery;
- $collection = Str::of('filename.jpg')->scan('%[^.].%s');
+Lottery::odds(1, 20)
+ ->winner(fn () => $user->won())
+ ->loser(fn () => $user->lost())
+ ->choose();
+```
- // collect(['filename', 'jpg'])
+You may combine Laravel's lottery class with other Laravel features. For example, you may wish to only report a small percentage of slow queries to your exception handler. And, since the lottery class is callable, we may pass an instance of the class into any method that accepts callables:
-
-#### `singular` {.collection-method}
+```php
+use Carbon\CarbonInterval;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Lottery;
+
+DB::whenQueryingForLongerThan(
+ CarbonInterval::seconds(2),
+ Lottery::odds(1, 100)->winner(fn () => report('Querying > 2 seconds.')),
+);
+```
-The `singular` method converts a string to its singular form. This function currently only supports the English language:
+
+#### Testing Lotteries
- use Illuminate\Support\Str;
+Laravel provides some simple methods to allow you to easily test your application's lottery invocations:
- $singular = Str::of('cars')->singular();
+```php
+// Lottery will always win...
+Lottery::alwaysWin();
- // car
+// Lottery will always lose...
+Lottery::alwaysLose();
- $singular = Str::of('children')->singular();
+// Lottery will win then lose, and finally return to normal behavior...
+Lottery::fix([true, false]);
- // child
+// Lottery will return to normal behavior...
+Lottery::determineResultsNormally();
+```
-
-#### `slug` {.collection-method}
+
+### Pipeline
-The `slug` method generates a URL friendly "slug" from the given string:
+Laravel's `Pipeline` facade provides a convenient way to "pipe" a given input through a series of invokable classes, closures, or callables, giving each class the opportunity to inspect or modify the input and invoke the next callable in the pipeline:
- use Illuminate\Support\Str;
+```php
+use Closure;
+use App\Models\User;
+use Illuminate\Support\Facades\Pipeline;
+
+$user = Pipeline::send($user)
+ ->through([
+ function (User $user, Closure $next) {
+ // ...
+
+ return $next($user);
+ },
+ function (User $user, Closure $next) {
+ // ...
+
+ return $next($user);
+ },
+ ])
+ ->then(fn (User $user) => $user);
+```
- $slug = Str::of('Laravel Framework')->slug('-');
+As you can see, each invokable class or closure in the pipeline is provided the input and a `$next` closure. Invoking the `$next` closure will invoke the next callable in the pipeline. As you may have noticed, this is very similar to [middleware](/docs/{{version}}/middleware).
- // laravel-framework
+When the last callable in the pipeline invokes the `$next` closure, the callable provided to the `then` method will be invoked. Typically, this callable will simply return the given input. For convenience, if you simply want to return the input after it has been processed, you may use the `thenReturn` method.
-
-#### `snake` {.collection-method}
+Of course, as discussed previously, you are not limited to providing closures to your pipeline. You may also provide invokable classes. If a class name is provided, the class will be instantiated via Laravel's [service container](/docs/{{version}}/container), allowing dependencies to be injected into the invokable class:
-The `snake` method converts the given string to `snake_case`:
+```php
+$user = Pipeline::send($user)
+ ->through([
+ GenerateProfilePhoto::class,
+ ActivateSubscription::class,
+ SendWelcomeEmail::class,
+ ])
+ ->thenReturn();
+```
- use Illuminate\Support\Str;
+The `withinTransaction` method may be invoked on the pipeline to automatically wrap all steps of the pipeline within a single database transaction:
- $converted = Str::of('fooBar')->snake();
+```php
+$user = Pipeline::send($user)
+ ->withinTransaction()
+ ->through([
+ ProcessOrder::class,
+ TransferFunds::class,
+ UpdateInventory::class,
+ ])
+ ->thenReturn();
+```
- // foo_bar
+
+### Sleep
-
-#### `split` {.collection-method}
+Laravel's `Sleep` class is a light-weight wrapper around PHP's native `sleep` and `usleep` functions, offering greater testability while also exposing a developer friendly API for working with time:
-The `split` method splits a string into a collection using a regular expression:
+```php
+use Illuminate\Support\Sleep;
- use Illuminate\Support\Str;
+$waiting = true;
- $segments = Str::of('one, two, three')->split('/[\s,]+/');
+while ($waiting) {
+ Sleep::for(1)->second();
- // collect(["one", "two", "three"])
+ $waiting = /* ... */;
+}
+```
-
-#### `start` {.collection-method}
+The `Sleep` class offers a variety of methods that allow you to work with different units of time:
-The `start` method adds a single instance of the given value to a string if it does not already start with that value:
+```php
+// Return a value after sleeping...
+$result = Sleep::for(1)->second()->then(fn () => 1 + 1);
- use Illuminate\Support\Str;
+// Sleep while a given value is true...
+Sleep::for(1)->second()->while(fn () => shouldKeepSleeping());
- $adjusted = Str::of('this/string')->start('/');
+// Pause execution for 90 seconds...
+Sleep::for(1.5)->minutes();
- // /this/string
+// Pause execution for 2 seconds...
+Sleep::for(2)->seconds();
- $adjusted = Str::of('/this/string')->start('/');
+// Pause execution for 500 milliseconds...
+Sleep::for(500)->milliseconds();
- // /this/string
+// Pause execution for 5,000 microseconds...
+Sleep::for(5000)->microseconds();
-
-#### `startsWith` {.collection-method}
+// Pause execution until a given time...
+Sleep::until(now()->addMinute());
-The `startsWith` method determines if the given string begins with the given value:
+// Alias of PHP's native "sleep" function...
+Sleep::sleep(2);
- use Illuminate\Support\Str;
+// Alias of PHP's native "usleep" function...
+Sleep::usleep(5000);
+```
- $result = Str::of('This is my name')->startsWith('This');
+To easily combine units of time, you may use the `and` method:
- // true
+```php
+Sleep::for(1)->second()->and(10)->milliseconds();
+```
-
-#### `studly` {.collection-method}
+
+#### Testing Sleep
-The `studly` method converts the given string to `StudlyCase`:
+When testing code that utilizes the `Sleep` class or PHP's native sleep functions, your test will pause execution. As you might expect, this makes your test suite significantly slower. For example, imagine you are testing the following code:
- use Illuminate\Support\Str;
+```php
+$waiting = /* ... */;
- $converted = Str::of('foo_bar')->studly();
+$seconds = 1;
- // FooBar
+while ($waiting) {
+ Sleep::for($seconds++)->seconds();
-
-#### `substr` {.collection-method}
+ $waiting = /* ... */;
+}
+```
-The `substr` method returns the portion of the string specified by the given start and length parameters:
+Typically, testing this code would take _at least_ one second. Luckily, the `Sleep` class allows us to "fake" sleeping so that our test suite stays fast:
- use Illuminate\Support\Str;
+```php tab=Pest
+it('waits until ready', function () {
+ Sleep::fake();
- $string = Str::of('Laravel Framework')->substr(8);
+ // ...
+});
+```
- // Framework
+```php tab=PHPUnit
+public function test_it_waits_until_ready()
+{
+ Sleep::fake();
- $string = Str::of('Laravel Framework')->substr(8, 5);
+ // ...
+}
+```
- // Frame
+When faking the `Sleep` class, the actual execution pause is bypassed, leading to a substantially faster test.
-
-#### `substrReplace` {.collection-method}
+Once the `Sleep` class has been faked, it is possible to make assertions against the expected "sleeps" that should have occurred. To illustrate this, let's imagine we are testing code that pauses execution three times, with each pause increasing by a single second. Using the `assertSequence` method, we can assert that our code "slept" for the proper amount of time while keeping our test fast:
-The `substrReplace` method replaces text within a portion of a string, starting at the position specified by the second argument and replacing the number of characters specified by the third argument. Passing `0` to the method's third argument will insert the string at the specified position without replacing any of the existing characters in the string:
+```php tab=Pest
+it('checks if ready three times', function () {
+ Sleep::fake();
- use Illuminate\Support\Str;
+ // ...
- $string = Str::of('1300')->substrReplace(':', 2);
+ Sleep::assertSequence([
+ Sleep::for(1)->second(),
+ Sleep::for(2)->seconds(),
+ Sleep::for(3)->seconds(),
+ ]);
+}
+```
- // 13:
+```php tab=PHPUnit
+public function test_it_checks_if_ready_three_times()
+{
+ Sleep::fake();
- $string = Str::of('The Framework')->substrReplace(' Laravel', 3, 0);
+ // ...
- // The Laravel Framework
+ Sleep::assertSequence([
+ Sleep::for(1)->second(),
+ Sleep::for(2)->seconds(),
+ Sleep::for(3)->seconds(),
+ ]);
+}
+```
-
-#### `swap` {.collection-method}
+Of course, the `Sleep` class offers a variety of other assertions you may use when testing:
-The `swap` method replaces multiple values in the string using PHP's `strtr` function:
+```php
+use Carbon\CarbonInterval as Duration;
+use Illuminate\Support\Sleep;
- use Illuminate\Support\Str;
+// Assert that sleep was called 3 times...
+Sleep::assertSleptTimes(3);
- $string = Str::of('Tacos are great!')
- ->swap([
- 'Tacos' => 'Burritos',
- 'great' => 'fantastic',
- ]);
+// Assert against the duration of sleep...
+Sleep::assertSlept(function (Duration $duration): bool {
+ return /* ... */;
+}, times: 1);
- // Burritos are fantastic!
+// Assert that the Sleep class was never invoked...
+Sleep::assertNeverSlept();
-
-#### `tap` {.collection-method}
+// Assert that, even if Sleep was called, no execution paused occurred...
+Sleep::assertInsomniac();
+```
-The `tap` method passes the string to the given closure, allowing you to examine and interact with the string while not affecting the string itself. The original string is returned by the `tap` method regardless of what is returned by the closure:
+Sometimes it may be useful to perform an action whenever a fake sleep occurs. To achieve this, you may provide a callback to the `whenFakingSleep` method. In the following example, we use Laravel's [time manipulation helpers](/docs/{{version}}/mocking#interacting-with-time) to instantly progress time by the duration of each sleep:
- use Illuminate\Support\Str;
+```php
+use Carbon\CarbonInterval as Duration;
- $string = Str::of('Laravel')
- ->append(' Framework')
- ->tap(function ($string) {
- dump('String after append: ' . $string);
- })
- ->upper();
+$this->freezeTime();
- // LARAVEL FRAMEWORK
+Sleep::fake();
-
-#### `test` {.collection-method}
+Sleep::whenFakingSleep(function (Duration $duration) {
+ // Progress time when faking sleep...
+ $this->travel($duration->totalMilliseconds)->milliseconds();
+});
+```
-The `test` method determines if a string matches the given regular expression pattern:
+As progressing time is a common requirement, the `fake` method accepts a `syncWithCarbon` argument to keep Carbon in sync when sleeping within a test:
- use Illuminate\Support\Str;
+```php
+Sleep::fake(syncWithCarbon: true);
- $result = Str::of('Laravel Framework')->test('/Laravel/');
+$start = now();
- // true
+Sleep::for(1)->second();
-
-#### `title` {.collection-method}
+$start->diffForHumans(); // 1 second ago
+```
-The `title` method converts the given string to `Title Case`:
+Laravel uses the `Sleep` class internally whenever it is pausing execution. For example, the [retry](#method-retry) helper uses the `Sleep` class when sleeping, allowing for improved testability when using that helper.
- use Illuminate\Support\Str;
+
+### Timebox
- $converted = Str::of('a nice title uses the correct case')->title();
+Laravel's `Timebox` class ensures that the given callback always takes a fixed amount of time to execute, even if its actual execution completes sooner. This is particularly useful for cryptographic operations and user authentication checks, where attackers might exploit variations in execution time to infer sensitive information.
- // A Nice Title Uses The Correct Case
+If the execution exceeds the fixed duration, `Timebox` has no effect. It is up to the developer to choose a sufficiently long time as the fixed duration to account for worst-case scenarios.
-
-#### `trim` {.collection-method}
+The call method accepts a closure and a time limit in microseconds, and then executes the closure and waits until the time limit is reached:
-The `trim` method trims the given string:
+```php
+use Illuminate\Support\Timebox;
- use Illuminate\Support\Str;
+(new Timebox)->call(function ($timebox) {
+ // ...
+}, microseconds: 10000);
+```
- $string = Str::of(' Laravel ')->trim();
+If an exception is thrown within the closure, this class will respect the defined delay and re-throw the exception after the delay.
- // 'Laravel'
+
+### URI
- $string = Str::of('/Laravel/')->trim('/');
+Laravel's `Uri` class provides a convenient and fluent interface for creating and manipulating URIs. This class wraps the functionality provided by the underlying League URI package and integrates seamlessly with Laravel's routing system.
- // 'Laravel'
+You can create a `Uri` instance easily using static methods:
-
-#### `ucfirst` {.collection-method}
+```php
+use App\Http\Controllers\UserController;
+use App\Http\Controllers\InvokableController;
+use Illuminate\Support\Uri;
+
+// Generate a URI instance from the given string...
+$uri = Uri::of('https://example.com/path');
+
+// Generate URI instances to paths, named routes, or controller actions...
+$uri = Uri::to('/dashboard');
+$uri = Uri::route('users.show', ['user' => 1]);
+$uri = Uri::signedRoute('users.show', ['user' => 1]);
+$uri = Uri::temporarySignedRoute('user.index', now()->addMinutes(5));
+$uri = Uri::action([UserController::class, 'index']);
+$uri = Uri::action(InvokableController::class);
+
+// Generate a URI instance from the current request URL...
+$uri = $request->uri();
+```
-The `ucfirst` method returns the given string with the first character capitalized:
+Once you have a URI instance, you can fluently modify it:
- use Illuminate\Support\Str;
+```php
+$uri = Uri::of('https://example.com/')
+ ->withScheme('http')
+ ->withHost('test.com')
+ ->withPort(8000)
+ ->withPath('/users')
+ ->withQuery(['page' => 2])
+ ->withFragment('section-1');
+```
- $string = Str::of('foo bar')->ucfirst();
+
+#### Inspecting URIs
- // Foo bar
+The `Uri` class also allows you to easily inspect the various components of the underlying URI:
-
-#### `upper` {.collection-method}
+```php
+$scheme = $uri->scheme();
+$host = $uri->host();
+$port = $uri->port();
+$path = $uri->path();
+$segments = $uri->pathSegments();
+$query = $uri->query();
+$fragment = $uri->fragment();
+```
-The `upper` method converts the given string to uppercase:
+
+#### Manipulating Query Strings
- use Illuminate\Support\Str;
+The `Uri` class offers several methods that may be used to manipulate a URI's query string. The `withQuery` method may be used to merge additional query string parameters into the existing query string:
- $adjusted = Str::of('laravel')->upper();
+```php
+$uri = $uri->withQuery(['sort' => 'name']);
+```
- // LARAVEL
+The `withQueryIfMissing` method may be used to merge additional query string parameters into the existing query string if the given keys do not already exist in the query string:
-
-#### `when` {.collection-method}
+```php
+$uri = $uri->withQueryIfMissing(['page' => 1]);
+```
-The `when` method invokes the given closure if a given condition is `true`. The closure will receive the fluent string instance:
+The `replaceQuery` method may be used to complete replace the existing query string with a new one:
- use Illuminate\Support\Str;
+```php
+$uri = $uri->replaceQuery(['page' => 1]);
+```
- $string = Str::of('Taylor')
- ->when(true, function ($string) {
- return $string->append(' Otwell');
- });
+The `pushOntoQuery` method may be used to push additional parameters onto a query string parameter that has an array value:
- // 'Taylor Otwell'
+```php
+$uri = $uri->pushOntoQuery('filter', ['active', 'pending']);
+```
-If necessary, you may pass another closure as the third parameter to the `when` method. This closure will execute if the condition parameter evaluates to `false`.
+The `withoutQuery` method may be used to remove parameters from the query string:
-
-#### `whenContains` {.collection-method}
+```php
+$uri = $uri->withoutQuery(['page']);
+```
-The `whenContains` method invokes the given closure if the string contains the given value. The closure will receive the fluent string instance:
+
+#### Generating Responses From URIs
- use Illuminate\Support\Str;
+The `redirect` method may be used to generate a `RedirectResponse` instance to the given URI:
- $string = Str::of('tony stark')
- ->whenContains('tony', function ($string) {
- return $string->title();
- });
+```php
+$uri = Uri::of('https://example.com/');
- // 'Tony Stark'
+return $uri->redirect();
+```
-If necessary, you may pass another closure as the third parameter to the `when` method. This closure will execute if the string does not contain the given value.
+Or, you may simply return the `Uri` instance from a route or controller action, which will automatically generate a redirect response to the returned URI:
-You may also pass an array of values to determine if the given string contains any of the values in the array:
+```php
+use Illuminate\Support\Facades\Route;
+use Illuminate\Support\Uri;
- use Illuminate\Support\Str;
-
- $string = Str::of('tony stark')
- ->whenContains(['tony', 'hulk'], function ($string) {
- return $string->title();
- });
-
- // Tony Stark
-
-
-#### `whenContainsAll` {.collection-method}
-
-The `whenContainsAll` method invokes the given closure if the string contains all of the given sub-strings. The closure will receive the fluent string instance:
-
- use Illuminate\Support\Str;
-
- $string = Str::of('tony stark')
- ->whenContainsAll(['tony', 'stark'], function ($string) {
- return $string->title();
- });
-
- // 'Tony Stark'
-
-If necessary, you may pass another closure as the third parameter to the `when` method. This closure will execute if the condition parameter evaluates to `false`.
-
-
-#### `whenEmpty` {.collection-method}
-
-The `whenEmpty` method invokes the given closure if the string is empty. If the closure returns a value, that value will also be returned by the `whenEmpty` method. If the closure does not return a value, the fluent string instance will be returned:
-
- use Illuminate\Support\Str;
-
- $string = Str::of(' ')->whenEmpty(function ($string) {
- return $string->trim()->prepend('Laravel');
- });
-
- // 'Laravel'
-
-
-#### `whenNotEmpty` {.collection-method}
-
-The `whenNotEmpty` method invokes the given closure if the string is not empty. If the closure returns a value, that value will also be returned by the `whenNotEmpty` method. If the closure does not return a value, the fluent string instance will be returned:
-
- use Illuminate\Support\Str;
-
- $string = Str::of('Framework')->whenNotEmpty(function ($string) {
- return $string->prepend('Laravel ');
- });
-
- // 'Laravel Framework'
-
-
-#### `whenStartsWith` {.collection-method}
-
-The `whenStartsWith` method invokes the given closure if the string starts with the given sub-string. The closure will receive the fluent string instance:
-
- use Illuminate\Support\Str;
-
- $string = Str::of('disney world')->whenStartsWith('disney', function ($string) {
- return $string->title();
- });
-
- // 'Disney World'
-
-
-#### `whenEndsWith` {.collection-method}
-
-The `whenEndsWith` method invokes the given closure if the string ends with the given sub-string. The closure will receive the fluent string instance:
-
- use Illuminate\Support\Str;
-
- $string = Str::of('disney world')->whenEndsWith('world', function ($string) {
- return $string->title();
- });
-
- // 'Disney World'
-
-
-#### `whenExactly` {.collection-method}
-
-The `whenExactly` method invokes the given closure if the string exactly matches the given string. The closure will receive the fluent string instance:
-
- use Illuminate\Support\Str;
-
- $string = Str::of('laravel')->whenExactly('laravel', function ($string) {
- return $string->title();
- });
-
- // 'Laravel'
-
-
-#### `whenIs` {.collection-method}
-
-The `whenIs` method invokes the given closure if the string matches a given pattern. Asterisks may be used as wildcard values. The closure will receive the fluent string instance:
-
- use Illuminate\Support\Str;
-
- $string = Str::of('foo/bar')->whenIs('foo/*', function ($string) {
- return $string->append('/baz');
- });
-
- // 'foo/bar/baz'
-
-
-#### `whenIsAscii` {.collection-method}
-
-The `whenIsAscii` method invokes the given closure if the string is 7 bit ASCII. The closure will receive the fluent string instance:
-
- use Illuminate\Support\Str;
-
- $string = Str::of('foo/bar')->whenIsAscii('laravel', function ($string) {
- return $string->title();
- });
-
- // 'Laravel'
-
-
-#### `whenIsUuid` {.collection-method}
-
-The `whenIsUuid` method invokes the given closure if the string is a valid UUID. The closure will receive the fluent string instance:
-
- use Illuminate\Support\Str;
-
- $string = Str::of('foo/bar')->whenIsUuid('a0a2a2d2-0b87-4a18-83f2-2529882be2de', function ($string) {
- return $string->substr(0, 8);
- });
-
- // 'a0a2a2d2'
-
-
-#### `whenTest` {.collection-method}
-
-The `whenTest` method invokes the given closure if the string matches the given regular expression. The closure will receive the fluent string instance:
-
- use Illuminate\Support\Str;
-
- $string = Str::of('laravel framework')->whenTest('/laravel/', function ($string) {
- return $string->title();
- });
-
- // 'Laravel Framework'
-
-
-#### `wordCount` {.collection-method}
-
-The `wordCount` method returns the number of words that a string contains:
-
-```php
-use Illuminate\Support\Str;
-
-Str::of('Hello, world!')->wordCount(); // 2
+Route::get('/redirect', function () {
+ return Uri::to('/index')
+ ->withQuery(['sort' => 'name']);
+});
```
-
-
-#### `words` {.collection-method}
-
-The `words` method limits the number of words in a string. If necessary, you may specify an additional string that will be appended to the truncated string:
-
- use Illuminate\Support\Str;
-
- $string = Str::of('Perfectly balanced, as all things should be.')->words(3, ' >>>');
-
- // Perfectly balanced, as >>>
-
-
-## URLs
-
-
-#### `action()` {.collection-method}
-
-The `action` function generates a URL for the given controller action:
-
- use App\Http\Controllers\HomeController;
-
- $url = action([HomeController::class, 'index']);
-
-If the method accepts route parameters, you may pass them as the second argument to the method:
-
- $url = action([UserController::class, 'profile'], ['id' => 1]);
-
-
-#### `asset()` {.collection-method}
-
-The `asset` function generates a URL for an asset using the current scheme of the request (HTTP or HTTPS):
-
- $url = asset('img/photo.jpg');
-
-You can configure the asset URL host by setting the `ASSET_URL` variable in your `.env` file. This can be useful if you host your assets on an external service like Amazon S3 or another CDN:
-
- // ASSET_URL=http://example.com/assets
-
- $url = asset('img/photo.jpg'); // http://example.com/assets/img/photo.jpg
-
-
-#### `route()` {.collection-method}
-
-The `route` function generates a URL for a given [named route](/docs/{{version}}/routing#named-routes):
-
- $url = route('route.name');
-
-If the route accepts parameters, you may pass them as the second argument to the function:
-
- $url = route('route.name', ['id' => 1]);
-
-By default, the `route` function generates an absolute URL. If you wish to generate a relative URL, you may pass `false` as the third argument to the function:
-
- $url = route('route.name', ['id' => 1], false);
-
-
-#### `secure_asset()` {.collection-method}
-
-The `secure_asset` function generates a URL for an asset using HTTPS:
-
- $url = secure_asset('img/photo.jpg');
-
-
-#### `secure_url()` {.collection-method}
-
-The `secure_url` function generates a fully qualified HTTPS URL to the given path. Additional URL segments may be passed in the function's second argument:
-
- $url = secure_url('https://github.com/user/profile');
-
- $url = secure_url('https://github.com/user/profile',%20[1]);
-
-
-#### `to_route()` {.collection-method}
-
-The `to_route` function generates a [redirect HTTP response](/docs/{{version}}/responses#redirects) for a given [named route](/docs/{{version}}/routing#named-routes):
-
- return to_route('users.show', ['user' => 1]);
-
-If necessary, you may pass the HTTP status code that should be assigned to the redirect and any additional response headers as the third and fourth arguments to the `to_route` method:
-
- return to_route('users.show', ['user' => 1], 302, ['X-Framework' => 'Laravel']);
-
-
-#### `url()` {.collection-method}
-
-The `url` function generates a fully qualified URL to the given path:
-
- $url = url('https://github.com/user/profile');
-
- $url = url('https://github.com/user/profile',%20[1]);
-
-If no path is provided, an `Illuminate\Routing\UrlGenerator` instance is returned:
-
- $current = url()->current();
-
- $full = url()->full();
-
- $previous = url()->previous();
-
-
-## Miscellaneous
-
-
-#### `abort()` {.collection-method}
-
-The `abort` function throws [an HTTP exception](/docs/{{version}}/errors#http-exceptions) which will be rendered by the [exception handler](/docs/{{version}}/errors#the-exception-handler):
-
- abort(403);
-
-You may also provide the exception's message and custom HTTP response headers that should be sent to the browser:
-
- abort(403, 'Unauthorized.', $headers);
-
-
-#### `abort_if()` {.collection-method}
-
-The `abort_if` function throws an HTTP exception if a given boolean expression evaluates to `true`:
-
- abort_if(! Auth::user()->isAdmin(), 403);
-
-Like the `abort` method, you may also provide the exception's response text as the third argument and an array of custom response headers as the fourth argument to the function.
-
-
-#### `abort_unless()` {.collection-method}
-
-The `abort_unless` function throws an HTTP exception if a given boolean expression evaluates to `false`:
-
- abort_unless(Auth::user()->isAdmin(), 403);
-
-Like the `abort` method, you may also provide the exception's response text as the third argument and an array of custom response headers as the fourth argument to the function.
-
-
-#### `app()` {.collection-method}
-
-The `app` function returns the [service container](/docs/{{version}}/container) instance:
-
- $container = app();
-
-You may pass a class or interface name to resolve it from the container:
-
- $api = app('HelpSpot\API');
-
-
-#### `auth()` {.collection-method}
-
-The `auth` function returns an [authenticator](/docs/{{version}}/authentication) instance. You may use it as an alternative to the `Auth` facade:
-
- $user = auth()->user();
-
-If needed, you may specify which guard instance you would like to access:
-
- $user = auth('admin')->user();
-
-
-#### `back()` {.collection-method}
-
-The `back` function generates a [redirect HTTP response](/docs/{{version}}/responses#redirects) to the user's previous location:
-
- return back($status = 302, $headers = [], $fallback = '/');
-
- return back();
-
-
-#### `bcrypt()` {.collection-method}
-
-The `bcrypt` function [hashes](/docs/{{version}}/hashing) the given value using Bcrypt. You may use this function as an alternative to the `Hash` facade:
-
- $password = bcrypt('my-secret-password');
-
-
-#### `blank()` {.collection-method}
-
-The `blank` function determines whether the given value is "blank":
-
- blank('');
- blank(' ');
- blank(null);
- blank(collect());
-
- // true
-
- blank(0);
- blank(true);
- blank(false);
-
- // false
-
-For the inverse of `blank`, see the [`filled`](#method-filled) method.
-
-
-#### `broadcast()` {.collection-method}
-
-The `broadcast` function [broadcasts](/docs/{{version}}/broadcasting) the given [event](/docs/{{version}}/events) to its listeners:
-
- broadcast(new UserRegistered($user));
-
- broadcast(new UserRegistered($user))->toOthers();
-
-
-#### `cache()` {.collection-method}
-
-The `cache` function may be used to get values from the [cache](/docs/{{version}}/cache). If the given key does not exist in the cache, an optional default value will be returned:
-
- $value = cache('key');
-
- $value = cache('key', 'default');
-
-You may add items to the cache by passing an array of key / value pairs to the function. You should also pass the number of seconds or duration the cached value should be considered valid:
-
- cache(['key' => 'value'], 300);
-
- cache(['key' => 'value'], now()->addSeconds(10));
-
-
-#### `class_uses_recursive()` {.collection-method}
-
-The `class_uses_recursive` function returns all traits used by a class, including traits used by all of its parent classes:
-
- $traits = class_uses_recursive(App\Models\User::class);
-
-
-#### `collect()` {.collection-method}
-
-The `collect` function creates a [collection](/docs/{{version}}/collections) instance from the given value:
-
- $collection = collect(['taylor', 'abigail']);
-
-
-#### `config()` {.collection-method}
-
-The `config` function gets the value of a [configuration](/docs/{{version}}/configuration) variable. The configuration values may be accessed using "dot" syntax, which includes the name of the file and the option you wish to access. A default value may be specified and is returned if the configuration option does not exist:
-
- $value = config('app.timezone');
-
- $value = config('app.timezone', $default);
-
-You may set configuration variables at runtime by passing an array of key / value pairs. However, note that this function only affects the configuration value for the current request and does not update your actual configuration values:
-
- config(['app.debug' => true]);
-
-
-#### `cookie()` {.collection-method}
-
-The `cookie` function creates a new [cookie](/docs/{{version}}/requests#cookies) instance:
-
- $cookie = cookie('name', 'value', $minutes);
-
-
-#### `csrf_field()` {.collection-method}
-
-The `csrf_field` function generates an HTML `hidden` input field containing the value of the CSRF token. For example, using [Blade syntax](/docs/{{version}}/blade):
-
- {{ csrf_field() }}
-
-
-#### `csrf_token()` {.collection-method}
-
-The `csrf_token` function retrieves the value of the current CSRF token:
-
- $token = csrf_token();
-
-
-#### `decrypt()` {.collection-method}
-
-The `decrypt` function [decrypts](/docs/{{version}}/encryption) the given value. You may use this function as an alternative to the `Crypt` facade:
-
- $password = decrypt($value);
-
-
-#### `dd()` {.collection-method}
-
-The `dd` function dumps the given variables and ends execution of the script:
-
- dd($value);
-
- dd($value1, $value2, $value3, ...);
-
-If you do not want to halt the execution of your script, use the [`dump`](#method-dump) function instead.
-
-
-#### `dispatch()` {.collection-method}
-
-The `dispatch` function pushes the given [job](/docs/{{version}}/queues#creating-jobs) onto the Laravel [job queue](/docs/{{version}}/queues):
-
- dispatch(new App\Jobs\SendEmails);
-
-
-#### `dump()` {.collection-method}
-
-The `dump` function dumps the given variables:
-
- dump($value);
-
- dump($value1, $value2, $value3, ...);
-
-If you want to stop executing the script after dumping the variables, use the [`dd`](#method-dd) function instead.
-
-
-#### `encrypt()` {.collection-method}
-
-The `encrypt` function [encrypts](/docs/{{version}}/encryption) the given value. You may use this function as an alternative to the `Crypt` facade:
-
- $secret = encrypt('my-secret-value');
-
-
-#### `env()` {.collection-method}
-
-The `env` function retrieves the value of an [environment variable](/docs/{{version}}/configuration#environment-configuration) or returns a default value:
-
- $env = env('APP_ENV');
-
- $env = env('APP_ENV', 'production');
-
-> {note} If you execute the `config:cache` command during your deployment process, you should be sure that you are only calling the `env` function from within your configuration files. Once the configuration has been cached, the `.env` file will not be loaded and all calls to the `env` function will return `null`.
-
-
-#### `event()` {.collection-method}
-
-The `event` function dispatches the given [event](/docs/{{version}}/events) to its listeners:
-
- event(new UserRegistered($user));
-
-
-#### `filled()` {.collection-method}
-
-The `filled` function determines whether the given value is not "blank":
-
- filled(0);
- filled(true);
- filled(false);
-
- // true
-
- filled('');
- filled(' ');
- filled(null);
- filled(collect());
-
- // false
-
-For the inverse of `filled`, see the [`blank`](#method-blank) method.
-
-
-#### `info()` {.collection-method}
-
-The `info` function will write information to your application's [log](/docs/{{version}}/logging):
-
- info('Some helpful information!');
-
-An array of contextual data may also be passed to the function:
-
- info('User login attempt failed.', ['id' => $user->id]);
-
-
-#### `logger()` {.collection-method}
-
-The `logger` function can be used to write a `debug` level message to the [log](/docs/{{version}}/logging):
-
- logger('Debug message');
-
-An array of contextual data may also be passed to the function:
-
- logger('User has logged in.', ['id' => $user->id]);
-
-A [logger](/docs/{{version}}/errors#logging) instance will be returned if no value is passed to the function:
-
- logger()->error('You are not allowed here.');
-
-
-#### `method_field()` {.collection-method}
-
-The `method_field` function generates an HTML `hidden` input field containing the spoofed value of the form's HTTP verb. For example, using [Blade syntax](/docs/{{version}}/blade):
-
-
-
-
-#### `now()` {.collection-method}
-
-The `now` function creates a new `Illuminate\Support\Carbon` instance for the current time:
-
- $now = now();
-
-
-#### `old()` {.collection-method}
-
-The `old` function [retrieves](/docs/{{version}}/requests#retrieving-input) an [old input](/docs/{{version}}/requests#old-input) value flashed into the session:
-
- $value = old('value');
-
- $value = old('value', 'default');
-
-
-#### `optional()` {.collection-method}
-
-The `optional` function accepts any argument and allows you to access properties or call methods on that object. If the given object is `null`, properties and methods will return `null` instead of causing an error:
-
- return optional($user->address)->street;
-
- {!! old('name', optional($user)->name) !!}
-
-The `optional` function also accepts a closure as its second argument. The closure will be invoked if the value provided as the first argument is not null:
-
- return optional(User::find($id), function ($user) {
- return $user->name;
- });
-
-
-#### `policy()` {.collection-method}
-
-The `policy` method retrieves a [policy](/docs/{{version}}/authorization#creating-policies) instance for a given class:
-
- $policy = policy(App\Models\User::class);
-
-
-#### `redirect()` {.collection-method}
-
-The `redirect` function returns a [redirect HTTP response](/docs/{{version}}/responses#redirects), or returns the redirector instance if called with no arguments:
-
- return redirect($to = null, $status = 302, $headers = [], $https = null);
-
- return redirect('/home');
-
- return redirect()->route('route.name');
-
-
-#### `report()` {.collection-method}
-
-The `report` function will report an exception using your [exception handler](/docs/{{version}}/errors#the-exception-handler):
-
- report($e);
-
-The `report` function also accepts a string as an argument. When a string is given to the function, the function will create an exception with the given string as its message:
-
- report('Something went wrong.');
-
-
-#### `request()` {.collection-method}
-
-The `request` function returns the current [request](/docs/{{version}}/requests) instance or obtains an input field's value from the current request:
-
- $request = request();
-
- $value = request('key', $default);
-
-
-#### `rescue()` {.collection-method}
-
-The `rescue` function executes the given closure and catches any exceptions that occur during its execution. All exceptions that are caught will be sent to your [exception handler](/docs/{{version}}/errors#the-exception-handler); however, the request will continue processing:
-
- return rescue(function () {
- return $this->method();
- });
-
-You may also pass a second argument to the `rescue` function. This argument will be the "default" value that should be returned if an exception occurs while executing the closure:
-
- return rescue(function () {
- return $this->method();
- }, false);
-
- return rescue(function () {
- return $this->method();
- }, function () {
- return $this->failure();
- });
-
-
-#### `resolve()` {.collection-method}
-
-The `resolve` function resolves a given class or interface name to an instance using the [service container](/docs/{{version}}/container):
-
- $api = resolve('HelpSpot\API');
-
-
-#### `response()` {.collection-method}
-
-The `response` function creates a [response](/docs/{{version}}/responses) instance or obtains an instance of the response factory:
-
- return response('Hello World', 200, $headers);
-
- return response()->json(['foo' => 'bar'], 200, $headers);
-
-
-#### `retry()` {.collection-method}
-
-The `retry` function attempts to execute the given callback until the given maximum attempt threshold is met. If the callback does not throw an exception, its return value will be returned. If the callback throws an exception, it will automatically be retried. If the maximum attempt count is exceeded, the exception will be thrown:
-
- return retry(5, function () {
- // Attempt 5 times while resting 100ms between attempts...
- }, 100);
-
-If you would like to manually calculate the number of milliseconds to sleep between attempts, you may pass a closure as the third argument to the `retry` function:
-
- return retry(5, function () {
- // ...
- }, function ($attempt) {
- return $attempt * 100;
- });
-
-For convenience, you may provide an array as the first argument to the `retry` function. This array will be used to determine how many milliseconds to sleep between subsequent attempts:
-
- return retry([100, 200] function () {
- // Sleep for 100ms on first retry, 200ms on second retry...
- });
-
-To only retry under specific conditions, you may pass a closure as the fourth argument to the `retry` function:
-
- return retry(5, function () {
- // ...
- }, 100, function ($exception) {
- return $exception instanceof RetryException;
- });
-
-
-#### `session()` {.collection-method}
-
-The `session` function may be used to get or set [session](/docs/{{version}}/session) values:
-
- $value = session('key');
-
-You may set values by passing an array of key / value pairs to the function:
-
- session(['chairs' => 7, 'instruments' => 3]);
-
-The session store will be returned if no value is passed to the function:
-
- $value = session()->get('key');
-
- session()->put('key', $value);
-
-
-#### `tap()` {.collection-method}
-
-The `tap` function accepts two arguments: an arbitrary `$value` and a closure. The `$value` will be passed to the closure and then be returned by the `tap` function. The return value of the closure is irrelevant:
-
- $user = tap(User::first(), function ($user) {
- $user->name = 'taylor';
-
- $user->save();
- });
-
-If no closure is passed to the `tap` function, you may call any method on the given `$value`. The return value of the method you call will always be `$value`, regardless of what the method actually returns in its definition. For example, the Eloquent `update` method typically returns an integer. However, we can force the method to return the model itself by chaining the `update` method call through the `tap` function:
-
- $user = tap($user)->update([
- 'name' => $name,
- 'email' => $email,
- ]);
-
-To add a `tap` method to a class, you may add the `Illuminate\Support\Traits\Tappable` trait to the class. The `tap` method of this trait accepts a Closure as its only argument. The object instance itself will be passed to the Closure and then be returned by the `tap` method:
-
- return $user->tap(function ($user) {
- //
- });
-
-
-#### `throw_if()` {.collection-method}
-
-The `throw_if` function throws the given exception if a given boolean expression evaluates to `true`:
-
- throw_if(! Auth::user()->isAdmin(), AuthorizationException::class);
-
- throw_if(
- ! Auth::user()->isAdmin(),
- AuthorizationException::class,
- 'You are not allowed to access this page.'
- );
-
-
-#### `throw_unless()` {.collection-method}
-
-The `throw_unless` function throws the given exception if a given boolean expression evaluates to `false`:
-
- throw_unless(Auth::user()->isAdmin(), AuthorizationException::class);
-
- throw_unless(
- Auth::user()->isAdmin(),
- AuthorizationException::class,
- 'You are not allowed to access this page.'
- );
-
-
-#### `today()` {.collection-method}
-
-The `today` function creates a new `Illuminate\Support\Carbon` instance for the current date:
-
- $today = today();
-
-
-#### `trait_uses_recursive()` {.collection-method}
-
-The `trait_uses_recursive` function returns all traits used by a trait:
-
- $traits = trait_uses_recursive(\Illuminate\Notifications\Notifiable::class);
-
-
-#### `transform()` {.collection-method}
-
-The `transform` function executes a closure on a given value if the value is not [blank](#method-blank) and then returns the return value of the closure:
-
- $callback = function ($value) {
- return $value * 2;
- };
-
- $result = transform(5, $callback);
-
- // 10
-
-A default value or closure may be passed as the third argument to the function. This value will be returned if the given value is blank:
-
- $result = transform(null, $callback, 'The value is blank');
-
- // The value is blank
-
-
-#### `validator()` {.collection-method}
-
-The `validator` function creates a new [validator](/docs/{{version}}/validation) instance with the given arguments. You may use it as an alternative to the `Validator` facade:
-
- $validator = validator($data, $rules, $messages);
-
-
-#### `value()` {.collection-method}
-
-The `value` function returns the value it is given. However, if you pass a closure to the function, the closure will be executed and its returned value will be returned:
-
- $result = value(true);
-
- // true
-
- $result = value(function () {
- return false;
- });
-
- // false
-
-
-#### `view()` {.collection-method}
-
-The `view` function retrieves a [view](/docs/{{version}}/views) instance:
-
- return view('auth.login');
-
-
-#### `with()` {.collection-method}
-
-The `with` function returns the value it is given. If a closure is passed as the second argument to the function, the closure will be executed and its returned value will be returned:
-
- $callback = function ($value) {
- return is_numeric($value) ? $value * 2 : 0;
- };
-
- $result = with(5, $callback);
-
- // 10
-
- $result = with(null, $callback);
-
- // 0
-
- $result = with(5, null);
-
- // 5
diff --git a/homestead.md b/homestead.md
index 25c43197487..74172ccd9bc 100644
--- a/homestead.md
+++ b/homestead.md
@@ -1,33 +1,33 @@
# Laravel Homestead
- [Introduction](#introduction)
-- [Installation & Setup](#installation-and-setup)
+- [Installation and Setup](#installation-and-setup)
- [First Steps](#first-steps)
- [Configuring Homestead](#configuring-homestead)
- [Configuring Nginx Sites](#configuring-nginx-sites)
- [Configuring Services](#configuring-services)
- - [Launching The Vagrant Box](#launching-the-vagrant-box)
+ - [Launching the Vagrant Box](#launching-the-vagrant-box)
- [Per Project Installation](#per-project-installation)
- [Installing Optional Features](#installing-optional-features)
- [Aliases](#aliases)
- [Updating Homestead](#updating-homestead)
- [Daily Usage](#daily-usage)
- - [Connecting Via SSH](#connecting-via-ssh)
+ - [Connecting via SSH](#connecting-via-ssh)
- [Adding Additional Sites](#adding-additional-sites)
- [Environment Variables](#environment-variables)
- [Ports](#ports)
- [PHP Versions](#php-versions)
- - [Connecting To Databases](#connecting-to-databases)
+ - [Connecting to Databases](#connecting-to-databases)
- [Database Backups](#database-backups)
- [Configuring Cron Schedules](#configuring-cron-schedules)
- - [Configuring MailHog](#configuring-mailhog)
+ - [Configuring Mailpit](#configuring-mailpit)
- [Configuring Minio](#configuring-minio)
- [Laravel Dusk](#laravel-dusk)
- [Sharing Your Environment](#sharing-your-environment)
-- [Debugging & Profiling](#debugging-and-profiling)
+- [Debugging and Profiling](#debugging-and-profiling)
- [Debugging Web Requests With Xdebug](#debugging-web-requests)
- [Debugging CLI Applications](#debugging-cli-applications)
- - [Profiling Applications with Blackfire](#profiling-applications-with-blackfire)
+ - [Profiling Applications With Blackfire](#profiling-applications-with-blackfire)
- [Network Interfaces](#network-interfaces)
- [Extending Homestead](#extending-homestead)
- [Provider Specific Settings](#provider-specific-settings)
@@ -36,13 +36,17 @@
## Introduction
-Laravel strives to make the entire PHP development experience delightful, including your local development environment. [Laravel Homestead](https://github.com/laravel/homestead) is an official, pre-packaged Vagrant box that provides you a wonderful development environment without requiring you to install PHP, a web server, and any other server software on your local machine.
+> [!WARNING]
+> Laravel Homestead is a legacy package that is no longer actively maintained. [Laravel Sail](/docs/{{version}}/sail) may be used as a modern alternative.
+
+Laravel strives to make the entire PHP development experience delightful, including your local development environment. [Laravel Homestead](https://github.com/laravel/homestead) is an official, pre-packaged Vagrant box that provides you a wonderful development environment without requiring you to install PHP, a web server, or any other server software on your local machine.
[Vagrant](https://www.vagrantup.com) provides a simple, elegant way to manage and provision Virtual Machines. Vagrant boxes are completely disposable. If something goes wrong, you can destroy and re-create the box in minutes!
Homestead runs on any Windows, macOS, or Linux system and includes Nginx, PHP, MySQL, PostgreSQL, Redis, Memcached, Node, and all of the other software you need to develop amazing Laravel applications.
-> {note} If you are using Windows, you may need to enable hardware virtualization (VT-x). It can usually be enabled via your BIOS. If you are using Hyper-V on a UEFI system you may additionally need to disable Hyper-V in order to access VT-x.
+> [!WARNING]
+> If you are using Windows, you may need to enable hardware virtualization (VT-x). It can usually be enabled via your BIOS. If you are using Hyper-V on a UEFI system you may additionally need to disable Hyper-V in order to access VT-x.
### Included Software
@@ -56,8 +60,11 @@ Homestead runs on any Windows, macOS, or Linux system and includes Nginx, PHP, M
-- Ubuntu 20.04
+
+- Ubuntu 22.04
- Git
+- PHP 8.3
+- PHP 8.2
- PHP 8.1
- PHP 8.0
- PHP 7.4
@@ -70,18 +77,20 @@ Homestead runs on any Windows, macOS, or Linux system and includes Nginx, PHP, M
- MySQL 8.0
- lmm
- Sqlite3
-- PostgreSQL 13
+- PostgreSQL 15
- Composer
+- Docker
- Node (With Yarn, Bower, Grunt, and Gulp)
- Redis
- Memcached
- Beanstalkd
-- Mailhog
+- Mailpit
- avahi
- ngrok
- Xdebug
- XHProf / Tideways / XHGui
- wp-cli
+
@@ -96,19 +105,21 @@ Homestead runs on any Windows, macOS, or Linux system and includes Nginx, PHP, M
+
- Apache
- Blackfire
- Cassandra
- Chronograf
- CouchDB
- Crystal & Lucky Framework
-- Docker
- Elasticsearch
- EventStoreDB
+- Flyway
- Gearman
- Go
- Grafana
- InfluxDB
+- Logstash
- MariaDB
- Meilisearch
- MinIO
@@ -120,22 +131,24 @@ Homestead runs on any Windows, macOS, or Linux system and includes Nginx, PHP, M
- Python
- R
- RabbitMQ
+- Rust
- RVM (Ruby Version Manager)
- Solr
- TimescaleDB
- Trader (PHP extension)
- Webdriver & Laravel Dusk Utilities
+
-## Installation & Setup
+## Installation and Setup
### First Steps
-Before launching your Homestead environment, you must install [Vagrant](https://www.vagrantup.com/downloads.html) as well as one of the following supported providers:
+Before launching your Homestead environment, you must install [Vagrant](https://developer.hashicorp.com/vagrant/downloads) as well as one of the following supported providers:
-- [VirtualBox 6.1.x](https://www.virtualbox.org/wiki/Downloads)
+- [VirtualBox 6.1.x](https://www.virtualbox.org/wiki/Download_Old_Builds_6_1)
- [Parallels](https://www.parallels.com/products/desktop/)
All of these software packages provide easy-to-use visual installers for all popular operating systems.
@@ -179,7 +192,8 @@ The `provider` key in your `Homestead.yaml` file indicates which Vagrant provide
provider: virtualbox
-> {note} If you are using Apple Silicon, you should add `box: laravel/homestead-arm` to your `Homestead.yaml` file. Apple Silicon requires the Parallels provider.
+> [!WARNING]
+> If you are using Apple Silicon the Parallels provider is required.
#### Configuring Shared Folders
@@ -192,7 +206,8 @@ folders:
to: /home/vagrant/project1
```
-> {note} Windows users should not use the `~/` path syntax and instead should use the full path to their project, such as `C:\Users\user\Code\project1`.
+> [!WARNING]
+> Windows users should not use the `~/` path syntax and instead should use the full path to their project, such as `C:\Users\user\Code\project1`.
You should always map individual applications to their own folder mapping instead of mapping a single large directory that contains all of your applications. When you map a folder, the virtual machine must keep track of all disk IO for *every* file in the folder. You may experience reduced performance if you have a large number of files in a folder:
@@ -204,9 +219,10 @@ folders:
to: /home/vagrant/project2
```
-> {note} You should never mount `.` (the current directory) when using Homestead. This causes Vagrant to not map the current folder to `/vagrant` and will break optional features and cause unexpected results while provisioning.
+> [!WARNING]
+> You should never mount `.` (the current directory) when using Homestead. This causes Vagrant to not map the current folder to `/vagrant` and will break optional features and cause unexpected results while provisioning.
-To enable [NFS](https://www.vagrantup.com/docs/synced-folders/nfs.html), you may add a `type` option to your folder mapping:
+To enable [NFS](https://developer.hashicorp.com/vagrant/docs/synced-folders/nfs), you may add a `type` option to your folder mapping:
```yaml
folders:
@@ -215,9 +231,10 @@ folders:
type: "nfs"
```
-> {note} When using NFS on Windows, you should consider installing the [vagrant-winnfsd](https://github.com/winnfsd/vagrant-winnfsd) plug-in. This plug-in will maintain the correct user / group permissions for files and directories within the Homestead virtual machine.
+> [!WARNING]
+> When using NFS on Windows, you should consider installing the [vagrant-winnfsd](https://github.com/winnfsd/vagrant-winnfsd) plug-in. This plug-in will maintain the correct user / group permissions for files and directories within the Homestead virtual machine.
-You may also pass any options supported by Vagrant's [Synced Folders](https://www.vagrantup.com/docs/synced-folders/basic_usage.html) by listing them under the `options` key:
+You may also pass any options supported by Vagrant's [Synced Folders](https://developer.hashicorp.com/vagrant/docs/synced-folders/basic_usage) by listing them under the `options` key:
```yaml
folders:
@@ -242,7 +259,8 @@ sites:
If you change the `sites` property after provisioning the Homestead virtual machine, you should execute the `vagrant reload --provision` command in your terminal to update the Nginx configuration on the virtual machine.
-> {note} Homestead scripts are built to be as idempotent as possible. However, if you are experiencing issues while provisioning you should destroy and rebuild the machine by executing the `vagrant destroy && vagrant up` command.
+> [!WARNING]
+> Homestead scripts are built to be as idempotent as possible. However, if you are experiencing issues while provisioning you should destroy and rebuild the machine by executing the `vagrant destroy && vagrant up` command.
#### Hostname Resolution
@@ -251,7 +269,9 @@ Homestead publishes hostnames using `mDNS` for automatic host resolution. If you
Using automatic hostnames works best for [per project installations](#per-project-installation) of Homestead. If you host multiple sites on a single Homestead instance, you may add the "domains" for your web sites to the `hosts` file on your machine. The `hosts` file will redirect requests for your Homestead sites into your Homestead virtual machine. On macOS and Linux, this file is located at `/etc/hosts`. On Windows, it is located at `C:\Windows\System32\drivers\etc\hosts`. The lines you add to this file will look like the following:
- 192.168.56.56 homestead.test
+```text
+192.168.56.56 homestead.test
+```
Make sure the IP address listed is the one set in your `Homestead.yaml` file. Once you have added the domain to your `hosts` file and launched the Vagrant box you will be able to access the site via your web browser:
@@ -275,7 +295,7 @@ services:
The specified services will be started or stopped based on their order in the `enabled` and `disabled` directives.
-### Launching The Vagrant Box
+### Launching the Vagrant Box
Once you have edited the `Homestead.yaml` to your liking, run the `vagrant up` command from your Homestead directory. Vagrant will boot the virtual machine and automatically configure your shared folders and Nginx sites.
@@ -320,15 +340,17 @@ features:
- chronograf: true
- couchdb: true
- crystal: true
- - docker: true
+ - dragonflydb: true
- elasticsearch:
version: 7.9.0
- eventstore: true
version: 21.2.0
+ - flyway: true
- gearman: true
- golang: true
- grafana: true
- influxdb: true
+ - logstash: true
- mariadb: true
- meilisearch: true
- minio: true
@@ -340,6 +362,7 @@ features:
- python: true
- r-base: true
- rabbitmq: true
+ - rustc: true
- rvm: true
- solr: true
- timescaledb: true
@@ -352,7 +375,8 @@ features:
You may specify a supported version of Elasticsearch, which must be an exact version number (major.minor.patch). The default installation will create a cluster named 'homestead'. You should never give Elasticsearch more than half of the operating system's memory, so make sure your Homestead virtual machine has at least twice the Elasticsearch allocation.
-> {tip} Check out the [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current) to learn how to customize your configuration.
+> [!NOTE]
+> Check out the [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current) to learn how to customize your configuration.
#### MariaDB
@@ -432,7 +456,7 @@ vagrant up
## Daily Usage
-### Connecting Via SSH
+### Connecting via SSH
You can SSH into your virtual machine by executing the `vagrant ssh` terminal command from your Homestead directory.
@@ -449,12 +473,15 @@ sites:
to: /home/vagrant/project2/public
```
-> {note} You should ensure that you have configured a [folder mapping](#configuring-shared-folders) for the project's directory before adding the site.
+> [!WARNING]
+> You should ensure that you have configured a [folder mapping](#configuring-shared-folders) for the project's directory before adding the site.
If Vagrant is not automatically managing your "hosts" file, you may need to add the new site to that file as well. On macOS and Linux, this file is located at `/etc/hosts`. On Windows, it is located at `C:\Windows\System32\drivers\etc\hosts`:
- 192.168.56.56 homestead.test
- 192.168.56.56 another.test
+```text
+192.168.56.56 homestead.test
+192.168.56.56 another.test
+```
Once the site has been added, execute the `vagrant reload --provision` terminal command from your Homestead directory.
@@ -470,7 +497,7 @@ sites:
type: "statamic"
```
-The available site types are: `apache`, `apigility`, `expressive`, `laravel` (the default), `proxy`, `silverstripe`, `statamic`, `symfony2`, `symfony4`, and `zf`.
+The available site types are: `apache`, `apache-proxy`, `apigility`, `expressive`, `laravel` (the default), `proxy` (for nginx), `silverstripe`, `statamic`, `symfony2`, `symfony4`, and `zf`.
#### Site Parameters
@@ -536,7 +563,7 @@ Below is a list of additional Homestead service ports that you may wish to map f
- **MySQL:** 33060 → To 3306
- **PostgreSQL:** 54320 → To 5432
- **MongoDB:** 27017 → To 27017
-- **Mailhog:** 8025 → To 8025
+- **Mailpit:** 8025 → To 8025
- **Minio:** 9600 → To 9600
+
+- `minProcesses` defines the minimum number of worker processes per queue. This value must be greater than or equal to 1.
+- `maxProcesses` defines the maximum total number of worker processes Horizon may scale up to across all queues. This value should typically be greater than the number of queues multiplied by the `minProcesses` value. To prevent the supervisor from spawning any processes, you may set this value to 0.
+
+
+
+For example, you may configure Horizon to maintain at least one process per queue and scale up to a total of 10 worker processes:
+
+```php
+'environments' => [
+ 'production' => [
+ 'supervisor-1' => [
+ 'connection' => 'redis',
+ 'queue' => ['default', 'notifications'],
+ 'balance' => 'auto',
+ 'autoScalingStrategy' => 'time',
+ 'minProcesses' => 1,
+ 'maxProcesses' => 10,
+ 'balanceMaxShift' => 1,
+ 'balanceCooldown' => 3,
+ ],
+ ],
+],
+```
+
+The `autoScalingStrategy` configuration option determines how Horizon will assign more worker processes to queues. You can choose between two strategies:
+
+
+
+- The `time` strategy will assign workers based on the total estimated amount of time it will take to clear the queue.
+- The `size` strategy will assign workers based on the total number of jobs on the queue.
+
+
+
+The `balanceMaxShift` and `balanceCooldown` configuration values determine how quickly Horizon will scale to meet worker demand. In the example above, a maximum of one new process will be created or destroyed every three seconds. You are free to tweak these values as necessary based on your application's needs.
+
+
+#### Queue Priorities and Auto Balancing
+
+When using the `auto` balancing strategy, Horizon does not enforce strict priority between queues. The order of queues in a supervisor's configuration does not affect how worker processes are assigned. Instead, Horizon relies on the selected `autoScalingStrategy` to dynamically allocate worker processes based on queue load.
+
+For example, in the following configuration, the high queue is not prioritized over the default queue, despite appearing first in the list:
+
+```php
+'environments' => [
+ 'production' => [
+ 'supervisor-1' => [
+ // ...
+ 'queue' => ['high', 'default'],
+ 'minProcesses' => 1,
+ 'maxProcesses' => 10,
+ ],
+ ],
+],
+```
+
+If you need to enforce a relative priority between queues, you may define multiple supervisors and explicitly allocate processing resources:
+
+```php
+'environments' => [
+ 'production' => [
+ 'supervisor-1' => [
+ // ...
+ 'queue' => ['default'],
+ 'minProcesses' => 1,
+ 'maxProcesses' => 10,
+ ],
+ 'supervisor-2' => [
+ // ...
+ 'queue' => ['images'],
+ 'minProcesses' => 1,
+ 'maxProcesses' => 1,
+ ],
+ ],
+],
+```
+
+In this example, the default `queue` can scale up to 10 processes, while the `images` queue is limited to one process. This configuration ensures that your queues can scale independently.
+
+> [!NOTE]
+> When dispatching resource-intensive jobs, it's sometimes best to assign them to a dedicated queue with a limited `maxProcesses` value. Otherwise, these jobs could consume excessive CPU resources and overload your system.
+
+
+### Simple Balancing
+
+The `simple` strategy distributes worker processes evenly across the specified queues. With this strategy, Horizon does not automatically scale the number of worker processes. Rather, it uses a fixed number of processes:
+
+```php
+'environments' => [
+ 'production' => [
+ 'supervisor-1' => [
+ // ...
+ 'queue' => ['default', 'notifications'],
+ 'balance' => 'simple',
+ 'processes' => 10,
+ ],
+ ],
+],
+```
+
+In the example above, Horizon will assign 5 processes to each queue, splitting the total of 10 evenly.
+
+If you'd like to control the number of worker processes assigned to each queue individually, you can define multiple supervisors:
+
+```php
+'environments' => [
+ 'production' => [
+ 'supervisor-1' => [
+ // ...
+ 'queue' => ['default'],
+ 'balance' => 'simple',
+ 'processes' => 10,
+ ],
+ 'supervisor-notifications' => [
+ // ...
+ 'queue' => ['notifications'],
+ 'balance' => 'simple',
+ 'processes' => 2,
+ ],
+ ],
+],
+```
+
+With this configuration, Horizon will assign 10 processes to the `default` queue and 2 processes to the `notifications` queue.
+
+
+### No Balancing
+
+When the `balance` option is set to `false`, Horizon processes queues strictly in the order they're listed, similar to Laravel's default queue system. However, it will still scale the number of worker processes if jobs begin to accumulate:
+
+```php
+'environments' => [
+ 'production' => [
+ 'supervisor-1' => [
+ // ...
+ 'queue' => ['default', 'notifications'],
+ 'balance' => false,
+ 'minProcesses' => 1,
+ 'maxProcesses' => 10,
+ ],
+ ],
+],
+```
+
+In the example above, jobs in the `default` queue are always prioritized over jobs in the `notifications` queue. For instance, if there are 1,000 jobs in `default` and only 10 in `notifications`, Horizon will fully process all `default` jobs before handling any from `notifications`.
+
+You can control Horizon's ability to scale worker processes using the `minProcesses` and `maxProcesses` options:
+
+
+
+- `minProcesses` defines the minimum number of worker processes in total. This value must be greater than or equal to 1.
+- `maxProcesses` defines the maximum total number of worker processes Horizon may scale up to.
+
+
+
+
+## Upgrading Horizon
+
+When upgrading to a new major version of Horizon, it's important that you carefully review [the upgrade guide](https://github.com/laravel/horizon/blob/master/UPGRADE.md).
+
## Running Horizon
@@ -194,7 +467,13 @@ You may check the current status of the Horizon process using the `horizon:statu
php artisan horizon:status
```
-You may gracefully terminate the Horizon process using the `horizon:terminate` Artisan command. Any jobs that are currently being processed by will be completed and then Horizon will stop executing:
+You may check the current status of a specific Horizon [supervisor](#supervisors) using the `horizon:supervisor-status` Artisan command:
+
+```shell
+php artisan horizon:supervisor-status supervisor-1
+```
+
+You may gracefully terminate the Horizon process using the `horizon:terminate` Artisan command. Any jobs that are currently being processed will be completed and then Horizon will stop executing:
```shell
php artisan horizon:terminate
@@ -220,7 +499,8 @@ Supervisor is a process monitor for the Linux operating system and will automati
sudo apt-get install supervisor
```
-> {tip} If configuring Supervisor yourself sounds overwhelming, consider using [Laravel Forge](https://forge.laravel.com), which will automatically install and configure Supervisor for your Laravel projects.
+> [!NOTE]
+> If configuring Supervisor yourself sounds overwhelming, consider using [Laravel Cloud](https://cloud.laravel.com), which can manage background processes for your Laravel applications.
#### Supervisor Configuration
@@ -239,7 +519,10 @@ stdout_logfile=/home/forge/example.com/horizon.log
stopwaitsecs=3600
```
-> {note} You should ensure that the value of `stopwaitsecs` is greater than the number of seconds consumed by your longest running job. Otherwise, Supervisor may kill the job before it is finished processing.
+When defining your Supervisor configuration, you should ensure that the value of `stopwaitsecs` is greater than the number of seconds consumed by your longest running job. Otherwise, Supervisor may kill the job before it is finished processing.
+
+> [!WARNING]
+> While the examples above are valid for Ubuntu based servers, the location and file extension expected of Supervisor configuration files may vary between other server operating systems. Please consult your server's documentation for more information.
#### Starting Supervisor
@@ -254,130 +537,148 @@ sudo supervisorctl update
sudo supervisorctl start horizon
```
-> {tip} For more information on running Supervisor, consult the [Supervisor documentation](http://supervisord.org/index.html).
+> [!NOTE]
+> For more information on running Supervisor, consult the [Supervisor documentation](http://supervisord.org/index.html).
## Tags
-Horizon allows you to assign “tags” to jobs, including mailables, broadcast events, notifications, and queued event listeners. In fact, Horizon will intelligently and automatically tag most jobs depending on the Eloquent models that are attached to the job. For example, take a look at the following job:
+Horizon allows you to assign "tags" to jobs, including mailables, broadcast events, notifications, and queued event listeners. In fact, Horizon will intelligently and automatically tag most jobs depending on the Eloquent models that are attached to the job. For example, take a look at the following job:
- video = $video;
- }
-
- /**
- * Execute the job.
- *
- * @return void
- */
- public function handle()
- {
- //
- }
+ // ...
}
+}
+```
If this job is queued with an `App\Models\Video` instance that has an `id` attribute of `1`, it will automatically receive the tag `App\Models\Video:1`. This is because Horizon will search the job's properties for any Eloquent models. If Eloquent models are found, Horizon will intelligently tag the job using the model's class name and primary key:
- use App\Jobs\RenderVideo;
- use App\Models\Video;
+```php
+use App\Jobs\RenderVideo;
+use App\Models\Video;
- $video = Video::find(1);
+$video = Video::find(1);
- RenderVideo::dispatch($video);
+RenderVideo::dispatch($video);
+```
#### Manually Tagging Jobs
If you would like to manually define the tags for one of your queueable objects, you may define a `tags` method on the class:
- class RenderVideo implements ShouldQueue
+```php
+class RenderVideo implements ShouldQueue
+{
+ /**
+ * Get the tags that should be assigned to the job.
+ *
+ * @return array
+[assertAccepted](#assert-accepted)
+[assertBadRequest](#assert-bad-request)
+[assertClientError](#assert-client-error)
+[assertConflict](#assert-conflict)
[assertCookie](#assert-cookie)
[assertCookieExpired](#assert-cookie-expired)
[assertCookieNotExpired](#assert-cookie-not-expired)
@@ -618,31 +974,51 @@ Laravel's `Illuminate\Testing\TestResponse` class provides a variety of custom a
[assertDontSeeText](#assert-dont-see-text)
[assertDownload](#assert-download)
[assertExactJson](#assert-exact-json)
+[assertExactJsonStructure](#assert-exact-json-structure)
[assertForbidden](#assert-forbidden)
+[assertFound](#assert-found)
+[assertGone](#assert-gone)
[assertHeader](#assert-header)
[assertHeaderMissing](#assert-header-missing)
+[assertInternalServerError](#assert-internal-server-error)
[assertJson](#assert-json)
[assertJsonCount](#assert-json-count)
[assertJsonFragment](#assert-json-fragment)
+[assertJsonIsArray](#assert-json-is-array)
+[assertJsonIsObject](#assert-json-is-object)
[assertJsonMissing](#assert-json-missing)
[assertJsonMissingExact](#assert-json-missing-exact)
[assertJsonMissingValidationErrors](#assert-json-missing-validation-errors)
[assertJsonPath](#assert-json-path)
+[assertJsonMissingPath](#assert-json-missing-path)
[assertJsonStructure](#assert-json-structure)
[assertJsonValidationErrors](#assert-json-validation-errors)
[assertJsonValidationErrorFor](#assert-json-validation-error-for)
[assertLocation](#assert-location)
+[assertMethodNotAllowed](#assert-method-not-allowed)
+[assertMovedPermanently](#assert-moved-permanently)
+[assertContent](#assert-content)
[assertNoContent](#assert-no-content)
+[assertStreamed](#assert-streamed)
+[assertStreamedContent](#assert-streamed-content)
[assertNotFound](#assert-not-found)
[assertOk](#assert-ok)
+[assertPaymentRequired](#assert-payment-required)
[assertPlainCookie](#assert-plain-cookie)
[assertRedirect](#assert-redirect)
+[assertRedirectBack](#assert-redirect-back)
+[assertRedirectBackWithErrors](#assert-redirect-back-with-errors)
+[assertRedirectBackWithoutErrors](#assert-redirect-back-without-errors)
[assertRedirectContains](#assert-redirect-contains)
+[assertRedirectToRoute](#assert-redirect-to-route)
[assertRedirectToSignedRoute](#assert-redirect-to-signed-route)
+[assertRequestTimeout](#assert-request-timeout)
[assertSee](#assert-see)
[assertSeeInOrder](#assert-see-in-order)
[assertSeeText](#assert-see-text)
[assertSeeTextInOrder](#assert-see-text-in-order)
+[assertServerError](#assert-server-error)
+[assertServiceUnavailable](#assert-service-unavailable)
[assertSessionHas](#assert-session-has)
[assertSessionHasInput](#assert-session-has-input)
[assertSessionHasAll](#assert-session-has-all)
@@ -651,11 +1027,12 @@ Laravel's `Illuminate\Testing\TestResponse` class provides a variety of custom a
[assertSessionHasNoErrors](#assert-session-has-no-errors)
[assertSessionDoesntHaveErrors](#assert-session-doesnt-have-errors)
[assertSessionMissing](#assert-session-missing)
-[assertSimilarJson](#assert-similar-json)
[assertStatus](#assert-status)
[assertSuccessful](#assert-successful)
+[assertTooManyRequests](#assert-too-many-requests)
[assertUnauthorized](#assert-unauthorized)
[assertUnprocessable](#assert-unprocessable)
+[assertUnsupportedMediaType](#assert-unsupported-media-type)
[assertValid](#assert-valid)
[assertInvalid](#assert-invalid)
[assertViewHas](#assert-view-has)
@@ -665,160 +1042,293 @@ Laravel's `Illuminate\Testing\TestResponse` class provides a variety of custom a
+
+#### assertAccepted
+
+Assert that the response has an accepted (202) HTTP status code:
+
+```php
+$response->assertAccepted();
+```
+
+
+#### assertBadRequest
+
+Assert that the response has a bad request (400) HTTP status code:
+
+```php
+$response->assertBadRequest();
+```
+
+
+#### assertClientError
+
+Assert that the response has a client error (>= 400, < 500) HTTP status code:
+
+```php
+$response->assertClientError();
+```
+
+
+#### assertConflict
+
+Assert that the response has a conflict (409) HTTP status code:
+
+```php
+$response->assertConflict();
+```
+
#### assertCookie
Assert that the response contains the given cookie:
- $response->assertCookie($cookieName, $value = null);
+```php
+$response->assertCookie($cookieName, $value = null);
+```
#### assertCookieExpired
Assert that the response contains the given cookie and it is expired:
- $response->assertCookieExpired($cookieName);
+```php
+$response->assertCookieExpired($cookieName);
+```
#### assertCookieNotExpired
Assert that the response contains the given cookie and it is not expired:
- $response->assertCookieNotExpired($cookieName);
+```php
+$response->assertCookieNotExpired($cookieName);
+```
#### assertCookieMissing
-Assert that the response does not contains the given cookie:
+Assert that the response does not contain the given cookie:
- $response->assertCookieMissing($cookieName);
+```php
+$response->assertCookieMissing($cookieName);
+```
#### assertCreated
Assert that the response has a 201 HTTP status code:
- $response->assertCreated();
+```php
+$response->assertCreated();
+```
#### assertDontSee
Assert that the given string is not contained within the response returned by the application. This assertion will automatically escape the given string unless you pass a second argument of `false`:
- $response->assertDontSee($value, $escaped = true);
+```php
+$response->assertDontSee($value, $escape = true);
+```
#### assertDontSeeText
Assert that the given string is not contained within the response text. This assertion will automatically escape the given string unless you pass a second argument of `false`. This method will pass the response content to the `strip_tags` PHP function before making the assertion:
- $response->assertDontSeeText($value, $escaped = true);
+```php
+$response->assertDontSeeText($value, $escape = true);
+```
#### assertDownload
Assert that the response is a "download". Typically, this means the invoked route that returned the response returned a `Response::download` response, `BinaryFileResponse`, or `Storage::download` response:
- $response->assertDownload();
+```php
+$response->assertDownload();
+```
If you wish, you may assert that the downloadable file was assigned a given file name:
- $response->assertDownload('image.jpg');
+```php
+$response->assertDownload('image.jpg');
+```
#### assertExactJson
Assert that the response contains an exact match of the given JSON data:
- $response->assertExactJson(array $data);
+```php
+$response->assertExactJson(array $data);
+```
+
+
+#### assertExactJsonStructure
+
+Assert that the response contains an exact match of the given JSON structure:
+
+```php
+$response->assertExactJsonStructure(array $data);
+```
+
+This method is a more strict variant of [assertJsonStructure](#assert-json-structure). In contrast with `assertJsonStructure`, this method will fail if the response contains any keys that aren't explicitly included in the expected JSON structure.
#### assertForbidden
Assert that the response has a forbidden (403) HTTP status code:
- $response->assertForbidden();
+```php
+$response->assertForbidden();
+```
+
+
+#### assertFound
+
+Assert that the response has a found (302) HTTP status code:
+
+```php
+$response->assertFound();
+```
+
+
+#### assertGone
+
+Assert that the response has a gone (410) HTTP status code:
+
+```php
+$response->assertGone();
+```
#### assertHeader
Assert that the given header and value is present on the response:
- $response->assertHeader($headerName, $value = null);
+```php
+$response->assertHeader($headerName, $value = null);
+```
#### assertHeaderMissing
Assert that the given header is not present on the response:
- $response->assertHeaderMissing($headerName);
+```php
+$response->assertHeaderMissing($headerName);
+```
+
+
+#### assertInternalServerError
+
+Assert that the response has an "Internal Server Error" (500) HTTP status code:
+
+```php
+$response->assertInternalServerError();
+```
#### assertJson
Assert that the response contains the given JSON data:
- $response->assertJson(array $data, $strict = false);
+```php
+$response->assertJson(array $data, $strict = false);
+```
-The `assertJson` method converts the response to an array and utilizes `PHPUnit::assertArraySubset` to verify that the given array exists within the JSON response returned by the application. So, if there are other properties in the JSON response, this test will still pass as long as the given fragment is present.
+The `assertJson` method converts the response to an array to verify that the given array exists within the JSON response returned by the application. So, if there are other properties in the JSON response, this test will still pass as long as the given fragment is present.
#### assertJsonCount
Assert that the response JSON has an array with the expected number of items at the given key:
- $response->assertJsonCount($count, $key = null);
+```php
+$response->assertJsonCount($count, $key = null);
+```
#### assertJsonFragment
Assert that the response contains the given JSON data anywhere in the response:
- Route::get('/users', function () {
- return [
- 'users' => [
- [
- 'name' => 'Taylor Otwell',
- ],
+```php
+Route::get('/users', function () {
+ return [
+ 'users' => [
+ [
+ 'name' => 'Taylor Otwell',
],
- ];
- });
+ ],
+ ];
+});
+
+$response->assertJsonFragment(['name' => 'Taylor Otwell']);
+```
+
+
+#### assertJsonIsArray
+
+Assert that the response JSON is an array:
+
+```php
+$response->assertJsonIsArray();
+```
+
+
+#### assertJsonIsObject
- $response->assertJsonFragment(['name' => 'Taylor Otwell']);
+Assert that the response JSON is an object:
+
+```php
+$response->assertJsonIsObject();
+```
#### assertJsonMissing
Assert that the response does not contain the given JSON data:
- $response->assertJsonMissing(array $data);
+```php
+$response->assertJsonMissing(array $data);
+```
#### assertJsonMissingExact
Assert that the response does not contain the exact JSON data:
- $response->assertJsonMissingExact(array $data);
+```php
+$response->assertJsonMissingExact(array $data);
+```
#### assertJsonMissingValidationErrors
Assert that the response has no JSON validation errors for the given keys:
- $response->assertJsonMissingValidationErrors($keys);
+```php
+$response->assertJsonMissingValidationErrors($keys);
+```
-> {tip} The more generic [assertValid](#assert-valid) method may be used to assert that a response does not have validation errors that were returned as JSON **and** that no errors were flashed to session storage.
+> [!NOTE]
+> The more generic [assertValid](#assert-valid) method may be used to assert that a response does not have validation errors that were returned as JSON **and** that no errors were flashed to session storage.
#### assertJsonPath
Assert that the response contains the given data at the specified path:
- $response->assertJsonPath($path, $expectedValue);
+```php
+$response->assertJsonPath($path, $expectedValue);
+```
-For example, if the JSON response returned by your application contains the following data:
+For example, if the following JSON response is returned by your application:
-```js
+```json
{
"user": {
"name": "Steve Schoger"
@@ -828,18 +1338,47 @@ For example, if the JSON response returned by your application contains the foll
You may assert that the `name` property of the `user` object matches a given value like so:
- $response->assertJsonPath('user.name', 'Steve Schoger');
+```php
+$response->assertJsonPath('user.name', 'Steve Schoger');
+```
+
+
+#### assertJsonMissingPath
+
+Assert that the response does not contain the given path:
+
+```php
+$response->assertJsonMissingPath($path);
+```
+
+For example, if the following JSON response is returned by your application:
+
+```json
+{
+ "user": {
+ "name": "Steve Schoger"
+ }
+}
+```
+
+You may assert that it does not contain the `email` property of the `user` object:
+
+```php
+$response->assertJsonMissingPath('user.email');
+```
#### assertJsonStructure
Assert that the response has a given JSON structure:
- $response->assertJsonStructure(array $structure);
+```php
+$response->assertJsonStructure(array $structure);
+```
For example, if the JSON response returned by your application contains the following data:
-```js
+```json
{
"user": {
"name": "Steve Schoger"
@@ -849,15 +1388,17 @@ For example, if the JSON response returned by your application contains the foll
You may assert that the JSON structure matches your expectations like so:
- $response->assertJsonStructure([
- 'user' => [
- 'name',
- ]
- ]);
+```php
+$response->assertJsonStructure([
+ 'user' => [
+ 'name',
+ ]
+]);
+```
Sometimes, JSON responses returned by your application may contain arrays of objects:
-```js
+```json
{
"user": [
{
@@ -876,307 +1417,547 @@ Sometimes, JSON responses returned by your application may contain arrays of obj
In this situation, you may use the `*` character to assert against the structure of all of the objects in the array:
- $response->assertJsonStructure([
- 'user' => [
- '*' => [
- 'name',
- 'age',
- 'location'
- ]
+```php
+$response->assertJsonStructure([
+ 'user' => [
+ '*' => [
+ 'name',
+ 'age',
+ 'location'
]
- ]);
+ ]
+]);
+```
#### assertJsonValidationErrors
Assert that the response has the given JSON validation errors for the given keys. This method should be used when asserting against responses where the validation errors are returned as a JSON structure instead of being flashed to the session:
- $response->assertJsonValidationErrors(array $data, $responseKey = 'errors');
+```php
+$response->assertJsonValidationErrors(array $data, $responseKey = 'errors');
+```
-> {tip} The more generic [assertInvalid](#assert-invalid) method may be used to assert that a response has validation errors returned as JSON **or** that errors were flashed to session storage.
+> [!NOTE]
+> The more generic [assertInvalid](#assert-invalid) method may be used to assert that a response has validation errors returned as JSON **or** that errors were flashed to session storage.
#### assertJsonValidationErrorFor
Assert the response has any JSON validation errors for the given key:
- $response->assertJsonValidationErrorFor(string $key, $responseKey = 'errors');
+```php
+$response->assertJsonValidationErrorFor(string $key, $responseKey = 'errors');
+```
+
+
+#### assertMethodNotAllowed
+
+Assert that the response has a method not allowed (405) HTTP status code:
+
+```php
+$response->assertMethodNotAllowed();
+```
+
+
+#### assertMovedPermanently
+
+Assert that the response has a moved permanently (301) HTTP status code:
+
+```php
+$response->assertMovedPermanently();
+```
#### assertLocation
Assert that the response has the given URI value in the `Location` header:
- $response->assertLocation($uri);
+```php
+$response->assertLocation($uri);
+```
+
+
+#### assertContent
+
+Assert that the given string matches the response content:
+
+```php
+$response->assertContent($value);
+```
#### assertNoContent
Assert that the response has the given HTTP status code and no content:
- $response->assertNoContent($status = 204);
+```php
+$response->assertNoContent($status = 204);
+```
+
+
+#### assertStreamed
+
+Assert that the response was a streamed response:
+
+ $response->assertStreamed();
+
+
+#### assertStreamedContent
+
+Assert that the given string matches the streamed response content:
+
+```php
+$response->assertStreamedContent($value);
+```
#### assertNotFound
Assert that the response has a not found (404) HTTP status code:
- $response->assertNotFound();
+```php
+$response->assertNotFound();
+```
#### assertOk
Assert that the response has a 200 HTTP status code:
- $response->assertOk();
+```php
+$response->assertOk();
+```
+
+
+#### assertPaymentRequired
+
+Assert that the response has a payment required (402) HTTP status code:
+
+```php
+$response->assertPaymentRequired();
+```
#### assertPlainCookie
Assert that the response contains the given unencrypted cookie:
- $response->assertPlainCookie($cookieName, $value = null);
+```php
+$response->assertPlainCookie($cookieName, $value = null);
+```
#### assertRedirect
Assert that the response is a redirect to the given URI:
- $response->assertRedirect($uri);
+```php
+$response->assertRedirect($uri = null);
+```
+
+
+#### assertRedirectBack
+
+Assert whether the response is redirecting back to the previous page:
+
+```php
+$response->assertRedirectBack();
+```
+
+
+#### assertRedirectBackWithErrors
+
+Assert whether the response is redirecting back to the previous page and the [session has the given errors](#assert-session-has-errors):
+
+```php
+$response->assertRedirectBackWithErrors(
+ array $keys = [], $format = null, $errorBag = 'default'
+);
+```
+
+
+#### assertRedirectBackWithoutErrors
+
+Assert whether the response is redirecting back to the previous page and the session does not contain any error messages:
+
+```php
+$response->assertRedirectBackWithoutErrors();
+```
#### assertRedirectContains
Assert whether the response is redirecting to a URI that contains the given string:
- $response->assertRedirectContains($string);
+```php
+$response->assertRedirectContains($string);
+```
+
+
+#### assertRedirectToRoute
+
+Assert that the response is a redirect to the given [named route](/docs/{{version}}/routing#named-routes):
+
+```php
+$response->assertRedirectToRoute($name, $parameters = []);
+```
#### assertRedirectToSignedRoute
-Assert that the response is a redirect to the given signed route:
+Assert that the response is a redirect to the given [signed route](/docs/{{version}}/urls#signed-urls):
- $response->assertRedirectToSignedRoute($name = null, $parameters = []);
+```php
+$response->assertRedirectToSignedRoute($name = null, $parameters = []);
+```
+
+
+#### assertRequestTimeout
+
+Assert that the response has a request timeout (408) HTTP status code:
+
+```php
+$response->assertRequestTimeout();
+```
#### assertSee
Assert that the given string is contained within the response. This assertion will automatically escape the given string unless you pass a second argument of `false`:
- $response->assertSee($value, $escaped = true);
+```php
+$response->assertSee($value, $escape = true);
+```
#### assertSeeInOrder
Assert that the given strings are contained in order within the response. This assertion will automatically escape the given strings unless you pass a second argument of `false`:
- $response->assertSeeInOrder(array $values, $escaped = true);
+```php
+$response->assertSeeInOrder(array $values, $escape = true);
+```
#### assertSeeText
Assert that the given string is contained within the response text. This assertion will automatically escape the given string unless you pass a second argument of `false`. The response content will be passed to the `strip_tags` PHP function before the assertion is made:
- $response->assertSeeText($value, $escaped = true);
+```php
+$response->assertSeeText($value, $escape = true);
+```
#### assertSeeTextInOrder
Assert that the given strings are contained in order within the response text. This assertion will automatically escape the given strings unless you pass a second argument of `false`. The response content will be passed to the `strip_tags` PHP function before the assertion is made:
- $response->assertSeeTextInOrder(array $values, $escaped = true);
+```php
+$response->assertSeeTextInOrder(array $values, $escape = true);
+```
+
+
+#### assertServerError
+
+Assert that the response has a server error (>= 500 , < 600) HTTP status code:
+
+```php
+$response->assertServerError();
+```
+
+
+#### assertServiceUnavailable
+
+Assert that the response has a "Service Unavailable" (503) HTTP status code:
+
+```php
+$response->assertServiceUnavailable();
+```
#### assertSessionHas
Assert that the session contains the given piece of data:
- $response->assertSessionHas($key, $value = null);
+```php
+$response->assertSessionHas($key, $value = null);
+```
If needed, a closure can be provided as the second argument to the `assertSessionHas` method. The assertion will pass if the closure returns `true`:
- $response->assertSessionHas($key, function ($value) {
- return $value->name === 'Taylor Otwell';
- });
+```php
+$response->assertSessionHas($key, function (User $value) {
+ return $value->name === 'Taylor Otwell';
+});
+```
#### assertSessionHasInput
Assert that the session has a given value in the [flashed input array](/docs/{{version}}/responses#redirecting-with-flashed-session-data):
- $response->assertSessionHasInput($key, $value = null);
+```php
+$response->assertSessionHasInput($key, $value = null);
+```
If needed, a closure can be provided as the second argument to the `assertSessionHasInput` method. The assertion will pass if the closure returns `true`:
- $response->assertSessionHasInput($key, function ($value) {
- return Crypt::decryptString($value) === 'secret';
- });
+```php
+use Illuminate\Support\Facades\Crypt;
+
+$response->assertSessionHasInput($key, function (string $value) {
+ return Crypt::decryptString($value) === 'secret';
+});
+```
#### assertSessionHasAll
Assert that the session contains a given array of key / value pairs:
- $response->assertSessionHasAll(array $data);
+```php
+$response->assertSessionHasAll(array $data);
+```
For example, if your application's session contains `name` and `status` keys, you may assert that both exist and have the specified values like so:
- $response->assertSessionHasAll([
- 'name' => 'Taylor Otwell',
- 'status' => 'active',
- ]);
+```php
+$response->assertSessionHasAll([
+ 'name' => 'Taylor Otwell',
+ 'status' => 'active',
+]);
+```
#### assertSessionHasErrors
Assert that the session contains an error for the given `$keys`. If `$keys` is an associative array, assert that the session contains a specific error message (value) for each field (key). This method should be used when testing routes that flash validation errors to the session instead of returning them as a JSON structure:
- $response->assertSessionHasErrors(
- array $keys, $format = null, $errorBag = 'default'
- );
+```php
+$response->assertSessionHasErrors(
+ array $keys = [], $format = null, $errorBag = 'default'
+);
+```
For example, to assert that the `name` and `email` fields have validation error messages that were flashed to the session, you may invoke the `assertSessionHasErrors` method like so:
- $response->assertSessionHasErrors(['name', 'email']);
+```php
+$response->assertSessionHasErrors(['name', 'email']);
+```
Or, you may assert that a given field has a particular validation error message:
- $response->assertSessionHasErrors([
- 'name' => 'The given name was invalid.'
- ]);
+```php
+$response->assertSessionHasErrors([
+ 'name' => 'The given name was invalid.'
+]);
+```
+
+> [!NOTE]
+> The more generic [assertInvalid](#assert-invalid) method may be used to assert that a response has validation errors returned as JSON **or** that errors were flashed to session storage.
#### assertSessionHasErrorsIn
Assert that the session contains an error for the given `$keys` within a specific [error bag](/docs/{{version}}/validation#named-error-bags). If `$keys` is an associative array, assert that the session contains a specific error message (value) for each field (key), within the error bag:
- $response->assertSessionHasErrorsIn($errorBag, $keys = [], $format = null);
+```php
+$response->assertSessionHasErrorsIn($errorBag, $keys = [], $format = null);
+```
#### assertSessionHasNoErrors
Assert that the session has no validation errors:
- $response->assertSessionHasNoErrors();
+```php
+$response->assertSessionHasNoErrors();
+```
#### assertSessionDoesntHaveErrors
Assert that the session has no validation errors for the given keys:
- $response->assertSessionDoesntHaveErrors($keys = [], $format = null, $errorBag = 'default');
+```php
+$response->assertSessionDoesntHaveErrors($keys = [], $format = null, $errorBag = 'default');
+```
+
+> [!NOTE]
+> The more generic [assertValid](#assert-valid) method may be used to assert that a response does not have validation errors that were returned as JSON **and** that no errors were flashed to session storage.
#### assertSessionMissing
Assert that the session does not contain the given key:
- $response->assertSessionMissing($key);
+```php
+$response->assertSessionMissing($key);
+```
#### assertStatus
Assert that the response has a given HTTP status code:
- $response->assertStatus($code);
+```php
+$response->assertStatus($code);
+```
#### assertSuccessful
Assert that the response has a successful (>= 200 and < 300) HTTP status code:
- $response->assertSuccessful();
+```php
+$response->assertSuccessful();
+```
+
+
+#### assertTooManyRequests
+
+Assert that the response has a too many requests (429) HTTP status code:
+
+```php
+$response->assertTooManyRequests();
+```
#### assertUnauthorized
Assert that the response has an unauthorized (401) HTTP status code:
- $response->assertUnauthorized();
+```php
+$response->assertUnauthorized();
+```
#### assertUnprocessable
Assert that the response has an unprocessable entity (422) HTTP status code:
- $response->assertUnprocessable();
+```php
+$response->assertUnprocessable();
+```
+
+
+#### assertUnsupportedMediaType
+
+Assert that the response has an unsupported media type (415) HTTP status code:
+
+```php
+$response->assertUnsupportedMediaType();
+```
#### assertValid
Assert that the response has no validation errors for the given keys. This method may be used for asserting against responses where the validation errors are returned as a JSON structure or where the validation errors have been flashed to the session:
- // Assert that no validation errors are present...
- $response->assertValid();
+```php
+// Assert that no validation errors are present...
+$response->assertValid();
- // Assert that the given keys do not have validation errors...
- $response->assertValid(['name', 'email']);
+// Assert that the given keys do not have validation errors...
+$response->assertValid(['name', 'email']);
+```
#### assertInvalid
Assert that the response has validation errors for the given keys. This method may be used for asserting against responses where the validation errors are returned as a JSON structure or where the validation errors have been flashed to the session:
- $response->assertInvalid(['name', 'email']);
+```php
+$response->assertInvalid(['name', 'email']);
+```
You may also assert that a given key has a particular validation error message. When doing so, you may provide the entire message or only a small portion of the message:
- $response->assertInvalid([
- 'name' => 'The name field is required.',
- 'email' => 'valid email address',
- ]);
+```php
+$response->assertInvalid([
+ 'name' => 'The name field is required.',
+ 'email' => 'valid email address',
+]);
+```
+
+If you would like to assert that the given fields are the only fields with validation errors, you may use the `assertOnlyInvalid` method:
+
+```php
+$response->assertOnlyInvalid(['name', 'email']);
+```
#### assertViewHas
-Assert that the response view contains given a piece of data:
+Assert that the response view contains a given piece of data:
- $response->assertViewHas($key, $value = null);
+```php
+$response->assertViewHas($key, $value = null);
+```
Passing a closure as the second argument to the `assertViewHas` method will allow you to inspect and make assertions against a particular piece of view data:
- $response->assertViewHas('user', function (User $user) {
- return $user->name === 'Taylor';
- });
+```php
+$response->assertViewHas('user', function (User $user) {
+ return $user->name === 'Taylor';
+});
+```
In addition, view data may be accessed as array variables on the response, allowing you to conveniently inspect it:
- $this->assertEquals('Taylor', $response['name']);
+```php tab=Pest
+expect($response['name'])->toBe('Taylor');
+```
+
+```php tab=PHPUnit
+$this->assertEquals('Taylor', $response['name']);
+```
#### assertViewHasAll
Assert that the response view has a given list of data:
- $response->assertViewHasAll(array $data);
+```php
+$response->assertViewHasAll(array $data);
+```
This method may be used to assert that the view simply contains data matching the given keys:
- $response->assertViewHasAll([
- 'name',
- 'email',
- ]);
+```php
+$response->assertViewHasAll([
+ 'name',
+ 'email',
+]);
+```
Or, you may assert that the view data is present and has specific values:
- $response->assertViewHasAll([
- 'name' => 'Taylor Otwell',
- 'email' => 'taylor@example.com,',
- ]);
+```php
+$response->assertViewHasAll([
+ 'name' => 'Taylor Otwell',
+ 'email' => 'taylor@example.com,',
+]);
+```
#### assertViewIs
Assert that the given view was returned by the route:
- $response->assertViewIs($value);
+```php
+$response->assertViewIs($value);
+```
#### assertViewMissing
Assert that the given data key was not made available to the view returned in the application's response:
- $response->assertViewMissing($key);
+```php
+$response->assertViewMissing($key);
+```
### Authentication Assertions
@@ -1188,18 +1969,60 @@ Laravel also provides a variety of authentication related assertions that you ma
Assert that a user is authenticated:
- $this->assertAuthenticated($guard = null);
+```php
+$this->assertAuthenticated($guard = null);
+```
#### assertGuest
Assert that a user is not authenticated:
- $this->assertGuest($guard = null);
+```php
+$this->assertGuest($guard = null);
+```
#### assertAuthenticatedAs
Assert that a specific user is authenticated:
- $this->assertAuthenticatedAs($user, $guard = null);
+```php
+$this->assertAuthenticatedAs($user, $guard = null);
+```
+
+
+## Validation Assertions
+
+Laravel provides two primary validation related assertions that you may use to ensure the data provided in your request was either valid or invalid.
+
+
+#### assertValid
+
+Assert that the response has no validation errors for the given keys. This method may be used for asserting against responses where the validation errors are returned as a JSON structure or where the validation errors have been flashed to the session:
+
+```php
+// Assert that no validation errors are present...
+$response->assertValid();
+
+// Assert that the given keys do not have validation errors...
+$response->assertValid(['name', 'email']);
+```
+
+
+#### assertInvalid
+
+Assert that the response has validation errors for the given keys. This method may be used for asserting against responses where the validation errors are returned as a JSON structure or where the validation errors have been flashed to the session:
+
+```php
+$response->assertInvalid(['name', 'email']);
+```
+
+You may also assert that a given key has a particular validation error message. When doing so, you may provide the entire message or only a small portion of the message:
+
+```php
+$response->assertInvalid([
+ 'name' => 'The name field is required.',
+ 'email' => 'valid email address',
+]);
+```
diff --git a/installation.md b/installation.md
index d6b81486d42..603257864c1 100644
--- a/installation.md
+++ b/installation.md
@@ -2,18 +2,22 @@
- [Meet Laravel](#meet-laravel)
- [Why Laravel?](#why-laravel)
-- [Your First Laravel Project](#your-first-laravel-project)
- - [Getting Started On macOS](#getting-started-on-macos)
- - [Getting Started On Windows](#getting-started-on-windows)
- - [Getting Started On Linux](#getting-started-on-linux)
- - [Choosing Your Sail Services](#choosing-your-sail-services)
- - [Installation Via Composer](#installation-via-composer)
+- [Creating a Laravel Application](#creating-a-laravel-project)
+ - [Installing PHP and the Laravel Installer](#installing-php)
+ - [Creating an Application](#creating-an-application)
- [Initial Configuration](#initial-configuration)
- [Environment Based Configuration](#environment-based-configuration)
+ - [Databases and Migrations](#databases-and-migrations)
- [Directory Configuration](#directory-configuration)
+- [Installation Using Herd](#installation-using-herd)
+ - [Herd on macOS](#herd-on-macos)
+ - [Herd on Windows](#herd-on-windows)
+- [IDE Support](#ide-support)
+- [Laravel and AI](#laravel-and-ai)
+ - [Installing Laravel Boost](#installing-laravel-boost)
- [Next Steps](#next-steps)
- - [Laravel The Full Stack Framework](#laravel-the-fullstack-framework)
- - [Laravel The API Backend](#laravel-the-api-backend)
+ - [Laravel the Full Stack Framework](#laravel-the-fullstack-framework)
+ - [Laravel the API Backend](#laravel-the-api-backend)
## Meet Laravel
@@ -22,7 +26,7 @@ Laravel is a web application framework with expressive, elegant syntax. A web fr
Laravel strives to provide an amazing developer experience while providing powerful features such as thorough dependency injection, an expressive database abstraction layer, queues and scheduled jobs, unit and integration testing, and more.
-Whether you are new to PHP or web frameworks or have years of experience, Laravel is a framework that can grow with you. We'll help you take your first steps as a web developer or give you a boost as you take your expertise to the next level. We can't wait to see what you build.
+Whether you are new to PHP web frameworks or have years of experience, Laravel is a framework that can grow with you. We'll help you take your first steps as a web developer or give you a boost as you take your expertise to the next level. We can't wait to see what you build.
### Why Laravel?
@@ -39,224 +43,218 @@ If you're a senior developer, Laravel gives you robust tools for [dependency inj
Laravel is incredibly scalable. Thanks to the scaling-friendly nature of PHP and Laravel's built-in support for fast, distributed cache systems like Redis, horizontal scaling with Laravel is a breeze. In fact, Laravel applications have been easily scaled to handle hundreds of millions of requests per month.
-Need extreme scaling? Platforms like [Laravel Vapor](https://vapor.laravel.com) allow you to run your Laravel application at nearly limitless scale on AWS's latest serverless technology.
+Need extreme scaling? Platforms like [Laravel Cloud](https://cloud.laravel.com) allow you to run your Laravel application at nearly limitless scale.
#### A Community Framework
Laravel combines the best packages in the PHP ecosystem to offer the most robust and developer friendly framework available. In addition, thousands of talented developers from around the world have [contributed to the framework](https://github.com/laravel/framework). Who knows, maybe you'll even become a Laravel contributor.
-
-## Your First Laravel Project
+
+## Creating a Laravel Application
-We want it to be as easy as possible to get started with Laravel. There are a variety of options for developing and running a Laravel project on your own computer. While you may wish to explore these options at a later time, Laravel provides [Sail](/docs/{{version}}/sail), a built-in solution for running your Laravel project using [Docker](https://www.docker.com).
+
+### Installing PHP and the Laravel Installer
-Docker is a tool for running applications and services in small, light-weight "containers" which do not interfere with your local computer's installed software or configuration. This means you don't have to worry about configuring or setting up complicated development tools such as web servers and databases on your personal computer. To get started, you only need to install [Docker Desktop](https://www.docker.com/products/docker-desktop).
+Before creating your first Laravel application, make sure that your local machine has [PHP](https://php.net), [Composer](https://getcomposer.org), and [the Laravel installer](https://github.com/laravel/installer) installed. In addition, you should install either [Node and NPM](https://nodejs.org) or [Bun](https://bun.sh/) so that you can compile your application's frontend assets.
-Laravel Sail is a light-weight command-line interface for interacting with Laravel's default Docker configuration. Sail provides a great starting point for building a Laravel application using PHP, MySQL, and Redis without requiring prior Docker experience.
+If you don't have PHP and Composer installed on your local machine, the following commands will install PHP, Composer, and the Laravel installer on macOS, Windows, or Linux:
-> {tip} Already a Docker expert? Don't worry! Everything about Sail can be customized using the `docker-compose.yml` file included with Laravel.
-
-
-### Getting Started On macOS
+```shell tab=macOS
+/bin/bash -c "$(curl -fsSL https://php.new/install/mac/8.4)"
+```
-If you're developing on a Mac and [Docker Desktop](https://www.docker.com/products/docker-desktop) is already installed, you can use a simple terminal command to create a new Laravel project. For example, to create a new Laravel application in a directory named "example-app", you may run the following command in your terminal:
+```shell tab=Windows PowerShell
+# Run as administrator...
+Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://php.new/install/windows/8.4'))
+```
-```shell
-curl -s "https://laravel.build/example-app" | bash
+```shell tab=Linux
+/bin/bash -c "$(curl -fsSL https://php.new/install/linux/8.4)"
```
-Of course, you can change "example-app" in this URL to anything you like. The Laravel application's directory will be created within the directory you execute the command from.
+After running one of the commands above, you should restart your terminal session. To update PHP, Composer, and the Laravel installer after installing them via `php.new`, you can re-run the command in your terminal.
-After the project has been created, you can navigate to the application directory and start Laravel Sail. Laravel Sail provides a simple command-line interface for interacting with Laravel's default Docker configuration:
+If you already have PHP and Composer installed, you may install the Laravel installer via Composer:
```shell
-cd example-app
-
-./vendor/bin/sail up
+composer global require laravel/installer
```
-The first time you run the Sail `up` command, Sail's application containers will be built on your machine. This could take several minutes. **Don't worry, subsequent attempts to start Sail will be much faster.**
-
-Once the application's Docker containers have been started, you can access the application in your web browser at: http://localhost.
-
-> {tip} To continue learning more about Laravel Sail, review its [complete documentation](/docs/{{version}}/sail).
+> [!NOTE]
+> For a fully-featured, graphical PHP installation and management experience, check out [Laravel Herd](#installation-using-herd).
-
-### Getting Started On Windows
+
+### Creating an Application
-Before we create a new Laravel application on your Windows machine, make sure to install [Docker Desktop](https://www.docker.com/products/docker-desktop). Next, you should ensure that Windows Subsystem for Linux 2 (WSL2) is installed and enabled. WSL allows you to run Linux binary executables natively on Windows 10. Information on how to install and enable WSL2 can be found within Microsoft's [developer environment documentation](https://docs.microsoft.com/en-us/windows/wsl/install-win10).
-
-> {tip} After installing and enabling WSL2, you should ensure that Docker Desktop is [configured to use the WSL2 backend](https://docs.docker.com/docker-for-windows/wsl/).
-
-Next, you are ready to create your first Laravel project. Launch [Windows Terminal](https://www.microsoft.com/en-us/p/windows-terminal/9n0dx20hk701?rtc=1&activetab=pivot:overviewtab) and begin a new terminal session for your WSL2 Linux operating system. Next, you can use a simple terminal command to create a new Laravel project. For example, to create a new Laravel application in a directory named "example-app", you may run the following command in your terminal:
+After you have installed PHP, Composer, and the Laravel installer, you're ready to create a new Laravel application. The Laravel installer will prompt you to select your preferred testing framework, database, and starter kit:
```shell
-curl -s https://laravel.build/example-app | bash
+laravel new example-app
```
-Of course, you can change "example-app" in this URL to anything you like. The Laravel application's directory will be created within the directory you execute the command from.
-
-After the project has been created, you can navigate to the application directory and start Laravel Sail. Laravel Sail provides a simple command-line interface for interacting with Laravel's default Docker configuration:
+Once the application has been created, you can start Laravel's local development server, queue worker, and Vite development server using the `dev` Composer script:
```shell
cd example-app
-
-./vendor/bin/sail up
+npm install && npm run build
+composer run dev
```
-The first time you run the Sail `up` command, Sail's application containers will be built on your machine. This could take several minutes. **Don't worry, subsequent attempts to start Sail will be much faster.**
-
-Once the application's Docker containers have been started, you can access the application in your web browser at: http://localhost.
-
-> {tip} To continue learning more about Laravel Sail, review its [complete documentation](/docs/{{version}}/sail).
-
-#### Developing Within WSL2
+Once you have started the development server, your application will be accessible in your web browser at [http://localhost:8000](http://localhost:8000). Next, you're ready to [start taking your next steps into the Laravel ecosystem](#next-steps). Of course, you may also want to [configure a database](#databases-and-migrations).
-Of course, you will need to be able to modify the Laravel application files that were created within your WSL2 installation. To accomplish this, we recommend using Microsoft's [Visual Studio Code](https://code.visualstudio.com) editor and their first-party extension for [Remote Development](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack).
+> [!NOTE]
+> If you would like a head start when developing your Laravel application, consider using one of our [starter kits](/docs/{{version}}/starter-kits). Laravel's starter kits provide backend and frontend authentication scaffolding for your new Laravel application.
-Once these tools are installed, you may open any Laravel project by executing the `code .` command from your application's root directory using Windows Terminal.
+
+## Initial Configuration
-
-### Getting Started On Linux
+All of the configuration files for the Laravel framework are stored in the `config` directory. Each option is documented, so feel free to look through the files and get familiar with the options available to you.
-If you're developing on Linux and [Docker Compose](https://docs.docker.com/compose/install/) is already installed, you can use a simple terminal command to create a new Laravel project. For example, to create a new Laravel application in a directory named "example-app", you may run the following command in your terminal:
+Laravel needs almost no additional configuration out of the box. You are free to get started developing! However, you may wish to review the `config/app.php` file and its documentation. It contains several options such as `url` and `locale` that you may wish to change according to your application.
-```shell
-curl -s https://laravel.build/example-app | bash
-```
+
+### Environment Based Configuration
-Of course, you can change "example-app" in this URL to anything you like. The Laravel application's directory will be created within the directory you execute the command from.
+Since many of Laravel's configuration option values may vary depending on whether your application is running on your local machine or on a production web server, many important configuration values are defined using the `.env` file that exists at the root of your application.
-After the project has been created, you can navigate to the application directory and start Laravel Sail. Laravel Sail provides a simple command-line interface for interacting with Laravel's default Docker configuration:
+Your `.env` file should not be committed to your application's source control, since each developer / server using your application could require a different environment configuration. Furthermore, this would be a security risk in the event an intruder gains access to your source control repository, since any sensitive credentials would be exposed.
-```shell
-cd example-app
+> [!NOTE]
+> For more information about the `.env` file and environment based configuration, check out the full [configuration documentation](/docs/{{version}}/configuration#environment-configuration).
-./vendor/bin/sail up
-```
+
+### Databases and Migrations
-The first time you run the Sail `up` command, Sail's application containers will be built on your machine. This could take several minutes. **Don't worry, subsequent attempts to start Sail will be much faster.**
+Now that you have created your Laravel application, you probably want to store some data in a database. By default, your application's `.env` configuration file specifies that Laravel will be interacting with an SQLite database.
-Once the application's Docker containers have been started, you can access the application in your web browser at: http://localhost.
+During the creation of the application, Laravel created a `database/database.sqlite` file for you, and ran the necessary migrations to create the application's database tables.
-> {tip} To continue learning more about Laravel Sail, review its [complete documentation](/docs/{{version}}/sail).
+If you prefer to use another database driver such as MySQL or PostgreSQL, you can update your `.env` configuration file to use the appropriate database. For example, if you wish to use MySQL, update your `.env` configuration file's `DB_*` variables like so:
-
-### Choosing Your Sail Services
+```ini
+DB_CONNECTION=mysql
+DB_HOST=127.0.0.1
+DB_PORT=3306
+DB_DATABASE=laravel
+DB_USERNAME=root
+DB_PASSWORD=
+```
-When creating a new Laravel application via Sail, you may use the `with` query string variable to choose which services should be configured in your new application's `docker-compose.yml` file. Available services include `mysql`, `pgsql`, `mariadb`, `redis`, `memcached`, `meilisearch`, `minio`, `selenium`, and `mailhog`:
+If you choose to use a database other than SQLite, you will need to create the database and run your application's [database migrations](/docs/{{version}}/migrations):
```shell
-curl -s "https://laravel.build/example-app?with=mysql,redis" | bash
+php artisan migrate
```
-If you do not specify which services you would like configured, a default stack of `mysql`, `redis`, `meilisearch`, `mailhog`, and `selenium` will be configured.
+> [!NOTE]
+> If you are developing on macOS or Windows and need to install MySQL, PostgreSQL, or Redis locally, consider using [Herd Pro](https://herd.laravel.com/#plans) or [DBngin](https://dbngin.com/).
-You may instruct Sail to install a default [Devcontainer](/docs/{{version}}/sail#using-devcontainers) by adding the `devcontainer` parameter to the URL:
+
+### Directory Configuration
-```shell
-curl -s "https://laravel.build/example-app?with=mysql,redis&devcontainer" | bash
-```
+Laravel should always be served out of the root of the "web directory" configured for your web server. You should not attempt to serve a Laravel application out of a subdirectory of the "web directory". Attempting to do so could expose sensitive files present within your application.
-
-### Installation Via Composer
+
+## Installation Using Herd
-If your computer already has PHP and Composer installed, you may create a new Laravel project by using Composer directly. After the application has been created, you may start Laravel's local development server using the Artisan CLI's `serve` command:
+[Laravel Herd](https://herd.laravel.com) is a blazing fast, native Laravel and PHP development environment for macOS and Windows. Herd includes everything you need to get started with Laravel development, including PHP and Nginx.
-```shell
-composer create-project laravel/laravel example-app
+Once you install Herd, you're ready to start developing with Laravel. Herd includes command line tools for `php`, `composer`, `laravel`, `expose`, `node`, `npm`, and `nvm`.
-cd example-app
+> [!NOTE]
+> [Herd Pro](https://herd.laravel.com/#plans) augments Herd with additional powerful features, such as the ability to create and manage local MySQL, Postgres, and Redis databases, as well as local mail viewing and log monitoring.
-php artisan serve
-```
+
+### Herd on macOS
-
-#### The Laravel Installer
+If you develop on macOS, you can download the Herd installer from the [Herd website](https://herd.laravel.com). The installer automatically downloads the latest version of PHP and configures your Mac to always run [Nginx](https://www.nginx.com/) in the background.
-Or, you may install the Laravel Installer as a global Composer dependency:
+Herd for macOS uses [dnsmasq](https://en.wikipedia.org/wiki/Dnsmasq) to support "parked" directories. Any Laravel application in a parked directory will automatically be served by Herd. By default, Herd creates a parked directory at `~/Herd` and you can access any Laravel application in this directory on the `.test` domain using its directory name.
-```shell
-composer global require laravel/installer
+After installing Herd, the fastest way to create a new Laravel application is using the Laravel CLI, which is bundled with Herd:
-laravel new example-app
+```shell
+cd ~/Herd
+laravel new my-app
+cd my-app
+herd open
+```
-cd example-app
+Of course, you can always manage your parked directories and other PHP settings via Herd's UI, which can be opened from the Herd menu in your system tray.
-php artisan serve
-```
+You can learn more about Herd by checking out the [Herd documentation](https://herd.laravel.com/docs).
-Make sure to place Composer's system-wide vendor bin directory in your `$PATH` so the `laravel` executable can be located by your system. This directory exists in different locations based on your operating system; however, some common locations include:
+
+### Herd on Windows
-
+You can download the Windows installer for Herd on the [Herd website](https://herd.laravel.com/windows). After the installation finishes, you can start Herd to complete the onboarding process and access the Herd UI for the first time.
-- macOS: `$HOME/.composer/vendor/bin`
-- Windows: `%USERPROFILE%\AppData\Roaming\Composer\vendor\bin`
-- GNU / Linux Distributions: `$HOME/.config/composer/vendor/bin` or `$HOME/.composer/vendor/bin`
+The Herd UI is accessible by left-clicking on Herd's system tray icon. A right-click opens the quick menu with access to all tools that you need on a daily basis.
-
+During installation, Herd creates a "parked" directory in your home directory at `%USERPROFILE%\Herd`. Any Laravel application in a parked directory will automatically be served by Herd, and you can access any Laravel application in this directory on the `.test` domain using its directory name.
-For convenience, the Laravel installer can also create a Git repository for your new project. To indicate that you want a Git repository to be created, pass the `--git` flag when creating a new project:
+After installing Herd, the fastest way to create a new Laravel application is using the Laravel CLI, which is bundled with Herd. To get started, open Powershell and run the following commands:
```shell
-laravel new example-app --git
+cd ~\Herd
+laravel new my-app
+cd my-app
+herd open
```
-This command will initialize a new Git repository for your project and automatically commit the base Laravel skeleton. The `git` flag assumes you have properly installed and configured Git. You can also use the `--branch` flag to set the initial branch name:
+You can learn more about Herd by checking out the [Herd documentation for Windows](https://herd.laravel.com/docs/windows).
-```shell
-laravel new example-app --git --branch="main"
-```
+
+## IDE Support
-Instead of using the `--git` flag, you may also use the `--github` flag to create a Git repository and also create a corresponding private repository on GitHub:
+You are free to use any code editor you wish when developing Laravel applications. If you're looking for lightweight and extensible editors, [VS Code](https://code.visualstudio.com) or [Cursor](https://cursor.com) combined with the official [Laravel VS Code Extension](https://marketplace.visualstudio.com/items?itemName=laravel.vscode-laravel) offers excellent Laravel support with features like syntax highlighting, snippets, artisan command integration, and smart autocompletion for Eloquent models, routes, middleware, assets, config, and Inertia.js.
-```shell
-laravel new example-app --github
-```
+For extensive and robust support of Laravel, take a look at [PhpStorm](https://www.jetbrains.com/phpstorm/laravel/?utm_source=laravel.com&utm_medium=link&utm_campaign=laravel-2025&utm_content=partner&ref=laravel-2025), a JetBrains IDE. With the [Laravel Idea plugin](https://laravel-idea.com/), it provides accurate support for Laravel and its ecosystem, including Laravel Pint, Pest, Larastan, and more. Laravel Idea's framework support includes Blade templates, smart autocompletion for Eloquent models, routes, views, translations, and components, along with powerful code generation and navigation across Laravel projects.
-The created repository will then be available at `https://github.com/
- [Request Lifecycle](/docs/{{version}}/lifecycle)
- [Configuration](/docs/{{version}}/configuration)
- [Directory Structure](/docs/{{version}}/structure)
+- [Frontend](/docs/{{version}}/frontend)
- [Service Container](/docs/{{version}}/container)
- [Facades](/docs/{{version}}/facades)
@@ -265,22 +263,20 @@ Now that you have created your Laravel project, you may be wondering what to lea
How you want to use Laravel will also dictate the next steps on your journey. There are a variety of ways to use Laravel, and we'll explore two primary use cases for the framework below.
-### Laravel The Full Stack Framework
+### Laravel the Full Stack Framework
-Laravel may serve as a full stack framework. By "full stack" framework we mean that you are going to use Laravel to route requests to your application and render your frontend via [Blade templates](/docs/{{version}}/blade) or using a single-page application hybrid technology like [Inertia.js](https://inertiajs.com). This is the most common way to use the Laravel framework.
+Laravel may serve as a full stack framework. By "full stack" framework we mean that you are going to use Laravel to route requests to your application and render your frontend via [Blade templates](/docs/{{version}}/blade) or a single-page application hybrid technology like [Inertia](https://inertiajs.com). This is the most common way to use the Laravel framework, and, in our opinion, the most productive way to use Laravel.
-If this is how you plan to use Laravel, you may want to check out our documentation on [routing](/docs/{{version}}/routing), [views](/docs/{{version}}/views), or the [Eloquent ORM](/docs/{{version}}/eloquent). In addition, you might be interested in learning about community packages like [Livewire](https://laravel-livewire.com) and [Inertia.js](https://inertiajs.com). These packages allow you to use Laravel as a full-stack framework while enjoying many of the UI benefits provided by single-page JavaScript applications.
+If this is how you plan to use Laravel, you may want to check out our documentation on [frontend development](/docs/{{version}}/frontend), [routing](/docs/{{version}}/routing), [views](/docs/{{version}}/views), or the [Eloquent ORM](/docs/{{version}}/eloquent). In addition, you might be interested in learning about community packages like [Livewire](https://livewire.laravel.com) and [Inertia](https://inertiajs.com). These packages allow you to use Laravel as a full-stack framework while enjoying many of the UI benefits provided by single-page JavaScript applications.
-If you are using Laravel as a full stack framework, we also strongly encourage you to learn how to compile your application's CSS and JavaScript using [Laravel Mix](/docs/{{version}}/mix).
+If you are using Laravel as a full stack framework, we also strongly encourage you to learn how to compile your application's CSS and JavaScript using [Vite](/docs/{{version}}/vite).
-> {tip} If you want to get a head start building your application, check out one of our official [application starter kits](/docs/{{version}}/starter-kits).
+> [!NOTE]
+> If you want to get a head start building your application, check out one of our official [application starter kits](/docs/{{version}}/starter-kits).
-### Laravel The API Backend
+### Laravel the API Backend
Laravel may also serve as an API backend to a JavaScript single-page application or mobile application. For example, you might use Laravel as an API backend for your [Next.js](https://nextjs.org) application. In this context, you may use Laravel to provide [authentication](/docs/{{version}}/sanctum) and data storage / retrieval for your application, while also taking advantage of Laravel's powerful services such as queues, emails, notifications, and more.
If this is how you plan to use Laravel, you may want to check out our documentation on [routing](/docs/{{version}}/routing), [Laravel Sanctum](/docs/{{version}}/sanctum), and the [Eloquent ORM](/docs/{{version}}/eloquent).
-
-> {tip} Need a head start scaffolding your Laravel backend and Next.js frontend? Laravel Breeze offers an [API stack](/docs/{{version}}/starter-kits#breeze-and-next) as well as a [Next.js frontend implementation](https://github.com/laravel/breeze-next) so you can get started in minutes.
-
diff --git a/lifecycle.md b/lifecycle.md
index 356e9d2f411..98c78f1dda3 100644
--- a/lifecycle.md
+++ b/lifecycle.md
@@ -7,7 +7,7 @@
- [Service Providers](#service-providers)
- [Routing](#routing)
- [Finishing Up](#finishing-up)
-- [Focus On Service Providers](#focus-on-service-providers)
+- [Focus on Service Providers](#focus-on-service-providers)
## Introduction
@@ -29,31 +29,31 @@ The `index.php` file loads the Composer generated autoloader definition, and the
### HTTP / Console Kernels
-Next, the incoming request is sent to either the HTTP kernel or the console kernel, depending on the type of request that is entering the application. These two kernels serve as the central location that all requests flow through. For now, let's just focus on the HTTP kernel, which is located in `app/Http/Kernel.php`.
+Next, the incoming request is sent to either the HTTP kernel or the console kernel, using the `handleRequest` or `handleCommand` methods of the application instance, depending on the type of request entering the application. These two kernels serve as the central location through which all requests flow. For now, let's just focus on the HTTP kernel, which is an instance of `Illuminate\Foundation\Http\Kernel`.
-The HTTP kernel extends the `Illuminate\Foundation\Http\Kernel` class, which defines an array of `bootstrappers` that will be run before the request is executed. These bootstrappers configure error handling, configure logging, [detect the application environment](/docs/{{version}}/configuration#environment-configuration), and perform other tasks that need to be done before the request is actually handled. Typically, these classes handle internal Laravel configuration that you do not need to worry about.
+The HTTP kernel defines an array of `bootstrappers` that will be run before the request is executed. These bootstrappers configure error handling, configure logging, [detect the application environment](/docs/{{version}}/configuration#environment-configuration), and perform other tasks that need to be done before the request is actually handled. Typically, these classes handle internal Laravel configuration that you do not need to worry about.
-The HTTP kernel also defines a list of HTTP [middleware](/docs/{{version}}/middleware) that all requests must pass through before being handled by the application. These middleware handle reading and writing the [HTTP session](/docs/{{version}}/session), determining if the application is in maintenance mode, [verifying the CSRF token](/docs/{{version}}/csrf), and more. We'll talk more about these soon.
+The HTTP kernel is also responsible for passing the request through the application's middleware stack. These middleware handle reading and writing the [HTTP session](/docs/{{version}}/session), determining if the application is in maintenance mode, [verifying the CSRF token](/docs/{{version}}/csrf), and more. We'll talk more about these soon.
The method signature for the HTTP kernel's `handle` method is quite simple: it receives a `Request` and returns a `Response`. Think of the kernel as being a big black box that represents your entire application. Feed it HTTP requests and it will return HTTP responses.
### Service Providers
-One of the most important kernel bootstrapping actions is loading the [service providers](/docs/{{version}}/providers) for your application. All of the service providers for the application are configured in the `config/app.php` configuration file's `providers` array.
+One of the most important kernel bootstrapping actions is loading the [service providers](/docs/{{version}}/providers) for your application. Service providers are responsible for bootstrapping all of the framework's various components, such as the database, queue, validation, and routing components.
Laravel will iterate through this list of providers and instantiate each of them. After instantiating the providers, the `register` method will be called on all of the providers. Then, once all of the providers have been registered, the `boot` method will be called on each provider. This is so service providers may depend on every container binding being registered and available by the time their `boot` method is executed.
-Service providers are responsible for bootstrapping all of the framework's various components, such as the database, queue, validation, and routing components. Essentially every major feature offered by Laravel is bootstrapped and configured by a service provider. Since they bootstrap and configure so many features offered by the framework, service providers are the most important aspect of the entire Laravel bootstrap process.
+Essentially every major feature offered by Laravel is bootstrapped and configured by a service provider. Since they bootstrap and configure so many features offered by the framework, service providers are the most important aspect of the entire Laravel bootstrap process.
+
+While the framework internally uses dozens of service providers, you also have the option to create your own. You can find a list of the user-defined or third-party service providers that your application is using in the `bootstrap/providers.php` file.
### Routing
-One of the most important service providers in your application is the `App\Providers\RouteServiceProvider`. This service provider loads the route files contained within your application's `routes` directory. Go ahead, crack open the `RouteServiceProvider` code and take a look at how it works!
-
Once the application has been bootstrapped and all service providers have been registered, the `Request` will be handed off to the router for dispatching. The router will dispatch the request to a route or controller, as well as run any route specific middleware.
-Middleware provide a convenient mechanism for filtering or examining HTTP requests entering your application. For example, Laravel includes a middleware that verifies if the user of your application is authenticated. If the user is not authenticated, the middleware will redirect the user to the login screen. However, if the user is authenticated, the middleware will allow the request to proceed further into the application. Some middleware are assigned to all routes within the application, like those defined in the `$middleware` property of your HTTP kernel, while some are only assigned to specific routes or route groups. You can learn more about middleware by reading the complete [middleware documentation](/docs/{{version}}/middleware).
+Middleware provide a convenient mechanism for filtering or examining HTTP requests entering your application. For example, Laravel includes a middleware that verifies if the user of your application is authenticated. If the user is not authenticated, the middleware will redirect the user to the login screen. However, if the user is authenticated, the middleware will allow the request to proceed further into the application. Some middleware are assigned to all routes within the application, like `PreventRequestsDuringMaintenance`, while some are only assigned to specific routes or route groups. You can learn more about middleware by reading the complete [middleware documentation](/docs/{{version}}/middleware).
If the request passes through all of the matched route's assigned middleware, the route or controller method will be executed and the response returned by the route or controller method will be sent back through the route's chain of middleware.
@@ -62,13 +62,13 @@ If the request passes through all of the matched route's assigned middleware, th
Once the route or controller method returns a response, the response will travel back outward through the route's middleware, giving the application a chance to modify or examine the outgoing response.
-Finally, once the response travels back through the middleware, the HTTP kernel's `handle` method returns the response object and the `index.php` file calls the `send` method on the returned response. The `send` method sends the response content to the user's web browser. We've finished our journey through the entire Laravel request lifecycle!
+Finally, once the response travels back through the middleware, the HTTP kernel's `handle` method returns the response object to the `handleRequest` of the application instance, and this method calls the `send` method on the returned response. The `send` method sends the response content to the user's web browser. We've now completed our journey through the entire Laravel request lifecycle!
-## Focus On Service Providers
+## Focus on Service Providers
Service providers are truly the key to bootstrapping a Laravel application. The application instance is created, the service providers are registered, and the request is handed to the bootstrapped application. It's really that simple!
-Having a firm grasp of how a Laravel application is built and bootstrapped via service providers is very valuable. Your application's default service providers are stored in the `app/Providers` directory.
+Having a firm grasp of how a Laravel application is built and bootstrapped via service providers is very valuable. Your application's user-defined service providers are stored in the `app/Providers` directory.
By default, the `AppServiceProvider` is fairly empty. This provider is a great place to add your application's own bootstrapping and service container bindings. For large applications, you may wish to create several service providers, each with more granular bootstrapping for specific services used by your application.
diff --git a/localization.md b/localization.md
index faf658f3681..e7649199486 100644
--- a/localization.md
+++ b/localization.md
@@ -1,71 +1,123 @@
# Localization
- [Introduction](#introduction)
- - [Configuring The Locale](#configuring-the-locale)
+ - [Publishing the Language Files](#publishing-the-language-files)
+ - [Configuring the Locale](#configuring-the-locale)
+ - [Pluralization Language](#pluralization-language)
- [Defining Translation Strings](#defining-translation-strings)
- [Using Short Keys](#using-short-keys)
- - [Using Translation Strings As Keys](#using-translation-strings-as-keys)
+ - [Using Translation Strings as Keys](#using-translation-strings-as-keys)
- [Retrieving Translation Strings](#retrieving-translation-strings)
- - [Replacing Parameters In Translation Strings](#replacing-parameters-in-translation-strings)
+ - [Replacing Parameters in Translation Strings](#replacing-parameters-in-translation-strings)
- [Pluralization](#pluralization)
- [Overriding Package Language Files](#overriding-package-language-files)
## Introduction
+> [!NOTE]
+> By default, the Laravel application skeleton does not include the `lang` directory. If you would like to customize Laravel's language files, you may publish them via the `lang:publish` Artisan command.
+
Laravel's localization features provide a convenient way to retrieve strings in various languages, allowing you to easily support multiple languages within your application.
-Laravel provides two ways to manage translation strings. First, language strings may be stored in files within the `lang` directory. Within this directory, there may be subdirectories for each language supported by the application. This is the approach Laravel uses to manage translation strings for built-in Laravel features such as validation error messages:
+Laravel provides two ways to manage translation strings. First, language strings may be stored in files within the application's `lang` directory. Within this directory, there may be subdirectories for each language supported by the application. This is the approach Laravel uses to manage translation strings for built-in Laravel features such as validation error messages:
- /lang
- /en
- messages.php
- /es
- messages.php
+```text
+/lang
+ /en
+ messages.php
+ /es
+ messages.php
+```
-Or, translation strings may be defined within JSON files that are placed within the `lang` directory. When taking this approach, each language supported by your application would have a corresponding JSON file within this directory. This approach is recommended for application's that have a large number of translatable strings:
+Or, translation strings may be defined within JSON files that are placed within the `lang` directory. When taking this approach, each language supported by your application would have a corresponding JSON file within this directory. This approach is recommended for applications that have a large number of translatable strings:
- /lang
- en.json
- es.json
+```text
+/lang
+ en.json
+ es.json
+```
We'll discuss each approach to managing translation strings within this documentation.
-
-### Configuring The Locale
+
+### Publishing the Language Files
-The default language for your application is stored in the `config/app.php` configuration file's `locale` configuration option. You are free to modify this value to suit the needs of your application.
+By default, the Laravel application skeleton does not include the `lang` directory. If you would like to customize Laravel's language files or create your own, you should scaffold the `lang` directory via the `lang:publish` Artisan command. The `lang:publish` command will create the `lang` directory in your application and publish the default set of language files used by Laravel:
-You may modify the default language for a single HTTP request at runtime using the `setLocale` method provided by the `App` facade:
+```shell
+php artisan lang:publish
+```
- use Illuminate\Support\Facades\App;
+
+### Configuring the Locale
- Route::get('/greeting/{locale}', function ($locale) {
- if (! in_array($locale, ['en', 'es', 'fr'])) {
- abort(400);
- }
+The default language for your application is stored in the `config/app.php` configuration file's `locale` configuration option, which is typically set using the `APP_LOCALE` environment variable. You are free to modify this value to suit the needs of your application.
- App::setLocale($locale);
+You may also configure a "fallback language", which will be used when the default language does not contain a given translation string. Like the default language, the fallback language is also configured in the `config/app.php` configuration file, and its value is typically set using the `APP_FALLBACK_LOCALE` environment variable.
- //
- });
+You may modify the default language for a single HTTP request at runtime using the `setLocale` method provided by the `App` facade:
+
+```php
+use Illuminate\Support\Facades\App;
-You may configure a "fallback language", which will be used when the active language does not contain a given translation string. Like the default language, the fallback language is also configured in the `config/app.php` configuration file:
+Route::get('/greeting/{locale}', function (string $locale) {
+ if (! in_array($locale, ['en', 'es', 'fr'])) {
+ abort(400);
+ }
+
+ App::setLocale($locale);
- 'fallback_locale' => 'en',
+ // ...
+});
+```
-#### Determining The Current Locale
+#### Determining the Current Locale
You may use the `currentLocale` and `isLocale` methods on the `App` facade to determine the current locale or check if the locale is a given value:
- use Illuminate\Support\Facades\App;
+```php
+use Illuminate\Support\Facades\App;
- $locale = App::currentLocale();
+$locale = App::currentLocale();
- if (App::isLocale('en')) {
- //
- }
+if (App::isLocale('en')) {
+ // ...
+}
+```
+
+
+### Pluralization Language
+
+
+
+
+
+
+### Installation
+
+> [!WARNING]
+> Laravel Pail requires the [PCNTL](https://www.php.net/manual/en/book.pcntl.php) PHP extension.
+
+To get started, install Pail into your project using the Composer package manager:
+
+```shell
+composer require --dev laravel/pail
+```
+
+
+### Usage
+
+To start tailing logs, run the `pail` command:
+
+```shell
+php artisan pail
+```
+
+To increase the verbosity of the output and avoid truncation (…), use the `-v` option:
+
+```shell
+php artisan pail -v
+```
+
+For maximum verbosity and to display exception stack traces, use the `-vv` option:
+
+```shell
+php artisan pail -vv
+```
+
+To stop tailing logs, press `Ctrl+C` at any time.
+
+
+### Filtering Logs
+
+
+#### `--filter`
+
+You may use the `--filter` option to filter logs by their type, file, message, and stack trace content:
+
+```shell
+php artisan pail --filter="QueryException"
+```
+
+
+#### `--message`
+
+To filter logs by only their message, you may use the `--message` option:
+
+```shell
+php artisan pail --message="User created"
+```
+
+
+#### `--level`
+
+The `--level` option may be used to filter logs by their [log level](#log-levels):
+
+```shell
+php artisan pail --level=error
+```
+
+
+#### `--user`
+
+To only display logs that were written while a given user was authenticated, you may provide the user's ID to the `--user` option:
+
+```shell
+php artisan pail --user=1
+```
diff --git a/mail.md b/mail.md
index 9ced46384c8..fd32113157c 100644
--- a/mail.md
+++ b/mail.md
@@ -4,25 +4,31 @@
- [Configuration](#configuration)
- [Driver Prerequisites](#driver-prerequisites)
- [Failover Configuration](#failover-configuration)
+ - [Round Robin Configuration](#round-robin-configuration)
- [Generating Mailables](#generating-mailables)
- [Writing Mailables](#writing-mailables)
- - [Configuring The Sender](#configuring-the-sender)
- - [Configuring The View](#configuring-the-view)
+ - [Configuring the Sender](#configuring-the-sender)
+ - [Configuring the View](#configuring-the-view)
- [View Data](#view-data)
- [Attachments](#attachments)
- [Inline Attachments](#inline-attachments)
- - [Customizing The Symfony Message](#customizing-the-symfony-message)
+ - [Attachable Objects](#attachable-objects)
+ - [Headers](#headers)
+ - [Tags and Metadata](#tags-and-metadata)
+ - [Customizing the Symfony Message](#customizing-the-symfony-message)
- [Markdown Mailables](#markdown-mailables)
- [Generating Markdown Mailables](#generating-markdown-mailables)
- [Writing Markdown Messages](#writing-markdown-messages)
- - [Customizing The Components](#customizing-the-components)
+ - [Customizing the Components](#customizing-the-components)
- [Sending Mail](#sending-mail)
- [Queueing Mail](#queueing-mail)
- [Rendering Mailables](#rendering-mailables)
- - [Previewing Mailables In The Browser](#previewing-mailables-in-the-browser)
+ - [Previewing Mailables in the Browser](#previewing-mailables-in-the-browser)
- [Localizing Mailables](#localizing-mailables)
-- [Testing Mailables](#testing-mailables)
-- [Mail & Local Development](#mail-and-local-development)
+- [Testing](#testing-mailables)
+ - [Testing Mailable Content](#testing-mailable-content)
+ - [Testing Mailable Sending](#testing-mailable-sending)
+- [Mail and Local Development](#mail-and-local-development)
- [Events](#events)
- [Custom Transports](#custom-transports)
- [Additional Symfony Transports](#additional-symfony-transports)
@@ -30,7 +36,7 @@
## Introduction
-Sending email doesn't have to be complicated. Laravel provides a clean, simple email API powered by the popular [Symfony Mailer](https://symfony.com/doc/6.0/mailer.html) component. Laravel and Symfony Mailer provide drivers for sending email via SMTP, Mailgun, Postmark, Amazon SES, and `sendmail`, allowing you to quickly get started sending mail through a local or cloud based service of your choice.
+Sending email doesn't have to be complicated. Laravel provides a clean, simple email API powered by the popular [Symfony Mailer](https://symfony.com/doc/current/mailer.html) component. Laravel and Symfony Mailer provide drivers for sending email via SMTP, Mailgun, Postmark, Resend, Amazon SES, and `sendmail`, allowing you to quickly get started sending mail through a local or cloud-based service of your choice.
### Configuration
@@ -42,7 +48,7 @@ Within your `mail` configuration file, you will find a `mailers` configuration a
### Driver / Transport Prerequisites
-The API based drivers such as Mailgun and Postmark are often simpler and faster than sending mail via SMTP servers. Whenever possible, we recommend that you use one of these drivers.
+The API based drivers such as Mailgun, Postmark, and Resend are often simpler and faster than sending mail via SMTP servers. Whenever possible, we recommend that you use one of these drivers.
#### Mailgun Driver
@@ -53,45 +59,93 @@ To use the Mailgun driver, install Symfony's Mailgun Mailer transport via Compos
composer require symfony/mailgun-mailer symfony/http-client
```
-Next, set the `default` option in your application's `config/mail.php` configuration file to `mailgun`. After configuring your application's default mailer, verify that your `config/services.php` configuration file contains the following options:
+Next, you will need to make two changes in your application's `config/mail.php` configuration file. First, set your default mailer to `mailgun`:
- 'mailgun' => [
- 'domain' => env('MAILGUN_DOMAIN'),
- 'secret' => env('MAILGUN_SECRET'),
- ],
+```php
+'default' => env('MAIL_MAILER', 'mailgun'),
+```
-If you are not using the United States [Mailgun region](https://documentation.mailgun.com/en/latest/api-intro.html#mailgun-regions), you may define your region's endpoint in the `services` configuration file:
+Second, add the following configuration array to your array of `mailers`:
- 'mailgun' => [
- 'domain' => env('MAILGUN_DOMAIN'),
- 'secret' => env('MAILGUN_SECRET'),
- 'endpoint' => env('MAILGUN_ENDPOINT', 'api.eu.mailgun.net'),
- ],
+```php
+'mailgun' => [
+ 'transport' => 'mailgun',
+ // 'client' => [
+ // 'timeout' => 5,
+ // ],
+],
+```
+
+After configuring your application's default mailer, add the following options to your `config/services.php` configuration file:
+
+```php
+'mailgun' => [
+ 'domain' => env('MAILGUN_DOMAIN'),
+ 'secret' => env('MAILGUN_SECRET'),
+ 'endpoint' => env('MAILGUN_ENDPOINT', 'api.mailgun.net'),
+ 'scheme' => 'https',
+],
+```
+
+If you are not using the United States [Mailgun region](https://documentation.mailgun.com/docs/mailgun/api-reference/#mailgun-regions), you may define your region's endpoint in the `services` configuration file:
+
+```php
+'mailgun' => [
+ 'domain' => env('MAILGUN_DOMAIN'),
+ 'secret' => env('MAILGUN_SECRET'),
+ 'endpoint' => env('MAILGUN_ENDPOINT', 'api.eu.mailgun.net'),
+ 'scheme' => 'https',
+],
+```
#### Postmark Driver
-To use the Postmark driver, install Symfony's Postmark Mailer transport via Composer:
+To use the [Postmark](https://postmarkapp.com/) driver, install Symfony's Postmark Mailer transport via Composer:
```shell
composer require symfony/postmark-mailer symfony/http-client
```
-Next, set the `default` option in your application's `config/mail.php` configuration file to `postmark`. After configuring your application's default mailer, verify that your `config/services.php` configuration file contains the following options:
+Next, set the `default` option in your application's `config/mail.php` configuration file to `postmark`. After configuring your application's default mailer, ensure that your `config/services.php` configuration file contains the following options:
- 'postmark' => [
- 'token' => env('POSTMARK_TOKEN'),
- ],
+```php
+'postmark' => [
+ 'token' => env('POSTMARK_TOKEN'),
+],
+```
If you would like to specify the Postmark message stream that should be used by a given mailer, you may add the `message_stream_id` configuration option to the mailer's configuration array. This configuration array can be found in your application's `config/mail.php` configuration file:
- 'postmark' => [
- 'transport' => 'postmark',
- 'message_stream_id' => env('POSTMARK_MESSAGE_STREAM_ID'),
- ],
+```php
+'postmark' => [
+ 'transport' => 'postmark',
+ 'message_stream_id' => env('POSTMARK_MESSAGE_STREAM_ID'),
+ // 'client' => [
+ // 'timeout' => 5,
+ // ],
+],
+```
This way you are also able to set up multiple Postmark mailers with different message streams.
+
+#### Resend Driver
+
+To use the [Resend](https://resend.com/) driver, install Resend's PHP SDK via Composer:
+
+```shell
+composer require resend/resend-php
+```
+
+Next, set the `default` option in your application's `config/mail.php` configuration file to `resend`. After configuring your application's default mailer, ensure that your `config/services.php` configuration file contains the following options:
+
+```php
+'resend' => [
+ 'key' => env('RESEND_KEY'),
+],
+```
+
#### SES Driver
@@ -103,58 +157,113 @@ composer require aws/aws-sdk-php
Next, set the `default` option in your `config/mail.php` configuration file to `ses` and verify that your `config/services.php` configuration file contains the following options:
- 'ses' => [
- 'key' => env('AWS_ACCESS_KEY_ID'),
- 'secret' => env('AWS_SECRET_ACCESS_KEY'),
- 'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
- ],
+```php
+'ses' => [
+ 'key' => env('AWS_ACCESS_KEY_ID'),
+ 'secret' => env('AWS_SECRET_ACCESS_KEY'),
+ 'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
+],
+```
To utilize AWS [temporary credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_use-resources.html) via a session token, you may add a `token` key to your application's SES configuration:
- 'ses' => [
- 'key' => env('AWS_ACCESS_KEY_ID'),
- 'secret' => env('AWS_SECRET_ACCESS_KEY'),
- 'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
- 'token' => env('AWS_SESSION_TOKEN'),
- ],
+```php
+'ses' => [
+ 'key' => env('AWS_ACCESS_KEY_ID'),
+ 'secret' => env('AWS_SECRET_ACCESS_KEY'),
+ 'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
+ 'token' => env('AWS_SESSION_TOKEN'),
+],
+```
+
+To interact with SES's [subscription management features](https://docs.aws.amazon.com/ses/latest/dg/sending-email-subscription-management.html), you may return the `X-Ses-List-Management-Options` header in the array returned by the [headers](#headers) method of a mail message:
+
+```php
+/**
+ * Get the message headers.
+ */
+public function headers(): Headers
+{
+ return new Headers(
+ text: [
+ 'X-Ses-List-Management-Options' => 'contactListName=MyContactList;topicName=MyTopic',
+ ],
+ );
+}
+```
If you would like to define [additional options](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sesv2-2019-09-27.html#sendemail) that Laravel should pass to the AWS SDK's `SendEmail` method when sending an email, you may define an `options` array within your `ses` configuration:
- 'ses' => [
- 'key' => env('AWS_ACCESS_KEY_ID'),
- 'secret' => env('AWS_SECRET_ACCESS_KEY'),
- 'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
- 'options' => [
- 'ConfigurationSetName' => 'MyConfigurationSet',
- 'EmailTags' => [
- ['Name' => 'foo', 'Value' => 'bar'],
- ],
+```php
+'ses' => [
+ 'key' => env('AWS_ACCESS_KEY_ID'),
+ 'secret' => env('AWS_SECRET_ACCESS_KEY'),
+ 'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
+ 'options' => [
+ 'ConfigurationSetName' => 'MyConfigurationSet',
+ 'EmailTags' => [
+ ['Name' => 'foo', 'Value' => 'bar'],
],
],
+],
+```
### Failover Configuration
Sometimes, an external service you have configured to send your application's mail may be down. In these cases, it can be useful to define one or more backup mail delivery configurations that will be used in case your primary delivery driver is down.
-To accomplish this, you should define a mailer within your application's `mail` configuration file that uses the `failover` transport. The configuration array for your application's `failover` mailer should contain an array of `mailers` that reference the order in which mail drivers should be chosen for delivery:
+To accomplish this, you should define a mailer within your application's `mail` configuration file that uses the `failover` transport. The configuration array for your application's `failover` mailer should contain an array of `mailers` that reference the order in which configured mailers should be chosen for delivery:
- 'mailers' => [
- 'failover' => [
- 'transport' => 'failover',
- 'mailers' => [
- 'postmark',
- 'mailgun',
- 'sendmail',
- ],
+```php
+'mailers' => [
+ 'failover' => [
+ 'transport' => 'failover',
+ 'mailers' => [
+ 'postmark',
+ 'mailgun',
+ 'sendmail',
],
-
- // ...
+ 'retry_after' => 60,
],
+ // ...
+],
+```
+
Once your failover mailer has been defined, you should set this mailer as the default mailer used by your application by specifying its name as the value of the `default` configuration key within your application's `mail` configuration file:
- 'default' => env('MAIL_MAILER', 'failover'),
+```php
+'default' => env('MAIL_MAILER', 'failover'),
+```
+
+
+### Round Robin Configuration
+
+The `roundrobin` transport allows you to distribute your mailing workload across multiple mailers. To get started, define a mailer within your application's `mail` configuration file that uses the `roundrobin` transport. The configuration array for your application's `roundrobin` mailer should contain an array of `mailers` that reference which configured mailers should be used for delivery:
+
+```php
+'mailers' => [
+ 'roundrobin' => [
+ 'transport' => 'roundrobin',
+ 'mailers' => [
+ 'ses',
+ 'postmark',
+ ],
+ 'retry_after' => 60,
+ ],
+
+ // ...
+],
+```
+
+Once your round robin mailer has been defined, you should set this mailer as the default mailer used by your application by specifying its name as the value of the `default` configuration key within your application's `mail` configuration file:
+
+```php
+'default' => env('MAIL_MAILER', 'roundrobin'),
+```
+
+The round robin transport selects a random mailer from the list of configured mailers and then switches to the next available mailer for each subsequent email. In contrast to `failover` transport, which helps to achieve *[high availability](https://en.wikipedia.org/wiki/High_availability)*, the `roundrobin` transport provides *[load balancing](https://en.wikipedia.org/wiki/Load_balancing_(computing))*.
## Generating Mailables
@@ -168,72 +277,113 @@ php artisan make:mail OrderShipped
## Writing Mailables
-Once you have generated a mailable class, open it up so we can explore its contents. First, note that all of a mailable class' configuration is done in the `build` method. Within this method, you may call various methods such as `from`, `subject`, `view`, and `attach` to configure the email's presentation and delivery.
+Once you have generated a mailable class, open it up so we can explore its contents. Mailable class configuration is done in several methods, including the `envelope`, `content`, and `attachments` methods.
-> {tip} You may type-hint dependencies on the mailable's `build` method. The Laravel [service container](/docs/{{version}}/container) automatically injects these dependencies.
+The `envelope` method returns an `Illuminate\Mail\Mailables\Envelope` object that defines the subject and, sometimes, the recipients of the message. The `content` method returns an `Illuminate\Mail\Mailables\Content` object that defines the [Blade template](/docs/{{version}}/blade) that will be used to generate the message content.
-### Configuring The Sender
+### Configuring the Sender
-
-#### Using The `from` Method
+
+#### Using the Envelope
-First, let's explore configuring the sender of the email. Or, in other words, who the email is going to be "from". There are two ways to configure the sender. First, you may use the `from` method within your mailable class' `build` method:
+First, let's explore configuring the sender of the email. Or, in other words, who the email is going to be "from". There are two ways to configure the sender. First, you may specify the "from" address on your message's envelope:
- /**
- * Build the message.
- *
- * @return $this
- */
- public function build()
- {
- return $this->from('example@example.com', 'Example')
- ->view('emails.orders.shipped');
- }
+```php
+use Illuminate\Mail\Mailables\Address;
+use Illuminate\Mail\Mailables\Envelope;
+
+/**
+ * Get the message envelope.
+ */
+public function envelope(): Envelope
+{
+ return new Envelope(
+ from: new Address('jeffrey@example.com', 'Jeffrey Way'),
+ subject: 'Order Shipped',
+ );
+}
+```
+
+If you would like, you may also specify a `replyTo` address:
+
+```php
+return new Envelope(
+ from: new Address('jeffrey@example.com', 'Jeffrey Way'),
+ replyTo: [
+ new Address('taylor@example.com', 'Taylor Otwell'),
+ ],
+ subject: 'Order Shipped',
+);
+```
-#### Using A Global `from` Address
+#### Using a Global `from` Address
-However, if your application uses the same "from" address for all of its emails, it can become cumbersome to call the `from` method in each mailable class you generate. Instead, you may specify a global "from" address in your `config/mail.php` configuration file. This address will be used if no other "from" address is specified within the mailable class:
+However, if your application uses the same "from" address for all of its emails, it can become cumbersome to add it to each mailable class you generate. Instead, you may specify a global "from" address in your `config/mail.php` configuration file. This address will be used if no other "from" address is specified within the mailable class:
- 'from' => ['address' => 'example@example.com', 'name' => 'App Name'],
+```php
+'from' => [
+ 'address' => env('MAIL_FROM_ADDRESS', 'hello@example.com'),
+ 'name' => env('MAIL_FROM_NAME', 'Example'),
+],
+```
In addition, you may define a global "reply_to" address within your `config/mail.php` configuration file:
- 'reply_to' => ['address' => 'example@example.com', 'name' => 'App Name'],
+```php
+'reply_to' => [
+ 'address' => 'example@example.com',
+ 'name' => 'App Name',
+],
+```
-### Configuring The View
-
-Within a mailable class' `build` method, you may use the `view` method to specify which template should be used when rendering the email's contents. Since each email typically uses a [Blade template](/docs/{{version}}/blade) to render its contents, you have the full power and convenience of the Blade templating engine when building your email's HTML:
-
- /**
- * Build the message.
- *
- * @return $this
- */
- public function build()
- {
- return $this->view('emails.orders.shipped');
- }
+### Configuring the View
+
+Within a mailable class's `content` method, you may define the `view`, or which template should be used when rendering the email's contents. Since each email typically uses a [Blade template](/docs/{{version}}/blade) to render its contents, you have the full power and convenience of the Blade templating engine when building your email's HTML:
+
+```php
+/**
+ * Get the message content definition.
+ */
+public function content(): Content
+{
+ return new Content(
+ view: 'mail.orders.shipped',
+ );
+}
+```
-> {tip} You may wish to create a `resources/views/emails` directory to house all of your email templates; however, you are free to place them wherever you wish within your `resources/views` directory.
+> [!NOTE]
+> You may wish to create a `resources/views/mail` directory to house all of your email templates; however, you are free to place them wherever you wish within your `resources/views` directory.
#### Plain Text Emails
-If you would like to define a plain-text version of your email, you may use the `text` method. Like the `view` method, the `text` method accepts a template name which will be used to render the contents of the email. You are free to define both an HTML and plain-text version of your message:
+If you would like to define a plain-text version of your email, you may specify the plain-text template when creating the message's `Content` definition. Like the `view` parameter, the `text` parameter should be a template name which will be used to render the contents of the email. You are free to define both an HTML and plain-text version of your message:
+
+```php
+/**
+ * Get the message content definition.
+ */
+public function content(): Content
+{
+ return new Content(
+ view: 'mail.orders.shipped',
+ text: 'mail.orders.shipped-text'
+ );
+}
+```
+
+For clarity, the `html` parameter may be used as an alias of the `view` parameter:
- /**
- * Build the message.
- *
- * @return $this
- */
- public function build()
- {
- return $this->view('emails.orders.shipped')
- ->text('emails.orders.shipped_plain');
- }
+```php
+return new Content(
+ html: 'mail.orders.shipped',
+ text: 'mail.orders.shipped-text'
+);
+```
### View Data
@@ -241,206 +391,214 @@ If you would like to define a plain-text version of your email, you may use the
#### Via Public Properties
-Typically, you will want to pass some data to your view that you can utilize when rendering the email's HTML. There are two ways you may make data available to your view. First, any public property defined on your mailable class will automatically be made available to the view. So, for example, you may pass data into your mailable class' constructor and set that data to public properties defined on the class:
+Typically, you will want to pass some data to your view that you can utilize when rendering the email's HTML. There are two ways you may make data available to your view. First, any public property defined on your mailable class will automatically be made available to the view. So, for example, you may pass data into your mailable class's constructor and set that data to public properties defined on the class:
+
+```php
+order = $order;
- }
-
- /**
- * Build the message.
- *
- * @return $this
- */
- public function build()
- {
- return $this->view('emails.orders.shipped');
- }
+ return new Content(
+ view: 'mail.orders.shipped',
+ );
}
+}
+```
Once the data has been set to a public property, it will automatically be available in your view, so you may access it like you would access any other data in your Blade templates:
-
+ */
+public function attachments(): array
+{
+ return [
+ Attachment::fromPath('/path/to/file'),
+ ];
+}
+```
- /**
- * Build the message.
- *
- * @return $this
- */
- public function build()
- {
- return $this->view('emails.orders.shipped')
- ->attach('/path/to/file', [
- 'as' => 'name.pdf',
- 'mime' => 'application/pdf',
- ]);
- }
+When attaching files to a message, you may also specify the display name and / or MIME type for the attachment using the `as` and `withMime` methods:
+
+```php
+/**
+ * Get the attachments for the message.
+ *
+ * @return array
+ */
+public function attachments(): array
+{
+ return [
+ Attachment::fromPath('/path/to/file')
+ ->as('name.pdf')
+ ->withMime('application/pdf'),
+ ];
+}
+```
#### Attaching Files From Disk
-If you have stored a file on one of your [filesystem disks](/docs/{{version}}/filesystem), you may attach it to the email using the `attachFromStorage` method:
-
- /**
- * Build the message.
- *
- * @return $this
- */
- public function build()
- {
- return $this->view('emails.orders.shipped')
- ->attachFromStorage('/path/to/file');
- }
-
-If necessary, you may specify the file's attachment name and additional options using the second and third arguments to the `attachFromStorage` method:
-
- /**
- * Build the message.
- *
- * @return $this
- */
- public function build()
- {
- return $this->view('emails.orders.shipped')
- ->attachFromStorage('/path/to/file', 'name.pdf', [
- 'mime' => 'application/pdf'
- ]);
- }
+If you have stored a file on one of your [filesystem disks](/docs/{{version}}/filesystem), you may attach it to the email using the `fromStorage` attachment method:
+
+```php
+/**
+ * Get the attachments for the message.
+ *
+ * @return array
+ */
+public function attachments(): array
+{
+ return [
+ Attachment::fromStorage('/path/to/file'),
+ ];
+}
+```
-The `attachFromStorageDisk` method may be used if you need to specify a storage disk other than your default disk:
+Of course, you may also specify the attachment's name and MIME type:
+
+```php
+/**
+ * Get the attachments for the message.
+ *
+ * @return array
+ */
+public function attachments(): array
+{
+ return [
+ Attachment::fromStorage('/path/to/file')
+ ->as('name.pdf')
+ ->withMime('application/pdf'),
+ ];
+}
+```
- /**
- * Build the message.
- *
- * @return $this
- */
- public function build()
- {
- return $this->view('emails.orders.shipped')
- ->attachFromStorageDisk('s3', '/path/to/file');
- }
+The `fromStorageDisk` method may be used if you need to specify a storage disk other than your default disk:
+
+```php
+/**
+ * Get the attachments for the message.
+ *
+ * @return array
+ */
+public function attachments(): array
+{
+ return [
+ Attachment::fromStorageDisk('s3', '/path/to/file')
+ ->as('name.pdf')
+ ->withMime('application/pdf'),
+ ];
+}
+```
#### Raw Data Attachments
-The `attachData` method may be used to attach a raw string of bytes as an attachment. For example, you might use this method if you have generated a PDF in memory and want to attach it to the email without writing it to disk. The `attachData` method accepts the raw data bytes as its first argument, the name of the file as its second argument, and an array of options as its third argument:
-
- /**
- * Build the message.
- *
- * @return $this
- */
- public function build()
- {
- return $this->view('emails.orders.shipped')
- ->attachData($this->pdf, 'name.pdf', [
- 'mime' => 'application/pdf',
- ]);
- }
+The `fromData` attachment method may be used to attach a raw string of bytes as an attachment. For example, you might use this method if you have generated a PDF in memory and want to attach it to the email without writing it to disk. The `fromData` method accepts a closure which resolves the raw data bytes as well as the name that the attachment should be assigned:
+
+```php
+/**
+ * Get the attachments for the message.
+ *
+ * @return array
+ */
+public function attachments(): array
+{
+ return [
+ Attachment::fromData(fn () => $this->pdf, 'Report.pdf')
+ ->withMime('application/pdf'),
+ ];
+}
+```
### Inline Attachments
@@ -455,7 +613,8 @@ Embedding inline images into your emails is typically cumbersome; however, Larav
```
-> {note} The `$message` variable is not available in plain-text message templates since plain-text messages do not utilize inline attachments.
+> [!WARNING]
+> The `$message` variable is not available in plain-text message templates since plain-text messages do not utilize inline attachments.
#### Embedding Raw Data Attachments
@@ -470,30 +629,150 @@ If you already have a raw image data string you wish to embed into an email temp
+
+You may instruct Laravel's "pluralizer", which is used by Eloquent and other portions of the framework to convert singular strings to plural strings, to use a language other than English. This may be accomplished by invoking the `useLanguage` method within the `boot` method of one of your application's service providers. The pluralizer's currently supported languages are: `french`, `norwegian-bokmal`, `portuguese`, `spanish`, and `turkish`:
+
+
+
+```php
+use Illuminate\Support\Pluralizer;
+
+/**
+ * Bootstrap any application services.
+ */
+public function boot(): void
+{
+ Pluralizer::useLanguage('spanish');
+
+ // ...
+}
+```
+
+> [!WARNING]
+> If you customize the pluralizer's language, you should explicitly define your Eloquent model's [table names](/docs/{{version}}/eloquent#table-names).
## Defining Translation Strings
@@ -75,30 +127,35 @@ You may use the `currentLocale` and `isLocale` methods on the `App` facade to de
Typically, translation strings are stored in files within the `lang` directory. Within this directory, there should be a subdirectory for each language supported by your application. This is the approach Laravel uses to manage translation strings for built-in Laravel features such as validation error messages:
- /lang
- /en
- messages.php
- /es
- messages.php
+```text
+/lang
+ /en
+ messages.php
+ /es
+ messages.php
+```
All language files return an array of keyed strings. For example:
- 'Welcome to our application!',
- ];
+return [
+ 'welcome' => 'Welcome to our application!',
+];
+```
-> {note} For languages that differ by territory, you should name the language directories according to the ISO 15897. For example, "en_GB" should be used for British English rather than "en-gb".
+> [!WARNING]
+> For languages that differ by territory, you should name the language directories according to the ISO 15897. For example, "en_GB" should be used for British English rather than "en-gb".
-### Using Translation Strings As Keys
+### Using Translation Strings as Keys
For applications with a large number of translatable strings, defining every string with a "short key" can become confusing when referencing the keys in your views and it is cumbersome to continually invent keys for every translation string supported by your application.
-For this reason, Laravel also provides support for defining translation strings using the "default" translation of the string as the key. Translation files that use translation strings as keys are stored as JSON files in the `lang` directory. For example, if your application has a Spanish translation, you should create a `lang/es.json` file:
+For this reason, Laravel also provides support for defining translation strings using the "default" translation of the string as the key. Language files that use translation strings as keys are stored as JSON files in the `lang` directory. For example, if your application has a Spanish translation, you should create a `lang/es.json` file:
```json
{
@@ -108,49 +165,85 @@ For this reason, Laravel also provides support for defining translation strings
#### Key / File Conflicts
-You should not define translation string keys that conflict with other translation filenames. For example, translating `__('Action')` for the "NL" locale while a `nl/action.php` file exists but a `nl.json` file does not exist will result in the translator returning the contents of `nl/action.php`.
+You should not define translation string keys that conflict with other translation filenames. For example, translating `__('Action')` for the "NL" locale while a `nl/action.php` file exists but a `nl.json` file does not exist will result in the translator returning the entire contents of `nl/action.php`.
## Retrieving Translation Strings
You may retrieve translation strings from your language files using the `__` helper function. If you are using "short keys" to define your translation strings, you should pass the file that contains the key and the key itself to the `__` function using "dot" syntax. For example, let's retrieve the `welcome` translation string from the `lang/en/messages.php` language file:
- echo __('messages.welcome');
+```php
+echo __('messages.welcome');
+```
If the specified translation string does not exist, the `__` function will return the translation string key. So, using the example above, the `__` function would return `messages.welcome` if the translation string does not exist.
- If you are using your [default translation strings as your translation keys](#using-translation-strings-as-keys), you should pass the default translation of your string to the `__` function;
+If you are using your [default translation strings as your translation keys](#using-translation-strings-as-keys), you should pass the default translation of your string to the `__` function;
- echo __('I love programming.');
+```php
+echo __('I love programming.');
+```
Again, if the translation string does not exist, the `__` function will return the translation string key that it was given.
If you are using the [Blade templating engine](/docs/{{version}}/blade), you may use the `{{ }}` echo syntax to display the translation string:
- {{ __('messages.welcome') }}
+```blade
+{{ __('messages.welcome') }}
+```
-### Replacing Parameters In Translation Strings
+### Replacing Parameters in Translation Strings
If you wish, you may define placeholders in your translation strings. All placeholders are prefixed with a `:`. For example, you may define a welcome message with a placeholder name:
- 'welcome' => 'Welcome, :name',
+```php
+'welcome' => 'Welcome, :name',
+```
To replace the placeholders when retrieving a translation string, you may pass an array of replacements as the second argument to the `__` function:
- echo __('messages.welcome', ['name' => 'dayle']);
+```php
+echo __('messages.welcome', ['name' => 'dayle']);
+```
If your placeholder contains all capital letters, or only has its first letter capitalized, the translated value will be capitalized accordingly:
- 'welcome' => 'Welcome, :NAME', // Welcome, DAYLE
- 'goodbye' => 'Goodbye, :Name', // Goodbye, Dayle
+```php
+'welcome' => 'Welcome, :NAME', // Welcome, DAYLE
+'goodbye' => 'Goodbye, :Name', // Goodbye, Dayle
+```
+
+
+#### Object Replacement Formatting
+
+If you attempt to provide an object as a translation placeholder, the object's `__toString` method will be invoked. The [__toString](https://www.php.net/manual/en/language.oop5.magic.php#object.tostring) method is one of PHP's built-in "magic methods". However, sometimes you may not have control over the `__toString` method of a given class, such as when the class that you are interacting with belongs to a third-party library.
+
+In these cases, Laravel allows you to register a custom formatting handler for that particular type of object. To accomplish this, you should invoke the translator's `stringable` method. The `stringable` method accepts a closure, which should type-hint the type of object that it is responsible for formatting. Typically, the `stringable` method should be invoked within the `boot` method of your application's `AppServiceProvider` class:
+
+```php
+use Illuminate\Support\Facades\Lang;
+use Money\Money;
+
+/**
+ * Bootstrap any application services.
+ */
+public function boot(): void
+{
+ Lang::stringable(function (Money $money) {
+ return $money->formatTo('en_GB');
+ });
+}
+```
### Pluralization
Pluralization is a complex problem, as different languages have a variety of complex rules for pluralization; however, Laravel can help you translate strings differently based on pluralization rules that you define. Using a `|` character, you may distinguish singular and plural forms of a string:
- 'apples' => 'There is one apple|There are many apples',
+```php
+'apples' => 'There is one apple|There are many apples',
+```
Of course, pluralization is also supported when using [translation strings as keys](#using-translation-strings-as-keys):
@@ -162,21 +255,29 @@ Of course, pluralization is also supported when using [translation strings as ke
You may even create more complex pluralization rules which specify translation strings for multiple ranges of values:
- 'apples' => '{0} There are none|[1,19] There are some|[20,*] There are many',
+```php
+'apples' => '{0} There are none|[1,19] There are some|[20,*] There are many',
+```
After defining a translation string that has pluralization options, you may use the `trans_choice` function to retrieve the line for a given "count". In this example, since the count is greater than one, the plural form of the translation string is returned:
- echo trans_choice('messages.apples', 10);
+```php
+echo trans_choice('messages.apples', 10);
+```
You may also define placeholder attributes in pluralization strings. These placeholders may be replaced by passing an array as the third argument to the `trans_choice` function:
- 'minutes_ago' => '{1} :value minute ago|[2,*] :value minutes ago',
+```php
+'minutes_ago' => '{1} :value minute ago|[2,*] :value minutes ago',
- echo trans_choice('time.minutes_ago', 5, ['value' => 5]);
+echo trans_choice('time.minutes_ago', 5, ['value' => 5]);
+```
If you would like to display the integer value that was passed to the `trans_choice` function, you may use the built-in `:count` placeholder:
- 'apples' => '{0} There are none|{1} There is one|[2,*] There are :count',
+```php
+'apples' => '{0} There are none|{1} There is one|[2,*] There are :count',
+```
## Overriding Package Language Files
diff --git a/logging.md b/logging.md
index 02d886d1352..0de5c8ae320 100644
--- a/logging.md
+++ b/logging.md
@@ -8,11 +8,15 @@
- [Building Log Stacks](#building-log-stacks)
- [Writing Log Messages](#writing-log-messages)
- [Contextual Information](#contextual-information)
- - [Writing To Specific Channels](#writing-to-specific-channels)
+ - [Writing to Specific Channels](#writing-to-specific-channels)
- [Monolog Channel Customization](#monolog-channel-customization)
- - [Customizing Monolog For Channels](#customizing-monolog-for-channels)
+ - [Customizing Monolog for Channels](#customizing-monolog-for-channels)
- [Creating Monolog Handler Channels](#creating-monolog-handler-channels)
- - [Creating Custom Channels Via Factories](#creating-custom-channels-via-factories)
+ - [Creating Custom Channels via Factories](#creating-custom-channels-via-factories)
+- [Tailing Log Messages Using Pail](#tailing-log-messages-using-pail)
+ - [Installation](#pail-installation)
+ - [Usage](#pail-usage)
+ - [Filtering Logs](#pail-filtering-logs)
## Introduction
@@ -26,360 +30,571 @@ Under the hood, Laravel utilizes the [Monolog](https://github.com/Seldaek/monolo
## Configuration
-All of the configuration options for your application's logging behavior is housed in the `config/logging.php` configuration file. This file allows you to configure your application's log channels, so be sure to review each of the available channels and their options. We'll review a few common options below.
+All of the configuration options that control your application's logging behavior are housed in the `config/logging.php` configuration file. This file allows you to configure your application's log channels, so be sure to review each of the available channels and their options. We'll review a few common options below.
By default, Laravel will use the `stack` channel when logging messages. The `stack` channel is used to aggregate multiple log channels into a single channel. For more information on building stacks, check out the [documentation below](#building-log-stacks).
-
-#### Configuring The Channel Name
-
-By default, Monolog is instantiated with a "channel name" that matches the current environment, such as `production` or `local`. To change this value, add a `name` option to your channel's configuration:
-
- 'stack' => [
- 'driver' => 'stack',
- 'name' => 'channel-name',
- 'channels' => ['single', 'slack'],
- ],
-
### Available Channel Drivers
Each log channel is powered by a "driver". The driver determines how and where the log message is actually recorded. The following log channel drivers are available in every Laravel application. An entry for most of these drivers is already present in your application's `config/logging.php` configuration file, so be sure to review this file to become familiar with its contents:
-Name | Description
-------------- | -------------
-`custom` | A driver that calls a specified factory to create a channel
-`daily` | A `RotatingFileHandler` based Monolog driver which rotates daily
-`errorlog` | An `ErrorLogHandler` based Monolog driver
-`monolog` | A Monolog factory driver that may use any supported Monolog handler
-`null` | A driver that discards all log messages
-`papertrail` | A `SyslogUdpHandler` based Monolog driver
-`single` | A single file or path based logger channel (`StreamHandler`)
-`slack` | A `SlackWebhookHandler` based Monolog driver
-`stack` | A wrapper to facilitate creating "multi-channel" channels
-`syslog` | A `SyslogHandler` based Monolog driver
-
-> {tip} Check out the documentation on [advanced channel customization](#monolog-channel-customization) to learn more about the `monolog` and `custom` drivers.
+
+
+| Name | Description |
+| ------------ | -------------------------------------------------------------------- |
+| `custom` | A driver that calls a specified factory to create a channel. |
+| `daily` | A `RotatingFileHandler` based Monolog driver which rotates daily. |
+| `errorlog` | An `ErrorLogHandler` based Monolog driver. |
+| `monolog` | A Monolog factory driver that may use any supported Monolog handler. |
+| `papertrail` | A `SyslogUdpHandler` based Monolog driver. |
+| `single` | A single file or path based logger channel (`StreamHandler`). |
+| `slack` | A `SlackWebhookHandler` based Monolog driver. |
+| `stack` | A wrapper to facilitate creating "multi-channel" channels. |
+| `syslog` | A `SyslogHandler` based Monolog driver. |
+
+
+
+> [!NOTE]
+> Check out the documentation on [advanced channel customization](#monolog-channel-customization) to learn more about the `monolog` and `custom` drivers.
+
+
+#### Configuring the Channel Name
+
+By default, Monolog is instantiated with a "channel name" that matches the current environment, such as `production` or `local`. To change this value, you may add a `name` option to your channel's configuration:
+
+```php
+'stack' => [
+ 'driver' => 'stack',
+ 'name' => 'channel-name',
+ 'channels' => ['single', 'slack'],
+],
+```
### Channel Prerequisites
-#### Configuring The Single and Daily Channels
+#### Configuring the Single and Daily Channels
The `single` and `daily` channels have three optional configuration options: `bubble`, `permission`, and `locking`.
-Name | Description | Default
-------------- | ------------- | -------------
-`bubble` | Indicates if messages should bubble up to other channels after being handled | `true`
-`locking` | Attempt to lock the log file before writing to it | `false`
-`permission` | The log file's permissions | `0644`
+
+
+| Name | Description | Default |
+| ------------ | ----------------------------------------------------------------------------- | ------- |
+| `bubble` | Indicates if messages should bubble up to other channels after being handled. | `true` |
+| `locking` | Attempt to lock the log file before writing to it. | `false` |
+| `permission` | The log file's permissions. | `0644` |
+
+
+
+Additionally, the retention policy for the `daily` channel can be configured via the `LOG_DAILY_DAYS` environment variable or by setting the `days` configuration option.
+
+
+
+| Name | Description | Default |
+| ------ | ----------------------------------------------------------- | ------- |
+| `days` | The number of days that daily log files should be retained. | `14` |
+
+
-#### Configuring The Papertrail Channel
+#### Configuring the Papertrail Channel
-The `papertrail` channel requires the `host` and `port` configuration options. You can obtain these values from [Papertrail](https://help.papertrailapp.com/kb/configuration/configuring-centralized-logging-from-php-apps/#send-events-from-php-app).
+The `papertrail` channel requires `host` and `port` configuration options. These may be defined via the `PAPERTRAIL_URL` and `PAPERTRAIL_PORT` environment variables. You can obtain these values from [Papertrail](https://help.papertrailapp.com/kb/configuration/configuring-centralized-logging-from-php-apps/#send-events-from-php-app).
-#### Configuring The Slack Channel
+#### Configuring the Slack Channel
-The `slack` channel requires a `url` configuration option. This URL should match a URL for an [incoming webhook](https://slack.com/apps/A0F7XDUAZ-incoming-webhooks) that you have configured for your Slack team.
+The `slack` channel requires a `url` configuration option. This value may be defined via the `LOG_SLACK_WEBHOOK_URL` environment variable. This URL should match a URL for an [incoming webhook](https://slack.com/apps/A0F7XDUAZ-incoming-webhooks) that you have configured for your Slack team.
-By default, Slack will only receive logs at the `critical` level and above; however, you can adjust this in your `config/logging.php` configuration file by modifying the `level` configuration option within your Slack log channel's configuration array.
+By default, Slack will only receive logs at the `critical` level and above; however, you can adjust this using the `LOG_LEVEL` environment variable or by modifying the `level` configuration option within your Slack log channel's configuration array.
### Logging Deprecation Warnings
-PHP, Laravel, and other libraries often notify their users that some of their features have been deprecated and will be removed in a future version. If you would like to log these deprecation warnings, you may specify your preferred `deprecations` log channel in your application's `config/logging.php` configuration file:
+PHP, Laravel, and other libraries often notify their users that some of their features have been deprecated and will be removed in a future version. If you would like to log these deprecation warnings, you may specify your preferred `deprecations` log channel using the `LOG_DEPRECATIONS_CHANNEL` environment variable, or within your application's `config/logging.php` configuration file:
- 'deprecations' => env('LOG_DEPRECATIONS_CHANNEL', 'null'),
+```php
+'deprecations' => [
+ 'channel' => env('LOG_DEPRECATIONS_CHANNEL', 'null'),
+ 'trace' => env('LOG_DEPRECATIONS_TRACE', false),
+],
- 'channels' => [
- ...
- ]
+'channels' => [
+ // ...
+]
+```
Or, you may define a log channel named `deprecations`. If a log channel with this name exists, it will always be used to log deprecations:
- 'channels' => [
- 'deprecations' => [
- 'driver' => 'single',
- 'path' => storage_path('logs/php-deprecation-warnings.log'),
- ],
+```php
+'channels' => [
+ 'deprecations' => [
+ 'driver' => 'single',
+ 'path' => storage_path('logs/php-deprecation-warnings.log'),
],
+],
+```
## Building Log Stacks
As mentioned previously, the `stack` driver allows you to combine multiple channels into a single log channel for convenience. To illustrate how to use log stacks, let's take a look at an example configuration that you might see in a production application:
- 'channels' => [
- 'stack' => [
- 'driver' => 'stack',
- 'channels' => ['syslog', 'slack'],
- ],
+```php
+'channels' => [
+ 'stack' => [
+ 'driver' => 'stack',
+ 'channels' => ['syslog', 'slack'], // [tl! add]
+ 'ignore_exceptions' => false,
+ ],
- 'syslog' => [
- 'driver' => 'syslog',
- 'level' => 'debug',
- ],
+ 'syslog' => [
+ 'driver' => 'syslog',
+ 'level' => env('LOG_LEVEL', 'debug'),
+ 'facility' => env('LOG_SYSLOG_FACILITY', LOG_USER),
+ 'replace_placeholders' => true,
+ ],
- 'slack' => [
- 'driver' => 'slack',
- 'url' => env('LOG_SLACK_WEBHOOK_URL'),
- 'username' => 'Laravel Log',
- 'emoji' => ':boom:',
- 'level' => 'critical',
- ],
+ 'slack' => [
+ 'driver' => 'slack',
+ 'url' => env('LOG_SLACK_WEBHOOK_URL'),
+ 'username' => env('LOG_SLACK_USERNAME', 'Laravel Log'),
+ 'emoji' => env('LOG_SLACK_EMOJI', ':boom:'),
+ 'level' => env('LOG_LEVEL', 'critical'),
+ 'replace_placeholders' => true,
],
+],
+```
Let's dissect this configuration. First, notice our `stack` channel aggregates two other channels via its `channels` option: `syslog` and `slack`. So, when logging messages, both of these channels will have the opportunity to log the message. However, as we will see below, whether these channels actually log the message may be determined by the message's severity / "level".
#### Log Levels
-Take note of the `level` configuration option present on the `syslog` and `slack` channel configurations in the example above. This option determines the minimum "level" a message must be in order to be logged by the channel. Monolog, which powers Laravel's logging services, offers all of the log levels defined in the [RFC 5424 specification](https://tools.ietf.org/html/rfc5424): **emergency**, **alert**, **critical**, **error**, **warning**, **notice**, **info**, and **debug**.
+Take note of the `level` configuration option present on the `syslog` and `slack` channel configurations in the example above. This option determines the minimum "level" a message must be in order to be logged by the channel. Monolog, which powers Laravel's logging services, offers all of the log levels defined in the [RFC 5424 specification](https://tools.ietf.org/html/rfc5424). In descending order of severity, these log levels are: **emergency**, **alert**, **critical**, **error**, **warning**, **notice**, **info**, and **debug**.
So, imagine we log a message using the `debug` method:
- Log::debug('An informational message.');
+```php
+Log::debug('An informational message.');
+```
Given our configuration, the `syslog` channel will write the message to the system log; however, since the error message is not `critical` or above, it will not be sent to Slack. However, if we log an `emergency` message, it will be sent to both the system log and Slack since the `emergency` level is above our minimum level threshold for both channels:
- Log::emergency('The system is down!');
+```php
+Log::emergency('The system is down!');
+```
## Writing Log Messages
You may write information to the logs using the `Log` [facade](/docs/{{version}}/facades). As previously mentioned, the logger provides the eight logging levels defined in the [RFC 5424 specification](https://tools.ietf.org/html/rfc5424): **emergency**, **alert**, **critical**, **error**, **warning**, **notice**, **info** and **debug**:
- use Illuminate\Support\Facades\Log;
+```php
+use Illuminate\Support\Facades\Log;
- Log::emergency($message);
- Log::alert($message);
- Log::critical($message);
- Log::error($message);
- Log::warning($message);
- Log::notice($message);
- Log::info($message);
- Log::debug($message);
+Log::emergency($message);
+Log::alert($message);
+Log::critical($message);
+Log::error($message);
+Log::warning($message);
+Log::notice($message);
+Log::info($message);
+Log::debug($message);
+```
You may call any of these methods to log a message for the corresponding level. By default, the message will be written to the default log channel as configured by your `logging` configuration file:
- User::findOrFail($id)
- ]);
- }
+ Log::info('Showing the user profile for user: {id}', ['id' => $id]);
+
+ return view('user.profile', [
+ 'user' => User::findOrFail($id)
+ ]);
}
+}
+```
### Contextual Information
An array of contextual data may be passed to the log methods. This contextual data will be formatted and displayed with the log message:
- use Illuminate\Support\Facades\Log;
+```php
+use Illuminate\Support\Facades\Log;
- Log::info('User failed to login.', ['id' => $user->id]);
+Log::info('User {id} failed to login.', ['id' => $user->id]);
+```
-Occasionally, you may wish to specify some contextual information that should be included with all subsequent log entries. For example, you may wish to log a request ID that is associated with each incoming request to your application. To accomplish this, you may call the `Log` facade's `withContext` method:
+Occasionally, you may wish to specify some contextual information that should be included with all subsequent log entries in a particular channel. For example, you may wish to log a request ID that is associated with each incoming request to your application. To accomplish this, you may call the `Log` facade's `withContext` method:
- $requestId
- ]);
-
- return $next($request)->header('Request-Id', $requestId);
- }
+ $requestId = (string) Str::uuid();
+
+ Log::withContext([
+ 'request-id' => $requestId
+ ]);
+
+ $response = $next($request);
+
+ $response->headers->set('Request-Id', $requestId);
+
+ return $response;
}
+}
+```
+
+If you would like to share contextual information across _all_ logging channels, you may invoke the `Log::shareContext()` method. This method will provide the contextual information to all created channels and any channels that are created subsequently:
+
+```php
+ $requestId
+ ]);
+
+ // ...
+ }
+}
+```
+
+> [!NOTE]
+> If you need to share log context while processing queued jobs, you may utilize [job middleware](/docs/{{version}}/queues#job-middleware).
-### Writing To Specific Channels
+### Writing to Specific Channels
Sometimes you may wish to log a message to a channel other than your application's default channel. You may use the `channel` method on the `Log` facade to retrieve and log to any channel defined in your configuration file:
- use Illuminate\Support\Facades\Log;
+```php
+use Illuminate\Support\Facades\Log;
- Log::channel('slack')->info('Something happened!');
+Log::channel('slack')->info('Something happened!');
+```
If you would like to create an on-demand logging stack consisting of multiple channels, you may use the `stack` method:
- Log::stack(['single', 'slack'])->info('Something happened!');
+```php
+Log::stack(['single', 'slack'])->info('Something happened!');
+```
#### On-Demand Channels
It is also possible to create an on-demand channel by providing the configuration at runtime without that configuration being present in your application's `logging` configuration file. To accomplish this, you may pass a configuration array to the `Log` facade's `build` method:
- use Illuminate\Support\Facades\Log;
+```php
+use Illuminate\Support\Facades\Log;
- Log::build([
- 'driver' => 'single',
- 'path' => storage_path('logs/custom.log'),
- ])->info('Something happened!');
+Log::build([
+ 'driver' => 'single',
+ 'path' => storage_path('logs/custom.log'),
+])->info('Something happened!');
+```
You may also wish to include an on-demand channel in an on-demand logging stack. This can be achieved by including your on-demand channel instance in the array passed to the `stack` method:
- use Illuminate\Support\Facades\Log;
+```php
+use Illuminate\Support\Facades\Log;
- $channel = Log::build([
- 'driver' => 'single',
- 'path' => storage_path('logs/custom.log'),
- ]);
+$channel = Log::build([
+ 'driver' => 'single',
+ 'path' => storage_path('logs/custom.log'),
+]);
- Log::stack(['slack', $channel])->info('Something happened!');
+Log::stack(['slack', $channel])->info('Something happened!');
+```
## Monolog Channel Customization
-### Customizing Monolog For Channels
+### Customizing Monolog for Channels
Sometimes you may need complete control over how Monolog is configured for an existing channel. For example, you may want to configure a custom Monolog `FormatterInterface` implementation for Laravel's built-in `single` channel.
To get started, define a `tap` array on the channel's configuration. The `tap` array should contain a list of classes that should have an opportunity to customize (or "tap" into) the Monolog instance after it is created. There is no conventional location where these classes should be placed, so you are free to create a directory within your application to contain these classes:
- 'single' => [
- 'driver' => 'single',
- 'tap' => [App\Logging\CustomizeFormatter::class],
- 'path' => storage_path('logs/laravel.log'),
- 'level' => 'debug',
- ],
+```php
+'single' => [
+ 'driver' => 'single',
+ 'tap' => [App\Logging\CustomizeFormatter::class],
+ 'path' => storage_path('logs/laravel.log'),
+ 'level' => env('LOG_LEVEL', 'debug'),
+ 'replace_placeholders' => true,
+],
+```
Once you have configured the `tap` option on your channel, you're ready to define the class that will customize your Monolog instance. This class only needs a single method: `__invoke`, which receives an `Illuminate\Log\Logger` instance. The `Illuminate\Log\Logger` instance proxies all method calls to the underlying Monolog instance:
- getHandlers() as $handler) {
- $handler->setFormatter(new LineFormatter(
- '[%datetime%] %channel%.%level_name%: %message% %context% %extra%'
- ));
- }
+ foreach ($logger->getHandlers() as $handler) {
+ $handler->setFormatter(new LineFormatter(
+ '[%datetime%] %channel%.%level_name%: %message% %context% %extra%'
+ ));
}
}
+}
+```
-> {tip} All of your "tap" classes are resolved by the [service container](/docs/{{version}}/container), so any constructor dependencies they require will automatically be injected.
+> [!NOTE]
+> All of your "tap" classes are resolved by the [service container](/docs/{{version}}/container), so any constructor dependencies they require will automatically be injected.
### Creating Monolog Handler Channels
-Monolog has a variety of [available handlers](https://github.com/Seldaek/monolog/tree/main/src/Monolog/Handler) and Laravel does not include a built-in channel for each one. In some cases, you may wish to create a custom channel that is merely an instance of a specific Monolog handler that does not have a corresponding Laravel log driver. These channels can be easily created using the `monolog` driver.
+Monolog has a variety of [available handlers](https://github.com/Seldaek/monolog/tree/main/src/Monolog/Handler) and Laravel does not include a built-in channel for each one. In some cases, you may wish to create a custom channel that is merely an instance of a specific Monolog handler that does not have a corresponding Laravel log driver. These channels can be easily created using the `monolog` driver.
-When using the `monolog` driver, the `handler` configuration option is used to specify which handler will be instantiated. Optionally, any constructor parameters the handler needs may be specified using the `with` configuration option:
+When using the `monolog` driver, the `handler` configuration option is used to specify which handler will be instantiated. Optionally, any constructor parameters the handler needs may be specified using the `handler_with` configuration option:
- 'logentries' => [
- 'driver' => 'monolog',
- 'handler' => Monolog\Handler\SyslogUdpHandler::class,
- 'with' => [
- 'host' => 'my.logentries.internal.datahubhost.company.com',
- 'port' => '10000',
- ],
+```php
+'logentries' => [
+ 'driver' => 'monolog',
+ 'handler' => Monolog\Handler\SyslogUdpHandler::class,
+ 'handler_with' => [
+ 'host' => 'my.logentries.internal.datahubhost.company.com',
+ 'port' => '10000',
],
+],
+```
#### Monolog Formatters
When using the `monolog` driver, the Monolog `LineFormatter` will be used as the default formatter. However, you may customize the type of formatter passed to the handler using the `formatter` and `formatter_with` configuration options:
- 'browser' => [
- 'driver' => 'monolog',
- 'handler' => Monolog\Handler\BrowserConsoleHandler::class,
- 'formatter' => Monolog\Formatter\HtmlFormatter::class,
- 'formatter_with' => [
- 'dateFormat' => 'Y-m-d',
- ],
+```php
+'browser' => [
+ 'driver' => 'monolog',
+ 'handler' => Monolog\Handler\BrowserConsoleHandler::class,
+ 'formatter' => Monolog\Formatter\HtmlFormatter::class,
+ 'formatter_with' => [
+ 'dateFormat' => 'Y-m-d',
],
+],
+```
If you are using a Monolog handler that is capable of providing its own formatter, you may set the value of the `formatter` configuration option to `default`:
- 'newrelic' => [
- 'driver' => 'monolog',
- 'handler' => Monolog\Handler\NewRelicHandler::class,
- 'formatter' => 'default',
+```php
+'newrelic' => [
+ 'driver' => 'monolog',
+ 'handler' => Monolog\Handler\NewRelicHandler::class,
+ 'formatter' => 'default',
+],
+```
+
+
+#### Monolog Processors
+
+Monolog can also process messages before logging them. You can create your own processors or use the [existing processors offered by Monolog](https://github.com/Seldaek/monolog/tree/main/src/Monolog/Processor).
+
+If you would like to customize the processors for a `monolog` driver, add a `processors` configuration value to your channel's configuration:
+
+```php
+'memory' => [
+ 'driver' => 'monolog',
+ 'handler' => Monolog\Handler\StreamHandler::class,
+ 'handler_with' => [
+ 'stream' => 'php://stderr',
],
+ 'processors' => [
+ // Simple syntax...
+ Monolog\Processor\MemoryUsageProcessor::class,
+
+ // With options...
+ [
+ 'processor' => Monolog\Processor\PsrLogMessageProcessor::class,
+ 'with' => ['removeUsedContextFields' => true],
+ ],
+ ],
+],
+```
-### Creating Custom Channels Via Factories
+### Creating Custom Channels via Factories
If you would like to define an entirely custom channel in which you have full control over Monolog's instantiation and configuration, you may specify a `custom` driver type in your `config/logging.php` configuration file. Your configuration should include a `via` option that contains the name of the factory class which will be invoked to create the Monolog instance:
- 'channels' => [
- 'example-custom-channel' => [
- 'driver' => 'custom',
- 'via' => App\Logging\CreateCustomLogger::class,
- ],
+```php
+'channels' => [
+ 'example-custom-channel' => [
+ 'driver' => 'custom',
+ 'via' => App\Logging\CreateCustomLogger::class,
],
+],
+```
Once you have configured the `custom` driver channel, you're ready to define the class that will create your Monolog instance. This class only needs a single `__invoke` method which should return the Monolog logger instance. The method will receive the channels configuration array as its only argument:
-
+## Tailing Log Messages Using Pail
+
+Often you may need to tail your application's logs in real time. For example, when debugging an issue or when monitoring your application's logs for specific types of errors.
+
+Laravel Pail is a package that allows you to easily dive into your Laravel application's log files directly from the command line. Unlike the standard `tail` command, Pail is designed to work with any log driver, including Sentry or Flare. In addition, Pail provides a set of useful filters to help you quickly find what you're looking for.
+
+
+
+
+### Installation
+
+> [!WARNING]
+> Laravel Pail requires the [PCNTL](https://www.php.net/manual/en/book.pcntl.php) PHP extension.
+
+To get started, install Pail into your project using the Composer package manager:
+
+```shell
+composer require --dev laravel/pail
+```
+
+
+### Usage
+
+To start tailing logs, run the `pail` command:
+
+```shell
+php artisan pail
+```
+
+To increase the verbosity of the output and avoid truncation (…), use the `-v` option:
+
+```shell
+php artisan pail -v
+```
+
+For maximum verbosity and to display exception stack traces, use the `-vv` option:
+
+```shell
+php artisan pail -vv
+```
+
+To stop tailing logs, press `Ctrl+C` at any time.
+
+
+### Filtering Logs
+
+
+#### `--filter`
+
+You may use the `--filter` option to filter logs by their type, file, message, and stack trace content:
+
+```shell
+php artisan pail --filter="QueryException"
+```
+
+
+#### `--message`
+
+To filter logs by only their message, you may use the `--message` option:
+
+```shell
+php artisan pail --message="User created"
+```
+
+
+#### `--level`
+
+The `--level` option may be used to filter logs by their [log level](#log-levels):
+
+```shell
+php artisan pail --level=error
+```
+
+
+#### `--user`
+
+To only display logs that were written while a given user was authenticated, you may provide the user's ID to the `--user` option:
+
+```shell
+php artisan pail --user=1
+```
diff --git a/mail.md b/mail.md
index 9ced46384c8..fd32113157c 100644
--- a/mail.md
+++ b/mail.md
@@ -4,25 +4,31 @@
- [Configuration](#configuration)
- [Driver Prerequisites](#driver-prerequisites)
- [Failover Configuration](#failover-configuration)
+ - [Round Robin Configuration](#round-robin-configuration)
- [Generating Mailables](#generating-mailables)
- [Writing Mailables](#writing-mailables)
- - [Configuring The Sender](#configuring-the-sender)
- - [Configuring The View](#configuring-the-view)
+ - [Configuring the Sender](#configuring-the-sender)
+ - [Configuring the View](#configuring-the-view)
- [View Data](#view-data)
- [Attachments](#attachments)
- [Inline Attachments](#inline-attachments)
- - [Customizing The Symfony Message](#customizing-the-symfony-message)
+ - [Attachable Objects](#attachable-objects)
+ - [Headers](#headers)
+ - [Tags and Metadata](#tags-and-metadata)
+ - [Customizing the Symfony Message](#customizing-the-symfony-message)
- [Markdown Mailables](#markdown-mailables)
- [Generating Markdown Mailables](#generating-markdown-mailables)
- [Writing Markdown Messages](#writing-markdown-messages)
- - [Customizing The Components](#customizing-the-components)
+ - [Customizing the Components](#customizing-the-components)
- [Sending Mail](#sending-mail)
- [Queueing Mail](#queueing-mail)
- [Rendering Mailables](#rendering-mailables)
- - [Previewing Mailables In The Browser](#previewing-mailables-in-the-browser)
+ - [Previewing Mailables in the Browser](#previewing-mailables-in-the-browser)
- [Localizing Mailables](#localizing-mailables)
-- [Testing Mailables](#testing-mailables)
-- [Mail & Local Development](#mail-and-local-development)
+- [Testing](#testing-mailables)
+ - [Testing Mailable Content](#testing-mailable-content)
+ - [Testing Mailable Sending](#testing-mailable-sending)
+- [Mail and Local Development](#mail-and-local-development)
- [Events](#events)
- [Custom Transports](#custom-transports)
- [Additional Symfony Transports](#additional-symfony-transports)
@@ -30,7 +36,7 @@
## Introduction
-Sending email doesn't have to be complicated. Laravel provides a clean, simple email API powered by the popular [Symfony Mailer](https://symfony.com/doc/6.0/mailer.html) component. Laravel and Symfony Mailer provide drivers for sending email via SMTP, Mailgun, Postmark, Amazon SES, and `sendmail`, allowing you to quickly get started sending mail through a local or cloud based service of your choice.
+Sending email doesn't have to be complicated. Laravel provides a clean, simple email API powered by the popular [Symfony Mailer](https://symfony.com/doc/current/mailer.html) component. Laravel and Symfony Mailer provide drivers for sending email via SMTP, Mailgun, Postmark, Resend, Amazon SES, and `sendmail`, allowing you to quickly get started sending mail through a local or cloud-based service of your choice.
### Configuration
@@ -42,7 +48,7 @@ Within your `mail` configuration file, you will find a `mailers` configuration a
### Driver / Transport Prerequisites
-The API based drivers such as Mailgun and Postmark are often simpler and faster than sending mail via SMTP servers. Whenever possible, we recommend that you use one of these drivers.
+The API based drivers such as Mailgun, Postmark, and Resend are often simpler and faster than sending mail via SMTP servers. Whenever possible, we recommend that you use one of these drivers.
#### Mailgun Driver
@@ -53,45 +59,93 @@ To use the Mailgun driver, install Symfony's Mailgun Mailer transport via Compos
composer require symfony/mailgun-mailer symfony/http-client
```
-Next, set the `default` option in your application's `config/mail.php` configuration file to `mailgun`. After configuring your application's default mailer, verify that your `config/services.php` configuration file contains the following options:
+Next, you will need to make two changes in your application's `config/mail.php` configuration file. First, set your default mailer to `mailgun`:
- 'mailgun' => [
- 'domain' => env('MAILGUN_DOMAIN'),
- 'secret' => env('MAILGUN_SECRET'),
- ],
+```php
+'default' => env('MAIL_MAILER', 'mailgun'),
+```
-If you are not using the United States [Mailgun region](https://documentation.mailgun.com/en/latest/api-intro.html#mailgun-regions), you may define your region's endpoint in the `services` configuration file:
+Second, add the following configuration array to your array of `mailers`:
- 'mailgun' => [
- 'domain' => env('MAILGUN_DOMAIN'),
- 'secret' => env('MAILGUN_SECRET'),
- 'endpoint' => env('MAILGUN_ENDPOINT', 'api.eu.mailgun.net'),
- ],
+```php
+'mailgun' => [
+ 'transport' => 'mailgun',
+ // 'client' => [
+ // 'timeout' => 5,
+ // ],
+],
+```
+
+After configuring your application's default mailer, add the following options to your `config/services.php` configuration file:
+
+```php
+'mailgun' => [
+ 'domain' => env('MAILGUN_DOMAIN'),
+ 'secret' => env('MAILGUN_SECRET'),
+ 'endpoint' => env('MAILGUN_ENDPOINT', 'api.mailgun.net'),
+ 'scheme' => 'https',
+],
+```
+
+If you are not using the United States [Mailgun region](https://documentation.mailgun.com/docs/mailgun/api-reference/#mailgun-regions), you may define your region's endpoint in the `services` configuration file:
+
+```php
+'mailgun' => [
+ 'domain' => env('MAILGUN_DOMAIN'),
+ 'secret' => env('MAILGUN_SECRET'),
+ 'endpoint' => env('MAILGUN_ENDPOINT', 'api.eu.mailgun.net'),
+ 'scheme' => 'https',
+],
+```
#### Postmark Driver
-To use the Postmark driver, install Symfony's Postmark Mailer transport via Composer:
+To use the [Postmark](https://postmarkapp.com/) driver, install Symfony's Postmark Mailer transport via Composer:
```shell
composer require symfony/postmark-mailer symfony/http-client
```
-Next, set the `default` option in your application's `config/mail.php` configuration file to `postmark`. After configuring your application's default mailer, verify that your `config/services.php` configuration file contains the following options:
+Next, set the `default` option in your application's `config/mail.php` configuration file to `postmark`. After configuring your application's default mailer, ensure that your `config/services.php` configuration file contains the following options:
- 'postmark' => [
- 'token' => env('POSTMARK_TOKEN'),
- ],
+```php
+'postmark' => [
+ 'token' => env('POSTMARK_TOKEN'),
+],
+```
If you would like to specify the Postmark message stream that should be used by a given mailer, you may add the `message_stream_id` configuration option to the mailer's configuration array. This configuration array can be found in your application's `config/mail.php` configuration file:
- 'postmark' => [
- 'transport' => 'postmark',
- 'message_stream_id' => env('POSTMARK_MESSAGE_STREAM_ID'),
- ],
+```php
+'postmark' => [
+ 'transport' => 'postmark',
+ 'message_stream_id' => env('POSTMARK_MESSAGE_STREAM_ID'),
+ // 'client' => [
+ // 'timeout' => 5,
+ // ],
+],
+```
This way you are also able to set up multiple Postmark mailers with different message streams.
+
+#### Resend Driver
+
+To use the [Resend](https://resend.com/) driver, install Resend's PHP SDK via Composer:
+
+```shell
+composer require resend/resend-php
+```
+
+Next, set the `default` option in your application's `config/mail.php` configuration file to `resend`. After configuring your application's default mailer, ensure that your `config/services.php` configuration file contains the following options:
+
+```php
+'resend' => [
+ 'key' => env('RESEND_KEY'),
+],
+```
+
#### SES Driver
@@ -103,58 +157,113 @@ composer require aws/aws-sdk-php
Next, set the `default` option in your `config/mail.php` configuration file to `ses` and verify that your `config/services.php` configuration file contains the following options:
- 'ses' => [
- 'key' => env('AWS_ACCESS_KEY_ID'),
- 'secret' => env('AWS_SECRET_ACCESS_KEY'),
- 'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
- ],
+```php
+'ses' => [
+ 'key' => env('AWS_ACCESS_KEY_ID'),
+ 'secret' => env('AWS_SECRET_ACCESS_KEY'),
+ 'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
+],
+```
To utilize AWS [temporary credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_use-resources.html) via a session token, you may add a `token` key to your application's SES configuration:
- 'ses' => [
- 'key' => env('AWS_ACCESS_KEY_ID'),
- 'secret' => env('AWS_SECRET_ACCESS_KEY'),
- 'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
- 'token' => env('AWS_SESSION_TOKEN'),
- ],
+```php
+'ses' => [
+ 'key' => env('AWS_ACCESS_KEY_ID'),
+ 'secret' => env('AWS_SECRET_ACCESS_KEY'),
+ 'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
+ 'token' => env('AWS_SESSION_TOKEN'),
+],
+```
+
+To interact with SES's [subscription management features](https://docs.aws.amazon.com/ses/latest/dg/sending-email-subscription-management.html), you may return the `X-Ses-List-Management-Options` header in the array returned by the [headers](#headers) method of a mail message:
+
+```php
+/**
+ * Get the message headers.
+ */
+public function headers(): Headers
+{
+ return new Headers(
+ text: [
+ 'X-Ses-List-Management-Options' => 'contactListName=MyContactList;topicName=MyTopic',
+ ],
+ );
+}
+```
If you would like to define [additional options](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sesv2-2019-09-27.html#sendemail) that Laravel should pass to the AWS SDK's `SendEmail` method when sending an email, you may define an `options` array within your `ses` configuration:
- 'ses' => [
- 'key' => env('AWS_ACCESS_KEY_ID'),
- 'secret' => env('AWS_SECRET_ACCESS_KEY'),
- 'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
- 'options' => [
- 'ConfigurationSetName' => 'MyConfigurationSet',
- 'EmailTags' => [
- ['Name' => 'foo', 'Value' => 'bar'],
- ],
+```php
+'ses' => [
+ 'key' => env('AWS_ACCESS_KEY_ID'),
+ 'secret' => env('AWS_SECRET_ACCESS_KEY'),
+ 'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
+ 'options' => [
+ 'ConfigurationSetName' => 'MyConfigurationSet',
+ 'EmailTags' => [
+ ['Name' => 'foo', 'Value' => 'bar'],
],
],
+],
+```
### Failover Configuration
Sometimes, an external service you have configured to send your application's mail may be down. In these cases, it can be useful to define one or more backup mail delivery configurations that will be used in case your primary delivery driver is down.
-To accomplish this, you should define a mailer within your application's `mail` configuration file that uses the `failover` transport. The configuration array for your application's `failover` mailer should contain an array of `mailers` that reference the order in which mail drivers should be chosen for delivery:
+To accomplish this, you should define a mailer within your application's `mail` configuration file that uses the `failover` transport. The configuration array for your application's `failover` mailer should contain an array of `mailers` that reference the order in which configured mailers should be chosen for delivery:
- 'mailers' => [
- 'failover' => [
- 'transport' => 'failover',
- 'mailers' => [
- 'postmark',
- 'mailgun',
- 'sendmail',
- ],
+```php
+'mailers' => [
+ 'failover' => [
+ 'transport' => 'failover',
+ 'mailers' => [
+ 'postmark',
+ 'mailgun',
+ 'sendmail',
],
-
- // ...
+ 'retry_after' => 60,
],
+ // ...
+],
+```
+
Once your failover mailer has been defined, you should set this mailer as the default mailer used by your application by specifying its name as the value of the `default` configuration key within your application's `mail` configuration file:
- 'default' => env('MAIL_MAILER', 'failover'),
+```php
+'default' => env('MAIL_MAILER', 'failover'),
+```
+
+
+### Round Robin Configuration
+
+The `roundrobin` transport allows you to distribute your mailing workload across multiple mailers. To get started, define a mailer within your application's `mail` configuration file that uses the `roundrobin` transport. The configuration array for your application's `roundrobin` mailer should contain an array of `mailers` that reference which configured mailers should be used for delivery:
+
+```php
+'mailers' => [
+ 'roundrobin' => [
+ 'transport' => 'roundrobin',
+ 'mailers' => [
+ 'ses',
+ 'postmark',
+ ],
+ 'retry_after' => 60,
+ ],
+
+ // ...
+],
+```
+
+Once your round robin mailer has been defined, you should set this mailer as the default mailer used by your application by specifying its name as the value of the `default` configuration key within your application's `mail` configuration file:
+
+```php
+'default' => env('MAIL_MAILER', 'roundrobin'),
+```
+
+The round robin transport selects a random mailer from the list of configured mailers and then switches to the next available mailer for each subsequent email. In contrast to `failover` transport, which helps to achieve *[high availability](https://en.wikipedia.org/wiki/High_availability)*, the `roundrobin` transport provides *[load balancing](https://en.wikipedia.org/wiki/Load_balancing_(computing))*.
## Generating Mailables
@@ -168,72 +277,113 @@ php artisan make:mail OrderShipped
## Writing Mailables
-Once you have generated a mailable class, open it up so we can explore its contents. First, note that all of a mailable class' configuration is done in the `build` method. Within this method, you may call various methods such as `from`, `subject`, `view`, and `attach` to configure the email's presentation and delivery.
+Once you have generated a mailable class, open it up so we can explore its contents. Mailable class configuration is done in several methods, including the `envelope`, `content`, and `attachments` methods.
-> {tip} You may type-hint dependencies on the mailable's `build` method. The Laravel [service container](/docs/{{version}}/container) automatically injects these dependencies.
+The `envelope` method returns an `Illuminate\Mail\Mailables\Envelope` object that defines the subject and, sometimes, the recipients of the message. The `content` method returns an `Illuminate\Mail\Mailables\Content` object that defines the [Blade template](/docs/{{version}}/blade) that will be used to generate the message content.
-### Configuring The Sender
+### Configuring the Sender
-
-#### Using The `from` Method
+
+#### Using the Envelope
-First, let's explore configuring the sender of the email. Or, in other words, who the email is going to be "from". There are two ways to configure the sender. First, you may use the `from` method within your mailable class' `build` method:
+First, let's explore configuring the sender of the email. Or, in other words, who the email is going to be "from". There are two ways to configure the sender. First, you may specify the "from" address on your message's envelope:
- /**
- * Build the message.
- *
- * @return $this
- */
- public function build()
- {
- return $this->from('example@example.com', 'Example')
- ->view('emails.orders.shipped');
- }
+```php
+use Illuminate\Mail\Mailables\Address;
+use Illuminate\Mail\Mailables\Envelope;
+
+/**
+ * Get the message envelope.
+ */
+public function envelope(): Envelope
+{
+ return new Envelope(
+ from: new Address('jeffrey@example.com', 'Jeffrey Way'),
+ subject: 'Order Shipped',
+ );
+}
+```
+
+If you would like, you may also specify a `replyTo` address:
+
+```php
+return new Envelope(
+ from: new Address('jeffrey@example.com', 'Jeffrey Way'),
+ replyTo: [
+ new Address('taylor@example.com', 'Taylor Otwell'),
+ ],
+ subject: 'Order Shipped',
+);
+```
-#### Using A Global `from` Address
+#### Using a Global `from` Address
-However, if your application uses the same "from" address for all of its emails, it can become cumbersome to call the `from` method in each mailable class you generate. Instead, you may specify a global "from" address in your `config/mail.php` configuration file. This address will be used if no other "from" address is specified within the mailable class:
+However, if your application uses the same "from" address for all of its emails, it can become cumbersome to add it to each mailable class you generate. Instead, you may specify a global "from" address in your `config/mail.php` configuration file. This address will be used if no other "from" address is specified within the mailable class:
- 'from' => ['address' => 'example@example.com', 'name' => 'App Name'],
+```php
+'from' => [
+ 'address' => env('MAIL_FROM_ADDRESS', 'hello@example.com'),
+ 'name' => env('MAIL_FROM_NAME', 'Example'),
+],
+```
In addition, you may define a global "reply_to" address within your `config/mail.php` configuration file:
- 'reply_to' => ['address' => 'example@example.com', 'name' => 'App Name'],
+```php
+'reply_to' => [
+ 'address' => 'example@example.com',
+ 'name' => 'App Name',
+],
+```
-### Configuring The View
-
-Within a mailable class' `build` method, you may use the `view` method to specify which template should be used when rendering the email's contents. Since each email typically uses a [Blade template](/docs/{{version}}/blade) to render its contents, you have the full power and convenience of the Blade templating engine when building your email's HTML:
-
- /**
- * Build the message.
- *
- * @return $this
- */
- public function build()
- {
- return $this->view('emails.orders.shipped');
- }
+### Configuring the View
+
+Within a mailable class's `content` method, you may define the `view`, or which template should be used when rendering the email's contents. Since each email typically uses a [Blade template](/docs/{{version}}/blade) to render its contents, you have the full power and convenience of the Blade templating engine when building your email's HTML:
+
+```php
+/**
+ * Get the message content definition.
+ */
+public function content(): Content
+{
+ return new Content(
+ view: 'mail.orders.shipped',
+ );
+}
+```
-> {tip} You may wish to create a `resources/views/emails` directory to house all of your email templates; however, you are free to place them wherever you wish within your `resources/views` directory.
+> [!NOTE]
+> You may wish to create a `resources/views/mail` directory to house all of your email templates; however, you are free to place them wherever you wish within your `resources/views` directory.
#### Plain Text Emails
-If you would like to define a plain-text version of your email, you may use the `text` method. Like the `view` method, the `text` method accepts a template name which will be used to render the contents of the email. You are free to define both an HTML and plain-text version of your message:
+If you would like to define a plain-text version of your email, you may specify the plain-text template when creating the message's `Content` definition. Like the `view` parameter, the `text` parameter should be a template name which will be used to render the contents of the email. You are free to define both an HTML and plain-text version of your message:
+
+```php
+/**
+ * Get the message content definition.
+ */
+public function content(): Content
+{
+ return new Content(
+ view: 'mail.orders.shipped',
+ text: 'mail.orders.shipped-text'
+ );
+}
+```
+
+For clarity, the `html` parameter may be used as an alias of the `view` parameter:
- /**
- * Build the message.
- *
- * @return $this
- */
- public function build()
- {
- return $this->view('emails.orders.shipped')
- ->text('emails.orders.shipped_plain');
- }
+```php
+return new Content(
+ html: 'mail.orders.shipped',
+ text: 'mail.orders.shipped-text'
+);
+```
### View Data
@@ -241,206 +391,214 @@ If you would like to define a plain-text version of your email, you may use the
#### Via Public Properties
-Typically, you will want to pass some data to your view that you can utilize when rendering the email's HTML. There are two ways you may make data available to your view. First, any public property defined on your mailable class will automatically be made available to the view. So, for example, you may pass data into your mailable class' constructor and set that data to public properties defined on the class:
+Typically, you will want to pass some data to your view that you can utilize when rendering the email's HTML. There are two ways you may make data available to your view. First, any public property defined on your mailable class will automatically be made available to the view. So, for example, you may pass data into your mailable class's constructor and set that data to public properties defined on the class:
+
+```php
+order = $order;
- }
-
- /**
- * Build the message.
- *
- * @return $this
- */
- public function build()
- {
- return $this->view('emails.orders.shipped');
- }
+ return new Content(
+ view: 'mail.orders.shipped',
+ );
}
+}
+```
Once the data has been set to a public property, it will automatically be available in your view, so you may access it like you would access any other data in your Blade templates:
-
- Price: {{ $order->price }}
-
+```blade
+
+ Price: {{ $order->price }}
+
+```
+
+
+#### Via the `with` Parameter:
-
-#### Via The `with` Method:
+If you would like to customize the format of your email's data before it is sent to the template, you may manually pass your data to the view via the `Content` definition's `with` parameter. Typically, you will still pass data via the mailable class's constructor; however, you should set this data to `protected` or `private` properties so the data is not automatically made available to the template:
-If you would like to customize the format of your email's data before it is sent to the template, you may manually pass your data to the view via the `with` method. Typically, you will still pass data via the mailable class' constructor; however, you should set this data to `protected` or `private` properties so the data is not automatically made available to the template. Then, when calling the `with` method, pass an array of data that you wish to make available to the template:
+```php
+order = $order;
- }
-
- /**
- * Build the message.
- *
- * @return $this
- */
- public function build()
- {
- return $this->view('emails.orders.shipped')
- ->with([
- 'orderName' => $this->order->name,
- 'orderPrice' => $this->order->price,
- ]);
- }
+ return new Content(
+ view: 'mail.orders.shipped',
+ with: [
+ 'orderName' => $this->order->name,
+ 'orderPrice' => $this->order->price,
+ ],
+ );
}
+}
+```
-Once the data has been passed to the `with` method, it will automatically be available in your view, so you may access it like you would access any other data in your Blade templates:
+Once the data has been passed via the `with` parameter, it will automatically be available in your view, so you may access it like you would access any other data in your Blade templates:
-
- Price: {{ $orderPrice }}
-
+```blade
+
+ Price: {{ $orderPrice }}
+
+```
### Attachments
-To add attachments to an email, use the `attach` method within the mailable class' `build` method. The `attach` method accepts the full path to the file as its first argument:
+To add attachments to an email, you will add attachments to the array returned by the message's `attachments` method. First, you may add an attachment by providing a file path to the `fromPath` method provided by the `Attachment` class:
- /**
- * Build the message.
- *
- * @return $this
- */
- public function build()
- {
- return $this->view('emails.orders.shipped')
- ->attach('/path/to/file');
- }
+```php
+use Illuminate\Mail\Mailables\Attachment;
-When attaching files to a message, you may also specify the display name and / or MIME type by passing an `array` as the second argument to the `attach` method:
+/**
+ * Get the attachments for the message.
+ *
+ * @return array