>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3600769. --> Reported by: [hydra](https://www.drupal.org/user/647364) Related to !23 >>> <h2>Problem/Motivation</h2> <p>The original implementation of site overrides composed an "effective" entity at <em>read time</em> by merging individual overrideable fields from a site-specific override revision onto the canonical revision (<code>SiteAwareEntityResolver::mergeFields()</code>). This field-by-field merge approach made several things hard:</p> <ul> <li>Sub-field-level overrides (e.g. individual values inside a compound field such as <code>behaviors</code>) were not possible without bespoke per-field merge logic.</li> <li>Submodules that need a "real", loadable entity for the current site (Layout Builder sections, Content Moderation state, revision history) had to work around a synthetic, never-saved "effective" entity that didn't correspond to any stored revision.</li> <li>Keeping overrides up to date when the canonical revision changes required ad-hoc logic instead of one well-defined re-sync step.</li> </ul> <p>This issue also tracks the remaining work needed to publish a first stable 1.0.0 release of the module.</p> <h2>Proposed resolution</h2> <p>Move to a <strong>full-snapshot override model</strong>:</p> <ul> <li>Each site override is now a <em>complete revision</em> of the entity (identified by <code>site_id</code>), not a virtual merge. <code>loadEffective()</code> simply returns the latest override revision for the current site, or the canonical revision otherwise &mdash; no more read-time field merging.</li> <li><code>site_override_fields</code> tracks which fields are "pinned" (intentionally diverged) on a given override revision.</li> <li><code>SiteAwareEntityResolverInterface::buildSnapshot()</code> builds a new override snapshot from the canonical revision plus the pinned fields from a source revision, and invokes the new <code>hook_sites_content_overrides_snapshot_alter()</code> so submodules can perform sub-field-level merging (used by <code>sites_content_overrides_behaviors</code> for the <code>behaviors</code> field).</li> <li><code>SiteAwareEntityResolverInterface::resyncOverrides()</code> re-snapshots all existing site overrides whenever the canonical revision is saved, so non-pinned fields stay in sync automatically (<code>getOverriddenSiteIds()</code> finds all sites with an override).</li> <li>Adds <code>sites_content_overrides.install</code> with update hooks 10001/10002 to migrate existing sites from the old merge-based model to the new snapshot model.</li> </ul> <h2>API changes</h2> <ul> <li><code>SiteAwareEntityResolverInterface::loadEffective()</code> no longer returns <code>NULL</code> (always returns the canonical or override revision).</li> <li>New hook: <code>hook_sites_content_overrides_snapshot_alter(ContentEntityInterface &amp;amp;$snapshot, array $context)</code>.</li> <li>New methods on <code>SiteAwareEntityResolverInterface</code>: <code>buildSnapshot()</code>, <code>getOverriddenSiteIds()</code>, <code>resyncOverrides()</code>.</li> </ul> <h2>Remaining tasks</h2> <ul> <li>Core: <code>SiteAwareEntityResolver</code>/<code>SitesContentOverridesService</code> snapshot-model refactor, update hooks, schema/service changes</li> <li>Adapt <code>sites_content_overrides_revisions_ui</code> to the snapshot model</li> <li>Adapt <code>sites_content_overrides_content_moderation</code> to the snapshot model</li> <li>Adapt <code>sites_content_overrides_layout_builder</code> to the snapshot model; replace deprecated <code>hook_module_implements_alter()</code> usage with <code>#[Hook('entity_presave')]</code> + <code>#[RemoveHook(...)]</code></li> <li>Adapt <code>sites_content_overrides_behaviors</code> to the snapshot model via <code>hook_sites_content_overrides_snapshot_alter()</code></li> <li>Add/extend kernel test coverage for the update path and all submodules</li> <li>Update <code>README.md</code> with a "How It Works" section documenting the snapshot model</li> <li>Add <code>CHANGELOG.md</code></li> <li>Add <code>.gitlab-ci.yml</code> (enable phpstan) and <code>phpstan.neon</code> / baseline</li> </ul>