Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
209 lines (152 loc) · 4.75 KB

DEVELOPMENT.md

File metadata and controls

209 lines (152 loc) · 4.75 KB
Raw

Development Guide

Purpose

This document is for developers who want to:

  • work on this package locally
  • use this package inside another Laravel app before publishing to Packagist
  • run tests, formatting, and static analysis
  • contribute features or fixes safely

Local Development Setup

Clone the package:

git clone git@github.com:ghostcompiler/laravel-querybuilder.git laravel-querybuilder
cd laravel-querybuilder

Install dependencies:

composer update

Quality tooling currently targets PHP 8.2+ because the latest Larastan release requires it. The package itself still supports PHP 8.1+ at runtime.

Use the Package in Another Laravel Project

If you want to pull this package directly into a Laravel app from your local machine, add a path repository to the consuming app's composer.json:

{
    "repositories": [
        {
            "type": "path",
            "url": "/absolute/path/to/laravel-querybuilder"
        }
    ],
    "require": {
        "ghostcompiler/laravel-querybuilder": "*"
    }
}

Then install or refresh it:

composer update ghostcompiler/laravel-querybuilder

If you want Composer to symlink instead of mirroring the package, you can use:

{
    "repositories": [
        {
            "type": "path",
            "url": "/absolute/path/to/laravel-querybuilder",
            "options": {
                "symlink": true
            }
        }
    ]
}

When you change package classes or move internals during local development, it is also a good idea to refresh autoload metadata in the consuming app:

composer dump-autoload

Security Notes

This package is designed to safely transform request input into Eloquent query constraints, but contributors should treat it as a boundary-sensitive library.

Keep these rules in mind when changing behavior:

  • start from a safe base query in consuming apps
  • do not rely on this package to create tenant scoping or authorization automatically
  • keep request-driven filters, sorts, includes, and selected columns deny-by-default unless explicitly allow-listed
  • keep soft-delete behavior behind the trashed command instead of request-driven deleted_at filters
  • keep relation-depth limits in place for request-driven dotted relation paths
  • avoid introducing raw SQL paths that accept user-controlled identifiers or expressions

Safe consuming-app pattern:

$request->user()
    ->videos()
    ->queryBuilder($request)
    ->paginateTable();

Less safe multi-tenant pattern:

Video::queryBuilder($request)->paginateTable();

If you add new request-driven behavior, make sure it is:

  1. validated before query application
  2. covered by explicit allow-lists where applicable
  3. tested in both normal mode and strict mode
  4. documented in README.md

If the new behavior affects performance-sensitive query shapes, also consider:

  • pagination caps
  • relation depth
  • list-size caps for in style filters
  • whether the exposed fields should be indexed in production databases

Package Scripts

Validate the package manifest:

composer analyse

Run the test suite:

composer test

Run static analysis:

composer stan

Check formatting:

composer lint

Auto-format:

composer format

Run the full local quality suite:

composer quality

Test Coverage Notes

The package test suite uses Orchestra Testbench with an in-memory SQLite database.

Current fixture coverage includes:

  • model search
  • nested relation search
  • morph relation search
  • scalar filters
  • relation filters
  • morph relation filters
  • relation sorting
  • morph relation eager loading
  • selective columns
  • soft deletes
  • date ranges
  • API-style pagination payloads
  • custom filter callbacks
  • strict mode validation

Optional PostgreSQL Runs

The local test harness can also use PostgreSQL when these environment variables are provided:

TEST_DB_CONNECTION=pgsql
TEST_DB_HOST=127.0.0.1
TEST_DB_PORT=5432
TEST_DB_DATABASE=laravel_querybuilder_test
TEST_DB_USERNAME=postgres
TEST_DB_PASSWORD=secret
composer test

This is useful for verifying PostgreSQL-specific behavior such as boolean casting, alias-heavy queries, and subquery sorting. The database itself must already exist and be reachable from your machine.

Adding New Features

When adding a new query option:

  1. Add the behavior in src/Support/QueryBuilderEngine.php.
  2. Add model-facing configuration if needed.
  3. Add or extend tests in tests/QueryBuilderTest.php.
  4. Update README.md.
  5. Run composer quality.

Publishing Notes

Before tagging a release:

  1. Update README.md if the API changed.
  2. Run composer quality.
  3. Check GitHub Actions for tests, quality, and security.
  4. Tag the release with semantic versioning.