Home

The aim of DatabaseFactory is to give PHP application developers a dependency-free means to securely and efficiently interact with, manage and manipulate their databases with a simple, and intuitive API. Further documentation, including a deeper look into the API can be found here.

Project Goals

• Security:
  • DatabaseFactory is highly opinionated in one main area; security. It's built on top of the native PHP library; PDO. It uses prepared statements to ensure that your database transactions are protected and secure.
• Efficiency
  • Using PDO at its core, DatabaseFactory aims to be as efficient as possible, where possible. This is done by issuing statements and executing queries only when needed.
• Accessibility
  • DatabaseFactory aims to provide a simple API that works across a range of different database drivers. Using the Query Builder or the ORM (or both in conjunction with one another), you can interact with your databases with ease.
• Modularity
  • This library is intended to be manipulated and extended with very little effort. Customizing DatabaseFactory is extremely simple and gives developers full control over the API.
• Documentation
  • DatabaseFactory aims to be well documented. The main repository contains a Wiki section, which contains the libraries corresponding documentation files in markdown format.

Requirements

• PHP >=8.2
  • This package uses explicit false return types [read more] and readonly classes [read more]
• PDO Extension

Library Features

• Object Relational Mapper (ORM)
• Intuitive query builder
• Entity based system

Getting Started

Installation

The first thing you'll need to do, is ensure that you have DatabaseFactory properly installed. Since DatabaseFactory requires PRS-4 to allow for proper class autoloading, composer will need to be installed on your computer. Composer is free, and easy to install for virtually every environment.

Now you could download the zip file and add the \DatabaseFactory namespace to your own PSR-4 autoloader, if you don't have access to composer. Please take note, that if this is the installation path you take, then you will be denying yourself access to important updates, and you risk missing out on new features.

$ composer require database-factory/framework

Configure

• Developer's Note: If you're installing this into a project that has already established a PDO connection then you can forego the initialization and configuration processes, and you can move onto the TLDR section below to start interacting with your data.

When configuring DatabaseFactory, it's important to understand how it connects to a database. If you're looking to use this library for a database that differs from the default MySQL, then I advise you to review this section of the wiki before proceeding. Here is an example .env configuration for a MySQL based setup.

DB_HOSTNAME=127.0.0.1
DB_DATABASE=database_name
DB_USERNAME=root
DB_PASSWORD=password
DB_DRIVER=mysql

Initialize

DatabaseFactory is extremely easy to set up. Ultimately, it can be instantiated with just one line of code, assuming you have your ENV library already configured in some way. If you do not, then two lines of code can get you up and running in not time flat.

# first, we load the ENV configuration variables. This step is optional if
# you've already setup an ENV library for use within your project and have
# your env variables configured. 
DatabaseFactory\Facades\Env::init(__DIR__); // the absolute path of the .env file

# next, we establish a new connection
DatabaseFactory\Facades\DB::connect();

That's it! Now, all we need to do, is use DatabaseFactory within our application.

TLDR

The TLDR of the entire wiki boils down to this; There are three main components of DatabaseFactory - the query builder, the ORM and the Entity system. Let's take a shallow dive into how to use and utilize each of these components.

Using the query builder

DatabaseFactory provides an amazingly simple, robust and intuitive Query Builder API that grants us the ability to easily work with our database tables. In order to utilize it, we need to call the table() method and pass through the database table we want to work with. To see how to customize how your query builder instance executes queries, go here.

# initiate the query builder using the facade system
$users = DatabaseFactory\Facades\DB::table('users');

# OR

# initiate the query builder using the helper function
$users = db_factory('users');

# generate the query
$users->select('name, email');

# the SQL to be executed
SELECT name, email FROM users

# generate the query
$users->select('name, email')->where('name', '=', 'Mark')->orderBy('name', 'DESC')->limit(10);

# the SQL to be executed
SELECT name, email FROM users WHERE name = 'Mark' ORDER BY name DESC LIMIT 10

Using the ORM

DatabaseFactory also provides an intuitive ORM (Object Relational Mapper) to work with data which uses an entity class to model that data (see here). The ORM has many shortcut methods which give us the ability to generate even the most robust queries with minimal code.

Selecting all columns [default behavior]

# generate the query
User::where('name', '<>', '');

# the SQL to be executed
SELECT * FROM users WHERE name <> ''

Selecting other columns by passing them as a string via the final argument (optional)

# generate the query
User::where('name', '<>', '', 'email, name');

# the SQL to be executed
SELECT email, name FROM users WHERE users.name <> ''

Using them together

Naturally, you can use the ORM and Query Builder in conjunction with one another to build complex queries. See the advanced usage section, for more concrete examples.

Selecting all columns [default behavior]

# generate the query
User::whereNot('name', '')->limit(5)->offset(5);

# the SQL to be executed
SELECT * FROM users WHERE name <> '' LIMIT 5 OFFSET 5

Selecting other columns by passing them as a string via the final argument (optional)

# generate the query
User::whereNot('name', '', 'email, name')->limit(5)->offset(5);

# the SQL to be executed
SELECT email, name FROM users WHERE name <> '' LIMIT 5 OFFSET 5

Using entities

Once we've built a collection of data, we can use the entity system to access that data. This is done by accessing the properties of the entity object. For more information on how DatabaseFactory utilizes the entity approach to modeling data, go here.

Collecting all records within a table

# generate a collection of all records
$users = User::all();

# the SQL to be executed
SELECT * FROM users

# loop through each entity object
foreach($users as $user) {
  # output the value of the 'name' property from that object
  echo $user->name;
}

Collecting one record based on its ID

# generate a collection of one record based 
# on its ID
$user = User::find(15);

# the SQL to be executed
SELECT * FROM users WHERE id = '15'

# output the value of the 'name' property from that object
echo $user->name