README

Hypervel Meta Generator adalah package powerful yang memungkinkan Anda dengan mudah melampirkan dan mengelola metadata untuk model Eloquent Anda tanpa memodifikasi tabel database utama mereka. Package ini menyediakan sistem key-value yang fleksibel dengan fitur deteksi tipe otomatis, casting, dan perintah artisan yang berguna untuk menyederhanakan instalasi dan maintenance.

🚀 Dibangun untuk Hypervel Framework - Framework PHP high-performance dengan dukungan coroutine native berbasis Swoole.

Daftar Isi

• Fitur
• Instalasi
• Penggunaan
  • Melampirkan Metadata ke Model
  • Mengelola Metadata
• Artisan Commands
  • make:metadata
  • metadata:clean-orphaned
• Konfigurasi
• Perbedaan dengan Laravel Version
• License

Fitur

✨ Auto Type Detection - Deteksi tipe data otomatis (string, integer, boolean, json, datetime, dll) ✨ Type Casting - Casting otomatis saat retrieve data ✨ Query Scopes - Query builder scopes untuk filter berdasarkan metadata ✨ Artisan Commands - Generate metadata system dan clean orphaned records ✨ Coroutine Safe - Dioptimasi untuk environment Swoole/Hypervel dengan coroutine support ✨ Zero Table Modification - Tidak perlu mengubah tabel database utama

Instalasi

Ada dua cara untuk mengintegrasikan Hypervel Meta Generator ke dalam project Anda:

1. Via Packagist (Coming Soon)

composer require augustpermana/hypervel-meta-generator

Hypervel akan secara otomatis menemukan service provider melalui package discovery.

2. Menggunakan Local Repository

Jika package belum dipublish di Packagist, tambahkan sebagai local repository. Modifikasi composer.json project Anda:

"repositories": [
    {
        "type": "path",
        "url": "./vendor/augustpermana/hypervel-meta-generator"
    }
],
"require": {
    "augustpermana/hypervel-meta-generator": "@dev"
}

Kemudian jalankan:

composer update augustpermana/hypervel-meta-generator

Penggunaan

Hypervel Meta Generator memungkinkan Anda melampirkan metadata ke model tanpa memodifikasi tabel database asli.

Melampirkan Metadata ke Model

1. Generate Metadata Files:

   Jalankan artisan command untuk setup metadata system untuk model yang ada. Contoh untuk model Product:

   php artisan make:metadata --model=Product

   Saat Anda menjalankan command ini, akan melakukan:

   • Membuat Meta Model File: Generate file baru (contoh: ProductMeta.php) di direktori app/Models
   • Membuat Migration: Generate migration untuk membuat tabel metadata (contoh: product_meta)

2. Update Model Asli:

   Anda harus secara manual update model asli (contoh: Product.php) untuk menyertakan trait HasMetadata:

   <?php
   
   namespace App\Models;
   
   use App\Models\Model;
   use AugustPermana\HypervelMetaGenerator\Traits\HasMetadata;
   
   class Product extends Model
   {
       use HasMetadata;
       
       // ... model code lainnya
   }

3. Jalankan Migration:

   php artisan migrate

Mengelola Metadata

Setelah setup, Anda dapat menggunakan berbagai method untuk manage metadata:

Set Single Meta

$product = Product::find(1);
$product->setMeta('warranty_period', 24); // Auto-detected as integer
$product->setMeta('is_featured', true);   // Auto-detected as boolean
$product->setMeta('specifications', [     // Auto-detected as json
    'color' => 'black',
    'weight' => '1.5kg'
]);

Get Single Meta

$warrantyPeriod = $product->getMeta('warranty_period'); // Returns: 24 (as integer)
$isFeatured = $product->getMeta('is_featured');         // Returns: true (as boolean)
$specs = $product->getMeta('specifications');           // Returns: array

// Dengan default value
$discount = $product->getMeta('discount', 0); // Returns: 0 jika tidak ada

Set Multiple Meta

