IRL - Woo Fast Search Plugin - Wholesale filter contract mismatch wipes customers and breaks response shape

[noelsaw1]

Short answer

Not with the current WPCC stack.

• Static grep rules and the PHP golden rules analyzer are designed for local, syntactic patterns (e.g., “unbounded WP_Query”, “unsanitized superglobal”, “file_get_contents on URL”), not cross‑function data‑structure contract checks.
• The bug you described is a contract mismatch across multiple functions/classes (search_customers() → filter interface → Ajax handler → JS expectations). That’s semantic / type‑shape logic, which our current grep‑based system doesn’t model.

So: this specific “flat array vs hash” mismatch would not be reliably caught by the existing scanner or golden rules analyzer.

---

Why this kind of bug is hard for grep / golden rules

Your bug is essentially:

• Producer: search_customers() returns array<Customer> (flat list).
• Filter contract: apply( $results ) expects ['customers' => [...], 'guest_orders' => [...], 'orders' => [...]].
• Filter apply() checks isset( $results['customers'] ) and, if not present, returns ['customers' => [], 'guest_orders' => [], 'orders' => []].
• Ajax handler then:
  • Treats this hash as “customers payload”
  • JS expects data.customers to be an array, but instead gets { customers: [], guest_orders: [], orders: [] }.

To detect this statically you’d need to:

1. Track what shape search_customers() returns.
2. Track that it passes that value through a filter (or interface method).
3. Know the intended shape in the filter interface (interface-kiss-woo-order-filter.php).
4. Compare the shapes and see they’re incompatible.

Our current system:

• Doesn’t track return types or array shapes across functions.
• Doesn’t understand hook/filter contracts beyond string matching on hook names.
• Golden rules are largely single‑file, regex + small validator script checks, not inter‑procedural type analysis.

That’s the kind of thing tools like PHPStan/Psalm with strict types or runtime tests are good at, but it’s beyond what a pure grep + line‑window validator can reliably do.

---

Could we add some heuristic for this class of bug?

We could design very narrow, heuristic rules for this plugin, for example:

• Flag filters whose apply():
  • Return a structure like ['customers' => [], 'guest_orders' => [], 'orders' => []], and
  • Are wired into code that later treats the filter result as a flat array (e.g., foreach ( $customers as $customer ) without going through $customers['customers']).

Or:

• Flag any place where a function named *search_customers*:
  • Calls apply_filters( 'kiss_woo_wholesale_filter', $results ), and
  • Subsequently treats $results as a flat list, while there exists a filter implementation that wraps it into a hash.

But:

• That would be highly plugin‑specific and brittle.
• It still wouldn’t be generally reliable across arbitrary codebases.

For a general solution, you’d want one or more of:

• Static typing (PHPStan/Psalm) with:
  • Return type for search_customers(): array<Customer>
  • Interface defining apply(array{customers: list<Customer>, guest_orders: list<...>, orders: list<...>})
  • Those tools would then complain when the types don’t line up.
• Runtime tests:
  • Unit test that calls search_customers() with the “Wholesale only” flag and asserts the result shape matches what JS expects, and that customers aren’t wiped.

---

Bottom line

• Today:

  • Our static grep scanner and the PHP golden rules analyzer will not catch this “hash vs flat array” mismatch in a dependable way.
  • They don’t model data shapes, interfaces, or cross‑function contracts.

• To catch this class of issue well, you’d need:

  • Type‑aware static analysis (PHPStan/Psalm or similar) or
  • Focused unit/integration tests that assert the response shape under “Wholesale only” (including guest_orders).

If you want, I can outline what a minimal test (PHPUnit or WP_UnitTestCase) would look like to lock this bug down, or sketch how a PHPStan rule for your KISS_Woo_Order_Filter interface might be structured.

[noelsaw1]

It’s a very good motivating use case, but only a medium‑complexity first check for PHPStan/Psalm—not the simplest possible one.

Let me walk through your criteria.

---

How this scenario scores vs your criteria

1. “Simple”

Mixed.

To have PHPStan/Psalm reliably catch this, you’d want at least:

