Bagian 4: Billing dan Subscriptions

CREATE TABLE IF NOT EXISTS plans (
    kode          TEXT    PRIMARY KEY,
    nama          TEXT    NOT NULL,
    harga_bulanan INTEGER NOT NULL CHECK (harga_bulanan >= 0),
    batas_proyek  INTEGER NOT NULL CHECK (batas_proyek >= 1)
);

CREATE TABLE IF NOT EXISTS subscriptions (
    id            INTEGER PRIMARY KEY AUTOINCREMENT,
    tenant_id     INTEGER NOT NULL UNIQUE REFERENCES tenants(id),
    plan_kode     TEXT    NOT NULL REFERENCES plans(kode),
    mulai_pada    TEXT    NOT NULL,
    berakhir_pada TEXT,
    dibuat_pada   TEXT    NOT NULL
);

<?php

declare(strict_types=1);

/**
 * Lapisan akses data untuk tabel plans (katalog paket langganan).
 *
 * Katalog plan adalah data konfigurasi, bukan data milik tenant:
 * seluruh tenant membaca daftar plan yang sama. Karena itu query
 * di sini memang tidak menyaring tenant_id — kebalikan dari
 * repository tabel milik tenant.
 */
final class PlanRepository
{
    public function __construct(private PDO $pdo)
    {
        // PRAGMA foreign_keys berlaku per koneksi; constructor adalah
        // titik yang pasti dilewati setiap kali repository dibuat.
        $this->pdo->exec('PRAGMA foreign_keys = ON');
    }

    /**
     * Daftar seluruh plan, urut harga termurah lebih dulu.
     *
     * Urutan ini siap dipakai halaman harga: plan gratis tampil
     * paling atas sebagai titik masuk, plan berbayar menyusul.
     *
     * @return list<array<string, mixed>> baris: kode, nama, harga_bulanan, batas_proyek
     */
    public function listAll(): array
    {
        return $this->pdo
            ->query('SELECT kode, nama, harga_bulanan, batas_proyek FROM plans ORDER BY harga_bulanan')
            ->fetchAll(PDO::FETCH_ASSOC);
    }

    /**
     * Ambil satu plan berdasarkan kode; null bila tidak ditemukan.
     *
     * @return array<string, mixed>|null
     */
    public function find(string $kode): ?array
    {
        $stmt = $this->pdo->prepare(
            'SELECT kode, nama, harga_bulanan, batas_proyek FROM plans WHERE kode = :kode'
        );
        $stmt->execute(['kode' => $kode]);
        $baris = $stmt->fetch(PDO::FETCH_ASSOC);

        return $baris === false ? null : $baris;
    }
}

<?php
require __DIR__ . '/src/PlanRepository.php';

$pdo = new PDO('sqlite::memory:');
$pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
$pdo->exec('PRAGMA foreign_keys = ON');
$pdo->exec(file_get_contents(__DIR__ . '/../bagian-1-tenant-dan-domain-model/schema.sql'));
$pdo->exec(file_get_contents(__DIR__ . '/migrasi-billing.sql'));

$plans = new PlanRepository($pdo);

echo "Katalog plan:\n";
foreach ($plans->listAll() as $p) {
    echo "  [{$p['kode']}] {$p['nama']} — Rp"
        . number_format((int) $p['harga_bulanan'], 0, ',', '.')
        . "/bulan, batas {$p['batas_proyek']} proyek\n";
}

echo "\nfind('pro'):\n";
var_dump($plans->find('pro'));

echo "\nfind('enterprise'):\n";
var_dump($plans->find('enterprise'));

Katalog plan:
  [free] Gratis — Rp0/bulan, batas 3 proyek
  [pro] Pro Bulanan — Rp149.000/bulan, batas 25 proyek

find('pro'):
array(4) {
  ["kode"]=>
  string(3) "pro"
  ["nama"]=>
  string(11) "Pro Bulanan"
  ["harga_bulanan"]=>
  int(149000)
  ["batas_proyek"]=>
  int(25)
}

find('enterprise'):
NULL

<?php

declare(strict_types=1);

/**
 * Thrown saat operasi billing melanggar batas plan.
 *
 * Dipakai khususnya oleh downgrade(): menurunkan plan ditolak
 * bila penggunaan saat ini melebihi batas plan tujuan.
 */
final class BatasanPlanException extends RuntimeException
{
}

