5.12

.claude/skills/twig-upgrade/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: twig-upgrade
+description: Checklist for updating the twig/twig dependency. Lists the Craft classes and methods that copy or mirror Twig core code, what to diff each one against, and how to verify the upgrade. Use when bumping twig/twig in composer.json, or when reviewing whether Craft's Twig integration is in sync with upstream.
+---
+
+# Updating Twig
+
+Several Craft classes copy, fork, or depend on Twig internals. When `twig/twig` is bumped, each of them must be compared against the new upstream code, or Craft silently drifts from Twig's behavior (including sandbox security fixes).
+
+## 1. See what changed upstream
+
+Clone Twig into the scratchpad and diff the two versions for the files listed below:
+
+```sh
+git clone https://github.com/twigphp/Twig.git <scratchpad>/twig
+cd <scratchpad>/twig
+git diff v<OLD> v<NEW> --stat -- src/
+git diff v<OLD> v<NEW> -- src/Node/Expression/GetAttrExpression.php src/Sandbox/ src/NodeVisitor/SandboxNodeVisitor.php
+```
+
+Also read `CHANGELOG` between the two versions. Look especially for entries mentioning the sandbox, `GetAttrExpression`, `getAttribute()`, deprecations, or security fixes.
+
+## 2. Files to check
+
+### Direct copies (highest risk)
+
+| Craft file | Upstream counterpart | Notes |
+|---|---|---|
+| `src/web/twig/nodes/GetAttrNode.php` — `compile()` | `src/Node/Expression/GetAttrExpression.php` — `compile()` | Line-for-line port. Differences are marked with `// DIFF` comments. The main intended difference is calling `craft\helpers\Template::attribute()` instead of `CoreExtension::getAttribute()`. `compileArrayKey()` also intentionally coerces every `Stringable` key to a string, to match `Template::attribute()`, rather than only for arrays, `ArrayObject`, and `ArrayIterator` like upstream (since Twig 3.29). Private upstream helpers (`compileArrayKey()`, `isShortCircuited()`, `markAsShortCircuited()`, `getVarName()`) are reimplemented here and must be re-synced too. Port every upstream change to `compile()` or its helpers. |
+| `src/web/twig/SecurityPolicy.php` | `src/Sandbox/SecurityPolicy.php` (a `final` class, so Craft forks it) | `checkSecurity()`, `checkMethodAllowed()`, `checkPropertyAllowed()`, the error messages, and the constructor/setter structure mirror upstream. Craft adds `allowedClasses`, the `AllowedInSandbox` attribute, the `AllowableInSandbox` interface, and a getter fallback for `yii\base\BaseObject` properties. Also check `src/Sandbox/SecurityPolicyInterface.php` for signature changes. See the sandbox notes below. |
+| `src/web/twig/nodes/expressions/binaries/HasSomeBinary.php`, `HasEveryBinary.php` | `src/Node/Expression/Binary/HasSomeBinary.php`, `HasEveryBinary.php` | Identical except they compile to `craft\web\twig\Extension::arraySome()`/`arrayEvery()`. Those methods in `src/web/twig/Extension.php` delegate to `CoreExtension::checkArrow()` and `CoreExtension::arraySome()`/`arrayEvery()`, so check those signatures too. |
+| `src/web/twig/tokenparsers/DeprecatedTokenParser.php`, `nodes/DeprecatedNode.php` | `src/TokenParser/DeprecatedTokenParser.php`, `src/Node/DeprecatedNode.php` | Derived from an older upstream version. The node logs to Craft's deprecator instead of calling `trigger_deprecation()`. Upstream's `package`/`version` options were never ported. Only update if upstream changes the core parsing. |
+
+### Code that depends on Twig internals
+
+| Craft file | What to check |
+|---|---|
+| `src/web/twig/nodevisitors/GetAttrAdjuster.php` | Swaps every `GetAttrExpression` for `GetAttrNode` and copies its nodes and attributes **explicitly**. If upstream adds an attribute to `GetAttrExpression` (or sets one on it from elsewhere, such as `sandboxed_function_name`/`sandboxed_function` from `ExpressionParser/Infix/FunctionExpressionParser.php`), it must be copied here too, or it is silently dropped. Grep the new version for `setAttribute(` calls that target `GetAttrExpression` nodes. |
+| `src/helpers/Template.php` — `attribute()` | Wraps `CoreExtension::getAttribute()`. Compare its signature with upstream's. The `BaseObject` property branch bypasses `getAttribute()`, so compare it against upstream's sandbox checks (`checkPropertyAllowed()`, `ensureToStringAllowed()` for `Stringable` items). Its twigphp/Twig#4701 workaround coerces every `Stringable` key to a string for non-method calls. Upstream only does that for arrays, `ArrayObject`, and `ArrayIterator`, and passes the object through for other `ArrayAccess` implementations, which breaks Collections, so keep the workaround unless upstream's behavior changes. |
+| `src/web/twig/nodes/FallbackNameExpression.php` | Mirrors `src/Node/Expression/Variable/ContextVariable.php`/`NameExpression.php`'s `compile()`. Deprecated since 5.9.15; only keep it compiling. |
+| `src/web/twig/nodes/NavNode.php` | Extends `src/Node/ForNode.php` and calls `parent::compile()`. Check `ForNode`'s constructor signature and the loop variables it compiles. |
+| `src/web/twig/Extension.php` | Many filters and functions override core ones but delegate to `CoreExtension` static methods (`sort`, `reduce`, `map`, `filter`, `merge`, `length`, `testEmpty`, `checkArrow`, `formatDate`, `convertDate`, …). Check that those still exist with the same signatures. `capitalizeFilter()` copies `CoreExtension::capitalize()`'s logic. Also compare the `getFilters()`/`getFunctions()`/`getTests()` options (e.g. `needs_environment`, `needs_charset`, `needs_is_sandboxed`, `is_safe`) against the core definitions they override. |
+| `src/base/Element.php` — `getIterator()` | Skips custom fields when called from the sandbox's `__toString()` checks, to avoid infinite recursion (#19004). It detects that by checking `debug_backtrace()` for a specific class and method (`Twig\Sandbox\SecurityChecker::doEnsureToStringAllowed()` since Twig 3.29; `SandboxExtension` before that). If upstream renames or moves that method, the check silently stops matching. `tests/unit/base/ElementTest.php` covers it. |
+| `src/web/View.php` — `sandbox()` | Turns sandboxing on and off for Craft's shared environment through `SandboxExtension::getChecker()->setSandboxed()`, because `enableSandbox()`/`disableSandbox()` are deprecated since Twig 3.29. `getChecker()` and `SecurityChecker` are `@internal`, so check that they still exist. Twig's replacement, `Twig\Sandbox\Sandbox`, requires a dedicated environment and a strict policy, so it doesn't fit Craft's approach yet. |
+| `src/web/twig/tokenparsers/NavTokenParser.php` | Mirrors `src/TokenParser/ForTokenParser.php`'s handling of loop targets. |
+| `src/config/twig-sandbox.php`, `src/web/View.php` (`createTwig()`) | If upstream adds allowlist types or constructor arguments to the sandbox, decide whether Craft's policy and config should support them. |
+
+## 3. Sandbox notes
+
+- Twig's `SandboxExtension::checkSecurity()` uses reflection to check how many parameters the policy's `checkSecurity()` declares, and triggers a deprecation if it declares fewer than upstream expects. Keep `SecurityPolicy::checkSecurity()`'s parameter list in sync, even for arguments Craft ignores (such as `array $tests`).
+- Upstream often loosens things temporarily with "X is always allowed in sandboxes, but won't be in 4.0" deprecations. Don't copy these into Craft's policy without checking what Craft's policy currently does. If Craft already rejects something, copying upstream's deprecate-but-allow branch loosens the sandbox. For example, Twig 3.27 made `parent()`/`block()`/`attribute()` reportable to the policy, and Craft rejects them unless they're in `allowedFunctions`.
+- Craft's node visitors and Twig's `SandboxNodeVisitor` all use priority `0`, and Craft's extension is registered first, so Craft's visitors see (and can replace) nodes before the sandbox does. Any node replacement must preserve the attributes the sandbox reads.
+
+## 4. Verify
+
+- **Tests:** run `vendor/bin/codecept run unit web/twig`. This needs the test database named in `tests/.env` to exist.
+- **Static analysis and coding standards:** run `vendor/bin/phpstan analyse` and `vendor/bin/ecs check` on the changed files.
+- **Compiled templates:** compiled templates are cached by template source, not by Craft's node or visitor code. After changing `GetAttrNode`, `GetAttrAdjuster`, or any other compile-time code, clear `tests/_craft/storage/runtime/compiled_templates/` before running tests, or stale compiled templates will hide the change.
+- **Strict variables:** `GetAttrNode`'s optimized array path only runs when strict variables are **off** (Dev Mode disabled). The test config enables Dev Mode, so cover that path with a standalone `Twig\Environment` created with `'strict_variables' => false` and `GetAttrAdjuster` registered (see `tests/unit/web/twig/GetAttrNodeTest.php`).
+- **Template deprecations:** compile every template under `src/templates/` with a temporary test that records `E_USER_DEPRECATED` errors, and check for deprecations introduced by the new version. `exception.twig` fails to compile because it uses a `renderSourceCode` filter that Craft doesn't register. That's a pre-existing issue, not a Twig regression.
+- **Sandbox:** exercise it with `View::renderSandboxedString()` after setting `enableTwigSandbox = true` (see `tests/unit/web/twig/SecurityPolicyTest.php`).

