yii/docs/guide/id/basics.controller.txt

Controller
====================

Sebuah `controller` adalah turunan dari [CController] atau anak kelasnya.
Controller dibuat oleh aplikasi saat pengguna me-request-nya. Ketika berjalan, controller
melakukan action yang di-request yang biasanya memerlukan model
dan membuat view yang sesuai. Sebuah `action`, dalam bentuk paling sederhana sebenarnya
hanyalah metode kelas controller yang namanya dimulai dengan kata `action`.

Controller memiliki action standar. Ketika permintaan pengguna tidak menetapkan
action mana yang dijalankan, action standar yang akan dijalankan. Biasanya
action default dinamai sebagai `index`. Action default bisa diubah dengan menyetel
[CController::defaultAction].

Berikut merupakan code untuk mendefinisikan controller `site`, sebuah action `index` (action
default), dan sebuah action `contact`:

~~~
[php]
class SiteController extends CController
{
	public function actionIndex()
	{
		// ...
	}

	public function actionContact()
	{
		// ...
	}
}
~~~


Route
-----------

Controller dan action diidentifikasi oleh ID. ID Controller dalam
format `path/ke/xyz` sesuai dengan letak file kelas controller di
`protected/controllers/path/ke/XyzController.php`. `xyz`
harus diganti dengan nama sebenarnya (contoh, `post` pada
`protected/controllers/PostController.php`). ID Action adalah nama metode
action tanpa berawalan `action`. Sebagai contoh, jika kelas controller berisi
sebuah metode bernama `actionEdit`, ID dari action tersebut adalah
`edit`.

> Note|Catatan: Sebelum versi 1.0.3, format ID controller adalah `path.ke.xyz`
sedangkan sekarang dalam format `path/ke/xyz`.

Request pengguna terhadap controller dan action tertentu sesuai dengan aturan route.
Route dibentuk dengan menggabungkan ID controller dan ID action yang dipisahkan
dengan garis miring. Sebagai contoh, route `post/edit` merujuk ke `PostController`
dan action `edit`. Dan secara default, URL
`http://hostname/index.php?r=post/edit` akan meminta controller dan
action tersebut.

>Note|Catatan: Secara default, route bersifat case-sensitive. Sejak versi 1.0.1, dimungkinkan
>menjadikan route tidak bersifat case-sensitive dengan mengatur [CUrlManager::caseSensitive]
>menjadi false dalam konfigurasi aplikasi. Ketika dalam mode tidak bersifat case-sensitive,
>pastikan Anda mengikuti konvensi bahwa direktori yang berisi file kelas controller
>dalam huruf kecil, dan [peta controller|CWebApplication::controllerMap]
>serta [peta action|CController::actions] keduanya menggunakan kunci dalam huruf kecil.

Semenjak versi 1.0.3, sebuah aplikasi bisa berisi [module](/doc/guide/basics.module). Route action controller di dalam sebuah module yakni dalam format `moduleID/controllerID/actionID`. Untuk lebih rinci, lihat [bagian mengenai module](/doc/guide/basics.module).


Instansiasi Controller
-------------------

Instance controller dibuat ketika [CWebApplication] menangani request
yang masuk. Berdasarkan ID controller yang diberikan, aplikasi akan
menentukan kelas controller apa dan di mana file kelas ditempatkan, dengan menggunakan
aturan berikut.

   - Jika [CWebApplication::catchAllRequest] ditetapkan, controller
akan dibuat berdasarkan properti ini, dam ID controller yang ditetapkan pengguna
akan diabaikan. Ini dipakai terutama untuk menyimpan aplikasi dalam maintenance
mode dan menampilkan halaman statis pemberitahuan.

   - Jika ID ditemukan dalam [CWebApplication::controllerMap], konfigurasi
controller terkait akan dipakai dalam membuat turunan
controller.

   - Jika ID ada dalam format `'path/ke/xyz'`, nama kelas controller
diasumsikan adalah `XyzController` dan file kelas terkait adalah
`protected/controllers/path/ke/XyzController.php`. Sebagai contoh, ID controller
`admin/user` akan dipecahkan sebagai kelas controller `UserController`
dan file kelas `protected/controllers/admin/UserController.php`.
Jika file kelas tidak ada, 404 [CHttpException] akan dimunculkan.

