Post Categories Block Extension Laravel Package

Getting Started

This is a PyroCMS 3.x addon (Anomaly Labs "extension") that contributes a single block type to the block picker: a rendered list of categories from the Posts module. It is not a Laravel package you use in application code — it is an addon that hooks into the Streams Platform addon lifecycle, so "getting started" means installing it into a PyroCMS application, not a plain Laravel app.

Minimal steps:

1. From your PyroCMS project root, install via composer:

   composer require anomaly/post_categories_block-extension
   

   Given the package has no packagist traction (0 dependents), be prepared to fall back to a VCS repository entry or a manual clone into addons/default/anomalylabs/posts_categories_block-extension/.
2. Install and enable the addon:

   php artisan addon:install anomaly.post_categories_block-extension
   

3. Confirm the dependency anomaly/posts-module is installed — this block reads that module's category stream, and it will render empty (or throw) without it.
4. Go to Admin → Pages → (a page) → Blocks, pick the posts-categories block, and assign it to a page/partial area.

Where to look first, in the addon source:

• src/PostsCategoriesBlockExtensionServiceProvider.php — registers the block, view namespace, and any bindings.
• src/PostsCategoriesBlockExtension.php (the block class) — $name, $category, $fields(), and $stream are where the behavior actually lives. Read fields() first; that is your entire configuration surface.
• resources/views/blocks/ — the Twig template that produces the markup you will almost certainly need to override.
• resources/lang/en/addon.php — name/description, useful for confirming the addon slug you should pass to artisan.

First realistic use case: a sidebar or footer "Browse by category" widget on a blog page. Place the block in a partial area, set the category limit/ordering in the block form, and the block renders category names linked to the Posts module's category route (typically posts/category/{slug} — verify against your Posts module route config rather than assuming).

Implementation Patterns

Block placement, not code. The intended workflow is entirely admin-driven: the block is added to a page, page type, or partial area through the Pages module's block picker. Your job as a developer is usually limited to (a) configuring the block fields and (b) overriding the view. Treat the block form as the API.

Override the Twig view rather than editing the addon. Publish the addon's views into your theme namespace and shadow them:

php artisan addon:publish anomaly.post_categories_block-extension

Then copy/extend the block template under your theme's resources/views/ using the addon's view namespace. Keeping overrides in the theme means composer update cannot clobber your markup — important here, because with 0 stars and 0 dependents the upstream is unlikely to accept or ship your fixes.

Pair it with the Posts module's own views. The block's value is as a navigation surface. Render category links that match the route your Posts module actually exposes, and keep the slug source consistent — if the Posts module stores categories in a categories stream with slug and name columns, reference those exact field handles. Mismatched handles are the #1 cause of a blank block.

Compose with other blocks via partials. Put the categories block in a partial area alongside a "recent posts" block and include that partial in layout.twig. This is the idiomatic Pyro way to build a sidebar without touching PHP.

Scope the query in the block fields, not in Twig. Block fields are declarative Streams fields; anything resembling limit, ordering, or parent-category filtering belongs there so editors can change it without a deploy. Resist the urge to hardcode limit in the template.

Extend by registering your own block. If you need logic the block doesn't express (e.g. filter to categories that have at least one published post), write a small custom block extension in your own addon that reuses the same stream query builder, rather than forking this one. The block class is small enough to copy as a starting point; the service provider registration is the only boilerplate.

Caching. Pyro blocks participate in the page/block cache. If you see stale categories after publishing a post, that is the block cache, not a bug in this addon — clear it as part of your publish workflow or disable caching on the page during development.

Gotchas and Tips

• Effectively unmaintained. 0 stars, 0 dependents, no listed activity. Do not build a client deliverable that depends on upstream fixes. Vendor it, pin it, and assume you own the code from day one.
• Composer constraint drift. Anomaly addons commonly pin anomaly/streams-platform to an older ~1.x range. On a newer PyroCMS you will likely hit a resolution conflict — install with --ignore-platform-reqs only as a diagnostic, then correct the constraint in a fork rather than leaving it ignored.
• The addon slug is not the composer name. anomaly/post_categories_block-extension (composer) vs anomaly.post_categories_block-extension (artisan slug). Passing the wrong one to addon:install yields a confusing "addon not found."
• Silent empty output. A block that renders nothing is almost always a stream/field handle mismatch or a missing anomaly/posts-module. Check the addon is enabled (php artisan addon:list), then dump the categories stream directly before blaming the template.
• Block doesn't appear in the picker. Run php artisan view:clear && php artisan cache:clear and re-check the addon's addon.php category — blocks are grouped, and a missing category can hide it from the picker's expected tab.
• Streams compilation after edits. If you modify the block's fields(), the Streams schema can go stale. php artisan streams:compile (or reinstall the addon) is the reliable reset.
• Route assumptions in the template. The bundled view will assume a category URL pattern. If your Posts module uses a localized or prefixed route, every link in the block will 404 — this is the first thing to verify after install, and the most common reason to override the view.
• Multisite/multilingual. Category names are stream entries; check whether the Posts module's categories stream is translatable in your setup before promising localized category labels. If it isn't, the block will show one language everywhere.
• Extension points you actually have: the block view (override), the block fields (configure), and block registration (replace with your own). There is no event/listener surface worth relying on in an addon this size — do not expect to hook behavior without editing the class.
• Debugging tip: temporarily render {{ dump() }} (with Twig debug enabled in dev) inside your overridden block view to inspect what the block is actually handing the template; it removes all guesswork about which fields are populated.