Merge branch '10.x'

Author: nunomaduro

broadcasting.md

@@ -306,7 +306,7 @@ Events are broadcast over "channels", which may be specified as public or privat
 
 Before diving into each component of event broadcasting, let's take a high level overview using an e-commerce store as an example.
 
-In our application, let's assume we have a page that allows users to view the shipping status for their orders. Let's also assume that a `OrderShipmentStatusUpdated` event is fired when a shipping status update is processed by the application:
+In our application, let's assume we have a page that allows users to view the shipping status for their orders. Let's also assume that an `OrderShipmentStatusUpdated` event is fired when a shipping status update is processed by the application:
 
     use App\Events\OrderShipmentStatusUpdated;
 
@@ -696,7 +696,7 @@ However, remember that we also broadcast the task's creation. If your JavaScript
 <a name="only-to-others-configuration"></a>
 #### Configuration
 
-When you initialize a Laravel Echo instance, a socket ID is assigned to the connection. If you are using a global [Axios](https://github.com/mzabriskie/axios) instance to make HTTP requests from your JavaScript application, the socket ID will automatically be attached to every outgoing request as a `X-Socket-ID` header. Then, when you call the `toOthers` method, Laravel will extract the socket ID from the header and instruct the broadcaster to not broadcast to any connections with that socket ID.
+When you initialize a Laravel Echo instance, a socket ID is assigned to the connection. If you are using a global [Axios](https://github.com/mzabriskie/axios) instance to make HTTP requests from your JavaScript application, the socket ID will automatically be attached to every outgoing request as an `X-Socket-ID` header. Then, when you call the `toOthers` method, Laravel will extract the socket ID from the header and instruct the broadcaster to not broadcast to any connections with that socket ID.
 
 If you are not using a global Axios instance, you will need to manually configure your JavaScript application to send the `X-Socket-ID` header with all outgoing requests. You may retrieve the socket ID using the `Echo.socketId` method:
 
@@ -851,7 +851,7 @@ Echo.join(`chat.${roomId}`)
     });
 ```
 
-The `here` callback will be executed immediately once the channel is joined successfully, and will receive an array containing the user information for all of the other users currently subscribed to the channel. The `joining` method will be executed when a new user joins a channel, while the `leaving` method will be executed when a user leaves the channel. The `error` method will be executed when the authentication endpoint returns a HTTP status code other than 200 or if there is a problem parsing the returned JSON.
+The `here` callback will be executed immediately once the channel is joined successfully, and will receive an array containing the user information for all of the other users currently subscribed to the channel. The `joining` method will be executed when a new user joins a channel, while the `leaving` method will be executed when a user leaves the channel. The `error` method will be executed when the authentication endpoint returns an HTTP status code other than 200 or if there is a problem parsing the returned JSON.
 
 <a name="broadcasting-to-presence-channels"></a>
 ### Broadcasting to Presence Channels
@@ -982,7 +982,7 @@ protected function newBroadcastableEvent(string $event): BroadcastableModelEvent
 
 As you may have noticed, the `broadcastOn` method in the model example above did not return `Channel` instances. Instead, Eloquent models were returned directly. If an Eloquent model instance is returned by your model's `broadcastOn` method (or is contained in an array returned by the method), Laravel will automatically instantiate a private channel instance for the model using the model's class name and primary key identifier as the channel name.
 
-So, an `App\Models\User` model with an `id` of `1` would be converted into a `Illuminate\Broadcasting\PrivateChannel` instance with a name of `App.Models.User.1`. Of course, in addition to returning Eloquent model instances from your model's `broadcastOn` method, you may return complete `Channel` instances in order to have full control over the model's channel names:
+So, an `App\Models\User` model with an `id` of `1` would be converted into an `Illuminate\Broadcasting\PrivateChannel` instance with a name of `App.Models.User.1`. Of course, in addition to returning Eloquent model instances from your model's `broadcastOn` method, you may return complete `Channel` instances in order to have full control over the model's channel names:
 
 ```php
 use Illuminate\Broadcasting\PrivateChannel;

configuration.md

@@ -186,17 +186,31 @@ php artisan env:decrypt --force
 <a name="accessing-configuration-values"></a>
 ## Accessing Configuration Values
 
-You may easily access your configuration values using the 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:
+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:
+
+    use Illuminate\Support\Facades\Config;
+
+    $value = Config::get('app.timezone');
 
     $value = config('app.timezone');
 
     // Retrieve a default value if the configuration value does not exist...
     $value = config('app.timezone', 'Asia/Seoul');
 
