Waiting for breaking change improvement proposals until V1 Q4 2026 release

[marius-ciclistu]

I am looking for suggestions and ideas of what new improvements could I/we do before V1 release from the end of 2026, that require breacking changes.

Currently the php ecosystem is in RC version and the time left can be used proactively.

What was accomplished so far can be seen in the releases and commits sections of each project. If you like fabulas, you can read a high level metaphoric presentation in The API Grand Prix.

The Active record and global helpers will stay because RetrieveQL relies on them.

The documentation is up to date with the latest code changes: https://macropay-solutions.github.io/php-framework-docs/1.x/.

[marius-ciclistu]

Contextual bindings will be removed to avoid developer convenience slowing down the execution with no real gains.

[macropay-solutions]

https://github.com/macropay-solutions/php-kernel/releases/tag/1.0.0-RC-46

[marius-ciclistu]

Event Subscribers could be next on the removal list:

The Not Recommended Way (Event Subscriber):

<?php
namespace App\Listeners;

use MacropaySolutions\Kernel\Auth\Events\Login;
use MacropaySolutions\Kernel\Auth\Events\Logout;
use MacropaySolutions\Kernel\Events\Dispatcher;

class UserEventSubscriber
{
    public function handleUserLogin(Login $event): void {}
    public function handleUserLogout(Logout $event): void {}

    public function subscribe(Dispatcher $events): void
    {
        $events->listen(Login::class, [UserEventSubscriber::class, 'handleUserLogin']);
        $events->listen(Logout::class, [UserEventSubscriber::class, 'handleUserLogout']);
    }
}

// Register in EventServiceProvider:
protected $subscribe = [
    UserEventSubscriber::class,  // ❌ NOT RECOMMENDED
];

Problem: This subscriber gets instantiated and registered every single request. Framework has to dynamically discover and boot it each time, bypassing the caching layer.

The Recommended Way (Class-based Listeners):

<?php
namespace App\Listeners;

use MacropaySolutions\Kernel\Auth\Events\Login;

class HandleUserLogin
{
    public function handle(Login $event): void {}
}

// Register in EventServiceProvider:
protected $listen = [
    Login::class => [
        HandleUserLogin::class,  // ✅ RECOMMENDED
    ],
];

// Then cache it:
// php artisan event:cache

Benefit: The event:cache command compiles these listeners into memory once, so they're available instantly on every request without dynamic registration overhead.

[marius-ciclistu]

Also closure based event listeners should be banned: #3
macropay-solutions/php-crufd-wizard#1
Model::observe should do nothing at app boot time WHEN observers are cached because the results are cached anyway.

[macropay-solutions]

Done in 65b98a2

[marius-ciclistu]

Json Resources will go also. As stated in docs, they are replaced by php-crufd-wizard + php-crufd-wizard-decorator

The Base Classes:

MacropaySolutions\Kernel\Http\Resources\Json\JsonResource

MacropaySolutions\Kernel\Http\Resources\Json\ResourceCollection

MacropaySolutions\Kernel\Http\Resources\Json\AnonymousResourceCollection

The Response Handlers:

MacropaySolutions\Kernel\Http\Resources\Json\ResourceResponse

MacropaySolutions\Kernel\Http\Resources\Json\PaginatedResourceResponse

The "Magic" Traits & Helpers (The source of the conditional logic bugs):

MacropaySolutions\Kernel\Http\Resources\ConditionallyLoadsAttributes (This contains the buggy whenLoaded() logic)

MacropaySolutions\Kernel\Http\Resources\DelegatesToResource (The trait that blindly forwards missing methods to the underlying object)

MacropaySolutions\Kernel\Http\Resources\CollectsResources (Trait used by collections)

MacropaySolutions\Kernel\Http\Resources\MergeValue

MacropaySolutions\Kernel\Http\Resources\MissingValue

MacropaySolutions\Kernel\Http\Resources\PotentiallyMissing (Interface)

[macropay-solutions]

Done in 65b98a2

[marius-ciclistu]

Architectural Note: High-Performance Timestamps, Soft Deletes & Migrations by Gemini (It contains the high level idea. The code is not acc to PSR12 and it contains the else word... Also $dates should be removed and replaced by casts)
🎯 The Philosophy

Standard Obvious relies on heavy Carbon objects, expensive Database Grammar lookups, and dynamic type-casting just to save, delete, and read dates. Furthermore, standard migrations default to SQL TIMESTAMP columns, which perform hidden, database-level timezone conversions.

To achieve maximum performance and perfect timezone predictability, I will modify the Kernel to process timestamps strictly as raw PHP strings natively, and ensure the database stores them as literal strings (DATETIME). Carbon will become "Lazy" — it will never be instantiated by the php-framework unless I explicitly request it via the $dates or $casts arrays.
🛠️ 1. Kernel Changes (The Core Model)

I will eliminate the reliance on the php-framework's runtime $dateFormat variable and grammar queries by baking the formats directly into the base Kernel Model.

In MacropaySolutions\Kernel\Database\Obvious\Model:

Compile-Time Constants: I will define the formats as static constants at the root Kernel level. This skips database connection lookups and allows child models to override them if needed.
PHP

public const CREATED_AT_FORMAT = 'Y-m-d H:i:s';
public const UPDATED_AT_FORMAT = 'Y-m-d H:i:s';
public const DELETED_AT_FORMAT = 'Y-m-d H:i:s';

String Casting on Read: I will enforce that timestamps return as raw strings when fetching from PDO, bypassing Obvious's default Carbon auto-casting.
PHP

protected function getDates()
{
    // Override standard Obvious behavior. 
    // Do NOT auto-append created_at/updated_at/deleted_at to be cast to Carbon by default.
    // Only return what the developer explicitly added to the $dates array.
    return $this->dates ?? [];
}

⚙️ 2. Kernel Changes (The Core Traits)

I will directly modify the php-framework's core traits in MacropaySolutions\Kernel\Database\Obvious\Concerns\ to stop using $this->freshTimestamp() and instead use native PHP \date() paired with the new Kernel constants.

