v0.4.0: Mutable MarkdownBlock with AbstractBlock Architecture

🔄 BREAKING CHANGES: Mutable MarkdownBlock with AbstractBlock Architecture

This release introduces a major architectural improvement by converting MarkdownBlock from immutable to mutable design and adding an AbstractBlock base class for extensibility.

✨ What's New

AbstractBlock Base Class

• New extensible foundation for all block types
• Common functionality shared across all blocks (ID, timestamps, helper methods)
• Easy extensibility for future block types (CodeBlock, HtmlBlock, etc.)

Mutable MarkdownBlock

• Direct modification with setSource(), setId(), setCreatedAt() methods
• Proper encapsulation with private properties and getter/setter methods
• Better performance - no object creation overhead for updates

Enhanced Architecture

• Clean inheritance hierarchy with AbstractBlock providing common functionality
• Improved code organization and maintainability
• Foundation for future features - easy to add new block types

🚨 Breaking Changes

Property Access:

// ❌ Before (v0.3.0)
$source = $block->source;
$id = $block->id;

// ✅ After (v0.4.0)
$source = $block->getSource();
$id = $block->getId();

Block Updates:

// ❌ Before (v0.3.0)
$updated = $block->withSource('New content');

// ✅ After (v0.4.0)
$block->setSource('New content');

📝 Migration Guide

1. Update Property Access - Replace direct property access with getter methods
2. Update Modifications - Replace withSource() with setSource()
3. Update Repository Code - Use getters in any custom repository implementations
4. Update Tests - Modify test assertions to use new getter/setter methods

See CHANGELOG.md for detailed migration instructions.

🏗️ Future Block Types Made Easy

The new AbstractBlock makes it simple to add new block types:

class CodeBlock extends AbstractBlock
{
    private string $language;
    private string $code;
    
    // Inherits common functionality from AbstractBlock
    // Easy to implement required abstract methods
}

📊 Quality Metrics

• ✅ All 315 tests passing with 1,669 assertions
• ✅ PHPStan Level 9 compliance (zero static analysis errors)
• ✅ Complete documentation updated for new architecture
• ✅ Backward compatibility through proper encapsulation

🔧 Technical Details

• PHP 8.3+ compatibility maintained
• No database changes required
• All validation logic preserved
• Enhanced extensibility for future development

---

Full Changelog: v0.3.0...v0.4.0

v0.3.0: Entity Architecture

🔄 Major Release: Entity Architecture v0.3.0

🚨 BREAKING CHANGE: ContentItem Entity Conversion

This release converts ContentItem from an immutable value object to a mutable entity, representing a significant architectural shift that improves usability while maintaining data integrity.

✨ What's New

🔧 Enhanced ContentItem API

• Getter Methods - Complete encapsulation with getId(), getType(), getTitle(), getSummary(), getBlocks(), getCreatedAt(), getUpdatedAt()
• Setter Methods - Mutable operations with setType(), setTitle(), setSummary(), setBlocks(), addBlock()
• Automatic Timestamps - updatedAt automatically updated when properties change
• Enhanced Validation - All validation logic preserved in setter methods

🏗️ Architectural Improvements

• Better Encapsulation - Proper object-oriented design with private properties
• Maintained Validation - All business rules and validation logic preserved
• Type Safety - Full type hints and static analysis compliance maintained
• Test Coverage - All 315 tests updated and passing with 1,673 assertions

🔄 Migration Guide

Before (v0.2.0 - Immutable Value Object)

// Property access
$title = $content->title;
$blocks = $content->blocks;

// Updates (created new instances)
$updated = $content->withTitle('New Title');
$withBlocks = $content->withBlocks([$block1, $block2]);
$withNewBlock = $content->addBlock($newBlock);

After (v0.3.0 - Mutable Entity)

// Property access (use getters)
$title = $content->getTitle();
$blocks = $content->getBlocks();

// Updates (modify same object)
$content->setTitle('New Title');
$content->setBlocks([$block1, $block2]);
$content->addBlock($newBlock); // void return

📋 Migration Steps

1. Update Property Access - Replace direct property access with getter methods
2. Update Modifications - Replace with* methods with set* methods
3. Handle Return Values - addBlock() now returns void instead of self
4. Update Tests - Modify test assertions to use new getter methods

🗑️ Removed Features

• Immutable Methods - Removed withTitle(), withSummary(), withBlocks() methods
• Public Properties - All properties now private (breaking change)
• Method Chaining - Removed fluent interface for content modification

📊 Impact & Benefits

• Breaking Change - Requires code updates for property access and modification patterns
• Improved Usability - More intuitive mutable entity pattern
• Better Performance - Eliminates object creation overhead for updates
• Enhanced Maintainability - Cleaner separation between data and behavior

✅ Compatibility

