Controller

Pendalaman mengenai komponen Controller.

Pengantar

Controller merupakan class PHP yang memegang peranan penting dalam aplikasi berpola MVC karena merupakan komponen utama yang menentukan bagaimana sebuah HTTP request dari user ditangani. Controller dapat memberikan lebih dari satu tindakan sebagai bentuk dari proses request tersebut yang kemudian harus disertai dengan tanggapan dari proses request tersebut.

Controller bertanggung jawab untuk mengendalikan logika dari aplikasi (business-logic) dan bertindak sebagai koordinator antara Model, Presenter dan View. Controller menerima request dari pengguna melalui View yang kemudian data permintaan tersebut diproses dengan bantuan Model lalu mempresentasikannya kembali ke View dengan bantuan Presenter.

Lokasi Controller

Seluruh file Controller harus ditempatkan di dalam direktori khusus dengan nama Controllers. Directory Controllers dapat ditempatkan pada direktori utama aplikasi anda ataupun oleh module-module dari aplikasi anda.

Membuat Controller

Agar lebih mudah memahami pendalaman mengenai Controller, kita akan mempelajarinya melalui sebuah kasus sederhana, yaitu membuat Controller bernama Articles.

Melalui Console

Cara termudah membuat controller pertama kali adalah melalui O2System Console, dengan perintah:

$ php o2system make:controller --name=Articles

Option-option yang tersedia lainnya adalah:

Opsi	Shortcut	Aturan	Keterangan
--name	-n	required	Menentukan nama class dari Controller
--path	-p	optional	Menentukan penempatan di direktori lain, selain direktori default, yaitu app/Controllers/
--namespace	-ns	optional	Menentukan namespace lain, selain namespace default, yaitu App\Controllers

Melalui Editor

Buatlah sebuah file Controller berekstensi php dan simpanlah pada directory Controllers, berisikan kode seperti pada contoh dibawah ini:

Berikut adalah contoh dasar dari penulisan source code sebuah Controller:

/path/to/app/Controllers/Articles.php

<?php
namespace App\Controllers;

use O2System\Framework\Http\Controller;

/**
* Class Articles
*
* @package App\Controllers
*/
class Articles extends Controller
{
    
}

Pola URI Controller

Didalam O2System Framework telah terdapat Router Service yang secara pintar dapat melakukan routing secara otomatis mengarah kepada lokasi Controller aplikasi anda. Pola URI Controller dasar yang dapat dikenali O2System Framework secara mendasar adalah sebagai berikut:

http://example.com/[class]/[method]/[arguments]

Pola URI diatas merupakan pola URI segmentasi, yang apabila diuraikan secara segmentasi adalah sebagai berikut:

Segment (n)	Segment (k)	Segment (v)
1	class	[class]
2	method	[method]
3	arguments	[arguments]

(n) adalah Number, (k) adalah Key, (v) adalah Value

Pola URI untuk mengakses Controller dapat menjadi lebih kompleks, anda dapat mempelajarinya lebih lanjut pada pendalaman mengenai URI dan Router.

Metode Pada Controller

Metode pada Controller merupakan action yang akan dieksekusi ketika Controller diakses melalui URI.

Penulisan Nama Metode Pada Controller

Format penulisan nama metode pada Controller wajib dideklarasikan dengan format camelCase sesuai dengan PSR-1: Basic Coding Standards.

Sedangkan format penulisan pada URI sebaiknya dituliskan dengan format dash sesuai dengan aturan Search Engine Friendly URL.

Contoh:

Jika anda memiliki class Controller dengan nama Tutorial dan metode dengan nama helloWorld, seperti dibawah ini:

Tutorial::helloWorld();

Untuk mengaksesnya URI sebaiknya dituliskan seperti dibawah ini:

http://example.com/tutorial/hello-world

Aturan Dasar Eksekusi Metode Pada Controller

• Apabila pada URI hanya terdapat satu (1) segment saja yaitu segment key class, maka secara otomatis metode yang akan dieksekusi adalah index.

• Apabila metode index atau metode yang dicari tidak terdapat pada Controller maka secara otomatis sistem akan mengeluarkan error 404 - Page Not Found.

• Apabila terdapat metode route maka seluruh permintaan secara otomatis akan dialihkan ke metode route.

• Metode yang dapat diakses hanyalah metode dengan visibility public.

Metode Reserved

Metode __reconstruct

Metode __reconstruct adalah metode yang otomatis dieksekusi setelah Controller di-inisasi oleh sistem, yang berfungsi sebagai tempat untuk menuliskan source code logic tambahan yang biasa kita tuliskan di metode __construct.

Example

<?php
namespace App\Controllers;

use O2System\Framework\Http\Controller;

/**
* Class ControllerClassName
*
* @package App\ControllerClassName
*/
class ControllerClassName extends Controller
{
    public function __reconstruct() 
    {
        $this->middleware('auth');
    }
}

Metode Index

Metode index akan otomatis dieksekusi apabila pada URI hanya terdapat (1) segment yaitu segment key class saja.

Keadaan lain yang akan menyebabkan metode index otomatis dieksekusi adalah apabila anda mendefinisikan index method dapat menerima argumen dan segment key argument terdefinisi nilainya.

Reference

ControllerClassName::index( string $argument = null );

Example

<?php
namespace App\Controllers;

use O2System\Framework\Http\Controller;

