Struktura imenika aplikacije

Pomembno je omeniti, da samo ogrodje Nette Framework ne vztraja pri nobeni posebni strukturi. Zasnovan je tako, da ga je mogoče zlahka prilagoditi vsem potrebam in željam.

Osnovna struktura projekta

Čeprav ogrodje Nette Framework ne narekuje nobene fiksne strukture imenikov, obstaja preverjena privzeta ureditev v obliki spletnega projekta:

web-project/
├── app/              ← imenik aplikacij
├── assets/           ← SCSS, JS datoteke, slike..., lahko tudi resources/
├── bin/              ← skripte ukazne vrstice
├── config/           ← konfiguracija
├── log/              ← zabeležene napake
├── temp/             ← začasne datoteke, predpomnilnik
├── tests/            ← testi
├── vendor/           ← knjižnice, ki jih je namestil Composer
└── www/              ← javni imenik (document-root)

To strukturo lahko poljubno spreminjate glede na svoje potrebe – preimenujete ali premikate mape. Nato morate le prilagoditi relativne poti do imenikov v Bootstrap.php in po možnosti composer.json. Nič drugega ni potrebno, nobene zapletene ponovne konfiguracije, nobenih stalnih sprememb. Nette ima pametno samodejno zaznavanje in samodejno prepozna lokacijo aplikacije, vključno z njeno bazo URL.

Načela organizacije kode

Ko prvič raziskujete nov projekt, se morate znati hitro orientirati. Predstavljajte si, da kliknete na imenik app/Model/ in vidite to strukturo:

app/Model/
├── Services/
├── Repositories/
└── Entities/

Iz nje boste izvedeli le, da projekt uporablja nekatere storitve, skladišča in entitete. Ne boste izvedeli ničesar o dejanskem namenu aplikacije.

Oglejmo si drugačen pristop – organizacija po domenah:

app/Model/
├── Cart/
├── Payment/
├── Order/
└── Product/

Na prvi pogled je jasno, da gre za spletno mesto e-trgovine. Že imena imenikov razkrivajo, kaj aplikacija zmore – dela s plačili, naročili in izdelki.

Prvi pristop (organizacija po vrsti razreda) v praksi prinaša več težav: koda, ki je logično povezana, je razpršena po različnih mapah in med njimi je treba preskakovati. Zato se bomo organizirali po domenah.

Prostori imen

Običajno struktura imenikov ustreza imenskim prostorom v aplikaciji. To pomeni, da fizična lokacija datotek ustreza njihovemu imenskemu prostoru. Na primer, razred, ki se nahaja v app/Model/Product/ProductRepository.php, mora imeti imenski prostor App\Model\Product. To načelo pomaga pri usmerjanju kode in poenostavlja samodejno nalaganje.

Ednina in množina v imenih

Opazite, da za glavne imenike aplikacij uporabljamo ednino: app config , log, temp, www. Enako velja tudi znotraj aplikacije: Model, Core, Presentation. To je zato, ker vsak od njih predstavlja en enoten koncept.

Podobno tudi app/Model/Product predstavlja vse o izdelkih. Ne imenujemo je Products, ker to ni mapa, polna izdelkov (ki bi vsebovala datoteke, kot so iphone.php, samsung.php). To je imenski prostor, ki vsebuje razrede za delo z izdelki – ProductRepository.php, ProductService.php.

Mapa app/Tasks je množinska, ker vsebuje nabor samostojnih izvršilnih skript – CleanupTask.php, ImportTask.php. Vsaka od njih je samostojna enota.

Zaradi doslednosti priporočamo uporabo:

• ednino za imenske prostore, ki predstavljajo funkcionalno enoto (tudi če delate z več enotami)
• množino za zbirke neodvisnih enot
• V primeru negotovosti ali če o tem ne želite razmišljati, izberite ednino

Javni imenik www/

Ta imenik je edini, ki je dostopen s spleta (tako imenovani koren dokumentov). Pogosto lahko namesto imena www/ naletite na ime public/ – to je le stvar konvencije in ne vpliva na funkcionalnost. Imenik vsebuje:

• vstopno točko aplikacije index.php
• datoteko .htaccess s pravili mod_rewrite (za Apache)
• statične datoteke (CSS, JavaScript, slike)
• naložene datoteke

Za ustrezno varnost aplikacije je ključnega pomena, da je pravilno konfiguriran document-root.

