Cara Mencipta dan Menjalankan Projek CakePHP dengan ServBay

ServBay adalah persekitaran pembangunan web tempatan untuk macOS dan Windows yang menyokong pelbagai bahasa seperti PHP, Node.js, Python, Go, dan Java, serta perkhidmatan pangkalan data seperti MySQL, PostgreSQL, MongoDB, dan Redis, bersama pelayan web Caddy atau Nginx. Platform ini memudahkan pembangun untuk membina dan mengurus projek tempatan dengan lebih efisien.

Artikel ini akan membimbing anda langkah demi langkah dalam mencipta, mengkonfigurasi, dan menjalankan projek CakePHP menggunakan persekitaran ServBay. CakePHP ialah salah satu kerangka pembangunan web PHP yang popular, mematuhi corak MVC (Model-View-Controller) dan terkenal dengan kepantasan pembangunannya, ORM yang mantap, serta ciri keselamatan terbina dalam. Dengan gabungan kecekapan ServBay, anda boleh memulakan pembangunan CakePHP dengan pantas.

Apa itu CakePHP?

CakePHP adalah kerangka sumber terbuka untuk pembangunan aplikasi web PHP. Ia menyediakan struktur asas untuk membina aplikasi web yang teratur dengan pantas serta fleksibel. Fokus utama CakePHP adalah “konvensyen lebih utama daripada konfigurasi”, sehingga banyak tugas-tugas pembangunan biasa menjadi lebih mudah.

Ciri-ciri & Kelebihan Utama CakePHP

• Berdasarkan Corak MVC: Struktur kod yang jelas, mudah diselenggara dan dikembangkan.
• Pembangunan Pantas: Menyediakan alatan baris arahan (Bake) untuk penjanaan kod, mempercepatkan aliran kerja.
• ORM Kuat (Object Relational Mapping): Permudahkan interaksi pangkalan data dan menyokong pelbagai sistem DB.
• Keselamatan Terbina: Perlindungan CSRF, pencegahan suntikan SQL, pengesahan input dan banyak lagi ciri keselamatan.
• Enjin Templat Fleksibel: Menyokong pelbagai teknologi lapisan pandangan.
• Komuniti Aktif & Banyak Plugin: Sokongan mudah dicari dan ciri boleh diperluas.
• Dokumentasi Lengkap: Panduan komprehensif dan rujukan API tersedia.

CakePHP sesuai untuk membina pelbagai skala aplikasi web, daripada API ringkas ke sistem perusahaan yang kompleks.

Menyediakan Persekitaran CakePHP dengan ServBay

ServBay menawarkan persekitaran berintegrasi untuk pembangunan CakePHP yang merangkumi:

• PHP interpreter dan pelbagai ekstensi telah dipasang.
• Pengurus pakej Composer tersedia secara lalai.
• Pelayan web (Caddy/Nginx) mudah untuk dikonfigurasikan.
• Perkhidmatan pangkalan data berintegrasi (MySQL, PostgreSQL, Redis dsb).

Dengan ServBay, anda tidak perlu lagi melakukan pemasangan atau konfigurasi manual yang rumit untuk komponen-komponen ini.

Prasyarat

Pastikan anda telah melengkapkan perkara berikut sebelum bermula:

1. Pasang ServBay: Muat turun dan pasang ServBay pada macOS anda.
2. Mulakan Perkhidmatan ServBay: Aktifkan aplikasi ServBay dan pastikan pakej yang diperlukan (contohnya PHP, DB seperti MySQL atau PostgreSQL, cache seperti Redis atau Memcached) telah berjalan. Anda boleh mengurus perkhidmatan ini di tab “Pakej” pada panel kawalan ServBay.
3. Fahami Operasi Asas ServBay: Ketahui cara menambah dan mengkonfigurasi laman web di ServBay. Jika belum familiar, rujuk dahulu Panduan Penggunaan Asas ServBay.

Mencipta Projek CakePHP

ServBay mencadangkan agar semua fail projek web disimpan di direktori /Applications/ServBay/www untuk memudahkan pengesanan dan pengurusan laman web anda.

