Zend Framework en Doctrine integreren

Last Modified: November 30, 2008 (13:11), Keywords: Doctrine, PHP, ZendFramework

Dit artikel zal je de vereiste stappen uitleggen om een project met zowel Zend Framework en Doctrine op te zetten. Stap voor stap zullen we een eenvoudige message board applicatie bouwen.

Note: This article has been translated: Dutch (by myself), French (by Fred Blanc), German (by Mario Guenterberg) and Russian (by Oleg Lobach). I cannot guarantee that they are up-to-date, heck I can't even read some of them, but do check them out. Many thanks to the translators!

Voor we beginnen

Ik heb dit artikel zo simpel mogelijk gehouden, maar het is geen inleiding tot beide technologieën. Ik stel voor dat je met ze allebei apart experimenteert vooraleer je ze probeert te combineren. Allebei hebben ze goede documentatie om mee te starten: Zend Framework Quick Start en Doctrine's My First Project. Akra's Zend Framework Tutorial is ook een heel goede inleiding.

Het Zend Framework heeft een use-at-will architectuur. Dit wil zeggen dat je enkel de componenten dient ge gebruiken die je wil. Dit in tegenstelling tot andere frameworks, waar het meer een alles-of-niets keuze is. Deze use-at-will architectuur is geweldig: het laat ons toe om volwaardige Zend Framework applicaties te ontwikkelen, zonder de ZF database abstractie (Zend_Db) te gebruiken. Zend_Db is zeker geen slechte technologie, het sluit echter nog zeer nauw aan bij de onderliggende database (en is dus nogal low-level). Door Doctrine te gebruiken kan je gegevens manipuleren met gewone objecten, zonder je al te veel zorgen te hoeven maken om de database.

Zend Framework geeft je heel wat vrijheid in hoe je je applicaties bouwt. Met andere woorden: het dwingt je geen vaste structuur te volgen. In dit artikel heb ik geprobeerd de voorgestelde standaard structuur nauwgelet te volgen. Dit is echter gewoon een kwestie van smaak.

Laten we beginnen!

Eerst zullen we de standaard project structuur aanmaken en de bibliotheken installeren. Open een file manager en maak een mappenstructuur aan zoals degene die je hieronder ziet. Ik zal het doel van elk van deze mappen zo dadelijk uitleggen.

Basis mappen structuur

Een heleboel mappen, maar de meeste zouden je bekend moeten zijn als je reeds een Zend Framework applicatie gemaakt hebt. Er zijn een paar zaken anders:

application/doctrine/: Deze map bevat alle doctrine gegevens bestanden, zoals sql en yaml schemas, migrations, datadumps, ...
application/models/: Doctrine zal automatisch model files genereren in deze map, welke daarna eenvoudig bruikbaar zijn in jou Zend Framework applicatie.
library/: Normaal zouden we gewoon een kopie van het Zend Framework in de library map plaatsen. Voor deze applicatie hebben we echter twee bibliotheken nodig: Zend Framework en Doctrine. Daarom maken we twee submappen waarin we de bibliotheken zullen installeren.
scripts/: Doctrine komt met een handig command line script, dat we hier zullen plaatsen (zoals in de voorstellen hierboven vermeld).

De volgende stap is Zend Framework en Doctrine installeren. Download de nieuwste versies van de respectievelijke websites en unzip de library (voor ZF) en lib (voor Doctrine) mappen in de mappen die we net aangemaakt hebben. Het resultaat zou er als volgt moeten uitzien:

Zend Framework en Doctrine geïnstalleerd

Tijd om te bootstrappen

Als je je de Zend Framework Quick Start goed herinnert, dan weet je zeker nog dat we een bootstrap.file moeten maken. Dat zullen we nu doen, met een paar wijzigingen om Doctrine te kunnen gebruiken.

Eerst maken we de public/index.php en public/.htaccess bestanden. Start je favoriete editor en kopieer de stukken hieronder (noot: je kan de volledige broncode ook verkrijgen via git, zie de appendix onderaan voor meer details):

