Tanuljuk meg a Kohana használatát

Találtam pár jól érthető oktató cikket a Kohanáról. Tervezem, hogy lefordítom ezeket, bár így is jól érthetőek.

A dealtaker oldalon:
Kohana PHP 2.3.x Tutorial Part 1
Kohana PHP 2.3.x Tutorial Part II
Kohana PHP Tuturial – Part III

A net tuts+ oldalon:
Kohana: The Swift PHP Framework

$this->db->list_fields('some_table');

Megjegyzés: Calls to these methods will not show up in the information displayed by the profiler library.

list_fields()

Database::list_fields($table) egy tömböt ad vissza mely a mezőket (oszlopokat) tartalmazza.

• Paraméter: string – a tábla neve.

field_data()

Database::list_fields($table) egy tömböt ad, egy bejegyzéssel mezőnként (oszloponként).
Minden bejegyzés egy asszociatív tömb a mező adataival.

• Paraméter: string – a tábla neve.

Megjegyzés: A kulcsok az al-tömbben (és a metaadatok) az adatbázis meghajtó tipusától függenek.
MySQL meghajtó esetén minden altömb a következő kulcsokat tartalmazza:

• Field: A mező (oszlop) neve.
• Type: A mező (oszlop) neve tipusa, pl. “int(10) unsigned”.
• Null: Null érték megengedett a mezőbben? ‘YES’ vagy ‘NO’.
• Key: A mező kulcs tipusa. Lehet üres, vagy ‘PRI’ elsődleges kulcs esetén.
• Default: A mező alapértelmezett értéke.
• Extra: Üres, vagy “auto_increment”.

table_exists()

Database::table_exists($table) igaz vagy hamis értéket ad vissza attól függően, hogy létezik-e a megadott tábla.

• Paraméter: string – a tábla neve.

list_tables()

Database::list_tables() egy tömböt ad vissza az adatbázisban található táblák neveivel.

• nem kell escapelni a < jelet
• szinsémák beállíthatók
• hosszú sorok tördelése letiltható

Használható nyelvek.
Használata:
Csak tedd a kódot a [nyelv] és [/nyelv] jelek közé, hasonlóan a BBCodehoz.

Metódusok

result()

A $query→result() automatikusan elérhető az alapértelmezett értékekkel ha végrehajtasz egy adatbázis lekérdezést a $this→db→get() vagy $this→db→query() utasítással. Általában nem kell ezt a függvényt meghívni, kivéve ha meg szeretnéd változtatni az eredmény formátumát az alapértelmezettről.
Ha meg kell változtatnod az alapértelmezett formátumot, akkor egyszerűen futtasd a $query→result() metódust a következő paraméterekkel:

• Az első paraméterként az, hogy objektumokat (TRUE) vagy tömböket (FALSE) szeretnél használni a lekérdezési eredményben.
• A második paraméter az, hogy milyen tipusú objektumot/tömböt szeretnél használni: Tömböknél használhatsz MYSQL_ASSOC, MYSQL_NUM, vagy MYSQL_BOTH tipust. Objektumoknál megadhatod az osztály nevét és a könyvtárat. For objects, you can specify a class name, and the library will create the specified object, if it exists, otherwise it will create stdObjects.

$query = $this->db->query("SELECT `first_name`, `last_name`, `age` FROM `users`");

foreach ($query as $row) {
   echo $row->first_name;
   echo $row->last_name;
   echo $row->age;
}

$query->result(FALSE);

foreach ($query as $row) {
   echo $row['first_name'];
   echo $row['last_name'];
   echo $row['age'];
}

class CircleObject {
	function area() {
		return $this->radius * $this->radius * 3.14;
	}
}

----

$query = $this->db->query("SELECT `radius` FROM `circles`");
$query->result(TRUE, 'CircleObject');
foreach ($query as $row) {
   echo '<p>'.$row->area().'</p>';
}

Note that the preferred way to iterate through result sets is with the result object. This is not an array, but an object with an internal pointer to return the current row. Ha fizikai? tömb kell eredményként, akkor használd a következő metódust:

result_array()

$query→result_array() a lekérdezési eredményt tömbként adja vissza.
A paraméterek ugyanazok, min a result() esetén.

$query = $this->db->query("SELECT `first_name`, `last_name`, `age` FROM `users`");

foreach ($query->result_array(FALSE) as $row) {
   echo $row['first_name'];
   echo $row['last_name'];
   echo $row['age'];
}

insert_id()