1. Buka Terminal

   Lancarkan aplikasi terminal pada macOS.

2. Navigasi ke Direktori Root Laman ServBay

   Tukar ke direktori yang disyorkan ServBay:

   cd /Applications/ServBay/www

3. Cipta Direktori Projek

   Cipta subdirektori baharu untuk projek CakePHP anda, contoh nama servbay-cakephp-app:

   mkdir servbay-cakephp-app
   cd servbay-cakephp-app

4. Cipta Projek CakePHP dengan Composer

   Composer telah disertakan dalam ServBay. Dari direktori projek, gunakan Composer untuk membina rangka projek CakePHP:

   composer create-project --prefer-dist cakephp/app .

   Arahan ini akan memuat turun versi stabil terkini dan kebergantungan CakePHP ke direktori semasa (.).

5. Pasang Pemacu ORM (jika menggunakan PostgreSQL)

   Jika anda memilih PostgreSQL, pasang pemacu ORM tambahan:

   composer require cakephp/orm-pgsql

   Jika menggunakan MySQL, pemacu telah tersedia dalam kebergantungan asas CakePHP.

Konfigurasi Awal

Selepas projek dicipta, lakukan beberapa konfigurasi asas khususnya untuk sambungan pangkalan data.

1. Tetapkan Pembolehubah Persekitaran dan Sambungan DB

   Tetapan persekitaran tempatan CakePHP biasanya dalam fail config/app_local.php. Edit fail ini, cari bahagian Datasources, dan kemas kini maklumat sambungan DB. ServBay biasanya menggunakan root sebagai nama pengguna dan password sebagai kata laluan lalai.

   Sebagai contoh, konfigurasi sambungan MySQL:

   // config/app_local.php
   'Datasources' => [
       'default' => [
           'className' => \Cake\Database\Connection::class,
           'driver' => \Cake\Database\Driver\Mysql::class, // atau \Cake\Database\Driver\Postgres::class untuk PostgreSQL
           'persistent' => false,
           'host' => '127.0.0.1', // alamat pelayan DB, ServBay lalai ke tempatan
           //'port' => '3306', // MySQL port lalai 3306, PostgreSQL lalai 5432
           'username' => 'root', // nama pengguna default ServBay
           'password' => 'password', // kata laluan default ServBay
           'database' => 'servbay_cakephp_app', // nama pangkalan data yang anda akan cipta
           'encoding' => 'utf8mb4',
           'timezone' => 'UTC',
           'flags' => [],
           'cacheMetadata' => true,
           'log' => false,
   
           /**
            * Set identifier quoting to true if you are using words like "user" as your table name.
            * But if you are using words like "cake" you can set it to false.
            * If you don't know use true.
            */
           'quoteIdentifiers' => false,
   
           /**
            * Current limitations include the following:
            * - Most drivers do not support setting isolation levels via PDO options.
            *   Using them will result in an error.
            * - Not all drivers support setting the charset via PDO options.
            *   Using them will result in an error.
            * - PDO options are not supported for packaged drivers like Postgres from CakePHP.
            *   For Postgres, you only need to set the encoding.
            */
           'options' => [],
   
           //'url' => env('DATABASE_URL', null), // Aktifkan jika anda gunakan pembolehubah DATABASE_URL
       ],
   ],

   Laraskan driver dan port mengikut jenis pangkalan data yang digunakan (MySQL atau PostgreSQL). Pastikan nama database sepadan dengan yang anda cipta.

Konfigurasi Pelayan Web (Cipta Laman Web dalam ServBay)

Untuk mengakses projek CakePHP melalui pelayar, anda perlu menambah laman web dalam ServBay yang menunjuk ke direktori projek anda.

1. Buka Panel Kawalan ServBay

   Klik ikon ServBay untuk membuka panel kawalan.

2. Navigasi ke Tab “Laman Web”

   Pada panel kawalan, pilih tab “Laman Web” di bar navigasi sebelah kiri (dahulu dipanggil “Host”).

