Overview

DSQL is a dynamic SQL query builder. You can write multi-vendor queries in PHP profiting from better security, clean syntax and most importantly – sub-query support. With DSQL you stay in control of when queries are executed and what data is transmitted. DSQL is easily composable – build one query and use it as a part of other query.

Goals of DSQL

  • simple and concise syntax
  • consistently scalable (e.g. 5 levels of sub-queries, 10 with joins and 15 parameters? no problem)
  • “One Query” paradigm
  • support for PDO vendors as well as NoSQL databases (with query language similar to SQL)
  • small code footprint (over 50% less than competing frameworks)
  • free, licensed under MIT
  • no dependencies
  • follows design paradigms:

DSQL by example

The simplest way to explain DSQL is by example:

$query = new atk4\dsql\Query();
$query  ->table('employees')
        ->where('birth_date','1961-05-02')
        ->field('count(*)')
        ;
echo "Employees born on May 2, 1961: ".$query->getOne();

The above code will execute the following query:

select count(*) from `salary` where `birth_date` = :a
    :a = "1961-05-02"

DSQL can also execute queries with multiple sub-queries, joins, expressions grouping, ordering, unions as well as queries on result-set.

DSQL is Part of Agile Toolkit

DSQL is a stand-alone and lightweight library with no dependencies and can be used in any PHP project, big or small.

Agile Toolkit Stack

DSQL is also a part of Agile Toolkit framework and works best with Agile Models. Your project may benefit from a higher-level data abstraction layer, so be sure to look at the rest of the suite.

Requirements

  1. PHP 5.5 and above

Installation

The recommended way to install DSQL is with Composer. Composer is a dependency management tool for PHP that allows you to declare the dependencies your project has and it automatically installs them into your project.

# Install Composer
curl -sS https://getcomposer.org/installer | php
php composer.phar require atk4/dsql

You can specify DSQL as a project or module dependency in composer.json:

{
  "require": {
     "atk4/dsql": "*"
  }
}

After installing, you need to require Composer’s autoloader in your PHP file:

require 'vendor/autoload.php';

You can find out more on how to install Composer, configure auto-loading, and other best-practices for defining dependencies at getcomposer.org.

Getting Started

Continue reading Quickstart where you will learn about basics of DSQL and how to use it to it’s full potential.

Contributing

Guidelines

  1. DSQL utilizes PSR-1, PSR-2, PSR-4, and PSR-7.
  2. DSQL is meant to be lean and fast with very few dependencies. This means that not every feature request will be accepted.
  3. All pull requests must include unit tests to ensure the change works as expected and to prevent regressions.
  4. All pull requests must include relevant documentation or amend the existing documentation if necessary.

Review and Approval

  1. All code must be submitted through pull requests on GitHub
  2. Any of the project managers may Merge your pull request, but it must not be the same person who initiated the pull request.

Running the tests

In order to contribute, you’ll need to checkout the source from GitHub and install DSQL dependencies using Composer:

git clone https://github.com/atk4/dsql.git
cd dsql && curl -s http://getcomposer.org/installer | php && ./composer.phar install --dev

DSQL is unit tested with PHPUnit. Run the tests using the Makefile:

make tests

There are also vendor-specific test-scripts which will require you to set database. To run them:

# All unit tests including SQLite database engine tests
phpunit --config phpunit.xml

# MySQL database engine tests
phpunit --config phpunit-mysql.xml

Look inside these the .xml files for further information and connection details.

Reporting a security vulnerability

We want to ensure that DSQL is a secure library for everyone. If you’ve discovered a security vulnerability in DSQL, we appreciate your help in disclosing it to us in a responsible manner.

Publicly disclosing a vulnerability can put the entire community at risk. If you’ve discovered a security concern, please email us at security@agiletoolkit.org. We’ll work with you to make sure that we understand the scope of the issue, and that we fully address your concern. We consider correspondence sent to security@agiletoolkit.org our highest priority, and work to address any issues that arise as quickly as possible.

After a security vulnerability has been corrected, a security hot-fix release will be deployed as soon as possible.