A $query→insert_id() visszaadja az INSERT utasítással beszúrt sor id-jét.

$query = $this->db->query("INSERT");

echo $query->insert_id();
// 15

count()

A $query→count() a lekérdezett adatok számát adja vissza.

$query = $this->db->query("SELECT * FROM table");

echo $query->count();
// 12

Manuálisan is mozgathatod az eredmény mutatót (result pointer) az eredmény objektumok között.
You can also manually move the result pointer around in the result object with the following chainable iterator methods.

next()

A következő elemre mozgatja az eredmény mutatót.

previous()

Az előző elemre mozgatja az eredmény mutatót.

rewind()

A legelső elemre mozgatja az eredmény mutatót.

valid()

Megadja, hogy létező (valid) az aktuális eredmény mutató.

current()

Visszaadja azt a sort, amire az aktuális eredmény mutató mutat.

$query = $this->db->select('title')->from($table)->get();
echo 'First:'.Kohana::debug($query->current()).'<br />';

$query->next();
echo 'Second:'.Kohana::debug($query->current()).'<br />';

$query->next();
echo 'Third:'.Kohana::debug($query->current());

echo '<h3>And we can reset it to the beginning:</h3>';
$query->rewind();
echo 'Rewound:'.Kohana::debug($query->current());

// Chain methods
echo $query->next()->next()->next()->current()->title;

Mire nem képes a query építő?

A query építő nagyon erőteljes eszköz és könnyű használni, de van határa a képességeinek. Ezek a határok főként abból fakadnak, hogy mindent escapel.

1. Matematikai műveletek az adatbázisban: $db→update('pages', array('views' ⇒ 'views+1')). Az escapelés miatt nem működik.
2. Zárójelek támogatása: Ez a lekérdezés nem működik: SELECT * FROM pages WHERE (id = 5) OR (title = “BLAH” AND id = 15), mert a query építő nem képes zárójeleket értelmezni. A jövőbeni változatok támogatni fogják a zárójeleket.
3. Bármilyen adatbázis specifikus funkció, pl. a MySql NOW() függvény ki lesz escapelve. A jövőbeni változatoknál majd ki lehet kapcsolni az automatikus escapelést.
   • A query építő adatbázis szerver függetlenül működik. Bármilyen adatbázis szerver specifikus funkció ezt megsemmisítené.
   • Egyszerűen túl sok funkció kellene támogatni az összes adatbázis szervert, és ezeket mind elleőrizni kellene. Mi a sebességre koncentráltunk a query építő létrehozásakor.
   • Quoting is necessary to allow maximum flexibility for table/column names

Metódusok

select()

A select() metódus beállítja a szelektálandó tábla/táblák mezőneveit a lekérdezéshez.

$db = new Database();
$db->select('id, title');

A fenti példa beállítja, hogy a lekérdezés az `id` és a `title` mezőneveken hajtódjon végre. Ha kihagyod ezt a metódust, akkor a “SELECT *” -ra lesz beállítva a lekérdezés.

$db->select('users.id, pages.title');

Ez a következő lekérdezést generálja: SELECT `users`.`id`, `pages`.`title`.
A mező alias-okat is megadhatod:

$db->select('id as page_id', 'title as page_title');

Ez a következő lekérdezést generálja: SELECT `id` AS `page_id`, `title` AS `page_title`.
Lekérdezés a többszörös adatok elhagyásával (DISTINCT):

$db->select('DISTINCT user')

Ez a következő lekérdezést generálja: SELECT DISTINCT `user`.

from()

A from() metódus beállítja hogy a lekérdezés mely táblából vegye az adatokat. Használhatsz tömböt, vagy vesszővel határolt listát a táblák neveinek megadására.

$db->from('pages');

// OR

$db->from(array('pages', 'users'));

Ez a következő lekérdezést generálja: FROM `pages`, `users`.
Ezenkívűl táblanév aliasokat is használhatsz, mint a select() példájában.

where()

A where() metódus a where feltételt állítja be a lekérdezésben. Használhatsz kulcsot és értéket, vagy egy tömböt ami több kulcsot és értéket tartalmaz.

$db->where('id', 5);
$db->where(array('id' => 5));
$db->where(array('id' => 5, 'title' => 'Demo'));

Az utolsó sor a következő lekérdezést generálja: WHERE `id` = 5 AND `title` = “Demo”.

where not

$db->where(array('id !=' => $some_id));

plusz operátorok

$db->where(array('id >=' => $some_id));
$db->where(array('id <' => $some_id));
// ... etc