3. Tambah Laman Web Baru

   Klik butang + di bawah untuk menambah laman web baru. Isi maklumat berikut:

   • Nama: Nama pengenalan laman, contoh My CakePHP Dev Site.
   • Domain: Nama domain pembangunan tempatan, contohnya servbay-cakephp-test.local. ServBay akan automatik menunjuk ke tempatan.
   • Jenis Laman: Pilih PHP.
   • Versi PHP: Pilih versi PHP yang sesuai dengan CakePHP anda (contohnya CakePHP 4+ perlukan PHP 7.4+, CakePHP 5+ perlukan PHP 8.1+), misalnya 8.3.
   • Root Dokumen: Penting! Root web pelayan untuk projek CakePHP ialah folder webroot di dalam projek, bukan folder utama projek. Tetapkan ke /Applications/ServBay/www/servbay-cakephp-app/webroot (ganti servbay-cakephp-app jika anda guna nama lain).

4. Simpan dan Terapkan Perubahan

   Selepas isi, klik butang “Simpan” di kanan bawah. ServBay akan meminta pengesahan untuk terapkan perubahan. ServBay secara automatik mengkonfigurasi pelayan web (Caddy atau Nginx) untuk domain anda, dan mengarahkan permintaan ke folder webroot.

Langkah terperinci boleh dirujuk pada dokumentasi ServBay di Tambah Laman Web Pertama.

Semak Tetapan Asas

Kini anda boleh mengakses laman web anda dari pelayar.

Buka pelayar dan kunjungi domain yang anda tetapkan, contohnya https://servbay-cakephp-test.local.

Jika semua berjaya, anda akan nampak halaman sambutan lalai CakePHP. Ini membuktikan PHP, pelayan web, dan tetapan ServBay anda berfungsi.

Integrasi Perkhidmatan Pangkalan Data & Cache

CakePHP dilengkapi dengan lapisan ORM dan cache berkuasa, membolehkan integrasi mudah perkhidmatan DB & cache dari ServBay.

Contoh Pangkalan Data Relasi (MySQL / PostgreSQL)

Contoh berikut akan menunjukkan bagaimana menghubungkan CakePHP dengan DB MySQL atau PostgreSQL dalam ServBay, cipta jadual users, dan operasi CRUD.

1. Cipta Pangkalan Data dalam ServBay

   Sebelum migrasi DB, cipta pangkalan data baru dalam pelayan DB ServBay. Gunakan alat pengurusan DB (phpMyAdmin, pgAdmin, Navicat, DBeaver dsb) sambung ke pelayan (127.0.0.1, user root, password password), dan cipta DB servbay_cakephp_app.

2. Cipta Fail Model ORM

   ORM CakePHP perlukan fail Model untuk jadual DB. Cipta fail UsersTable.php.

   Simpan kod berikut di src/Model/Table/UsersTable.php:

   <?php
   namespace App\Model\Table;
   
   use Cake\ORM\Table;
   use Cake\Validation\Validator; // Jika perlu aturan validasi
   
   class UsersTable extends Table
   {
       /**
        * Initialize method
        *
        * @param array $config The configuration for the Table.
        * @return void
        */
       public function initialize(array $config): void
       {
           parent::initialize($config);
   
           $this->setTable('users'); // Tetapkan nama jadual
           $this->setDisplayField('name'); // Medan paparan lalai
           $this->setPrimaryKey('id'); // Tetapkan primary key
   
           // Untuk timestamp
           // $this->addBehavior('Timestamp');
       }
   
       /**
        * Default validation rules.
        *
        * @param \Cake\Validation\Validator $validator Validator instance.
        * @return \Cake\Validation\Validator
        */
       public function validationDefault(Validator $validator): Validator
       {
           $validator
               ->scalar('name')
               ->maxLength('name', 255)
               ->requirePresence('name', 'create')
               ->notEmptyString('name');
   
           $validator
               ->email('email')
               ->requirePresence('email', 'create')
               ->notEmptyString('email')
               ->add('email', 'unique', ['rule' => 'validateUnique', 'provider' => 'table']); // email mesti unik
   
           return $validator;
       }
   }

