diff --git a/docs/.artifacts/cms/3.x/assets.md b/docs/.artifacts/cms/3.x/assets.md index 9200e3487..81ebfff62 100644 --- a/docs/.artifacts/cms/3.x/assets.md +++ b/docs/.artifacts/cms/3.x/assets.md @@ -8,7 +8,6 @@ | Param | Description | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- -| [addOrderBy](#addorderby) | Adds additional ORDER BY columns to the query. | [afterPopulate](#afterpopulate) | Performs any post-population processing on elements. | [andRelatedTo](#andrelatedto) | Narrows the query results to only assets that are related to certain other elements. | [anyStatus](#anystatus) | Removes element filters based on their statuses. @@ -18,7 +17,6 @@ | [dateCreated](#datecreated) | Narrows the query results based on the assets’ creation dates. | [dateModified](#datemodified) | Narrows the query results based on the assets’ files’ last-modified dates. | [dateUpdated](#dateupdated) | Narrows the query results based on the assets’ last-updated dates. -| [fields](#fields) | Returns the list of fields that should be returned by default by [toArray()](https://www.yiiframework.com/doc/api/2.0/yii-base-arrayabletrait#toArray()-detail) when no specific fields are specified. | [filename](#filename) | Narrows the query results based on the assets’ filenames. | [fixedOrder](#fixedorder) | Causes the query results to be returned in the order specified by [id](#id). | [folderId](#folderid) | Narrows the query results based on the folders the assets belong to, per the folders’ IDs. @@ -54,19 +52,6 @@ -#### `addOrderBy` - -Adds additional ORDER BY columns to the query. - - - - - - - - - - #### `afterPopulate` Performs any post-population processing on elements. @@ -292,45 +277,6 @@ $assets = \craft\elements\Asset::find() ::: -#### `fields` - -Returns the list of fields that should be returned by default by [toArray()](https://www.yiiframework.com/doc/api/2.0/yii-base-arrayabletrait#toArray()-detail) when no specific fields are specified. - -A field is a named element in the returned array by [toArray()](https://www.yiiframework.com/doc/api/2.0/yii-base-arrayabletrait#toArray()-detail). -This method should return an array of field names or field definitions. -If the former, the field name will be treated as an object property name whose value will be used -as the field value. If the latter, the array key should be the field name while the array value should be -the corresponding field definition which can be either an object property name or a PHP callable -returning the corresponding field value. The signature of the callable should be: - -```php -function ($model, $field) { - // return field value -} -``` - -For example, the following code declares four fields: - -- `email`: the field name is the same as the property name `email`; -- `firstName` and `lastName`: the field names are `firstName` and `lastName`, and their - values are obtained from the `first_name` and `last_name` properties; -- `fullName`: the field name is `fullName`. Its value is obtained by concatenating `first_name` - and `last_name`. - -```php -return [ - 'email', - 'firstName' => 'first_name', - 'lastName' => 'last_name', - 'fullName' => function ($model) { - return $model->first_name . ' ' . $model->last_name; - }, -]; -``` - - - - #### `filename` Narrows the query results based on the assets’ filenames. diff --git a/docs/.artifacts/cms/3.x/categories.md b/docs/.artifacts/cms/3.x/categories.md index f334d1576..e0c4ee1ea 100644 --- a/docs/.artifacts/cms/3.x/categories.md +++ b/docs/.artifacts/cms/3.x/categories.md @@ -8,7 +8,6 @@ | Param | Description | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ -| [addOrderBy](#addorderby) | Adds additional ORDER BY columns to the query. | [afterPopulate](#afterpopulate) | Performs any post-population processing on elements. | [ancestorDist](#ancestordist) | Narrows the query results to only categories that are up to a certain distance away from the category specified by [ancestorOf](#ancestorof). | [ancestorOf](#ancestorof) | Narrows the query results to only categories that are ancestors of another category in its structure. @@ -21,7 +20,6 @@ | [dateUpdated](#dateupdated) | Narrows the query results based on the categories’ last-updated dates. | [descendantDist](#descendantdist) | Narrows the query results to only categories that are up to a certain distance away from the category specified by [descendantOf](#descendantof). | [descendantOf](#descendantof) | Narrows the query results to only categories that are descendants of another category in its structure. -| [fields](#fields) | Returns the list of fields that should be returned by default by [toArray()](https://www.yiiframework.com/doc/api/2.0/yii-base-arrayabletrait#toArray()-detail) when no specific fields are specified. | [fixedOrder](#fixedorder) | Causes the query results to be returned in the order specified by [id](#id). | [group](#group) | Narrows the query results based on the category groups the categories belong to. | [groupId](#groupid) | Narrows the query results based on the category groups the categories belong to, per the groups’ IDs. @@ -58,19 +56,6 @@ -#### `addOrderBy` - -Adds additional ORDER BY columns to the query. - - - - - - - - - - #### `afterPopulate` Performs any post-population processing on elements. @@ -391,45 +376,6 @@ This can be combined with [descendantDist](#descendantdist) if you want to limit ::: -#### `fields` - -Returns the list of fields that should be returned by default by [toArray()](https://www.yiiframework.com/doc/api/2.0/yii-base-arrayabletrait#toArray()-detail) when no specific fields are specified. - -A field is a named element in the returned array by [toArray()](https://www.yiiframework.com/doc/api/2.0/yii-base-arrayabletrait#toArray()-detail). -This method should return an array of field names or field definitions. -If the former, the field name will be treated as an object property name whose value will be used -as the field value. If the latter, the array key should be the field name while the array value should be -the corresponding field definition which can be either an object property name or a PHP callable -returning the corresponding field value. The signature of the callable should be: - -```php -function ($model, $field) { - // return field value -} -``` - -For example, the following code declares four fields: - -- `email`: the field name is the same as the property name `email`; -- `firstName` and `lastName`: the field names are `firstName` and `lastName`, and their - values are obtained from the `first_name` and `last_name` properties; -- `fullName`: the field name is `fullName`. Its value is obtained by concatenating `first_name` - and `last_name`. - -```php -return [ - 'email', - 'firstName' => 'first_name', - 'lastName' => 'last_name', - 'fullName' => function ($model) { - return $model->first_name . ' ' . $model->last_name; - }, -]; -``` - - - - #### `fixedOrder` Causes the query results to be returned in the order specified by [id](#id). diff --git a/docs/.artifacts/cms/3.x/config-db.md b/docs/.artifacts/cms/3.x/config-db.md index 3d78d8065..c8b52da1e 100644 --- a/docs/.artifacts/cms/3.x/config-db.md +++ b/docs/.artifacts/cms/3.x/config-db.md @@ -19,6 +19,18 @@ Defined by An array of key => value pairs of PDO attributes to pass into the PDO constructor. +For example, when using the [MySQL PDO driver](https://php.net/manual/en/ref.pdo-mysql.php), if you wanted to enable a SSL database connection +(assuming [SSL is enabled in MySQL](https://dev.mysql.com/doc/mysql-secure-deployment-guide/5.7/en/secure-deployment-secure-connections.html) and `'user'` can connect via SSL, +you’d set these: + +```php +[ + PDO::MYSQL_ATTR_SSL_KEY => '/path/to/my/client-key.pem', + PDO::MYSQL_ATTR_SSL_CERT => '/path/to/my/client-cert.pem', + PDO::MYSQL_ATTR_SSL_CA => '/path/to/my/ca-cert.pem', +], +``` + ### `charset` @@ -38,6 +50,14 @@ Defined by The charset to use when creating tables. +::: tip +You can change the character set and collation across all existing database tables using this terminal command: + +```bash +> php craft db/convert-charset +``` +::: + ### `collation` @@ -60,6 +80,21 @@ Since The collation to use when creating tables. +This is only used by MySQL. If null, the [charset’s](https://docs.craftcms.com/api/v3/craft-config-dbconfig.html#property-charset) default collation will be used. + +| Charset | Default collation | +| --------- | -------------------- | +| `utf8` | `utf8_general_ci` | +| `utf8mb4` | `utf8mb4_0900_ai_ci` | + +::: tip +You can change the character set and collation across all existing database tables using this terminal command: + +```bash +> php craft db/convert-charset +``` +::: + ### `database` @@ -117,6 +152,12 @@ Defined by The Data Source Name (“DSN”) that tells Craft how to connect to the database. +DSNs should begin with a driver prefix (`mysql:` or `pgsql:`), followed by driver-specific parameters. +For example, `mysql:host=127.0.0.1;port=3306;dbname=acme_corp`. + +- MySQL parameters: +- PostgreSQL parameters: + ### `password` @@ -174,6 +215,11 @@ Defined by The schema that Postgres is configured to use by default (PostgreSQL only). +::: tip +To force Craft to use the specified schema regardless of PostgreSQL’s `search_path` setting, you must enable +the [setSchemaOnConnect](https://docs.craftcms.com/api/v3/craft-config-dbconfig.html#property-setschemaonconnect) setting. +::: + ### `server` @@ -215,6 +261,11 @@ Since Whether the [schema](https://docs.craftcms.com/api/v3/craft-config-dbconfig.html#property-schema) should be explicitly used for database queries (PostgreSQL only). +::: warning +This will cause an extra `SET search_path` SQL query to be executed per database connection. Ideally, +PostgreSQL’s `search_path` setting should be configured to prioritize the desired schema. +::: + ### `tablePrefix` @@ -274,6 +325,8 @@ Defined by The database connection URL, if one was provided by your hosting environment. +If this is set, the values for [driver](https://docs.craftcms.com/api/v3/craft-config-dbconfig.html#property-driver), [user](https://docs.craftcms.com/api/v3/craft-config-dbconfig.html#property-user), [database](https://docs.craftcms.com/api/v3/craft-config-dbconfig.html#property-database), [server](https://docs.craftcms.com/api/v3/craft-config-dbconfig.html#property-server), [port](https://docs.craftcms.com/api/v3/craft-config-dbconfig.html#property-port), and [database](https://docs.craftcms.com/api/v3/craft-config-dbconfig.html#property-database) will be extracted from it. + ### `useUnbufferedConnections` @@ -296,6 +349,11 @@ Since Whether batched queries should be executed on a separate, unbuffered database connection. +This setting only applies to MySQL. It can be enabled when working with high volume content, to prevent +PHP from running out of memory when querying too much data at once. (See + for an explanation +of MySQL’s batch query limitations.) + ### `user` diff --git a/docs/.artifacts/cms/3.x/config-general.md b/docs/.artifacts/cms/3.x/config-general.md index fd8533dd8..51e594f6c 100644 --- a/docs/.artifacts/cms/3.x/config-general.md +++ b/docs/.artifacts/cms/3.x/config-general.md @@ -28,6 +28,12 @@ Since The default user accessibility preferences that should be applied to users that haven’t saved their preferences yet. +The array can contain the following keys: + +- `alwaysShowFocusRings` - Whether focus rings should always be shown when an element has focus +- `useShapes` – Whether shapes should be used to represent statuses +- `underlineLinks` – Whether links should be underlined + ### `allowAdminChanges` @@ -50,6 +56,16 @@ Since Whether admins should be allowed to make administrative changes to the system. +When this is disabled, the Settings section will be hidden, the Craft edition and Craft/plugin versions will be locked, +and the project config and Plugin Store will become read-only—though Craft and plugin licenses may still be purchased. + +It’s best to disable this in production environments with a deployment workflow that runs `composer install` and +[propagates project config updates](../project-config.md#propagating-changes) on deploy. + +::: warning +Don’t disable this setting until **all** environments have been updated to Craft 3.1.0 or later. +::: + ### `allowSimilarTags` @@ -88,6 +104,8 @@ Defined by Whether Craft should allow system and plugin updates in the control panel, and plugin installation from the Plugin Store. +This setting will automatically be disabled if is disabled. + ### `autoLoginAfterAccountActivation` @@ -129,6 +147,8 @@ Since Whether drafts should be saved automatically as they are edited. +Note that drafts *will* be autosaved while Live Preview is open, regardless of this setting. + ### `backupOnUpdate` @@ -167,6 +187,10 @@ Defined by The default length of time Craft will store data, RSS feed, and template caches. +If set to `0`, data and RSS feed caches will be stored indefinitely; template caches will be stored for one year. + +See [craft\helpers\ConfigHelper::durationInSeconds()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-durationinseconds) for a list of supported value types. + ### `cpHeadTags` @@ -189,6 +213,23 @@ Since List of additional HTML tags that should be included in the `` of control panel pages. +Each tag can be specified as an array of the tag name and its attributes. + +For example, you can give the control panel a custom favicon (etc.) like this: + +```php +'cpHeadTags' => [ + // Traditional favicon + ['link', ['rel' => 'icon', 'href' => '/icons/favicon.ico']], + // Scalable favicon for browsers that support them + ['link', ['rel' => 'icon', 'type' => 'image/svg+xml', 'sizes' => 'any', 'href' => '/icons/favicon.svg']], + // Touch icon for mobile devices + ['link', ['rel' => 'apple-touch-icon', 'sizes' => '180x180', 'href' => '/icons/touch-icon.svg']], + // Pinned tab icon for Safari + ['link', ['rel' => 'mask-icon', 'href' => '/icons/mask-icon.svg', 'color' => '#663399']], +], +``` + ### `defaultCpLanguage` @@ -231,6 +272,8 @@ Since The default locale the control panel should use for date/number formatting, for users who haven’t set a preferred language or formatting locale. +If this is `null`, the config setting will determine which locale is used for date/number formatting by default. + ### `defaultDirMode` @@ -250,6 +293,8 @@ Defined by The default permission to be set for newly-generated directories. +If set to `null`, the permission will be determined by the current environment. + ### `defaultFileMode` @@ -269,6 +314,8 @@ Defined by The default permission to be set for newly-generated files. +If set to `null`, the permission will be determined by the current environment. + ### `defaultSearchTermOptions` @@ -288,6 +335,14 @@ Defined by The default options that should be applied to each search term. +Options include: + +- `attribute` – The attribute that the term should apply to (e.g. `'title'`), if any. (`null` by default) +- `exact` – Whether the term must be an exact match (only applies if `attribute` is set). (`false` by default) +- `exclude` – Whether search results should *exclude* records with this term. (`false` by default) +- `subLeft` – Whether to include keywords that contain the term, with additional characters before it. (`false` by default) +- `subRight` – Whether to include keywords that contain the term, with additional characters after it. (`true` by default) + ### `defaultTemplateExtensions` @@ -329,6 +384,16 @@ Defined by The default day new users should have set as their Week Start Day. +This should be set to one of the following integers: + +- `0` – Sunday +- `1` – Monday +- `2` – Tuesday +- `3` – Wednesday +- `4` – Thursday +- `5` – Friday +- `6` – Saturday + ### `devMode` @@ -370,6 +435,25 @@ Since Array of plugin handles that should be disabled, regardless of what the project config says. +```php +'dev' => [ + 'disabledPlugins' => ['webhooks'], +], +``` + +This can also be set to `'*'` to disable **all** plugins. + +```php +'dev' => [ + 'disabledPlugins' => '*', +], +``` + +::: warning +This should not be set on a per-environment basis, as it could result in plugin schema version mismatches +between environments, which will prevent project config changes from getting applied. +::: + ### `disallowRobots` @@ -393,6 +477,10 @@ Since Whether front end requests should respond with `X-Robots-Tag: none` HTTP headers, indicating that pages should not be indexed, and links on the page should not be followed, by web crawlers. +::: tip +This should be set to `true` for development and staging environments. +::: + ### `enableTemplateCaching` @@ -431,6 +519,8 @@ Defined by The prefix that should be prepended to HTTP error status codes when determining the path to look for an error’s template. +If set to `'_'` your site’s 404 template would live at `templates/_404.html`, for example. + ### `extraAllowedFileExtensions` @@ -472,6 +562,9 @@ Since List of extra locale IDs that the application should support, and users should be able to select as their Preferred Language. +Only use this setting if your server has the Intl PHP extension, or if you’ve saved the corresponding +[locale data](https://github.com/craftcms/locales) into your `config/locales/` folder. + ### `handleCasing` @@ -494,6 +587,12 @@ Since The casing to use for autogenerated component handles. +This can be set to one of the following: + +- `camel` – for camelCase +- `pascal` – for PascalCase (aka UpperCamelCase) +- `snake` – for snake_case + ### `headlessMode` @@ -516,6 +615,21 @@ Since Whether the system should run in Headless Mode, which optimizes the system and control panel for headless CMS implementations. +When this is enabled, the following changes will take place: + +- Template settings for sections and category groups will be hidden. +- Template route management will be hidden. +- Front-end routing will skip checks for element and template requests. +- Front-end responses will be JSON-formatted rather than HTML by default. +- Twig will be configured to escape unsafe strings for JavaScript/JSON rather than HTML by default for front-end requests. +- The , , , and settings will be ignored. + +::: tip +With Headless Mode enabled, users may only set passwords and verify email addresses via the control panel. Be sure to grant “Access the control +panel” permission to all content editors and administrators. You’ll also need to set the config setting if the control +panel is located on a different domain than your front end. +::: + ### `httpProxy` @@ -538,6 +652,8 @@ Since The proxy server that should be used for outgoing HTTP requests. +This can be set to a URL (`http://localhost`) or a URL plus a port (`http://localhost:8125`). + ### `indexTemplateFilenames` @@ -579,6 +695,10 @@ Defined by List of headers where proxies store the real client IP. +See [yii\web\Request::$ipHeaders](https://www.yiiframework.com/doc/api/2.0/yii-web-request#$ipHeaders-detail) for more details. + +If not set, the default [craft\web\Request::$ipHeaders](https://docs.craftcms.com/api/v3/craft-web-request.html#property-ipheaders) value will be used. + ### `isSystemLive` @@ -618,6 +738,10 @@ Defined by Whether non-ASCII characters in auto-generated slugs should be converted to ASCII (i.e. ñ → n). +::: tip +This only affects the JavaScript auto-generated slugs. Non-ASCII characters can still be used in slugs if entered manually. +::: + ### `maxBackups` @@ -660,6 +784,8 @@ Since The maximum number of revisions that should be stored for each element. +Set to `0` if you want to store an unlimited number of revisions. + ### `maxSlugIncrement` @@ -721,6 +847,8 @@ Defined by The maximum amount of memory Craft will try to reserve during memory-intensive operations such as zipping, unzipping and updating. Defaults to an empty string, which means it will use as much memory as it can. +See for a list of acceptable values. + ### `previewIframeResizerOptions` @@ -743,6 +871,12 @@ Since Custom [iFrame Resizer options](http://davidjbradshaw.github.io/iframe-resizer/#options) that should be used for preview iframes. +```php +'previewIframeResizerOptions' => [ + 'autoResize' => false, +], +``` + ### `privateTemplateTrigger` @@ -763,6 +897,8 @@ Defined by The template path segment prefix that should be used to identify “private” templates, which are templates that are not directly accessible via a matching URL. +Set to an empty value to disable public template routing. + ### `runQueueAutomatically` @@ -782,6 +918,19 @@ Defined by Whether Craft should run pending queue jobs automatically when someone visits the control panel. +If disabled, an alternate queue worker *must* be set up separately, either as an +[always-running daemon](https://github.com/yiisoft/yii2-queue/blob/master/docs/guide/worker.md), or a cron job that runs the +`queue/run` command every minute: + +```cron +** * * * * /path/to/project/craft queue/run +``` + +::: tip +This setting should be disabled for servers running Win32, or with Apache’s mod_deflate/mod_gzip installed, +where PHP’s [flush()](https://php.net/manual/en/function.flush.php) method won’t work. +::: + ### `sameSiteCookieValue` @@ -804,6 +953,12 @@ Since The [SameSite](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite) value that should be set on Craft cookies, if any. +This can be set to `'None'`, `'Lax'`, `'Strict'`, or `null`. + +::: tip +This setting requires PHP 7.3 or later. +::: + ### `sendContentLengthHeader` @@ -885,6 +1040,9 @@ Defined by Configures Craft to send all system emails to either a single email address or an array of email addresses for testing purposes. +By default, the recipient name(s) will be “Test Recipient”, but you can customize that by setting the value with the format +`['me@domain.tld' => 'Name']`. + ### `timezone` @@ -904,6 +1062,8 @@ Defined by The timezone of the site. If set, it will take precedence over the Timezone setting in Settings → General. +This can be set to one of PHP’s [supported timezones](https://php.net/manual/en/timezones.php). + ### `translationDebugOutput` @@ -943,6 +1103,12 @@ Defined by Whether Craft should set users’ usernames to their email addresses, rather than let them set their username separately. +If you enable this setting after user accounts already exist, run this terminal command to update existing usernames: + +```bash +php craft utils/update-usernames +``` + ### `useFileLocks` @@ -962,6 +1128,10 @@ Defined by Whether to grab an exclusive lock on a file when writing to it by using the `LOCK_EX` flag. +Some file systems, such as NFS, do not support exclusive file locking. + +If not set to `true` or `false`, Craft will try to detect if the underlying file system supports exclusive file locking and cache the results. + ### `useIframeResizer` @@ -984,6 +1154,21 @@ Since Whether [iFrame Resizer options](http://davidjbradshaw.github.io/iframe-resizer/#options) should be used for Live Preview. +Using iFrame Resizer makes it possible for Craft to retain the preview’s scroll position between page loads, for cross-origin web pages. + +It works by setting the height of the iframe to match the height of the inner web page, and the iframe’s container will be scrolled rather +than the iframe document itself. This can lead to some unexpected CSS issues, however, because the previewed viewport height will be taller +than the visible portion of the iframe. + +If you have a [decoupled front end](https://craftcms.com/docs/3.x/entries.html#previewing-decoupled-front-ends), you will need to include +[iframeResizer.contentWindow.min.js](https://raw.github.com/davidjbradshaw/iframe-resizer/master/js/iframeResizer.contentWindow.min.js) on your +page as well for this to work. You can conditionally include it for only Live Preview requests by checking if the requested URL contains a +`x-craft-live-preview` query string parameter. + +::: tip +You can customize the behavior of iFrame Resizer via the config setting. +::: + ## Environment @@ -1024,6 +1209,21 @@ Defined by The shell command that Craft should execute to create a database backup. +When set to `null` (default), Craft will run `mysqldump` or `pg_dump`, provided that those libraries are in the `$PATH` variable +for the system user running the web server. + +You may provide your own command, which can include several tokens Craft will substitute at runtime: + +- `{file}` - the target backup file path +- `{port}` - the current database port +- `{server}` - the current database hostname +- `{user}` - user that was used to connect to the database +- `{password}` - password for the specified `{user}` +- `{database}` - the current database name +- `{schema}` - the current database schema (if any) + +This can also be set to `false` to disable database backups completely. + ### `defaultCookieDomain` @@ -1102,6 +1302,19 @@ Defined by The shell command Craft should execute to restore a database backup. +By default Craft will run `mysql` or `psql`, provided those libraries are in the `$PATH` variable for the user the web server is running as. + +There are several tokens you can use that Craft will swap out at runtime: + +- `{path}` - the backup file path +- `{port}` - the current database port +- `{server}` - the current database hostname +- `{user}` - the user to connect to the database +- `{database}` - the current database name +- `{schema}` - the current database schema (if any) + +This can also be set to `false` to disable database restores completely. + ## Routing @@ -1142,6 +1355,8 @@ Defined by The URI that users without access to the control panel should be redirected to after activating their account. +See [craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) for a list of supported value types. + ### `addTrailingSlashesToUrls` @@ -1199,6 +1414,12 @@ Defined by The base URL Craft should use when generating control panel URLs. +It will be determined automatically if left blank. + +::: tip +The base control panel URL should **not** include the [control panel trigger word](config3:cpTrigger) (e.g. `/admin`). +::: + ### `cpTrigger` @@ -1219,6 +1440,19 @@ Defined by The URI segment Craft should look for when determining if the current request should route to the control panel rather than the front-end website. +This can be set to `null` if you have a dedicated hostname for the control panel (e.g. `cms.my-project.tld`), or you are running Craft in +[Headless Mode](config3:headlessMode). If you do that, you will need to ensure that the control panel is being served from its own web root +directory on your server, with an `index.php` file that defines the `CRAFT_CP` PHP constant. + +```php +define('CRAFT_CP', true); +``` + +Alternatively, you can set the config setting, but then you will run the risk of losing access to portions of your +control panel due to URI conflicts with actual folders/files in your main web root. + +(For example, if you have an `assets/` folder, that would conflict with the `/assets` page in the control panel.) + ### `invalidUserTokenPath` @@ -1239,6 +1473,8 @@ Defined by The URI Craft should redirect to when user token validation fails. A token is used on things like setting and resetting user account passwords. Note that this only affects front-end site requests. +See [craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) for a list of supported value types. + ### `loginPath` @@ -1258,6 +1494,12 @@ Defined by The URI Craft should use for user login on the front end. +This can be set to `false` to disable front-end login. + +Note that this config setting is ignored when is enabled. + +See [craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) for a list of supported value types. + ### `logoutPath` @@ -1277,6 +1519,12 @@ Defined by The URI Craft should use for user logout on the front end. +This can be set to `false` to disable front-end logout. + +Note that this config setting is ignored when is enabled. + +See [craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) for a list of supported value types. + ### `omitScriptNameInUrls` @@ -1296,6 +1544,22 @@ Defined by Whether generated URLs should omit `index.php` (e.g. `http://my-project.tld/path` instead of `http://my-project.tld/index.php/path`) +This can only be possible if your server is configured to redirect would-be 404s to `index.php`, for example, with the redirect found +in the `.htaccess` file that came with Craft: + +``` +RewriteEngine On +RewriteCond %{REQUEST_FILENAME} !-f +RewriteCond %{REQUEST_FILENAME} !-d +RewriteRule (.+) /index.php?p= [QSA,L] +``` + +::: tip +Even when this is set to `true`, the script name could still be included in some action URLs. +If you want to ensure that `index.php` is fully omitted from **all** generated URLs, set the +config setting to `null`. +::: + ### `pageTrigger` @@ -1316,6 +1580,18 @@ Defined by The string preceding a number which Craft will look for when determining if the current request is for a particular page in a paginated list of pages. +Example Value | Example URI +------------- | ----------- +`p` | `/news/p5` +`page` | `/news/page5` +`page/` | `/news/page/5` +`?page` | `/news?page=5` + +::: tip +If you want to set this to `?p` (e.g. `/news?p=5`), you’ll also need to change your setting which defaults to `p`. +If your server is running Apache, you’ll need to update the redirect code in your `.htaccess` file to match your new `pathParam` value. +::: + ### `pathParam` @@ -1335,6 +1611,13 @@ Defined by The query string param that Craft will check when determining the request’s path. +This can be set to `null` if your web server is capable of directing traffic to `index.php` without a query string param. +If you’re using Apache, that means you’ll need to change the `RewriteRule` line in your `.htaccess` file to: + +``` +RewriteRule (.+) index.php [QSA,L] +``` + ### `postCpLoginRedirect` @@ -1354,6 +1637,11 @@ Defined by The path users should be redirected to after logging into the control panel. +This setting will also come into effect if a user visits the control panel’s login page (`/admin/login`) or the control panel’s +root URL (`/admin`) when they are already logged in. + +See [craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) for a list of supported value types. + ### `postLoginRedirect` @@ -1373,6 +1661,11 @@ Defined by The path users should be redirected to after logging in from the front-end site. +This setting will also come into effect if the user visits the login page (as specified by the config setting) when +they are already logged in. + +See [craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) for a list of supported value types. + ### `postLogoutRedirect` @@ -1392,6 +1685,8 @@ Defined by The path that users should be redirected to after logging out from the front-end site. +See [craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) for a list of supported value types. + ### `setPasswordPath` @@ -1411,6 +1706,14 @@ Defined by The URI or URL that Craft should use for Set Password forms on the front end. +Note that this config setting is ignored when is enabled, unless it’s set to an absolute URL. + +See [craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) for a list of supported value types. + +::: tip +You might also want to set in case a user clicks on an expired password reset link. +::: + ### `setPasswordRequestPath` @@ -1433,6 +1736,15 @@ Since The URI to the page where users can request to change their password. +See [craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) for a list of supported value types. + +If this is set, Craft will redirect [.well-known/change-password requests](https://w3c.github.io/webappsec-change-password-url/) to this URI. + +::: tip +You’ll also need to set [setPasswordPath](config3:setPasswordPath), which determines the URI and template path for the Set Password form +where the user resets their password after following the link in the Password Reset email. +::: + ### `setPasswordSuccessPath` @@ -1452,6 +1764,8 @@ Defined by The URI Craft should redirect users to after setting their password from the front end. +See [craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) for a list of supported value types. + ### `siteToken` @@ -1512,6 +1826,8 @@ Defined by Whether Craft should specify the path using `PATH_INFO` or as a query string parameter when generating URLs. +Note that this setting only takes effect if is set to `false`. + ### `useSslOnTokenizedUrls` @@ -1533,6 +1849,8 @@ Determines what protocol/schema Craft will use when generating tokenized URLs. I current site’s base URL and the protocol of the current request and if either of them are HTTPS will use `https` in the tokenized URL. If not, will use `http`. +If set to `false`, Craft will always use `http`. If set to `true`, then, Craft will always use `https`. + ### `verifyEmailPath` @@ -1555,6 +1873,10 @@ Since The URI or URL that Craft should use for email verification links on the front end. +Note that this config setting is ignored when is enabled, unless it’s set to an absolute URL. + +See [craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) for a list of supported value types. + ### `verifyEmailSuccessPath` @@ -1577,6 +1899,8 @@ Since The URI that users without access to the control panel should be redirected to after verifying a new email address. +See [craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) for a list of supported value types. + ## Session @@ -1617,6 +1941,10 @@ Defined by The amount of time Craft will remember a username and pre-populate it on the control panel’s Login page. +Set to `0` to disable this feature altogether. + +See [craft\helpers\ConfigHelper::durationInSeconds()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-durationinseconds) for a list of supported value types. + ### `rememberedUserSessionDuration` @@ -1636,6 +1964,10 @@ Defined by The amount of time a user stays logged if “Remember Me” is checked on the login page. +Set to `0` to disable the “Remember Me” feature altogether. + +See [craft\helpers\ConfigHelper::durationInSeconds()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-durationinseconds) for a list of supported value types. + ### `requireMatchingUserAgentForSession` @@ -1693,6 +2025,10 @@ Defined by The amount of time before a user will get logged out due to inactivity. +Set to `0` if you want users to stay logged in as long as their browser is open rather than a predetermined amount of time. + +See [craft\helpers\ConfigHelper::durationInSeconds()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-durationinseconds) for a list of supported value types. + ## Security @@ -1714,6 +2050,15 @@ Defined by The higher the cost value, the longer it takes to generate a password hash and to verify against it. +Therefore, higher cost slows down a brute-force attack. + +For best protection against brute force attacks, set it to the highest value that is tolerable on production servers. + +The time taken to compute the hash doubles for every increment by one for this value. + +For example, if the hash takes 1 second to compute when the value is 14 then the compute time varies as +2^(value - 14) seconds. + ### `cooldownDuration` @@ -1734,6 +2079,10 @@ Defined by The amount of time a user must wait before re-attempting to log in after their account is locked due to too many failed login attempts. +Set to `0` to keep the account locked indefinitely, requiring an admin to manually unlock the account. + +See [craft\helpers\ConfigHelper::durationInSeconds()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-durationinseconds) for a list of supported value types. + ### `csrfTokenName` @@ -1772,6 +2121,8 @@ Defined by The default amount of time tokens can be used before expiring. +See [craft\helpers\ConfigHelper::durationInSeconds()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-durationinseconds) for a list of supported value types. + ### `deferPublicRegistrationPassword` @@ -1792,6 +2143,9 @@ Defined by By default, Craft requires a front-end “password” field for public user registrations. Setting this to `true` removes that requirement for the initial registration form. +If you have email verification enabled, new users will set their password once they’ve followed the verification link in the email. +If you don’t, the only way they can set their password is to go through your “forgot password” workflow. + ### `elevatedSessionDuration` @@ -1811,6 +2165,10 @@ Defined by The amount of time a user’s elevated session will last, which is required for some sensitive actions (e.g. user group/permission assignment). +Set to `0` to disable elevated session support. + +See [craft\helpers\ConfigHelper::durationInSeconds()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-durationinseconds) for a list of supported value types. + ### `enableBasicHttpAuth` @@ -1892,6 +2250,8 @@ Defined by The amount of time to track invalid login attempts for a user, for determining if Craft should lock an account. +See [craft\helpers\ConfigHelper::durationInSeconds()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-durationinseconds) for a list of supported value types. + ### `maxInvalidLogins` @@ -1930,6 +2290,10 @@ Defined by When `true`, Craft will always return a successful response in the “forgot password” flow, making it difficult to enumerate users. +When set to `false` and you go through the “forgot password” flow from the control panel login page, you’ll get distinct messages indicating +whether the username/email exists and whether an email was sent with further instructions. This can be helpful for the user attempting to +log in but allow for username/email enumeration based on the response. + ### `previewTokenDuration` @@ -1952,6 +2316,8 @@ Since The amount of time content preview tokens can be used before expiring. +See [craft\helpers\ConfigHelper::durationInSeconds()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-durationinseconds) for a list of supported value types. + ### `sanitizeCpImageUploads` @@ -1993,6 +2359,8 @@ Defined by Whether Craft should sanitize uploaded SVG files and strip out potential malicious-looking content. +This should definitely be enabled if you are accepting SVG uploads from untrusted sources. + ### `secureHeaders` @@ -2012,6 +2380,10 @@ Defined by Lists of headers that are, by default, subject to the trusted host configuration. +See [yii\web\Request::$secureHeaders](https://www.yiiframework.com/doc/api/2.0/yii-web-request#$secureHeaders-detail) for more details. + +If not set, the default [yii\web\Request::$secureHeaders](https://www.yiiframework.com/doc/api/2.0/yii-web-request#$secureHeaders-detail) value will be used. + ### `secureProtocolHeaders` @@ -2031,6 +2403,10 @@ Defined by List of headers to check for determining whether the connection is made via HTTPS. +See [yii\web\Request::$secureProtocolHeaders](https://www.yiiframework.com/doc/api/2.0/yii-web-request#$secureProtocolHeaders-detail) for more details. + +If not set, the default [yii\web\Request::$secureProtocolHeaders](https://www.yiiframework.com/doc/api/2.0/yii-web-request#$secureProtocolHeaders-detail) value will be used. + ### `securityKey` @@ -2050,6 +2426,8 @@ Defined by A private, random, cryptographically-secure key that is used for hashing and encrypting data in [craft\services\Security](craft3:craft\services\Security). +This value should be the same across all environments. If this key ever changes, any data that was encrypted with it will be inaccessible. + ### `storeUserIps` @@ -2093,6 +2471,10 @@ Defined by The configuration for trusted security-related headers. +See [yii\web\Request::$trustedHosts](https://www.yiiframework.com/doc/api/2.0/yii-web-request#$trustedHosts-detail) for more details. + +By default, all hosts are trusted. + ### `useSecureCookies` @@ -2112,6 +2494,9 @@ Defined by Whether Craft will set the “secure” flag when saving cookies when using `Craft::cookieConfig()` to create a cookie. +Valid values are `true`, `false`, and `'auto'`. Defaults to `'auto'`, which will set the secure flag if the page you’re currently accessing +is over `https://`. `true` will always set the flag, regardless of protocol and `false` will never automatically set the flag. + ### `verificationCodeDuration` @@ -2131,6 +2516,8 @@ Defined by The amount of time a user verification code can be used before expiring. +See [craft\helpers\ConfigHelper::durationInSeconds()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-durationinseconds) for a list of supported value types. + ## Assets @@ -2269,6 +2656,10 @@ Defined by Whether uploaded filenames with non-ASCII characters should be converted to ASCII (i.e. `ñ` → `n`). +::: tip +You can run `php craft utils/ascii-filenames` in your terminal to apply ASCII filenames to all existing assets. +::: + ### `extraFileKinds` @@ -2292,6 +2683,25 @@ Since List of additional file kinds Craft should support. This array will get merged with the one defined in `\craft\helpers\Assets::_buildFileKinds()`. +```php +'extraFileKinds' => [ + // merge .psb into list of Photoshop file kinds + 'photoshop' => [ + 'extensions' => ['psb'], + ], + // register new "Stylesheet" file kind + 'stylesheet' => [ + 'label' => 'Stylesheet', + 'extensions' => ['css', 'less', 'pcss', 'sass', 'scss', 'styl'], + ], +], +``` + +::: tip +File extensions listed here won’t immediately be allowed to be uploaded. You will also need to list them with +the config setting. +::: + ### `filenameWordSeparator` @@ -2330,6 +2740,8 @@ Defined by The maximum upload file size allowed. +See [craft\helpers\ConfigHelper::sizeInBytes()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-sizeinbytes) for a list of supported value types. + ### `revAssetUrls` @@ -2377,6 +2789,8 @@ Since The server path to an image file that should be sent when responding to an image request with a 404 status code. +This can be set to an aliased path such as `@webroot/assets/404.svg`. + ### `defaultImageQuality` @@ -2527,6 +2941,9 @@ Since Whether CMYK should be preserved as the colorspace when manipulating images. +Setting this to `true` will prevent Craft from transforming CMYK images to sRGB, but on some ImageMagick versions it can cause +image color distortion. This will only have an effect if ImageMagick is in use. + ### `preserveExifData` @@ -2546,6 +2963,10 @@ Defined by Whether the EXIF data should be preserved when manipulating and uploading images. +Setting this to `true` will result in larger image file sizes. + +This will only have effect if ImageMagick is in use. + ### `preserveImageColorProfiles` @@ -2565,6 +2986,9 @@ Defined by Whether the embedded Image Color Profile (ICC) should be preserved when manipulating images. +Setting this to `false` will reduce the image size a little bit, but on some ImageMagick versions can cause images to be saved with +an incorrect gamma value, which causes the images to become very dark. This will only have effect if ImageMagick is in use. + ### `rasterizeSvgThumbs` @@ -2587,6 +3011,8 @@ Since Whether SVG thumbnails should be rasterized. +Note this will only work if ImageMagick is installed, and is set to either `auto` or `imagick`. + ### `rotateImagesOnUploadByExifData` @@ -2696,6 +3122,11 @@ Since The Ajax origins that should be allowed to access the GraphQL API, if enabled. +If this is set to an array, then `graphql/api` requests will only include the current request’s [origin](https://www.yiiframework.com/doc/api/2.0/yii-web-request#getOrigin()-detail) +in the `Access-Control-Allow-Origin` response header if it’s listed here. + +If this is set to `false`, then the `Access-Control-Allow-Origin` response header will never be sent. + ### `disableGraphqlTransformDirective` @@ -2740,6 +3171,8 @@ Since Whether the GraphQL API should be enabled. +Note that the GraphQL API is only available for Craft Pro. + ### `enableGraphqlCaching` @@ -2762,6 +3195,12 @@ Since Whether Craft should cache GraphQL queries. +If set to `true`, Craft will cache the results for unique GraphQL queries per access token. The cache is automatically invalidated any time +an element is saved, the site structure is updated, or a GraphQL schema is saved. + +This setting will have no effect if a plugin is using the [craft\services\Gql::EVENT_BEFORE_EXECUTE_GQL_QUERY](https://docs.craftcms.com/api/v3/craft-services-gql.html#constant-event-before-execute-gql-query) event to provide its own +caching logic and setting the `result` property. + ### `enableGraphqlIntrospection` @@ -2956,6 +3395,16 @@ Defined by The amount of time to wait before Craft purges pending users from the system that have not activated. +Any content assigned to a pending user will be deleted as well when the given time interval passes. + +Set to `0` to disable this feature. + +See [craft\helpers\ConfigHelper::durationInSeconds()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-durationinseconds) for a list of supported value types. + +::: tip +Users will only be purged when [garbage collection](https://craftcms.com/docs/3.x/gc.html) is run. +::: + ### `purgeStaleUserSessionDuration` @@ -2978,6 +3427,10 @@ Since The amount of time to wait before Craft purges stale user sessions from the sessions table in the database. +Set to `0` to disable this feature. + +See [craft\helpers\ConfigHelper::durationInSeconds()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-durationinseconds) for a list of supported value types. + ### `purgeUnsavedDraftsDuration` @@ -3000,6 +3453,10 @@ Since The amount of time to wait before Craft purges unpublished drafts that were never updated with content. +Set to `0` to disable this feature. + +See [craft\helpers\ConfigHelper::durationInSeconds()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-durationinseconds) for a list of supported value types. + ### `softDeleteDuration` @@ -3022,6 +3479,10 @@ Since The amount of time before a soft-deleted item will be up for hard-deletion by garbage collection. +Set to `0` if you don’t ever want to delete soft-deleted items. + +See [craft\helpers\ConfigHelper::durationInSeconds()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-durationinseconds) for a list of supported value types. + diff --git a/docs/.artifacts/cms/3.x/entries.md b/docs/.artifacts/cms/3.x/entries.md index b9d722c3e..15d63ed38 100644 --- a/docs/.artifacts/cms/3.x/entries.md +++ b/docs/.artifacts/cms/3.x/entries.md @@ -8,7 +8,6 @@ | Param | Description | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- -| [addOrderBy](#addorderby) | Adds additional ORDER BY columns to the query. | [after](#after) | Narrows the query results to only entries that were posted on or after a certain date. | [afterPopulate](#afterpopulate) | Performs any post-population processing on elements. | [ancestorDist](#ancestordist) | Narrows the query results to only entries that are up to a certain distance away from the entry specified by [ancestorOf](#ancestorof). @@ -31,7 +30,6 @@ | [draftOf](#draftof) | Narrows the query results to only drafts of a given entry. | [drafts](#drafts) | Narrows the query results to only drafts entries. | [expiryDate](#expirydate) | Narrows the query results based on the entries’ expiry dates. -| [fields](#fields) | Returns the list of fields that should be returned by default by [toArray()](https://www.yiiframework.com/doc/api/2.0/yii-base-arrayabletrait#toArray()-detail) when no specific fields are specified. | [fixedOrder](#fixedorder) | Causes the query results to be returned in the order specified by [id](#id). | [hasDescendants](#hasdescendants) | Narrows the query results based on whether the entries have any descendants in their structure. | [id](#id) | Narrows the query results based on the entries’ IDs. @@ -77,19 +75,6 @@ -#### `addOrderBy` - -Adds additional ORDER BY columns to the query. - - - - - - - - - - #### `after` Narrows the query results to only entries that were posted on or after a certain date. @@ -736,45 +721,6 @@ $entries = \craft\elements\Entry::find() ::: -#### `fields` - -Returns the list of fields that should be returned by default by [toArray()](https://www.yiiframework.com/doc/api/2.0/yii-base-arrayabletrait#toArray()-detail) when no specific fields are specified. - -A field is a named element in the returned array by [toArray()](https://www.yiiframework.com/doc/api/2.0/yii-base-arrayabletrait#toArray()-detail). -This method should return an array of field names or field definitions. -If the former, the field name will be treated as an object property name whose value will be used -as the field value. If the latter, the array key should be the field name while the array value should be -the corresponding field definition which can be either an object property name or a PHP callable -returning the corresponding field value. The signature of the callable should be: - -```php -function ($model, $field) { - // return field value -} -``` - -For example, the following code declares four fields: - -- `email`: the field name is the same as the property name `email`; -- `firstName` and `lastName`: the field names are `firstName` and `lastName`, and their - values are obtained from the `first_name` and `last_name` properties; -- `fullName`: the field name is `fullName`. Its value is obtained by concatenating `first_name` - and `last_name`. - -```php -return [ - 'email', - 'firstName' => 'first_name', - 'lastName' => 'last_name', - 'fullName' => function ($model) { - return $model->first_name . ' ' . $model->last_name; - }, -]; -``` - - - - #### `fixedOrder` Causes the query results to be returned in the order specified by [id](#id). diff --git a/docs/.artifacts/cms/3.x/globals.md b/docs/.artifacts/cms/3.x/globals.md index 821d7723c..4f8d692b8 100644 --- a/docs/.artifacts/cms/3.x/globals.md +++ b/docs/.artifacts/cms/3.x/globals.md @@ -8,7 +8,6 @@ | Param | Description | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- -| [addOrderBy](#addorderby) | Adds additional ORDER BY columns to the query. | [afterPopulate](#afterpopulate) | Performs any post-population processing on elements. | [andRelatedTo](#andrelatedto) | Narrows the query results to only global sets that are related to certain other elements. | [anyStatus](#anystatus) | Removes element filters based on their statuses. @@ -17,7 +16,6 @@ | [clearCachedResult](#clearcachedresult) | Clears the [cached result](https://craftcms.com/docs/3.x/element-queries.html#cache). | [dateCreated](#datecreated) | Narrows the query results based on the global sets’ creation dates. | [dateUpdated](#dateupdated) | Narrows the query results based on the global sets’ last-updated dates. -| [fields](#fields) | Returns the list of fields that should be returned by default by [toArray()](https://www.yiiframework.com/doc/api/2.0/yii-base-arrayabletrait#toArray()-detail) when no specific fields are specified. | [fixedOrder](#fixedorder) | Causes the query results to be returned in the order specified by [id](#id). | [handle](#handle) | Narrows the query results based on the global sets’ handles. | [id](#id) | Narrows the query results based on the global sets’ IDs. @@ -41,19 +39,6 @@ -#### `addOrderBy` - -Adds additional ORDER BY columns to the query. - - - - - - - - - - #### `afterPopulate` Performs any post-population processing on elements. @@ -244,45 +229,6 @@ $globalSets = \craft\elements\GlobalSet::find() ::: -#### `fields` - -Returns the list of fields that should be returned by default by [toArray()](https://www.yiiframework.com/doc/api/2.0/yii-base-arrayabletrait#toArray()-detail) when no specific fields are specified. - -A field is a named element in the returned array by [toArray()](https://www.yiiframework.com/doc/api/2.0/yii-base-arrayabletrait#toArray()-detail). -This method should return an array of field names or field definitions. -If the former, the field name will be treated as an object property name whose value will be used -as the field value. If the latter, the array key should be the field name while the array value should be -the corresponding field definition which can be either an object property name or a PHP callable -returning the corresponding field value. The signature of the callable should be: - -```php -function ($model, $field) { - // return field value -} -``` - -For example, the following code declares four fields: - -- `email`: the field name is the same as the property name `email`; -- `firstName` and `lastName`: the field names are `firstName` and `lastName`, and their - values are obtained from the `first_name` and `last_name` properties; -- `fullName`: the field name is `fullName`. Its value is obtained by concatenating `first_name` - and `last_name`. - -```php -return [ - 'email', - 'firstName' => 'first_name', - 'lastName' => 'last_name', - 'fullName' => function ($model) { - return $model->first_name . ' ' . $model->last_name; - }, -]; -``` - - - - #### `fixedOrder` Causes the query results to be returned in the order specified by [id](#id). diff --git a/docs/.artifacts/cms/3.x/matrix-blocks.md b/docs/.artifacts/cms/3.x/matrix-blocks.md index 7f3e2d939..b49d87723 100644 --- a/docs/.artifacts/cms/3.x/matrix-blocks.md +++ b/docs/.artifacts/cms/3.x/matrix-blocks.md @@ -8,7 +8,6 @@ | Param | Description | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- -| [addOrderBy](#addorderby) | Adds additional ORDER BY columns to the query. | [afterPopulate](#afterpopulate) | Performs any post-population processing on elements. | [allowOwnerDrafts](#allowownerdrafts) | Narrows the query results based on whether the Matrix blocks’ owners are drafts. | [allowOwnerRevisions](#allowownerrevisions) | Narrows the query results based on whether the Matrix blocks’ owners are revisions. @@ -21,7 +20,6 @@ | [dateUpdated](#dateupdated) | Narrows the query results based on the Matrix blocks’ last-updated dates. | [field](#field) | Narrows the query results based on the field the Matrix blocks belong to. | [fieldId](#fieldid) | Narrows the query results based on the field the Matrix blocks belong to, per the fields’ IDs. -| [fields](#fields) | Returns the list of fields that should be returned by default by [toArray()](https://www.yiiframework.com/doc/api/2.0/yii-base-arrayabletrait#toArray()-detail) when no specific fields are specified. | [fixedOrder](#fixedorder) | Causes the query results to be returned in the order specified by [id](#id). | [id](#id) | Narrows the query results based on the Matrix blocks’ IDs. | [ignorePlaceholders](#ignoreplaceholders) | Causes the query to return matching Matrix blocks as they are stored in the database, ignoring matching placeholder elements that were set by [craft\services\Elements::setPlaceholderElement()](https://docs.craftcms.com/api/v3/craft-services-elements.html#method-setplaceholderelement). @@ -49,19 +47,6 @@ -#### `addOrderBy` - -Adds additional ORDER BY columns to the query. - - - - - - - - - - #### `afterPopulate` Performs any post-population processing on elements. @@ -345,45 +330,6 @@ $MatrixBlocks = \craft\elements\MatrixBlock::find() ::: -#### `fields` - -Returns the list of fields that should be returned by default by [toArray()](https://www.yiiframework.com/doc/api/2.0/yii-base-arrayabletrait#toArray()-detail) when no specific fields are specified. - -A field is a named element in the returned array by [toArray()](https://www.yiiframework.com/doc/api/2.0/yii-base-arrayabletrait#toArray()-detail). -This method should return an array of field names or field definitions. -If the former, the field name will be treated as an object property name whose value will be used -as the field value. If the latter, the array key should be the field name while the array value should be -the corresponding field definition which can be either an object property name or a PHP callable -returning the corresponding field value. The signature of the callable should be: - -```php -function ($model, $field) { - // return field value -} -``` - -For example, the following code declares four fields: - -- `email`: the field name is the same as the property name `email`; -- `firstName` and `lastName`: the field names are `firstName` and `lastName`, and their - values are obtained from the `first_name` and `last_name` properties; -- `fullName`: the field name is `fullName`. Its value is obtained by concatenating `first_name` - and `last_name`. - -```php -return [ - 'email', - 'firstName' => 'first_name', - 'lastName' => 'last_name', - 'fullName' => function ($model) { - return $model->first_name . ' ' . $model->last_name; - }, -]; -``` - - - - #### `fixedOrder` Causes the query results to be returned in the order specified by [id](#id). @@ -595,9 +541,7 @@ Possible values include: | Value | Fetches Matrix blocks… | - | - | `1` | created for an element with an ID of 1. -| `'not 1'` | not created for an element with an ID of 1. | `[1, 2]` | created for an element with an ID of 1 or 2. -| `['not', 1, 2]` | not created for an element with an ID of 1 or 2. diff --git a/docs/.artifacts/cms/3.x/tags.md b/docs/.artifacts/cms/3.x/tags.md index 8067d9639..7c8c67c4c 100644 --- a/docs/.artifacts/cms/3.x/tags.md +++ b/docs/.artifacts/cms/3.x/tags.md @@ -8,7 +8,6 @@ | Param | Description | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ -| [addOrderBy](#addorderby) | Adds additional ORDER BY columns to the query. | [afterPopulate](#afterpopulate) | Performs any post-population processing on elements. | [andRelatedTo](#andrelatedto) | Narrows the query results to only tags that are related to certain other elements. | [anyStatus](#anystatus) | Removes element filters based on their statuses. @@ -17,7 +16,6 @@ | [clearCachedResult](#clearcachedresult) | Clears the [cached result](https://craftcms.com/docs/3.x/element-queries.html#cache). | [dateCreated](#datecreated) | Narrows the query results based on the tags’ creation dates. | [dateUpdated](#dateupdated) | Narrows the query results based on the tags’ last-updated dates. -| [fields](#fields) | Returns the list of fields that should be returned by default by [toArray()](https://www.yiiframework.com/doc/api/2.0/yii-base-arrayabletrait#toArray()-detail) when no specific fields are specified. | [fixedOrder](#fixedorder) | Causes the query results to be returned in the order specified by [id](#id). | [group](#group) | Narrows the query results based on the tag groups the tags belong to. | [groupId](#groupid) | Narrows the query results based on the tag groups the tags belong to, per the groups’ IDs. @@ -44,19 +42,6 @@ -#### `addOrderBy` - -Adds additional ORDER BY columns to the query. - - - - - - - - - - #### `afterPopulate` Performs any post-population processing on elements. @@ -247,45 +232,6 @@ $tags = \craft\elements\Tag::find() ::: -#### `fields` - -Returns the list of fields that should be returned by default by [toArray()](https://www.yiiframework.com/doc/api/2.0/yii-base-arrayabletrait#toArray()-detail) when no specific fields are specified. - -A field is a named element in the returned array by [toArray()](https://www.yiiframework.com/doc/api/2.0/yii-base-arrayabletrait#toArray()-detail). -This method should return an array of field names or field definitions. -If the former, the field name will be treated as an object property name whose value will be used -as the field value. If the latter, the array key should be the field name while the array value should be -the corresponding field definition which can be either an object property name or a PHP callable -returning the corresponding field value. The signature of the callable should be: - -```php -function ($model, $field) { - // return field value -} -``` - -For example, the following code declares four fields: - -- `email`: the field name is the same as the property name `email`; -- `firstName` and `lastName`: the field names are `firstName` and `lastName`, and their - values are obtained from the `first_name` and `last_name` properties; -- `fullName`: the field name is `fullName`. Its value is obtained by concatenating `first_name` - and `last_name`. - -```php -return [ - 'email', - 'firstName' => 'first_name', - 'lastName' => 'last_name', - 'fullName' => function ($model) { - return $model->first_name . ' ' . $model->last_name; - }, -]; -``` - - - - #### `fixedOrder` Causes the query results to be returned in the order specified by [id](#id). diff --git a/docs/.artifacts/cms/3.x/users.md b/docs/.artifacts/cms/3.x/users.md index 84027c411..61494e5d7 100644 --- a/docs/.artifacts/cms/3.x/users.md +++ b/docs/.artifacts/cms/3.x/users.md @@ -8,7 +8,6 @@ | Param | Description | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- -| [addOrderBy](#addorderby) | Adds additional ORDER BY columns to the query. | [admin](#admin) | Narrows the query results to only users that have admin accounts. | [afterPopulate](#afterpopulate) | Performs any post-population processing on elements. | [andRelatedTo](#andrelatedto) | Narrows the query results to only users that are related to certain other elements. @@ -20,7 +19,6 @@ | [dateCreated](#datecreated) | Narrows the query results based on the users’ creation dates. | [dateUpdated](#dateupdated) | Narrows the query results based on the users’ last-updated dates. | [email](#email) | Narrows the query results based on the users’ email addresses. -| [fields](#fields) | Returns the list of fields that should be returned by default by [toArray()](https://www.yiiframework.com/doc/api/2.0/yii-base-arrayabletrait#toArray()-detail) when no specific fields are specified. | [firstName](#firstname) | Narrows the query results based on the users’ first names. | [fixedOrder](#fixedorder) | Causes the query results to be returned in the order specified by [id](#id). | [group](#group) | Narrows the query results based on the user group the users belong to. @@ -49,19 +47,6 @@ -#### `addOrderBy` - -Adds additional ORDER BY columns to the query. - - - - - - - - - - #### `admin` Narrows the query results to only users that have admin accounts. @@ -331,45 +316,6 @@ $users = \craft\elements\User::find() ::: -#### `fields` - -Returns the list of fields that should be returned by default by [toArray()](https://www.yiiframework.com/doc/api/2.0/yii-base-arrayabletrait#toArray()-detail) when no specific fields are specified. - -A field is a named element in the returned array by [toArray()](https://www.yiiframework.com/doc/api/2.0/yii-base-arrayabletrait#toArray()-detail). -This method should return an array of field names or field definitions. -If the former, the field name will be treated as an object property name whose value will be used -as the field value. If the latter, the array key should be the field name while the array value should be -the corresponding field definition which can be either an object property name or a PHP callable -returning the corresponding field value. The signature of the callable should be: - -```php -function ($model, $field) { - // return field value -} -``` - -For example, the following code declares four fields: - -- `email`: the field name is the same as the property name `email`; -- `firstName` and `lastName`: the field names are `firstName` and `lastName`, and their - values are obtained from the `first_name` and `last_name` properties; -- `fullName`: the field name is `fullName`. Its value is obtained by concatenating `first_name` - and `last_name`. - -```php -return [ - 'email', - 'firstName' => 'first_name', - 'lastName' => 'last_name', - 'fullName' => function ($model) { - return $model->first_name . ' ' . $model->last_name; - }, -]; -``` - - - - #### `firstName` Narrows the query results based on the users’ first names.