-To set configuration values at runtime, pass an array to the `config` function:
+To set configuration values at runtime, you may invoke the `Config` facade's `set` method or pass an array to the `config` function:
+
+    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:
+
+    Config::string('config-key');
+    Config::integer('config-key');
+    Config::float('config-key');
+    Config::boolean('config-key');
+    Config::array('config-key');
+
 <a name="configuration-caching"></a>
 ## Configuration Caching
 

eloquent-resources.md

@@ -334,24 +334,6 @@ By default, your outermost resource is wrapped in a `data` key when the resource
 }
 ```
 
-If you would like to use a custom key instead of `data`, you may define a `$wrap` attribute on the resource class:
-
-    <?php
-
-    namespace App\Http\Resources;
-
-    use Illuminate\Http\Resources\Json\JsonResource;
-
-    class UserResource extends JsonResource
-    {
-        /**
-         * The "data" wrapper that should be applied.
-         *
-         * @var string|null
-         */
-        public static $wrap = 'user';
-    }
-
 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:
 
     <?php

prompts.md

@@ -11,6 +11,7 @@
     - [Suggest](#suggest)
     - [Search](#search)
     - [Multi-search](#multisearch)
+    - [Pause](#pause)
 - [Informational Messages](#informational-messages)
 - [Tables](#tables)
 - [Spin](#spin)
@@ -638,8 +639,19 @@ $ids = multisearch(
 
 If the `options` closure returns an associative array, then the closure will receive the selected keys; otherwise, it will receive the selected values. The closure may return an error message, or `null` if the validation passes.
 
+<a name="pause"></a>
+### Pause
+
+The `pause` function may be used to display informational text to the user and wait for them to confirm their desire to proceed by pressing the Enter / Return key:
+
+```php
+use function Laravel\Prompts\pause;
+
+pause('Press ENTER to continue.');
+```
+
 <a name="informational-messages"></a>
-### Informational Messages
+## Informational Messages
 
 The `note`, `info`, `warning`, `error`, and `alert` functions may be used to display informational messages:
 
@@ -650,7 +662,7 @@ info('Package installed successfully.');
 ```
 
 <a name="tables"></a>
-### Tables
+## Tables
 
 The `table` function makes it easy to display multiple rows and columns of data. All you need to do is provide the column names and the data for the table:
 
@@ -664,7 +676,7 @@ table(
 ```
 
 <a name="spin"></a>
-### Spin
+## Spin
 
 The `spin` function displays a spinner along with an optional message while executing a specified callback. It serves to indicate ongoing processes and returns the callback's results upon completion:
 
@@ -733,7 +745,7 @@ $progress->finish();
 ```
 
 <a name="terminal-considerations"></a>
-### Terminal Considerations
+## Terminal Considerations
 
 <a name="terminal-width"></a>
 #### Terminal Width
@@ -746,7 +758,7 @@ If the length of any label, option, or validation message exceeds the number of
 For any prompts that accept the `scroll` argument, the configured value will automatically be reduced to fit the height of the user's terminal, including space for a validation message.
 
 <a name="fallbacks"></a>
-### Unsupported Environments and Fallbacks
+## Unsupported Environments and Fallbacks
 
 Laravel Prompts supports macOS, Linux, and Windows with WSL. Due to limitations in the Windows version of PHP, it is not currently possible to use Laravel Prompts on Windows outside of WSL.
 

queries.md

@@ -380,6 +380,26 @@ You may use the `joinSub`, `leftJoinSub`, and `rightJoinSub` methods to join a q
                 $join->on('users.id', '=', 'latest_posts.user_id');
             })->get();
 
+<a name="lateral-joins"></a>
+#### Lateral Joins
+
+> [!WARNING]  
+> Lateral joins are currently supported by PostgreSQL, MySQL >= 8.0.14, and SQL Server.
+
+You may use the `joinLateral` and `leftJoinLateral` methods to perform a "lateral join" with a subquery. Each of these methods receives two arguments: the subquery and its table alias. The join condition(s) should be specified within the `where` clause of the given subquery. Lateral joins are evaluated for each row and can reference columns outside the subquery.
+
+In this example, we will retrieve a collection of users as well as the user's three most recent blog posts. Each user can produce up to three rows in the result set: one for each of their most recent blog posts. The join condition is specified with a `whereColumn` clause within the subquery, referencing the current user row:
+
+    $latestPosts = DB::table('posts')
+                       ->select('id as post_id', 'title as post_title', 'created_at as post_created_at')
+                       ->whereColumn('user_id', 'users.id')
+                       ->orderBy('created_at', 'desc')
+                       ->limit(3);
+
+    $users = DB::table('users')
+                ->joinLateral($latestPosts, 'latest_posts')
+                ->get();
+
 <a name="unions"></a>
 ## Unions
 