orwhere()

Azonos a where() metódussal, csak a részek között vagy kapcsolat van.

$db->orwhere(array('id' => 5, 'title' => 'Demo'));

Ez a következő lekérdezést generálja: WHERE `id` = 5 OR `title` = “Demo”.

like()

Azonos a where() metódussal, csak a like-ot használja.

$db->like('title', 'Demo');

Ez a következő lekérdezést generálja: WHERE `title` LIKE ”%Demo%”.
Ha a % jeleket is meg szeretnéd adnim akkor a FALSE 3. paramétert kell megadnod.

$db->like('title', '%Demo', FALSE);
$db->like('title', 'Demo%', FALSE);

Megadhatsz tömböt is több kulcs/érték párral. Ezek és kapcsolatban állnak.

$db->like(array('title' => 'Demo', 'subtitle' => 'Start'));

Ez a következő lekérdezést generálja: WHERE `title` LIKE ”%Demo%” AND `subtitle` LIKE ”%Start%”.

orlike()

Azonos a like() metódussal, kivéve, hogy a részek vagy kapcsolatban állnak.

$db->orlike(array('title' => 'Demo', 'subtitle' => 'Start'));

Ez a következő lekérdezést generálja: WHERE `title` LIKE ”%Demo%” OR `subtitle` LIKE ”%Start%”.

notlike()

Azonos a like() metódussal, kivéve, hogy NOT LIKE-ként működik.

$db->notlike('title' => 'Demo'); // generates "WHERE `title` NOT LIKE "%Demo%""
$db->notlike(array('title' => 'Demo', 'subtitle' => 'Start')); // generates "WHERE `title` NOT LIKE "%Demo%" AND `subtitle` NOT LIKE "%Start%""

ornotlike()

Azonos a like() metódussal, kivéve, hogy OR NOT LIKE-ként működik.

$db->ornotlike(array('title' => 'Demo', 'subtitle' => 'Start')); // generates "WHERE `title` NOT LIKE "%Demo%" OR `subtitle` NOT LIKE "%Start%""

in()

Egy in() részt tesz a lekérdezésbe. Három paramétere van:

1. A mező, amelynek meg kell egyeznie.
2. Egy tömb vagy string, az értékekkel.
3. Egy logikai, amely jelzi, hogy NOT feltétel legyen

$db->in('title', array(1,2,3,4,5));

Ez a következő lekérdezést generálja: `title` IN ('1','2','3','4','5').

notin()

Azonos az in()-nel, kivéve azt, hogy NOT IN feltételt generál. Használhatod ezt a metódust 2 paraméterrel, vagy az in() metódust 3 paraméterrel.

$db->notin('title', array(1,2,3,4,5));
// or
$db->in('title', array(1,2,3,4,5), TRUE);

Ez a következő lekérdezést generálja: `title` NOT IN ('1','2','3','4','5').

regex()

Ez a metódus keresést valósít meg reguláris kifejezésre. A szintakszisa azonos a like()-kal.

$db->regex('title', 'Demo|Sample');
$db->regex(array('title' => 'Demo|Sample'));

orregex()

Azonos a regex()-szel, csak több feltételt adhatunk meg, vagy kapcsolattal.

notregex()

Azonos a regex()-szel, csak a feltételnek nem megfelelő adatokat adja vissza.

ornotregex()

Azonos a regex()-szel, csak több feltételt adhatunk meg, vagy kapcsolattal és a feltételnek nem megfelelő adatokat adja vissza.

groupby()

Beállítja a lekérdezés GROUP BY részét. Megadható string vagy tömb paramáter.

$db->groupby('title');
$db->groupby(array('title', 'id'));

having()

Beállítja a lekérdezés HAVING részét. A szintakszisa azonos a like()-kal.

$db->having('title', 'Demo');

orhaving()

Azonos a having() metódusal, csak több feltételt adhatunk meg, vagy kapcsolattal.

get()

Végrehajtja az aktuális lekérdezés építő utasítást. 3 paramétere van:

1. A használt tábla neve.
2. A lekérdezési feltétel.
3. Az eltolási érték, ha a LIMIT be van állítva.

Visszaadja az adatbázis RESULT objektumot.

$query = $db->from('pages')->where(array('id >=' => 5))->get();

// This is the same as
$query = $db->where(array('id >=' => 5))->get('pages');

getwhere()

Azonos a get() metódusal, csak 4 paramétert kell megadni.l

