Cats Module Laravel Package

Getting Started

This is a PyroCMS / Streams Platform module, not a standalone Laravel package. Treat it as a taxonomy/categories add-on that plugs into the Streams ecosystem rather than something you require into an arbitrary Laravel app.

Prerequisites

• A host application running pyrocms/pyrocms or the underlying streams-platform (this module uses Streams' service-provider, migration, and UI registration hooks).
• PHP version compatible with the host PyroCMS branch you're on. The 2023-11-13 release line will align with the current 3.x PyroCMS generation — check composer.json constraints before installing into an older 1.x/2.x install.

Install

composer require visiosoft/cats-module
php artisan migrate

Then locate the module in the PyroCMS admin under the Streams/modules area and enable/seed it as required.

Where to look first (in the source, in this order)

1. src/CatsModuleServiceProvider.php (or *ServiceProvider) — reveals registered Streams, routes, view namespaces, and admin navigation.
2. src/Cats/ (entity/stream definitions) — the Streams schema (fields, assignments) that defines what a "cat" actually is.
3. migrations/ — table creation, seed data, and field assignments; this is the fastest way to understand the data model.
4. resources/ — admin views and any Blade partials you can reuse or override.
5. config/ — plugin/module config keys, cache settings, and namespace options.

First use case The canonical scenario is attaching a category tree to an existing Streams entry type (posts, products, pages): register the cats stream as a relation, then render/filter entries by category. Build one category tree, attach it to one entry stream, and verify the admin UI + a front-end query before extending further.

Implementation Patterns

Streams-first integration

• Don't treat entities as Eloquent models. Use the Streams Repository ($stream->getRepository('cats') or the injected repo) for CRUD so field-type casting, translations, and events fire correctly.
• Query via the repository's criteria builder (fields, ordering, where on field slugs) rather than raw SQL against the generated table — schema is Streams-managed and field names are slugs, not columns you can assume.

Hierarchical categories

• Categories are typically modeled as a self-referential tree (parent field). For day-to-day use, wrap traversal in your own service/helper: getTree(), getBreadcrumb($slug), getDescendants($id). The module gives you the storage; traversal logic is usually your responsibility.
• For "entries in category and all descendants," resolve descendant IDs first, then query entries with whereIn. Caching the flattened descendant map per tree is the standard optimization.

Attaching to entries

• Create the relation as a Streams field assignment on your target stream (cats field type / many-to-many). Pivot tables are managed by Streams, so read the generated schema before hand-writing migrations or join queries.
• When seeding content, set relations through the repository's field API, not by inserting into pivot tables directly.

Admin + front-end

• Admin CRUD usually comes for free via the Streams module UI (the category stream appears in the control panel). Focus your code on views and APIs, not on building an admin panel.
• Publish/override module views with php artisan vendor:publish where supported, or via view namespace overrides in your own theme — check the service provider for registered namespaces like visiosoft.module.cats::.

Workflow that works

1. Migrate + enable module.
2. Seed a representative category tree (fixtures, not production data) to validate traversal and queries.
3. Register the relation on one entry stream.
4. Build a repository-backed query for "entries by category."
5. Only then wire up front-end rendering or APIs.

Gotchas and Tips

Adoption risk (score ~0.06, 0 stars, 0 dependents)

• There is little-to-no community surface: no issue backlog to mine, no Stack Overflow answers, few examples. Budget time to read the source directly and expect to debug by dd()/log, not by search.
• No dependents means no one else's usage is validating edge cases for you — pin the exact version ("visiosoft/cats-module": "0.1.x"-style constraint) and commit the lock file. Treat upgrades as breaking until diffed.
• Last release 2023-11-13 means it's stale relative to current Laravel/PyroCMS branches. Verify the host platform's Laravel version aligns before installing; the most common failure is a service provider that won't boot on a newer framework.

Configuration & compatibility

• This is not a general-purpose Laravel package — installing it into a plain laravel/laravel app will fail or no-op. Confirm streams-platform is present.
• Migration order matters: module migrations assume the Streams core tables exist. Run core migrations first, then module migrations.
• If the Streams admin UI doesn't show the module, check (a) the service provider is auto-discovered/registered, (b) the module is enabled in the CP, (c) cache: php artisan cache:clear && php artisan view:clear.

Querying pitfalls

• Field slugs ≠ column names. $repository->where('category', $x) targets the field slug; raw ->where('category_id', ...) may hit a generated column that differs. Always inspect the generated schema.
• Descendant queries without a cached map are N+1 traps — a tree traversal per request is the usual performance cliff.
• Watch for soft deletes and published/unpublished flags on the category stream; a "missing" category is often just filtered out by Streams' default criteria.

Debugging

• Repository queries return Streams entries, not models; ->toArray() may not show every field (field types like relations/grids lazy-load). Dump via field accessors.
• When admin saves fail silently, check Streams validation rules defined in the stream schema — required fields added in migrations are a frequent culprit.

Extension points

• Override views through the registered view namespace and publish tags.
• Extend the category stream by adding field assignments (migrations) rather than altering module tables — this keeps you upgrade-compatible.
• Wrap repository access in a small application-level service so that if you later replace this module, only that service changes. Given the low adoption, keeping the dependency contained is the pragmatic engineering call.