Membina & Menjalankan Projek CakePHP dengan ServBay

ServBay adalah persekitaran pembangunan web tempatan yang direka khas untuk macOS, dengan integrasi pelbagai bahasa seperti PHP, Node.js, Python, Go, Java, serta perkhidmatan pangkalan data seperti MySQL, PostgreSQL, MongoDB, dan Redis, digabungkan dengan pelayan web Caddy atau Nginx. Ia menawarkan platform pembangunan yang mudah dan efisien supaya pembangun boleh menyediakan dan mengurus projek tempatan dengan pantas.

Artikel ini akan memandu anda tentang cara membina, mengkonfigurasi dan menjalankan projek CakePHP dengan mudah di dalam persekitaran ServBay. CakePHP adalah rangka kerja pembangunan web PHP popular yang mengikuti corak MVC (Model-View-Controller), terkenal dengan keupayaan pembangunan pantas, ORM yang mantap, dan ciri-ciri keselamatan terbina dalam. Digabungkan dengan kemudahan ServBay, anda boleh memulakan pembangunan CakePHP tanpa kerumitan.

Apa Itu CakePHP?

CakePHP merupakan rangka kerja pembangunan aplikasi web PHP sumber terbuka yang menawarkan struktur asas untuk membangunkan aplikasi web secara pantas dan tersusun tanpa menjejaskan fleksibiliti. Ia mengamalkan prinsip “convention over configuration” untuk menyederhanakan pelbagai tugas pembangunan biasa.

Ciri-ciri & Kelebihan Utama CakePHP

• Berdasarkan Model MVC: Struktur kod yang jelas, mudah disenggara dan dikembangkan.
• Pembangunan Pantas: Menyediakan alat CLI (Bake) untuk menjana kod dan mempercepat aliran kerja pembangunan.
• ORM Mantap (Pemetaan Relasi-Objek): Memudahkan interaksi dengan pangkalan data dan menyokong pelbagai jenis sistem pangkalan data.
• Ciri-ciri Keselamatan Terbina: Perlindungan CSRF, pencegahan suntikan SQL, pengesahan input, dan banyak lagi.
• Enjin Templat Fleksibel: Menyokong pelbagai teknologi pada lapisan pandangan.
• Komuniti Aktif & Pelbagai Plugin: Mudah mendapatkan sokongan bila ada masalah, dan fungsinya boleh diperluas.
• Dokumentasi Lengkap: Rujukan panduan dan API yang terperinci.

CakePHP sesuai untuk membangunkan aplikasi web dari skala kecil (API mudah) hingga sistem perusahaan yang kompleks.

Membina Persekitaran Pembangunan CakePHP di ServBay

ServBay menyokong pembangunan CakePHP dengan menyediakan integrasi perkhidmatan berikut:

• PHP beserta sambungan penting dipra-pasang.
• Composer, pengurus pakej PHP, dipra-pasang.
• Pengurusan pelayan web mudah (Caddy/Nginx).
• Perkhidmatan pangkalan data terbina (MySQL, PostgreSQL, Redis, dan sebagainya).

Dengan ServBay, anda tidak perlu lagi menghabiskan masa memasang dan mengkonfigurasi komponen ini satu per satu.

Prasyarat

Sebelum bermula, pastikan anda telah menyiapkan perkara berikut:

1. Pasang ServBay: Pastikan anda telah memuat turun dan memasang ServBay pada macOS anda.
2. Mulakan ServBay: Jalankan aplikasi ServBay, dan pastikan semua perkhidmatan yang diperlukan (seperti PHP, pangkalan data seperti MySQL/PostgreSQL, dan cache seperti Redis/Memcached) telah diaktifkan. Anda boleh menguruskan perkhidmatan ini melalui tab “Perisian” di panel kawalan ServBay.
3. Fahami Operasi Asas ServBay: Ketahui cara menambah dan mengkonfigurasi laman web dalam ServBay. Jika anda masih baru, anda disarankan membaca Panduan Penggunaan Asas ServBay.

