Testing Bundle Laravel Package

Getting Started

Reality check first: ongr/testing-bundle is a Symfony/ONGR package, not a Laravel one. It ships no service provider, no facade, no publishable config, and targets the ongr/elasticsearch-bundle (ESB) stack circa Elasticsearch 1.x. The repo is archived and the last tag is from November 2014. Treat it as a reference implementation, not a dependency you drop into a Laravel app.

Minimal steps if you still want to inspect or vendor it:

# Not on Packagist in a usable state for modern PHP; pull the source directly
git clone https://github.com/ongr-archive/TestingBundle /tmp/ongr-testing-bundle

Then read, in order:

1. composer.json — confirms the hard requirements: ongr/elasticsearch-bundle, symfony/framework-bundle, phpunit/phpunit (3.x/4.x era), PHP >=5.4.
2. README.md and the Tests/ directory — the fixtures and example ESB document classes are the actual payload; the bundle itself is thin.
3. The Document/ and Fixtures/ folders — annotated PHP document classes plus the loader that bulk-indexes them.
4. Cross-reference with the ONGR ElasticsearchBundle docs for how documents, managers, and index aliases work.

First use case to crib from: seeding a real Elasticsearch index with known documents so a functional test can assert on query results, then tearing the index down. In a Laravel app you reproduce that pattern with elasticsearch/elasticsearch (or Elastica) in a test trait — you do not need this bundle to get the behavior.

Implementation Patterns

Fixture-per-test trait (Laravel translation of the bundle's intent). The bundle's core idea is: define documents as PHP classes, load them into a live index, refresh, assert, delete. Emulate it:

trait ElasticFixtures
{
    protected Client $client;
    protected string $index;

    protected function setUpElastic(): void
    {
        $this->index  = 'test_' . Str::random(8);
        $this->client = ClientBuilder::create()
            ->setHosts(config('scout.elasticsearch.hosts'))
            ->build();

        $this->client->indices()->create([
            'index' => $this->index,
            'body'  => ['mappings' => $this->mappings()],
        ]);
    }

    protected function seed(array $docs): void
    {
        $body = [];
        foreach ($docs as $doc) {
            $body[] = ['index' => ['_index' => $this->index]];
            $body[] = $doc;
        }
        $this->client->bulk(['body' => $body]);
        $this->client->indices()->refresh(['index' => $this->index]);
    }

    protected function tearDownElastic(): void
    {
        if (isset($this->client, $this->index)) {
            $this->client->indices()->delete(['index' => $this->index, 'ignore_unavailable' => true]);
        }
    }
}

Where the bundle's example documents help. Their annotated document classes double as canonical mappings: fields, analyzers, date formats. Copy the mapping shape into your mappings() method rather than trying to boot the annotation reader in Laravel.

Symfony-side wiring (if you ever run it in its native habitat). Register Ongr\Bundle\TestingBundle\OngrTestingBundle in AppKernel, point ongr_elasticsearch.managers.default.index at a disposable *_test index, and let the bundle's fixture loader hydrate it before each functional test. That is the only integration shape the package supports.

In Laravel, prefer the sanctioned stack instead:

Data provider pattern. Example documents make good PHPUnit data providers for query-building unit tests — you get realistic field values without touching a live cluster. This is the one place the package's fixtures are genuinely useful: as static JSON/PHP arrays.

Gotchas and Tips

• Abandoned and version-locked. No commits since the archive; PHP >=5.4, Symfony 2.x, PHPUnit 3/4, Elasticsearch 1.x. Installing it in a PHP 8 / Laravel 10+ project will fail dependency resolution or, worse, resolve against ancient transitive packages that break other things.
• Annotation metadata. ESB documents rely on Doctrine annotations. Modern projects use PHP 8 attributes, and doctrine/annotations is deprecated. You cannot simply require the document classes and expect metadata to load.
• ES version drift is fatal, not cosmetic. ESB 1.x mappings use type/_type, string fields, and filter (not query) in some places. On ES 7/8 those requests 400. If you copy the example documents, port them to keyword/text and drop mapping types.
• No Laravel container bindings. There is no OngrTestingBundleServiceProvider. Trying to register the bundle's services by hand drags in symfony/framework-bundle, symfony/dependency-injection, and the ONGR compiler passes — a large detour for what a 40-line test trait gives you.
• refresh is mandatory before assertions. Near-real-time indexing means a bulk() followed immediately by a search() returns stale results. The bundle does this internally; your port must call indices()->refresh() (or ?refresh=true on writes) or tests flake intermittently. This is the single most common source of "works locally, fails in CI" in ES test suites.
• Index leakage between tests. Always generate a unique index name per test and delete it in tearDown, including on failure. Shared test_index names produce order-dependent failures that are painful to reproduce. Consider ignore_unavailable => true on delete.
• Alias footgun. ESB tests typically assert against an alias pointing at a physical index. In Laravel, skip aliases entirely for tests — point directly at the concrete index; alias swap logic belongs in deploy tooling, not test setup.
• Debugging. When a request fails opaquely, log json_encode($body) plus $response->getTransferInfo('url'); the ES error body in getResponse()->getBody() contains the actual reason (usually a mapping mismatch). Running the cluster with discovery.type=single-node and matching versions (via Docker image pinned to your client major version) eliminates most "works in prod, not in test" noise.
• Extension points that actually exist: the fixture loader is a plain service, and the example documents are ordinary classes — both are forkable/copyable. That is the right move: copy the fixture arrays into tests/Fixtures/, discard the bundle. Two stars and zero dependents mean no upstream to wait on.
• Bottom line for a Laravel assessment: adopt the pattern (per-test index, bulk seed, refresh, teardown, realistic document fixtures), not the package. Build it on elasticsearch/elasticsearch or Laravel Scout, and budget an afternoon instead of a dependency-audit rabbit hole.