Dalam hal ketika [modul](/doc/guide/basics.module) dipakai (tersedia sejak versi 1.0.3), proses di atas cukup berbeda. Dalam keadaan tertentu, aplikasi akan memeriksa apakah ID merujuk ke controller di dalam sebuah modul, dan jika demikian, turunan modul akan dibuat lebih dulu diikuti dengan turunan controller.


Action
------------

Seperti yang telah disinggung, action dapat didefinisikan sebagai metode yang namanya dimulai
dengan kata `action`. Cara tingkat mahir adalah dengan mendefinisikan kelas action
dan meminta controller untuk menurunkannya apabila diperlukan. Dengan demikian memungkinkan sebuah action
untuk dipakai ulang.

Untuk mendefinisikan kelas action baru, lakukan hal berikut:

~~~
[php]
class UpdateAction extends CAction
{
	public function run()
	{
		// tempat logika action di sini
	}
}
~~~

Agar controller menyadari adanya action ini, kita override metode
[actions()|CController::actions] pada kelas controller kita:

~~~
[php]
class PostController extends CController
{
	public function actions()
	{
		return array(
			'edit'=>'application.controllers.post.UpdateAction',
		);
	}
}
~~~

Di atas, kita menggunakan alias path
`application.controllers.post.UpdateAction` untuk menetapkan apakah file kelas
action adalah `protected/controllers/post/UpdateAction.php`.

Dengan menulis action berbasis-kelas, kita dapat mengatur aplikasi dalam gaya
modular. Sebagai contoh, struktur direktori berikut dapat dipakai untuk
mengatur kode controller:

~~~
protected/
    controllers/
        PostController.php
        UserController.php
        post/
            CreateAction.php
            ReadAction.php
            UpdateAction.php
        user/
            CreateAction.php
            ListAction.php
            ProfileAction.php
            UpdateAction.php
~~~

Action Parameter Binding
---------------------------------------------------
Semenjak versi 1.1.4, Yii telah menambah dukungan binding (pengikatan) parameter action otomatis,
yakni sebuah action controller dapat mendefinisikan parameter yang nilainya akan secara
otomatis diisi oleh Yii dari nilai `$_GET`.

Untuk menjelaskan fitur ini, mari kita asumsi bahwa kita perlu membuat sebuah action `create`
pada `PostController`. Action ini memerlukan dua buah parameter :

   * `category`: sebuah integer yang menunjukkan ID kategori ke berapa post baru yang
akan dibuat.
   * `language`: sebuah string yang mewakili kode bahasa pada post baru.

Kita mungkin akan menggunakan coding berikut ini untuk mendapatkan nilai yang
diinginkan dari parameter `$_GET`:

~~~
[php]
class PostController extends CController
{
    public function actionCreate()
    {
        if(isset($_GET['category']))
            $category=(int)$_GET['category'];
        else
            throw new CHttpException(404,'invalid request');

        if(isset($_GET['language']))
            $language=$_GET['language'];
        else
            $language='en';

        // ... mulai koding di sini...
    }
}
~~~

Sekarang, dengan menggunakan fitur parameter action, kita bisa mendapatkan hasil sama dengan cara lebih gampang :

~~~
[php]
class PostController extends CController
{
    public function actionCreate($category, $language='en')
    {
        $category=(int)$category;

        // ... mulai koding di sini...
    }
}
~~~

Perhatikan bahwa kita menambahkan dua buah parameter ke metode action `actionCreate`.
Nama parameter ini haruslah sama persis dengan nama yang ingin didapatkan dari `$_GET`. Parameter
`$language` mengambil nilai default `en` apabila ternyata pengguna tidak
memberikan nilai pada parameter. Karena `$category` tidak memiliki nilai default,
maka jika pengguna tidak memberikan parameter `category` di `$_GET`
sebuah [CHttpException](kode kesalahan 400) akan dikeluarkan secara otomatis.

Mulai dari versi 1.1.5, Yii juga akan mendukung pendeteksian jenis array untuk parameter action.
Ini dapat dilakukan dengan PHP type hinting (pemberian petunjuk jenis PHP) dengan menggunakan sintaks berikut :

