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...
}

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

portable-content / portable-content-php

Maintainers

Details