testmonitor/eloquent-calculated-columns

A Laravel package for adding calculated columns to Eloquent models using SQL for more performant queries.

dev-main 2024-10-07 07:50 UTC

Requires

• php: ^8.2
• illuminate/config: ^11.0
• illuminate/database: ^11.0
• illuminate/support: ^11.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.7
• orchestra/testbench: ^9.0
• phpunit/phpunit: ^11.0
• squizlabs/php_codesniffer: ^3.6

MIT

• Thijs Kok
• Stephan Grootveld
• Frank Keulen

• model
• laravel
• eloquent
• testmonitor
• calculated columns

README

A Laravel package for adding calculated columns when retrieving data from an Eloquent model. This package allows you to define these columns using SQL, resulting in more performant queries compared to accessors.

It is heavily inspired by Spatie's Query Builder and can be used in conjunction with this package.

Table of Contents

• Installation
• Usage
• Examples
• Tests
• Changelog
• Contributing
• Credits
• License

Installation

This package can be installed through Composer:

$ composer require testmonitor/eloquent-calculated-columns

Next, publish the configuration file:

$ php artisan vendor:publish --tag=eloquent-calculated-columns

The configuration file allows you the change the HTTP parameter name, when desired.

Usage

To use calculated columns, you need to:

1. Use the trait TestMonitor\CalculatedColumns\HasCalculatedColumns in your model.
2. Define the available calculated in your model.

Add the CalculatedColumns trait to the models where you want to add calculated columns:

use Illuminate\Database\Query\Builder;
use Illuminate\Database\Eloquent\Model;
use TestMonitor\CalculatedColumns\HasCalculatedColumns;

class User extends Model
{
    use HasCalculatedColumns;

    public function calculatedColumns(): array
    {
        return [
            'total_price' => function (Builder $query) {
                $query->select(DB::raw("SUM(order_items.price) AS total_price"))
                    ->from('order_items')
                    ->whereColumn('order_items.order_id', 'orders.id');
            },
        ];
    }
}

Next, use the calculated columns in your queries:

use App\Models\Order;

$orders = Order::query()
    ->withCalculatedColumns()
    ->get();
}

In this example, the total_price column calculates the total price of an order by adding all the order item prices.

The requested columns are automatically derived from the HTTP request. You can modify the HTTP query parameter in the configuration file. By default, the name calculate is used.

Examples

Tests

The package contains integration tests. You can run them using PHPUnit.

$ vendor/bin/phpunit

Changelog

Refer to CHANGELOG for more information.

Contributing

Refer to CONTRIBUTING for contributing details.

Credits

• Thijs Kok
• Stephan Grootveld
• Frank Keulen
• All Contributors

License

The MIT License (MIT). Refer to the License for more information.