public/index.php

<?php
require '../application/bootstrap.php';

public/.htaccess

RewriteEngine on 
RewriteCond %{SCRIPT_FILENAME} !-f
RewriteRule ^(.*)$ index.php/$1

Zoals je kan zien zijn deze hetzelfde als elke andere Zend Framework applicatie. Het application/bootstrap.php bestand ziet er ietwat anders uit. Ik heb het opgesplitst in twee bestanden: application/bootstrap.php en application/global.php. Het eerste handelt alle verzoeken af, het tweede zorgt dat de vereiste bestanden gelanden zijn. Ik heb deze bestanden opgesplitst omdat de code van global.php ook vereist is in het Doctrine command line script (dat we zo dadelijk zullen bekijken).

application/global.php

<?php
error_reporting(E_ALL | E_STRICT);
ini_set('display_startup_errors', 1);
ini_set('display_errors', 1);
date_default_timezone_set('Europe/Brussels');
 
/*
 * Setup libraries & autoloaders
 */
set_include_path(dirname(__FILE__).'/../library/zendframework' 
        . PATH_SEPARATOR . dirname(__FILE__).'/../library/doctrine'
        . PATH_SEPARATOR . dirname(__FILE__).'/models'
        . PATH_SEPARATOR . dirname(__FILE__).'/models/generated'
        . PATH_SEPARATOR . get_include_path());
require 'Zend/Loader.php';
Zend_Loader::registerAutoload('Zend_Loader');
 
/*
 * Set super-global data
 */
Doctrine_Manager::connection("mysql://user:pass@localhost/database");
 
/*
 * Configure Doctrine
 */
Zend_Registry::set('doctrine_config', array(
        'data_fixtures_path'  =>  dirname(__FILE__).'/doctrine/data/fixtures',
        'models_path'         =>  dirname(__FILE__).'/models',
        'migrations_path'     =>  dirname(__FILE__).'/doctrine/migrations',
        'sql_path'            =>  dirname(__FILE__).'/doctrine/data/sql',
        'yaml_schema_path'    =>  dirname(__FILE__).'/doctrine/schema'
        ));

application/bootstrap.php

require dirname(__FILE__).'/global.php';
 
Zend_Controller_Front::run(dirname(__FILE__).'/controllers');

We zullen dit even stap voor stap overlopen:

error_reporting(E_ALL | E_STRICT);
ini_set('display_startup_errors', 1);
ini_set('display_errors', 1);
date_default_timezone_set('Europe/Brussels');

Het is altijd een goed idee om error handling en een tijdzone in te stellen. Niets speciaal hier.

/*
 * Setup libraries & autoloaders
 */
set_include_path(dirname(__FILE__).'/../library/zendframework' 
        . PATH_SEPARATOR . dirname(__FILE__).'/../library/doctrine'
        . PATH_SEPARATOR . dirname(__FILE__).'/models'
        . PATH_SEPARATOR . dirname(__FILE__).'/models/generated'
        . PATH_SEPARATOR . get_include_path());
require 'Zend/Loader.php';
Zend_Loader::registerAutoload('Zend_Loader');

Hier sluiten we Doctrine aan. Zoals je kan zien stellen we het include path in zodat het zowel Zend Framework als Doctirne bevat. We voegen ook de mappen waar Doctrine de model files zal genereren toe. Merk op dat we de Doctrine autoloader niet hoeven in te stellen. De Zend Loader gebruiken werkt evengoed, zolang we het include_path maar goed instellen. Opgelet: in de ZF releases voor 1.8 is er een bug aanwezig wat ervoor zorgt dat er (onschuldige) warnings getoond worden wanneer je Doctrine Class Templates gebruikt. Dit gaat opgelost worden zodra versie 1.8 released is (de fix zit reeds in Subversion).

/*
 * Set super-global data
 */
Doctrine_Manager::connection("mysql://user:pass@localhost/database");
 
