Brif

Pengenalan

Ngorei Brif adalah library PHP yang powerful untuk membangun dan mengelola query database dengan cara yang aman dan efisien. Library ini menyediakan interface yang mudah digunakan untuk operasi database umum seperti SELECT, INSERT, UPDATE, dan DELETE.

Instalasi

Untuk menggunakan NgoreiBuilder, Anda perlu:

use app\Ngorei;
$Tds = new Ngorei();

Konfigurasi Dasar

Konfigurasi koneksi database di file .env:

DB_HOST=localhost
DB_NAME=exsampel
DB_USER=root
DB_PASS=12345678
DB_PORT=3306
DB_CHARSET=utf8mb4

Cara Penggunaan

4.1 Inisialisasi Builder

$query = $Tds->Network->Brief('users');

4.2 Query Dasar

Select Dasar


// SELECT Query
$users = $Tds->Network->Brief('users')
    ->select('id, name, email')
    ->get();

Insert Dasar


// INSERT Query
$data = ['name' => 'John', 'email' => 'john@example.com'];
$Tds->Network->Brief('users')->insert($data);

Update Dasar


// UPDATE Query
$Tds->Network->Brief('users')
    ->where('id', 1)
    ->update(['name' => 'John Doe']);

Delete Dasar


// DELETE Query
$Tds->Network->Brief('users')
    ->where('id', 1)
    ->delete();

4.3 Klausa WHERE

Where Dasar


// Where dasar
->where('column', 'value');

Where dengan Operator


// Where dengan operator
->where('age', '>', 18);

Where IN


// Where dengan IN
->whereIn('id', [1, 2, 3]);

Where NOT IN


// Where dengan NOT IN
->whereNotIn('id', [1, 2, 3]);

Where NULL


// Where NULL - mencari data dengan nilai NULL
->whereNull('deleted_at');

Where NOT NULL


// Where NOT NULL - mencari data yang tidak NULL
->whereNotNull('email');

4.4 JOIN Tables

Inner Join

Menggabungkan data dari dua tabel berdasarkan kondisi yang cocok di kedua tabel.


// INNER JOIN dasar
$Tds->Network->Brief('users')
    ->join('orders', 'users.id = orders.user_id')
    ->get();

// INNER JOIN dengan kondisi tambahan
$Tds->Network->Brief('users')
    ->join('orders', 'users.id = orders.user_id AND orders.status = "completed"')
    ->get();

Left Join

Mengambil semua data dari tabel kiri (pertama) dan data yang cocok dari tabel kanan.


// LEFT JOIN dasar
$Tds->Network->Brief('users')
    ->leftJoin('orders', 'users.id = orders.user_id')
    ->get();

// LEFT JOIN dengan select kolom spesifik
$Tds->Network->Brief('users')
    ->select('users.name, orders.order_date')
    ->leftJoin('orders', 'users.id = orders.user_id')
    ->get();

Right Join

Mengambil semua data dari tabel kanan (kedua) dan data yang cocok dari tabel kiri.


// RIGHT JOIN dasar
$Tds->Network->Brief('orders')
    ->rightJoin('users', 'orders.user_id = users.id')
    ->get();

Multiple Join

Menggabungkan lebih dari dua tabel dalam satu query.


// Multiple JOIN
$Tds->Network->Brief('orders')
    ->select('orders.*, users.name, products.product_name')
    ->join('users', 'orders.user_id = users.id')
    ->join('products', 'orders.product_id = products.id')
    ->get();

// Kombinasi berbagai tipe JOIN
$Tds->Network->Brief('users')
    ->leftJoin('orders', 'users.id = orders.user_id')
    ->rightJoin('profiles', 'users.id = profiles.user_id')
    ->get();

Join dengan Subquery

Melakukan join dengan hasil dari subquery.


// JOIN dengan subquery
$Tds->Network->Brief('users')
    ->join('(SELECT user_id, COUNT(*) as order_count 
            FROM orders 
            GROUP BY user_id) as order_summary', 
           'users.id = order_summary.user_id')
    ->get();

4.5 GROUP dan HAVING

GROUP BY digunakan untuk mengelompokkan data, sedangkan HAVING digunakan untuk memfilter hasil pengelompokan.