In HasTimestamps.php (updateTimestamps method):

Raw String Injection: I will update this to generate strings instantly using the static constants.

Built-in "Silent Save": I will add the logic where setting $model->updated_at = '' restores the original value, bypassing the update without needing saveQuietly().

PHP

public function updateTimestamps()
{
// Fast native string, using the Kernel Model's constant
$time = \date(static::UPDATED_AT_FORMAT);

$updatedAtColumn = $this->getUpdatedAtColumn();

if (! is_null($updatedAtColumn)) {
    if ($this->getAttribute($updatedAtColumn) === '') {
        $this->setUpdatedAt($this->getOriginal($updatedAtColumn)); // Silent save bypass
    } elseif (! $this->isDirty($updatedAtColumn)) {
        $this->setUpdatedAt($time);
    }
}

$createdAtColumn = $this->getCreatedAtColumn();
if (! $this->exists && ! is_null($createdAtColumn) && ! $this->isDirty($createdAtColumn)) {
    $this->setCreatedAt(\date(static::CREATED_AT_FORMAT));
}

return $this;

}

In SoftDeletes.php (runSoftDelete method):

Soft Deletes Optimization: I will strip out freshTimestamp() and fromDateTime() entirely.

I will inject the raw string directly into the query builder array for both deleted_at and updated_at, sharing the exact same fast \date() call.

PHP

protected function runSoftDelete()
{
$query = $this->setKeysForSaveQuery($this->newModelQuery());

// Generate string instantly using the Kernel's deleted_at constant
$time = \date(static::DELETED_AT_FORMAT);

$deletedAtColumn = $this->getDeletedAtColumn();
$columns = [$deletedAtColumn => $time];
$this->{$deletedAtColumn} = $time;

if ($this->timestamps && ! is_null($updatedAtColumn = $this->getUpdatedAtColumn())) {
    $this->{$updatedAtColumn} = $time;
    $columns[$updatedAtColumn] = $time;
}

$query->update($columns);
$this->syncOriginalAttributes(\array_keys($columns));
$this->fireModelEvent('trashed', false);

}

🏗️ 3. Kernel Changes (The Schema Blueprint)

To ensure the database does not perform hidden timezone conversions on my fast PHP strings, I will modify the Schema Builder so that the migration helpers generate DATETIME columns instead of TIMESTAMP columns.

In MacropaySolutions\Kernel\Database\Schema\Blueprint:
I will update the timestamps() and softDeletes() methods to map to dateTime instead of timestamp.
PHP

/**
 * Add creation and update timestamps to the table (as DATETIME).
 */
public function timestamps($precision = 0)
{
    $this->dateTime('created_at', $precision)->index();
    $this->dateTime('updated_at', $precision)->nullable();
}

/**
 * Add a "deleted_at" timestamp for the table (as DATETIME).
 */
public function softDeletes($column = 'deleted_at', $precision = 0)
{
    return $this->dateTime($column, $precision)->nullable();
}

🚀 The Result (Why this will be genius)

Zero Double-Timezone Bugs: By switching from TIMESTAMP to DATETIME in migrations, the database will store the exact literal string generated by PHP's \date(). There will be no hidden SQL-level UTC conversions.

Seamless Migrations: I will still use $table->timestamps() and $table->softDeletes() in my migration files just like before, but they will generate the safer, optimized DATETIME columns automatically.

Zero PHP Overhead: Bulk inserting, updating, or soft-deleting 10,000 rows will create 0 Carbon objects instead of 10,000.

Developer Experience Maintained: If a developer really wants a Carbon object to do date math, they will just add 'created_at' or 'deleted_at' to their protected $dates array, or use 'deleted_at' => 'datetime' in their protected $casts array. The php-framework will respect either approach and lazy-instantiate the Carbon object strictly on demand.

Update. datetime cast is gone.

[marius-ciclistu]

Currently, custom class casts and object casts step directly into the territory of Accessors and Mutators.

When objects (except BackedEnum) are used for casting, the engine is forced to merge and sync these mutated states back into raw arrays on every single save() operation just to check for dirty states and build queries. Furthermore, toArray() runs these same expensive object hydrations and transformations just to turn them back into strings for JSON output.

This slows down the core execution massively, and this overhead exists solely for developer convenience.

For V1, I propose we strictly restrict $casts to int, string, and BackedEnum only.

Here is why this is the right architectural move:

HTTP Only Speaks Strings: HTTP requests don't send native booleans, dates, or arrays—they send raw strings. Keeping our casts aligned with scalar primitives prevents artificial type-churn.

Zero save() Overhead: By keeping the underlying $attributes strictly as raw database primitives, we completely eliminate the need for complex object diffing and array merging on write operations.

Blazing Fast toArray(): Serialization becomes a direct O(1) dump of the raw attributes. We stop paying the "Carbon tax" or triggering json_decode loops for data that is just going to be sent out as JSON anyway.

Backed Enums Fit Perfectly: Unlike custom objects, a BackedEnum strips down to a pure scalar value (string or int) instantly on write, meaning it gives backend developers type-safety without breaking the raw storage rules.

Complex object hydration, UI formatting, or JSON decoding belongs in the presentation layer, virtual $appends, or DTOs—not hardcoded into the core storage pipeline.

[marius-ciclistu]

Furthermore, using accessors to return complex objects introduces a severe state-synchronization flaw.

If an accessor returns a mutable object (like a decoded JSON object or a custom class), mutating that object in memory does not automatically update the underlying $attributes array. The framework cannot track deep object mutations without massive proxy overhead. This forces the developer to manually write mutators just to merge and serialize the mutated values back into the raw storage array before saving.

Bottom line: Accessors should not return objects. They must strictly return primitives, with BackedEnum being the only allowable exception since enums are strictly immutable and instantly resolve back to a scalar value on assignment.

Accessors must strictly return int | string | BackedEnum | null. Returning mutable objects violates the state-synchronization guarantee and is forbidden.