/*
 * Configure Doctrine
 */
Zend_Registry::set('doctrine_config', array(
        'data_fixtures_path'  =>  dirname(__FILE__).'/doctrine/data/fixtures',
        'models_path'         =>  dirname(__FILE__).'/models',
        'migrations_path'     =>  dirname(__FILE__).'/doctrine/migrations',
        'sql_path'            =>  dirname(__FILE__).'/doctrine/data/sql',
        'yaml_schema_path'    =>  dirname(__FILE__).'/doctrine/schema'
        ));

Dit laatste stuk code heeft twee taken. Om te beginnen stelt het de database connectie in. Om het simpel te houden heb ik gewoon een string waarde hardcoded opgegeven. In een echter systeem wil je echter iets als Zend_Config gebruiken. Dat laat ik als oefening. Vervolgens stelt het de paden in voor de Doctrine command line tool (die de code en database schemas genereert). Ik sla deze array op in het Zend_Registry, wat een generieke methode is om objecten op te slaan, die je op een later punt tijdens de uitvoering weer kan opvragen.

Verander de regel die de Doctrine connectie instelt zodat ze jouw systeemconfiguratie volgt. Dit dient naar een lege database te verwijzen. We zullen deze later vullen met tabellen.

Het application/bootstrap.php bestand zou geen verrassingen mogen bevatten. Nogmaals, ik heb het voorbeeld zo simpel mogelijk gehouden.

Als laatste configureren we de Doctrine command line interface:

scripts/doctrine-cli

#!/usr/bin/env php
<?php
require dirname(__FILE__).'/../application/global.php';
 
$cli = new Doctrine_Cli(Zend_Registry::get('doctrine_config'));
$cli->run($_SERVER['argv']);

Maak dit script uitvoerbaar: chmod +x scripts/doctrine-cli en je bent helemaal klaar om te beginnen.

Een applicatie bouwen

Nu we de basis code hebben gaan we een simpele applicatie bouwen die Zend Framework en Doctrine gebruikt. We gaan een simpele boodschappen muur bouwen, een plaats waar gebruikers berichten kunnen plaatsen en berichten van anderen kunnen lezen.

We gaan het heel simpel houden: slechts 1 controller en 1 view script. Je hebt volgende bestanden nodig:

application/views/scripts/index/index.phtml

<html>
<head>
    <title>ZF & Doctrine example</title>
</head>
 
<body>
<h1>Submit a message:</h1>
<?=$this->form?>
 
<hr />
<h1>Messages posted:</h1>
<!-- TODO: Show messages here -->
</body>
</html>

application/controllers/IndexController.php

<?php
class IndexController extends Zend_Controller_Action
{
    public function indexAction()
    {
        $form = $this->getForm();
        $req = $this->getRequest();
        if ($req->getPost() && $form->isValid($req->getPost())) {
            // TODO: Insert message into database
        }
        $this->view->form = $form;
 
        // TODO: Retrieve all messages.
    }
 
    private function getForm()
    {
        $form = new Zend_Form();
        $form->addElement('text', 'name', array(
                    'label' => 'Your name',
                    'required' => true
                    ));
        $form->addElement('textarea', 'message', array(
                    'label' => 'Message',
                    'required' => true,
                    'rows' => 4
                    ));
        $form->addElement('submit', 'send');
        return $form;
    }
}
?>

Zoals je kan zien zijn er nog drie grote TODO items: een in het view script en twee in de controller. Op deze plaatsen gaan we Doctrine aansluiten. Maar om dat te doen moeten we eerst enkele data objecten definiëren. We keren later terug naar de controller en het view script, maar eerst gaan we het database schema maken.

Het database schema definiëren

Doctrine laat je toe om je database structuur te beschrijven in YAML bestanden, een simpele tekstuele voorstelling. We zullen dit gebruiken en de PHP bestanden automatisch laten genereren. Ik heb het volgende schema gedefinieerd:

application/doctrine/schema/schema.yml

