README

A flexible, framework-agnostic content container system for Laravel applications. This package provides the core infrastructure for building modular content management systems with support for multiple container types, layouts, scheduling, and multi-tenant context filtering.

Features

Polymorphic Containers: Attach containers to any Eloquent model (pages, products, categories, etc.)
Flexible Type System: Define custom container types with their own data structures and layouts
Layout Support: Multiple visual layouts per container type
Visibility Scheduling: Show containers based on fixed dates or recurring schedules
Context Filtering: Multi-tenant support with customizable context scoping
View Resolution: Theme-aware view resolution with fallback support
URL Resolution: Abstract URL resolution for internal references

Installation

Install the package via Composer:

composer require ameax/content-container-core

Publish the config file:

php artisan vendor:publish --tag="content-container-core-config"

Database Setup

This package provides migration stubs that you can use as a reference. Copy them to your project and customize as needed:

# The stubs are located in:
# vendor/ameax/content-container-core/database/migrations/create_containers_table.php.stub
# vendor/ameax/content-container-core/database/migrations/create_container_references_table.php.stub

Or create your own migrations based on the schema requirements below.

Configuration

// config/content-container-core.php
return [
    'models' => [
        'container' => \App\Models\Container::class,
        'container_reference' => \App\Models\ContainerReference::class,
    ],

    'resolvers' => [
        'view' => \App\Services\MyViewResolver::class,
        'url' => \App\Services\MyUrlResolver::class,
        'context_filter' => \App\Services\MyContextFilter::class,
    ],

    'tables' => [
        'containers' => 'containers',
        'container_references' => 'container_references',
    ],
];

Usage

1. Create Your Container Model

Extend the base container model with your project-specific implementation:

<?php

namespace App\Models;

use Ameax\ContentContainerCore\Models\BaseContainer;
use App\Enums\ContainerTypeEnum;
use App\Enums\ContainerLayoutEnum;

class Container extends BaseContainer
{
    protected $casts = [
        'type' => ContainerTypeEnum::class,
        'layout' => ContainerLayoutEnum::class,
        'display_from' => 'datetime',
        'display_to' => 'datetime',
        'data' => 'array',
        'recurring_settings' => 'array',
    ];

    public function isContainerCollection(): bool
    {
        return $this->type === ContainerTypeEnum::CONTAINER_COLLECTION;
    }

    // Add your tenant/context relationship
    public function tenant()
    {
        return $this->belongsTo(Tenant::class);
    }
}

2. Define Container Types

Implement the ContainerTypeContract with your enum:

<?php

namespace App\Enums;

use Ameax\ContentContainerCore\Contracts\ContainerTypeContract;
use Ameax\ContentContainerCore\Contracts\ContainerLayoutContract;

enum ContainerTypeEnum: string implements ContainerTypeContract
{
    case TEXT = 'text';
    case IMAGE = 'image';
    case IMAGE_TEXT = 'image_text';
    case CONTAINER_COLLECTION = 'container_collection';

    public function getValue(): string
    {
        return $this->value;
    }

    public function getDefaults(): array
    {
        return match ($this) {
            self::TEXT => ['headline' => null, 'content' => null],
            self::IMAGE => ['image' => null, 'alt' => null],
            self::IMAGE_TEXT => ['headline' => null, 'content' => null, 'image' => null],
            self::CONTAINER_COLLECTION => ['container_references' => []],
        };
    }

    public function getAvailableLayouts(): array
    {
        return match ($this) {
            self::IMAGE_TEXT => [
                ContainerLayoutEnum::DEFAULT,
                ContainerLayoutEnum::OVERLAY,
            ],
            default => [ContainerLayoutEnum::DEFAULT],
        };
    }

    public function getView(ContainerLayoutContract $layout): string
    {
        // Implement your view resolution logic
        return "containers.{$layout->getViewDirectory()}.{$this->value}";
    }

    public function supports(string $feature): bool
    {
        return match ($feature) {
            'scheduling' => true,
            'collections' => $this === self::CONTAINER_COLLECTION,
            default => false,
        };
    }

    public function getIcon(): string
    {
        return asset("images/containers/{$this->value}.png");
    }

    public function getLabel(): ?string
    {
        return ucfirst(str_replace('_', ' ', $this->value));
    }
}

3. Add Containers to Your Models

Use the HasContainers trait on models that should have containers:

