6.0.0

Changelog - Version 6.0

Overview

Version 6.0 is a major release that introduces significant improvements to type safety, adds new features for enhanced ORM functionality, and removes deprecated methods from version 5.x. This release requires PHP 8.3+ and includes breaking changes that require code updates when upgrading from 5.x.

New Features

ActiveRecordQuery - Fluent Query API

• Introduced ActiveRecordQuery for a fluent and chainable query API
• Provides an intuitive way to build complex queries with method chaining
• Enhances the Active Record pattern implementation
• See: docs/active-record.md for examples

UUID Support Enhancements

• Added comprehensive UUID field support beyond just primary keys
• Introduced FormatSelectUuidMapper and FormatUpdateUuidMapper (renamed from Binary variants)
• Added HexUuidMapperFunctionTest for validation of UUID handling
• Full support for UUIDs in regular fields with automatic formatting
• See: docs/uuid-support.md

Varchar Primary Keys

• Added support for non-integer (varchar) primary keys
• Introduced Product and ActiveRecordProduct models showcasing custom primary key handling
• Enhanced primary key validation and handling across the ORM
• Updated tests and examples with seed functions for varchar PKs

HAVING Clause Support

• Added native support for HAVING clause in query building
• Allows for aggregate function filtering in SQL queries
• Integrates seamlessly with the existing query API

Entity Lifecycle Hooks

• Added beforeUpdate and beforeInsert hooks to the TableAttribute
• Introduced EntityProcessorInterface for custom entity processing
• Allows for custom validation and data transformation before persistence
• Can be defined at both table attribute and mapper levels
• Methods: withBeforeInsert() and withBeforeUpdate() in Mapper

Mapper Functions (Enhanced)

• Introduced MapperFunctionInterface as the standard interface for field transformations
• Added comprehensive mapper functions:
  • StandardMapper - basic field mapping
  • ReadOnlyMapper - read-only fields
  • NowUtcMapper - automatic UTC timestamp
  • FormatUpdateUuidMapper - UUID formatting on update
  • FormatSelectUuidMapper - UUID formatting on select
• Simplified and more consistent API for field transformations
• See: docs/mapper-functions.md

Enhanced Field Mapping

• Added MapperTest to validate field mapping behavior
• Support for field overwriting, aliases, and non-existent properties
• Added getPropertyName() method to Mapper for reverse field-to-property lookup
• Improved handling of array-to-object casting in Mapper

Observer Events

• Introduced ObserverEvent enum with Insert, Update, and Delete events
• Provides type-safe event handling for database operations
• See: docs/observers.md

Update Constraints

• Added UpdateConstraintInterface for controlling update operations
• Introduced CustomConstraint for custom update validation
• Added RequireChangedValuesConstraint to ensure values have changed before update
• New exception: RequireChangedValuesConstraintException
• See: docs/update-constraints.md

Enhanced Primary Key Handling

• Improved validation with MissingPrimaryKeyException
• More robust primary key validation in Repository::getPrimaryKeys()
• Better error messages for missing or invalid primary keys
• Enhanced support for composite primary keys

Iterator Support

• Added buildAndExecuteIterator() to QueryBuilderInterface
• Implemented getIterator() and enhanced getByQuery() in Repository
• Allows for efficient memory usage with large result sets

Serialization Optimization

• Applied withStopAtFirstLevel() in Serialize calls across multiple classes
• Prevents unnecessary deep parsing and improves performance
• Optimizes data transfer between layers

Documentation Improvements

• Added comprehensive docs/architecture-layers.md explaining Infrastructure vs Domain layers
• Added docs/comparison-with-other-orms.md comparing with Eloquent and Doctrine
• Added docs/common-traits.md for timestamp field helpers
• Added docs/mapper-functions.md for field transformation documentation
• Added docs/query-build.md for SQL query building
• Expanded and improved all existing documentation files
• Better examples and code samples throughout

Bug Fixes

• Fixed Repository::setBeforeUpdate() and Repository::setBeforeInsert() implementations
• Improved primary key handling edge cases
• Fixed namespace references for byjg/anydataset-db compatibility
• Resolved Psalm static analysis issues
• Fixed test compatibility with updated dependencies
• Corrected return type for Repository::insert() to ?int
• Improved transaction handling in Repository
• Fixed UUID formatting consistency issues

Breaking Changes

Before (5.x)	After (6.0)	Description
php: >=8.1 <8.4	php: >=8.3 <8.6	PHP 8.3+ is now required
byjg/anydataset-db: ^5.0	byjg/anydataset-db: ^6.0	Updated to version 6.x of anydataset-db
phpunit/phpunit: ^9.6	phpunit/phpunit: ^10.5|^11.5	Updated to PHPUnit 10.5+ or 11.5+
byjg/cache-engine: ^5.0	byjg/cache-engine: ^6.0	Updated to version 6.x
DbFunctionsInterface	DatabaseExecutor	Interface renamed for clarity
DbDriverInterface parameter	Repository->getExecutor()	Access database executor through repository
SqlObject	SqlStatement	Class renamed across entire codebase
UniqueIdGeneratorInterface	MapperFunctionInterface	Interface renamed for consistency
SelectBinaryUuidMapper	FormatSelectUuidMapper	Mapper class renamed
UpdateBinaryUuidMapper	FormatUpdateUuidMapper	Mapper class renamed
Mapper::addFieldMap()	Mapper::addFieldMapping()	Deprecated method removed
MapperClosure	Mapper Functions (e.g., StandardMapper)	Deprecated class removed
AllowOnlyNewValuesConstraintException	Removed/replaced	Exception removed
Literal class usage	LiteralInterface	Refactored to use interface
Nullable types (inconsistent)	Strict nullable types (?Type)	Improved type safety across all methods
withPrimaryKeySeedFunction(callable)	withPrimaryKeySeedFunction(string|MapperFunctionInterface)	Type signature changed

