Upgrade Guide

From version 9.x to 10.x

PHP version `8.4` required

You need PHP v8.4 or higher to run Athenaeum packages.

Note: PHP v8.5 is supported!

Laravel `v13.x`

Please read Laravel's upgrade guide, before continuing here.

Several components and methods concerning audit trail formatting have been deprecated. Formatting of audit trail entries has been extracted into their own Formatter classes. While the previous formatting logic is still supported in the current version (v10.x), it is highly recommended that you refactor.

❌ previously

namespace Acme\Models;

use Aedart\Audit\Concerns\ChangeRecording;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use ChangeRecording;
    
    public function formatOriginalData(array|null $filtered, string $type): array|null
    {
        // ...formatting not shown here...
        return $filtered;
    }
    
    public function formatChangedData(array|null $filtered, string $type): array|null
    {
        // ...formatting not shown here...
        return $filtered;
    }
}

✔️ Now

namespace Acme\Models;

use Aedart\Contracts\Audit\Formatter;
use Aedart\Audit\Concerns\ChangeRecording;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use ChangeRecording;
    
    public function auditTrailRecordFormatter(): string|Formatter|null
    {
        // Formatting of audit trail entry moved into custom "formatter"... 
        return UserAuditTrailFormatter::class;
    }
}

Please review the Audit Trail Formatting documentation for additional information.

Field Criteria Logical Operators

The logical operator constants (FieldCriteria::AND and FieldCriteria::OR) have been deprecated and replaced by a new LogicalOperator enum. If you have custom query filters that inherit from FieldCriteria, then you must change your comparison of the logical operator.

❌ previously

use Aedart\Database\Query\FieldFilter;
use Aedart\Contracts\Database\Query\FieldCriteria;
use Illuminate\Contracts\Database\Eloquent\Builder as EloquentBuilder;
use Illuminate\Contracts\Database\Query\Builder;

class StringFilter extends FieldFilter
{
    public function apply(Builder|EloquentBuilder $query)
    {
        if ($this->logical() === FieldCriteria::OR) {
            return $query->orWhere(
                $this->field(),
                $this->operator(),
                $this->value()
            );
        }

        return $query->where(
            $this->field(),
            $this->operator(),
            $this->value()
        );
    }
}

✔️ Now

use Aedart\Database\Query\FieldFilter;
use Aedart\Contracts\Database\Query\Operators\LogicalOperator
use Illuminate\Contracts\Database\Eloquent\Builder as EloquentBuilder;
use Illuminate\Contracts\Database\Query\Builder;

class StringFilter extends FieldFilter
{
    public function apply(Builder|EloquentBuilder $query)
    {
        if ($this->logical() === LogicalOperator::OR) {
            return $query->orWhere(
                $this->field(),
                $this->operator(),
                $this->value()
            );
        }

        return $query->where(
            $this->field(),
            $this->operator(),
            $this->value()
        );
    }
}

You can also use the buildFor() utility method, instead of performing manual comparison of the logical operator.

use Aedart\Database\Query\FieldFilter;
use Illuminate\Contracts\Database\Eloquent\Builder as EloquentBuilder;
use Illuminate\Contracts\Database\Query\Builder;

class StringFilter extends FieldFilter
{
    public function apply(Builder|EloquentBuilder $query)
    {
        return $this->buildFor(
            and: fn () => $query->where(
                    $this->field(),
                    $this->operator(),
                    $this->value()
                ),
            or: fn () => $query->orWhere(
                    $this->field(),
                    $this->operator(),
                    $this->value()
                ), 
        );
    }
}

`Paths` Container now inherits from `ArrayDto`

The Paths container now inherits from ArrayDto. It no longer depends on the deprecated / removed "Aware-of" components. All mutator methods (setters) have been removed. If you wish to manually set a directory path, you must do so by setting the property's value directly

❌ previously

use Aedart\Core\Helpers\Paths;

$paths = new Paths();
$paths->setConfigPath(getcwd() . DIRECTORY_SEPARATOR . 'environments');

✔️ Now

use Aedart\Core\Helpers\Paths;

$paths = new Paths();
$paths->configPath = getcwd() . DIRECTORY_SEPARATOR . 'environments';

File Stream Locks

The LockTypes (interface) has been replaced with a new LockType enum.

❌ previously

use Aedart\Contracts\Streams\Locks\LockTypes;

✔️ Now

use Aedart\Contracts\Streams\Locks\LockType;

Your file stream "transactions" configuration, in config/streams.php, SHOULD be modified to use the LockType enum.

return [

    // ...previous not shown...

    'transactions' => [

        'default' => [
            'driver' => \Aedart\Streams\Transactions\Drivers\CopyWriteReplaceDriver::class,
            'options' => [
                'maxMemory' => 5 * \Aedart\Contracts\Streams\BufferSizes::BUFFER_1MB,
                'lock' => [
                    'enabled' => true,
                    'profile' => env('STREAM_LOCK', 'default'),

                    // Use LockType enum value here...
                    'type' => \Aedart\Contracts\Streams\Locks\LockType::EXCLUSIVE,

                    'timeout' => 0.5,
                ],
                
                // ...remaining not shown ...
            ]
        ]
    ]
];