• A precise return type for search_customers():

  /**
   * @return list<Customer>
   */
  function search_customers(): array { ... }

• A precise parameter/return type for the filter interface:

  /**
   * @param array{
   *   customers: list<Customer>,
   *   guest_orders: list<GuestOrder>,
   *   orders: list<Order>
   * } $results
   * @return array{
   *   customers: list<Customer>,
   *   guest_orders: list<GuestOrder>,
   *   orders: list<Order>
   * }
   */
  public function apply( array $results );

• And then wire it so search_customers() actually passes its output into something with that shape.

That’s not hard, but it isn’t the trivial case of “function claims to return int but returns string”. You’re immediately using:

• Array shapes
• Cross‑function contracts
• WordPress-ish architecture (filters, multiple files)

So: it’s simple for someone already comfortable with PHPStan/Psalm, but not “hello world” simple.

---

2. “Fast”

Yes, once configured.

• The check itself is cheap: PHPStan/Psalm run quickly once the project is set up.
• This scenario doesn’t require deep inference; once the shapes are declared, the tools can flag mismatches essentially for free.

The time cost is mostly initial setup:

• Adding the tool (composer dev‑dependency).
• Configuring autoloading / bootstrap for WordPress.
• Possibly adding a baseline file to suppress existing noise.

---

3. “Easy”

Moderate.

For this scenario to work smoothly as a first target, you’d need to:

1. Decide on your canonical contract (flat array vs structured hash) and document it.
2. Add type/shape annotations to:
   • search_customers()
   • The filter interface
   • The wholesale filter implementation
3. Possibly refactor call sites slightly so the shapes are clean and consistent.

None of that is scary, but it’s more than “flip on PHPStan at level 0 and read what it says.” So as an intro to PHPStan/Psalm for the team, it’s medium difficulty, not minimal.

---

4. “Meaningful check and useful for developers”

Absolutely yes.

• It’s a real IRL bug, not a contrived example.
• It touches exactly what static analysis is good at:
  • “Producer returns X, consumer expects Y.”
  • Code runs fine at runtime until a particular flag/branch is used.
• If you show developers, “PHPStan would have caught this contract mismatch before it shipped,” that’s high‑credibility proof that the tool is worth having.

On the “meaningful” axis, this is an excellent first story.

---

Recommendation

Short version:

• Use this bug as your flagship / north‑star example for why PHPStan/Psalm is valuable.
• But for the very first integration steps, I’d start with slightly simpler checks and then grow into this scenario as Milestone Development to Main #2.

Suggested order

1. Phase 1 – Minimal integration & low‑hanging fruit

   • Add PHPStan or Psalm at a low level (e.g. PHPStan level 1–3).
   • Let it run across the plugin and:
     • Catch obvious return/param mismatches.
     • Catch impossible property access, nullable misuse, etc.
   • Fix a few easy wins so devs see quick value with low cognitive load.

2. Phase 2 – Model this wholesale search contract

   Use this exact scenario as your first “typed design” milestone:

   • Decide: flat array vs structured hash (your Option A vs B).
   • Add phpDoc/array shapes (or small DTO classes) to:
     • search_customers()
     • interface-kiss-woo-order-filter.php
     • KISS_Woo_Wholesale_Filter::apply()
   • Introduce one small intentional mismatch in a branch to prove PHPStan/Psalm catches it.
   • Once verified, remove the mismatch and keep the types as guard rails.

This way:

• You keep the initial integration “simple/fast/easy”.
• You still use this high‑value IRL bug as the first serious, cross‑function contract check once the basics are in place.

---

Direct answer to your question

Would this particular current scenario be a useful first test use case…?

• Useful and meaningful? Yes, very.
• Simple/easy as the first check? It’s medium complexity, not the gentlest possible intro.
• I’d treat it as the first “real” milestone check after the tool is in place, rather than the literal first thing you try the moment PHPStan/Psalm is installed.

If you’d like, next I can sketch the exact phpDoc / type signatures for search_customers(), the filter interface, and the wholesale filter in both Option A (structured hash) and Option B (flat list), so you can see what PHPStan/Psalm would be looking at.

[noelsaw1]

#104