/**
 * Siklus langganan dan gerbang fitur per tenant.
 *
 * Seluruh method yang membaca waktu menerima DateTimeImmutable
 * dari pemanggil ("frozen now"). Tidak ada pemanggilan time()
 * atau date() di dalam class — inilah yang membuat siklus 30 hari,
 * masa tenggang, dan kedaluwarsa dapat diuji deterministik: tes
 * cukup menjalankan waktu ke depan dengan membuat objek waktu
 * baru, bukan menunggu hari berganti.
 *
 * Model status satu tenant pada satu titik waktu:
 * - 'tidak-berlangganan' : tanpa baris subscription -> tier gratis implisit.
 * - 'aktif'              : dalam masa berlaku (atau plan tanpa batas).
 * - 'tenggang'           : lewat masa berlaku, masih dalam MASA_TENGGANG_HARI
 *                          -> baca-saja, penulisan data ditolak.
 * - 'kedaluwarsa'        : lewat masa tenggang -> tier kembali ke batas plan
 *                          gratis; data utuh, penulisan diizinkan selama masih
 *                          di bawah batas gratis.
 */
final class SubscriptionService
{
    /** Panjang periode plan berbayar, dalam hari. */
    public const MASA_AKTIF_HARI = 30;

    /** Masa tenggang baca-saja setelah masa berlaku habis, dalam hari. */
    public const MASA_TENGGANG_HARI = 7;

    /** Zona waktu yang dipakai menyimpan dan membaca seluruh waktu. */
    private const ZONA_WAKTU = 'Asia/Jakarta';

    public function __construct(
        private PDO $pdo,
        private PlanRepository $plans,
    ) {
        $this->pdo->exec('PRAGMA foreign_keys = ON');
    }

    /**
     * Mulai/perbarui langganan tenant ke sebuah plan.
     *
     * Plan gratis (harga 0) tidak memiliki masa berlaku
     * (berakhir_pada NULL); plan berbayar berlaku MASA_AKTIF_HARI
     * hari dihitung dari $now, sehingga memanggil ulang method ini
     * saat masih aktif berarti perpanjangan. Baris lama tenant
     * diperbarui lewat upsert — satu tenant selalu punya tepat
     * satu baris subscription.
     *
     * @return array<string, mixed> baris subscription hasil operasi
     */
    public function subscribe(int $tenantId, string $kodePlan, DateTimeImmutable $now): array
    {
        $plan = $this->plans->find($kodePlan);
        if ($plan === null) {
            throw new InvalidArgumentException(
                "Plan tidak dikenal: '$kodePlan'"
            );
        }

        $mulai = $now->format('Y-m-d H:i:s');
        $berakhir = ((int) $plan['harga_bulanan'] > 0)
            ? $now->modify('+' . self::MASA_AKTIF_HARI . ' days')->format('Y-m-d H:i:s')
            : null;

        $stmt = $this->pdo->prepare(
            'INSERT INTO subscriptions (tenant_id, plan_kode, mulai_pada, berakhir_pada, dibuat_pada)
             VALUES (:tenant_id, :plan_kode, :mulai, :berakhir, :dibuat)
             ON CONFLICT(tenant_id) DO UPDATE SET
                 plan_kode     = excluded.plan_kode,
                 mulai_pada    = excluded.mulai_pada,
                 berakhir_pada = excluded.berakhir_pada,
                 dibuat_pada   = excluded.dibuat_pada'
        );
        $stmt->execute([
            'tenant_id' => $tenantId,
            'plan_kode' => $kodePlan,
            'mulai' => $mulai,
            'berakhir' => $berakhir,
            'dibuat' => $mulai,
        ]);

        return $this->rowByTenant($tenantId);
    }

    /**
     * Status langganan tenant pada titik waktu $now.
     *
     * Lihat daftar empat status pada docblock class. Perbandingan
     * waktu memakai string format 'Y-m-d H:i:s' — format ISO yang
     * urut secara leksikografis — dengan seluruh nilai ditulis
     * pada zona waktu yang sama (ZONA_WAKTU).
     */
    public function status(int $tenantId, DateTimeImmutable $now): string
    {
        $row = $this->rowByTenant($tenantId);
        if ($row === null) {
            return 'tidak-berlangganan';
        }

        if ($row['berakhir_pada'] === null) {
            return 'aktif';
        }

        $sekarang = $now->format('Y-m-d H:i:s');
        if ($sekarang <= $row['berakhir_pada']) {
            return 'aktif';
        }

        $batasTenggang = (new DateTimeImmutable($row['berakhir_pada'], new DateTimeZone(self::ZONA_WAKTU)))
            ->modify('+' . self::MASA_TENGGANG_HARI . ' days')
            ->format('Y-m-d H:i:s');
        if ($sekarang <= $batasTenggang) {
            return 'tenggang';
        }

        return 'kedaluwarsa';
    }