Membina Projek CakePHP

ServBay mencadangkan semua fail projek web anda diletakkan dalam direktori /Applications/ServBay/www bagi memudahkan pengesanan dan pengurusan laman secara automatik.

1. Buka Terminal

   Lancarkan aplikasi Terminal pada macOS anda.

2. Masuk ke Direktori Root Laman ServBay

   Navigasi ke direktori yang disarankan ServBay untuk laman web:

   cd /Applications/ServBay/www

3. Cipta Direktori Projek

   Buat subdirektori baharu untuk projek CakePHP anda. Dalam contoh ini, kita guna nama projek servbay-cakephp-app:

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

4. Cipta Projek CakePHP dengan Composer

   Composer sudah dipasangkan di ServBay. Dalam direktori projek, jalankan:

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

   Perintah ini akan memuat turun versi terkini CakePHP serta segala pergantungan dalam direktori semasa (.).

5. Pasang Pemandu ORM (Jika Menggunakan PostgreSQL)

   Bagi penggunaan pangkalan data PostgreSQL, pasang pemandu tambahan ORM PostgreSQL:

   composer require cakephp/orm-pgsql

   Untuk MySQL, pemandu biasanya sudah tersedia bersama keperluan CakePHP.

Konfigurasi Permulaan

Selepas projek dicipta, beberapa konfigurasi asas perlu dibuat, khususnya berkaitan sambungan pangkalan data.

1. Konfigurasi Persekitaran & Sambungan Pangkalan Data

   Konfigurasi persekitaran tempatan CakePHP tertumpu dalam fail config/app_local.php. Edit fail ini dan cari bahagian Datasources untuk mengisi maklumat sambungan pangkalan data anda. Nama pengguna dan kata laluan lalai ServBay biasanya root dan password.

   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 pangkalan data, lalai di tempatan (localhost)
           //'port' => '3306', // MySQL lalai port 3306, PostgreSQL lalai 5432
           'username' => 'root', // Nama pengguna lalai ServBay
           'password' => 'password', // Kata laluan lalai ServBay
           'database' => 'servbay_cakephp_app', // Nama pangkalan data yang akan anda 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), // Jika guna pemboleh ubah persekitaran DATABASE_URL, nyahkomen baris ini
       ],
   ],

   Sila ubah driver dan tetapan port mengikut jenis pangkalan data yang anda gunakan (MySQL/ PostgreSQL). Pastikan nama database selari dengan pangkalan data yang andal ingin bina.

Konfigurasi Pelayan Web (Cipta Laman Dalam ServBay)

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

1. Buka Panel Kawalan ServBay

   Klik ikon ServBay untuk membuka panel kawalan.

2. Pergi ke Tab “Laman Web”

   Dalam panel kawalan, pilih “Laman Web” pada bar navigasi sebelah kiri.

3. Tambah Laman Baharu

   Klik butang + untuk tambah laman. Isi maklumat berikut:

   • Nama: Nama mudah diingat, contohnya My CakePHP Dev Site.
   • Domain: Tetapkan domain pembangunan tempatan, seperti servbay-cakephp-test.local. ServBay akan automatik menunjuk ke mesin tempatan.
   • Jenis Laman: Pilih PHP.
   • Versi PHP: Pilih yang sesuai (contoh: CakePHP 4+ perlukan PHP 7.4+; CakePHP 5+ perlukan PHP 8.1+; misalnya, 8.3).
   • Dokumen Root: Penting! Direktori root pelayan web untuk CakePHP ialah subdirektori webroot dalam projek anda, jadi letakkan /Applications/ServBay/www/servbay-cakephp-app/webroot (tukar servbay-cakephp-app mengikut nama projek anda).