.github/workflows/ci.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches:
       - 5.x
+      - '5.12'
       - '*-internal'
   pull_request:
 permissions:

CHANGELOG-5.12.md

@@ -0,0 +1,69 @@
+# Release Notes for Craft CMS 5.12 (WIP)
+
+### Content Management
+
+- Addresses within Addresses fields can now be edited from drafts of their owner elements, by users who can save the drafts but not the canonical owner elements. ([#19881](https://github.com/craftcms/cms/issues/19881))
+
+### Administration
+
+- Custom fields now have “Default Tip” and “Default Warning” settings. ([#19976](https://github.com/craftcms/cms/pull/19976))
+- A rate limit is now enforced for `users/login`, `auth/verify-totp`, and `auth/verify-recovery-code` requests. ([#20054](https://github.com/craftcms/cms/pull/20054))
+- Added the `defaultRateLimit` and `defaultRateLimitDuration` config settings, which configure the rate limits for `users/login`, `users/send-password-reset-email`, `auth/verify-totp`, and `auth/verify-recovery-code` requests. ([#20054](https://github.com/craftcms/cms/pull/20054))
+
+### Development
+
+- The `capitalize`, `lower`, `title`, and `upper` Twig filters now have `language` arguments, which default to the current application language. ([#19558](https://github.com/craftcms/cms/pull/19558))
+- Added the `project-config/check` command, which checks project config schema compatibility without applying changes.
+- Added the `{% render %}` Twig tag. ([#19988](https://github.com/craftcms/cms/pull/19988))
+- `{% render %}` tags and `render()` methods are allowed within the Twig sandbox. ([#19988](https://github.com/craftcms/cms/pull/19988))
+- GraphQL schemas can now include read-only components for sites, sections, entry types, volumes, user groups, category groups, and tag groups. ([#20055](https://github.com/craftcms/cms/pull/20055))
+- Added the `sites`, `site`, `sections`, `section`, `entryTypes`, `entryType`, `volumes`, `volume`, `userGroups`, `userGroup`, `categoryGroups`, `categoryGroup`, `tagGroups`, and `tagGroup` GraphQL queries, which are available when the schema includes the corresponding components. ([#20055](https://github.com/craftcms/cms/pull/20055))
+- Elements now have `site` fields in GraphQL, when the schema includes the “Query for sites” component. ([#20055](https://github.com/craftcms/cms/pull/20055))
+- Entries now have `section` and `type` fields in GraphQL, when the schema includes the “Query for sections” and “Query for entry types” components. ([#20055](https://github.com/craftcms/cms/pull/20055))
+- Assets now have `volume` fields in GraphQL, when the schema includes the “Query for volumes” component. ([#20055](https://github.com/craftcms/cms/pull/20055))
+- Users now have `groups` fields in GraphQL, when the schema includes the “Query for user groups” component. ([#20055](https://github.com/craftcms/cms/pull/20055))
+- Categories and tags now have `group` fields in GraphQL, when the schema includes the “Query for category groups” and “Query for tag groups” components. ([#20055](https://github.com/craftcms/cms/pull/20055))
+
+### Extensibility
+
+- Addresses now support drafts.
+- Element fixtures no longer create revisions by default. Set their `createRevisions` property to `true` to retain the previous behavior. ([#19626](https://github.com/craftcms/cms/pull/19626))
+- Added `craft\base\FieldTrait::$tip`.
+- Added `craft\base\FieldTrait::$warning`.
+- Added `craft\base\NestedElementTrait::$touchOwnersOnSave`.
+- Added `craft\base\Renderable`. ([#19988](https://github.com/craftcms/cms/pull/19988))
+- Added `craft\elements\db\NestedElementQueryTrait::mustHaveField()`.
+- Added `craft\elements\db\NestedElementQueryTrait::mustHaveOwner()`.
+- Added `craft\fieldlayoutelements\BaseField::defaultTip()`.
+- Added `craft\fieldlayoutelements\BaseField::defaultWarning()`.
+- Added `craft\gql\queries\Settings`. ([#20055](https://github.com/craftcms/cms/pull/20055))
+- Added `craft\gql\types\CategoryGroup`. ([#20055](https://github.com/craftcms/cms/pull/20055))
+- Added `craft\gql\types\EntryType`. ([#20055](https://github.com/craftcms/cms/pull/20055))
+- Added `craft\gql\types\Section`. ([#20055](https://github.com/craftcms/cms/pull/20055))
+- Added `craft\gql\types\Site`. ([#20055](https://github.com/craftcms/cms/pull/20055))
+- Added `craft\gql\types\TagGroup`. ([#20055](https://github.com/craftcms/cms/pull/20055))
+- Added `craft\gql\types\UserGroup`. ([#20055](https://github.com/craftcms/cms/pull/20055))
+- Added `craft\gql\types\Volume`. ([#20055](https://github.com/craftcms/cms/pull/20055))
+- Added `craft\helpers\Template::render()`. ([#19988](https://github.com/craftcms/cms/pull/19988))
+- Added `craft\i18n\Locale::languageId()`.
+- Added `craft\services\Images::getSupportsBmp()`.
+- Added `craft\services\Images::getSupportsJxl()`.
+- Added `craft\test\ElementFixtureTrait`. ([#19626](https://github.com/craftcms/cms/pull/19626))
+- `Illuminate\Support\Collection` now has a `render()` macro, which replaces `craft\elements\ElementCollection::render()`. ([#19988](https://github.com/craftcms/cms/pull/19988))
+- `craft\helpers\ElementHelper::normalizeSlug()` now has a `$language` argument, which defaults to the current application language. ([#19558](https://github.com/craftcms/cms/pull/19558))
+- `craft\helpers\StringHelper::toLowerCase()`, `::toTitleCase()`, and `::toUpperCase()` now have `$language` arguments, which default to the current application language. ([#19558](https://github.com/craftcms/cms/pull/19558))
+- Deprecated `craft\helpers\ElementHelper::renderElements()`. `craft\helpers\Template::render()` should be used instead. ([#19988](https://github.com/craftcms/cms/pull/19988))
+
+### System
+
+- Added support for JPEG XL (`.jxl`) images, when ImageMagick supports it. JPEG XL images can now be uploaded, transformed, and set as a transform’s output format.
+- BMP images can now be transformed and edited in the Image Editor.
+- MySQL database backups and restores now carry over SSL/TLS settings from the system’s MySQL option files (e.g. `ssl-ca` or `disable-ssl-verify-server-cert`), if the database connection doesn’t have any `PDO::MYSQL_ATTR_SSL_*` attributes set. ([#19366](https://github.com/craftcms/cms/pull/19366))
+- MySQL database backups and restores now respect the `PDO::MYSQL_ATTR_SSL_CAPATH` and `PDO::MYSQL_ATTR_SSL_CIPHER` database connection attributes. ([#19366](https://github.com/craftcms/cms/pull/19366))
+- Craft can now determine the dimensions of BMP and JPEG XL images on remote volumes without downloading them.
+- Removed support for the non-standard `ED256` passkey algorithm. ([#19701](https://github.com/craftcms/cms/pull/19701))
+- Updated Axios to 1.20.0. 
+- Updated Twig to 3.30.
+- Updated Fabric.js to v7. ([#19628](https://github.com/craftcms/cms/pull/19628))
+- Fixed a bug where entry and address indexes weren’t showing any results if they had a “Field” condition rule set to “is empty”.
+- Fixed a bug where saving a deeply-nested element on its own wouldn’t update its owners’ `dateUpdated` timestamps, which could cause new revisions to reuse stale nested content. ([#19594](https://github.com/craftcms/cms/issues/19594))

composer.json

@@ -68,7 +68,7 @@
     "symfony/var-dumper": "^5.0|^6.0|^7.0",
     "symfony/yaml": "^5.2.3|^6.0|^7.0",
     "theiconic/name-parser": "^1.2",
-    "twig/twig": "~3.28.0",
+    "twig/twig": "~3.30.0",
     "voku/portable-ascii": "^2.0",
     "web-auth/webauthn-lib": "~5.3.9",
     "yiisoft/yii2": "~2.0.55.0",