acf-lint --wpml: the repeater 'forced to 3' rule is options-page-only, and fires everywhere

[parisek]

Summary

acf-lint --wpml rejects any repeater / flexible_content whose wpml_cf_preferences is not 3, on the grounds that ACFML forces the value at runtime and anything else is dead configuration (src/Lint/AcfLinter.php:243).

That is true on the options-page path and not true on the post/block path. The rule does not distinguish them, so on a post_type field group it reports a real, deliberate configuration as dead — and its advice, followed literally, reverts a production bug fix.

Where the claim holds

On options pages, ACFML\Options\EditorHooks::onUpdateMainValue() (acfml/classes/Options/EditorHooks.php:174) returns early for wrappers:

if ( Fields::isWrapperOrGroup( $field ) ) {
    $this->maybeCopyWrapperToTranslations( $value, $field );
    return $value;
}

The preference switch below is never reached, so the configured value genuinely does not drive copying. Same early return at :114 and :287.

Where it does not

For post/block field groups the relevant path is WPML_ACF_Field_Settings. field_should_be_set_to_copy_once() (class-wpml-acf-field-settings.php:331) is used in exactly one place — as an || inside is_field_parsable() (:127-128):

return ( isset( $field['wpml_cf_preferences'], $field['name'] ) && $this->isValidFieldPreference( … ) && $field['name'] )
    || $this->field_should_be_set_to_copy_once( $field );

It widens which fields get processed. It does not set a value. save_field_settings() (:161) then writes the configured preference into the translation-management settings:

$this->maybe_set_new_preference( $setting_index, $field['name'], $field['wpml_cf_preferences'] );

Fields::WRAPPER_FIELDS, the other constant the message cites, backs only isWrapper() / isWrapperOrGroup() — structural predicates for "does this field wrap sub_fields". The two places that select WPML_COPY_ONCE_CUSTOM_FIELD (class-wpml-acf-field-settings.php:283, :439) choose it from the field group's Mode, for system fields, not by field type.

So the mechanism the message names does not support the claim, even in the context where the conclusion happens to hold.

Empirical half

Downstream on fellows, templates/room_type/acf.json has a style_galleries repeater on a post_type field group. It was moved from 3 to 1 on purpose (portadesign/fellows#96): Czech flats were falling back to the shared gallery because WPML copied the repeater's sub-field rows into translations without the row-count meta ACF reads first. The change worked, and shipped with a data migration to recompute counts on room types translated earlier.

A value the plugin ignored could not have done that.

Today acf-lint --wpml flags that field, and the obvious response — flip it back to 3 — is precisely what that bug report and migration moved away from. With no local ignore by design, the project is left with a permanently red lint or a regression.

Suggested direction

The package already has the machinery: classifyLocationContext() (src/Lint/AcfLinter.php:321) exists for the image/gallery preference rules and encodes the same options-page-vs-post distinction the doctrine documents. The pluginForced branch at :243 simply does not consult it.

Scoping that branch to the options-page context would make the rule match the plugin. I have not opened a PR because I am not sure whether you would prefer scoping it, downgrading it to a warning, or dropping it — and the wording of the message needs revisiting either way, since the cited mechanism is not the one doing the work.

Happy to do the PR if you say which shape you want.

Found while bumping a consuming project to 0.7.6.

[parisek]

Correction — my "where the claim holds" section is wrong, and so is the fix I proposed

Two independent reviews of this issue caught the same thing from different directions. Retracting the concession and the recommendation.

The options-page half does not hold either

I wrote that the rule's claim is true on options pages because onUpdateMainValue() returns early for wrappers. The early return is real; what happens next is not what I assumed.

EditorHooks::maybeCopyWrapperToTranslations() (acfml/classes/Options/EditorHooks.php:204) fires only at WPML_COPY_CUSTOM_FIELD:

if ( WPML_COPY_CUSTOM_FIELD === (int) Obj::prop( 'wpml_cf_preferences', $field ) ) {

WPML_COPY_CUSTOM_FIELD is 1; WPML_COPY_ONCE_CUSTOM_FIELD is 3 (sitepress-multilingual-cms/inc/constants.php:122,124). So a wrapper set to 3 on an options page gets neither copy-once nor wrapper copying — it gets nothing. Requiring 3 is wrong there too, not "right with a caveat".

That also breaks the fix I suggested. Scoping the branch to options pages would keep the rule wrong precisely where it would still fire. Please disregard that recommendation.

ACFML's own migration writes 1 to wrappers

class-wpml-acf-migrate-block-preferences.php:101 sets wrapper fields to WPML_COPY_CUSTOM_FIELD (1) — the value this rule rejects.

The rule did not flag a fix; its advice produced the defect

I understated this. portadesign/fellows#96 records the origin of the 3:

The preference came from a Copilot review comment on #79 that applied the rule without this consequence.

So the chain is: rule → 3 shipped → Czech room types lost their galleries (WPML copies a copy-once repeater sub-field by sub-field and omits the row-count meta ACF reads first) → bug report → fix to 1 plus a data migration → the rule now flags the fix.

One thing I overstated

I argued the plugin could not be ignoring the value, because changing it fixed production. That deployment shipped the preference change and a count-repair migration together, so it does not isolate the two on its own. What does support it is #96's local repro and the documented mechanism: 1 (copy) carries the row count with the rows, 3 (copy once) does not. Worth stating precisely rather than as a clincher.

Revised recommendation

Mirror the shape of #37 rather than scoping Layer 1:

• Move repeater / flexible_content into the Layer 2 doctrine bucket, whose message already says "doctrine, not a plugin fact".
• Under post_type / block, accept 1 and 3. Both are legitimate editorial choices — 3 when translations should diverge, 1 when the rows are identical in every language and copy-once would cost the feature. That is the same argument fix(wpml): accept copy-once on images, everywhere except options pages #37 made for images.
• On options pages, whatever the house rule says, labelled as doctrine.

Dropping the branch entirely is the reasonable runner-up. A warning severity is not, since src/ has no severity concept and --strict would fail on it anyway.

On the framing of the original report

One line above deserves rewording: I said the cited mechanism does not support the claim. Accurate, but it reads as a gotcha. The more useful framing is that #31 deliberately separated plugin-fact from doctrine, and this is a case of the fact having been mis-verified — the layering itself survives and is what makes the fix straightforward.

Happy to open the PR for the revised shape, with a failing fixture (post_type location, repeater at 1) so the change is mechanical.