Streams Distribution Laravel Package

Getting Started

anomaly/streams-distribution is not a library you code against — it is a Composer distribution metapackage. Its job is to pin a known-good combination of the Streams platform (anomaly/streams) plus the standard first-party addons (fields, UI, users, pages, etc.) so a fresh install boots into a working control panel instead of a bare Laravel app with a dozen packages you have to wire up yourself.

Minimal steps:

composer require anomaly/streams-distribution
php artisan vendor:publish --tag=streams
php artisan streams:install
php artisan serve

1. Look first at composer.json of the package itself (in vendor/anomaly/streams-distribution). That require block is the real documentation — it tells you exactly which version of anomaly/streams and which addons you are running. Everything else in your day-to-day work happens against anomaly/streams, not against this package.
2. Then look at config/streams.php after publishing. That is where addon paths, the addons/ directory, and the streams cache live.
3. Then look at the addons/ directory. Streams ships with a default addon structure; your application-specific addon belongs there (e.g. addons/default/example/).

First real use case: stand up a Streams app, log into /admin, and create a stream through the control panel to confirm the distribution resolved cleanly. If the dashboard renders and you can define a stream and add a field, the distribution did its job. From that point on you are effectively a Streams developer, not a streams-distribution developer.

Implementation Patterns

Treat the distribution as your composition root, not as application code. Pin it in composer.json and let it pull the platform:

"require": {
    "anomaly/streams-distribution": "^1.0"
}

Then add your own addons alongside it. Every addon you write is a Laravel package with a service provider, and Streams discovers it via the addons directory — you almost never touch the distribution's own files.

Define streams in code, not clicks. The panel is great for prototyping, but reproducible streams belong in an addon's migrations or a seeder using the Streams repository:

use Anomaly\Streams\Platform\Stream\Contract\StreamRepositoryInterface;

public function up(StreamRepositoryInterface $streams)
{
    $streams->create([
        'namespace' => 'blog',
        'slug'      => 'posts',
        'name'      => 'Blog Posts',
    ]);
}

This is the pattern that makes environments reproducible and CI testable. Capture field assignments the same way (AssignmentRepositoryInterface) rather than relying on exported SQL.

Use the facade for entry work, the repositories for schema work. Streams::entries('blog', 'posts')->get() for runtime reads; repositories and migrations for structural changes. Mixing the two in a seeder is the usual source of flaky installs.

Keep one app addon per project. Put controllers, migrations, streams definitions, and field types in addons/default/{vendor}/{addon}/. This keeps your work upgradeable: when the distribution bumps anomaly/streams, your code lives outside the version-pinned surface.

Integration tip — lock the distribution in CI. Because this package pins a working matrix, adding a stray anomaly/* requirement at the app root is the fastest way to break that matrix. If you must add an addon, add it at the same caret range the distribution uses, then run composer update --dry-run to confirm no transitive drift.

Seeders over manual setup. A StreamsSeeder that builds namespaces, streams, fields, and sample entries gives you a one-command demo environment and doubles as documentation of your data model.

Gotchas and Tips

• There is no runtime API here. Do not use Anomaly\Streams\Distribution\... in application code. If you find yourself reaching into this package, you actually want anomaly/streams. Search the core repo when stuck — the distribution has essentially no code of its own.
• Version drift is the main failure mode. The distribution's value is an exact pinned matrix; a partial composer require of one addon can pull a newer anomaly/streams core and produce confusing panel errors. composer why anomaly/streams will show you who is holding the version back.
• The streams cache is aggressive. When migrations or field assignments appear not to apply, clear it before debugging anything else. Streams caches compiled stream definitions; a stale cache looks exactly like a broken migration. There is a compile/clear artisan command in the platform — check php artisan list for the exact name on your version.
• Config caching ordering. If you php artisan config:cache before publishing Streams config, the addon path resolution falls back to defaults and addons silently fail to load. Publish, verify, then cache in your deploy pipeline.
• Very low adoption (3 stars, 0 dependents) means you are the support channel. Expect to read the anomaly/streams source for answers, and expect the README to be thinner than the platform it wraps. Budget time for that.
• Extension points live in the platform, not the distribution. Overriding a field type, a view, or a stream definition is done by registering your own addon and using Streams' override/discovery mechanism. Patching files under vendor/ will be wiped on the next composer update.
• Debugging checklist, in order: composer show anomaly/streams (right version resolved?) → addons directory actually registered in config/streams.php → caches cleared → migrations ran in the expected namespace order. Most "broken install" reports resolve at step one or two.
• Upgrade discipline: bump anomaly/streams-distribution in a branch, run your seeders against a fresh database, and exercise the control panel before merging. Because it is a distribution, the upgrade is the change — there is no partial upgrade path worth attempting.