3. Cipta Fail Migrasi dengan Bake

   CakePHP mengesyorkan pengurusan struktur DB melalui migrasi. Dari direktori projek (/Applications/ServBay/www/servbay-cakephp-app), cipta fail migrasi untuk jadual users:

   bin/cake bake migration CreateUsers name:string email:string:unique

   Arahan ini mencipta migrasi untuk jadual users dengan medan name dan email (unik).

4. Jalankan Migrasi Pangkalan Data

   Jalankan migrasi untuk cipta jadual di pangkalan data:

   bin/cake migrations migrate

   Selepas berjaya, jadual users akan wujud dalam DB.

5. Semak Konfigurasi Sambungan DB (jika belum)

   Pastikan tetapan Datasources.default dalam config/app_local.php sepadan dengan jenis DB dan maklumat akaun anda.

   • Contoh Konfigurasi MySQL:

     'Datasources' => [
         'default' => [
             'className' => \Cake\Database\Connection::class,
             'driver' => \Cake\Database\Driver\Mysql::class,
             'host' => '127.0.0.1',
             'username' => 'root',
             'password' => 'password',
             'database' => 'servbay_cakephp_app',
             // ... lain-lain
         ],
     ],

   • Contoh Konfigurasi PostgreSQL:

     'Datasources' => [
         'default' => [
             'className' => \Cake\Database\Connection::class,
             'driver' => \Cake\Database\Driver\Postgres::class,
             'host' => '127.0.0.1',
             // 'port' => '5432', // port lalai
             'username' => 'root', // user default ServBay
             'password' => 'password', // password default ServBay
             'database' => 'servbay_cakephp_app',
             // ... lain-lain
         ],
     ],

6. Tambah Contoh Routing & Kaedah Pengawal

   Edit fail config/routes.php untuk tambah routing:

   // config/routes.php
   use Cake\Routing\RouteBuilder;
   use Cake\Routing\Router;
   use Cake\Routing\Route\DashedRoute;
   
   Router::defaultRouteClass(DashedRoute::class);
   
   Router::scope('/', function (RouteBuilder $routes) {
       // ... lain-lain
       $routes->connect('/', ['controller' => 'Pages', 'action' => 'display', 'home']);
   
       // Tambah contoh DB
       $routes->connect('/db-add-user', ['controller' => 'Pages', 'action' => 'dbAddUser']);
       $routes->connect('/db-list-users', ['controller' => 'Pages', 'action' => 'dbListUsers']);
   
       // ... lain-lain
       $routes->fallbacks(DashedRoute::class);
   });

   Edit src/Controller/PagesController.php untuk tambah kaedah operasi DB:

   <?php
   namespace App\Controller;
   
   use Cake\Http\Response;
   use Cake\ORM\TableRegistry;
   use Cake\Datasource\Exception\RecordNotFoundException; // Untuk exception jika rekod tidak dijumpai
   
   class PagesController extends AppController
   {
       /**
        * Displays a view
        *
        * @param array ...$path Path segments.
        * @return \Cake\Http\Response|null
        */
       public function display(...$path): ?Response
       {
           // ... kaedah paparan lalai
           return new Response(['body' => 'Hello ServBay! Ini adalah halaman lalai.']);
       }
   
       /**
        * Contoh DB: Tambah pengguna
        */
       public function dbAddUser(): Response
       {
           $usersTable = TableRegistry::getTableLocator()->get('Users'); // Dapatkan instance jadual Users
   
           // Cipta entiti pengguna baru
           $user = $usersTable->newEntity([
               'name' => 'ServBay Demo User',
               'email' => 'servbay-demo@servbay.test' // Contoh email menggunakan jenama ServBay
           ]);
   
           // Cubaan simpan ke DB
           if ($usersTable->save($user)) {
               return new Response(['body' => 'User berjaya ditambah! ID Pengguna: ' . $user->id]);
           } else {
               // Jika gagal, mungkin kerana validasi atau masalah lain
               $errors = $user->getErrors(); // Dapatkan info ralat validasi
               return new Response(['body' => 'Gagal menambah pengguna. Ralat: ' . json_encode($errors)]);
           }
       }
   
       /**
        * Contoh DB: Senaraikan semua pengguna
        */
       public function dbListUsers(): Response
       {
           $usersTable = TableRegistry::getTableLocator()->get('Users'); // Dapatkan instance jadual Users
   
           // Dapatkan semua pengguna
           $users = $usersTable->find()->all();
   
           // Keluarkan dalam format JSON
           return new Response(['body' => json_encode($users->toArray())]); // Tukarkan Collection ke array
       }
   }

