From fb1dd3d79c215918748b2a3813922805e9f97568 Mon Sep 17 00:00:00 2001 From: August Miller Date: Thu, 4 Jan 2024 15:01:37 -0800 Subject: [PATCH 1/9] Default mutex driver --- docs/4.x/config/app.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/4.x/config/app.md b/docs/4.x/config/app.md index 91514a3ea..9dd2dda59 100644 --- a/docs/4.x/config/app.md +++ b/docs/4.x/config/app.md @@ -452,13 +452,13 @@ If your queue driver supplies its own worker, set the , which means it will work natively in [load-balanced environments](kb:configuring-load-balanced-environments#mutex-locks). -::: tip -A [NullMutex](craft4:craft\mutex\NullMutex) driver is used when Dev Mode is enabled, since mutex drivers aren’t necessary for local development and we’ve seen issues with mutex in some Windows and Linux filesystems. +::: warning +Prior to 4.6, enabling `devMode` would automatically switch from the default `FileMutex` driver to a special `NullMutex` driver to help avoid some virtualization bugs. Now, `NullMutex` is only used when a database connection is not available (i.e. prior to installation). ::: -You can configure a custom mutex driver by configuring the `mutex` component’s nested `$mutex` property: +You can configure a custom mutex driver by overriding the `mutex` component’s nested `$mutex` property: ```php // Use mutex driver provided by yii2-redis @@ -487,7 +487,7 @@ return [ ``` ::: warning -Pay careful attention to the structure, here—we’re only modifying the existing component’s `mutex` _property_ and leaving the rest of its config as-is. +Pay careful attention to the structure of the configuration object: we’re only modifying the existing `mutex` component’s nested _driver_ property and leaving the rest of its config as-is. The mutex _component_ should always be an instance of , ::: ## Modules From 0d6c492aabae17dd7ad42f86e0d08fd13e2872ec Mon Sep 17 00:00:00 2001 From: August Miller Date: Tue, 9 Jan 2024 11:48:07 -0800 Subject: [PATCH 2/9] Support custom templates in `Since` component --- docs/.vuepress/components/Since.vue | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/.vuepress/components/Since.vue b/docs/.vuepress/components/Since.vue index 3d319445d..4fbaa0fea 100644 --- a/docs/.vuepress/components/Since.vue +++ b/docs/.vuepress/components/Since.vue @@ -2,7 +2,7 @@ {{ ver }}+ @@ -32,6 +32,10 @@ export default { type: String, default: 'This feature', }, + description: { + type: String, + default: '{feature} was first available in version {ver} of {product}.', + } }, computed: { releaseUrl() { @@ -42,6 +46,12 @@ export default { return `${GITHUB_URL}/${this.repo}/releases/tag/${this.ver}`; }, + parsedDescription() { + return this.description + .replace('{feature}', this.feature) + .replace('{ver}', this.ver) + .replace('{product}', this.product); + } }, }; From c3eff579d00f785edf7eb655e80ceb0315f4b1cc Mon Sep 17 00:00:00 2001 From: August Miller Date: Tue, 9 Jan 2024 11:48:37 -0800 Subject: [PATCH 3/9] Mutex example updates --- docs/4.x/config/app.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/4.x/config/app.md b/docs/4.x/config/app.md index 9dd2dda59..ac7422082 100644 --- a/docs/4.x/config/app.md +++ b/docs/4.x/config/app.md @@ -452,7 +452,7 @@ If your queue driver supplies its own worker, set the , which means it will work natively in [load-balanced environments](kb:configuring-load-balanced-environments#mutex-locks). +Craft uses the database for mutex (or “mutually exclusive”) locks , which means it will work natively in [load-balanced environments](kb:configuring-load-balanced-environments#mutex-locks). ::: warning Prior to 4.6, enabling `devMode` would automatically switch from the default `FileMutex` driver to a special `NullMutex` driver to help avoid some virtualization bugs. Now, `NullMutex` is only used when a database connection is not available (i.e. prior to installation). @@ -461,21 +461,18 @@ Prior to 4.6, enabling `devMode` would automatically switch from the default `Fi You can configure a custom mutex driver by overriding the `mutex` component’s nested `$mutex` property: ```php -// Use mutex driver provided by yii2-redis return [ 'components' => [ 'mutex' => function() { + $generalConfig = Craft::$app->getConfig()->getGeneral(); + $config = [ - 'class' => craft\mutex\Mutex::class, + 'class' => craft\mutex\File::class, + // Alter just this nested property of the main mutex component: 'mutex' => [ - 'class' => yii\redis\Mutex::class, - // set the max duration to 15 minutes for console requests - 'expire' => Craft::$app->request->isConsoleRequest ? 900 : 30, - 'redis' => [ - 'hostname' => App::env('REDIS_HOSTNAME') ?: 'localhost', - 'port' => 6379, - 'password' => App::env('REDIS_PASSWORD') ?: null, - ], + 'class' => yii\mutex\FileMutex::class, + 'fileMode' => $generalConfig->defaultFileMode, + 'dirMode' => $generalConfig->defaultDirMode, ], ]; @@ -483,11 +480,14 @@ return [ return Craft::createObject($config); }, ], + // ... ]; ``` +The specific properties that you can (or must) use in the configuration object will differ based on the specified mutex class—check the driver’s documentation for instructions. + ::: warning -Pay careful attention to the structure of the configuration object: we’re only modifying the existing `mutex` component’s nested _driver_ property and leaving the rest of its config as-is. The mutex _component_ should always be an instance of , +The primary mutex _component_ should always be an instance of . We’re only modifying the existing `mutex` component’s nested _driver_ property and leaving the rest of its config as-is! ::: ## Modules From 0af2d31beb715a7c2f53aabc716f83340e14f1ad Mon Sep 17 00:00:00 2001 From: August Miller Date: Tue, 9 Jan 2024 13:07:37 -0800 Subject: [PATCH 4/9] Note about changes to search indexing behavior --- docs/4.x/searching.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/4.x/searching.md b/docs/4.x/searching.md index b133cdff7..d3b4245ba 100644 --- a/docs/4.x/searching.md +++ b/docs/4.x/searching.md @@ -273,7 +273,7 @@ You can configure any [custom field](./fields.md) to make its content available ![Searchable Checkbox](./images/searchable-checkbox.png) -Indexes are only updated once an element with the field is saved, though. If you have a large amount of content and users (admin or otherwise) rely heavily on search, consider [resaving the elements](#rebuilding-your-search-indexes) to populate the index. +Indexes are only updated once an element with the field is saved. If you have a large amount of content and users (admin or otherwise) rely heavily on search, consider [resaving the elements](#rebuilding-your-search-indexes) to populate the index. ::: tip For Matrix fields, the top-level **Use this field’s values as search keywords** setting determines whether _any_ sub-fields will factor into results for the parent—individual fields must also opt-in to indexing for any keywords to be bubbled up. @@ -281,6 +281,12 @@ For Matrix fields, the top-level **Use this field’s values as search keywords* For relational fields like [Assets](./assets-fields.md), [Categories](./categories-fields.md), and [Entries](./entries-fields.md), the setting determines whether titles of related elements should factor into search results. ::: +## Indexing Criteria + +Any time an indexable attribute or field on an element is updated (as indicated by Craft’s change-tracking feature, which powers drafts and revisions), an “Updating search indexes” job is pushed into the queue. Prior versions generate an indexing job whenever an element with _any_ searchable attributes or fields is saved, regardless of whether or not those specific attributes changed. + +The [eligible properties](#searching-for-specific-element-attributes) differ for each element type, the field layout a given element uses, and which of the underlying fields are flagged as searchable. + ## Rebuilding Your Search Indexes Craft does its best to keep its search indexes as up-to-date as possible, but there are a couple things that might render portions of them inaccurate. If you suspect your search indexes are out of date, you can have Craft rebuild them by bulk-resaving entries with the [`resave/entries`](console-commands.md#resave) command and including the `--update-search-index` flag: From 6c2d9783cd9a752dc552c0e23a381b1c2f7d0a22 Mon Sep 17 00:00:00 2001 From: August Miller Date: Tue, 9 Jan 2024 13:49:40 -0800 Subject: [PATCH 5/9] Disabling utilities --- docs/4.x/control-panel.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/4.x/control-panel.md b/docs/4.x/control-panel.md index e1f51a802..1e491b086 100644 --- a/docs/4.x/control-panel.md +++ b/docs/4.x/control-panel.md @@ -118,6 +118,10 @@ Access to utilities should be granted only to trusted users, especially the inno Keep in mind that any user marked as an “Admin” implicitly has access to _all_ utilities. ::: +#### Disabling Utilities + +You can disable a utility for all users with the [`disabledUtilities` config setting](config4:disabledUtilities). Refer to the subclasses’ `id()` method for the handles of specific utilities—including those provided by plugins. + ### Settings The **Settings** screen is where you’ll configure the system and design your content model. Settings complement [configuration](./config/README.md) are typically stored in [Project Config](./project-config.md) so that you can easily deploy them to other environments. From 2a2fc9f2435e2d2157e2881c7ab66ea7da4f1aa4 Mon Sep 17 00:00:00 2001 From: August Miller Date: Tue, 9 Jan 2024 14:16:41 -0800 Subject: [PATCH 6/9] Phrasing --- docs/4.x/control-panel.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/4.x/control-panel.md b/docs/4.x/control-panel.md index 1e491b086..a8ebf66fe 100644 --- a/docs/4.x/control-panel.md +++ b/docs/4.x/control-panel.md @@ -120,7 +120,7 @@ Keep in mind that any user marked as an “Admin” implicitly has access to _al #### Disabling Utilities -You can disable a utility for all users with the [`disabledUtilities` config setting](config4:disabledUtilities). Refer to the subclasses’ `id()` method for the handles of specific utilities—including those provided by plugins. +You can disable a utility for all users with the [`disabledUtilities` config setting](config4:disabledUtilities). Refer to each [utility class](repo:craftcms/cms)’s `id()` method for their handles—including those provided by plugins. ### Settings From dfb41cf8b22db39e9eafcab4d1f1548234332be9 Mon Sep 17 00:00:00 2001 From: August Miller Date: Tue, 9 Jan 2024 14:17:16 -0800 Subject: [PATCH 7/9] Complete source URL --- docs/4.x/control-panel.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/4.x/control-panel.md b/docs/4.x/control-panel.md index a8ebf66fe..9914399ef 100644 --- a/docs/4.x/control-panel.md +++ b/docs/4.x/control-panel.md @@ -120,7 +120,7 @@ Keep in mind that any user marked as an “Admin” implicitly has access to _al #### Disabling Utilities -You can disable a utility for all users with the [`disabledUtilities` config setting](config4:disabledUtilities). Refer to each [utility class](repo:craftcms/cms)’s `id()` method for their handles—including those provided by plugins. +You can disable a utility for all users with the [`disabledUtilities` config setting](config4:disabledUtilities). Refer to each [utility class](repo:craftcms/cms/tree/main/src/utilities)’s `id()` method for their handles—including those provided by plugins. ### Settings From fb0a135a7c78b2e3f1ee74df5129c237db08dadf Mon Sep 17 00:00:00 2001 From: August Miller Date: Tue, 9 Jan 2024 14:24:14 -0800 Subject: [PATCH 8/9] More notes on utility permissions --- docs/4.x/extend/utilities.md | 2 +- docs/4.x/user-management.md | 3 +-- docs/4.x/users.md | 2 +- 3 files changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/4.x/extend/utilities.md b/docs/4.x/extend/utilities.md index 05b01b5bb..1c2bf860a 100644 --- a/docs/4.x/extend/utilities.md +++ b/docs/4.x/extend/utilities.md @@ -64,7 +64,7 @@ You may also implement static `toolbarHtml()` and `footerHtml()` methods to inje Each utility automatically gets its own [permission](user-permissions.md). Craft checks these permissions before displaying a utility in the sidebar, and when the utility’s URL is requested. -However, those permissions do _not_ have any bearing on what functionality might be accessible to a user via other means. For example, if your utility displayed a form to authorized users and allowed them to download a specialized report of some kind, the [controller](controllers.md) or action that ultimately generates the report must also check the appropriate permissions. +However, those permissions do _not_ have any bearing on what functionality might be accessible to a user via other means. For example, if your utility displayed a form to authorized users and allowed them to download a specialized report of some kind, the [controller](controllers.md) or action that ultimately generates the report must also check the appropriate permissions. In general, those permissions should be discrete: an administrator would grant users access to the utility _and_ a _Modify Widgets_ permission that your plugin explicitly defines (and checks in the appropriate controller action). ## Registering your Utility diff --git a/docs/4.x/user-management.md b/docs/4.x/user-management.md index 1394b9282..d1d15fa32 100644 --- a/docs/4.x/user-management.md +++ b/docs/4.x/user-management.md @@ -97,11 +97,10 @@ The permissions Craft comes with are: | ↳  Find and Replace | `utility:find-replace` | ↳  Migrations | `utility:migrations` -You may not see all of these options, initially—only ones that are relevant based on the current content schema will be displayed. For example, everything under _View categories_ will be hidden until you have at least one category group. +You may not see all of these options, initially—only ones that are relevant based on the current content schema will be displayed. For example, everything under _View categories_ will be hidden until you have at least one [category group](categories.md#category-groups). Plugins may register their own permissions, which can appear in a top-level group, under _Access the control panel_, or within _Utilities_. - ::: tip See the _Extending Craft_ [User Permissions](extend/user-permissions.md) page to learn how to register custom permissions from your module or plugin. ::: diff --git a/docs/4.x/users.md b/docs/4.x/users.md index d42fd1faa..a77827d40 100644 --- a/docs/4.x/users.md +++ b/docs/4.x/users.md @@ -30,7 +30,7 @@ You can’t create an inactive user from the control panel, but you can deactiva ### Addresses -Users each have an address book. [Addresses](./addresses.md) can be managed on behalf of a User via the control panel, or [by the user themselves](./dev/controller-actions.md#post-users-save-address). +Users each have an address book. [Addresses](./addresses.md) can be managed on behalf of a user via the control panel, or [by the user themselves](./dev/controller-actions.md#post-users-save-address). ## Querying Users From 62f15e76bf7d580027a8adfd3ca9b31b00b2b9c5 Mon Sep 17 00:00:00 2001 From: August Miller Date: Tue, 9 Jan 2024 14:25:23 -0800 Subject: [PATCH 9/9] UI label emphasis --- docs/4.x/user-management.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/4.x/user-management.md b/docs/4.x/user-management.md index d1d15fa32..87589788f 100644 --- a/docs/4.x/user-management.md +++ b/docs/4.x/user-management.md @@ -25,9 +25,9 @@ Considering how much damage an admin can do, we strongly advise caution when cre If you have Craft Pro, you can create User Groups to help organize your site’s user accounts, as well as batch-set permissions on them. -To create a new User Group, go to **Settings** → **Users** and press **+ New user group**. You can give your group a Name and Handle, plus any permissions you want every user within the group to have. +To create a new User Group, go to **Settings** → **Users** and press **+ New user group**. You can give your group a **Name** and **Handle**, plus any **Permissions** you want every user within the group to have. -After you create your groups, you can assign users to groups by going into their account settings and choosing the Permissions tab. +After you create your groups, you can assign users to groups by going into their account settings and choosing the **Permissions** tab. ## Permissions