• PHP Version - Still requires PHP 8.3+
• Dependencies - No changes to external dependencies
• Database Schema - No database changes required
• Validation Rules - All validation logic unchanged

🧪 Quality Assurance

• ✅ 315 tests passing (100% success rate)
• ✅ 1,673 assertions all successful
• ✅ PHPStan Level 9 - Zero static analysis errors
• ✅ Full test coverage - Unit and integration tests
• ✅ Backward compatibility - Database and validation layers unchanged

📚 Documentation Updates

• Updated CHANGELOG.md with comprehensive migration guide
• Updated README.md with new API examples
• Updated docs/architecture.md to reflect entity design patterns
• Updated llms.txt with new getter/setter API documentation

---

Full Changelog: v0.2.0...v0.3.0

Need Help? Check the migration guide or open an issue.

v0.2.0

🧹 Repository Architecture Cleanup

This release focuses on simplifying the repository architecture by removing speculative vector database implementations and focusing on a robust SQLite-only foundation.

✨ Key Improvements

• Enhanced ContentRepositoryInterface with capability discovery
• Simplified architecture removing speculative implementations
• Library best practices with composer.lock management
• Cleaner, more maintainable codebase (-6,684 lines)
• All 315 tests passing, PHPStan Level 9 compliance

🎯 Philosophy Shift

Strategic decision to avoid over-engineering and focus on delivering a solid, tested foundation. Vector capabilities will be added when there's genuine demand.

Full Changelog: v0.1.0...v0.2.0

v0.1.0

🎉 Initial Release - Production Ready PHP Content Management Library

This release represents the completed Phase 1A implementation with all goals achieved and exceeded. The Portable Content PHP library is now production-ready with enterprise-grade code quality.

✨ Key Features

• 🏗️ Immutable Domain Objects - Thread-safe ContentItem and MarkdownBlock entities
• 🔒 Type-Safe Validation - Comprehensive input validation and sanitization pipeline
• 💾 Repository Pattern - Clean abstraction with optimized SQLite implementation
• 🧪 Comprehensive Testing - 315 tests with 1,674 assertions
• 📚 Complete Documentation - 7 detailed guides covering all aspects
• ⚡ Production Ready - PHPStan Level 9, zero static analysis errors

🎯 Phase 1A Goals - All Achieved ✅

• ✅ Content Entity Storage - ContentItem with MarkdownBlock support
• ✅ SQLite Database - Optimized schema with foreign key constraints
• ✅ Repository Pattern - Clean data access abstraction with transaction safety
• ✅ Input Validation - Comprehensive validation and sanitization system
• ✅ Comprehensive Testing - Complete unit and integration test coverage
• ✅ Enterprise Quality - Maximum code quality standards exceeded

📊 Release Metrics

• Source Code: 2,500+ lines of production PHP 8.3+ code
• Test Coverage: 315 tests, 1,674 assertions
• Documentation: 7 comprehensive guides (50+ pages)
• Code Quality: PHPStan Level 9, zero static analysis errors
• Performance: Handles 1000+ content items efficiently
• Dependencies: Minimal, production-ready dependency set

🚀 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

📚 Documentation

• Getting Started Guide - Complete setup and basic usage
• API Reference - Detailed API documentation
• Architecture Overview - System design and components
• Examples - Common usage patterns and recipes

🔧 Technical Highlights

Type Safety & Immutability

• PHP 8.3+ Compatibility with strict typing throughout
• Immutable Domain Objects for thread safety and reliability
• Comprehensive Type Hints with full static analysis compliance
• Defensive Programming with robust error handling

Quality Assurance

• PHPStan Level 9 - Strictest static analysis (0 errors)
• PHP-CS-Fixer - Complete code style standardization
• Comprehensive Testing - Unit and integration test coverage
• CI/CD Pipeline - Automated quality checks and testing

Performance & Scalability

• Optimized Database Queries with efficient SQLite operations
• Memory Management with efficient object lifecycle
• Batch Operations supporting large dataset processing
• Connection Pooling Ready for production scaling

🎯 Ready For Production

This library is ready for production use in:

• Content Management Systems requiring reliable content storage
• API Backends needing type-safe content validation
• Documentation Systems with markdown content support
• Enterprise Applications requiring maximum code quality

🚀 What's Next - Phase 1B

The next major release will focus on GraphQL API implementation:

• GraphQL Server with complete schema and resolver system
• API Endpoints for query, mutation, and subscription support
• Additional CLI Tools for content management utilities
• Enhanced Block Types including HTML, Code, Image, and Embed blocks

See Future Features for the complete roadmap.

📝 Full Changelog

See CHANGELOG.md for detailed release notes.

---

This release represents a production-ready foundation for content management systems with enterprise-grade code quality, comprehensive testing, and complete documentation. The library exceeds industry standards and is ready for community contributions and Phase 1B development.