7. Akses Contoh DB

   Buka pelayar anda:

   • Kunjungi https://servbay-cakephp-test.local/db-add-user untuk tambah pengguna baru. Anda akan lihat mesej berjaya.
   • Kunjungi https://servbay-cakephp-test.local/db-list-users untuk senarai pengguna (seorang telah anda tambah tadi).

Dengan langkah ini, projek CakePHP anda berhubung dengan pangkalan data relasi dalam ServBay dan berjaya lakukan operasi ORM asas.

Contoh Perkhidmatan Cache (Memcached / Redis)

CakePHP menawarkan API cache bersatu yang membolehkan anda menggunakan pelbagai enjin cache (contohnya Memcached, Redis). ServBay telah menyediakan ekstensi PHP untuk Memcached dan Redis serta perkhidmatan berkaitan.

Pastikan perkhidmatan Memcached atau Redis sudah aktif di tab “Pakej” panel kawalan ServBay.

1. Konfigurasi Sambungan Cache

   Edit fail config/app_local.php, pada bahagian Cache:

   • Contoh konfigurasi Memcached:

     // config/app_local.php
     'Cache' => [
         'default' => [
             'className' => \Cake\Cache\Engine\MemcachedEngine::class,
             'servers' => ['127.0.0.1:11211'], // alamat & port default Memcached ServBay
             'prefix' => 'servbay_cakephp_',
         ],
         // ... lain-lain konfigurasi
     ],

   • Contoh konfigurasi Redis:

     // config/app_local.php
     'Cache' => [
         'default' => [
             'className' => \Cake\Cache\Engine\RedisEngine::class,
             'host' => '127.0.0.1', // alamat Redis ServBay
             'port' => 6379, // port Redis ServBay
             'password' => null, // isi jika Redis perlukan password
             'database' => 0, // indeks DB Redis
             'prefix' => 'servbay_cakephp_',
         ],
         // ... lain-lain konfigurasi
     ],

   Pilih mana-mana cache yang anda gunakan.

2. Tambah Rout & Method Controller Contoh

   Edit config/routes.php tambah routing untuk cache:

   // config/routes.php
   // ... lain-lain
   $routes->connect('/cache-memcached', ['controller' => 'Pages', 'action' => 'cacheMemcached']);
   $routes->connect('/cache-redis', ['controller' => 'Pages', 'action' => 'cacheRedis']);
   // ... lain-lain

   Edit src/Controller/PagesController.php untuk method cache:

   <?php
   namespace App\Controller;
   
   use Cake\Http\Response;
   use Cake\Cache\Cache; // Import kelas Cache
   // ... lain-lain use
   
   class PagesController extends AppController
   {
       // ... method lain (display, dbAddUser, dbListUsers)
   
       /**
        * Contoh Cache: Memcached
        */
       public function cacheMemcached(): Response
       {
           // Pastikan 'default' cache adalah MemcachedEngine dalam app_local.php
   
           $cacheKey = 'servbay_memcached_test_key';
           $cachedData = Cache::read($cacheKey); // Cuba baca data dari cache
   
           $responseBody = '';
   
           if ($cachedData === false) {
               // Cache miss
               $responseBody = 'Cache miss! Menulis "Hello Memcached!" ke cache.';
               $dataToCache = 'Hello Memcached!';
               Cache::write($cacheKey, $dataToCache, 'default'); // Simpan ke cache Memcached
           } else {
               // Cache hit
               $responseBody = 'Cache hit! Data dari cache: ' . $cachedData;
           }
   
           return new Response(['body' => $responseBody]);
       }
   
       /**
        * Contoh Cache: Redis
        */
       public function cacheRedis(): Response
       {
            // Pastikan 'default' cache adalah RedisEngine dalam app_local.php
   
           $cacheKey = 'servbay_redis_test_key';
           $cachedData = Cache::read($cacheKey); // Cuba baca data dari cache
   
           $responseBody = '';
   
           if ($cachedData === false) {
               // Cache miss
               $responseBody = 'Cache miss! Menulis "Hello Redis!" ke cache.';
               $dataToCache = 'Hello Redis!';
               Cache::write($cacheKey, $dataToCache, 'default'); // Simpan ke Redis
           } else {
               // Cache hit
               $responseBody = 'Cache hit! Data dari cache: ' . $cachedData;
           }
   
           return new Response(['body' => $responseBody]);
       }
   }