4. Simpan & Terapkan Perubahan

   Selepas semua maklumat lengkap, klik “Simpan”. ServBay akan minta pengesahan untuk menerapkan perubahan. Ia akan mengkonfigurasi pelayan web (Caddy/Nginx) supaya domain seperti servbay-cakephp-test.local menunjuk ke direktori webroot projek anda.

Langkah lanjut boleh dirujuk pada dokumen ServBay Menambah Laman Web Pertama.

Sahkan Tetapan Asas

Kini, anda boleh mengakses laman tersebut dengan pelayar.

Buka pelayar dan lawat domain yang anda telah tetapkan dalam ServBay, contoh: https://servbay-cakephp-test.local.

Jika semua betul, anda akan melihat halaman sambutan lalai CakePHP, membuktikan pelayan PHP, pelayan web, dan konfigurasi laman ServBay berjalan dengan baik.

Integrasi Pangkalan Data & Perkhidmatan Cache

CakePHP menawarkan ORM dan lapisan abstraksi cache yang mudah untuk diintegrasikan dengan pangkalan data dan cache ServBay.

Contoh Pangkalan Data Relasi (MySQL / PostgreSQL)

Contoh berikut menunjukkan penggunaan ORM CakePHP untuk sambungan dengan MySQL atau PostgreSQL di ServBay, membina jadual users dan operasi CRUD.

1. Cipta Pangkalan Data Dalam ServBay

   Sebelum migrasi, cipta dahulu pangkalan data baru melalui alat pengurusan ServBay (phpMyAdmin untuk MySQL/MariaDB, pgAdmin untuk PostgreSQL, atau alat pihak ketiga seperti Navicat/DBeaver). Sambungkan dengan alamat 127.0.0.1, pengguna root, kata laluan password, dan cipta pangkalan data nama servbay_cakephp_app.

2. Cipta Fail Model ORM

   ORM CakePHP perlukan fail Model untuk setiap jadual. Bina fail UsersTable.php untuk jadual users.

   Simpan kod ini dalam src/Model/Table/UsersTable.php:

   <?php
   namespace App\Model\Table;
   
   use Cake\ORM\Table;
   use Cake\Validation\Validator; // Jika perlukan peraturan pengesahan
   
   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 secara jelas
           $this->setDisplayField('name'); // Tetapkan medan paparan lalai
           $this->setPrimaryKey('id'); // Tetapkan medan utama
   
           // Jika mahu guna fungsi 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']); // Pastikan email unik
   
           return $validator;
       }
   }

3. Bina Fail Migrasi Menggunakan Bake Tool

   Untuk pengurusan struktur pangkalan data yang teratur, gunakan Bake untuk cipta migrasi dalam direktori projek (/Applications/ServBay/www/servbay-cakephp-app):

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

   Ini akan menghasilkan fail migrasi dengan definisi jadual users yang mengandungi medan name (string) dan email (string unik).

4. Jalankan Migrasi Pangkalan Data

   Jalankan migrasi untuk mencipta jadual dalam pangkalan data:

   bin/cake migrations migrate

   Jika berjaya, jadual users baru boleh didapati dalam pangkalan data anda.

5. Periksa Konfigurasi Sambungan Pangkalan Data

   Sahkan bahawa konfigurasi Datasources.default dalam config/app_local.php adalah tepat:

   • Contoh 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',
             // ... konfigurasi lain
         ],
     ],

   • Contoh 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', // Nama pengguna lalai ServBay
             'password' => 'password', // Kata laluan lalai ServBay
             'database' => 'servbay_cakephp_app',
             // ... konfigurasi lain
         ],
     ],

