Giorno 6: Di più sul Modello

Ieri è stato un grande giorno. Abbiamo imparato come creare URL carini e come usare il framework symfony per automatizzare parecchie cose.

Oggi miglioreremo il sito web di Jobeet, ottimizzando il codice qua e là. Facendolo, si imparerà ulteriormente ad utilizzare tutte le feature introdotte nei primi cinque giorni di questo tutorial.

L'oggetto Query di Doctrine

Dai requisiti del giorno 2:

"Quando un utente arriva sul sito web di Jobeet vede una lista di offerte di lavoro attive."

Ma al momento tutte le offerte di lavoro sono visualizzate, indipendentemente dal fatto che siano attive o meno:

// apps/frontend/modules/job/actions/actions.class.php
class jobActions extends sfActions
{
  public function executeIndex(sfWebRequest $request)
  {
    $this->jobeet_job_list = Doctrine::getTable('JobeetJob')
      ->createQuery('a')
      ->execute();
  }
 
  // ...
}

Un'offerta di lavoro attiva è un'offerta pubblicata da meno di 30 giorni. Il metodo ~Doctrine_Query~::execute() farà una richiesta al database. Nel codice precedente non abbiamo specificato nessuna condizione di "where", il che significa che tutti i record vengono recuperati dal database.

Modifichiamolo per ottenere solamente le offerte attive:

public function executeIndex(sfWebRequest $request)
{
  $q = Doctrine_Query::create()
    ->from('JobeetJob j')
    ->where('j.created_at > ?', date('Y-m-d h:i:s', time() - 86400 * 30));
 
  $this->jobeet_job_list = $q->execute();
}

Debug dell'SQL generato da Doctrine

Visto che non si scriveranno direttamente le query SQL a mano, Doctrine si prenderà cura delle differenze tra i diversi database e genererà codice SQL ottimizzato per il database selezionato durante il giorno 3. Alcune volte però è molto utile verificare il codice SQL generato da Doctrine; per esempio per fare il debug di una query che non funziona come ci si aspetta. Nell'ambiente di sviluppo (dev), symfony salva queste query (assieme a molto altro) nella cartella log/. Esiste un file di log per ogni combinazione di applicazione ed ambiente. Il file che stiamo cercando si chiama frontend_dev.log:

# log/frontend_dev.log
Dec 04 13:58:33 symfony [info] {sfDoctrineLogger} executeQuery : SELECT 
j.id AS j__id, j.category_id AS j__category_id, j.type AS j__type, 
j.company AS j__company, j.logo AS j__logo, j.url AS j__url, 
j.position AS j__position, j.location AS j__location, 
j.description AS j__description, j.how_to_apply AS j__how_to_apply, 
j.token AS j__token, j.is_public AS j__is_public, 
j.is_activated AS j__is_activated, j.email AS j__email, 
j.expires_at AS j__expires_at, j.created_at AS j__created_at, 
j.updated_at AS j__updated_at FROM jobeet_job j 
WHERE j.created_at > ? (2008-11-08 01:13:35)

Si può vedere che Doctrine ha una clausola where per la colonna created_at (WHERE j.created_at > ?).

Questo è bene, ma è un po' scomodo dover passare dal browser all'IDE ed al file di log ogni volta che si ha bisogno di testare un cambiamento. Grazie alla barra di debug di symfony, tutte le informazioni necessarie sono comodamente disponibili all'interno del browser:

Serializzazione degli oggetti

Anche se il codice precedente funziona, non è affatto perfetto, perché non considera i requisiti del giorno 2:

"Un utente può tornare per riattivare o estendere la validità di un'offerta di lavoro per ulteriori 30 giorni..."

Ma il codice precedente si basa sul valore di created_at e poiché questa colonna memorizza il valore di creazione, non possiamo soddisfare il requisito.

Ma se ricordate lo schema del database che abbiamo descritto il giorno 3, abbiamo anche definito una colonna expires_at. Attualmente questo valore è sempre vuoto, non essendo stato definito nelle fixture. Ma quando un'offerta di lavoro viene creata, il valore va impostato a 30 giorni successivi alla data corrente.

Per fare qualcosa automaticamente prima che un oggetto di tipo Doctrine venga serializzato sul database, si può sovrascrivere il metodo save() della classe del modello:

// lib/model/doctrine/JobeetJob.class.php
class JobeetJob extends BaseJobeetJob
{
  public function save(Doctrine_Connection $conn = null)
  {
    if ($this->isNew() && !$this->getExpiresAt())
    {
      $now = $this->getCreatedAt() ? $this->getDateTimeObject('created_at')->format('U') : time();
      $this->setExpiresAt(date('Y-m-d h:i:s', $now + 86400 * 30));
    }
 
    return parent::save($conn);
  }
 
