Rol Tabanlı Yetkilendirme Paneli

CY Admin — PHP PDO · MySQL · AJAX Yönetim Paneli

Sıfır bağımlılıklı, OOP mimarili, rol tabanlı yetkilendirmeye sahip açık kaynak yönetim paneli örneği.

Rol tabanlı yetkilendirme · Sunucu taraflı DataTables · CSRF korumalı AJAX
Modal CRUD · Açık/koyu tema · Mobil uyumlu

English · cilginyazilim.com · MIT Lisansı

---

Ekran Görüntüleri

Tanıtım sayfası — herkese açık, sistemin ne yaptığını anlatır

Kontrol paneli — özet kartlar, kayıt grafiği, role özel bölümler

Kullanıcı yönetimi — sunucu taraflı tablo, arama ve filtreler

Roller ve yetkiler — hangi rol neyi yapabilir, tek tabloda

Giriş ekranı

Koyu tema

Hesabım

Sistem

Mobil görünüm

---

İçindekiler

• Bu proje nedir?
• Öne çıkan özellikler
• Kurulum
• Demo hesaplar
• Klasör yapısı
• Mimari
• Roller ve yetkiler
• Güvenlik önlemleri
• Yeni sayfa nasıl eklenir?
• Canlıya alma kontrol listesi
• Sık karşılaşılan sorunlar
• Katkı ve lisans

---

Bu proje nedir?

PHP öğrenirken en çok takılınan yer, "çalışan kod" ile "doğru kod" arasındaki
farktır. Bu depo, klasik bir CRUD örneğini alıp gerçek bir projede olması
gereken hâline getiriyor: katmanlı mimari, rol tabanlı yetkilendirme,
oturum yönetimi ve baştan sona güvenlik.

Composer yok, framework yok, CDN yok. İndirin, cy_login.sql dosyasını içe
aktarın, çalışır. Tüm kod satır satır Türkçe açıklamalıdır; amaç kopyalamak
değil, neden öyle yazıldığını anlamaktır.

Bu depo daha önce tek dosyalık bir CRUD örneğiydi.
Yeni sürümde tam bir yönetim paneline dönüştürüldü.
Eski kurulumdan geçiş için cy_login.sql dosyasının sonundaki
"6) ESKİ SÜRÜMDEN YÜKSELTME" bölümüne bakın.

---

Öne çıkan özellikler

Mimari

