Pemecahan Masalah

Panduan ini membantu Anda menyelesaikan masalah umum saat menginstal, mengkonfigurasi, atau menggunakan Laravel Nusa.

Masalah Instalasi

Ekstensi SQLite PHP Hilang

Error: could not find driver atau PDO SQLite driver not found

Solusi: Instal ekstensi SQLite PHP:

bash

# Ubuntu/Debian
sudo apt-get install php8.2-sqlite3

# CentOS/RHEL/Fedora
sudo yum install php-sqlite3
# atau
sudo dnf install php-sqlite3

# macOS dengan Homebrew
brew install [email protected]

# Windows (batalkan komentar di php.ini)
extension=pdo_sqlite
extension=sqlite3

Verifikasi instalasi:

bash

php -m | grep sqlite
# Seharusnya menampilkan: pdo_sqlite, sqlite3

Instalasi Composer Gagal

Error: Package not found atau Version conflicts

Solusi:

Bersihkan cache Composer:

bash

composer clear-cache
composer install --no-cache

Perbarui Composer:
bash
```
composer self-update
```
Periksa versi PHP:
bash
```
php -v
# Pastikan PHP >= 8.2
```

Instal dengan versi tertentu:

bash

composer require creasi/laravel-nusa:^0.1

Kompatibilitas Versi Laravel

Error: Package requires Laravel X.Y but you have Z.A

Solusi: Periksa matriks kompatibilitas:

Laravel Nusa	Versi Laravel
0.1.x	9.0 - 12.x

Perbarui Laravel atau gunakan versi yang kompatibel:

bash

# Perbarui Laravel
composer update laravel/framework

# Atau instal versi Nusa yang kompatibel
composer require creasi/laravel-nusa:^0.1

Masalah Database

Database SQLite Tidak Ditemukan

Error: database disk image is malformed atau no such file

Solusi:

Periksa apakah file ada:

bash

ls -la vendor/creasi/laravel-nusa/database/nusa.sqlite

Instal ulang paket:

bash

composer remove creasi/laravel-nusa
composer require creasi/laravel-nusa

Periksa izin file:

bash

chmod 644 vendor/creasi/laravel-nusa/database/nusa.sqlite

Error Koneksi Database

Error: SQLSTATE[HY000] [14] unable to open database file

Solusi:

Periksa jalur database:

php

// Di tinker
config('database.connections.nusa.database')

Verifikasi izin file:

bash

# Jadikan direktori dapat ditulis
chmod 755 vendor/creasi/laravel-nusa/database/

# Jadikan file dapat dibaca
chmod 644 vendor/creasi/laravel-nusa/database/nusa.sqlite

Uji koneksi:

bash

php artisan tinker
>>> DB::connection('nusa')->getPdo()

Error Kendala Kunci Asing

Error: FOREIGN KEY constraint failed

Solusi: Aktifkan kendala kunci asing:

php

// Di config/database.php
'nusa' => [
    'driver' => 'sqlite',
    'database' => database_path('nusa.sqlite'),
    'foreign_key_constraints' => true, // Tambahkan ini
],

Masalah Konfigurasi

Rute Tidak Berfungsi

Error: Route [nusa.provinces.index] not defined

Solusi:

Periksa apakah rute diaktifkan:

bash

# Di .env
CREASI_NUSA_ROUTES_ENABLE=true

Bersihkan cache rute:

bash

php artisan route:clear
php artisan config:clear

Verifikasi penyedia layanan dimuat:

bash

php artisan config:show app.providers | grep Nusa

Periksa registrasi rute:
bash
```
php artisan route:list | grep nusa
```

Endpoint API Mengembalikan 404

Error: 404 Not Found untuk /nusa/provinces

Solusi:

Periksa awalan rute:

bash

# Di .env
CREASI_NUSA_ROUTES_PREFIX=nusa

Verifikasi konfigurasi web server:

apache

# Apache .htaccess
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ index.php [QSA,L]

Uji dengan URL lengkap:

bash

curl http://your-app.test/index.php/nusa/provinces

Masalah Cache Konfigurasi

Error: Perubahan konfigurasi tidak berlaku

