Featured Posts Block Extension Laravel Package

Getting Started

1. Check compatibility first. Open this package's composer.json and confirm its require constraints against your project's PyroCMS / Streams Platform version. This is a first-party micro-extension with no dependents, so treat the source as the documentation.
2. Install it like any PyroCMS addon:

   composer require anomaly/featured_posts_block-extension
   php artisan addon:install anomaly/featured_posts_block-extension
   php artisan view:clear && php artisan cache:clear
   

   Verify registration with php artisan addon:list.
3. Where to look first:
   • src/FeaturedPostsBlockExtension.php — the extension class, its $provides slug, and the block/form registration.
   • src/Block/ — the Block class that returns the view and the data (this is where the "featured" query lives).
   • resources/views/ — the render template.
   • resources/lang/ — field labels and block name/description.
   • Any resources/config/ form definition for the block's admin fields.
4. First use case: ensure the Posts module is installed and that posts have the "featured" flag the block filters on. Then in the admin go to Blocks, create a new block, pick the Featured Posts type, set options (count, category, ordering if exposed), assign it to a block area, and render that area in a page layout or theme partial. Confirm the block's data method to see exactly which field/scope it uses before assuming the flag name.

Implementation Patterns

• Admin-first configuration. Blocks are instances of a type, so create one block per placement (homepage hero, sidebar, footer) and configure each independently. Editors manage content; you manage placement via page layouts and block areas.
• Render via the Blocks plugin/helper in your layouts, e.g.:

  {{ blocks('home-featured').render()|raw }}
  

  The exact helper depends on your Blocks module version — confirm in the module's own docs/source.
• Theme override over vendor edits. If the markup doesn't fit, override the block's view from your theme (same namespace path) or, since the surface area is tiny, fork the extension into your own namespace. Never edit vendor/ directly.
• Keep data logic out of the view. The Block class is the natural seam: return the query result from getData() (or equivalent), and keep the template presentation-only. If you need the data outside a block, inject the Posts repository directly instead of resolving a block:

  use Anomaly\PostsModule\Post\Contract\PostRepositoryInterface;
  
  $posts = app(PostRepositoryInterface::class)
      ->where('featured', true)
      ->limit(3)
      ->get();
  

  Replace where('featured', true) with whatever scope/field the package's Block class actually uses.
• Compose with the Pages module. Use block areas in page layouts rather than hardcoding block IDs in templates, so editors can swap blocks without a deploy.
• Fork as a template. The extension is a good starting point for variants ("featured posts by category", "latest featured from a tag"); copy the structure and change the query rather than fighting the original.

Gotchas and Tips

• Maintenance risk is real. Zero dependents and no meaningful stars means the source is the spec. Pin the Composer version and read src/ before relying on behavior; expect no changelog or upgrade path.
• API drift across PyroCMS 3.x. The BlockExtension/Block base class contracts changed over Streams Platform releases. If the block type never appears in the admin, check php artisan addon:list, then storage/logs/laravel.log — a signature mismatch or namespace/autoload issue is the usual culprit.
• Empty output almost always means the featured flag isn't set (or the field doesn't exist on the posts stream). Verify the posts themselves, not the block, before debugging the template.
• Caching. If the block class caches its data or the view is cached, content changes may not appear. Run php artisan view:clear and php artisan cache:clear, and check whether the block's data method memoizes.
• Compiled views live in storage/framework/views. If an override isn't taking effect, confirm which view path is actually being resolved (namespace vs. filesystem path) before assuming the file was ignored.
• Permissions. Managing blocks is a Blocks module permission, separate from page editing. Editors who "can't see the block" often lack the block-management role, not the content.
• Debugging tip: temporarily dd($this->getData()) inside the block class, or resolve the block in php artisan tinker and inspect it. Faster than guessing from rendered HTML.
• Extension points: the block's data method and its view are the only meaningful seams. Anything beyond that (new filters, different ordering, alternate markup) is cleanest as a forked extension in your own vendor namespace, which also protects you from upstream changes.