README

JQL Builder is a supercharged PHP package that allows you to create Jira Query Language (JQL) queries programmatically.

Requirements

• PHP ^8.0

Installation

Install the package via Composer:

composer require bbs-lab/jql-builder

Usage

Basic example

use JqlBuilder\Jql;
 
$query = new Jql();
 
$query->where('project', 'PROJECT')
      ->where('summary', '~', 'title');
 
echo $query; // project = "PROJECT" and summary ~ "title"

where()

Add a condition to the query. The default operator is =.

$query = new Jql();
 
// Using default operator (=)
$query->where('project', 'MY PROJECT');
// project = "MY PROJECT"
 
// Using a specific operator
$query->where('summary', '~', 'some text');
// summary ~ "some text"
 
// Using an array of values (IN operator)
$query->where('status', ['New', 'In Progress', 'Done']);
// status in ("New", "In Progress", "Done")

orWhere()

Add an OR condition to the query. Accepts the same arguments as where().

$query = new Jql();
 
$query->where('project', 'MY PROJECT')
      ->orWhere('summary', '~', 'sub-issue for "TES-xxx"');
// project = "MY PROJECT" or summary ~ "sub-issue for \"TES-xxx\""

orderBy()

Sort the results by a given field and direction (asc or desc).

$query = new Jql();
 
$query->where('project', 'MY PROJECT')
      ->orderBy('created', 'asc');
// project = "MY PROJECT" order by created asc

when()

Conditionally add a clause to the query. The closure is only executed when the first argument evaluates to true.

$query = new Jql();
 
$onlyOpen = true;
 
$query->where('project', 'MY PROJECT')
      ->when($onlyOpen, function (Jql $builder) {
          $builder->where('status', 'Open');
      });
// project = "MY PROJECT" and status = "Open"

macro()

Register a custom macro to extend the builder with your own reusable logic, powered by spatie/macroable.

use JqlBuilder\Jql;
 
Jql::macro('forProject', function (string $project) {
    /** @var Jql $this */
    return $this->where('project', $project);
});
 
$query = new Jql();
 
$query->forProject('MY PROJECT')
      ->where('status', 'Open')
      ->getQuery();
// project = "MY PROJECT" and status = "Open"

getQuery()

Return the final JQL query string.

$query = new Jql();
 
$result = $query->where('project', 'MY PROJECT')
                ->where('status', ['New', 'Done'])
                ->orWhere('summary', '~', 'sub-issue for "TES-xxx"')
                ->orderBy('created', 'asc')
                ->getQuery();
 
echo $result;
// project = "MY PROJECT" and status in ("New", "Done") or summary ~ "sub-issue for \"TES-xxx\"" order by created asc

Laravel Integration

The package includes a Laravel service provider and facade for seamless integration.

Facade

use JqlBuilder\Facades\Jql;
 
$query = Jql::where('project', 'MY PROJECT')
            ->where('status', 'Open')
            ->getQuery();

The service provider is auto-discovered via Laravel's package auto-discovery.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

License

The MIT License (MIT). Please see License File for more information.