De la Zero la RESTful în 4 pași. Fundația.

Georgiana Gligor
Owner @Tekkie Consulting

Dezvoltarea de aplicații în mod profesionist folosind LAMP impune un framework modern. Acesta standardizează modul în care muncim, în primul rând prin folosirea unei organizări predictibile a codului și a fișierelor și în al doilea rând pentru că vine la pachet cu utilități și librării de bază. Mai mult decât atât, un framework abordează noțiuni de securitate la baza software-ului, este un factor cheie în îmbunătățirea muncii de echipă prin impunerea standardelor de codare și integrarea mai ușoară în echipă a noilor colegi. Nu în cele din urmă, în spatele său stă o comunitate, și ne face mai eficienți pentru că ne ajută să ne concentrăm în primul rând pe funcționalitatea proiectului nostru.

Cu toate acestea, există anumite proiecte unde folosirea unui framework complet este percepută drept o povară pentru dezvoltatori. Microservicii individuale, mici prototipuri, situri web de complexitate redusă, APIuri simple, funcționalitate mock, iată câteva cazuri în care programatorul ar prefera să beneficieze doar de amprenta redusă a unor librării. Acesta este momentul în care micro-framework-urile intră în scenă, închegând aceste librării cu costuri minimale.

Împreună vom construi o aplicație pentru managementul datelor despre vehicule, pentru a putea fi informați atunci când anumite operații trebuie efectuate. Acest lucru se va desfășura pe parcursul câtorva articole, iată un roadmap succint: 1. pregătirea proiectului și a dependințelor, suport TDD și capabilități de logare 2. design al API-urilor RESTful; BDD folosind Behat 3. implementarea API-uri definite la pasul anterior 4. mediu de dezvoltare cu Vagrant și Ansible; automatizarea proceselor de build; integrare continuă

În lumea PHP micro-frameworkurile au devenit cetățeni de prim rang în urmă cu mult timp. Slim, Flight, Limonade, GluePHP, Phlyty sunt doar câteva exemple cunoscute. Noi vom întrebuința Silex, care are la bază componente ale mai popularului Symfony. Pentru a ne forma o idee cât de suplu e Silex, haideți să aruncăm o privire asupra containerului său de injectare a dependințelor (Pimple) și să vedem cum se compară cu cel de la Symfony (imaginea este preluată dintr-o prezentare a lui Igor Wiedler):

Pregătirea proiectului

Să începem prin crearea unui nou proiect: pregătim un director nou de lucru și îl accesăm. Mai jos folosesc o cale absolută pe mașina mea de lucru:

$ mkdir -p /Users/g/Sites/learn/silex-tutorial
$ cd /Users/g/Sites/learn/silex-tutorial

Instalare Composer

Pentru managementul dependințelor vom utiliza Composer. Vine împachetat sub forma unei arhive Phar, deci trebuie să fim atenți să avem extensia phar activată în php.ini:

extension=phar.so # să nu fie comentată această linie

Personal prefer să am Composer instalat global, deoarece îl folosesc la aproape toate proiectele mele. Mai jos este o linie de comandă care efectuează această instalare (avem nevoie de sudo).

$ curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer

Declararea Silex drept dependință

Următorul pas este crearea fișierului composer.json cu ajutorul căruia vom face managementul dependințelor.

{
  "require" : {
    "silex/silex" : "1.*"
  }
}

În directorul de lucru, vom executa următoarea comandă:

$ composer install

Aceasta nu doar că ne va instala Silex și toate dependințele declarate ale acestuia, dar va crea deasemenea un fișier numit composer.lock care va conține o stare cunoscută a tuturor depenințelor deja instalate.

Primul request

A venit momentul să pregătim o mică strategie pentru aranjarea fișierelor proiectului nostru. Este considerată o bună practică păstrarea fișierelor accesibile public într-un director separat, așadar noi vom folosi web/ în acest scop.

Încărcarea resurselor și alte chestiuni de bucătărie internă le vom avea în app/bootstrap.php. Iată cum plănuim să aranjăm fișierele și directoarele:

Fișierul de bootstrap defineste obiectul aplicației Silex și îl returnează. Conținutul fișierului accesibil public e foarte simplu, instanțiază acest obiect și îl rulează prin apelarea metodei run() a acestuia.

Iată cât de ușor ne folosim de caracteristica autoload a Composer:

require_once(__DIR__ . '/../vendor/autoload.php');

Această linie simplă ne salveazaă de multă muncă, deoarece va ști să încarce orice clasă din directorul vendor/ fără să fie necesar să facem asta manual de fiecare dată.

Haideți să vedem ce se întâmplă dacă accesăm direct fișierul web/index.php:

Iată cum Silex răspunde cererii noastre. Ne indică faptul că nu are idee ce ar trebui să facă în cazul cererii noastre, deoarece nu am definit niciun comportament al aplicației până în acest moment. E timpul să adăugăm unul!