    /**
     * Apakah langganan tenant aktif pada $now?
     *
     * Hanya status 'aktif' yang mengembalikan true — masa tenggang
     * sengaja TIDAK dihitung aktif karena penulisan data harus
     * sudah berhenti di sana.
     */
    public function isActive(int $tenantId, DateTimeImmutable $now): bool
    {
        return $this->status($tenantId, $now) === 'aktif';
    }

    /**
     * Batas jumlah proyek yang berlaku bagi tenant pada $now.
     *
     * Status aktif dan tenggang memakai batas plan yang tercatat;
     * status kedaluwarsa dan tenant tanpa langganan memakai batas
     * plan gratis — data tidak pernah dihapus, hanya pembuatannya
     * yang dibatasi.
     */
    public function batasProyekEfektif(int $tenantId, DateTimeImmutable $now): int
    {
        $status = $this->status($tenantId, $now);

        if ($status === 'aktif' || $status === 'tenggang') {
            $row = $this->rowByTenant($tenantId);
            $plan = $this->plans->find($row['plan_kode']);

            return (int) $plan['batas_proyek'];
        }

        return (int) $this->plans->find('free')['batas_proyek'];
    }

    /**
     * Bolehkah tenant membuat proyek baru pada $now?
     *
     * Dua syarat: bukan sedang berada di masa tenggang (baca-saja),
     * dan jumlah proyek saat ini masih di bawah batas efektif.
     * Tenant tanpa langganan maupun yang kedaluwarsa tetap boleh
     * menulis selama masih di bawah batas plan gratis.
     */
    public function bolehBuatProyek(int $tenantId, DateTimeImmutable $now): bool
    {
        if ($this->status($tenantId, $now) === 'tenggang') {
            return false;
        }

        return $this->jumlahProyek($tenantId) < $this->batasProyekEfektif($tenantId, $now);
    }

    /**
     * Penjelasan mengapa tenant tidak boleh membuat proyek.
     *
     * Mengembalikan null bila pembuatan proyek justru diizinkan;
     * pesan lengkap dengan angka dipakai antarmuka untuk 402/403
     * yang informatif.
     */
    public function alasanBlokir(int $tenantId, DateTimeImmutable $now): ?string
    {
        if ($this->bolehBuatProyek($tenantId, $now)) {
            return null;
        }

        $status = $this->status($tenantId, $now);
        $jumlah = $this->jumlahProyek($tenantId);

        if ($status === 'tenggang') {
            $row = $this->rowByTenant($tenantId);
            return 'Masa tenggang sejak ' . $row['berakhir_pada']
                . ' — data hanya dapat dibaca. Perpanjang langganan untuk membuka kembali penulisan data.';
        }

        $batas = $this->batasProyekEfektif($tenantId, $now);
        $namaPlan = ($status === 'aktif')
            ? $this->plans->find($this->rowByTenant($tenantId)['plan_kode'])['nama']
            : $this->plans->find('free')['nama'];

        return "Batas plan $namaPlan: $batas proyek (saat ini $jumlah)."
            . (($status === 'kedaluwarsa') ? ' Langganan kedaluwarsa — batas dikembalikan ke plan gratis.' : '');
    }

    /**
     * Turunkan langganan tenant ke plan lain yang lebih rendah.
     *
     * Aturan gerbang: tenant dengan jumlah proyek melebihi batas
     * plan tujuan TIDAK boleh menurun — hapus proyeknya lebih dulu.
     * Tanpa aturan ini, downgrade akan meninggalkan tenant dengan
     * lebih banyak proyek daripada batas barunya.
     */
    public function downgrade(int $tenantId, string $kodePlan, DateTimeImmutable $now): void
    {
        $target = $this->plans->find($kodePlan);
        if ($target === null) {
            throw new InvalidArgumentException(
                "Plan tidak dikenal: '$kodePlan'"
            );
        }

        $jumlah = $this->jumlahProyek($tenantId);
        $batas = (int) $target['batas_proyek'];
        if ($jumlah > $batas) {
            throw new BatasanPlanException(
                'Downgrade ditolak: tenant #' . $tenantId . ' memiliki ' . $jumlah
                . ' proyek, batas plan ' . $target['nama'] . ' hanya ' . $batas
                . '. Hapus minimal ' . ($jumlah - $batas) . ' proyek terlebih dahulu.'
            );
        }

        $this->subscribe($tenantId, $kodePlan, $now);
    }