protected function mutateAttribute($key, $value)
    {
        $result = $this->resolveSegregatedAccessorClosure($key)->call($this, $value);

        // ENFORCE THE RULE: Only allow int, string, BackedEnum, or null
        if ($result !== null && !is_string($result) && !is_int($result) && !($result instanceof \BackedEnum)) {
            throw new \LogicException(sprintf(
                "Kernel Violation: Accessor for attribute '%s' on model '%s' must return int, string, BackedEnum, or null. Returned '%s'. Mutable objects are strictly forbidden to prevent state-synchronization flaws.",
                $key,
                static::class,
                get_debug_type($result)
            ));
        }

        return $result;
    }

This will remove over 1400 lines of complex, CPU-heavy execution loops from HasAttributes.php.

[marius-ciclistu]

For cast optimization:

1. The Strict $primitiveCastTypes Property

protected static $primitiveCastTypes = [
    'int',
    'string',
];

2. The Runtime castAttribute Method

protected function castAttribute($key, $value)
{
    if ($value === null) {
        return null;
    }

    $castType = $this->getCastType($key);

    return match ($castType) {
        'int' => (int) $value,
        'string' => (string) $value,
        default => $this->isEnumCastable($key)
            ? $this->getEnumCastableAttributeValue($key, $value)
            : throw new \InvalidCastException(
                sprintf(
                    'Invalid cast type "%s" for attribute "%s" on model [%s]. ' .
                    'V1 strictly allows "int", "string", or a valid \BackedEnum FQN.',
                    $castType,
                    $key,
                    static::class
                )
            ),
    };
}

3. The Strict isEnumCastable Runtime Check

protected function isEnumCastable($key)
{
    $casts = $this->getCasts();

    if (!isset($casts[$key])) {
        return false;
    }

    $castType = $casts[$key];

    if (in_array($castType, static::$primitiveCastTypes, true)) {
        return false;
    }

    return enum_exists($castType) && is_subclass_of($castType, \BackedEnum::class);
}

[macropay-solutions]

DONE github.com/macropay-solutions/php-kernel/commit/65b98a2926df8637babecab95dfffe9e19bd8d69 github.com/macropay-solutions/php-kernel/commit/24b115b736050f913935b6c5586f785c33b067d8 github.com/macropay-solutions/php-kernel/commit/1bd824082f91bbdc52fc7d3f163680bc8676c86c github.com/macropay-solutions/php-kernel/commit/c490ddb48faec87c2487ba6f8fdb47c5cdf227ed 3600 lines of code deleted

[marius-ciclistu]

Document purpose of rate limit which does not replace server rate limits. See https://marius-ciclistu.medium.com/the-hidden-cost-of-fast-rejections-why-framework-boot-time-is-sinking-your-infrastructure-f2298ce4bc86

[macropay-solutions]

Done https://macropay-solutions.github.io/php-framework-docs/1.x/rate-limiting

[marius-ciclistu]

The http client should also be purged. Guzzle or curl can be used instead.

[macropay-solutions]

DONE https://github.com/macropay-solutions/php-kernel/releases/tag/1.0.0-RC-49

[marius-ciclistu]

Morphable relations maybe? I am not sure yet. I never used them because they are slower than normal relations. RetrieveQL does not support them anyway.

[marius-ciclistu]

Maybe the helpers from HasRelationships trait like hasMany, hasOne and so on, should NOT have optional parameters to avoid the time lost in guessing them.

If they don't have to be guessed, then those helper methods can be moved from the trait/model.

Here is what the architecture would look like:

1. The Segregated Map (Inside the Model):

protected function segregatedRelationsDefinitionMap(): array
{
    return [
        'comments' => fn(): HasMany => HasMany::make(
            $this,           // Parent model (preserves connection state)
            Comment::class,  // Related model
            'post_id',       // Mandatory explicit foreign key
            'id'             // Mandatory explicit local key
        ),
    ];
}

2. The Static Factory (Inside HasMany / Relation classes):

class HasMany extends Relation
{
    public static function make(Model $parent, string $related, string $foreignKey, string $localKey): static
    {
        $instance = $parent->newRelatedInstance($related); 
        
        // We still use di() so the relation can be swapped/resolved via the container!
        return \di(static::class, [
            $instance->newQuery(),
            $parent,
            $instance->getTable() . '.' . $foreignKey,
            $localKey
        ]);
    }
}

The Result for V1:
Zero parameter-guessing overhead.

The HasRelationships trait can be smaller, drastically shrinking the Model class footprint.

We preserve 100% DI testability and modularity because of di().

Edit. The above make factory was not implemented!

[macropay-solutions]

DONE
https://github.com/macropay-solutions/php-kernel/releases/tag/1.0.0-RC-50
Removed morphism and refactored the hasRelationships to require all params for hasMany etc.
over 3840 lines removed

[macropay-solutions]

Removing custom casts allowed the model serialization to be improved https://macropay-solutions.github.io/php-framework-docs/1.x/obvious.html#model-serialization-and-state-freezing

[marius-ciclistu]

Container optimization to avoid double failure

