PHPackages                             madebyraygun/craft-block-loader - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. madebyraygun/craft-block-loader

ActiveCraft-plugin[Utility & Helpers](/categories/utility)

madebyraygun/craft-block-loader
===============================

Context loader for Craft CMS matrix blocks and nested entries.

3.1.5.1(3mo ago)1287[1 issues](https://github.com/madebyraygun/craft-block-loader/issues)MITPHPPHP >=8.2.0

Since Sep 11Pushed 2mo ago1 watchersCompare

[ Source](https://github.com/madebyraygun/craft-block-loader)[ Packagist](https://packagist.org/packages/madebyraygun/craft-block-loader)[ RSS](/packages/madebyraygun-craft-block-loader/feed)WikiDiscussions dev Synced 1mo ago

READMEChangelog (10)Dependencies (4)Versions (14)Used By (0)

Craft Block Loader
==================

[](#craft-block-loader)

This is a context loader for Craft CMS matrix blocks and nested entries. Use this plugin in conjunction with the [Craft Component Library](https://github.com/madebyraygun/craft-component-library) to format your block context to work with your component library.

See a sample implementation in the [Craft Component Library Demo](https://github.com/madebyraygun/craft-component-library-demo) repository.

Requirements
------------

[](#requirements)

This plugin requires Craft CMS 5.0 or later, and PHP 8.2 or later.

Installation
------------

[](#installation)

This plugin is not available in the Craft Plugin Store, but is published on Packagist and can be installed with Composer.

From the terminal:

```
composer require madebyraygun/craft-block-loader
php craft plugin/install block-loader

```

Configuration
-------------

[](#configuration)

By default, the plugin will initialize all block class definitions using the namespace `modules\blocks` in the `craft/modules/blocks` directory so make sure you have the proper [autoloading config](https://craftcms.com/docs/5.x/extend/module-guide.html#set-up-class-autoloading) in place. Where you tipically would have:

```
"autoload": {
  "psr-4": {
    "modules\\blocks": "modules/blocks"
  }
}
```

`ContextBlock` classes work outside the module initialization logic from CraftCMS but it is expected to have compliance with the [PSR-4](https://www.php-fig.org/psr/psr-4/) standard on the directory structure you define. To change these defaults, create a `block-loader.php` file in your Craft config directory to change this directory.

Sample config:

```
return [
  'blocksNamespace' => 'modules\blocks',
  'scanNewFiles' => false,
  'enableCaching' => true,
];
```

Scan New Files
--------------

[](#scan-new-files)

Available `ContextBlock` classes are automatically detected based on the `namespace` you define, but the `autoloader` will not pick up file changes until you regenerate the `autoloader` class map, which you can do by running `composer dump-autoload -a`. This can be a bit cumbersome during development. Instead, you can set the `scanNewFiles` setting to true, and the plugin will scan the directory for new files on every request. Just note that this is **not recommended** for production environments since performance can be affected.

Usage
-----

[](#usage)

Each class defined using the provided namespace `modules\blocks` is paired with each entry block inside a [Matrix Field](https://docs.craftcms.com/api/v5/craft-fields-matrix.html#matrix) or a [Ckeditor Field](https://github.com/craftcms/ckeditor) using their block handle. You need to extend from the `ContextBlock` class and implement the `getContext` method to return the context data for your block.

Example: `AnchorBlock.php`

```
namespace modules\blocks;

use craft\elements\Entry;
use madebyraygun\blockloader\base\ContextBlock;

class AnchorBlock extends ContextBlock
{
    public function getContext(Entry $block): array
    {
        return [
            'anchorId' => $block->anchorId,
        ];
    }
}
```

Not very exciting, but hopefully you see that this gives you the opportunity to return an *any* custom data you want for your block content.

More complex examples can extend the `ContextBlockSettings` class to change the settings on a per-block basis. Settings options include:

- `fieldHandle`: The `entry` type handle inside a `matrix` or `ckeditor` fields. By default this is auto-generated based on the classname. Example: a class `RichTextBlock` will look for a `richText` handle inside your fields.
- `templateHandle`: The handle to id each block. This can be any id you want to use to identify the block in your templates.
- `eagerFields`: Whether to [load fields eagerly](https://craftcms.com/docs/5.x/development/eager-loading.html) to improve performance on related or nested elements. Passed as an array of field handles like `['cards.image','cards.author']`.
- `cacheable`: Whether the results of the query should be cached (improves performance on large pages)

```
namespace modules\blocks;

use craft\elements\Entry;
use madebyraygun\blockloader\base\ContextBlock;

class RichTextBlock extends ContextBlock
{
    public function setSettings(): void
    {
        $this->settings
            ->templateHandle('richTextColumns')
            ->eagerFields([
                'richTextColumns',
            ]);
    }

    public function getContext(Entry $block): array
    {
        $columnsTable = $block->richTextColumns->all();
        $columns = [];
        foreach ($columnsTable as $column) {
            $columns[] = [
                'body' => $body = ($field ? (string) $field : '');
            ];
        }
        return [
            'align' => $block->align->value ?? 'left',
            'width' => $block->width->value ?? 'default',
            'columns' => $columns,
        ];
    }
}
```

### In your entry template

[](#in-your-entry-template)

```
{% set blocks = entry.blocksFromField('contentBlocks') %}
{% for item in blocks %}
  {% include '@content-blocks/' ~ item.templateHandle with item.context %}
{% endfor %}
```

Cache
-----

[](#cache)

The plugin will cache all blocks defined as `cacheable` in the context block settings. This will improve performance for blocks that don't change its context on a per-request basis. The blocks cache is cleared every time an Entry is saved, affecting only the blocks that are related to the saved entry.

If you need to clear the cache globally for all entries, you can do so from the Craft Control Panel under the `Utilities > Caches > Blocks context data` item or by running the `php craft clear-caches/block-loader` command from the terminal.

Additionally you can disable the caching for all blocks entirely by setting the `enableCaching` setting to `false` in the `block-loader.php` config file. This is useful for development environments where you want to see changes to your blocks immediately. But you may want to enable caching in production to improve performance.

### Expired entries

[](#expired-entries)

When an asset or an entry is saved, the cache is automatically cleared for related entries, but this action doesn't run when an entry expires rather than being saved. If you use the expiration feature and are concerned about expired entries showing up in related content blocks, use the console command `craft block-loader/expire-cache` to clear the block-loader cache specifically for entries that are related to entries that have expired since the last time the command was run.

Ckeditor Fields
---------------

[](#ckeditor-fields)

You can call `blocksFromField` function on an entry indistinctly of the field type (`Matrix` or `Ckeditor`). The plugin will automatically detect the field type and return the blocks in the same format. However, for `Ckeditor` fields the `markup` is by default wrapped as a block, you can pass the context into a specific component or just render the `markup` directly.

```
{% set blocks = entry.blocksFromField('ckEditorFieldHandle') %}
{% for item in blocks %}
  {% if item.templateHandle == 'markup' %}
    {{ item.context.content|raw }}
  {% else %}
    {% include '@content-blocks/' ~ item.templateHandle with item.context %}
  {% endif %}
{% endfor %}
```

For more advance preprocessing on the `markup` context blocks you can create your own class extending from `ContextBlock` class and implementing the `getMarkupContext` method. For this class to be automatically called the `fieldHandle` setting must be set to `markup`. Or just name the class `MarkupBlock` and the plugin will automatically derive the template handle from the class name as `markup`.

```
namespace modules\blocks;
use madebyraygun\blockloader\base\ContextBlock;

class MarkupBlock extends ContextBlock
{
    public function getMarkupContext(string $markup): array
    {
        // do some preprocessing on the markup before rendering
        $markup = preg_replace('//', '', $markup);
        return [
            'content' => $markup,
        ];
    }
}
```

### Nested entries within a matrix field

[](#nested-entries-within-a-matrix-field)

If you're using the CKEditor nested entries feature *within another matrix field*, be sure to extract the context for the nested entries within the context for that block:

```
public function getContext(Entry $block): array
{
    $blocks = BlocksProvider::extractBlockDescriptors($block, 'body');
    return [
        'blocks' => $blocks,
    ];
}
```

The markup for your rich text component will look similar to the CkEditor example above:

```

  {% for item in blocks %}
    {% if item.templateHandle == 'markup' %}
      {{ item.context.content|raw }}
    {% else %}
      {% include '@content-blocks/' ~ item.templateHandle with item.context %}
    {% endif %}
  {% endfor %}

```

###  Health Score

41

—

FairBetter than 88% of packages

Maintenance68

Regular maintenance activity

Popularity16

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity59

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 63.3% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~50 days

Recently: every ~114 days

Total

11

Last Release

100d ago

Major Versions

v1.x-dev → 3.0.02024-09-24

PHP version history (2 changes)2.0.0PHP >=8.2.0

1.0.2PHP >=8.0.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/e02ff0b466f74ebaa2909e2c366a1675d2d319aa5a35624e2a6fd74ffc6c73e9?d=identicon)[madebyraygun](/maintainers/madebyraygun)

---

Top Contributors

[![daltonrooney](https://avatars.githubusercontent.com/u/742045?v=4)](https://github.com/daltonrooney "daltonrooney (57 commits)")[![vanrez-nez](https://avatars.githubusercontent.com/u/3966786?v=4)](https://github.com/vanrez-nez "vanrez-nez (33 commits)")

### Embed Badge

![Health badge](/badges/madebyraygun-craft-block-loader/health.svg)

```
[![Health](https://phpackages.com/badges/madebyraygun-craft-block-loader/health.svg)](https://phpackages.com/packages/madebyraygun-craft-block-loader)
```

###  Alternatives

[barryvdh/laravel-ide-helper

Laravel IDE Helper, generates correct PHPDocs for all Facade classes, to improve auto-completion.

14.9k123.0M682](/packages/barryvdh-laravel-ide-helper)[spicyweb/craft-neo

A Matrix-like field type with block hierarchy

395798.1k10](/packages/spicyweb-craft-neo)[solspace/craft-freeform

The most flexible and user-friendly form building plugin!

52664.9k12](/packages/solspace-craft-freeform)[verbb/navigation

Create navigation menus for your site.

90683.7k17](/packages/verbb-navigation)[verbb/formie

The most user-friendly forms plugin for Craft.

101372.9k40](/packages/verbb-formie)[olvlvl/composer-attribute-collector

A convenient and near zero-cost way to retrieve targets of PHP 8 attributes

184108.8k8](/packages/olvlvl-composer-attribute-collector)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)