KAL
Menu

Namespace

Deklarasi namespace, impor, dan alias.

Daftar isi

Namespace adalah lingkup bernama yang mengelompokkan kelas di dalam proyek, sehingga dua kelas dengan nama sama dapat hidup berdampingan tanpa saling mengganggu. Topik ini membahas cara mendeklarasikan namespace, penulisan nama lengkap (fully qualified name), impor kelas dengan use, serta pemberian alias ketika nama impornya bertentangan. Setelah membaca, kelas proyek dapat diberi nama yang netral dan pendek, misalnya Tugas atau Laporan, tanpa khawatir bentrok dengan kelas milik pustaka lain.

Mengapa namespace diperlukan#

Nama kelas di PHP bersifat global. Tanpa namespace, seluruh kelas dari seluruh pustaka yang dimuat bersama-sama harus memiliki nama yang berbeda satu sama lain. Keunikan nama pada proyek kecil memang mudah dijaga, tetapi begitu kode pihak ketiga ikut dimuat, peluang dua kelas diberi nama yang sama menjadi besar. Kelas bernama Tugas milik proyek dan kelas Tugas milik pustaka luar tidak dapat dimuat dalam satu program apabila keduanya hidup di lingkup global.

Namespace menyelesaikan masalah tersebut dengan memberi setiap kumpulan kelas alamat tersendiri. Kelas Tugas milik proyek ditempatkan di namespace ArsipKegiatan, sedangkan kelas Tugas milik pihak lain berada di namespace miliknya sendiri. Nama lengkap kelasnya berbeda, yaitu ArsipKegiatan\Tugas berbanding PustakaLain\Tugas, sehingga keduanya dapat dipakai bersama. Nama pendek tetap nyaman dibaca di dalam kode, sedangkan nama lengkap menjamin keunikannya.

Mendeklarasikan namespace#

Deklarasi namespace memakai kata kunci namespace yang ditulis sebagai pernyataan pertama di dalam berkas, tepat setelah declare(strict_types=1);. Satu berkas memuat satu namespace, dan seluruh kelas yang dideklarasikan di dalamnya menjadi anggota namespace tersebut. Nama namespace mengikuti gaya PascalCase per segmen sesuai konvensi PSR (PHP Standard Recommendation), dan sub-namespace ditulis dengan garis miring terbalik, misalnya ArsipKegiatan\Ringkasan.

Dua berkas berikut mendeklarasikan namespace ArsipKegiatan beserta kelas-kelas di dalamnya. Kelasnya bernama netral karena keunikannya sudah dijamin oleh namespace.

php Tugas.php 
<?php

declare(strict_types=1);

namespace ArsipKegiatan;

class Tugas
{
    public function __construct(public string $judul)
    {
    }

    public function label(): string
    {
        return "Tugas arsip: {$this->judul}";
    }
}
php Laporan.php 
<?php

declare(strict_types=1);

namespace ArsipKegiatan;

class Laporan
{
    public function __construct(
        public string $periode,
        public int $jumlahArsip,
    ) {
    }

    public function ringkasan(): string
    {
        return "Laporan {$this->periode}: {$this->jumlahArsip} arsip tercatat";
    }
}

Deklarasi namespace hanya memberi label pada kelas. PHP tidak otomatis memuat berkasnya ketika kelas tersebut digunakan, sehingga berkas di atas masih perlu dimuat dengan require_once atau lewat autoloader sebelum kelasnya dapat diinstansiasi. Mekanisme pemuatan otomatisnya dibahas pada topik autoloading.

Kelas bernama sama di dua namespace#

Dua namespace yang berbeda boleh memuat kelas dengan nama sama. Berkas berikut mendeklarasikan kelas Tugas di namespace KegiatanKantor, berdampingan dengan kelas Tugas milik namespace ArsipKegiatan tanpa bentrok apa pun.

php TugasKantor.php 
<?php

declare(strict_types=1);

namespace KegiatanKantor;

class Tugas
{
    public function __construct(public string $judul)
    {
    }

    public function label(): string
    {
        return "Tugas kantor: {$this->judul}";
    }
}

Ketiga kelas di atas dapat dimuat bersama dalam satu program. Pembedanya ada pada nama lengkapnya: ArsipKegiatan\Tugas dan KegiatanKantor\Tugas adalah dua kelas yang benar-benar berbeda. Inilah manfaat utama namespace, yaitu nama pendek tetap dapat digunakan di dalam kode selama namespace asal kelasnya diketahui.

Impor dengan use, alias, dan nama lengkap#

Menulis nama lengkap pada setiap penggunaan kelas membuat kode menjadi panjang. Pernyataan use mengimpor kelas ke dalam berkas sehingga nama pendeknya dapat dipakai langsung. Apabila dua impor bertabrakan, misalnya ArsipKegiatan\Tugas dan KegiatanKantor\Tugas, kata kunci as memberi alias pada salah satunya. Nama lengkap dengan awalan garis miring terbalik tetap tersedia sebagai alternatif tanpa impor.