~~~
[php]
class PostController extends CController
{
	public function actionCreate(array $categories)
	{
		// Yii akan memastikan $categories menjadi sebuah array
	}
}
~~~

Demikianlah, kita menambah kata kunci `array` di depan `$categories` dalam deklarasi
parameter metode tersebut. Dengan melakukan demikian, jika `$_GET['categories']` adalah
sebuah string sederhana, akan diubah menjadi sebuah array yang terdiri dari string tersebut.

> Note|Catatan: Jika sebuah parameter dideklarasi tanpa petunjuk jenis `array`, itu artinya parameter tersebut
> haruslah skalar (seperti non-array). Dalam kasus ini, mem-pass sebuah parameter array dengan
> `$_GET` akan mengakibatkan HTTP exception.


Filter
------

Filter adalah kode yang dikonfigurasi untuk dijalankan sebelum dan/atau
setelah action controller dijalankan. Misalnya, filter kontrol akses
dapat dijalankan guna memastikan bahwa pengguna diotentikasi sebelum menjalankan
action yang diminta; filter kinerja bisa dipakai untuk mengukur waktu
yang diperlukan dalam menjalankan action.

Action bisa memiliki multipel filter. Filter dijalankan dalam urutan seperti
yang terlihat dalam daftar filter. Filter bisa menjaga eksekusi action dan filter
lain yang tidak dieksekusi.

Filter bisa didefinisikan sebagai metode kelas controller. Nama metode harus
dimulai dengan `filter`. Sebagai contoh, keberadaan metode
`filterAccessControl` mendefinisikan sebuah filter bernama `accessControl`. 
Metode filter harus bertanda:

~~~
[php]
public function filterAccessControl($filterChain)
{
	// panggil $filterChain->run() untuk melanjutkan penyaringan dan eksekusi action
}
~~~

di mana `$filterChain` adalah turunan [CFilterChain] yang menggambarkan daftar
filter yang dikaitkan dengan action yang diminta. Di dalam metode filter, kita
dapat memanggil `$filterChain->run()` untuk melanjutkan penyaringan dan jalannya
action.

Filter juga dapat berupa turunan [CFilter] atau anak kelasnya. Kode
berikut mendefinisikan kelas filter baru:

~~~
[php]
class PerformanceFilter extends CFilter
{
	protected function preFilter($filterChain)
	{
		// logika sedang diterapkan sebelum action dieksekusi
		return true; // false jika action tidak dieksekusi
	}

	protected function postFilter($filterChain)
	{
		// logika sedang diterapkan setelah action dieksekusi
	}
}
~~~

Untuk menerapkan filter terhadap action, kita perlu menimpa metode
`CController::filters()`. Metode harus mengembalikan array konfigurasi
filter. Contoh,

~~~
[php]
class PostController extends CController
{
	......
	public function filters()
	{
		return array(
			'postOnly + edit, create',
			array(
				'application.filters.PerformanceFilter - edit, create',
				'unit'=>'second',
			),
		);
	}
}
~~~

Kode di atas menetapkan dua filter: `postOnly` dan `PerformanceFilter`.
Filter `postOnly` berbasis-metode (metode filter terkait sudah didefinisikan
dalam [CController]); sementara filter `PerformanceFilter` berbasis
obyek. Alias path `application.filters.PerformanceFilter`
menetapkan bahwa file kelas filter adalah
`protected/filters/PerformanceFilter`. Kita menggunakan array untuk mengkonfigurasi
`PerformanceFilter` agar ia dapat dipakai guna menginisialisasi nilai
properti obyek filter. Di sini, properti `unit` pada
`PerformanceFilter` akan diinisialisasi sebagai `'second'`.

Dengan menggunakan operator plus dan minus, kita dapat menetapakan action mana
yang harus dan tidak diterapkan oleh filter. Dalam contoh di atas, `postOnly`
harus diterapkan ke action `edit` dan `create`, sementara
`PerformanceFilter` harus diterapkan ke semua action KECUALI `edit` dan
`create`. Jika plus maupun minus tidak muncul dalam konfigurasi filter,
maka filter akan diterapkan ke semua action.

<div class="revision">$Id: basics.controller.txt 2672 2010-11-22 19:13:16Z qiang.xue $</div>