feat(database): add option to get underlying query for property relation

[laylatichy]

pr to add option to have similar behavior to laravels author->books() to get underlying query for property relation we can chain into

// select with constraints
$author->query('books')->select()->whereField(field: 'title', value: 'Timeline Taxi')->all();
$author->query('books')->select()->limit(limit: 5)->all();

// count
$author->query('books')->count()->execute();

// update scoped to relation
$author->query('books')->update(title: 'Updated')->execute();

// delete scoped to relation
$author->query('books')->delete()->execute();

works with all relation types:

// HasMany / HasOne
$author->query('books')->select()->all();
$book->query('isbn')->select()->first();

// BelongsTo
$book->query('author')->select()->first();

// HasManyThrough / HasOneThrough
$tag->query('reviewers')->select()->all();
$tag->query('topReviewer')->select()->first();

// BelongsToMany
$tag->query('books')->select()->all();

now, I wasnt sure about naming it but opted in for query since it returns querybuilder same as query() helper just scoped to model property

[github-actions]

Benchmark Results

Comparison of feat-add-option-to-get-underlaying-query-for-property against 3.x (f527f4c1b96acac2a380c50a4daff11518c8dc5d).

Open to see the benchmark results

No benchmark changes above ±5%.

_{Generated by phpbench against commit 71ee424}

[brendt]

Can you add dedicated exceptions in Tempest\Database\Exceptions?

Our guidelines on exceptions are here: https://tempestphp.com/3.x/extra-topics/contributing#exception-classes

I did notice that we don't have any QueryBuilderException or DatabaseException interface yet, so you don't have to add these marker interfaces.

[laylatichy]

added 2 exceptions
packages/database/src/Exceptions/PrimaryKeyWasNotInitialized.php
packages/database/src/Exceptions/PropertyWasNotARelation.php

[laylatichy]

@brendt had to add #[RunTestsInSeparateProcesses] to rector tests as with my extra tests we went over 1GB mem threshold causing tests to OOM https://github.com/tempestphp/tempest-framework/actions/runs/24194408952/job/70620184698 Im not fully sure if that was the culprit as I was unable to replicate it on my local but mem analysis showed rector tests consuming around 200MB each

If you want i can move that commit into separate pr 71ee424

[brendt]

No it's fine to keep it here. I'll review later today :)