V ta imenik nikoli ne postavite mape node_modules/ – vsebuje na tisoče datotek, ki so lahko izvedljive in ne smejo biti javno dostopne.

Imenik aplikacij app/

To je glavni imenik z aplikacijsko kodo. Osnovna struktura:

app/
├── Core/               ← infrastrukturne zadeve
├── Model/              ← poslovna logika
├── Presentation/       ← predstavitve in predloge
├── Tasks/              ← skripte ukazov
└── Bootstrap.php       ← zagonski razred aplikacije

Bootstrap.php je zagonski razred aplikacije, ki inicializira okolje, naloži konfiguracijo in ustvari vsebnik DI.

Zdaj si podrobno oglejmo posamezne podimenike.

Predstavniki in predloge

Predstavitveni del aplikacije imamo v imeniku app/Presentation. Druga možnost je kratek naslov app/UI. To je prostor za vse predstavitve, njihove predloge in morebitne pomožne razrede.

To plast organiziramo po domenah. V kompleksnem projektu, ki združuje e-trgovino, blog in API, bi bila struktura videti takole:

app/Presentation/
├── Shop/              ← e-trgovina frontend
│   ├── Product/
│   ├── Cart/
│   └── Order/
├── Blog/              ← blog
│   ├── Home/
│   └── Post/
├── Admin/             ← uprava
│   ├── Dashboard/
│   └── Products/
└── Api/               ← Končne točke API
	└── V1/

Za preprost blog pa bi uporabili to strukturo:

app/Presentation/
├── Front/             ← spletna stran frontend
│   ├── Home/
│   └── Post/
├── Admin/             ← uprava
│   ├── Dashboard/
│   └── Posts/
├── Error/
└── Export/            ← RSS, zemljevide itd.

V mapah, kot sta Home/ ali Dashboard/, so predstavniki in predloge. Mape, kot so Front/, Admin/ ali Api/, se imenujejo moduli. Tehnično gledano so to običajni imeniki, ki služijo za logično organizacijo aplikacije.

Vsaka mapa s predstavnikom vsebuje podobno poimenovane predstavnike in njihove predloge. Na primer, mapa Dashboard/ vsebuje:

Dashboard/
├── DashboardPresenter.php     ← voditelj
└── default.latte              ← predloga

Ta struktura imenikov se odraža v imenskih prostorih razredov. Na primer, DashboardPresenter je v imenskem prostoru App\Presentation\Admin\Dashboard (glejte preslikavo predavateljev):

namespace App\Presentation\Admin\Dashboard;

class DashboardPresenter extends Nette\Application\UI\Presenter
{
	//...
}

Predstavnik Dashboard znotraj modula Admin v aplikaciji označujemo z zapisom v dvopičju kot Admin:Dashboard. Na njegovo akcijo default pa nato kot Admin:Dashboard:default. Za vgnezdene module uporabljamo več dvopičij, na primer Shop:Order:Detail:default.

Razvoj prilagodljive strukture

Ena od velikih prednosti te strukture je, kako elegantno se prilagaja naraščajočim potrebam projekta. Kot primer vzemimo del, ki ustvarja vire XML. Na začetku imamo preprost obrazec:

Export/
├── ExportPresenter.php   ← en predavatelj za ves izvoz
├── sitemap.latte         ← predlogo za karto spletnega mesta
└── feed.latte            ← predlogo za vir RSS

Sčasoma se doda več vrst virov in zanje potrebujemo več logike… Ni problema! Mapa Export/ preprosto postane modul:

Export/
├── Sitemap/
│   ├── SitemapPresenter.php
│   └── sitemap.latte
└── Feed/
	├── FeedPresenter.php
	├── amazon.latte         ← krma za Amazon
	└── ebay.latte           ← vir za eBay

Preoblikovanje je popolnoma nemoteno – ustvarite nove podmape, razdelite kodo vanje in posodobite povezave (npr. iz Export:feed v Export:Feed:amazon). Zaradi tega lahko strukturo postopoma širimo po potrebi, raven gnezdenja ni v ničemer omejena.

Če imate na primer v administraciji veliko predstavnikov, povezanih z upravljanjem naročil, kot so OrderDetail, OrderEdit, OrderDispatch itd, lahko za boljšo organizacijo ustvarite modul (mapo) Order, ki bo vseboval (mape za) predstavnike Detail, Edit, Dispatch in druge.

Lokacija predloge