3. Akses Contoh Cache

   Buka pelayar:

   • Jika anda guna Memcached, akses https://servbay-cakephp-test.local/cache-memcached. Lawatan pertama akan paparkan “Cache miss”, lepas refresh dapat “Cache hit”.
   • Jika anda guna Redis, akses https://servbay-cakephp-test.local/cache-redis. Paparan pertama “Cache miss”, lepas refresh dapat “Cache hit”.

Ini menunjukkan projek CakePHP anda berjaya berintegrasi dengan cache ServBay.

Perkara Penting

• Maklumat pangkalan data: Nama pengguna dan password lalai ServBay (root/password) hanya untuk persekitaran pembangunan tempatan. Tukar ke yang lebih selamat dalam produksi.
• Root laman web: Pastikan “Root Dokumen” laman web ServBay menunjuk ke folder webroot dalam projek CakePHP, bukan folder utama — ini amalan terbaik CakePHP.
• Keserasian versi PHP: Pastikan versi PHP di ServBay sepadan dengan versi CakePHP. Semak dokumentasi rasmi CakePHP untuk keperluan versi.
• Port ServBay: Jika port default (80, 443) digunakan aplikasi lain, ubah dalam tetapan ServBay, dan boleh ubah fail hosts atau akses dengan nombor port.

Soalan Lazim (FAQ)

• S: Muncul ralat “Page not found” bila akses servbay-cakephp-test.local?
  • J: Semak adakah “Root Dokumen” laman web ServBay betul ke /Applications/ServBay/www/servbay-cakephp-app/webroot.
  • Pastikan pelayan web (Caddy/Nginx) ServBay berjalan.
  • Pastikan fail hosts sistem menghala servbay-cakephp-test.local ke 127.0.0.1 (ServBay urus automatik, tapi kadang perlu semak).
  • Pastikan fail .htaccess atau konfigurasi pelayan web projek CakePHP betul (biasanya webroot/.htaccess telah sesuai).
• S: Sambungan database gagal?
  • J: Semak pelayan DB (MySQL/PostgreSQL) ServBay aktif.
  • Semak konfigurasi sambungan DB dalam config/app_local.php (host, port, username, password, database).
  • Pastikan DB dengan nama servbay_cakephp_app wujud di pelayan.
• S: Arahan Composer (bin/cake) tidak boleh dijalankan?
  • J: Pastikan direktori semasa di terminal ialah root projek CakePHP (/Applications/ServBay/www/servbay-cakephp-app).
  • Pastikan pakej PHP dan Composer dalam ServBay aktif.
  • Pastikan terminal boleh akses arahan php (ServBay biasanya tambah PHP ke PATH). Cuba terminal ServBay atau tambah PATH manual.

Rumusan

Dengan ServBay, anda boleh menyediakan persekitaran pembangunan tempatan dengan pantas untuk projek CakePHP. Integrasi PHP, Composer, pelayan web, dan perkhidmatan pangkalan data yang tersedia telah mempermudahkan proses konfigurasi. Panduan ini membentangkan langkah demi langkah dari penciptaan projek, konfigurasi asas, tetapan pelayan web, hinggalah ke integrasi DB relasi dan servis cache — membantu anda memulakan CakePHP dengan mudah. Manfaatkan kemudahan ServBay dan fokus pada penulisan kod, bukan pada kerumitan persediaan persekitaran.