Releaser & uppdateringar

Den här releasen innehåller en större förbättring av ORM-lagrets relationer, eager loading
och constrained loading. Fokus har varit att göra relationerna mer konsekventa, mer
testbara och enklare att använda tillsammans med QueryBuilder.

Alla ändringar är verifierade med:

PHPUnit: grönt
PHPStan: grönt
GitHub Actions: grönt
Infection: 5360 / 5360 mutanter dödade
Mutation Code Coverage: 100%
Covered Code MSI: 100%
Nytt och förbättrat
Förbättrad relationsstatus på modeller
Modeller har nu bättre stöd för att hantera laddade relationer.

Nya/uppdaterade metoder:

$model->relationLoaded('relation');
$model->unsetRelation('relation');
$model->withoutRelations();
relationLoaded() använder intern relations-cache och kan skilja mellan:

relation saknas
och:

relation är laddad men värdet är null
Det är särskilt viktigt för one-relationer som hasOne, belongsTo och hasOneThrough.

Bättre dynamisk access till laddade relationer
Om en relation redan är laddad returnerar modellens dynamiska property-access nu den
laddade relationsdatan före relationsobjektet.

Exempel:

$user->load('posts');

$posts = $user->posts;
Relationens metod fungerar fortfarande som tidigare:

$relation = $user->posts();
Det innebär:

$user->posts() => relationsobjekt
$user->posts => laddad relationsdata, om relationen är laddad
Säkrare relation-validering
relationExists() har förbättrats så att interna modellmetoder inte längre räknas som relationer.

Exempel på metoder som inte ska accepteras som relationer:

save
delete
load
toArray
Det gör både load() och eager loading säkrare och mer konsekvent.

loadMissing() respekterar laddade null-relationer
loadMissing() laddar nu bara relationer som faktiskt saknas.

En relation som redan är laddad med värdet null betraktas som laddad och laddas inte om.

Query-stöd på relationer
Flera relationstyper har fått eller förbättrat stöd för query().

Relationer med query-stöd:

HasMany
HasOne
BelongsTo
BelongsToMany
HasManyThrough
HasOneThrough
Det gör att relationer kan användas mer konsekvent tillsammans med QueryBuilder.

Exempel:

$user->posts()
->query()
->where('published', '=', 1)
->orderBy('created_at', 'DESC')
->get();
Constrained relation loading
Model::load() hanterar nu QueryBuilder-typade closures mer konsekvent.

Exempel:

$user->load([
'posts' => function (QueryBuilder $query): void {
$query->where('published', '=', 1);
},
]);
För many-relationer sparas resultatet som en Collection.

$posts = $user->getRelation('posts');
För one-relationer sparas resultatet som en modell eller null.

$profile = $user->getRelation('profile');
Relation cardinality
Relationer kan nu ange om de representerar en eller flera modeller.

Nya metoder på relationer:

$relation->isOne();
$relation->isMany();
Exempel:

$user->profile()->isOne(); // true
$user->posts()->isMany(); // true
Det används internt för att avgöra om constrained loading ska använda:

$query->first();
eller:

$query->get();
Bättre eager loading
Eager loading använder nu samma relation-validering som modellens load().

Det betyder att relationer kontrolleras via modellens relationslogik i stället för enkel method_exists()-kontroll.

Exempel:

$users = User::with(['profile', 'posts'])->get();
Med constraints:

$users = User::with([
'posts' => function (QueryBuilder $query): void {
$query->where('published', '=', 1);
},
])->get();
Mindre reflection i Model::load()
Model::load() använder nu publika relation-getters där det går, och faller bara tillbaka till
reflection när det behövs för bakåtkompatibilitet.

Exempel på metadata som nu kan läsas via publikt API:

getForeignKey()
getLocalKeyName()
getRelatedModelClass()
getRelatedTable()
Det gör relationerna lättare att introspektera och minskar beroendet av privata properties.

Förbättrade relationer
HasMany
HasMany har fått:

query()
getLocalKeyName()
isMany()
isOne()
Exempel:

$posts = $user->posts()
->query()
->where('published', '=', 1)
->get();
Om parent saknar local key används en tom-resultat-query:

WHERE (1 = 0)
HasOne
HasOne har fått:

query()
getLocalKeyName()
isMany()
isOne()
Exempel:

$profile = $user->profile()
->query()
->where('active', '=', 1)
->first();
BelongsTo
BelongsTo har fått:

query()
isMany()
isOne()
Exempel:

$author = $post->user()
->query()
->where('active', '=', 1)
->first();
BelongsToMany
BelongsToMany::query() har förbättrats.

Förbättringar:

stabilare pivot-join via raw join
bättre hantering när parent saknar id
stöd för whereRaw('1 = 0') vid tomt resultat
fortsatt stöd för withPivot()
befintlig builder återanvänds när query() redan har byggts
Exempel:

$roles = $user->roles()
->query()
->where('roles.active', '=', 1)
->get();
Pivot-kolumner:

$roles = $user->roles()
->withPivot('created_by', 'created_at')
->query()
->get();
HasManyThrough
HasManyThrough har fått query-stöd.

Exempel:

$votes = $category->votes()
->query()
->where('points', '>', 0)
->get();
HasOneThrough
HasOneThrough har fått query-stöd.

Exempel:

$topVote = $category->topVote()
->query()
->where('points', '>', 0)
->first();
Bättre testtäckning
Den här releasen lägger till och förbättrar tester för:

relation state
relationLoaded()
unsetRelation()
withoutRelations()
relationExists()
Model::load()
loadMissing()
QueryBuilder-constraints
HasMany::query()
HasOne::query()
BelongsTo::query()
BelongsToMany::query()
HasManyThrough::query()
HasOneThrough::query()
relation cardinality
eager loading
pivot select
fallback via reflection
getQuery/query relation resolution
Mutation testing visar:

5360 mutations were generated
5360 mutants were killed by Test Framework
Mutation Code Coverage: 100%
Covered Code MSI: 100%
Bakåtkompatibilitet
Ändringarna är gjorda med bakåtkompatibilitet i åtanke.

Befintlig användning fungerar fortfarande:

$user->posts()->get();
$user->profile()->first();
$user->load('posts');
$user->loadMissing('profile');
Reflection-fallbacks finns kvar där äldre/custom relationer kan sakna nya publika getters.

Det finns dock ett mer korrekt beteende vid QueryBuilder-typade closures:

$user->load([
'profile' => function (QueryBuilder $query): void {
$query->where('active', '=', 1);
},
]);
One-relationer lagras nu som:

Model|null
Many-relationer lagras som:

Collection
Det är mer konsekvent med relationens cardinality.

Rekommenderad uppgradering
Efter uppdatering rekommenderas:

composer update
composer dump-autoload
Kör sedan projektets tester:

composer test
composer stan
Om appen har egna relationer bör du särskilt verifiera:

load()
loadMissing()
with()
withCount()
withSum()
belongsToMany()
withPivot()
Sammanfattning
Den här releasen gör ORM-relationer mer konsekventa, säkrare och bättre integrerade med
QueryBuilder.

Största förbättringarna är:

query-stöd på alla centrala relationstyper
bättre constrained loading
korrekt hantering av one/many-relationer
säkrare relation-validering
mindre reflection
starkare test- och mutationstäckning

Den här releasen fokuserar på att göra dokumentationen mer komplett, konsekvent och
bättre anpassad till nuvarande Radix App/Radix Framework-struktur.

Ändrat
Uppdaterat dokumentationen under docs/ med tydligare uppdelning mellan:

radix-app som starter-applikation
radix-framework som Composer-baserat framework
Förtydligat installation, CLI, scaffolds och rekommenderade startflöden.

Dokumenterat säkrare scaffold-flöden med:

--force-placeholders
--all
--dry-run
försiktigare användning av --force
Uppdaterat dokumentation för:

routing
controllers
middleware
HTTP
databas, migrations och seeders
ORM
validation
templates
frontend
images och uploads
files
services och dependency injection
events och listeners
cache
logging
mail
security
API
geolocation
testing
Uppdaterat README med mer komplett översikt över:

installation
CLI
scaffolds
frontend
public assets och uploads
utveckling/test
kort deployment-flöde
Uppdaterat CI-dokumentationen i github-settings/ så lokala kommandon fungerar bättre
när de körs direkt från markdown-filer i github-settings/.

Justerat Infection-kommandon till att använda:

composer infect:pcov
composer infect:xdebug
Undviker nu det generella composer infect i CI-dokumentationen eftersom projektets
wrapper kräver explicit mode.

Lagt till exempel med:

composer -d ..
npm --prefix ..
så kommandon fungerar även när terminalen står i github-settings/.

Varför
Målet är att dokumentationen ska vara lättare att följa för nya projekt, tydligare vid
scaffold-installation och mer korrekt i förhållande till hur Radix App faktiskt används
tillsammans med Radix Framework.

Dokumentationen skiljer nu tydligare mellan appens ansvar och frameworkets ansvar, vilket
gör det enklare att förstå vad som ska ändras i appen och vad som kommer från
Composer-paketet.

Rekommenderat efter uppdatering
Kör gärna grundkontrollerna:

composer format:check
composer stan
composer test
Vid behov, kör mutation testing med explicit driver:

composer infect:pcov
eller:

composer infect:xdebug

Stabiliserat sidhuvudet på mobila enheter genom att använda fast positionerad header med
konsekvent höjd.
Minskat visuella hopp och korta vita flashar vid mobil paginering, sidledsswipe och navigering.
Infört gemensam headerhöjd via --header-h för mer konsekvent layout mellan olika vyer.
Justerat innehållets toppavstånd så det anpassas efter den fasta headern.
Förbättrat vertikal centrering av navigation och headerinnehåll.
Lagt till renderingstabilisering för fixed/sticky-liknande element på mobila webbläsare.
Minskat horisontell overscroll för att undvika oönskade visuella effekter vid touchinteraktion.
Förbättrat sidebar-layoutens anpassning till den fasta headern där sidebar används.

Uppdaterar javascript pagination till att använda radix-framework klasserna.
Uppdaterat färgschemat för search-profiles.