• OOP katmanlı yapı — Core / Models / Repositories / Controllers / Views
• PSR-4 mantığında otomatik yükleyici (Composer'sız)
• Tek giriş noktası (front controller) + rota tablosu
• Repository deseni — SQL tek dosyada, denetleyiciler temiz
• Ara katmanlar (middleware) — yetki kontrolü rota tanımında

Kimlik ve oturum

• Beni hatırla — iki parçalı anahtar (selector + validator), sır veritabanında

özetlenmiş saklanır, anahtar tek kullanımlıktır ve her otomatik girişte yenilenir

• Parola değişince tüm cihazlardaki kalıcı oturumlar iptal edilir
• Kaba kuvvet koruması, oturum sertleştirme, taze yetki kontrolü

Yönetim paneli

• Herkese açık tanıtım sayfası — kök adres, sistemin ne yaptığını anlatır
• Roller ve Yetkiler sayfası — yetki matrisi; her kullanıcı kendi sınırlarını görür
• Role özel kontrol paneli — yönetici/editör istatistik görür, üye kendi hesap özetini
• Temiz adresler — /login, /users (mod_rewrite kapalıysa tek ayarla eski biçime döner)
• Açık/koyu tema hesaba bağlıdır — başka cihazdan girseniz de tercihiniz gelir
• Daraltılabilir sol menü (masaüstünde ikon modu, mobilde çekmece)
• Kontrol paneli: özet kartlar, 14 günlük kayıt grafiği, işlem günlüğü
• Kullanıcı yönetimi: sunucu taraflı DataTables, canlı arama, rol/durum filtresi
• Modal tabanlı ekle / düzenle / detay / sil akışı
• Hesabım sayfası: profil, görsel, parola değiştirme
• Sistem sayfası: güvenlik denetimi, veri durumu ve yürürlükteki kurallar

Mobil

• Off-canvas menü, karartma katmanı, ESC ile kapatma
• 44×44 px dokunma hedefleri
• Modallar alttan açılan panel biçiminde
• Tabloda ikincil sütunlar gizlenir, bilgi ad hücresine taşınır (veri kaybı yok)
• iOS'ta form alanına dokununca otomatik yakınlaştırma engellenir
• Çentikli ekranlar için safe-area desteği

---

Kurulum

Gereksinimler

1. Dosyaları yerleştirin

# XAMPP kullanıyorsanız
cd C:/xampp/htdocs
git clone https://github.com/CilginYazilim/rbac-login-system.git

2. Veritabanını oluşturun

mysql -u root -p < cy_login.sql

veya phpMyAdmin › İçe Aktar › cy_login.sql › Başlat

Dosya cy_login veritabanını kendisi oluşturur; elle açmanıza gerek yoktur.
Tablolar: users, remember_tokens, login_attempts, activity_log.

3. Ayarları yapın

cp .env.example .env      # Windows: copy .env.example .env

.env dosyasını açıp veritabanı bilgilerinizi yazın:

APP_DEBUG=true
APP_PRETTY_URLS=true
DB_HOST=127.0.0.1
DB_NAME=cy_login
DB_USER=root
DB_PASS=

.env yoksa uygulama XAMPP varsayılanlarıyla (root / boş parola) çalışır.

APP_PRETTY_URLS=true temiz adresleri (/login) açar; kökteki .htaccess ve

Apache'de mod_rewrite gerekir. Sunucunuzda yeniden yazma kapalıysa false

yapın — hiçbir kod değişmez, adresler index.php?r=login biçimine döner.

4. Klasör izinleri

upload/ klasörü yazılabilir olmalıdır.

chmod 755 upload    # Linux / macOS

5. Tarayıcıda açın

http://localhost/rbac-login-system/

---

Demo hesaplar

Giriş ekranındaki demo kartlarına tıklayarak formu tek hamlede doldurabilirsiniz.

⚠️ Canlı sunucuda bu hesapları silin veya parolalarını değiştirin.
Giriş ekranındaki demo kartı bloğunu da kaldırın:
views/auth/login.php içindeki $demoAccounts dizisi ve cy-demo bloğu.

---

Klasör yapısı

├── index.php                  ← TEK giriş noktası (front controller)
├── .env.example               ← Ortam değişkeni şablonu
├── cy_login.sql               ← Veritabanı kurulum dosyası
│
├── config/
│   └── config.php             ← Tüm ayarlar tek dizide
│
├── routes/
│   └── web.php                ← Rota tablosu + yetki kuralları
│
├── app/
│   ├── Core/                  ← Çatı sınıfları
│   │   ├── Autoloader.php       Sınıf otomatik yükleyici
│   │   ├── Env.php              .env okuyucu
│   │   ├── Config.php           Nokta notasyonlu ayar erişimi
│   │   ├── Database.php         PDO bağlantısı (tembel tekil)
│   │   ├── Session.php          Sertleştirilmiş oturum
│   │   ├── Csrf.php             Sahte istek koruması
│   │   ├── Auth.php             Kimlik doğrulama
│   │   ├── Middleware.php       Rota öncesi kontroller
│   │   ├── Router.php           İstek yönlendirme
│   │   ├── Request.php          Girdi okuma ve temizleme
│   │   ├── Response.php         JSON / yönlendirme / güvenlik başlıkları
│   │   ├── Validator.php        Form doğrulama
│   │   ├── Uploader.php         Güvenli görsel yükleme
│   │   ├── RateLimiter.php      Kaba kuvvet koruması
│   │   ├── Flash.php            Tek seferlik bildirimler
│   │   └── View.php             Şablon motoru
│   │
│   ├── Models/
│   │   ├── User.php           ← Kullanıcı varlığı (entity)
│   │   └── Role.php           ← Roller ve yetki tablosu
│   │
│   ├── Repositories/
│   │   ├── UserRepository.php            ← users tablosunun TEK kapısı
│   │   ├── RememberTokenRepository.php   ← "Beni hatırla" anahtarları
│   │   └── ActivityRepository.php        ← İşlem günlüğü
│   │
│   ├── Http/
│   │   ├── Controller.php
│   │   └── Controllers/
│   │       ├── HomeController.php       ← Herkese açık tanıtım
│   │       ├── AuthController.php
│   │       ├── DashboardController.php
│   │       ├── UserController.php
│   │       ├── RoleController.php       ← Roller ve yetkiler
│   │       ├── ProfileController.php
│   │       ├── SettingsController.php
│   │       └── Api/
│   │           ├── UserApiController.php        ← AJAX CRUD
│   │           └── PreferenceApiController.php  ← Tema tercihi
│   │
│   └── Support/helpers.php    ← e(), url(), can(), icon() …
│
├── views/
│   ├── layouts/               ← admin · auth · public · plain
│   ├── partials/              ← sidebar · topbar
│   ├── home/ auth/ dashboard/ users/ roles/ profile/ settings/ errors/
│
├── assets/
│   ├── css/  cilginyazilim.css (tasarım kalıbı) · admin.css (panel)
│   └── js/   app.js (kabuk) · users.js (CRUD) · login.js
│
├── docs/screenshots/          ← README'deki ekran görüntüleri
└── upload/                    ← Yüklenen görseller (PHP çalıştırma kapalı)

---

Mimari

İsteğin yolculuğu

Tarayıcı
   │
   ▼
index.php ────────── Autoloader · .env · Config · Session · Güvenlik başlıkları
   │
   ▼
routes/web.php ───── Rota eşleştirme
   │
   ▼
Middleware ───────── auth · csrf · can:users.delete   (başarısızsa DURUR)
   │
   ▼
Controller ───────── Girdiyi al · doğrula · yetkiyi kontrol et
   │
   ▼
Repository ───────── Prepared statement ile veritabanı
   │
   ▼
View / JSON ──────── Ekrana bas veya AJAX yanıtı döndür

Neden bu ayrım?

Tüm SQL'in tek dosyada olması, güvenlik denetimini de tek dosyaya indirir.

Adres yapısı

Varsayılan temiz adrestir; kökteki .htaccess bununla birlikte gelir:

/login
/users
/api/users/list

Sunucunuzda mod_rewrite yoksa .env içinde APP_PRETTY_URLS=false yapın:

index.php?r=users
index.php?r=api/users/list

Bağlantılar url() yardımcısıyla ve mutlak üretilir (Router::basePath()),
bu yüzden proje bir alt klasörde (htdocs/rbac-login-system) de, alan adının kökünde
de aynı şekilde çalışır.

.htaccess içinde bilerek RewriteBase yoktur. Alt klasör kurulumunda
RewriteBase / yazmak, isteği yanlışlıkla htdocs kökündeki index.php'ye
gönderir (XAMPP'ta karşılama sayfasına düşersiniz).

---

Roller ve yetkiler

Yetkiler app/Models/Role.php içinde tek bir tabloda tanımlıdır. Kodda rol adı değil yetki adı kullanılır:

Auth::can('users.delete')           // ✔ doğru
Auth::user()->role === 'admin'      // ✘ kırılgan

Ek iş kuralları

Rol tablosunun üstünde, kazaları ve yetki yükseltmeyi önleyen kurallar vardır:

• Yönetici olmayan biri yönetici hesabını düzenleyemez/silemez
• Kimse kendi rolünü değiştiremez, kendini pasifleştiremez, kendini silemez
• Sistemdeki son aktif yönetici silinemez ve pasifleştirilemez
• Yetkisi olmayan biri form üzerinden role gönderirse değer sessizce yok sayılır

Yeni rol eklemek için Role::ABILITIES dizisine bir satır eklemek ve
cy_login.sql içindeki ENUM değerini genişletmek yeterlidir.

---

Güvenlik önlemleri

Sistem sayfası (yalnızca yönetici) bu önlemlerin kurulumunuzda aktif olup
olmadığını canlı olarak denetler.

---

Yeni sayfa nasıl eklenir?

Üç adım:

1 — Denetleyiciyi yazın · app/Http/Controllers/ReportController.php

namespace App\Http\Controllers;

use App\Core\Request;
use App\Http\Controller;

final class ReportController extends Controller
{
    public function index(Request $request): void
    {
        $this->view('reports/index', [
            'title' => 'Raporlar',
            'total' => $this->users()->countAll(),
        ]);
    }
}

2 — Rotayı tanımlayın · routes/web.php

$router->get('reports', ReportController::class, 'index', ['auth', 'can:reports.view']);

3 — Görünümü oluşturun · views/reports/index.php

<div class="cy-card">
    <div class="cy-card__body">Toplam kullanıcı: <?= (int) $total ?></div>
</div>

Menüde görünmesi için views/partials/sidebar.php içindeki $menu dizisine
bir satır, yetkinin tanınması için app/Models/Role.php içine
'reports.view' eklemeniz yeterlidir.

---

Canlıya alma kontrol listesi

• [ ] .env içinde APP_DEBUG=false
• [ ] Demo hesapları silin; kendi yönetici hesabınızı oluşturun
• [ ] views/auth/login.php içindeki demo kartı bloğunu kaldırın
• [ ] Güçlü bir veritabanı kullanıcısı tanımlayın (root kullanmayın)
• [ ] HTTPS sertifikası kurun (oturum çerezi otomatik secure olur)
• [ ] .env, app/, config/, views/, routes/ tarayıcıdan erişilemez olsun
• [ ] upload/ klasöründe PHP çalıştırma kapalı olsun
• [ ] PHP hata günlüğünü (error_log) bir dosyaya yönlendirin
• [ ] Veritabanı yedeklemesini planlayın
• [ ] Sistem sayfasındaki denetim listesini kontrol edin — hepsi yeşil olmalı

Nginx kullanıyorsanız

.htaccess dosyaları yok sayılır. Sunucu bloğunuza ekleyin:

location ~ ^/(app|config|views|routes)/ { deny all; return 404; }
location ~ /\.               { deny all; return 404; }
location ~ \.(sql|md|log|ini|bak)$ { deny all; return 404; }
location ^~ /upload/         { location ~ \.php$ { deny all; } }

---

Sık karşılaşılan sorunlar

"Veritabanına bağlanılamadı" hatası

.env dosyanızdaki DB_USER / DB_PASS değerlerini kontrol edin.
XAMPP varsayılanı root ve boş paroladır. MySQL servisinin çalıştığından
emin olun.

Giriş yapıyorum ama sürekli giriş ekranına dönüyorum

Oturum klasörü yazılabilir değildir. php.ini içindeki session.save_path
değerini kontrol edin. Ayrıca tarayıcı çerezlerinin açık olduğundan emin olun.

"Çok fazla hatalı deneme" — kendimi kilitledim

DELETE FROM login_attempts;

Süre dolduğunda (varsayılan 15 dakika) kilit kendiliğinden kalkar.

Görsel yükleniyor ama görünmüyor

upload/ klasörünün yazma izni olmalıdır (755). Ayrıca php.ini içindeki
upload_max_filesize ve post_max_size değerleri en az 2 MB olmalıdır.

Türkçe karakterler bozuk görünüyor

Veritabanı ve tablolar utf8mb4_unicode_ci olmalıdır. cy_login.sql bunu
zaten ayarlar; eski bir tabloyu dönüştürmek için:

ALTER TABLE users CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Sayfa stilsiz görünüyor / JS çalışmıyor

Tarayıcı konsolunu açın. Content-Security-Policy hatası görüyorsanız
kendi eklediğiniz satır içi bir `` veya dış CDN bağlantısı olabilir.
Tüm JavaScript ayrı dosyada olmalıdır. Geçici olarak config/config.php
içinden security.csp_enabled değerini false yapabilirsiniz.

Görseller küçültülmüyor

PHP'nin gd eklentisi kurulu değildir. Zorunlu değildir; eklenti yoksa
görsel olduğu gibi kaydedilir, diğer güvenlik kontrolleri yine çalışır.
XAMPP'ta php.ini içinde extension=gd satırını açın.

---

Katkı ve lisans

Katkılara açığız. Depoyu çatallayın (fork), bir dal açın, değişikliğinizi
gönderin. Kod yazarken mevcut üslubu koruyun: **Türkçe açıklamalar,
declare(strict_types=1), katman ayrımına saygı.**

MIT Lisansı — dilediğiniz gibi indirip kullanabilir, değiştirebilir,
ticari projelerinizde kullanabilirsiniz.

cilginyazilim.com ile geliştirildi

Faydalı bulduysanız ⭐ vermeyi unutmayın.