1. A használt tábla neve.
2. A WHERE feltétel.
3. A lekérdezési feltétel.
4. Az eltolási érték, ha a LIMIT be van állítva.

A fenti példa egyszerűbben:

$query = $db->getwhere('pages', array('id >=' => 5));

set()

A lekérdezés SET részét állítja be a beszúráshoz. Használható 1 vagy 2 paraméterrel:

$db->set('column', 'value');

// OR

$db->set(array('column' => 'value'));

merge()

Merge lekérdezést. The behavior of this method will change depending on which backend database you are using. MySql-ben például az adatbázisben megkeresi az adott kulcsot, ha létezik, akkor törli a sort, majd beszúrja az új sort. A szintakszisa hasonló az update-hez.

insert()

Adatbázis beszúrást valósít meg. A metódusnak 2 paramétere van:

1. A tábla neve, ahova az adatok beszúrása történik
2. Egy asszociatív tömb a mezőkről és az értékekről

$status = $db->insert('pages', array('title' => 'My new title'));

// count how many rows were inserted
$rows = count($status);

Visszatér a lekérdezési eredménnyel (ugyanaz, mint a Database::query()).
Elhagyható bármely paraméter, ha már be van állítva egy lekérdezés építő metódussal.:

$db->from('pages')->set(array('title' => 'My new title'))->insert();

delete()

Rekordokat töröl az adatbázisból. A metódusnak 2 paramétere van:

1. A tábla neve, ahonnan az adatok törlődnek
2. Egy WHERE feltétel a törlendő rekordokról. Lehet string vagy asszociatív tömb. Lásd a where() metódust.

$status = $db->delete('pages', array('id' => 5));

// count how many rows were deleted
$rows = count($status);

Beállíthatod a táblanevet és a where feltételt hasonlóképp, mint az insert() és az update() esetében.

offset()

Beállítja a lekérdezés kezdetét.

// Start the results at position 10
$db->offset(10);

limit()

A LIMIT részt állítja be a lekérdezésben. Az első paraméter az eredmények száma, amit limitálni szeretnél. A második paraméterrel az offset() álíítható be.

// Limit the query to 15 results
$db->limit(15);

// OR

// Limit the query to 15 results starting at position 10
$db->limit(15, 10);

orderby()

Megadható a lekérdezés rendezettsége.
A metódusnak 2 paramétere van:

1. A mezőnevek, amik alapján rendezni kell (használj tömböt ha több mező kell)
2. A rendezettség megadása (ASC vagy DESC alapesetben ASC)

$db->orderby('title', 'ASC');

Véletlenszerűen rendezetett eredmény:

$db->orderby(NULL, 'RAND()');

Az orderby() metódus ezenkívűl támogatja a több mezőre rendezést, ha paraméterként asszociatív tömböt adsz meg.

$db->orderby( array( 'id' => 'ASC', 'date_created' => 'ASC') );

join()

2 tábla olvaszt össze. Paraméterek:

1. string – Tábla név
2. string vagy tömb – WHERE kulcs vagy kulcs→érték asszociatív tömb.
3. string – WHERE érték
4. string – Join tipus (LEFT, RIGHT, OUTER, INNER, LEFT OUTER, RIGHT OUTER)

// Run query against the (user_roles) table.
$db->from('users_roles');

// Join the roles with (user_roles)
$db->join('roles', 'roles.id', 'users_roles.role_id');

// Execute the query.
$db->get();

count_records()

Lekérdezi a lekérdezésben a rekordok számát. Paraméterek:

1. string – Tábla név
2. tömb – WHERE kulcs→érték asszociatív tömb.

// Count all the users
$count = $db->count_records('users');

// Count banned users
$banned_users_count = $db->count_records('users', array('banned' => 1));

// Or like this
$banned_users_count = $db->where('banned', 1)->count_records('users');

query()l

$db→query($sql) a lekérdező utasítás. Will also connect to the database if it wasn’t connected before. Egy result objektumot ad vissza. Ne escapeeljed a tábla neveket és mást sem!

Példa:

$query = $db->query('SELECT username FROM users');

last_query()

$db→last_query($sql) visszaadja a legutóbbi lekérdezést stringben.
Példa:

$last_query = $db->last_query();

escape()

$db→escape( $value ) visszaadja a $string escapelt változatát. Az escapelt string biztonságosan használható az SQL utasításban.

Néhány példa

A következő példában bemutatjuk, hogyan kell lekérdezni egy adatbázist és lekérni a felhasználóneveket a users táblából.

