README

A robust PHP library for managing portable content with comprehensive validation, sanitization, and flexible storage backends.

✨ Key Features

• 🏗️ Mutable Domain Objects - Flexible ContentItem and MarkdownBlock entities with proper encapsulation
• 🧱 AbstractBlock Architecture - Extensible base class for all block types
• 🔒 Type-Safe Validation - Comprehensive input validation and sanitization
• 💾 Repository Pattern - Clean abstraction with capability discovery system
• 🧪 Comprehensive Testing - 315 tests with 1,669 assertions
• 📚 Complete Documentation - 7 detailed guides covering all aspects
• ⚡ Production Ready - PHPStan Level 9, zero static analysis errors
• 🧹 Clean Architecture - Focused, maintainable codebase with extensible design

Requirements

• PHP 8.3 or higher
• Composer
• SQLite (included with PHP)

Installation

git clone https://github.com/portable-content/portable-content-php.git
cd portable-content-php
composer install

Database Setup

Initialize Database

# Create database with migrations
composer migrate

# Or specify custom path
php bin/migrate.php --path=storage/custom.db

# Test with in-memory database
composer migrate-test

Database Schema

The system uses SQLite with two main tables:

• content_items: Stores ContentItem metadata (id, type, title, summary, timestamps)
• markdown_blocks: Stores MarkdownBlock content (id, content_id, source, timestamp)

Foreign key constraints ensure data integrity between content and blocks.

Quick Start

Basic Usage

<?php

require_once 'vendor/autoload.php';

use PortableContent\Block\Markdown\MarkdownBlock;
use PortableContent\ContentItem;
use PortableContent\Tests\Support\Repository\RepositoryFactory;

// Create a markdown block
$block = MarkdownBlock::create('# Hello World\n\nThis is my first note!');

// Create content with the block
$content = ContentItem::create('note', 'My First Note', 'A simple example', [$block]);

// Set up repository (in-memory for this example)
$repository = RepositoryFactory::createInMemoryRepository();

// Save content
$repository->save($content);

// Retrieve content
$retrieved = $repository->findById($content->id);
echo "Retrieved: {$retrieved->title}\n";

With Validation

use PortableContent\Validation\ContentValidationService;
use PortableContent\Validation\ContentSanitizer;
use PortableContent\Validation\BlockSanitizerManager;
use PortableContent\Validation\Adapters\SymfonyValidatorAdapter;
use PortableContent\Block\Markdown\MarkdownBlockSanitizer;
use Symfony\Component\Validator\Validation;

// Set up validation service
$blockSanitizerManager = new BlockSanitizerManager([new MarkdownBlockSanitizer()]);
$contentSanitizer = new ContentSanitizer($blockSanitizerManager);
$symfonyValidator = Validation::createValidator();
$contentValidator = new SymfonyValidatorAdapter($symfonyValidator);
$validationService = new ContentValidationService($contentSanitizer, $contentValidator);

// Raw input data (as from API/form)
$rawData = [
    'type' => '  note  ',  // Will be sanitized
    'title' => 'My Note',
    'blocks' => [
        [
            'kind' => 'markdown',
            'source' => '# Hello World\n\nContent here.'
        ]
    ]
];

// Validate and sanitize
$result = $validationService->validateContentCreation($rawData);

if ($result->isValid()) {
    $sanitizedData = $result->getData();
    // Create domain objects from validated data...
} else {
    $errors = $result->getErrors();
    // Handle validation errors...
}

Table of Contents

• Installation
• Database Setup
• Quick Start
• Documentation
• Development
• Project Structure
• Features
• Requirements
• License

Features

✅ Immutable Domain Objects - Thread-safe, predictable content management ✅ Type-Safe API - Full PHP 8.3+ type hints and strict typing ✅ Input Validation - Comprehensive sanitization and validation pipeline ✅ Repository Pattern - Clean data access abstraction ✅ Transaction Safety - ACID-compliant database operations ✅ Extensible Blocks - Plugin system for different content types ✅ Production Ready - 315+ tests, PHPStan Level 9, CI/CD pipeline ✅ Developer Friendly - Comprehensive documentation and examples

Documentation

For complete documentation, see the docs/ directory:

• Getting Started Guide - Complete setup and basic usage
• API Reference - Detailed API documentation
• Validation System - Input validation and sanitization
• Repository Pattern - Data persistence and retrieval
• Architecture Overview - System design and components
• Examples - Common usage patterns and recipes
• Future Features - Planned features and roadmap

For AI/LLM Developers

• llms.txt - Essential guide for Large Language Models working with this library

Development

# Run tests
composer test

# Run tests with coverage
composer test-coverage

# Run specific test suite
./vendor/bin/phpunit --testsuite=Unit

# Code quality checks
composer cs-check          # Check code style
composer cs-fix            # Fix code style
composer phpstan           # Run static analysis
composer security-audit    # Check for security issues

# Composer maintenance
composer composer-normalize # Check composer.json format
composer composer-normalize-fix # Fix composer.json format

Project Structure

src/                          # Source code
├── Block/                   # Block implementations (MarkdownBlock)
├── Contracts/               # Interfaces and contracts
├── Exception/               # Exception classes
├── Validation/              # Validation and sanitization system
└── ContentItem.php          # Main domain object
tests/                        # Test files (315 tests, 1,283 assertions)
├── Support/                  # Test support utilities
│   ├── Database/            # SQLite database helpers
│   └── Repository/          # Repository factory for testing
├── Unit/                    # Unit tests
└── Integration/             # Integration tests (end-to-end workflows)
docs/                        # Complete documentation
├── getting-started.md       # Setup and basic usage
├── api-reference.md         # Complete API documentation
├── validation.md            # Validation system guide
├── examples.md              # Usage examples and patterns
├── architecture.md          # System design and components
├── repository.md            # Repository pattern details
└── future-features.md       # Roadmap and planned features
storage/                     # SQLite database files
bin/                         # CLI tools
└── migrate.php              # Database migration tool
migrations/                  # Database schema migrations
llms.txt                     # Guide for AI/LLM developers

Development Status

Phase 1A: COMPLETE ✅

This library represents the completed Phase 1A implementation with all goals achieved:

• ✅ Basic content entity storage (ContentItem, MarkdownBlock)
• ✅ SQLite database with proper schema and migrations
• ✅ Repository pattern for data access
• ✅ Comprehensive input validation and sanitization
• ✅ Extensive testing (315+ tests, 1,283+ assertions)
• ✅ Production-ready code quality (PHPStan Level 9, CS-Fixer)

Next Phase: GraphQL API

Phase 1B will add a GraphQL API layer on top of this solid foundation. See docs/future-features.md for the complete roadmap.

📦 Installation

composer require portable-content/portable-content-php

Or clone the repository:

git clone https://github.com/portable-content/portable-content-php.git
cd portable-content-php
composer install

Contributing

This library follows strict quality standards:

• PHP 8.3+ with strict typing
• PHPStan Level 9 static analysis
• PHP-CS-Fixer code style compliance
• Comprehensive testing with unit and integration tests
• Mutable entity design with proper encapsulation
• Clean architecture with clear separation of concerns

License

Apache 2.0 License