php pemakaian.php 
<?php

declare(strict_types=1);

use ArsipKegiatan\Laporan;
use ArsipKegiatan\Tugas;
use KegiatanKantor\Tugas as TugasKantor;

require_once 'Tugas.php';
require_once 'Laporan.php';
require_once 'TugasKantor.php';

$tugas = new Tugas('Backup basis data');
echo $tugas->label(), "\n";

$kantor = new TugasKantor('Rapat evaluasi');
echo $kantor->label(), "\n";

$laporan = new Laporan('November 2026', 42);
echo $laporan->ringkasan(), "\n";

echo Tugas::class, "\n";
echo TugasKantor::class, "\n";
echo \KegiatanKantor\Tugas::class, "\n";
text Keluaran 
Tugas arsip: Backup basis data
Tugas kantor: Rapat evaluasi
Laporan November 2026: 42 arsip tercatat
ArsipKegiatan\Tugas
KegiatanKantor\Tugas
KegiatanKantor\Tugas

Tiga baris terakhir keluaran menegaskan cara resolusi nama. Tugas::class menghasilkan ArsipKegiatan\Tugas karena nama pendeknya diimpor oleh use, TugasKantor::class menghasilkan kelas yang dirujuk oleh alias tersebut, sedangkan \KegiatanKantor\Tugas::class ditulis sebagai nama lengkap tanpa impor sama sekali. Ketiga bentuk tersebut menunjuk kelas yang sama dengan tiga cara yang sah.

Nama global memerlukan awalan backslash#

Di dalam namespace, nama kelas yang ditulis tanpa awalan backslash diselesaikan relatif terhadap namespace berjalan. Nama DateTimeImmutable di dalam namespace ArsipKegiatan berarti ArsipKegiatan\DateTimeImmutable, dan kelas tersebut tidak ada. Kelas global seperti DateTimeImmutable, Exception, atau Throwable harus ditulis dengan awalan backslash, atau diimpor dengan use.

php nama-global.php 
<?php

declare(strict_types=1);

namespace ArsipKegiatan;

var_dump(class_exists('ArsipKegiatan\DateTimeImmutable'));
var_dump(class_exists('\DateTimeImmutable'));

$waktu = new \DateTimeImmutable('2026-11-02');
echo $waktu->format('Y-m-d'), "\n";
text Keluaran 
bool(false)
bool(true)
2026-11-02

Pemeriksaan class_exists() di atas memperlihatkan perbedaannya: kelas DateTimeImmutable di bawah namespace ArsipKegiatan tidak ditemukan, sedangkan nama lengkap dengan awalan backslash menunjuk kelas global yang benar. Fungsi dan konstanta global mempunyai aturan yang lebih longgar karena PHP secara otomatis melakukan fallback ke lingkup global apabila fungsi bernama sama tidak ditemukan di namespace berjalan. Kelas tidak memiliki perilaku fallback tersebut, sehingga penulisan awalan backslash hanya wajib untuk kelas.

Kesalahan umum#

  • Menulis kelas global tanpa awalan backslash di dalam namespace. Pernyataan new DateTimeImmutable(); di dalam namespace berarti new ArsipKegiatan\DateTimeImmutable(); dan menghentikan program dengan error Class not found. Perbaikannya adalah menulis new \DateTimeImmutable(); atau menambahkan use DateTimeImmutable; di awal berkas.
  • Mengira deklarasi namespace memuat berkasnya secara otomatis. namespace hanya melabel kelas, sedangkan pemuatan berkas tetap menjadi tugas require_once atau autoloader. Sampai autoloader dipasang, setiap kelas yang digunakan lintas berkas harus dimuat secara eksplisit.
  • Mencampur kelas dari namespace berbeda dalam satu berkas. Satu berkas sebaiknya memuat satu namespace beserta kelas utamanya, sesuai konvensi satu kelas per berkas. Berkas yang menampung banyak namespace menyulitkan autoloader berbasis pemetaan nama ke berkas.
  • Memberi nama namespace dengan huruf kecil semuanya. PHP menerima nama apa pun, tetapi konvensi PSR menetapkan PascalCase per segmen sehingga arsipkegiatan sulit dibedakan dari ArsipKegiatan oleh pembaca kode. Konsistensi gaya juga membuat pemetaan ke folder pada autoloading tetap sederhana.

Ringkasan#

  • Namespace mengelompokkan kelas di bawah lingkup bernama, sehingga dua kelas bernama sama dapat berdampingan karena nama lengkapnya berbeda.
  • Deklarasi namespace ditulis di awal berkas dan hanya melabel kelas, sedangkan pemuatan berkasnya tetap memerlukan require_once atau autoloader.
  • Pernyataan use mengimpor kelas dengan nama pendek, kata kunci as memberi alias ketika nama impornya bertabrakan, dan nama lengkap dengan awalan backslash sah digunakan tanpa impor.
  • Kelas global seperti DateTimeImmutable dan Exception harus ditulis dengan awalan backslash ketika dirujuk dari dalam namespace.

Referensi#