public function build($concrete, array $parameters = []): mixed
{
    if ($concrete instanceof Closure) {
        return $concrete($this, $parameters);
    }

    $parameters = (
        [] === BoundMethod::getAndCachePrecompiledAutoWiringClassMethodParametersMapForClassAndMethod(
            \ltrim($concrete, '\\'),
            '__construct'
        )
    ) ? [] : ($parameters === [] || !\array_is_list($parameters) ?
        \array_values(BoundMethod::getConstructDependencies(
            $this,
            $concrete,
            $parameters
        )) : $parameters);

    // Track the class for autowiring discovery BEFORE we instantiate
    BoundMethod::addToClassesFqnsToCacheForAutowire($concrete);

    try {
        // FAST PATH: This is all you need.
        return new $concrete(...$parameters);
    } catch (\Error $e) { 
        // ONLY catch native PHP fatal errors (e.g., trying to instantiate an interface).
        // Let standard Application Exceptions bubble up instantly!
        
        try {
            $reflector = new ReflectionClass($concrete);
        } catch (ReflectionException $e2) {
            throw new BindingResolutionException("Target class [$concrete] does not exist.", 0, $e2);
        }

        if (!$reflector->isInstantiable()) {
            $this->notInstantiable($concrete);
        }
        
        throw $e;
}

[macropay-solutions]

https://packagist.org/packages/macropay-solutions/php-kernel#1.0.0-RC-54

   public function build(\Closure|string $concrete, array $parameters = []): mixed
    {
        if ($concrete instanceof Closure) {
            return $concrete($this, $parameters);
        }

        if (!\class_exists($concrete)) {
            if (\interface_exists($concrete)) {
                throw new BindingResolutionException('Target interface [' . $concrete . '] is not instantiable.');
            }

            if (\trait_exists($concrete)) {
                throw new BindingResolutionException('Target trait [' . $concrete . '] is not instantiable.');
            }

            throw new BindingResolutionException('Target class [' . $concrete . '] does not exist.');
        }

        BoundMethod::addToClassesFqnsToCacheForAutowire($concrete);

        if (
            [] === BoundMethod::getAndCachePrecompiledAutoWiringClassMethodParametersMapForClassAndMethod(
                \ltrim($concrete, '\\'),
                '__construct'
            )
        ) {
            return new $concrete();
        }

        if ($parameters === [] || !\array_is_list($parameters)) {
            return new $concrete(...\array_values(BoundMethod::getConstructDependencies(
                $this,
                $concrete,
                $parameters
            )));
        }

        return new $concrete(...$parameters);
    }

[marius-ciclistu]

The Application's methods that are there just to comply with the contract but are doing nothing, should be removed together with the contract method definition.

[macropay-solutions]

https://packagist.org/packages/macropay-solutions/php-kernel#1.0.0-RC-57

[marius-ciclistu]

Model::where should be removed in favor of Model::query()->where

[macropay-solutions]

https://github.com/macropay-solutions/php-kernel/releases/tag/1.0.0-RC-56

[marius-ciclistu]

The through convention from __call should also be removed together with the actual through method and functionality.

Also these should be history in obvious builder

User::whereEmail($email);
User::whereNameAndStatus($name, $status);

[macropay-solutions]

https://github.com/macropay-solutions/php-kernel/releases/tag/1.0.0-RC-56

[marius-ciclistu]

QueriesRelationships trait has these magic methods

• whereBelongsTo() — hides foreign-key and relationship resolution;
• orWhereBelongsTo() — same inference plus implicit boolean composition;

[macropay-solutions]

https://github.com/macropay-solutions/php-kernel/releases/tag/1.0.0-RC-56

[macropay-solutions]

Some methods from model were made public and strictly typed
https://github.com/macropay-solutions/php-kernel/releases/tag/1.0.0-RC-58

The model no longer forwards its calls to the builder implicitly.

[marius-ciclistu]

Model local scopes should not polute the model with methods so, replace dynamic method construction with a map lookup:

public function hasNamedScope($scope)
{
    return isset($this->segregatedScopesMap()[$scope]);
}


public function callNamedScope(
    string $scope,
    array $parameters = []
): Builder {
    return $this->segregatedScopesMap()[$scope](...$parameters);
}

Map in model:

protected function segregatedScopesMap(): array
{
    return [
        'active' => static function (Builder $obviousBuilder): Builder {
            return $obviousBuilder->where('active', 1);
        },
    ];
}

The builder should stop handling scopes via __call.
->scopes('scope') should be used instead to avoid name collisions with the query builder methods.

[macropay-solutions]

https://github.com/macropay-solutions/php-kernel/releases/tag/1.0.0-RC-61 The implementation is a bit different.

public static function segregatedScopesMap(): array
{
    return [
        'active' => static function (Builder $obviousBuilder): Builder {
            return $obviousBuilder->where('active', 1);
        },
    ];
}

hasNamedScope was removed from both model and obvious builder.

    protected function callNamedScope($scope, array $parameters = [])
    {
        return $this->callScope(function (...$parameters) use ($scope) {
            return $this->model::segregatedScopesMap()[$scope](...$parameters);
        }, $parameters);
    }

[macropay-solutions]

🚀 Release 1.0.0-RC-62: Builder Extensions Refactor & High-Performance Soft Deletes
We are excited to announce 1.0.0-RC-62, bringing major architectural and performance improvements to our database query builder! This release unifies query builder customization under a cleaner Extensions API and drastically reduces memory overhead during soft-delete operations by eliminating per-builder Closure allocations.

🔑 Key Highlights

1. Renamed Local Macros to Extensions
   To cleanly differentiate stateful, global Closures ($this binding) from stateless, local query helpers, we have officially replaced the Local Macros concept with Local Extensions.

API Changes:

$builder->addLocalMacro() ➡️ $builder->addExtension()

$builder->hasMacro() ➡️ $builder->hasExtension()

$builder->getMacro() ➡️ $builder->getExtension()

Flexibility: Extensions now accept any valid PHP callable (closures, invokable objects, or array callables like [FlightFilters::class, 'active']).

Signature: Injected closures or callables explicitly receive the $builder instance as their first argument (fn (Builder $builder, ...$args)), keeping extensions pure and stateless.

2. High-Performance, Zero-Allocation Soft Deleting
   Previously, every time a new query builder instance was spun up (e.g., Flight::query()), SoftDeletingScope bound multiple isolated Closure instances per builder to register soft-delete macros like withTrashed, restore, and onlyTrashed.

What changed:

Soft-delete extension logic has been refactored to use array callables ([$this, 'restore'], [$this, 'withTrashed'], etc.) referencing the single, booted SoftDeletingScope service object.

onDelete now accepts callable callbacks directly instead of requiring a Closure.

Performance Impact:
When executing thousands of queries during a request lifecycle, memory allocations for scope methods drop to zero additional closures, resulting in faster query initialization and lower memory overhead across your application.

🛠️ Code Comparison
❌ Before (Pre-RC-62)
PHP
// SoftDeletingScope allocating dynamic closures per query builder instance:
$builder->addLocalMacro('restore', function (Builder $builder) {
$builder->withTrashed();
return $builder->update([$builder->getModel()->getDeletedAtColumn() => null]);
});

$builder->onDelete(function (Builder $builder) {
// Delete closure bound per builder
});
✅ After (RC-62)
PHP
// SoftDeletingScope reusing a single stateless instance with array callables:
$builder->addExtension('restore', [$this, 'restore']);
$builder->onDelete([$this, 'performDelete']);

// Custom local extension registration:
$query->addExtension('active', [FlightFilters::class, 'active']);
$flights = $query->active()->get();
📝 Breaking Changes & Migration Guide
If you directly interacted with local macro APIs or custom global scopes in your application:

Update Method Calls: Replace calls to addLocalMacro, hasMacro, or getMacro on the Builder with addExtension, hasExtension, and getExtension.

Update Type Hints: If you overridden scope registration methods, ensure onDelete() and extension definitions use callable instead of strict Closure type hints.

🔗 Useful Links
Release: v1.0.0-RC-62 on GitHub

NOTE

Before v1.0.0-RC-62, the local macro retrieval and soft-deleting setup worked as follows:

1. getMacro() (now getExtension())
   Before: getMacro($name) used Arr::get($this->localMacros, $name). If the macro wasn't registered, it silently returned null.

Now: getExtension($name) strictly throws an exception if the extension key does not exist on the builder or is not callable, catching missing extensions early instead of failing silently when invoked

[macropay-solutions]

Fix arbitrary command injection in Scheduler and Queue Worker https://github.com/macropay-solutions/php-kernel/releases/tag/1.0.0-RC-63

[macropay-solutions]

Updated Model's properties A and R from private to protected to allow this php 8.4 magic bypass : https://marius-ciclistu.medium.com/eliminate-magic-property-access-for-model-attributes-and-relations-in-obvious-model-orm-6d5ba666e786

[macropay-solutions]

This qualifies as a breaking change also https://marius-ciclistu.medium.com/php-framework-from-macropay-solutions-prevents-validation-rule-injection-37c587e38201

[macropay-solutions]

https://github.com/macropay-solutions/php-kernel/releases/tag/1.0.0-RC-70

https://github.com/macropay-solutions/php-kernel/releases/tag/1.0.0-RC-71

https://github.com/macropay-solutions/php-kernel/releases/tag/1.0.0-RC-72

Refactor: Enforce strict Model architecture, eliminate magic forwarding, and decouple HTTP routing

This commit introduces a fundamental architectural shift to the Macropay-Solutions PHP-Framework, officially transitioning the ORM from a legacy "God Class" pattern to a strictly typed, explicit engine. It removes deep-rooted magic, enforces PHP 8 type contracts globally, and cleanly segregates the Database and HTTP layers.

Key Architectural Changes:

Eliminated Query Builder Proxying: Removed the ForwardsCalls trait and gutted the Model::__call() fallback. Magic queries (e.g., $model->where() or static Model::find()) are no longer supported. Developers must now explicitly request the builder via Model::query()->where().

Decoupled ORM from the HTTP Layer: Deleted the UrlRoutable interface and eradicated all route-binding leakage from the ORM. Gutted implicit model binding resolution from Broadcaster and UrlGenerator, enforcing explicit scalar ID passing across the framework.

Enforced Strict Interface Contracts: Upgraded foundational interfaces (Arrayable, Jsonable, CanBeEscapedWhenCastToString) with strict PHP 8 return types (: array, : string, : static). Systematically propagated these strict contracts across all implementing classes, including Paginator, Collection, Fluent, MessageBag, and ValidatedInput.

Optimized Internal Execution: Replaced legacy call_user_func() mechanisms with highly optimized direct static closure invocations (e.g., (static::$callback)($this, $keys)).

Bypassed Magic Method Overhead: Refactored internal framework logic (such as unique ID generation in HasUniqueIds) to use explicit getAttributeValue() and setAttribute() methods, bypassing expensive __get/__set magic method loops.

Secured Serialization Accuracy: Changed the default value of HasAttributes::$snakeAttributes to false to prevent the hidden mutation of camelCase column names during array/JSON serialization.

Breaking Changes:

UrlRoutable is removed; implicit model injection in controllers and broadcast channels requires manual ID fetching.

Direct builder method calls on model instances will now throw a BadMethodCallException. Always chain from ->query().

1000 lines deleted

[marius-ciclistu]

Macros are not inheritable... Child classes registered in DI can't inherit from multiple packages... that leads to manual registration via traits. Maybe I can find a better and faster solution that fixes both issues.

[macropay-solutions]

https://macropay-solutions.github.io/php-framework-docs/production/macros.html#dedicated-trait-architecture--aot-compilation

https://packagist.org/packages/macropay-solutions/php-kernel#1.0.0-RC-84

An Ahead-of-Time (AOT) compilation architecture has been implemented that solves both the macro inheritance leakage and the multiple-package registration bottleneck while achieving zero-overhead execution.
Here is how the new system resolves the mentioned constraints:

Dedicated Trait Architecture (Strict Isolation):

Instead of relying on a single shared Macroable trait that leaks static state across the inheritance tree, every macroable class and subclass now receives its own unique, flattened FQN trait (e.g., MacropaySolutionsKernelDatabaseObviousCollection). This ensures every class has its own strictly isolated memory space.

Dynamic Dev Resolution vs. Native Prod Execution:

• In local development, the system relies on standard magic methods where child classes dynamically traverse the inheritance tree (resolveMacro) to execute parent macros.
• In production, the new macro:cache command evaluates all boot-time registrations and compiles those deferred macros into concrete, native PHP methods directly inside each class's dedicated trait file.

Multi-Package Support via Deferred Macros:

Multiple packages can successfully hook into the same core class by registering a deferredMacro during the Service Provider boot phase. The AOT compiler flattens all of them into native methods side-by-side on the target class, completely eliminating closure-binding overhead for static methods.

Automated CI Enforcement (No Regression Leakage):

To prevent manual registration omissions from causing inheritance leaks, a dynamic unit test now strictly enforces this architecture framework-wide. By scanning Composer's autoload_classmap.php and utilizing PHP reflection, the test verifies that every single subclass implementing the Macroable contract explicitly utilizes its own dedicated fallback trait.

[marius-ciclistu]

Console $components and the related classes are now gone and their usage replaced because they were just a convenience slower wraper.

[macropay-solutions]

https://packagist.org/packages/macropay-solutions/php-kernel#1.0.0-RC-98

unserialize allowed_classes false and base64_decode strict true

To avoid POI and RCE

[macropay-solutions]

https://packagist.org/packages/macropay-solutions/php-kernel#1.0.0-RC-99

Warning

Mail Events Cannot Be Queued: To prevent queue payload bloat and memory exhaustion from large MIME bodies and file attachments, MessageSending and MessageSent events, as well as the underlying SentMessage wrapper, are strictly synchronous. Attempting to attach a queued listener to these events or serialize them will throw a LogicException.

Instead the mail sending should be queued.

[marius-ciclistu]

https://medium.com/@marius-ciclistu/closing-the-pop-chain-hardening-php-framework-deserialization-against-poi-attacks-bd735f56145d

[marius-ciclistu]

Patched timing attack on app key rotation in rc 104 and fixed the cipher rotation also.

[macropay-solutions]

Rip out most of the magic and replace it with ->to() and ->toStatic(). For manager classes the magic remains.
Rip out magic from View.php for dynamic with{Word}. ->with('{word}', $param) should be used instead.

https://packagist.org/packages/macropay-solutions/php-kernel#1.0.0-RC-105

Release Notes: Architectural Strictness & Magic Removal

Overview

This release introduces a massive architectural shift focused on strict typing, static analysis compliance, and the eradication of runtime "magic." By removing dynamic method interception and higher-order proxies, the framework provides more transparency to IDEs and static analysis tools (like PHPStan and Psalm).

💥 Breaking Changes

• Higher-Order Proxies Eliminated:
  • All Higher-Order proxy classes (HigherOrderBuilderProxy, HigherOrderCollectionProxy, HigherOrderTapProxy, and HigherOrderWhenProxy) have been permanently deleted.
  • You can no longer omit closures on collection/conditionable methods. Calls like $collection->each->update(...), tap($user)->update(...), or $query->when($condition)->active() must now be written with explicit closures: $collection->each(fn($item) => $item->update(...)).
  • The tap(), when(), and unless() methods now strictly require a callable argument.
• Dynamic View Bindings Removed:
  • The __call magic inside View.php that handled dynamic variable binding has been removed.
  • You can no longer use $view->withTitle('foo'). You must use the explicit syntax: $view->with('title', 'foo').
• Decorator & Wrapper Strictness:
  • Wrapper classes no longer silently forward missing methods via __call.
  • Classes including Cache\Repository, FilesystemAdapter, ViewErrorBag, SentMessage, Optional, InvokableComponentVariable, AbstractPaginator, and AbstractCursorPaginator will now throw a BadMethodCallException if you attempt to call underlying driver methods directly on them. You must now explicitly unwrap them using the ->to() method.
• Global str() Helper Removed:
  • The dynamic str() global helper has been completely removed to enforce strict typing. All string manipulations must now use Str::of().
• Obvious Model Relation Execution:
  • Dynamic relation execution via the model's __call method is now disabled and throws an exception. You must use $model->r->relationName() or $model->callSegregatedRelation('relationName').
• Obvious Builder Proxies Removed:
  • Magic __get intercepts for orWhere, whereNot, and orWhereNot have been removed from the Database Builder.

✨ New Features & Enhancements

• Explicit Unwrapping (->to()) on Managers:
  • Added a strict ->to() method across all core Manager classes (AuthManager, CacheManager, DatabaseManager, LogManager, MailManager, QueueManager, RedisManager, FilesystemManager, BroadcastManager, PasswordBrokerManager, MultipleInstanceManager, and Process\Factory).
  • Calling ->to() explicitly returns the underlying active driver/connection, allowing for perfect static analysis.
  • Note: Manager classes retain their __call fallback logic to prevent widespread application breakage, but ->to() is the recommended standard.
• Static Unwrapping (::toStatic()) on Capsules:
  • Added ::toStatic() to Database\Capsule\Manager and Queue\Capsule\Manager to explicitly retrieve the underlying default connection in static contexts.
• New Forwarding Trait:
  • Introduced ExplicitForwardable trait. This trait standardize the new strict architecture by intercepting __call to throw a clear BadMethodCallException directing developers to use ->to() or ::toStatic() instead.

[macropay-solutions]

RC 106
Rip out most of the magic and replace it with ->fwd() and ::sfwd(). For manager classes the magic remains. Replace to with fwd and sfwd from to and toStatic

[marius-ciclistu]

All this because CTL+CLICK beats annotation's magic.

[marius-ciclistu]

The deferred macro logic can improve bindings registration.
Usimg array callables instead of closures will lower the memory and increase the boot speed.

This is a high level idea. Register Explicit Bindings could be kept for middlewares etc. instead of being removed.

/**
//         * To avoid calls to
//         * @see \MacropaySolutions\Framework\Concerns\RoutesRequests::routeMiddleware()
//         * Note that you can use the middleware FQN on a route without declaring its alias here!
//         */
//        $this->routeMiddleware['decorate-' . ResourceClass::RESOURCE_NAME] =
//            \App\Http\Middleware\ResourceClassDecorator::class;
//        $this->foundRouteMiddleware['decorate-' . ResourceClass::RESOURCE_NAME] =
//            \App\Http\Middleware\ResourceClassDecorator::class;
    }