Group By Dasar


// Mengelompokkan pesanan berdasarkan user_id
$Tds->Network->Brief('orders')
    ->select('user_id, COUNT(*) as total_orders')
    ->groupBy('user_id')
    ->get();

// Mengelompokkan berdasarkan multiple kolom
$Tds->Network->Brief('orders')
    ->select('user_id, status, COUNT(*) as total')
    ->groupBy('user_id, status')
    ->get();

Having Dasar


// Filter grup yang memiliki total pesanan lebih dari 5
$Tds->Network->Brief('orders')
    ->select('user_id, COUNT(*) as total_orders')
    ->groupBy('user_id')
    ->having('total_orders > 5')
    ->get();

// Having dengan operator perbandingan
$Tds->Network->Brief('orders')
    ->select('user_id, SUM(amount) as total_amount')
    ->groupBy('user_id')
    ->having('total_amount', '>', 1000)
    ->get();

Penggunaan Lanjutan


// Analisis penjualan per kategori
$Tds->Network->Brief('products')
    ->select('category, 
             COUNT(*) as total_products,
             AVG(price) as avg_price,
             SUM(stock) as total_stock')
    ->groupBy('category')
    ->having('total_products', '>', 10)
    ->having('avg_price', '>', 100)
    ->orderBy('total_stock', 'DESC')
    ->get();

// Analisis transaksi pelanggan
$Tds->Network->Brief('orders')
    ->select('users.name,
             COUNT(orders.id) as total_orders,
             SUM(orders.amount) as total_spent')
    ->join('users', 'orders.user_id = users.id')
    ->groupBy('users.id, users.name')
    ->having('total_orders', '>=', 3)
    ->having('total_spent', '>', 500)
    ->orderBy('total_spent', 'DESC')
    ->get();

// Analisis penjualan bulanan
$Tds->Network->Brief('orders')
    ->select('MONTH(created_at) as month,
             YEAR(created_at) as year,
             COUNT(*) as total_orders,
             SUM(amount) as revenue')
    ->groupBy('year, month')
    ->having('revenue', '>', 10000)
    ->orderBy('year', 'DESC')
    ->orderBy('month', 'DESC')
    ->get();

Tips Penggunaan

Gunakan GROUP BY untuk menganalisis data berdasarkan kategori atau periode tertentu
HAVING digunakan untuk memfilter hasil setelah pengelompokan, berbeda dengan WHERE yang memfilter sebelum pengelompokan
Kombinasikan dengan fungsi agregat (COUNT, SUM, AVG, dll) untuk analisis yang lebih mendalam
Perhatikan performa query saat menggunakan GROUP BY pada dataset besar
Gunakan index pada kolom yang sering digunakan dalam GROUP BY

4.6 ORDER BY

Order Ascending


// Order ascending
$query = $Tds->Network->Brief('users')
    ->orderBy('name', 'ASC')
    ->get();

Order Descending


// Order descending
$query = $Tds->Network->Brief('products')
    ->orderBy('price', 'DESC')
    ->get();

Multiple Order


// Multiple order
$query = $Tds->Network->Brief('orders')
    ->orderBy('status', 'ASC')
    ->orderBy('created_at', 'DESC')
    ->get();

Raw Order


// Raw order expression
$query = $Tds->Network->Brief('products')
    ->orderByRaw('FIELD(status, "active", "pending", "inactive")')
    ->get();

Random Order


// Random order
$query = $Tds->Network->Brief('products')
    ->inRandomOrder()
    ->limit(5)
    ->get();

4.7 LIMIT dan OFFSET

Limit Dasar


// Basic limit
$query = $Tds->Network->Brief('users')
    ->limit(10)
    ->get();

Offset Dasar


// Basic offset
$query = $Tds->Network->Brief('users')
    ->offset(10)
    ->limit(10)
    ->get();

Kombinasi Limit & Offset


// Kombinasi limit dan offset
$query = $Tds->Network->Brief('products')
    ->orderBy('created_at', 'DESC')
    ->skip(20)    // Alias untuk offset
    ->take(10)    // Alias untuk limit
    ->get();

Limit untuk Pagination


// Limit untuk pagination
$page = 2;
$perPage = 15;
$query = $Tds->Network->Brief('orders')
    ->offset(($page - 1) * $perPage)
    ->limit($perPage)
    ->get();

4.8 Upload File

NgoreiBuilder menyediakan method untuk menangani upload file dengan mudah dan aman.

Upload File Tunggal


// Upload file tunggal dasar
$upload = $Tds->Network->Brief('files')
    ->uploadFile($_FILES['file'], [
        'destination' => 'uploads/',
        'allowed_types' => ['jpg', 'png', 'pdf'],
        'max_size' => 2048,
        'encrypt_name' => true
    ]);

if ($upload['status']) {
    echo "File berhasil diupload: " . $upload['file_name'];
} else {
    echo "Error: " . $upload['message'];
}

// Upload dengan custom filename
$upload = $Tds->Network->Brief('files')
    ->uploadFile($_FILES['file'], [
        'destination' => 'uploads/images/',
        'file_name' => 'custom_' . time(),
        'allowed_types' => ['jpg', 'png'],
        'max_size' => 1024
    ]);

// Upload dengan resize gambar otomatis
$upload = $Tds->Network->Brief('files')
    ->uploadFile($_FILES['file'], [
        'destination' => 'uploads/photos/',
        'allowed_types' => ['jpg', 'png'],
        'max_size' => 2048,
        'create_thumb' => true,
        'thumb_width' => 150,
        'thumb_height' => 150
    ]);

Upload Multiple Files


// Upload multiple files
$files = $Tds->Network->Brief('files')
    ->uploadMultipleFiles($_FILES['files'], [
        'destination' => 'uploads/documents/',
        'allowed_types' => ['doc', 'docx', 'pdf'],
        'max_size' => 5120,
        'encrypt_name' => true
    ]);

foreach ($files as $file) {
    if ($file['status']) {
        echo "File {$file['original_name']} berhasil diupload sebagai {$file['file_name']}\n";
        
        // Simpan informasi file ke database
        $Tds->Network->Brief('files')->insert([
            'file_name' => $file['file_name'],
            'original_name' => $file['original_name'],
            'file_type' => $file['file_type'],
            'file_size' => $file['file_size'],
            'file_path' => $file['file_path']
        ]);
    } else {
        echo "Error mengupload {$file['original_name']}: {$file['message']}\n";
    }
}

// Upload multiple files dengan validasi per file
$files = $Tds->Network->Brief('files')
    ->uploadMultipleFiles($_FILES['files'], [
        'destination' => 'uploads/images/',
        'allowed_types' => ['jpg', 'png'],
        'max_size' => 2048,
        'min_width' => 800,
        'min_height' => 600,
        'max_width' => 2400,
        'max_height' => 1800
    ]);

Opsi Konfigurasi Upload

destination: Path folder tujuan upload (required)
allowed_types: Array ekstensi file yang diizinkan (required)
max_size: Ukuran maksimal file dalam KB (required)
encrypt_name: Enkripsi nama file untuk keamanan (default: false)
file_name: Set nama file custom (optional)
create_thumb: Buat thumbnail untuk gambar (default: false)
thumb_width: Lebar thumbnail dalam pixel
thumb_height: Tinggi thumbnail dalam pixel
maintain_ratio: Pertahankan rasio aspek saat resize (default: true)
min_width: Lebar minimum untuk file gambar
min_height: Tinggi minimum untuk file gambar
max_width: Lebar maksimum untuk file gambar
max_height: Tinggi maksimum untuk file gambar
overwrite: Izinkan overwrite file yang sudah ada (default: false)
create_directory: Buat direktori jika belum ada (default: true)

Validasi File


// Validasi tipe MIME
$upload = $Tds->Network->Brief('files')
    ->uploadFile($_FILES['file'], [
        'destination' => 'uploads/',
        'allowed_types' => ['image/jpeg', 'image/png', 'application/pdf'],
        'max_size' => 2048
    ]);

// Validasi dimensi gambar
$upload = $Tds->Network->Brief('files')
    ->uploadFile($_FILES['file'], [
        'destination' => 'uploads/images/',
        'allowed_types' => ['jpg', 'png'],
        'min_width' => 800,
        'min_height' => 600,
        'max_width' => 2400,
        'max_height' => 1800
    ]);

// Validasi custom
$upload = $Tds->Network->Brief('files')
    ->uploadFile($_FILES['file'], [
        'destination' => 'uploads/',
        'allowed_types' => ['pdf'],
        'max_size' => 5120,
        'custom_validation' => function($file) {
            // Lakukan validasi custom
            return true;
        }
    ]);

Response Upload

Method upload akan mengembalikan array dengan struktur:


[
    'status' => true/false,           // Status upload
    'message' => 'Success/Error',     // Pesan sukses/error
    'file_name' => 'uploaded.jpg',    // Nama file setelah diupload
    'original_name' => 'photo.jpg',   // Nama asli file
    'file_size' => 1024,             // Ukuran file dalam KB
    'file_type' => 'image/jpeg',     // Tipe MIME file
    'file_path' => 'uploads/file.jpg',// Path lengkap file
    'image_width' => 800,            // Lebar gambar (untuk file gambar)
    'image_height' => 600,           // Tinggi gambar (untuk file gambar)
    'thumb_path' => 'thumbs/file.jpg',// Path thumbnail (jika dibuat)
]

Tips Upload File

Selalu validasi tipe file yang diupload untuk keamanan
Gunakan encrypt_name untuk menghindari konflik nama file
Set ukuran maksimum file sesuai kebutuhan
Validasi dimensi gambar untuk menjaga kualitas
Buat thumbnail untuk mengoptimalkan loading gambar
Simpan informasi file di database untuk tracking
Gunakan try-catch untuk menangani error upload
Bersihkan file temporary setelah upload selesai

4.9 Pagination

NgoreiBuilder menyediakan fitur pagination yang mudah digunakan untuk membagi data menjadi beberapa halaman.

Penggunaan Dasar


// Pagination dasar dengan 10 item per halaman
$users = $Tds->Network->Brief('users')
    ->paginate(10);

// Pagination dengan halaman tertentu
$page = $_GET['page'] ?? 1;
$users = $Tds->Network->Brief('users')
    ->page($page)
    ->paginate(10);

// Pagination dengan kondisi WHERE
$activeUsers = $Tds->Network->Brief('users')
    ->where('status', 'active')
    ->orderBy('created_at', 'DESC')
    ->paginate(15);

Hasil Pagination

Method paginate() akan mengembalikan array dengan struktur berikut:


[
    'data' => [
        // Array berisi data untuk halaman saat ini
        ['id' => 1, 'name' => 'John'],
        ['id' => 2, 'name' => 'Jane'],
        // ...
    ],
    'pagination' => [
        'total' => 100,          // Total seluruh data
        'per_page' => 10,        // Jumlah item per halaman
        'current_page' => 1,     // Halaman saat ini
        'last_page' => 10,       // Halaman terakhir
        'from' => 1,             // Index item pertama di halaman ini
        'to' => 10,              // Index item terakhir di halaman ini
        'has_more' => true       // Apakah masih ada halaman berikutnya
    ]
]

// Contoh penggunaan hasil pagination di view
foreach ($users['data'] as $user) {
    echo $user['name'] . "\n";
}

// Menampilkan informasi pagination
$pagination = $users['pagination'];
echo "Menampilkan {$pagination['from']} - {$pagination['to']} dari {$pagination['total']} data";

// Membuat link pagination
for ($i = 1; $i <= $pagination['last_page']; $i++) {
    $class = ($i == $pagination['current_page']) ? 'active' : '';
    echo "{$i}";
}

Contoh Implementasi dengan Bootstrap


// Di controller
$users = $Tds->Network->Brief('users')->paginate(10);

// Di view
<table class="table">
    <thead>
        <tr>
            <th>ID</th>
            <th>Nama</th>
            <th>Email</th>
        </tr>
    </thead>
    <tbody>
        <?php foreach ($users['data'] as $user): ?>
            <tr>
                <td><?= $user['id'] ?></td>
                <td><?= $user['name'] ?></td>
                <td><?= $user['email'] ?></td>
            </tr>
        <?php endforeach; ?>
    </tbody>
</table>

<nav>
    <ul class="pagination">
        <?php
        $pagination = $users['pagination'];
        $current = $pagination['current_page'];
        $last = $pagination['last_page'];
        
        // Tombol Previous
        if ($current > 1): ?>
            <li class="page-item">
                <a class="page-link" href="?page=<?= $current - 1 ?>">Previous</a>
            </li>
        <?php endif;

        // Nomor Halaman
        for ($i = 1; $i <= $last; $i++):
            $active = ($i == $current) ? ' active' : '';
        ?>
            <li class="page-item<?= $active ?>">
                <a class="page-link" href="?page=<?= $i ?>"><?= $i ?></a>
            </li>
        <?php endfor;

        // Tombol Next
        if ($current < $last): ?>
            <li class="page-item">
                <a class="page-link" href="?page=<?= $current + 1 ?>">Next</a>
            </li>
        <?php endif; ?>
    </ul>
</nav>

4.10 Validasi Data

Tipe Validasi

Validasi Teks


// Validasi teks
$text = $builder->validasi($input, 'text', 255);

Validasi Email


// Validasi email
$email = $builder->validasi($input, 'email');

Validasi Password


// Validasi password (min 8 karakter, harus mengandung huruf besar, kecil, dan angka)
$password = $builder->validasi($input, 'password');

Validasi Angka


// Validasi angka
$number = $builder->validasi($input, 'number');

// Validasi dengan range
$age = $builder->validasi($input, 'number', ['min' => 18, 'max' => 100]);

Validasi Tanggal


// Validasi tanggal
$date = $builder->validasi($input, 'date');

// Validasi tanggal dengan format spesifik
$customDate = $builder->validasi($input, 'date', 'Y-m-d H:i:s');

Validasi URL


// Validasi URL
$url = $builder->validasi($input, 'url');

// Validasi URL dengan protokol spesifik
$secureUrl = $builder->validasi($input, 'url', ['protocols' => ['https']]);

Validasi Nomor Telepon


// Validasi nomor telepon (8-15 digit)
$phone = $builder->validasi($input, 'phone');

// Validasi dengan format Indonesia
$phone = $builder->validasi($input, 'phone', 'ID');

Validasi Username


// Validasi username (hanya huruf, angka, underscore, min 3 karakter)
$username = $builder->validasi($input, 'username');

Validasi Lainnya


// Validasi warna hex
$color = $builder->validasi($input, 'color');

// Validasi IP address
$ip = $builder->validasi($input, 'ip');

// Validasi JSON
$json = $builder->validasi($input, 'json');

// Validasi array
$array = $builder->validasi($input, 'array');

// Validasi boolean
$bool = $builder->validasi($input, 'boolean');

// Validasi mata uang
$currency = $builder->validasi($input, 'currency');

// Validasi ekstensi file
$file = $builder->validasi($input, 'file_extension');

Tipe Validasi yang Tersedia:

text: Validasi teks biasa dengan pembersihan karakter berbahaya
email: Validasi format email dan domain
password: Minimal 8 karakter, harus mengandung huruf besar, kecil, dan angka
number: Validasi angka
date: Validasi format tanggal
url: Validasi format URL
phone: Validasi nomor telepon (8-15 digit)
username: Hanya huruf, angka, underscore (min 3 karakter)
slug: Mengubah teks menjadi format URL-friendly
color: Validasi format warna hex
ip: Validasi format IP address
json: Validasi format JSON
array: Validasi dan konversi array ke JSON
boolean: Konversi ke boolean
currency: Format mata uang
file_extension: Validasi ekstensi file

Penanganan Error


// Cek error validasi
$errors = $builder->getValidationErrors();

4.11 Query Caching

Penggunaan Cache


// Mengaktifkan cache dengan waktu kedaluwarsa 5 menit
$result = $Tds->Network->Brief('users')
    ->useCache(true)
    ->setCacheExpiry(300)
    ->get();

Menonaktifkan Cache


// Menonaktifkan cache untuk query tertentu
$result = $Tds->Network->Brief('users')
    ->useCache(false)
    ->get();

4.12 Batch Operations

Untuk operasi dengan data dalam jumlah besar:


// Insert batch
$data = [
    ['name' => 'John', 'email' => 'john@example.com'],
    ['name' => 'Jane', 'email' => 'jane@example.com'],
    // ...
];

$inserted = $Tds->Network->Brief('users')
    ->insertBatch($data);

echo "Berhasil insert {$inserted} data";

4.13 Fungsi Agregat

Count

Menghitung jumlah baris atau nilai dalam kolom.


// Hitung semua baris
$total = $Tds->Network->Brief('users')->count();

// Hitung dengan kondisi
$activeUsers = $Tds->Network->Brief('users')
    ->where('status', 'active')
    ->count();

// Hitung nilai unik
$uniqueCategories = $Tds->Network->Brief('products')
    ->select('COUNT(DISTINCT category) as total')
    ->get();

Sum

Menjumlahkan nilai dalam kolom numerik.


// Jumlah total pendapatan
$totalRevenue = $Tds->Network->Brief('orders')
    ->sum('amount');

// Jumlah dengan kondisi
$monthlyRevenue = $Tds->Network->Brief('orders')
    ->where('MONTH(created_at)', date('m'))
    ->sum('amount');

// Jumlah multiple kolom
$totals = $Tds->Network->Brief('orders')
    ->select('SUM(amount) as total_amount, 
             SUM(quantity) as total_items')
    ->get();

Average

Menghitung rata-rata nilai dalam kolom numerik.


// Rata-rata umur
$avgAge = $Tds->Network->Brief('users')
    ->avg('age');

// Rata-rata dengan kondisi
$avgOrderValue = $Tds->Network->Brief('orders')
    ->where('status', 'completed')
    ->avg('amount');

// Rata-rata dengan grouping
$avgByCategory = $Tds->Network->Brief('products')
    ->select('category, AVG(price) as avg_price')
    ->groupBy('category')
    ->get();

Maximum

Mencari nilai tertinggi dalam kolom.


// Nilai maksimum
$highestPrice = $Tds->Network->Brief('products')
    ->max('price');

// Maksimum per kategori
$maxPrices = $Tds->Network->Brief('products')
    ->select('category, MAX(price) as highest_price')
    ->groupBy('category')
    ->get();

Minimum

Mencari nilai terendah dalam kolom.


// Nilai minimum
$lowestPrice = $Tds->Network->Brief('products')
    ->min('price');

// Minimum per kategori
$minPrices = $Tds->Network->Brief('products')
    ->select('category, MIN(price) as lowest_price')
    ->groupBy('category')
    ->get();

Kombinasi Fungsi Agregat

Menggunakan beberapa fungsi agregat sekaligus untuk analisis komprehensif.


// Analisis lengkap produk
$productStats = $Tds->Network->Brief('products')
    ->select('category,
             COUNT(*) as total_products,
             SUM(stock) as total_stock,
             AVG(price) as avg_price,
             MAX(price) as highest_price,
             MIN(price) as lowest_price')
    ->groupBy('category')
    ->having('total_products', '>', 5)
    ->orderBy('total_stock', 'DESC')
    ->get();

// Analisis penjualan
$salesAnalysis = $Tds->Network->Brief('orders')
    ->select('MONTH(created_at) as month,
             COUNT(*) as total_orders,
             SUM(amount) as total_revenue,
             AVG(amount) as avg_order_value,
             MAX(amount) as largest_order,
             MIN(amount) as smallest_order')
    ->where('YEAR(created_at)', date('Y'))
    ->groupBy('month')
    ->get();

5. Contoh Penggunaan


// Contoh query kompleks
$result = $Tds->Network->Brief('users')
    ->select('users.*, COUNT(orders.id) as total_orders')
    ->leftJoin('orders', 'users.id', '=', 'orders.user_id')
    ->where('users.status', 'active')
    ->whereBetween('users.created_at', ['2023-01-01', '2023-12-31'])
    ->groupBy('users.id')
    ->having('total_orders', '>', 5)
    ->orderBy('total_orders', 'DESC')
    ->limit(10)
    ->get();

6. Tips dan Trik

Selalu gunakan prepared statements untuk menghindari SQL injection
Manfaatkan method chaining untuk membuat query yang lebih mudah dibaca
Gunakan index pada kolom yang sering digunakan dalam klausa WHERE
Optimalkan query dengan memilih kolom yang diperlukan saja
Manfaatkan caching untuk query yang sering diakses