README

Polyctopus Core is a lightweight PHP library for managing structured content and content types, inspired by headless CMS concepts. It provides a flexible, type-safe way to define content models, fields, and to manage content instances in your application.

Features

Versioning and rollback for content entries
Content Dimensions: Support for content variants based on arbitrary dimensions (e.g. brands, channels, campaigns)
Multilingual content and variants: Optional translations for any content or variant using locales (e.g. de_DE)
Event mechanism for custom application logic based on triggered events by accepting callbacks
Structured validation errors for better error handling
Test utilities for easy test data setup

Requirements

PHP 8.3 or higher

Installation

Install via Composer (assuming you have a composer.json):

composer require polyctopus/core

Service Structure

Polyctopus Core uses a modular service structure for clear separation of concerns:

ContentService: Core operations for content (create, update, delete, rollback, resolve, etc.)
ContentTypeService: Manage content types (create, update, delete, list)
ContentVariantService: Manage content variants for dimensions
ContentTranslationService: Manage translations for content and variants
ContentVersionService: Manage content versioning and rollback

You typically obtain all services pre-wired via the InMemoryContentServiceFactory or a similar factory. The ContentService is the main entry point for all operations, and it uses the other services internally.

Example:

use Polyctopus\Core\Services\InMemoryContentServiceFactory;

$service = InMemoryContentServiceFactory::create(); // returns a ContentService with all dependencies
$service->contentTypeService->createContentType(TestFactory::contentTypeWithTextField('article'));

Creating Content

use Polyctopus\Core\Models\ContentStatus;

// Create a new Content (valid)
$content = $service->createContent('c1', $contentType, ['title' => 'Hello', 'contact' => 'info@example.com']);
echo "Created content: " . print_r($content->toArray(), true) . PHP_EOL;

// Update Content (valid and status change)
$service->updateContent($content, ContentStatus::Published, ['title' => 'Updated Title', 'contact' => 'info@example.com']);
$updated = $service->findContent('c1');
echo "Updated content: " . print_r($updated->toArray(), true) . PHP_EOL;

Validation

When creating or updating content, the service automatically validates the data against the field definitions of the content type.
If validation fails (e.g. a string is too long), a ValidationException is thrown, containing structured error objects.

Example:

try {
    $service->createContent('c2', $contentType, ['title' => str_repeat('A', 300)]);
} catch (\Polyctopus\Core\Exceptions\ValidationException $e) {
    foreach ($e->getErrors() as $error) {
        echo "Field: {$error->field}, Value: " . var_export($error->value, true) . ", Message: {$error->message}\n";
    }
}

Extending

Add new field types by implementing FieldTypeInterface.
Implement your own repositories for persistent storage by extending ContentRepositoryInterface and ContentVersionRepositoryInterface.
Create custom validation rules by implementing FieldTypeInterface or custom logic in your service.
Use the provided TestFactory for easy test data setup in your tests.

Usage Example

See the example-usage.php file in the repository for a complete example of how to use the library.

Content Types

Content Types

Content Variants (Dimension Overrides)

Content Variants

Multilingual Content & Translations

Translations

Publish Scheduling

Publish Start & End Dates

Event Mechanism

Events

Versioning & Rollback

Versioning & Rollback

Asset Handling

Asset Handling

Contributing

Contributions are welcome! Please create a pull request or open an issue for discussion.

License

LGPL-3.0-or-later

polyctopus / core

Maintainers

Details