Cache Panel

Discovery berjalan dengan menelusuri directory dan melakukan reflection terhadap class. Itu wajar pada development tetapi boros jika dilakukan pada setiap production request. Karena itu php artisan panel:cache menjalankan discovery sekali lalu menulis hasilnya ke manifest. Ketika manifest tersedia, discovery sama sekali tidak berjalan: tidak ada filesystem scan, reflection, maupun pekerjaan discovery per request.

Membuat dan membersihkan cache

php artisan panel:cache
# Panels cached: {panels} panels, {n} resources, {n} pages, {n} widgets.

php artisan panel:clear
# Panel manifest cleared.

panel:cache melaporkan total dari seluruh registered panel, sehingga ini menjadi pemeriksaan cepat untuk memastikan panel sudah terdaftar dan discovery menemukan jumlah class yang diharapkan.

Kedua command didaftarkan sebagai hook optimize, sehingga deployment yang sudah menjalankan optimize otomatis mendapatkan keduanya:

php artisan optimize        # config, routes, events, views, panels
php artisan optimize:clear  # and the reverse

panel:clear menganggap manifest yang tidak ada sebagai kondisi sukses. Karena itu command aman dijalankan pada fresh checkout maupun dijalankan dua kali.

Isi manifest

File manifest berada di bootstrap/cache/panels.php, dan path-nya di-resolve melalui app()->bootstrapPath('cache/panels.php'). Aplikasi yang memindahkan bootstrap path tetap menghasilkan cache pada lokasi yang dapat ditemukan oleh optimize:clear.

<?php

// Generated by "php artisan panel:cache". Do not edit.

return array (
  'panels' =>
  array (
    'admin' =>
    array (
      'resources' => array ( 0 => 'App\\Panels\\Admin\\Resources\\Users\\UserResource' ),
      'pages' => array ( 0 => 'App\\Panels\\Admin\\Pages\\AccountsDashboard', /* ... */ ),
      'widgets' => array ( 0 => 'App\\Panels\\Admin\\Widgets\\RecentUsers', /* ... */ ),
    ),
  ),
  'fingerprint' => '…',
);

Manifest hanya menyimpan class name. File ditulis menggunakan var_export, bukan serialization, sehingga dapat disimpan opcache sekaligus tetap terbaca manusia. Penulisan dilakukan ke temporary file lalu dipindahkan ke lokasi final sehingga file setengah tertulis tidak pernah dapat dimuat. List juga diurutkan agar dua machine menghasilkan output byte-identical.

Tidak pernah di-cache: hasil authorization, active state navigation, badge value, record data, widget data, dan unread notification count. Semua data tersebut bergantung pada user dan URL; meng-cache-nya berarti berisiko menyajikan jawaban milik satu user kepada user lain.

Data yang masuk ke manifest

Untuk setiap registered panel, manifest menggabungkan class yang didaftarkan eksplisit dengan class yang ditemukan di discovery path:

$panel
    ->resources([UserResource::class])                       // explicit
    ->discoverResources(app_path('Panels/Admin/Resources')); // discovered

Class yang muncul pada keduanya tetap hanya satu. Entry ResourceConfiguration tidak dimasukkan ke manifest karena merupakan konfigurasi panel yang dievaluasi saat boot. Namun class yang dikonfigurasikan oleh object tersebut tetap terdaftar dari configuration, sehingga tidak perlu ditemukan oleh discovery.

Membaca manifest

Saat membangun registry, PanelManager meminta class setiap panel dari PandaPanel\Cache\PanelManifest:

use PandaPanel\Cache\PanelManifest;

$manifest = app(PanelManifest::class);

PanelManifest::path();          // absolute path to bootstrap/cache/panels.php
$manifest->exists();            // bool
$manifest->for(panel('admin')); // ['resources' => [...], 'pages' => [...], 'widgets' => [...]]

for() mengembalikan entry cache ketika tersedia dan menjalankan discovery jika tidak. Artinya call yang sama bekerja baik pada mode cached maupun uncached. File hanya dibaca sekali per process lalu disimpan di memory.

Dua method tambahan tersedia untuk tooling:

use PandaPanel\Core\PanelRegistry;

$manifest->write(app(PanelRegistry::class));   // build and write, returns the manifest array
$manifest->clear();                            // delete it, returns bool

Warning ketika cache stale

panel:cache menulis fingerprint di samping daftar class: jumlah PHP file di seluruh discovery path dan modification time terbaru. Saat boot, PanelManifest::warnIfStale() menghitung ulang fingerprint dan menulis warning ketika nilainya berubah:

[panel] The cached panel manifest is out of date: the classes under the discovery
paths have changed since `php artisan panel:cache` last ran. Until you run
`php artisan panel:clear`, anything added since then is invisible — no route,
no navigation entry, and no error to say so.

Warning ini diperlukan karena gejalanya sangat sulit ditebak: resource yang ditambahkan setelah cache dibuat hanya tidak terlihat. Tidak ada route, sidebar entry, maupun error.

Pemeriksaan stale hanya berjalan di development — ketika debug mode aktif, atau environment local/testing — dan hanya jika manifest memang ada, yang seharusnya merupakan kondisi tidak umum saat development. Di production, manifest adalah sumber kebenaran dan tidak ada filesystem scan. Biayanya hanya stat per PHP file di discovery path, jauh lebih ringan daripada reflection dan class loading discovery sebenarnya.

use PandaPanel\Cache\DiscoveryFingerprint;

DiscoveryFingerprint::of([panel('admin'), panel('app')]);        // string
DiscoveryFingerprint::isStale([panel('admin')], $recorded);      // bool

isStale() mengembalikan false ketika jawabannya tidak dapat dipastikan — misalnya fingerprint lama tidak tersedia atau path tidak dapat dibaca. Ketidakpastian bukan alasan untuk memberi warning bahwa cache pasti stale.

Posisi dalam deployment

composer install --no-dev --optimize-autoloader
php artisan migrate --force
npm ci && npm run build
php artisan optimize        # includes panel:cache

Buat cache setelah code berada pada posisi final, bukan sebelumnya. Rollback code tanpa membersihkan cache dapat meninggalkan manifest yang merujuk class yang sudah tidak ada; jalankan optimize:clear pada alur rollback untuk menghindarinya.

Catatan

• Menambah resource, page, atau widget setelah cache dibuat membuat class tersebut tidak terlihat sampai panel:clear atau panel:cache berikutnya. Saat development, lebih baik tidak memiliki manifest sama sekali.
• Manifest tidak meng-cache object panel. config/panda-panel.php tetap dibaca pada setiap boot; config:cache adalah mekanisme yang membuat pembacaan config murah.
• Route cache terpisah tetapi saling melengkapi. Route panel menunjuk controller dan bukan closure agar route:cache tetap bekerja.
• Manifest dari versi lama — flat map tanpa key fingerprint — tetap dapat dibaca, sehingga upgrade tidak membutuhkan cache clear hanya agar aplikasi dapat boot.
• Test suite menghapus manifest di antara test yang menulisnya. Suite yang meng-cache panel lalu mendaftarkan fixture panel tidak akan melihat fixture tersebut; ini trap yang sama seperti stale warning di production-like environment.

Lihat juga

• Defining a Panel
• Multi-Panel Applications
• Caching
• Discovery
• panel:cache
• panel:clear
• Panel cache in production
• Production checklist