<?php

namespace App\Models;

use Ameax\ContentContainerCore\Traits\HasContainers;
use Illuminate\Database\Eloquent\Model;

class Page extends Model
{
    use HasContainers;

    protected function getContainerClass(): string
    {
        return \App\Models\Container::class;
    }
}

Then use containers in your views:

// Get visible containers (respects scheduling and context filtering)
$containers = $page->visibleContainers();

// Get containers for a specific slot
$headerContainers = $page->containersForSlot('header');

// Get main content containers (no slot)
$mainContainers = $page->mainContainers();

4. Implement Context Filtering (Optional)

For multi-tenant applications, implement the ContextFilterContract:

<?php

namespace App\Services;

use Ameax\ContentContainerCore\Contracts\ContextFilterContract;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Relations\Relation;

class TenantContextFilter implements ContextFilterContract
{
    public function getContextColumn(): string
    {
        return 'tenant_id';
    }

    public function getContextRelationship(): ?string
    {
        return 'tenant';
    }

    public function getDefaultValue(): mixed
    {
        return auth()->user()?->tenant_id;
    }

    public function applyScope(Builder|Relation $query): void
    {
        $tenantId = $this->getCurrentContextValue();

        if ($tenantId !== null) {
            $query->where('tenant_id', $tenantId);
        }
    }

    public function getCurrentContextValue(): mixed
    {
        return auth()->user()?->tenant_id;
    }

    public function isEnabled(): bool
    {
        return !app()->runningInConsole();
    }
}

5. Implement View Resolution (Optional)

For theme-aware view resolution:

<?php

namespace App\Services;

use Ameax\ContentContainerCore\Contracts\ContainerTypeContract;
use Ameax\ContentContainerCore\Contracts\ContainerLayoutContract;
use Ameax\ContentContainerCore\Contracts\ViewResolverContract;

class ThemeViewResolver implements ViewResolverContract
{
    public function resolve(ContainerTypeContract $type, ContainerLayoutContract $layout): string
    {
        $theme = config('app.theme', 'default');
        $typeView = $type->getValue();
        $layoutView = $layout->getViewDirectory();

        // Try theme-specific view first
        $view = "themes.{$theme}.containers.{$layoutView}.{$typeView}";

        if (view()->exists($view)) {
            return $view;
        }

        // Fall back to default theme
        return "themes.default.containers.{$layoutView}.{$typeView}";
    }
}

Scheduling

Containers support three scheduling modes:

None (Always Visible)

$container->schedule_type = ScheduleType::NONE;

Fixed Date Range

$container->schedule_type = ScheduleType::FIXED;
$container->display_from = now();
$container->display_to = now()->addWeek();

Recurring (Annual)

$container->schedule_type = ScheduleType::RECURRING;
$container->recurring_settings = [
    'start_month_day' => '15/12',  // December 15
    'end_month_day' => '06/01',    // January 6 (supports year-spanning)
];

Container Collections

Container collections allow you to group and reuse containers:

// Create a collection container
$collection = Container::create([
    'type' => ContainerTypeEnum::CONTAINER_COLLECTION,
    'data' => [
        'container_references' => [
            ['referenced_container_id' => 1, 'sort' => 0],
            ['referenced_container_id' => 2, 'sort' => 1],
        ],
    ],
]);

// Access referenced containers
$referencedContainers = $collection->referencedContainers;

Database Schema

containers table

Column	Type	Description
id	bigint	Primary key
containerable_type	string	Polymorphic type
containerable_id	bigint	Polymorphic ID
type	string	Container type identifier
layout	string	Layout identifier
slot	string	Optional slot name (e.g., 'header', 'sidebar')
label	string	Internal label for admin
data	json	Container-specific data
sort	integer	Sort order
is_active	boolean	Visibility flag
schedule_type	string	'none', 'fixed', or 'recurring'
display_from	timestamp	Start of visibility (fixed scheduling)
display_to	timestamp	End of visibility (fixed scheduling)
recurring_settings	json	Recurring schedule config
created_at	timestamp
updated_at	timestamp

container_references table

Column	Type	Description
id	bigint	Primary key
collection_container_id	bigint	FK to containers
referenced_container_id	bigint	FK to containers
sort	integer	Sort order within collection
created_at	timestamp
updated_at	timestamp

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

ameax / content-container-core

Maintainers

Details