6. Tambah Contoh Route & Fungsi Controller

   Edit fail config/routes.php untuk menambah routes bagi fungsi tambah dan papar pengguna:

   // 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) {
       // ... routes lain
       $routes->connect('/', ['controller' => 'Pages', 'action' => 'display', 'home']);
   
       // Tambah routes contoh database
       $routes->connect('/db-add-user', ['controller' => 'Pages', 'action' => 'dbAddUser']);
       $routes->connect('/db-list-users', ['controller' => 'Pages', 'action' => 'dbListUsers']);
   
       // ... routes lain
       $routes->fallbacks(DashedRoute::class);
   });

   Tambah fungsi ke dalam src/Controller/PagesController.php:

   <?php
   namespace App\Controller;
   
   use Cake\Http\Response;
   use Cake\ORM\TableRegistry;
   use Cake\Datasource\Exception\RecordNotFoundException; // Untuk pengendalian error jika rekod tiada
   
   class PagesController extends AppController
   {
       /**
        * Displays a view
        *
        * @param array ...$path Path segments.
        * @return \Cake\Http\Response|null
        */
       public function display(...$path): ?Response
       {
           // ... fungsi default display
           return new Response(['body' => 'Hello ServBay! Ini adalah halaman lalai.']);
       }
   
       /**
        * Contoh Pangkalan Data: Tambah Pengguna
        */
       public function dbAddUser(): Response
       {
           $usersTable = TableRegistry::getTableLocator()->get('Users'); // Dapatkan instance Users Table
   
           // Cipta entiti pengguna baru
           $user = $usersTable->newEntity([
               'name' => 'ServBay Demo User',
               'email' => 'servbay-demo@servbay.test' // Emel contoh khusus untuk ServBay
           ]);
   
           // Cuba simpan entiti ke pangkalan data
           if ($usersTable->save($user)) {
               return new Response(['body' => 'Pengguna berjaya ditambah! ID Pengguna: ' . $user->id]);
           } else {
               // Gagal simpan - kemungkinan disebabkan pengesahan
               $errors = $user->getErrors(); // Dapatkan error pengesahan
               return new Response(['body' => 'Gagal tambah pengguna. Ralat: ' . json_encode($errors)]);
           }
       }
   
       /**
        * Contoh Pangkalan Data: Papar Semua Pengguna
        */
       public function dbListUsers(): Response
       {
           $usersTable = TableRegistry::getTableLocator()->get('Users'); // Dapatkan instance Users Table
   
           // Dapatkan semua pengguna
           $users = $usersTable->find()->all();
   
           // Paparkan hasil dalam format JSON
           return new Response(['body' => json_encode($users->toArray())]); // Tolak koleksi kepada array
       }
   }

7. Uji Contoh Pangkalan Data

   Buka pelayar:

   • Pergi ke https://servbay-cakephp-test.local/db-add-user untuk tambah pengguna baru. Anda akan lihat mesej kejayaan.
   • Pergi ke https://servbay-cakephp-test.local/db-list-users untuk papar senarai pengguna (termasuk pengguna yang baru ditambah).

Dengan langkah-langkah ini, projek CakePHP anda berjaya dihubungkan ke pangkalan data dalam ServBay, dan operasi asas ORM dapat dijalankan.

Contoh Perkhidmatan Cache (Memcached / Redis)

CakePHP menyediakan API cache seragam supaya mudah bertukar antara enjin cache seperti Memcached atau Redis. ServBay datang siap dengan extension PHP Memcached dan Redis serta perkhidmatan berkaitan.

Pastikan dahulu anda telah mengaktifkan Memcached atau Redis melalui tab “Perisian” di panel kawalan ServBay.

1. Konfigurasi Sambungan Cache

   Edit fail config/app_local.php di 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 Memcached lalai ServBay
             'prefix' => 'servbay_cakephp_', // Awalan cache key
         ],
         // ... konfigurasi cache lain
     ],

   • Contoh Konfigurasi Redis:

     // config/app_local.php
     'Cache' => [
         'default' => [
             'className' => \Cake\Cache\Engine\RedisEngine::class,
             'host' => '127.0.0.1', // Alamat Redis lalai ServBay
             'port' => 6379, // Port Redis lalai
             'password' => null, // Jika Redis dilindungi kata laluan, isikan di sini
             'database' => 0, // Indeks pangkalan data Redis
             'prefix' => 'servbay_cakephp_', // Awalan cache key
         ],
         // ... konfigurasi cache lain
     ],

   Pilih dan sesuaikan mengikut cache yang anda gunakan.