V prejšnjih primerih smo videli, da se predloge nahajajo neposredno v mapi s predstavitvijo:

Dashboard/
├── DashboardPresenter.php     ← voditelj
├── DashboardTemplate.php      ← neobvezen razred predloge
└── default.latte              ← Predloga

Ta lokacija se v praksi izkaže za najprimernejšo – vse povezane datoteke imate takoj pri roki.

Predloge lahko namestite tudi v podmapo templates/. Nette podpira obe različici. Predloge lahko postavite tudi povsem zunaj mape Presentation/. Vse o možnostih lokacije predlog najdete v poglavju Iskanje predlog.

Pomožni razredi in komponente

Predstavniki in predloge so pogosto opremljeni z drugimi pomožnimi datotekami. Razporedimo jih logično glede na njihovo področje uporabe:

1. Neposredno s predstavitvijo v primeru posebnih komponent za določeno predstavitev:

Product/
├── ProductPresenter.php
├── ProductGrid.php        ← komponenta za uvrstitev izdelka na seznam
└── FilterForm.php         ← obrazec za filtriranje

2. Za modul – priporočamo uporabo mape Accessory, ki je lepo postavljena na začetek abecede:

Front/
├── Accessory/
│   ├── NavbarControl.php    ← komponente za frontend
│   └── TemplateFilters.php
├── Product/
└── Cart/

3. Za celotno aplikacijo – v Presentation/Accessory/:

app/Presentation/
├── Accessory/
│   ├── LatteExtension.php
│   └── TemplateFilters.php
├── Front/
└── Admin/

Lahko pa pomožne razrede, kot sta LatteExtension.php ali TemplateFilters.php, namestite v infrastrukturno mapo app/Core/Latte/. Komponente pa v mapo app/Components. Izbira je odvisna od skupinskih konvencij.

Model – srce aplikacije

Model vsebuje vso poslovno logiko aplikacije. Za njegovo organizacijo velja enako pravilo – strukturiramo ga po domenah:

app/Model/
├── Payment/                   ← vse o plačilih
│   ├── PaymentFacade.php      ← glavna vstopna točka
│   ├── PaymentRepository.php
│   ├── Payment.php            ← entiteta
├── Order/                     ← vse o naročilih
│   ├── OrderFacade.php
│   ├── OrderRepository.php
│   ├── Order.php
└── Shipping/                  ← vse o odpremi

V modelu se običajno srečamo s temi vrstami razredov:

Fasade: predstavljajo glavno vstopno točko v določeno domeno v aplikaciji. Delujejo kot orkestrator, ki usklajuje sodelovanje med različnimi storitvami za izvajanje celotnih primerov uporabe (kot sta “ustvariti naročilo” ali “obdelati plačilo”). Pod orkestracijsko plastjo fasada skriva podrobnosti izvajanja pred preostalim delom aplikacije in tako zagotavlja čist vmesnik za delo z določeno domeno.

class OrderFacade
{
	public function createOrder(Cart $cart): Order
	{
		// potrjevanje
		// ustvarjanje naročila.
		// pošiljanje e-pošte
		// pisanje v statistiko
	}
}

Službe: osredotočajo se na posebne poslovne operacije znotraj domene. Za razliko od fasad, ki orkestrirajo celotne primere uporabe, storitev izvaja specifično poslovno logiko (kot so izračuni cen ali obdelava plačil). Storitve so običajno brez stanja in jih lahko uporabljajo fasade kot gradnike za kompleksnejše operacije ali drugi deli aplikacije neposredno za enostavnejša opravila.

class PricingService
{
	public function calculateTotal(Order $order): Money
	{
		// izračun cene
	}
}

Hrambe: skrbijo za vso komunikacijo s hrambo podatkov, običajno s podatkovno zbirko. Njihova naloga je nalaganje in shranjevanje entitet ter izvajanje metod za njihovo iskanje. Skladišče ščiti preostalo aplikacijo pred podrobnostmi izvajanja podatkovne zbirke in zagotavlja objektno usmerjen vmesnik za delo s podatki.

class OrderRepository
{
	public function find(int $id): ?Order
	{
	}

	public function findByCustomer(int $customerId): array
	{
	}
}

Entitete: objekti, ki predstavljajo glavne poslovne koncepte v aplikaciji, ki imajo svojo identiteto in se s časom spreminjajo. Običajno so to razredi, ki so s pomočjo ORM (kot sta Nette Database Explorer ali Doctrine) preslikani v tabele podatkovne zbirke. Entitete lahko vsebujejo poslovna pravila v zvezi z njihovimi podatki in logiko potrjevanja.