/**
* Class ControllerClassName
*
* @package App\ControllerClassName
*/
class ControllerClassName extends Controller
{
    public function index( string $filename = null ) 
    {
        if($filename === 'hello') {
            $this->view->load($fielename);
        }
        
        $this->output->sendError(404);
    }
}

Metode Route

Router method merupakan sebuah metode yang memiliki prioritas tertinggi yang berfungsi untuk melakukan internal routing pada Controller yang berperan sebagai pengambil alih tugas sistem router melalui Controller.

Reference

ControllerClassName::route( string $method, array $arguments = [] );

Name	Type	Requirement	Description
$method	String	Required	Nama metode controller yang akan dipanggil berasal dari key segment method.
$arguments	Array	Optional	Argument-argument yang akan di-passing ke metode controller yang akan dipanggil berasal dari key segment arguments.

Example

<?php
namespace App\Controllers;

use O2System\Framework\Http\Controller;

/**
* Class ControllerClassName
*
* @package App\ControllerClassName
*/
class ControllerClassName extends Controller
{
    public function route($method, array $arguments = []) 
    {
        if(method_exist($this, $method)) {
            return call_user_func_array([$this, $method], $arguments);
        }
        
        $this->output->sendError(404);
    }
}

Mengorganisir Controller Pada Sub-Folders

Ketika kita membangun aplikasi berskala besar akan sangat nyaman untuk melakukan organisir file-file Controller ke dalam sub-folders sesuai peruntukkannya. O2System Framework sudah memfasilitasi anda untuk hal ini.

Hal penting yang harus anda perhatikan adalah nama dari namespace controller anda harus sesuai dengan ketentuan PSR-4: Autoloader seperti contoh file controller dibawah ini:

/path/to/app/Controllers/SubFolders/ControllerClassName.php

<?php
namespace App\Controllers\SubFolders;

use O2System\Framework\Http\Controller;

/**
* Class ControllerClassName
*
* @package App\ControllerClassName
*/
class ControllerClassName extends Controller
{
    
}

Memanggil Service Pada Controller

Pada O2System Framework Controller seluruh service dapat diakses melalui property class Controller dengan menggunakan $this, hal ini dapat dilakukan karena O2System menggunakan pola design pattern Singleton pada Kernel-nya.

Built-in Controllers

Berikut ini adalah daftar Controller yang secara default sudah tersedia pada O2System Framework sesuai dengan peruntukkannya masing-masing:

Error Controller

Controller ini secara default diperuntukkan untuk memberikan respon halaman error, dengan pesan berdasarkan nomor kode error.

Untuk dapat memahami cara kerja dari Controller ini, bukalah browser anda dan ketikkan URL:

http://example.com/error/403

Images Controller

Controller ini secara default diperuntukkan untuk mengakses file-file gambar/image yang tersimpan dalam directory storage/images dan sekaligus sebagai penyedia service manipulasi gambar on-the-fly.

Untuk dapat memahami cara kerja dari Controller ini:

1. Simpan gambar dibawah ini pada path /path/to/storage/images/cars/aventador.jpg

   
2. Bukalah browser anda dan ketikkan URL: http://example.com/images/cars/200x200/aventador.jpg

Secara otomatis gambar Lamborghini Aventador yang anda simpan akan tampil pada ukuran 200x200 pixel pada browser anda.

Pola URI yang dikenali oleh Images Controller:

1. Original Image http://example.com/images/[sub-directory]/[filename]

2. Resize Image http://example.com/images/[sub-directory]/[width]x[height]/[filename]

3. Resize Image by Query Parameter http://example.com/images/[sub-directory]/[filename]?width=[pixel]&height=[pixel]&quality=[percent]&crop=[bool]

   Parameter	Value
   width	(int) pixel size
   height	(int) pixel size
   scale	(int) percentage
   quality	(int) percentage
   crop	(bool) true/false using centre auto crop.

Pages Controller

Controller ini secara default diperuntukkan untuk mengakses file-file PHTML yang terdapat dalam directory Pages.

Untuk memahami cara kerja dari controller ini anda dapat mendalaminya pada bagian mengenai Page.

Restful Controller

Controller ini secara default diperuntukkan sebagai base-controller dari aplikasi restful.

Untuk memahami cara kerja dari controller ini anda dapat mendalaminya pada bagian mengenai Restful.

Storage Controller

Controller ini secara default diperuntukkan untuk mengakses file-file yang tersimpan dalam directory storage dan sekaligus sebagai penyedia service file download.

Untuk dapat memahami cara kerja dari Controller ini:

1. Simpan sebuah file pdf pada path /path/to/storage/files/test.pdf

2. Bukalah browser anda dan ketikkan URL http://example.com/storage/files/test.pdf Secara otomatis file PDF tadi akan langsung ditampilkan sedangkan bila anda mengetikkan URL http://example.com/storage/download/files/test.pdf Maka secara otomatis file PDF tadi akan langsung mengalami proses download file melalui browser.

Pola URI yang dikenali oleh Storage Controller:

1. Original File http://example.com/storage/[sub-directory]/[filename]

2. Download Filehttp://example.com/storage/download/[sub-directory]/[filename]

Websocket Controller

Controller ini secara default diperuntukkan sebagai main-controller dari aplikasi websocket.

Untuk memahami cara kerja dari controller ini anda dapat mendalaminya pada bagian mengenai Websocket.