Patch 1: kernel/Container/Container.php

Diff

--- kernel/Container/Container.php
+++ kernel/Container/Container.php
@@ -201,44 +201,17 @@
     /**
      * Register a binding with the container.
-     *
-     * @param string $abstract
-     * @param \Closure|string|null $concrete
-     * @param bool $shared
-     * @return void
-     *
-     * @throws \TypeError
+     * 
+     * Explicit bindings accept a class FQCN string, a static Closure, or a static array callable (e.g. [Factory::class, 'make']).
+     * Array callables MUST use a class string as element 0 to remain state-free and memory-friendly under OPcache.
      */
-    public function bind($abstract, $concrete = null, $shared = false)
+    public function bind(string $abstract, array|string|\Closure|null $concrete = null, bool $shared = false): void
     {
         $this->dropStaleInstances($abstract);

-        // If the factory is not a Closure, it means it is just a class name which is
-        // bound into this container to the abstract type and we will just wrap it
-        // up inside its own Closure to give us more convenience when extending.
-        if (!$concrete instanceof Closure) {
-            if (!\is_string($concrete ??= $abstract)) {
-                throw new TypeError(
-                    self::class . '::bind(): Argument #2 ($concrete) must be of type Closure|string|null'
-                );
-            }
-
-            $concrete = $this->getClosure($abstract, $concrete);
-        }
+        $concrete ??= $abstract; // can be inlined bellow

         $this->bindings[$abstract] = ['concrete' => $concrete, 'shared' => $shared];

@@ -250,43 +223,6 @@
     }