Removed Deprecated Features

The following deprecated features from 5.x have been removed:

1. Mapper::addFieldMap() - Use Mapper::addFieldMapping() instead
2. MapperClosure - Use the new Mapper Functions classes (StandardMapper, ReadOnlyMapper, etc.)
3. Old closure-based field transformations - Use MapperFunctionInterface implementations
4. Direct DbDriverInterface access - Use Repository->getExecutor() instead

Upgrade Path from 5.x to 6.0

Step 1: Update Dependencies

Update your composer.json:

{
  "require": {
    "php": ">=8.3",
    "byjg/micro-orm": "^6.0"
  }
}

Run:

composer update byjg/micro-orm

Step 2: Update PHP Version

Ensure your project is running PHP 8.3 or higher. Version 6.0 takes advantage of PHP 8.3+ features including:

• Typed class constants
• Enhanced type system
• Improved readonly properties
• Better attribute handling

Step 3: Replace Deprecated Classes and Methods

Replace SqlObject with SqlStatement

Before:

use ByJG\AnyDataset\Db\SqlObject;

$sql = new SqlObject('SELECT * FROM users');

After:

use ByJG\AnyDataset\Db\SqlStatement;

$sql = new SqlStatement('SELECT * FROM users');

Replace DbFunctionsInterface with DatabaseExecutor

Before:

public function __construct(DbFunctionsInterface $dbFunctions)
{
    $this->dbFunctions = $dbFunctions;
}

After:

public function __construct(DatabaseExecutor $executor)
{
    $this->executor = $executor;
}

Or, if you were accessing it through Repository:

Before:

$driver = $repository->getDbDriver();

After:

$executor = $repository->getExecutor();

Replace UniqueIdGeneratorInterface with MapperFunctionInterface

Before:

use ByJG\MicroOrm\Interface\UniqueIdGeneratorInterface;

class MyGenerator implements UniqueIdGeneratorInterface
{
    // ...
}

After:

use ByJG\MicroOrm\Interface\MapperFunctionInterface;

class MyGenerator implements MapperFunctionInterface
{
    public function update(mixed $value, object $instance, string $field): mixed
    {
        // your logic
    }

    public function select(mixed $value, object $instance, string $field): mixed
    {
        // your logic
    }
}

Replace UUID Mapper Classes

Before:

use ByJG\MicroOrm\MapperFunctions\SelectBinaryUuidMapper;
use ByJG\MicroOrm\MapperFunctions\UpdateBinaryUuidMapper;

$field->withUpdateFunction(new UpdateBinaryUuidMapper());
$field->withSelectFunction(new SelectBinaryUuidMapper());

After:

use ByJG\MicroOrm\MapperFunctions\FormatUpdateUuidMapper;
use ByJG\MicroOrm\MapperFunctions\FormatSelectUuidMapper;

$field->withUpdateFunction(new FormatUpdateUuidMapper());
$field->withSelectFunction(new FormatSelectUuidMapper());

Replace Mapper::addFieldMap() with addFieldMapping()

Before:

$mapper->addFieldMap(
    'propertyName',
    'field_name',
    fn($value) => strtoupper($value),  // update function
    fn($value) => strtolower($value)   // select function
);

After:

use ByJG\MicroOrm\FieldMapping;

$fieldMapping = FieldMapping::create('propertyName')
    ->withFieldName('field_name')
    ->withUpdateFunction(new class implements MapperFunctionInterface {
        public function update(mixed $value, object $instance, string $field): mixed {
            return strtoupper($value);
        }
        public function select(mixed $value, object $instance, string $field): mixed {
            return strtolower($value);
...

Release 5.0.8

What's Changed

• Refactor query helper initialization for clarity by @byjg in #31

Full Changelog: 5.0.7...5.0.8

5.0.7

What's Changed

• feat: extend build methods to accept DbDriverInterface and add MySQL alias and subquery join tests by @HilarioJrx in #29
• Add bulk transaction support and enhanced DB interface compatibility by @byjg in #30

Full Changelog: 5.0.5...5.0.7

Release 5.0.6

What's Changed

• Add support for null and inclusion query conditions by @byjg in #28

Full Changelog: 5.0.4...5.0.6

Release 5.0.5

What's Changed

• Add support for null and inclusion query conditions by @byjg in #28

Full Changelog: 5.0.4...5.0.5

Release 5.0.4

What's Changed

• Add DISTINCT keyword support to Query classes by @byjg in #27

Full Changelog: 5.0.3...5.0.4

Release 5.0.3

What's Changed

• feat: add TablePgsqlUuidPKAttribute.php to work with pk uuid on postgres by @HilarioJrx in #26

Full Changelog: 5.0.2...5.0.3

Release 5.0.2

What's Changed

• Added InsertBulkQuery by @byjg in #24

Full Changelog: 5.0.1...5.0.2

Release 5.0.1

What's Changed

• Enable Cache Query results by @byjg in #21
• Add Soft Delete and Others by @byjg in #22
• Add ActiveRecord::reset() method by @byjg in #23

Full Changelog: 5.0.0...5.0.1

Release 5.0.0

What's Changed

• Implement PHP 8.1 with Breaking change features by @byjg in #14

Full Changelog: 4.9.4...5.0.0