    /**
     * Jumlah proyek milik tenant — query tetap ter-scope tenant_id,
     * konsisten dengan aturan isolasi Bagian 2.
     */
    private function jumlahProyek(int $tenantId): int
    {
        $stmt = $this->pdo->prepare(
            'SELECT COUNT(*) FROM projects WHERE tenant_id = :tenant_id'
        );
        $stmt->execute(['tenant_id' => $tenantId]);

        return (int) $stmt->fetchColumn();
    }

    /**
     * Baris subscription satu tenant; null bila belum berlangganan.
     *
     * @return array<string, mixed>|null
     */
    private function rowByTenant(int $tenantId): ?array
    {
        $stmt = $this->pdo->prepare(
            'SELECT id, tenant_id, plan_kode, mulai_pada, berakhir_pada, dibuat_pada
               FROM subscriptions WHERE tenant_id = :tenant_id'
        );
        $stmt->execute(['tenant_id' => $tenantId]);
        $baris = $stmt->fetch(PDO::FETCH_ASSOC);

        return $baris === false ? null : $baris;
    }
}

<?php
require __DIR__ . '/src/PlanRepository.php';
require __DIR__ . '/src/SubscriptionService.php';

$pdo = new PDO('sqlite::memory:');
$pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
$pdo->exec('PRAGMA foreign_keys = ON');
$pdo->exec(file_get_contents(__DIR__ . '/../bagian-1-tenant-dan-domain-model/schema.sql'));
$pdo->exec(file_get_contents(__DIR__ . '/migrasi-billing.sql'));

$z = fn (string $waktu): DateTimeImmutable
    => new DateTimeImmutable($waktu, new DateTimeZone('Asia/Jakarta'));

$svc = new SubscriptionService($pdo, new PlanRepository($pdo));

// Helper demo: pembuatan proyek tetap menyertakan tenant_id.
function buatProyek(PDO $pdo, int $tenantId, string $nama): void
{
    $stmt = $pdo->prepare('INSERT INTO projects (tenant_id, nama) VALUES (:tenant_id, :nama)');
    $stmt->execute(['tenant_id' => $tenantId, 'nama' => $nama]);
}

$yaTidak = fn (bool $b): string => $b ? 'YA' : 'TIDAK';

echo "== 1) Tenant #1 tanpa langganan (tier gratis implisit) ==\n";
$now = $z('2026-02-01 09:00:00');
echo "status: {$svc->status(1, $now)}, batas: {$svc->batasProyekEfektif(1, $now)}\n";
echo "bolehBuatProyek: ", $yaTidak($svc->bolehBuatProyek(1, $now)), "\n";
buatProyek($pdo, 1, 'Landing Page Lebaran');
echo "buat proyek ke-3 (2 -> 3): diizinkan\n";
echo "buat proyek ke-4? ", $yaTidak($svc->bolehBuatProyek(1, $now)), "\n";
echo "alasan: {$svc->alasanBlokir(1, $now)}\n";

echo "\n== 2) subscribe(1, 'pro', 2026-02-01 09:00) ==\n";
$sub = $svc->subscribe(1, 'pro', $now);
echo "plan: {$sub['plan_kode']}, mulai: {$sub['mulai_pada']}, berakhir: {$sub['berakhir_pada']}\n";
echo "status: {$svc->status(1, $now)}, isActive: ", $svc->isActive(1, $now) ? 'true' : 'false', "\n";
echo "batas efektif: {$svc->batasProyekEfektif(1, $now)}\n";
buatProyek($pdo, 1, 'Kampanye Ramadan');
buatProyek($pdo, 1, 'Desain Kemasan Baru');
echo "buat proyek ke-4 dan ke-5: diizinkan (batas Pro 25)\n";

echo "\n== 3) 2026-03-05 — lewat berakhir 2026-03-03, dalam tenggang 7 hari ==\n";
$tenggang = $z('2026-03-05 09:00:00');
echo "status: {$svc->status(1, $tenggang)}, isActive: ", $svc->isActive(1, $tenggang) ? 'true' : 'false', "\n";
echo "bolehBuatProyek: ", $yaTidak($svc->bolehBuatProyek(1, $tenggang)), "\n";
echo "alasan: {$svc->alasanBlokir(1, $tenggang)}\n";