Åtgärdat mobilproblem där sidan kunde hoppa/blinka vid klick på pagination.
Förbättrat horisontell scrollhantering och touch-beteende i paginationen.

Denna release uppdaterar Radix App med standardkonfiguration för den nya säkerhetsheadern
Cross-Origin-Resource-Policy som stöds av Radix Frameworks SecurityHeaders middleware.

Syftet är att ge nya Radix-projekt en säkrare grundkonfiguration direkt från start och göra
det enklare att kontrollera hur resurser från applikationen får användas av andra origins.

Ny miljövariabel

Radix App innehåller nu följande rekommenderade standard i .env.example:

SECURITY_CORP=same-origin

Tillåtna värden är:

same-origin
same-site
cross-origin
off

Rekommenderad standard för vanliga installationer är:

SECURITY_CORP=same-origin

Det passar när webb, API och statiska resurser ligger på samma origin, exempelvis:

https://example.com
https://example.com/api/v1/...
https://example.com/assets/...

Konfiguration

Radix App läser nu in SECURITY_CORP via appens säkerhetskonfiguration och skickar värdet
vidare till frameworkets SecurityHeaders middleware.

Om variabeln lämnas tom eller sätts till off sätts ingen Cross-Origin-Resource-Policy-header
av frameworkets middleware.

Apache och statiska filer

För Apache-installationer har public/.htaccess uppdaterats så att statiska resurser kan få
motsvarande header även när de serveras direkt av webbservern.

Det innebär att resurser som JavaScript, CSS, bilder, fonter och manifest kan omfattas av
samma skydd även utan att requesten passerar PHP-applikationen.

Standardvärdet i appens Apache-konfiguration är:

Cross-Origin-Resource-Policy: same-origin

Tester

Testerna för SecurityHeaders middleware har uppdaterats för att stödja den nya
SECURITY_CORP-konfigurationen.

Testsviten verifierar nu både att Cross-Origin-Resource-Policy-headern sätts när
SECURITY_CORP är konfigurerad och att headern inte sätts när värdet saknas eller inte är aktiverat.

Det säkerställer att den nya funktionen fungerar utan att bryta befintligt beteende för CSP,
HSTS och övriga säkerhetsheaders.

När ska andra värden användas?

Använd same-site om applikationen är uppdelad över flera subdomäner inom samma site,
till exempel:

https://app.example.com
https://api.example.com
https://static.example.com

Använd cross-origin endast om resurser från applikationen behöver kunna användas av
externa domäner.

Använd off om headern inte ska sättas av Radix Frameworks SecurityHeaders middleware.

Bakåtkompatibilitet

Ändringen är bakåtkompatibel för befintliga applikationer.

Projekt som redan har en egen .env påverkas inte automatiskt förrän SECURITY_CORP läggs
till eller konfigureras. Nya projekt som skapas från denna starter får däremot en
rekommenderad säker standard direkt via .env.example.

Rekommendation

För de flesta Radix App-installationer rekommenderas:

SECURITY_CORP=same-origin

Om applikationen använder CDN, externa bilddomäner, inbäddade resurser eller flera
subdomäner bör värdet ses över utifrån den faktiska deploymentsituationen.

Liten fix i middleware SecurityHeaders tagit tagit bort dublicerade setHeaders.

Denna release lägger till stöd för att konfigurera HTTP-headern Cross-Origin-Resource-Policy
via Radix SecurityHeaders middleware.

Headern kan användas för att styra hur resurser från applikationen får användas av andra
origins, och ger ett extra skyddslager mot oönskad cross-origin-användning av resurser.

Ny valfri miljövariabel: SECURITY_CORP=same-origin

Tillåtna värden:

same-origin
same-site
cross-origin
off

Rekommenderad standard för vanliga installationer är same-origin.

Det passar när webb, API och statiska resurser ligger på samma origin, exempelvis:

https://example.com
https://example.com/api/v1/...
https://example.com/assets/...

Använd same-site om applikationen är uppdelad på flera subdomäner inom samma site,
exempelvis:

https://app.example.com
https://api.example.com
https://static.example.com

Använd cross-origin endast om resurser från applikationen behöver kunna användas av
externa domäner.

Använd off om headern inte ska sättas av frameworkets SecurityHeaders middleware.

Ändringen är bakåtkompatibel. Befintliga applikationer som saknar SECURITY_CORP
påverkas inte automatiskt. Headern sätts endast när värdet är konfigurerat.

EnvValidator har uppdaterats för att validera SECURITY_CORP när variabeln är satt.
Ogiltiga värden stoppas tidigt med ett tydligt konfigurationsfel.

Testsviten har utökats för att säkerställa att SECURITY_CORP=same-origin accepteras, att
ogiltiga värden nekas och att befintlig bakåtkompatibilitet bibehålls.

För de flesta projekt rekommenderas:

SECURITY_CORP=same-origin

Om Apache eller annan webbserver används för att servera statiska filer direkt kan
motsvarande header även sättas på webbservernivå för att även omfatta exempelvis
JavaScript, CSS, bilder och fonter.

Updatering av js tooltip för att fungera inuti tables.

Uppdatering av devDependencies i package.json.