Phpunit Data Provider Laravel Package

Getting Started

Install the package as a dev dependency:

composer require --dev rawr/phpunit-data-provider

Then import the entry point:

use TRegx\PhpUnit\DataProviders\DataProvider;

Your first use case is eliminating duplicated data definitions. Instead of copying ['user' => 'alice', 'role' => 'admin'] across multiple @dataProvider methods, define a reusable base and combine it:

public function userPermissions(): iterable
{
    return DataProvider::cross(
        DataProvider::list(['alice', 'bob']),
        DataProvider::list(['read', 'write', 'delete'])
    );
}

Always start with DataProvider::list(), ::of(), or ::entries()—then chain combinators like ::cross(), ::join(), or ::zip().

Implementation Patterns

• Data composition pipelines: Chain transformations to avoid repetition:

  $testData = DataProvider::list([1, 2, 3])
      ->filter('is_int')
      ->map(fn($x) => $x * 2)
      ->cross(DataProvider::list(['sync', 'async']));
  

• Key-aware test cases (v3.3.0+): Use ::entries() when keys are meaningful (e.g., status codes or enums):

  public function statusEndpoints(): iterable
  {
      return DataProvider::entries([
          'draft'    => ['status' => 0, 'label' => 'Draft'],
          'active'   => ['status' => 1, 'label' => 'Active'],
          'archived' => ['status' => 2, 'label' => 'Archived'],
      ]);
  }
  // Test receives: $key = 'draft', $value = ['status' => 0, 'label' => 'Draft']
  

• Cross for matrix testing: Combine product dimensions (e.g., browser + OS + API version) in one provider:

  return DataProvider::cross(
      DataProvider::list(['Chrome', 'Firefox']),
      DataProvider::list(['macOS', 'Linux']),
      DataProvider::list(['v1', 'v2'])
  );
  

• Reusable factories: Centralize common test data shapes:

  public static function authenticatedUserProvider(): DataProvider
  {
      return DataProvider::list(['alice', 'bob'])
          ->map(fn($name) => new User($name, ['role' => 'admin']));
  }
  

• Adapting legacy arrays: Wrap raw arrays with ::of() for transformation:

  return DataProvider::of($this->loadUsersFromFixture())
      ->filter(fn($user) => $user->isActive())
      ->zip(DataProvider::list(['success', 'warning']));
  

Gotchas and Tips

• Namespace migration: v3+ uses \TRegx\PhpUnit\DataProviders\, not \TRegx\DataProvider\. Update imports and avoid mixing old and new namespaces—silent failures may occur.
• Strict type handling: Values 4 (int) and "4" (string) are always treated as distinct rows. This prevents edge-case bugs but may break assumptions in tests expecting loose comparison.
• Fluent order matters: Filter early to reduce memory/cpu overhead: filter()->map() instead of map()->filter().
• Debugging: Use the undocumented ->debug() method mid-chain to dump intermediate results:

  return DataProvider::list([1, 2, 3])->filter('is_int')->debug()->map(...);
  

• Return types must be explicit: Return iterable|DataProvider, not array. Returning array in strict mode may cause TypeError or silent truncation.
• Beta features: Check the README for ::flatMap(), ::reindex(), ::reindexTo()—these enable advanced reshaping (e.g., flattening nested arrays for parameterized endpoint tests).
• PHP version: Requires PHP 7.1+, but Laravel projects (v9+) meet this; confirm PHPUnit 10+ compatibility (currently unconfirmed per docs).
• Memory for large datasets: For 10k+ rows, prefer generators in ::of() over in-memory arrays to avoid exhaustion.