-    /**
-     * Set all the container bindings that should be registered when the app is instantiated
-     * @see \MacropaySolutions\Kernel\Container\Container::getClosure for Closure format
-     * Must set array shape:
-     * [
-     *     "{$abstractString}" => [
-     *         'concrete' => \Closure,
-     *         'shared' => bool
-     *     ],
-     * ]
-     */
-    protected function registerExplicitBindingsMap(): void
-    {
-//        $this->bindings = [
-//            \MacropaySolutions\Kernel\Http\Request::class => [
-//                'concrete' => static function (
-//                     \MacropaySolutions\Kernel\Contracts\Container\Container $container,
-//                     array $parameters = []
-//                ): \MacropaySolutions\Kernel\Http\Request {
-//                    return $container->resolve(
-//                        \App\Requests\Request::class, // your child class
-//                        $parameters,
-//                        false
-//                    );
-//                },
-//                'shared' => false
-//            ],
-//        ];
-    }

-    /**
-     * Get the Closure to be used when building a type.
-     *
-     * @param string $abstract
-     * @param string $concrete
-     * @return \Closure
-     */
-    protected function getClosure($abstract, $concrete)
-    {
-        return static function ($container, $parameters = []) use ($abstract, $concrete) {
-            if ($abstract == $concrete) {
-                return $container->build($concrete);
-            }
-
-            return $container->resolve(
-                $concrete,
-                $parameters,
-                false // raiseEvents
-            );
-        };
-    }

     /**
      * Determine if the container has a method binding.
@@ -772,7 +708,7 @@
      */
     protected function isBuildable($concrete, $abstract)
     {
-        return $concrete === $abstract || $concrete instanceof Closure;
+        return $concrete === $abstract || \is_array($concrete) || $concrete instanceof \Closure;
     }

     /**
@@ -782,9 +718,9 @@
      * @throws \MacropaySolutions\Kernel\Contracts\Container\CircularDependencyException
      * @throws ReflectionException
      */