queues.md

@@ -1897,7 +1897,7 @@ When a particular job fails, you may want to send an alert to your users or reve
         /**
          * Handle a job failure.
          */
-        public function failed(Throwable $exception): void
+        public function failed(?Throwable $exception): void
         {
             // Send user notification of failure, etc...
         }

rate-limiting.md

@@ -66,20 +66,24 @@ If you would like to manually interact with the rate limiter, a variety of other
         return 'Too many attempts!';
     }
 
-    RateLimiter::hit('send-message:'.$user->id);
+    RateLimiter::increment('send-message:'.$user->id);
 
     // Send message...
 
-Alternatively, you may use the `remaining` method to retrieve the number of attempts remaining for a given key. If a given key has retries remaining, you may invoke the `hit` method to increment the number of total attempts:
+Alternatively, you may use the `remaining` method to retrieve the number of attempts remaining for a given key. If a given key has retries remaining, you may invoke the `increment` method to increment the number of total attempts:
 
     use Illuminate\Support\Facades\RateLimiter;
 
     if (RateLimiter::remaining('send-message:'.$user->id, $perMinute = 5)) {
-        RateLimiter::hit('send-message:'.$user->id);
+        RateLimiter::increment('send-message:'.$user->id);
 
         // Send message...
     }
 
+If you would like to increment the value for a given rate limiter key by more than one, you may provide the desired amount to the `increment` method:
+
+    RateLimiter::increment('send-message:'.$user->id, amount: 5);
+
 <a name="determining-limiter-availability"></a>
 #### Determining Limiter Availability
 
@@ -93,7 +97,7 @@ When a key has no more attempts left, the `availableIn` method returns the numbe
         return 'You may try again in '.$seconds.' seconds.';
     }
 
-    RateLimiter::hit('send-message:'.$user->id);
+    RateLimiter::increment('send-message:'.$user->id);
 
     // Send message...
 

strings.md

@@ -559,6 +559,10 @@ The `Str::isUrl` method determines if the given string is a valid URL:
 
     // false
 
+The `isUrl` method considers a wide range of protocols as valid. However, you may specify the protocols that should be considered valid by providing them to the `isUrl` method:
+
+    $isUrl = Str::isUrl('http://example.com', ['http', 'https']);
+
 <a name="method-str-is-ulid"></a>
 #### `Str::isUlid()` {.collection-method}
 
@@ -1758,6 +1762,10 @@ The `isUrl` method determines if a given string is a URL:
 
     // false
 
+The `isUrl` method considers a wide range of protocols as valid. However, you may specify the protocols that should be considered valid by providing them to the `isUrl` method:
+
+    $result = Str::of('http://example.com')->isUrl(['http', 'https']);
+
 <a name="method-fluent-str-is-uuid"></a>
 #### `isUuid` {.collection-method}
 

telescope.md

@@ -56,6 +56,8 @@ php artisan telescope:install
 php artisan migrate
 ```
 
+Finally, you may access the Telescope dashboard via the `/telescope` route.
+
 <a name="local-only-installation"></a>
 ### Local Only Installation
 

validation.md

@@ -1245,6 +1245,28 @@ The `Enum` rule is a class based rule that validates whether the field under val
         'status' => [Rule::enum(ServerStatus::class)],
     ]);
 
+The `Enum` rule's `only` and `except` methods may be used to limit which enum cases should be considered valid:
+
+    Rule::enum(ServerStatus::class)
+        ->only([ServerStatus::Pending, ServerStatus::Active]);
+
+    Rule::enum(ServerStatus::class)
+        ->except([ServerStatus::Pending, ServerStatus::Active]);
+
+The `when` method may be used to conditionally modify the `Enum` rule:
+
+```php
+use Illuminate\Support\Facades\Auth;
+use Illuminate\Validation\Rule;
+
+Rule::enum(ServerStatus::class)
+    ->when(
+        Auth::user()->isAdmin(),
+        fn ($rule) => $rule->only(...),
+        fn ($rule) => $rule->only(...),
+    );
+```
+
 <a name="rule-exclude"></a>
 #### exclude