Solusi: Bersihkan cache konfigurasi:

bash

php artisan config:clear
php artisan config:cache
php artisan route:clear

Masalah Model dan Kueri

Error Model Tidak Ditemukan

Error: Class 'Creasi\Nusa\Models\Province' not found

Solusi:

Periksa autoloader:
bash
```
composer dump-autoload
```
Verifikasi instalasi paket:
bash
```
composer show creasi/laravel-nusa
```

Periksa impor namespace:

php

use Creasi\Nusa\Models\Province; // Tambahkan ini

Hasil Kueri Kosong

Error: Model mengembalikan koleksi kosong

Solusi:

Uji koneksi database:

bash

php artisan tinker
>>> DB::connection('nusa')->table('provinces')->count()

Periksa nama tabel:

bash

>>> Schema::connection('nusa')->getTableListing()

Verifikasi data ada:

bash

sqlite3 vendor/creasi/laravel-nusa/database/nusa.sqlite
.tables
SELECT COUNT(*) FROM provinces;

Error Relasi

Error: Call to undefined relationship

Solusi: Periksa apakah metode relasi ada:

php

// Penggunaan yang benar
$province = Province::find('33');
$regencies = $province->regencies; // Bukan regency()

// Relasi yang tersedia
$province->regencies;  // HasMany
$province->districts;  // HasMany  
$province->villages;   // HasMany

Masalah Kinerja

Kinerja Kueri Lambat

Masalah: Kueri memakan waktu terlalu lama

Solusi:

Gunakan paginasi:

php

// Baik
Village::paginate(50);

// Hindari
Village::all(); // 83.762 catatan!

Pilih kolom tertentu:

php

Province::select('code', 'name')->get();

Gunakan eager loading:
php
```
Province::with('regencies')->get();
```

Periksa indeks:

sql

EXPLAIN QUERY PLAN SELECT * FROM villages WHERE province_code = '33';

Batas Memori Terlampaui

Error: Fatal error: Allowed memory size exhausted

Solusi:

Tingkatkan batas memori:

bash

php -d memory_limit=512M artisan your:command

Gunakan chunking untuk dataset besar:

php

Village::chunk(1000, function ($villages) {
    foreach ($villages as $village) {
        // Proses desa/kelurahan
    }
});

Optimalkan kueri:

php

// Gunakan select() untuk membatasi kolom
Village::select('code', 'name')->chunk(1000, $callback);

Masalah Pengembangan

Masalah Submodule

Error: Submodule path 'workbench/submodules/wilayah': checked out 'abc123'

Solusi:

Inisialisasi submodule:
bash
```
git submodule update --init --recursive
```
Perbarui submodule:
bash
```
git submodule update --remote
```

Reset submodule:

bash

git submodule deinit --all
git submodule update --init --recursive

Masalah Docker

Error: Cannot connect to the Docker daemon

Solusi:

Mulai layanan Docker:

bash

# Linux
sudo systemctl start docker

# macOS
open -a Docker

Periksa Docker Compose:
bash
```
docker-compose --version
```

Reset lingkungan Docker:

bash

composer upstream:down
docker system prune -f
composer upstream:up

Perintah Impor Gagal

Error: Perintah impor data gagal

Solusi:

Periksa koneksi database:

bash

composer testbench tinker
>>> DB::connection()->getPdo()

Verifikasi submodule:
bash
```
ls -la workbench/submodules/
```

Jalankan dengan output verbose:

bash

composer testbench nusa:import -- --fresh -v

Periksa ruang disk:
bash
```
df -h
```

Masalah API

Error CORS

Error: Access to fetch at 'http://localhost/nusa/provinces' from origin 'http://localhost:3000' has been blocked by CORS policy

Solusi: Konfigurasi CORS di Laravel:

php

// config/cors.php
'paths' => ['api/*', 'nusa/*'],
'allowed_methods' => ['GET'],
'allowed_origins' => ['*'], // Atau domain tertentu
'allowed_headers' => ['*'],

Masalah Pembatasan Laju

Error: 429 Too Many Requests

Solusi:

Periksa batas laju:

php

// Di rute atau middleware
Route::middleware(['throttle:60,1'])->group(function () {
    // Rute Anda
});

