Merge branch 'main' into feature/externalize-artifacts

docs/.artifacts/4.x/events.json

@@ -37530,6 +37530,12 @@
         "type": "craft\\events\\RegisterComponentTypesEvent",
         "desc": "The event that is triggered when registering field types."
     },
+    {
+        "class": "craft\\services\\Fields",
+        "name": "EVENT_DEFINE_COMPATIBLE_FIELD_TYPES",
+        "type": "craft\\events\\DefineCompatibleFieldTypesEvent",
+        "desc": "The event that is triggered when defining the compatible field types for a field."
+    },
     {
         "class": "craft\\services\\Fields",
         "name": "EVENT_BEFORE_SAVE_FIELD_GROUP",

docs/.artifacts/commerce/4.x/events.json

@@ -2458,6 +2458,24 @@
         "type": "yii\\base\\ActionEvent",
         "desc": "an event raised right after executing a controller action."
     },
+    {
+        "class": "craft\\commerce\\console\\controllers\\GatewaysController",
+        "name": "EVENT_DEFINE_ACTIONS",
+        "type": "craft\\events\\DefineConsoleActionsEvent",
+        "desc": "The event that is triggered when defining custom actions for this controller."
+    },
+    {
+        "class": "craft\\commerce\\console\\controllers\\GatewaysController",
+        "name": "EVENT_BEFORE_ACTION",
+        "type": "yii\\base\\ActionEvent",
+        "desc": "an event raised right before executing a controller action. You may set `ActionEvent::isValid` to be false to cancel the action execution."
+    },
+    {
+        "class": "craft\\commerce\\console\\controllers\\GatewaysController",
+        "name": "EVENT_AFTER_ACTION",
+        "type": "yii\\base\\ActionEvent",
+        "desc": "an event raised right after executing a controller action."
+    },
     {
         "class": "craft\\commerce\\console\\controllers\\ResetDataController",
         "name": "EVENT_DEFINE_ACTIONS",

docs/.vuepress/theme/components/SidebarLink.vue

@@ -60,6 +60,12 @@ export default {
 };
 
 function renderLink(h, to, text, active, level) {
+  const hashPosition = to.indexOf('#');
+  const path = to.substring(0, hashPosition > 0 ? hashPosition : to.length);
+  const segments = path.split('/');
+  const lastSegment = segments[segments.length - 1];
+  const handle = lastSegment.replace('.html', '');
+
   const component = {
     props: {
       to,
@@ -69,6 +75,8 @@ function renderLink(h, to, text, active, level) {
     class: {
       active,
       "sidebar-link": true,
+      // Include a “slug” identifier when this isn't a jump link:
+      [`slug-${handle || 'root'}`]: hashPosition < 0,
     },
   };
 

docs/4.x/deployment.md

@@ -101,7 +101,7 @@ Proprietary and open source cloud computing solutions are both options for hosti
 
 ## Deployment
 
-Broadly, we’re defining _deployment_ as the process of publishing code changes to a live website.
+Broadly, we’re defining _deployment_ as the process of publishing code changes to a live website. For the following examples, we’ll assume your project uses the standard [directory structure](directory-structure.md).
 
 ::: tip
 Be sure and read our [Deployment Best Practices](kb:deployment-best-practices) article for some high-level recommendations. What follows is intended for technical users who are tasked with extending their workflow to a web server.
@@ -161,7 +161,7 @@ With a generic deployment framework in place, we’re ready to get into a few co
 
 Let’s assume you’ve cloned your project onto a host, and configured it to serve requests directly out of the `web/` directory.
 
-Within the project directory, a simple Git-based deployment might look like this:
+Within the project’s root directory, a simple Git-based deployment might look like this:
 
 ```bash
 # Fetch new code:

docs/4.x/extend/controllers.md

@@ -405,7 +405,7 @@ public function actionEdit(?int $id = null, ?Widget $widget = null)
     $widgets = MyPlugin::getInstance()->getWidgets();
 
     // Do we have an incoming Widget ID from the route?
-    if ($widgetId !== null) {
+    if ($id !== null) {
         // Was a Widget model passed back via route params? It should take priority:
         if ($widget === null) {
             // Nope, let’s look it up:
@@ -473,16 +473,16 @@ public function actionSave()
     if (!$widgets->saveWidget($widget)) {
         // Hand the model back to the original route:
         return $this->asModelFailure(
-            $widget,
+            $widget, // Model, passed back under the key, below...
             Craft::t('my-plugin', 'Something went wrong!'), // Flash message
             'widget', // Route param key
         );
     }
 
     return $this->asModelSuccess(
-        $widget,
+        $widget, // Model (included in JSON responses)
         Craft::t('my-plugin', 'Widget saved.'), // Flash message
-        'widget', // Route param key
+        'widget', // Key the model will be under (in JSON responses)
         'my-plugin/widgets/{id}', // Redirect “object template”
     );
 }

docs/4.x/extend/element-types.md

@@ -144,7 +144,7 @@ use craft\helpers\Db;
 public function afterSave(bool $isNew)
 {
     if (!$this->propagating) {
-        Db::upsert('{{%products}}', [
+        Db::upsert('{{%plugin_products}}', [
             'id' => $this->id,
         ], [
             'price' => $this->price,

docs/4.x/extend/queue-jobs.md

@@ -103,11 +103,11 @@ public function execute($queue): void
 
 ### Dealing with Failed Jobs
 
-In our first example, exceptions from the mailer can bubble out of our job—but in the second example, we’re to ensuring the job is not halted prematurely.
+In our first example, exceptions from the mailer can bubble out of our job—but in the second example, we catch those errors so the job is not halted prematurely.
 
 This decision is up to you: if the work in a job is nonessential (or will be done again later, like <craft4:craft\queue\jobs\GeneratePendingTransforms>), you can catch and log errors and let the job end nominally; if the work is critical (like synchronizing something to an external API), it may be better to let the exception bubble out of `execute()`.
 
-The queue wraps every job in its own `try` block, and will flag any jobs that generate exceptions as failed. The exception message that caused the failure will be recorded along with the job. Failed jobs can be retried from the control panel or with the `php craft queue/retry [id]` command.
+The queue wraps every job in its own `try` block, and will mark any jobs that throw exceptions as _failed_. The exception message that caused the failure will be recorded along with the job. Failed jobs can be retried from the control panel or with the `php craft queue/retry [id]` command.
 
 #### Retryable Jobs
 

docs/4.x/graphql.md

@@ -177,7 +177,7 @@ You can manage your schemas in the control panel at **GraphQL** → **Schemas**.
 
 ### Using the GraphiQL IDE
 
-The easiest way to start exploring your GraphQL API is with the built-in [GraphiQL](https://github.com/graphql/graphiql) IDE, which is available in the control panel from **GraphQL** → **Explore**.
+The easiest way to start exploring your GraphQL API is with the built-in [GraphiQL](https://github.com/graphql/graphiql) IDE, which is available in the control panel from **GraphQL** → **GraphiQL**.
 
 ![The built-in GraphiQL IDE](./images/graphiql.png)
 
@@ -1460,6 +1460,7 @@ This is the interface implemented by all users.
 | `status`| `String` | The element’s status.
 | `dateCreated`| `DateTime` | The date the element was created.
 | `dateUpdated`| `DateTime` | The date the element was last updated.
+| `photo`| `AssetInterface` | The user’s photo.
 | `friendlyName`| `String` | The user’s first name or username.
 | `fullName`| `String` | The user’s full name.
 | `name`| `String!` | The user’s full name or username.

docs/4.x/installation.md

@@ -78,7 +78,7 @@ Done for the day? [`ddev stop`](https://ddev.readthedocs.io/en/stable/users/basi
 
 ### Workflow + Collaboration
 
-We encourage starting with a local development environment (rather than a remote host) as a means of  of a defined workflow—whatever it may be—to the reliability and longevity of a website.
+We encourage starting with a local development environment (rather than a remote host) fosters a workflow that will support the reliability and longevity of a website.
 
 <See path="./deployment.md#workflow" label="Defining a Workflow" />
 

docs/commerce/4.x/dev/controller-actions.md

@@ -12,22 +12,22 @@ We recommend reviewing the main Craft documentation on [working with controller
 
 ## Available Actions
 
-Action | Description
------- | -----------
-<badge vertical="baseline" type="verb">POST</badge> [cart/complete](#post-cart-complete) | Completes an order without payment.
-<badge vertical="baseline" type="verb">GET</badge> [cart/get-cart](#get-cart-get-cart) | Returns the current cart as JSON.
-<badge vertical="baseline" type="verb">GET/POST</badge> [cart/load-cart](#get-post-cart-load-cart) | Loads a cookie for the given cart.
-<badge vertical="baseline" type="verb">POST</badge> [cart/forget-cart](#get-post-cart-forget-cart) | Loads a cookie for the given cart.
-<badge vertical="baseline" type="verb">POST</badge> [cart/update-cart](#post-cart-update-cart) | Manage a customer’s current [cart](../orders-carts.md).
-<badge vertical="baseline" type="verb">POST</badge> [payment-sources/add](#post-payment-sources-add) | Creates a new payment source.
-<badge vertical="baseline" type="verb">POST</badge> [payment-sources/delete](#post-payment-sources-delete) | Deletes a payment source.
-<badge vertical="baseline" type="verb">GET</badge> [payments/complete-payment](#get-payments-complete-payment) | Processes customer’s return from an off-site payment.
-<badge vertical="baseline" type="verb">POST</badge> [payments/pay](#post-payments-pay) | Makes a payment on an order.
-<badge vertical="baseline" type="verb">GET</badge> [downloads/pdf](#get-downloads-pdf) | Returns an order PDF as a file.
-<badge vertical="baseline" type="verb">POST</badge> [subscriptions/subscribe](#post-subscriptions-subscribe) | Starts a new subscription.
-<badge vertical="baseline" type="verb">POST</badge> [subscriptions/cancel](#post-subscriptions-cancel) | Cancels an active subscription.
-<badge vertical="baseline" type="verb">POST</badge> [subscriptions/switch](#post-subscriptions-switch) | Switch an active subscription’s plan.
-<badge vertical="baseline" type="verb">POST</badge> [subscriptions/reactivate](#post-subscriptions-reactivate) | Reactivates a canceled subscription.
+Methods | Action | Description
+--- | --- | ---
+<badge vertical="baseline" type="verb">POST</badge> | [cart/complete](#post-cart-complete) | Completes an order without payment.
+<badge vertical="baseline" type="verb">GET</badge> | [cart/get-cart](#get-cart-get-cart) | Returns the current cart as JSON.
+<badge vertical="baseline" type="verb">GET/POST</badge> | [cart/load-cart](#get-post-cart-load-cart) | Loads a cookie for the given cart.
+<badge vertical="baseline" type="verb">POST</badge> | [cart/forget-cart](#get-post-cart-forget-cart) | Removes a cookie for the current cart. <Since ver="4.3.0" product="Commerce" repo="craftcms/commerce" feature="Forgetting carts" />
+<badge vertical="baseline" type="verb">POST</badge> | [cart/update-cart](#post-cart-update-cart) | Manage a customer’s current [cart](../orders-carts.md).
+<badge vertical="baseline" type="verb">POST</badge> | [payment-sources/add](#post-payment-sources-add) | Creates a new payment source.
+<badge vertical="baseline" type="verb">POST</badge> | [payment-sources/delete](#post-payment-sources-delete) | Deletes a payment source.
+<badge vertical="baseline" type="verb">GET</badge> | [payments/complete-payment](#get-payments-complete-payment) | Processes customer’s return from an off-site payment.
+<badge vertical="baseline" type="verb">POST</badge> | [payments/pay](#post-payments-pay) | Makes a payment on an order.
+<badge vertical="baseline" type="verb">GET</badge> | [downloads/pdf](#get-downloads-pdf) | Returns an order PDF as a file.
+<badge vertical="baseline" type="verb">POST</badge> | [subscriptions/subscribe](#post-subscriptions-subscribe) | Starts a new subscription.
+<badge vertical="baseline" type="verb">POST</badge> | [subscriptions/cancel](#post-subscriptions-cancel) | Cancels an active subscription.
+<badge vertical="baseline" type="verb">POST</badge> | [subscriptions/switch](#post-subscriptions-switch) | Switch an active subscription’s plan.
+<badge vertical="baseline" type="verb">POST</badge> | [subscriptions/reactivate](#post-subscriptions-reactivate) | Reactivates a canceled subscription.
 
 [Address management](/4.x/addresses.md/#managing-addresses) actions are part of the main Craft documentation. Commerce also allows address information to be set directly on a cart via <badge vertical="baseline" type="verb">POST</badge> [cart/update-cart](#post-cart-update-cart).
 
@@ -208,15 +208,16 @@ State | `application/json`
 
 ### <badge vertical="baseline" type="verb">POST</badge> `payment-sources/add`
 
-Creates a new payment source.
+Creates a new payment source for the current customer.
 
 #### Supported Params
 
 Param | Description
 ----- | -----------
-`*` | All body parameters will be provided directly to the gateway’s [payment form](../payment-form-models.md) model.
+`*` | All body parameters will be provided directly to the gateway’s payment form model.
 `description` | Description for the payment source.
 `gatewayId` | ID of the new payment source’s gateway, which must support payment sources.
+`isPrimaryPaymentSource` | Send a non-empty value to make this the customer’s primary payment source.
 
 #### Response
 
@@ -232,7 +233,7 @@ State | `text/html` | `application/json`
 </span>
 
 ::: warning
-Note that successful requests will return the [payment _source_](../saving-payment-sources.md) that was created; failures will bounce back the [payment _form_](../payment-form-models.md) with errors.
+Note that the models available in success and failure states are different!
 :::
 
 ### <badge vertical="baseline" type="verb">POST</badge> `payment-sources/delete`
@@ -271,7 +272,7 @@ Param | Description
 `email` | Email address of the person responsible for payment, which must match the email address on the order. Required if the order being paid is not the active cart.
 `gatewayId` | The payment gateway ID to be used for payment.
 `number` | The order number payment should be applied to. When ommitted, payment is applied to the current cart.
-`paymentAmount` | Hashed payment amount, expressed in the cart’s `paymentCurrency`, available only if [partial payments](../making-payments.md#checkout-with-partial-payment) are allowed.
+`paymentAmount` | Hashed payment amount, expressed in the cart’s `paymentCurrency`. Available only if [partial payments](../making-payments.md#checkout-with-partial-payment) are allowed.
 `paymentCurrency` | ISO code of a configured [payment currency](../payment-currencies.md) to be used for the payment.
 `paymentSourceId` | The ID for a payment source that should be used for payment.
 `registerUserOnOrderComplete` | Whether the customer should have an account created on order completion.