$product->setManyMeta([
    'brand' => 'Samsung',
    'warranty_period' => 24,
    'is_featured' => true,
    'release_date' => '2025-10-22'
]);

Sync Meta (Replace All)

// Hapus semua metadata yang ada dan ganti dengan yang baru
$product->syncMeta([
    'brand' => 'Apple',
    'model' => 'iPhone 15',
    'price' => 999.99
]);

Check Meta Exists

if ($product->hasMeta('warranty_period')) {
    // Metadata exists
}

Remove Meta

$product->removeMeta('old_field');

Query dengan Meta Scope

// Cari semua produk yang featured
$featuredProducts = Product::whereHasMeta('is_featured', '1')->get();

// Cari semua produk yang punya metadata 'warranty_period'
$productsWithWarranty = Product::whereHasMeta('warranty_period')->get();

Artisan Commands

make:metadata

Generate metadata system untuk model yang sudah ada.

php artisan make:metadata --model=Product

Command ini akan:

• Membuat model meta baru (ProductMeta.php)
• Membuat migration untuk tabel metadata

metadata:clean-orphaned

Membersihkan orphaned metadata records (metadata yang parent recordnya sudah dihapus).

php artisan metadata:clean-orphaned --model=Product

⚠️ PERINGATAN: Command ini akan menghapus data dari database. Backup database Anda sebelum menjalankan command ini.

Konfigurasi

Package ini tidak memerlukan konfigurasi khusus. Namun, Anda dapat customize:

Custom Meta Model Location

Secara default, meta model akan dibuat di App\Models. Jika Anda ingin menggunakan lokasi berbeda, override method getMetaModelClass() di model Anda:

protected function getMetaModelClass()
{
    return 'App\\CustomNamespace\\' . class_basename($this) . 'Meta';
}

Supported Data Types

Package ini secara otomatis mendeteksi dan mendukung tipe data berikut:

• string - String pendek
• text - String panjang (> 255 chars)
• longtext - String sangat panjang (> 65535 chars)
• integer - Bilangan bulat
• float / double - Bilangan desimal
• decimal - Bilangan desimal presisi
• boolean - True/False
• json - Array atau Object
• date - Tanggal (Y-m-d)
• time - Waktu (H:i:s)
• datetime / timestamp - Tanggal dan waktu
• binary - Binary data (base64 encoded)

Perbedaan dengan Laravel Version

Package ini adalah adaptasi dari augustpermana/laravel-meta-generator untuk Hypervel Framework dengan perubahan berikut:

Performance Tips

1. Eager Loading Metadata

// ❌ N+1 Problem
$products = Product::all();
foreach ($products as $product) {
    $brand = $product->getMeta('brand'); // Query di setiap loop
}

// ✅ Eager Loading
$products = Product::with('meta')->get();
foreach ($products as $product) {
    $brand = $product->getMeta('brand'); // Tidak ada query tambahan
}

2. Batch Operations

// ❌ Multiple Queries
$product->setMeta('field1', 'value1');
$product->setMeta('field2', 'value2');
$product->setMeta('field3', 'value3');

// ✅ Single Batch
$product->setManyMeta([
    'field1' => 'value1',
    'field2' => 'value2',
    'field3' => 'value3',
]);

3. Indexing

Tabel metadata secara otomatis memiliki composite index pada (foreign_key, key) untuk query yang lebih cepat.

Requirements

• PHP: >= 8.2
• Hypervel Framework: ^0.3
• Swoole Extension: >= 5.0
• ext-json: *

Contributing

Kontribusi sangat diterima! Silakan buat pull request atau buka issue di repository GitHub.

License

Package ini adalah open-source software yang dilisensikan di bawah MIT license.

Author

Agus Permana

• Email: agus.emailnya@gmail.com
• GitHub: @agus-gian

Credits

Package ini terinspirasi dari kebutuhan untuk mengelola metadata dinamis tanpa mengubah struktur tabel database, dengan optimasi khusus untuk environment Hypervel yang high-performance.

Happy Coding with Hypervel! 🚀