---
Message:
    columns:
        id:
            primary: true
            autoincrement: true
            type: integer(4)
        posted:
            type: timestamp
        name:
            type: string(255)
        message:
            type: string

In deze applicatie hebben we maar een simpel object nodig: Message, met vier kolommen: de verplichte unieke ID, een tijdveld dat aangeeft wanneer het bericht geplaatst is, de naam van de schrijver en het bericht zelf.

We kunnen nu de doctrine command line gebruiken om de model files en de database tabellen te maken. Voer volgende commandos uit op de commandline:

$ ./scripts/doctrine-cli generate-models-yaml
generate-models-yaml - Generated models successfully from YAML schema
$ ./scripts/doctrine-cli generate-sql
generate-sql - Generated SQL successfully for models
$ ./scripts/doctrine-cli create-tables
create-tables - Created tables successfully

Als alles goed ging worden er geen fouten weergegeven. Indien dit wel het geval was, controleer dan of je database verbinding juist ingesteld is.

Alles samenvoegen

Nu gaan we de laatste stukjes TODO aanpakken. We zullen ze stap voor stap vervangen. De volledige code voor de afgewerkte bestanden is onderaan het artikel te vinden. Eerst zullen we code toevoegen om een bericht op te slaan. Vervangen het volgende:

// TODO: Insert message into database

Door dit (negeer de <?php and ?> tags):

$message = new Message();
$message->fromArray($form->getValues(true));
$message->posted = new Doctrine_Expression('NOW()');
$message->save();

Zoals je kan zien gebruiken we een object van de Message klasse. Deze klasse is automatisch aangemaakt door Doctrine. Je kan ze vinden in application/models/. De autoloader zorgt er voor dat alle vereiste bestanden geladen zijn.

We moeten de berichten weer opvragen om ze te tonen. Beginnen doen we bij de controller. Vervang:

// TODO: Retrieve all messages.

Door:

$messages = Doctrine_Query::create()
             ->from('Message m')
             ->orderBy('m.posted DESC')
             ->execute();
$this->view->messages = $messages;

Zeer simpel. Ik heb een DQL query gebruikt om omgekeerd chronologisch te sorteren.

Nu moeten we enkel deze berichten nog weergeven in ons view script. Wederom, vervang:

<!-- TODO: Show messages here -->

Door:

<?php foreach ($this->messages as $message): ?>
    <h2><?=$message->name?> (<?=$message->posted?>)</h2>
    <?=$message->message?>
<?php endforeach; ?>

En we zijn klaar! Het resultaat zou er zo moeten uitzien:

Afgewerkte applicatie

Om de belangrijkste dingen aan te tonen heb ik belangrijke zaken, zoals input validatie, eruit gelaten. Deze applicatie mag je dus niet gebruiken in een productie omgeving! Je kan deze checks als extra oefening zelf toevoegen.

Conclusie

Zo, een propere en simpele applicatie met zowel Zend Framework als Doctrine. Aangezien beide dezelfde filosofieën volgen is het mogelijk om deze proper te integreren, waardoor applicaties bouwen een waar genot wordt.

Als je opmerkingen, reacties of vragen hebt, stuur me gerust een email (ruben@savanne.be), of plaats een reactie op mijn blog.

Appendix: De code verkrijgen

Als je niet graag code kopieert en plakt is er nog een andere optie voor je: downloaden via git. Ik heb zowel de onafgewerkte versie (met TODO items) en een afgewerkte versie online geplaatst in een git repository. Je gebruikt het als volgt:

Clone de git repository met volgende commando: git clone git://git.savanne.be/git/chatapp.git Dit geeft je een kopie van de onafgewerkte versie.
Als je liever de afgewerkte versie wil bekijken, gebruik dan het volgende commando: git checkout -b finished-version origin/finished-version
Je kan wisselen tussen de twee versies met behulp van git checkout master (voor de onafgewerkte versie) en git checkout finished-version (voor de afgewerkte versie).

Appendix: Volledige bestanden