  // ...
}

Il metodo ~isNew()~ restituisce il valore true quando l'oggetto non è ancora stato serializzato nel database e false altrimenti.

Modifichiamo ora l'azione per utilizzare la colonna expires_at al posto di created_at per selezionare i lavori attivi:

public function executeIndex(sfWebRequest $request)
{
  $q = Doctrine_Query::create()
    ->from('JobeetJob j')
    ->where('j.expires_at > ?', date('Y-m-d h:i:s', time()));
 
  $this->jobeet_job_list = $q->execute();
}

Abbiamo ristretto il criterio per selezionare solamente le offerte di lavoro con la data expires_at nel futuro.

Ancora sulle Fixture

Aggiornando la homepage di Jobeet nel browser non cambia nulla, poiché i lavori nel database sono stati inseriti solo pochi giorni fa. Cambiamo le fixture per aggiungere un lavoro che sia già scaduto.

# data/fixtures/jobs.yml
JobeetJob:
  # other jobs
 
  expired_job:
    JobeetCategory: programming
    company:        Sensio Labs
    position:       Web Developer
    location:       Paris, France
    description:    Lorem ipsum dolor sit amet, consectetur adipisicing elit.
    how_to_apply:   Send your resume to lorem.ipsum [at] dolor.sit
    is_public:      true
    is_activated:   true
    created_at:     '2005-12-01 00:00:00'
    token:          job_expired
    email:          job@example.com

Ricarichiamo le fixture ed aggiorniamo il browser, per assicurarci che il vecchio lavoro non si veda più:

$ php symfony doctrine:data-load

Configurazione personalizzata

Nel metodo JobeetJob::save() abbiamo inserito il numero di giorni dopo cui un lavoro scade. Sarebbe stato molto meglio rendere quel valore configurabile. Il framework symfony fornisce un file di configurazione per le impostazioni specifiche dell'applicazione, il file app.yml. Questo file YAML può contenere tutte le impostazioni che si desiderano:

# apps/frontend/config/app.yml
all:
  active_days: 30

Nell'applicazione, queste impostazioni sono disponibili tramite la classe globale ~sfConfig~:

sfConfig::get('app_active_days')

Le impostazioni hanno come prefisso app_, perché la classe sfConfig dà accesso ad impostazioni di symfony, come vedremo più avanti.

Aggiorniamo il codice per tenere in considerazione queste nuove impostazioni:

public function save(Doctrine_Connection $conn = null)
{
  if ($this->isNew() && !$this->getExpiresAt())
  {
    $now = $this->getCreatedAt() ? $this->getDateTimeObject('created_at')->format('U') : time();
    $this->setExpiresAt(date('Y-m-d h:i:s', $now + 86400 * sfConfig::get('app_active_days')));
  }
 
  return parent::save($conn);
}

Il file di configurazione app.yml è un bel modo per centralizzare le impostazioni globali per la propria applicazione.

Infine, se si ha bisogno di impostazioni che valgano per tutto il progetto, basta creare un nuovo file app.yml nella cartella config, sotto la cartella radice del proprio progetto symfony.

Rifattorizzare

Sebbene il codice che abbiamo scritto funzioni, non va ancora del tutto bene. Riuscite ad intravedere il problema?

Il codice di Doctrine_Query non appartiene all'azione (livello del Controllore), ma al livello del Modello. Nel pattern MVC, il Modello definisce tutta la business logic, ed il Controllore si limita a richiamare il Modello per recuperare da esso i dati. Siccome il codice restituisce un insieme di lavori, spostiamo il codice nella classe JobeetJobTable e creiamo un metodo getActiveJobs(): JobeetJobTable:

// lib/model/doctrine/JobeetJobTable.class.php
class JobeetJobTable extends Doctrine_Table
{
  public function getActiveJobs()
  {
    $q = $this->createQuery('j')
      ->where('j.expires_at > ?', date('Y-m-d h:i:s', time()));
 
    return $q->execute();
  }
}

Ora il codice dell'azione può usare questo nuovo metodo per recuperare i lavori attivi.

public function executeIndex(sfWebRequest $request)
{
  $this->jobeet_job_list = Doctrine::getTable('JobeetJob')->getActiveJobs();
}

Questa rifattorizzazione ha diversi benefici rispetto al codice precedente:

• La logica per ottenere i lavori attivi è ora nel Modello, a cui appartiene
• Il codice nel controllore è molto più leggibile
• Il metodo getActiveJobs() è riutilizzabile (ad esempio in un'altra azione)
• Il codice del modello è ora testabile con i test unitari

Ordiniamo i lavori per la colonna expires_at:

public function getActiveJobs()
{
  $q = $this->createQuery('j')
    ->where('j.expires_at > ?', date('Y-m-d h:i:s', time()))
    ->orderBy('j.expires_at DESC');
 
  return $q->execute();
}

Il metodo orderBy imposta la clausola ORDER BY all'SQL generato (esiste anche addOrderBy()).

Categorie nella homepage

Dalle richieste del giorno 2: "I lavori sono ordinati per categoria e per data di pubblicazione (i più recenti prima)."

Finora, non abbiamo tenuto in considerazione la categoria dei lavori. Dalle richieste, la homepage deve mostrare i lavori per categoria. Innanzitutto, dobbiamo prendere tutte le categorie che abbiano almeno un lavoro attivo.

Aprire la classe JobeetCategoryTable ed aggiungere un metodo getWithJobs():

// lib/model/doctrine/JobeetCategoryTable.class.php
class JobeetCategoryTable extends Doctrine_Table
{
  public function getWithJobs()
  {
    $q = $this->createQuery('c')
      ->leftJoin('c.JobeetJob j')
      ->where('j.expires_at > ?', date('Y-m-d h:i:s', time()));
 
    return $q->execute();
  }
}

Cambiamo l'azione index di conseguenza:

// apps/frontend/modules/job/actions/actions.class.php
public function executeIndex(sfWebRequest $request)
{
  $this->categories = Doctrine::getTable('JobeetCategory')->getWithJobs();
}

Nel template, dobbiamo iterare su tutte le categorie e mostrare i lavori attivi:

// apps/frontend/modules/job/templates/indexSuccess.php
<?php use_stylesheet('jobs.css') ?>
 
<div id="jobs">
  <?php foreach ($categories as $category): ?>
    <div class="category_<?php echo Jobeet::slugify($category->getName()) ?>">
      <div class="category">
        <div class="feed">
          <a href="">RSS Feed</a>
        </div>
        <h1><?php echo $category ?></h1>
      </div>
 
      <table class="jobs">
        <?php foreach ($category->getActiveJobs() as $i => $job): ?>
          <tr class="<?php echo fmod($i, 2) ? 'even' : 'odd' ?>">
            <td class="location"><?php echo $job->getLocation() ?></td>
            <td class="position"><?php echo link_to($job->getPosition(), 'job_show_user', $job) ?></td>
            <td class="company"><?php echo $job->getCompany() ?></td>
          </tr>
        <?php endforeach; ?>
      </table>
    </div>
  <?php endforeach; ?>
</div>

Per poter funzionare, c'è bisogno di aggiungere il metodo getActiveJobs() alla classe JobeetCategory:

// lib/model/doctrine/JobeetCategory.class.php
public function getActiveJobs()
{
  $q = Doctrine_Query::create()
    ->from('JobeetJob j')
    ->where('j.category_id = ?', $this->getId());
 
  return Doctrine::getTable('JobeetJob')->getActiveJobs($q);
}

Il metodo JobeetCategory::getActiveJobs() usa il metodo Doctrine::getTable('JobeetJob')->getActiveJobs() per recuperare i lavori attivi per una data categoria.

Richiamando Doctrine::getTable('JobeetJob')->getActiveJobs(), vogliamo restringere ulteriormente le condizioni, fornendo una categoria. Invece di passare l'oggetto categoria, abbiamo deciso di passare un oggetto Doctrine_Query, perché è il modo migliore per incapsulare una condizione generica.

Il metodo getActiveJobs() ha bisogno di fondere questo oggetto Doctrine_Query con la sua query. Siccome Doctrine_Query è un oggetto, è piuttosto semplice:

// lib/model/doctrine/JobeetJobTable.class.php
public function getActiveJobs(Doctrine_Query $q = null)
{
  if (is_null($q))
  {
    $q = Doctrine_Query::create()
      ->from('JobeetJob j');
  }
 
  $q->andWhere('j.expires_at > ?', date('Y-m-d h:i:s', time()))
    ->addOrderBy('j.expires_at DESC');
 
  return $q->execute();
}

Limitare i risultati

C'è ancora una richiesta da implementare per la lista dei lavori sulla homepage:

"Per ogni categoria, la lista mostra solo i primi 10 lavori ed un link consente di elencare tutti i lavori per una data categoria."

Questo è semplice quanto aggiungere il metodo getActiveJobs():

// lib/model/doctrine/JobeetCategory.class.php
public function getActiveJobs($max = 10)
{
  $q = Doctrine_Query::create()
    ->from('JobeetJob j')
    ->where('j.category_id = ?', $this->getId())
    ->limit($max);
 
  return Doctrine::getTable('JobeetJob')->getActiveJobs($q);
}

L'appropriata clausola ~LIMIT~ è ora insita nel Modello, ma è meglio che tale valore sia configurabile. Cambiamo il template in modo che passi un numero massimo di lavori, impostato in app.yml:

<!-- apps/frontend/modules/job/templates/indexSuccess.php -->
<?php foreach ($category->getActiveJobs(sfConfig::get('app_max_jobs_on_homepage')) as $i => $job): ?>

ed aggiungiamo una nuova impostazione in app.yml:

all:
  active_days:          30
  max_jobs_on_homepage: 10

Fixture dinamiche

A meno che non si abbassi l'impostazione max_jobs_on_homepage ad uno, non si vedrà nessuna differenza. Abbiamo bisogno di aggiungere un sacco di lavori alle fixture. Si potrebbe copiare e incollare un lavoro esistente per dieci o venti volte a mano... ma c'è un modo migliore. La duplicazione è male, anche nei file fixture.

symfony al salvataggio! I file YAML in symfony possono contenere codice PHP, che viene valutato appena prima di leggere il file. Modifichiamo il file fixture 020_jobs.yml ed aggiungiamo alla fine il seguente codice:

JobeetJob:
# Inizia all'inizio della riga (senza spazi bianchi prima)
<?php for ($i = 100; $i <= 130; $i++): ?>
  job_<?php echo $i ?>:
    JobeetCategory: programming
    company:      Company <?php echo $i."\n" ?>
    position:     Web Developer
    location:     Paris, France
    description:  Lorem ipsum dolor sit amet, consectetur adipisicing elit.
    how_to_apply: |
      Send your resume to lorem.ipsum [at] company_<?php echo $i ?>.sit
    is_public:    true
    is_activated: true
    token:        job_<?php echo $i."\n" ?>
    email:        job@example.com
 
<?php endfor; ?>

State attenti, il parser YAML si arrabbierà se si fa confusione con l'indentazione. Tenete a mente i seguenti semplici consigli, quando aggiungete codice PHP ad un file YAML:

• Le istruzioni <?php ?> devono sempre iniziare la riga od essere compresi in un valore.
• Se un'istruzione <?php ?> termina una riga, si deve esplicitamente mandare in output un "a capo" ("\n").

Ora si possono ricaricare le fixture con il task doctrine:data-load e vedere se sono visualizzati solo 10 lavori sulla homepage per la categoria Programming. Nella seguente schermata, abbiamo cambiato il numero massimo di lavori a cinque per rendere l'immagine più piccola:

Rendere sicura la pagina del lavoro

Quando un lavoro scade, anche se si conosce l'URL, non deve essere possibile accedervi ancora. Proviamo l'URL per il lavoro scaduto (sostituire l'id con il vero valore di id contenuto nel proprio database) - SELECT id, token FROM jobeet_job WHERE expires_at < NOW()):

/frontend_dev.php/job/sensio-labs/paris-france/ID/web-developer-expired

Invece di mostrare il lavoro, dobbiamo rimandare l'utente ad una pagina 404. Ma come possiamo farlo, visto che il lavoro è recuperato automaticamente dalla rotta?

# apps/frontend/config/routing.yml
job_show_user:
  url:     /job/:company_slug/:location_slug/:id/:position_slug
  class:   sfDoctrineRoute
  options:
    model: JobeetJob
    type:  object
    method_for_query: retrieveActiveJob
  param:   { module: job, action: show }
  requirements:
    id: \d+
    sf_method: [GET]

Il metodo retrieveActiveJob riceverà l'oggetto Doctrine_Query costruito dalla rotta:

// lib/model/doctrine/JobeetJobTable.class.php
class JobeetJobTable extends Doctrine_Table
{       
  public function retrieveActiveJob(Doctrine_Query $q)
  {
    $q->andWhere('a.expires_at > ?', date('Y-m-d h:i:s', time()));
 
    return $q->fetchOne();
  }
 
  // ...
}

Se ora si prova ad ottenere un lavoro scaduto, si verrà rimandati ad una pagina 404.

Link alla pagina della categoria

Aggiungiamo ora un link alla pagina della categoria sulla homepage e creiamo la pagina della categoria.

Ma aspettate un minuto. C'è ancora tempo e non abbiamo lavorato molto. Avete un sacco di tempo libero ed abbastanza conoscenze per implementare tutto questo da soli! Rendiamolo un'esercitazione. Tornate domani a controllare l'implementazione.

A domani

Lavorate ad un'implementazione del vostro progetto Jobeet in locale. Abusate pure della documentazione API online e di tutta la documentazione liberamente disponibile sul sito di symfony per aiutarvi. Ci vediamo domani con la nostra implementazione.

Buona fortuna!