Using Databases in Hazaar

Hazaar provides a simple, consistent, and powerful database abstraction layer (DBI) built on top of PHP's PDO extension. This allows you to interact with a variety of database systems using a unified API, making your code portable and easy to maintain.

---

1. Configuring a Database Connection

Before you can use the database abstraction layer, you need to configure your database connection. Hazaar supports configuration via PHP, JSON, or INI files, as well as direct constructor arguments.

See the DBI Configuration documentation for full details.

PHP (Recommended)

<?php
return [
	'development' => [
		'type' => 'pgsql',
		'host' => 'localhost',
		'dbname' => 'my_database',
		'user' => 'my_user',
		'password' => 'my_password',
	],
	'test' => [
		'type' => 'sqlite',
		'file' => 'test.db',
	],
];

JSON

{
	"development": {
		"type": "pgsql",
		"host": "localhost",
		"dbname": "my_database",
		"user": "my_user",
		"password": "my_password"
	},
	"test": {
		"type": "sqlite",
		"file": "test.db"
	}
}

INI (Legacy)

[development]
type = "pgsql"
host = "localhost"
dbname = "my_database"
user = "my_user"
password = "my_password"

[test]
type = "sqlite"
file = "test.db"

Connecting in Code

$db = Hazaar\DBI\Adapter::create(); // Uses default config for current environment
$db = Hazaar\DBI\Adapter::create('test'); // Uses 'test' config
$db = Hazaar\DBI\Adapter::create([
	'type' => 'pgsql',
	'host' => 'localhost',
	'dbname' => 'test',
	'user' => 'test',
	'password' => 'test'
]); // Direct array config

---

2. Best Practices: Using Models and Controllers

Hazaar encourages separation of concerns by using Models for business logic and Controllers for handling HTTP requests. This makes your code more maintainable and testable.

See the CRUD documentation for more advanced usage.

Example: Product Model

Create a model to encapsulate all business logic related to products:

// app/models/Product.php
namespace App\Model;

use Hazaar\DBI\Adapter;

class Product
{
	protected Adapter $db;

	public function __construct(?Adapter $db = null)
	{
		$this->db = $db ?? Adapter::create();
	}

	public function getAll(): array
	{
		$result = $this->db->table('product')->find();
		return $result->fetchAll();
	}

	public function getById(int $id): ?array
	{
		return $this->db->table('product')->findOne(['id' => $id]);
	}

	public function update(int $id, array $data): bool
	{
		return $this->db->table('product')->update($data, ['id' => $id]);
	}
}

Example: Product Controller

Create a controller to handle GET and POST requests for products:

// app/controllers/Product.php
namespace App\Controller;

use Hazaar\Controller\Rest;
use App\Model\Product;

class Product extends Rest
{
	protected Product $model;

	public function __construct()
	{
		parent::__construct();
		$this->model = new Product();
	}

	/**
	 * @route("/product/{int:id}", methods={"GET"})
	 */
	public function get(int $id = null)
	{
		if ($id) {
			$product = $this->model->getById($id);
			return $product ? $product : ['error' => 'Product not found'];
		}
		return $this->model->getAll();
	}

	/**
	 * @route("/product/{int:id}", methods={"POST"})
	 */
	public function post(int $id)
	{
		$data = $this->request->getJSONBody();
		$success = $this->model->update($id, $data);
		return ['success' => $success];
	}
}

---

Example Usage

• GET /product: Returns all products
• GET /product/123: Returns product with ID 123
• POST /product/123: Updates product with ID 123 using POST data

---

---

3. PostgreSQL Replication Support

Hazaar DBI can automatically use a PostgreSQL read-only slave for queries and send writes to the master. This is configured using the db.master parameter in your config.

See DBI Configuration: PostgreSQL Replication for details.

---

4. More Features

• Hazaar DBI supports multiple database types (PostgreSQL, SQLite, MySQL, etc.)
• You can use transactions, schema management, and more advanced features.
• For full API details, see the Hazaar DBI API documentation.

---

Summary

Hazaar's database abstraction layer makes it easy to connect, query, and manage your databases with minimal configuration. For more advanced usage, see the linked documentation sections above.