class User_Controller extends Controller {

    public function listusers(){

        $db=new Database;
        $result= $db->query('SELECT username FROM users');
        echo '<h2>'.$db->last_query().'</h2>';
        echo '<ul>';
        foreach($result as $row) {
            echo '<li>'.$row->username.'</li>';
        }
        echo '</ul>';
    }
}

A kimenet a következő:

<h2>SELECT username FROM users</h2>
<ul>
<li>John</li>
<li>Michael</li>
</ul>

Query Binding

Az adatbázis könyvtár támogatja a Query Binding-et.

Példa:

$query = $db->query('SELECT `username` FROM `users` where `id` = ?', array(12));
// OR
$query = $db->query('SELECT `username` FROM `users` where `id` = ? and `foo` = ?', 12, 'bar');

Ezenkívül használhatod Query Builder részét az adatbázis könyvtárnak.
Miután végrehajtottad a lekérdezést, az eredményt Result formátumban kapod meg.

“Lusta” kapcsolódás

A Kohana nem kapcsolódik automatikusan az adatbázishoz, ha lekérdezést hajtasz végre. This is useful when you employ query or page caching, so you dont use a connection when it isn’t needed.

A kapcsolódás cache

Kohana uses the default behaviors in native php database methods to cache the database connection when using the same database group with multiple database objects.

Több adatbázis használata

A Kohana képes több adatbázishoz kapcsolódni egyidőben, ha a beállításkor adatbázis csoportot adtunk meg.

$db1 = new Database('db1');
$db2 = new Database('db2');

Ahol a db1 és db2 konfigurációs csoportok az adatbázis beállításnál.

$config['default'] = array (
	'benchmark'     => TRUE,
	'persistent'    => FALSE,
	'connection'    => array (
		'type'     => 'mysql',
		'user'     => 'dbuser',
		'pass'     => 'p@ssw0rd',
		'host'     => 'localhost',
		'port'     => FALSE,
		'socket'   => FALSE,
		'database' => 'kohana'
	),
	'character_set' => 'utf8',
	'table_prefix'  => '',
	'object'        => TRUE,
	'cache'         => FALSE,
	'escape'        => TRUE
);

• benchmark – ki és bekapcsolja a benchmarkot
• persistens – a perzisztens (állandó) kapcsolat ki- és bekapcsolása (javasolt a kikapcsolás)
• connection – tömb a kapcsolat paramétereivel vagy egy DSN azonosító a következő formátumban: driver://user:password@server_or_socket/database
• character_set – mely karakterkészlet használandó
• table_prefix – a táblák előtagja
• object – Ha igaz, akkor az adatbázis result objektumot ad viszza, különben tömböt
• cache – lekérdezés gyorsítótárazása igen/nem
• escape – be- vagy kikapcsolja a lekérdezés escape-ezését

Több $config bejegyzés is lehetséges. Mindegyiknek kell egy önálló csoport azonosító.

Rövid példák

Adatbázis előkészítése (initializing)

$db = Database::instance();

// or

$db = Database::instance('groupname');  // "default" is assumed if groupname is not given

Egyszerű lekérdezés

$result = $db->query('SELECT username,password,email FROM users');

foreach ($result as $row) {
    echo $row->username;
    echo $row->password;
    echo $row->email;
}

Rövid példák 2

Ez a példa bemutatja hogyan használd a lekérdezés eredményét a template-ben.

Kontroller:

class Clients_Controller extends Controller {

  public function index() {

    $db = Database::instance();
    $result = $db->query('SELECT name, code FROM clients');

    View::factory('clients')
    ->bind('result', $result)
    ->render(TRUE);
    }
}

Template:

<style>
/*
 * Zebra rows: When CSS3 is done we could simply use:
 *   tr :nth-child(odd) { background-color: #D0D0D0; }
 * but for now we use PHP and CSS
 */

table.db tr { background-color: #F0F0F0; }
table.db tr.odd { background-color: #D0D0D0; }
table.db th { color: #f0f0f0; background-color: #303030; }

</style>
</head>
<body>

<h2>Client List</h2>
<hr/>

<table class="db">
<tr>
	<th>Client</th>
	<th>ID</th>
</tr>
<?php foreach( $result as $row ):?>
<tr><?= text::alternate( '', ' class="odd"' ) ?>
	<td><?= $row->name ?> </td>
	<td><?= $row->code ?> </td>
</tr>
<?php endforeach; ?>
</table>

</body>