-    public function build(\Closure|string $concrete, array $parameters = []): mixed
+    public function build(array|string|\Closure $concrete, array $parameters = []): mixed
     {
-        if ($concrete instanceof Closure) {
+        if (\is_array($concrete) || $concrete instanceof \Closure) {
             return $concrete($this, $parameters); // fails at build time if invalid
         }

@@ -1071,7 +1007,11 @@
     public function offsetSet($offset, $value): void
     {
-        $this->bind($offset, $value instanceof Closure ? $value : static fn() => $value);
+        if (!\is_array($value) && !\is_string($value) && !$value instanceof Closure) {
+            $this->instance($offset, $value);
+
+            return;
+        }
+
+        $this->bind($offset, $value);
     }

Patch 2: framework/Application.php

Diff

--- framework/Application.php
+++ framework/Application.php
@@ -62,7 +62,25 @@
      * The container's bindings.
      *
      * @var array[]
      */
-    protected $bindings = [];
+    protected $bindings = [
+//        \MacropaySolutions\Kernel\Http\Request::class => [
+//            'concrete' => [Class::class, 'resolve']
+//            'shared' => false
+//        ],
+    ];

     /**
      * Create a new Framework application instance.
@@ -104,6 +122,4 @@
         static::setInstance($this);

-        $this->registerExplicitBindingsMap();@

         $this->instance('app', $this);

Patch 3: app/Application.php & New Factory Class

1. Create app/Factories/ContainerBindingsFactory.php

Create this file to hold static methods for custom complex resolutions:

<?php

namespace App\Factories;

use App\Exceptions\Handler;
use App\Console\Kernel;
use MacropaySolutions\CrufdWizard\Helpers\GeneralHelper;
use MacropaySolutions\CrufdWizard\Responses\DecoratableJsonResponse;
use MacropaySolutions\Kernel\Http\JsonResponse;

class ContainerBindingsFactory
{
    public static function createExceptionHandler(): Handler
    {
        return new Handler();
    }

    public static function createConsoleKernel($app): Kernel
    {
        return new Kernel($app);
    }

    public static function createJsonResponse($app, array $parameters): JsonResponse
    {
        if (
            false === ($parameters['json'] ?? $parameters[4] ?? false)
            && \in_array($code = (string)($parameters['status'] ?? $parameters[1] ?? '200'), ['200', '201', '202'], true)
            && \is_string(
                $decoratorFlag = ($request = $app['request'])->header(
                    GeneralHelper::JSON_RESPONSE_AS_ARRAY_FOR_DECORATION_IN_REQUEST_ATTRIBUTES
                )
            )
            && '' !== (string)($appKey = $app['config']->get('app.key'))
            && \hash_equals(
                $decoratorFlag,
                \hash_hmac('sha256', GeneralHelper::JSON_RESPONSE_AS_ARRAY, $appKey)
            )
        ) {
            if (\is_array($parameters['data'] ?? null)) {
                $request->attributes->set(GeneralHelper::JSON_RESPONSE_AS_ARRAY, $parameters['data']);

                return new DecoratableJsonResponse(
                    [],
                    $code,
                    $parameters['headers'] ?? [],
                    $parameters['options'] ?? JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES,
                    false
                );
            }

            if (\is_array($parameters[0] ?? null)) {
                $request->attributes->set(GeneralHelper::JSON_RESPONSE_AS_ARRAY, $parameters[0]);

                return new DecoratableJsonResponse(
                    [],
                    $code,
                    $parameters[2] ?? [],
                    $parameters[3] ?? JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES,
                    false
                );
            }
        }

        return new JsonResponse(
            $parameters['data'] ?? $parameters[0] ?? null,
            $parameters['status'] ?? $parameters[1] ?? 200,
            $parameters['headers'] ?? $parameters[2] ?? [],
            $parameters['options'] ?? $parameters[3] ?? JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES,
            $parameters['json'] ?? $parameters[4] ?? false,
        );
    }
}

2. Diff for app/Application.php

Diff

--- app/Application.php
+++ app/Application.php
@@ -28,6 +28,26 @@
     ];

+    /**
+     * Pre-compiled bindings array.
+     * Replaces registerExplicitBindingsMap(). Loaded directly into memory by OPcache.
+     *
+     * @var array
+     */
+    protected $bindings = [
+        \MacropaySolutions\Kernel\Contracts\Debug\ExceptionHandler::class => [
+            'concrete' => [\App\Factories\ContainerBindingsFactory::class, 'createExceptionHandler'],
+            'shared' => true,
+        ],
+        \MacropaySolutions\Kernel\Contracts\Console\Kernel::class => [
+            'concrete' => [\App\Factories\ContainerBindingsFactory::class, 'createConsoleKernel'],
+            'shared' => true,
+        ],
+        JsonResponse::class => [
+            'concrete' => [\App\Factories\ContainerBindingsFactory::class, 'createJsonResponse'],
+            'shared' => false,
+        ],
+    ];

     /**
      * The available container bindings and their respective load methods.
@@ -204,74 +224,6 @@
     }

-    /**
-     * Set all the container bindings that should be registered when the app is instantiated
-     * @see \MacropaySolutions\Kernel\Container\Container::getClosure for Closure format
-     * @see static::registerContainerAliases to handle alias changes if impacted by this function
-     * Must set array shape:
-     * [
-     *     "{$abstractString}" => [
-     *         'concrete' => \Closure,
-     *         'shared' => bool
-     *     ],
-     * ]
-     */
-    protected function registerExplicitBindingsMap(): void
-    {
-        $this->bindings = [
-//            \ParentFqn::class => [
-//                'concrete' => static function (
-//                     \MacropaySolutions\Kernel\Contracts\Container\Container $container,
-//                     array $parameters = []
-//                ): \MacropaySolutions\Kernel\Http\Request {
-//                    return $container->resolve(
-//                        \ChildFqn::class, // your child class
-//                        $parameters,
-//                        false
-//                    );
-//                },
-//                'shared' => false
-//            ],
-            \MacropaySolutions\Kernel\Contracts\Debug\ExceptionHandler::class => [
-                'concrete' => static fn(): \App\Exceptions\Handler => new \App\Exceptions\Handler(),
-                'shared' => true
-            ],
-            \MacropaySolutions\Kernel\Contracts\Console\Kernel::class => [
-                'concrete' => static fn($app): \App\Console\Kernel => new \App\Console\Kernel($app),
-                'shared' => true
-            ],
-            JsonResponse::class => [
-                'concrete' => static function ($app, $parameters): JsonResponse {
-                    // ... old inline closure logic ...
-                },
-                'shared' => false
-            ],
-        ];
-    }

     /**
      * Register the core container aliases.

Notice that ->resolve will not be available because is protected in container.

Closures would still work but will be slower even if defined static.

That is why caching the bindings is not an option.

Deferred Providers like the MailServiceProvider can bind things in their register even if they will not be registered when the app boots but only when they are required.

This reminds me. macro:cache must register ALL deferred providers before caching, just like config:cache'. Maybe autowiring:cache` also.

[macropay-solutions]

autowiring:cache had the deferred providers registered already.
3c23d8c
Added the registration to macro:cache also.

[marius-ciclistu]

Maybe the container would be better without Closures, with array callables.

[macropay-solutions]

https://packagist.org/packages/macropay-solutions/php-kernel#1.0.0-RC-119

Closures Eradicated 99% from Container.
+1% more RPS vs YIIi2
0.37/ 0.69 mb so -46% less memory usage vs Yii2.

This is without autowiring:cache. with it it sits at 2220 rpms and 0.38 MB on a HDD drive.

[macropay-solutions]

Released PHP-Framework v1.0.0-RC-27 with PHP-Kernel v 1.0.0-RC-122

The bench shows ~tie (with autowiring:cache) at RPS and 0.37 vs 0.69 MB vs Yii2 Basic

The container was cleaned of closures 99%.

[marius-ciclistu]

Kernel RC 123

[marius-ciclistu]

with HDD not SSD!

[macropay-solutions]

1.0.0-RC-125
Improvements and remove unused maintenance mode code

[marius-ciclistu]

1.0.0-RC-126 and framework rc 1.0.0-RC-28

[macropay-solutions]

https://packagist.org/packages/macropay-solutions/php-kernel-dev#1.0.0-RC-34

PHP storm IDE ctrl-click on things like

// getFiltered is ctrl+click-able and autocomplet-able
\app('request')->getFiltered('key');
\di('request')->getFiltered('key');
\app()->make('request')->getFiltered('key');

via composer plugin dump-autoload event.

$app['request'] is discouraged and offers no autocomplete