echo "\n== 4) 2026-03-15 — lewat masa tenggang ==\n";
$kedaluwarsa = $z('2026-03-15 09:00:00');
echo "status: {$svc->status(1, $kedaluwarsa)}\n";
echo "batas efektif: {$svc->batasProyekEfektif(1, $kedaluwarsa)} (kembali ke plan Gratis)\n";
echo "bolehBuatProyek: ", $yaTidak($svc->bolehBuatProyek(1, $kedaluwarsa)), "\n";
echo "alasan: {$svc->alasanBlokir(1, $kedaluwarsa)}\n";

echo "\n== 5) downgrade ke free dengan 5 proyek ==\n";
try {
    $svc->downgrade(1, 'free', $kedaluwarsa);
    echo "downgrade berhasil.\n";
} catch (BatasanPlanException $e) {
    echo "Ditolak: {$e->getMessage()}\n";
}

echo "\n== 6) hapus 2 proyek, downgrade ulang ==\n";
$pdo->exec(
    "DELETE FROM projects WHERE tenant_id = 1 AND nama IN ('Kampanye Ramadan', 'Desain Kemasan Baru')"
);
$svc->downgrade(1, 'free', $kedaluwarsa);
echo "downgrade berhasil — batas efektif: {$svc->batasProyekEfektif(1, $kedaluwarsa)}\n";
echo "status: {$svc->status(1, $kedaluwarsa)}, isActive: ", $svc->isActive(1, $kedaluwarsa) ? 'true' : 'false', "\n";
echo "bolehBuatProyek (3 proyek, batas 3): ", $yaTidak($svc->bolehBuatProyek(1, $kedaluwarsa)), "\n";
$baris = $pdo->query('SELECT COUNT(*) FROM subscriptions WHERE tenant_id = 1')->fetchColumn();
echo "baris subscription tenant #1: $baris\n";

echo "\n== 7) perpanjangan: subscribe ulang 'pro' saat masih berlangganan ==\n";
$sub2 = $svc->subscribe(1, 'pro', $z('2026-02-20 09:00:00'));
echo "mulai: {$sub2['mulai_pada']}, berakhir: {$sub2['berakhir_pada']}\n";
$baris = $pdo->query('SELECT COUNT(*) FROM subscriptions WHERE tenant_id = 1')->fetchColumn();
echo "baris subscription tenant #1 tetap: $baris (upsert, bukan baris baru)\n";

== 1) Tenant #1 tanpa langganan (tier gratis implisit) ==
status: tidak-berlangganan, batas: 3
bolehBuatProyek: YA
buat proyek ke-3 (2 -> 3): diizinkan
buat proyek ke-4? TIDAK
alasan: Batas plan Gratis: 3 proyek (saat ini 3).

== 2) subscribe(1, 'pro', 2026-02-01 09:00) ==
plan: pro, mulai: 2026-02-01 09:00:00, berakhir: 2026-03-03 09:00:00
status: aktif, isActive: true
batas efektif: 25
buat proyek ke-4 dan ke-5: diizinkan (batas Pro 25)

== 3) 2026-03-05 — lewat berakhir 2026-03-03, dalam tenggang 7 hari ==
status: tenggang, isActive: false
bolehBuatProyek: TIDAK
alasan: Masa tenggang sejak 2026-03-03 09:00:00 — data hanya dapat dibaca. Perpanjang langganan untuk membuka kembali penulisan data.

== 4) 2026-03-15 — lewat masa tenggang ==
status: kedaluwarsa
batas efektif: 3 (kembali ke plan Gratis)
bolehBuatProyek: TIDAK
alasan: Batas plan Gratis: 3 proyek (saat ini 5). Langganan kedaluwarsa — batas dikembalikan ke plan gratis.

== 5) downgrade ke free dengan 5 proyek ==
Ditolak: Downgrade ditolak: tenant #1 memiliki 5 proyek, batas plan Gratis hanya 3. Hapus minimal 2 proyek terlebih dahulu.

== 6) hapus 2 proyek, downgrade ulang ==
downgrade berhasil — batas efektif: 3
status: aktif, isActive: true
bolehBuatProyek (3 proyek, batas 3): TIDAK
baris subscription tenant #1: 1

== 7) perpanjangan: subscribe ulang 'pro' saat masih berlangganan ==
mulai: 2026-02-20 09:00:00, berakhir: 2026-03-22 09:00:00
baris subscription tenant #1 tetap: 1 (upsert, bukan baris baru)

aplikasi-saas-multi-tenant/
├── bagian-1-tenant-dan-domain-model/
│   └── schema.sql
└── bagian-4-billing-dan-subscriptions/
    ├── migrasi-billing.sql
    ├── src/
    │   ├── PlanRepository.php
    │   └── SubscriptionService.php
    └── uji-billing.php

php uji-billing.php