// Entiteta, preslikana v tabelo naročil v zbirki podatkov
class Order extends Nette\Database\Table\ActiveRow
{
	public function addItem(Product $product, int $quantity): void
	{
		$this->related('order_items')->insert([
			'product_id' => $product->id,
			'quantity' => $quantity,
			'unit_price' => $product->price,
		]);
	}
}

Vrednostni objekti: nespremenljivi objekti, ki predstavljajo vrednosti brez lastne identitete – na primer znesek denarja ali e-poštni naslov. Dva primerka objekta vrednosti z enakimi vrednostmi veljata za enaka.

Koda infrastrukture

V mapi Core/ (ali tudi Infrastructure/) se nahaja tehnični temelj aplikacije. Infrastrukturna koda običajno vključuje:

app/Core/
├── Router/               ← usmerjanje in upravljanje URL.
│   └── RouterFactory.php
├── Security/             ← avtentikacija in avtorizacija.
│   ├── Authenticator.php
│   └── Authorizator.php
├── Logging/              ← beleženje in spremljanje
│   ├── SentryLogger.php
│   └── FileLogger.php
├── Cache/                ← plast predpomnilnika
│   └── FullPageCache.php
└── Integration/          ← integracija z zunanjimi storitvami
	├── Slack/
	└── Stripe/

Za manjše projekte seveda zadostuje ravna struktura:

Core/
├── RouterFactory.php
├── Authenticator.php
└── QueueMailer.php

To je koda, ki:

• Obravnava tehnično infrastrukturo (usmerjanje, beleženje, predpomnilnik).
• vključuje zunanje storitve (Sentry, Elasticsearch, Redis)
• zagotavlja osnovne storitve za celotno aplikacijo (pošta, zbirka podatkov)
• je večinoma neodvisna od določene domene – predpomnilnik ali logger deluje enako za e-trgovino ali blog.

Se sprašujete, ali določen razred spada sem ali v model? Ključna razlika je v tem, da je koda v Core/:

• ne ve ničesar o domeni (izdelki, naročila, članki)
• Običajno jo je mogoče prenesti v drug projekt
• rešuje “kako deluje” (kako poslati pošto) in ne “kaj počne” (kakšno pošto poslati)

Primer za boljše razumevanje:

• App\Core\MailerFactory – ustvari primerke razreda za pošiljanje e-pošte, skrbi za nastavitve SMTP
• App\Model\OrderMailer – uporablja MailerFactory za pošiljanje e-poštnih sporočil o naročilih, pozna njihove predloge in ve, kdaj jih je treba poslati

Skripte ukazov

Aplikacije morajo pogosto opravljati naloge zunaj običajnih zahtevkov HTTP – bodisi gre za obdelavo podatkov v ozadju, vzdrževanje ali periodična opravila. Za izvajanje se uporabljajo preproste skripte v imeniku bin/, medtem ko je dejanska izvedbena logika nameščena v imeniku app/Tasks/ (ali app/Commands/).

Primer:

app/Tasks/
├── Maintenance/               ← skripte za vzdrževanje
│   ├── CleanupCommand.php     ← brisanje starih podatkov
│   └── DbOptimizeCommand.php  ← optimizacija podatkovne zbirke
├── Integration/               ← integracija z zunanjimi sistemi
│   ├── ImportProducts.php     ← uvoz iz sistema dobavitelja
│   └── SyncOrders.php         ← sinhronizacija naročil
└── Scheduled/                 ← redna opravila
	├── NewsletterCommand.php  ← pošiljanje novic
	└── ReminderCommand.php    ← obveščanje strank

Kaj spada v model in kaj v ukazne skripte? Na primer, logika za pošiljanje enega e-poštnega sporočila je del modela, množično pošiljanje tisočih e-poštnih sporočil pa spada v Tasks/.

Opravila se običajno izvajajo iz ukazne vrstice ali prek programa cron. Lahko se zaženejo tudi prek zahteve HTTP, vendar je pri tem treba upoštevati varnost. Predstavnik, ki izvaja opravilo, mora biti zavarovan, na primer samo za prijavljene uporabnike ali z močnim žetonom in dostopom z dovoljenih naslovov IP. Za dolga opravila je treba povečati časovno omejitev skripta in uporabiti spletno stran session_write_close(), da se prepreči zaklepanje seje.

