PHPackages                             okipa/laravel-brickables - 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. [Admin Panels](/categories/admin)
4. /
5. okipa/laravel-brickables

AbandonedArchivedLibrary[Admin Panels](/categories/admin)

okipa/laravel-brickables
========================

Page content bricks management made easy.

3.2.0(3y ago)97.2k3[1 issues](https://github.com/Okipa/laravel-brickables/issues)MITPHPPHP 8.1.\*|8.2.\*

Since Feb 14Pushed 2y ago1 watchersCompare

[ Source](https://github.com/Okipa/laravel-brickables)[ Packagist](https://packagist.org/packages/okipa/laravel-brickables)[ Docs](https://github.com/okipa/laravel-brickables)[ Fund](https://paypal.me/arthurlorent)[ GitHub Sponsors](https://github.com/Okipa)[ RSS](/packages/okipa-laravel-brickables/feed)WikiDiscussions master Synced 3w ago

READMEChangelog (10)Dependencies (8)Versions (16)Used By (0)

Package abandoned
-----------------

[](#package-abandoned)

This package has been abandoned, use with caution if you still need it.
Please fork this package and give it new life if you're interested!

---

[![Laravel Brickables](/docs/laravel-brickables.png)](/docs/laravel-brickables.png)

 [ ![Latest Stable Version](https://camo.githubusercontent.com/ba982434807ba259f21bf23f7f0e69c612bc8aa4a0c623dbfdad7af8e0749861/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f72656c656173652f4f6b6970612f6c61726176656c2d627269636b61626c65732e737667) ](https://github.com/Okipa/laravel-brickables/releases "Latest Stable Version") [ ![Total Downloads](https://camo.githubusercontent.com/fb7a9a5a8f6abdf3033f2fb71d49835fb79e2cc45e514d6645f5a7d744aeaddf/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6f6b6970612f6c61726176656c2d627269636b61626c65732e737667) ](https://packagist.org/packages/Okipa/laravel-brickables "Total Downloads") [ ![Build Status](https://github.com/Okipa/laravel-brickables/workflows/CI/badge.svg) ](https://github.com/Okipa/laravel-brickables/actions "Build Status") [ ![Coverage Status](https://camo.githubusercontent.com/5b2019e685d35c9b6ebff52ef4ed49048be0a40787bcb277d3d0ce1715476fab/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6769746875622f4f6b6970612f6c61726176656c2d627269636b61626c65732f62616467652e7376673f6272616e63683d6d6173746572) ](https://coveralls.io/github/Okipa/laravel-brickables?branch=master "Coverage Status") [ ![License: MIT](https://camo.githubusercontent.com/08cef40a9105b6526ca22088bc514fbfdbc9aac1ddbf8d4e6c750e3a88a44dca/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d626c75652e737667) ](/LICENSE.md "License: MIT")

This package allows you to associate content bricks to Eloquent models and provides a fully customizable admin panel to manage them.

This package is shipped with few pre-built brickables. You can use them as is but you definitely should consider them as examples: customizing them or create new ones has been designed to be simple as hell! 🔥

Found this package helpful? Please consider supporting my work!

[![Donate](https://camo.githubusercontent.com/6c3b5a78d466728cacf06baad81fbd1e05af9cdb0406db055d37df429291a74f/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4275795f6d655f612d4b6f2d2d66692d6666356635662e737667)](https://ko-fi.com/arthurlorent)[![Donate](https://camo.githubusercontent.com/3cd689d69c5219f5c2f2675b7ccccb50061b112100f2468c1cec746765762ebd/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f446f6e6174655f6f6e2d50617950616c2d677265656e2e737667)](https://paypal.me/arthurlorent)

Compatibility
-------------

[](#compatibility)

Laravel versionPHP versionPackage version^9.0 | ^10.08.1.\* | 8.2.\*^3.2^8.0 | ^9.0^8.1 | ^8.2^3.1^8.0 | ^9.0^8.0 | ^8.1^3.0^7.0 | ^8.0^7.4 | ^8.0^2.0^5.8 | ^6.0 | ^7.0^7.1 | ^7.2 | ^7.3 | ^7.4^1.0Upgrade guide
-------------

[](#upgrade-guide)

- [From V2 to V3](/docs/upgrade-guides/from-v2-to-v3.md)
- [From V1 to V2](/docs/upgrade-guides/from-v1-to-v2.md)

Usage
-----

[](#usage)

Associate content bricks to Eloquent models:

```
$page = Page::find(1);

// Associate one content brick
$page->addBrick(OneTextColumn::class, ['text' => 'Text']);

// Or associate several content bricks at once
$page->addBricks([
    [OneTextColumn::class, ['text' => 'Text']],
    [TwoTextColumns::class, ['text_left' => 'Left text', 'text_right' => 'Right text']]
]);
```

Display bricks in your views:

```
{{-- All at once --}}
{!! $page->displayBricks() !!}

{{-- Or one by one --}}
{{ $page->getFirstBrick(OneTextColumn::class) }}
```

Display the model-related bricks admin panel in your views:

```
{{ $page->displayAdminPanel() }}
```

Table of contents
-----------------

[](#table-of-contents)

- [Installation](#installation)
- [Configuration](#configuration)
- [Views](#views)
- [Translations](#translations)
- [Implementation](#implementation)
    - [Models](#models)
    - [Routes](#routes)
- [How to](#how-to)
    - [Define brick constraints for model](#define-brick-constraints-for-model)
    - [Add content bricks](#add-content-bricks)
    - [Update a content brick](#update-a-content-brick)
    - [Remove content bricks](#remove-content-bricks)
    - [Set content bricks order](#set-content-bricks-order)
    - [Retrieve content bricks](#retrieve-content-bricks)
    - [Query content bricks](#query-content-bricks)
    - [Display content bricks](#display-content-bricks)
    - [Retrieve brickables](#retrieve-brickables)
    - [Manage model content bricks](#manage-model-content-bricks)
    - [Create your own brickable](#create-your-own-brickable)
    - [Define brickable css and js resources](#define-brickable-css-and-js-resources)
    - [Empower bricks with extra abilities](#empower-brickables-with-extra-abilities)
    - [Get Eloquent model from Request](#get-eloquent-model-from-request)
- [Testing](#testing)
- [Changelog](#changelog)
- [Contributing](#contributing)
- [Security](#security)
- [Credits](#credits)
- [Licence](#license)

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

[](#installation)

Install the package via composer:

```
composer require okipa/laravel-brickables
```

Then, publish and run the database migrations:

```
php artisan vendor:publish --tag=laravel-brickables:migrations

php artisan migrate
```

Finally, to benefit from [smart loading of brickables css and js resources](#define-brickable-css-and-js-resources), add these directives to your blade layout as shown in the example bellow:

```
{{-- layout.blade.php --}}

        @brickablesCss

        @yield('content')
        @brickablesJs

```

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

[](#configuration)

Publish the package configuration:

```
php artisan vendor:publish --tag=laravel-brickables:config
```

⚠️ You may have to run a `composer dump-autoload` after changing a path in your configuration file.

Views
-----

[](#views)

Publish the package views:

```
php artisan vendor:publish --tag=laravel-brickables:views
```

Translations
------------

[](#translations)

All words and sentences used in this package are translatable.

See how to translate them on the Laravel official documentation : .

Here is the list of the words and sentences available for translation by default:

- `Content Bricks`
- `No saved content brick.`
- `Content`
- `Left content`
- `Right content`
- `Brick data`
- `Add`
- `Edit`
- `Update`
- `Destroy`
- `Cancel`
- `Move up`
- `Move down`
- `The entry :model > :brickable has been created.`
- `The entry :model > :brickable has been updated.`
- `The entry :model > :brickable has been deleted.`

You will also have to define the `validation.attributes.brickable_types` translation.

Finally, you will have to translate each registered brickable label translation.

Implementation
--------------

[](#implementation)

### Models

[](#models)

Implement the `HasBrickables` interface and use the `HasBrickablesTrait` trait to any Eloquent model that you want to be able to be associated to content bricks to.

```
use Illuminate\Database\Eloquent\Model;
use Okipa\LaravelBrickables\Contracts\HasBrickables;
use Okipa\LaravelBrickables\Traits\HasBrickablesTrait;

class Page extends Model implements HasBrickables
{
	use HasBrickablesTrait;

	// ...
}
```

### Routes

[](#routes)

Add the `web` routes that will be required by the content bricks admin panel:

```
Brickables::routes();
```

These routes are consuming the `Okipa\LaravelBrickables\Controllers\BricksController` controller by default.

To customize the admin panel actions, you can add routes inside or outside of the brickables route group.

```
Brickables::routes(function(){
    // Inside the routes group: will benefit from the CRUDBrickable middleware.
});
// Outside the route group: will not benefit from the CRUDBrickable middleware.
```

Check the [Empower bricks with extra abilities](#empower-brickables-with-extra-abilities) part to get more information about the customization possibilities.

How to
------

[](#how-to)

### Define brick constraints for model

[](#define-brick-constraints-for-model)

In your Eloquent model, you optionally can define constraints:

- Define the brickables that your model is being authorized to manage,
- Define the minimum number of bricks of each brickable that the model must hold,
- Define the maximum number of bricks of each brickable that the model can hold.

```
use Illuminate\Database\Eloquent\Model;
use Okipa\LaravelBrickables\Contracts\HasBrickables;
use Okipa\LaravelBrickables\Traits\HasBrickablesTrait;

class Page extends Model implements HasBrickables
{
	use HasBrickablesTrait;

    public array $brickables = [
        'can_only_handle' => [OneTextColumn::class], // By default all registered brickables can be handled.
        'number_of_bricks' => [OneTextColumn::class => ['min' => 1, 'max' => 3]], // By default, there are no number restrictions.
    ];

	// ...
}
```

In this example:

- The `Page` model will only be allowed to handle `OneTextColumn` bricks.
- The admin panel will only allow to manage `OneTextColumn` bricks.
- The admin panel will not allow to remove a `OneTextColumn` brick if there is only one left.
- The admin panel will not allow to add more `OneTextColumn` bricks if 3 are already added.
- Programmatically clearing all bricks for this model will keep the `OneTextColumn` one with the highest position.
- Programmatically adding a 4th `OneTextColumn` brick will thrown a `ModelHasReachedMaxNumberOfBricksException`.

**Important note:** you can disable a brickable management for a model by setting its max number to `0`.

### Add content bricks

[](#add-content-bricks)

Associate a single content brick to an Eloquent model:

```
$brick = $page->addBrick(OneTextColumn::class, ['text' => 'Text']);
```

You also can associate several content bricks at once:

```
$bricks = $page->addBricks([
    [OneTextColumn::class, ['text' => 'Text']],
    [TwoTextColumns::class, ['text_left' => 'Left text', 'text_right' => 'Right text']]
]);
```

### Update a content brick

[](#update-a-content-brick)

Just update your content brick as you would fo for any other Eloquent model instance:

```
// As data are stored in json, you will have to process this way: https://github.com/laravel/framework/pull/15464#issuecomment-247642772.
$brick->data = ['text' => 'Another text'];
$brick->save();
```

### Remove content bricks

[](#remove-content-bricks)

Just delete your content brick as you would fo for any other Eloquent model instance:

```
$brick->delete();
```

Clear all the content bricks associated to an Eloquent model, or only those with specific brickable types:

```
$page->clearBricks();

$page->clearBricks([OneTextColumn::class]);
```

Clear all the content bricks except specific ones:

```
$page->clearBricksExcept($bricksCollection);
```

**Note**

- According to the [number of bricks constraints](#define-brick-constraints-for-model) defined in the Eloquent model, these methods could be brought to keep the min number of bricks instead of removing the targeted brick(s).

### Set content bricks order

[](#set-content-bricks-order)

By default, all bricks are ordered by their creation order (last created at the end).

The `Brick` model uses the `spatie/eloquent-sortable` package to handle the content bricks positioning.

To see how to use this third party package, check its documentation here: .

You may note that the bricks order management is already handled in the provided [admin panel](#manage-model-content-bricks) and that you can use it as is.

### Retrieve content bricks

[](#retrieve-content-bricks)

Retrieve all the content bricks associated to an Eloquent model, or only those with a specific brickable type:

```
$bricks = $page->getBricks();

$bricks = $page->getBricks(OneTextColumn::class);
```

Get the first content brick associated to an Eloquent model, or the one with a specific brickable type:

```
$brick = $page->getFirstBrick();

$brick = $page->getFirstBrick(OneTextColumn::class);
```

### Query content bricks

[](#query-content-bricks)

As each brickable can specify its own brick model, you should query content bricks and then cast them ito the model defined in their related brickable:

```
$rawBricks = Brick::where('model_type', Page::class)->where('model_id', 1)->where('brickable_type', OneTextColumn::class)->get();
$bricks = Brickables::castBricks($rawBricks);
```

### Display content bricks

[](#display-content-bricks)

Display a single content brick in your view:

```
{{ $page->getFirstBrick(OneTextColumn::class) }}
```

Or display all the content bricks associated to an Eloquent model:

```
{!! $page->displayBricks() !!}
```

Or only display content bricks from given brickable types:

```
{!! $page->displayBricks([OneTextColumn::class, TwoTextColumns::class]) !!}
```

### Retrieve brickables

[](#retrieve-brickables)

Get all the registered brickables:

```
$registeredBrickables = $page->getRegisteredBrickables();
```

Get all the brickables that are allowed to be added to an Eloquent model:

```
$additionableBrickables = $page->getAdditionableBrickables();
```

Retrieve a brickable from a brick instance:

```
$brickable = $page->getFirstBrick(OneTextColumn::class)->brickable;
```

### Manage model content bricks

[](#manage-model-content-bricks)

Use the ready-to-use admin panel to manage related-model content bricks:

```
{!! $page->displayAdminPanel() !!}
```

Customize the admin panel views by [publishing them](#views).

**💡 Tips**

- It is highly recommended adding a javascript confirmation request to intercept the content bricks delete action, otherwise the removal action will be directly executed without asking the user agreement.

### Create your own brickable

[](#create-your-own-brickable)

Create a new brickable class that extends class in your `app/vendor/Brickables` directory.

In your brickable class, you can override any method from the extended abstract `Brickable` to customize the brickable behaviour.

```