Http Client Debugging and Logging

The Http Message Types (interface) has been replaced with a new Type enum. This affects all custom debugging and logging callbacks, in the Http Client. Previously a string value from the constants defined in the Types interface was used. Now, the Type enum case is passed on to the callbacks. Affected methods are:

log()
debug()
dd()

❌ previously

use Aedart\Contracts\Http\Messages\Type;
use Aedart\Contracts\Http\Clients\Requests\Builder;
use Psr\Http\Message\MessageInterface;

$response = $client
        ->where('date', 'today')
        ->debug(function(string $type, MessageInterface $message, Builder $builder) {
            if ($type === 'request') {
                // debug a request...
            } else {
                // debug response...
            }       
        })
        ->get('/weather');

✔️ Now

use Aedart\Contracts\Http\Messages\Type;
use Aedart\Contracts\Http\Clients\Requests\Builder;
use Psr\Http\Message\MessageInterface;

$response = $client
        ->where('date', 'today')
        ->debug(function(Type $type, MessageInterface $message, Builder $builder) {
            if ($type === Type::REQUEST) {
                // debug a request...
            } else {
                // debug response...
            }       
        })
        ->get('/weather');

Set-Cookies SameSite

The predefined SameSite constants in SetCookie have been deprecated. Use the SameSite enum cases instead. The sameSite() and getSameSite() methods are affected.

❌ previously

use Aedart\Http\Cookies\SetCookie;

$cookie = new SetCookie()->sameSite('lax');

$policy = $cookie->getSameSite() // string 'lax'

✔️ Now

use Aedart\Contracts\Http\Cookies\SameSite;
use Aedart\Http\Cookies\SetCookie;

$cookie = new SetCookie()->sameSite('lax'); 

$policy = $cookie->getSameSite() // SameSite::LAX enum case

The sameSite() also accepts an enum case.

use Aedart\Contracts\Http\Cookies\SameSite;
use Aedart\Http\Cookies\SetCookie;

$cookie = new SetCookie()->sameSite(SameSite::STRICT); 

$policy = $cookie->getSameSite() // SameSite::STRICT enum case

Secure Flag

If you set SameSite::NONE as the same-site value, then the secure flag is automatically set to true;

❌ previously

use Aedart\Http\Cookies\SetCookie;

$cookie = new SetCookie()
    ->secure(false)
    ->sameSite('none'); 

$secure = $cookie->isSecure() // false

✔️ Now

use Aedart\Http\Cookies\SetCookie;

$cookie = new SetCookie()
    ->secure(false)
    ->sameSite('none'); 

$secure = $cookie->isSecure() // true

Circuit Breaker State Identifiers

The state identifiers (constants) defined in \Aedart\Contracts\Circuits\CircuitBreaker have been deprecated. A new Identifier enum has replaced them. Consequently, the id() method of circuit breaker's State now returns an enum case. Unless you have logic that directly depends on the circuit breaker's state identifier, then this change should not affect your.

❌ previously

use Aedart\Contracts\Circuits\CircuitBreaker;

/** @var CircuitBreaker $circuitBreaker */
$id = $circuitBreaker->state()->id();

echo gettype($id); // integer
var_export($id === CircuitBreaker::CLOSED); // true

✔️ Now

use Aedart\Contracts\Circuits\States\Identifier;
use Aedart\Contracts\Circuits\CircuitBreaker;

/** @var CircuitBreaker $circuitBreaker */
$id = $circuitBreaker->state()->id();

echo gettype($id); // object
var_export($id === Identifier::CLOSED); // true

DTO

With the addition of property hooks, in PHP v8.4, the Dto abstraction has become somewhat irrelevant. It has therefore been deprecated and will no longer be supported in future versions. You are encourgaed to the ArrayDto abstraction instead, or create DTOs usign PHP native property hooks instead.

❌ previously

use Aedart\Dto\Dto;

class Person extends Dto
{
    protected string|null $name = '';
    protected int|null $age = 0;
}

✔️ Now

use Aedart\Dto\ArrayDto;

class Person extends ArrayDto
{
    protected array $allowed = [
        'name' => 'string|null',
        'age' => 'int|null'
    ];
}

See package documentation for additional examples.

Upgrade Guide

From version 9.x to 10.x

PHP version `8.4` required

Laravel `v13.x`

Audit Trail

Field Criteria Logical Operators

`Paths` Container now inherits from `ArrayDto`

File Stream Locks

Http Client Debugging and Logging

Set-Cookies SameSite

Secure Flag

Circuit Breaker State Identifiers

DTO

Removed "Aware-of" Components

Other Deprecated Components

Onward