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

container_references table

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

• ameax GmbH
• All Contributors

License

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