Să definim așadar un comportament simplu, care servește cereri de tip GET și răspunde cu un text simplu. Vom face asta definind un șablon de rutare, care este compus din: șablonul în sine ('/' in exemplul de mai jos) metoda HTTP la care poate fi accesat șablonul (verbul get() apelat pe obiectul aplicație) * funcția de tip closure care va fi executată

$app->get('/', function () {
      return 'Up and running.';
});

Dacă ne dorim ca această funcție closure să fie executată pentru mai multe metode HTTP, putem folosi abordarea de mai jos:

$app
    ->match('/', function () {return 'Up and running'; })
    ->method('GET|POST');

Să interpretăm puțin acest cod: prima dată căutăm potrivirea cu șablonul, apoi atașăm funcția de tip closure, după care specificăm lista metodelor la care poate fi accesat acesta.

Adăugarea suportului TDD

Este important să avem o metodă de a scrie teste pentru aplicația noastră. Standardul de-facto în lumea PHP este PHPUnit, chiar și Drupal8 a migrat la acesta de la SimpleTest pe care în folosea anterior.

Să ne întoarcem puțin la proiectul nostru, pentru a vedea cum putem adăuga în mod simplu suportul pentru dezvoltarea test-driven.

După cum se poate observa, avem nevoie de un fișier de configurare pentru PHPUnit și de un director unde să păstrăm testele. Totul funcționează atunci cănd rulăm testele:

Haideți să adaugăm o clasă ce va verifica ruta principală pe care am definit-o anterior; ne vom referi la ea în continuare ca "ruta de status", deoarece accesarea ei ne spune rapid dacă aplicația funcționează sau nu. În fișierul tests/BasicTest.php vom defini

/**
 * Clasa de test simpla pentru a verifica ruta de status
 */
class BasicTest extends WebTestCase

Este important să notăm că testul nostru funcțional extinde Silex\WebTestCase, așadar va fi nevoie să implementăm metoda createApplication() pentru a spune testului cum să primească obiectul de aplicație Silex. Este destul de ușor, tot ce trebuie să facem este să includem fișierul bootstrap și să returnăm obiectul $app. Obiectul WebTestCase este definit într-un pachet extern, așadar trebuie să adăugăm o nouă secțiune în composer.json:`

"require-dev" : {
    "symfony/browser-kit": ">=2.3,<2.4-dev"
}

Metoda de test în sine este extrem de simplă: inițiem o cerere de tip GET pe ruta de status, verificăm faptul că răspunsul are codul de status corect (200) și conținutul efectiv este "Up and running".

/**
 * Verificarea rutei de status
 */
public function testStatusRoute()
{
  $client = $this->createClient();
  $client->request('GET', '/');
  $this->assertTrue($client->getResponse()->isOk());
  $this->assertEquals(
        'Up and running',
        $client->getResponse()->getContent()
  );
}

Ca preferință personală, îmi place să am un namespace separat pentru teste. Așadar namespace TutorialTest are nevoie de puțină configurare în composer.json pentru a se putea încărca automat. Am adăugat următoarea secțiune:

"autoload" : {
    "psr-0" : {
        "TutorialTest" : "tests"
    }
}

După efectuarea acestei modificări este important să nu uităm să rulăm

$ composer update

Aceasta va rezolva toate dependințele proiectului nostru, și va scrie noile versiuni ale acestora în composer.lock.

Să rulăm din nou testele:

Aceasta a fost doar o mică introducere în testarea funcțională, puteți investiga mai multe în documentația Symfony a acestei componente.

Capabilități de logare

Integrarea librăriilor externe se face în Silex prin intermediul furnizorilor. Dacă dorim să folosim puternica librărie Monolog în scopuri de logare, o vom privi ca pe un serviciu și să o integrăm în aplicația noastră prin folosirea unuia din furnizorii de servicii. Din fericire există deja la îndemână MonologServiceProvider, haideți să îl folosim.

Vom adăuga mai întâi o nouă cerință în composer.json:

"monolog/monolog": ">=1.6.0"

și apoi vom rula composer update pentru a o instala.

În continuare vom crea directorul de loguri și îi vom atribui permisiile de rigoare:

$ mkdir logs
$ touch logs/dev.log
$ chmod -R 766 logs/

În plus, vom evita versionarea fișierelor de log prin adăugarea directorului logs/ în lista .gitignore.

Să vedem o utilizare simplă a noii noastre funcționalități de logare. Modificăm puțin codul rutei de status, după cum urmează:

$app
    ->match('/', function () use ($app) {
      $app['monolog']->addInfo('Logging example in the status route');
      return 'Up and running';
    })
    ->method('GET|POST');

Dacă verificăm fișierul de log vom ovserva că apare fiecare request pe care îl facem.

Până acum am creat o aplicație pornind de la un Silex vanilla, care răspunde unei cereri GET simple, am adăugat suport pentru TDD, precum și capabilități de logare. În partea următoare vom trece la designul API-ului nostru RESTful.