Drugi možni imeniki

Poleg omenjenih osnovnih imenikov lahko glede na potrebe projekta dodate tudi druge specializirane mape. Oglejmo si najpogostejše in njihovo uporabo:

app/
├── Api/              ← Logika API je neodvisna od predstavitvene plasti
├── Database/         ← migracijske skripte in sejalnike za testne podatke.
├── Components/       ← skupne vizualne komponente v aplikaciji
├── Event/            ← uporabno, če uporabljate arhitekturo, ki temelji na dogodkih
├── Mail/             ← e-poštne predloge in povezana logika
└── Utils/            ← pomožni razredi

Za skupne vizualne komponente, ki se uporabljajo v predstavitvah v celotni aplikaciji, lahko uporabite mapo app/Components ali app/Controls:

app/Components/
├── Form/                 ← komponente obrazca v skupni rabi
│   ├── SignInForm.php
│   └── UserForm.php
├── Grid/                 ← komponente za izpise podatkov
│   └── DataGrid.php
└── Navigation/           ← navigacijski elementi
	├── Breadcrumbs.php
	└── Menu.php

V to mapo spadajo komponente z bolj zapleteno logiko. Če želite komponente deliti med več projekti, jih je dobro ločiti v samostojni paket Composer.

V imenik app/Mail lahko umestite upravljanje komunikacije z elektronsko pošto:

app/Mail/
├── templates/            ← e-poštne predloge
│   ├── order-confirmation.latte
│   └── welcome.latte
└── OrderMailer.php

Predavatelj Mapiranje

Mapiranje določa pravila za izpeljavo imen razredov iz imen predvajalnikov. Določimo jih v konfiguraciji pod ključem application › mapping.

Na tej strani smo pokazali, da predstavnike namestimo v mapo app/Presentation (ali app/UI). V konfiguracijski datoteki moramo Nette obvestiti o tej konvenciji. Zadostuje ena vrstica:

application:
	mapping: App\Presentation\*\**Presenter

Kako deluje preslikava? Za boljše razumevanje si najprej predstavljajmo aplikacijo brez modulov. Želimo, da razredi predstavnikov spadajo v imenski prostor App\Presentation, tako da se predstavnik Home preslika v razred App\Presentation\HomePresenter. To dosežemo s to konfiguracijo:

application:
	mapping: App\Presentation\*Presenter

Mapiranje poteka tako, da se zvezdica v maski App\Presentation\*Presenter zamenja z imenom predstavnika Home, s čimer dobimo končno ime razreda App\Presentation\HomePresenter. Enostavno!

Vendar, kot vidite v primerih v tem in drugih poglavjih, umeščamo predstavitvene razrede v istoimenske podimenike, na primer predstavitveni razred Home se preslika v razred App\Presentation\Home\HomePresenter. To dosežemo s podvojitvijo dvopičja (zahteva aplikacijo Nette 3.2):

application:
	mapping: App\Presentation\**Presenter

Zdaj bomo prešli na preslikavo predstavnikov v module. Za vsak modul lahko določimo posebno kartiranje:

application:
	mapping:
		Front: App\Presentation\Front\**Presenter
		Admin: App\Presentation\Admin\**Presenter
		Api: App\Api\*Presenter

V skladu s to konfiguracijo je predstavnik Front:Home preslikan v razred App\Presentation\Front\Home\HomePresenter, medtem ko je predstavnik Api:OAuth preslikan v razred App\Api\OAuthPresenter.

Ker imata modula Front in Admin podoben način preslikave in ker bo takih modulov verjetno več, je mogoče ustvariti splošno pravilo, ki jih bo nadomestilo. V masko razreda bo dodana nova zvezdica za modul:

application:
	mapping:
		*: App\Presentation\*\**Presenter
		Api: App\Api\*Presenter

Deluje tudi za globlje ugnezdene imeniške strukture, kot je predstavnik Admin:User:Edit, kjer se segment z zvezdico ponovi za vsako raven in ima za rezultat razred App\Presentation\Admin\User\Edit\EditPresenter.

Alternativni zapis je, da namesto niza uporabimo polje, sestavljeno iz treh segmentov. Ta zapis je enakovreden prejšnjemu:

application:
	mapping:
		*: [App\Presentation, *, **Presenter]
		Api: [App\Api, '', *Presenter]