feat: datamachine_socials_platform_priority filter for ordering /platforms response

[chubes4]

Summary

Adds a datamachine_socials_platform_priority filter so any plugin can pin platform slugs to the top of the /datamachine/v1/socials/platforms response in declared order. Default behavior unchanged when nothing hooks the filter.

This is PR D of a 2-PR pair — extrachill-studio#25 hooks the filter to pin Instagram first.

Background

The previous /platforms contract sorted platforms (authenticated DESC, label ASC). That's the right default but not the right answer for every consumer. Studio wants Instagram pinned to the top because Extra Chill's social workflow centers on Instagram.

Two approaches were considered:

• Studio-local sort in React — re-introduces the client-side sort logic we just deleted in #131. Studio-only, so DM Socials' own Gutenberg sidebar wouldn't benefit.
• Server-side filter primitive — any plugin can hook in. Pure WP idiom. Future consumers (artist platform, venue dashboards, etc.) get the same primitive for free.

We picked the filter primitive.

Filter contract

/**
 * @param array $priority Ordered list of platform slugs to pin to the top. Default empty.
 */
$priority = apply_filters( 'datamachine_socials_platform_priority', array() );

Returns an ordered string[] of platform slugs. Slugs not in the list fall through to the default sort (authenticated → A-Z).

Behavior

1. Pinned slugs (in declared order)        ← from filter
2. Unpinned, authenticated (A-Z)
3. Unpinned, unauthenticated (A-Z)

Pinned + unauthenticated

Pinned slugs bypass the authenticated-first rule. If a caller pins an unauthenticated platform, it still appears at the top. This honors caller intent. Clients that only want to render authenticated platforms should filter on authenticated themselves (Studio's React already does this).

Defensive normalization

The filter result is run through array_filter(array_map('strval', ...)) and array_values(...) so plugins can't accidentally inject non-strings or sparse arrays. Empty/invalid filter results fall back to the default sort.

Verified locally

With add_filter('datamachine_socials_platform_priority', fn($p) => array_merge(['instagram'], $p)):

1. instagram   pinned
2. bluesky     unpinned authed A-Z
3. twitter     unpinned authed A-Z
4. facebook    unpinned unauthed A-Z
5. linkedin    unpinned unauthed A-Z
6. pinterest   unpinned unauthed A-Z
7. threads     unpinned unauthed A-Z

Without the filter (default behavior): unchanged from v0.13.0.

Test plan

• ✅ php -l clean
• ✅ Live preview with simulated Studio filter confirms Instagram pin
• ✅ Default (no filter) preserves v0.13.0 sort order
• ⏳ Studio sidebar manual check after PR E deploy

[homeboy-ci]

Homeboy Results — data-machine-socials

Audit

⚡ Scope: changed files only

✅ audit (changed files only)

• Alignment score: 0.781
• Outliers in current run: 25
• Drift increased: no
• Severity counts: info: 2, unknown: 25, warning: 2
• Top actionable findings:
  1. inc/RestApi.php — god_file — File has 1377 lines (threshold: 1000)
  2. inc/RestApi.php — intra_method_duplicate — Duplicated block in register_routes — 6 identical lines at line 223 and line 273
  3. inc/RestApi.php — missing_test_file — No test file found (expected 'tests/Unit/RestApiTest.php')
  4. inc/RestApi.php — repeated_literal_shape — Repeated literal shape ['success' => , 'error' => ] appears 23 time(s); top files: inc/RestApi.php (22), inc/Handlers/LinkedIn/LinkedInAuth.php (1); estimated LOC reduction: ~63
  5. inc/Handlers/Bluesky/BlueskySettings.php — outlier — (outlier)
  6. inc/Abilities/Bluesky/BlueskyPublishAbility.php — outlier — (outlier)
  7. inc/Cli/Commands/SharesCommand.php — outlier — (outlier)
  8. inc/Cli/Commands/LinkedInCommand.php — outlier — (outlier)
  9. inc/Cli/Commands/TwitterCommand.php — outlier — (outlier)
  10. inc/Cli/Commands/PinterestCommand.php — outlier — (outlier)

Audit findings (10 shown)

1. **inc/RestApi.php** — god_file — File has 1377 lines (threshold: 1000)
2. **inc/RestApi.php** — intra_method_duplicate — Duplicated block in `register_routes` — 6 identical lines at line 223 and line 273
3. **inc/RestApi.php** — missing_test_file — No test file found (expected 'tests/Unit/RestApiTest.php')
4. **inc/RestApi.php** — repeated_literal_shape — Repeated literal shape ['success' => <bool>, 'error' => <string>] appears 23 time(s); top files: inc/RestApi.php (22), inc/Handlers/LinkedIn/LinkedInAuth.php (1); estimated LOC reduction: ~63
5. **inc/Handlers/Bluesky/BlueskySettings.php** — outlier — (outlier)
6. **inc/Abilities/Bluesky/BlueskyPublishAbility.php** — outlier — (outlier)
7. **inc/Cli/Commands/SharesCommand.php** — outlier — (outlier)
8. **inc/Cli/Commands/LinkedInCommand.php** — outlier — (outlier)
9. **inc/Cli/Commands/TwitterCommand.php** — outlier — (outlier)
10. **inc/Cli/Commands/PinterestCommand.php** — outlier — (outlier)

Tooling versions

• Homeboy CLI: homeboy 0.100.0+8caf0755d
• Extension: wordpress from https://github.com/Extra-Chill/homeboy-extensions
• Extension revision: unknown
• Action: Extra-Chill/homeboy-action@v2

---

Homeboy Action v1