Tingkatkan batas:

php

Route::middleware(['throttle:1000,1'])->group(function () {
    // Rute batas yang lebih tinggi
});

Masalah Respon JSON

Error: Respon JSON tidak valid

Solusi:

Periksa header Accept:

bash

curl -H "Accept: application/json" http://your-app.test/nusa/provinces

Verifikasi rute API:
bash
```
php artisan route:list | grep nusa
```

Mendapatkan Bantuan

Informasi Debug

Saat melaporkan masalah, sertakan:

bash

# Informasi sistem
php -v
composer --version
laravel --version

# Informasi paket
composer show creasi/laravel-nusa

# Konfigurasi Laravel
php artisan about

# Uji koneksi database
php artisan tinker
>>> DB::connection('nusa')->getPdo()
>>> \Creasi\Nusa\Models\Province::count()

File Log

Periksa file log ini untuk error:

bash

# Log Laravel
tail -f storage/logs/laravel.log

# Log web server
tail -f /var/log/apache2/error.log
tail -f /var/log/nginx/error.log

# Log PHP
tail -f /var/log/php_errors.log

Saluran Dukungan

Dokumentasi - Periksa dokumentasi ini terlebih dahulu
Masalah GitHub - Laporkan bug
Diskusi GitHub - Dukungan komunitas
Stack Overflow - Beri tag dengan laravel-nusa

Membuat Laporan Bug

Sertakan informasi ini:

Lingkungan: Versi PHP, versi Laravel, OS
Versi paket: composer show creasi/laravel-nusa
Pesan error: Error lengkap dengan stack trace
Langkah-langkah untuk mereproduksi: Contoh kode minimal
Perilaku yang diharapkan: Apa yang seharusnya terjadi
Perilaku aktual: Apa yang sebenarnya terjadi

Panduan pemecahan masalah ini mencakup masalah paling umum. Jika Anda menemukan masalah yang tidak tercantum di sini, silakan periksa masalah GitHub atau buat yang baru dengan informasi terperinci.

Pemecahan Masalah ​

Masalah Instalasi ​

Ekstensi SQLite PHP Hilang ​

Instalasi Composer Gagal ​

Kompatibilitas Versi Laravel ​

Masalah Database ​

Database SQLite Tidak Ditemukan ​

Error Koneksi Database ​

Error Kendala Kunci Asing ​

Masalah Konfigurasi ​

Rute Tidak Berfungsi ​

Endpoint API Mengembalikan 404 ​

Masalah Cache Konfigurasi ​

Masalah Model dan Kueri ​

Error Model Tidak Ditemukan ​

Hasil Kueri Kosong ​

Error Relasi ​

Masalah Kinerja ​

Kinerja Kueri Lambat ​

Batas Memori Terlampaui ​

Masalah Pengembangan ​

Masalah Submodule ​

Masalah Docker ​

Perintah Impor Gagal ​

Masalah API ​

Error CORS ​

Masalah Pembatasan Laju ​

Masalah Respon JSON ​

Mendapatkan Bantuan ​

Informasi Debug ​

File Log ​

Saluran Dukungan ​

Membuat Laporan Bug ​

Pemecahan Masalah

Masalah Instalasi

Ekstensi SQLite PHP Hilang

Instalasi Composer Gagal

Kompatibilitas Versi Laravel

Masalah Database

Database SQLite Tidak Ditemukan

Error Koneksi Database

Error Kendala Kunci Asing

Masalah Konfigurasi

Rute Tidak Berfungsi

Endpoint API Mengembalikan 404

Masalah Cache Konfigurasi

Masalah Model dan Kueri

Error Model Tidak Ditemukan

Hasil Kueri Kosong

Error Relasi

Masalah Kinerja

Kinerja Kueri Lambat

Batas Memori Terlampaui

Masalah Pengembangan

Masalah Submodule

Masalah Docker

Perintah Impor Gagal

Masalah API

Error CORS

Masalah Pembatasan Laju

Masalah Respon JSON

Mendapatkan Bantuan

Informasi Debug

File Log

Saluran Dukungan

Membuat Laporan Bug