2. Tambah Route & Fungsi Cache

   Edit config/routes.php, tambah routes cache:

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

   Edit src/Controller/PagesController.php, tambah fungsi cache:

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

3. Uji Contoh Cache

   Dalam pelayar:

   • Jika anda mengkonfigurasi Memcached, lawat https://servbay-cakephp-test.local/cache-memcached. Lawatan pertama tunjukkan “Cache miss”, refresh akan tampil “Cache hit”.
   • Jika Redis, lawat https://servbay-cakephp-test.local/cache-redis untuk ujian sama.

Ini membuktikan projek CakePHP anda berjaya menggunakan cache ServBay.

Perkara Penting

• Kredensial Pangkalan Data: Nama pengguna dan kata laluan lalai ServBay (root/password) hanya untuk pembangunan tempatan. Jangan guna untuk persekitaran produksi!
• Root Laman Web: WAJIB tetapkan root laman kepada webroot di dalam projek CakePHP, BUKAN direktori utama projek.
• Keserasian Versi PHP: Pastikan versi PHP di ServBay sepadan dengan keperluan versi CakePHP. Rujuk dokumentasi rasmi CakePHP jika perlu.
• Port ServBay: Jika port lalai ServBay (seperti 80 atau 443) digunakan aplikasi lain, tukar tetapan port dalam ServBay dan sesuaikan hosts atau URL pelawat.

Soalan Lazim (FAQ)

• S: Lawatan ke servbay-cakephp-test.local paparkan ralat "halaman tidak dijumpai"?
  • J: Pastikan root laman web di ServBay betul-betul menunjuk ke /Applications/ServBay/www/servbay-cakephp-app/webroot.
  • Periksa pelayan web (Caddy/Nginx) ServBay berfungsi.
  • Periksa fail hosts sistem jika domain servbay-cakephp-test.local menunjuk ke 127.0.0.1 (ServBay akan set automatik, kadang-kadang perlu disemak).
  • Semak konfigurasi .htaccess (atau fail konfigurasi pelayan web) untuk projek CakePHP (webroot/.htaccess biasanya sudah betul).
• S: Gagal sambung ke pangkalan data?
  • J: Pastikan perkhidmatan pangkalan data (MySQL/PostgreSQL) berjalan di ServBay.
  • Semak maklumat sambungan di config/app_local.php (host, port, nama pengguna, kata laluan, nama pangkalan data).
  • Sahkan pangkalan data servbay_cakephp_app telah dicipta.
• S: Tidak dapat jalankan arahan Composer (bin/cake)?
  • J: Pastikan anda kini dalam direktori root projek CakePHP (/Applications/ServBay/www/servbay-cakephp-app) dalam terminal.
  • Sahkan PHP dan Composer beroperasi dalam ServBay.
  • Periksa jika arahan php boleh ditemui di terminal (ServBay lazimnya tambahkan ke PATH, atau gunakan terminal terbina ServBay/ubah PATH manual).

Rumusan

Dengan ServBay, anda dapat menyediakan persekitaran pembangunan tempatan untuk projek CakePHP di macOS secara efisien. Pra-integrasi PHP, Composer, pelayan web, dan perkhidmatan pangkalan data dalam ServBay memudahkan proses konfigurasi anda. Artikel ini membincangkan langkah demi langkah daripada penciptaan projek, konfigurasi asas, tetapan pelayan web, sehingga integrasi pangkalan data relasi dan servis cache. Anda dapat memulakan pembangunan CakePHP dengan lebih cepat, memberi tumpuan sepenuhnya kepada penulisan kod tanpa sebarang kerumitan tetapan persekitaran.