Nu, nu este chiar sintaxa PHP. Sau, mai degrabă, nu are nici o legătură cu cele mai PHP și interpretul PHP în sine niciodată nu parses. Acesta phpdoc-bloc care sa născut mai mult ca JavaDoc și convertit la PHPDocumentor
Până nu vom COD ca acesti baieti sunt aprinse:
dar încearcă să înțeleagă.
Toate aceste lucruri, după cum sugerează și numele, sunt cumva conectate cu documentația. De la ea și să înceapă.
codul de documentare
Dacă te uiți în API Reference în codul clasei vom vedea același lucru:
Acum am înțeles modul în care site-ul se schimbă atât de repede de fiecare dată când actualizați sursa. Se pare că nu este făcută manual, și a generat automat cadru cod.
Deci, putem formula deja primul bonus care ne da phpdoc-blocuri:
O singură aplicație: Posibilitatea unei singure comenzi în consolă pentru a genera documentație cu privire la toate clasele, câmpurile și metodele proiectului.
Dar altele decât că ceea ce este util în viața reală? Să considerăm câteva aplicații.
câmp virtual
În modelul, este util pentru aceeași clasă autogenerării a modelului, dar pentru ce se utilizează predstvaleniyah care nu apar în documentație?
De exemplu, o clasă fără domenii:
și nu este clar că există, ca Yii2 are atributele de tabele în baza de date. Autosubstitution vede doar câmpurile și metodele din ActiveRecord clasei de baza:
Și domeniul nostru subliniază, în același timp, jurând că obiectul lor nu este:
Zamorochitsya poate și să scrie un plugin care ar Pars câmp din baza de date pentru fiecare model. Dar acest lucru nu este în mod clar o cale ușoară.
Acum el știe faptele noastre și nu se plânge niciodată.
Sau, în cazul în care există o conexiune în model:
În codul, le putem folosi pur și simplu ca un câmp categorie. utilizator și tag-uri:
Dar aceste câmpuri în clasa nr. Totul funcționează prin metode virtuale și getterelor. Deci, nu avem de ales, cum să se precizeze aceste pseudofield și tipurile lor în mod explicit:
Deci phpdoc-bloc înainte de clasa poate conține o listă completă a ceea ce clasă nu.
Aplicarea celui de al doilea: Notă clasa PSEUDOFIELDS.
În exemplele pe care le-am analizat până în prezent doar domeniu. Prin psevdometodam'll obține mai târziu.
Tipuri de câmpuri existente
În plus față de blocul de clasă poate fi utilizată și în alte locuri.
Să presupunem că avem un domeniu privat, aproape de clasa _user PasswordChangeForm:
Și dacă ne vom arăta ce avem este o clasă model de utilizator:
atunci se va lucra așa ne-am dorit.
Aici am @var adnotări peredaom numai de tip. Dar, în general, este posibil să se transmită numele variabilei, tipul acestuia sau ambele argumente dintr-o dată.
Aplicarea celui de al treilea: tip Sfat pentru câmpurile existente din clasa.
tipul de retur
În mod similar, dacă @return adnotare Se specifică tipul obiectului returnat de metoda:
că, prin utilizarea acestei metode, design-ul nostru sistem va înțelege că în ghidul de $ variabila de asteptare dupa aceasta metoda va fi o clasă model de utilizator:
și nu va mai jura prin metodele ei anterior necunoscute de încărcare și de a salva.
Ce se întâmplă dacă o metodă ne întoarce la orice utilizator. sau nul. Apoi, puteți transfera opțiuni printr-o conductă:
Iar IDE-ul va lua în considerare două cazuri.
Aplicație a patra: tipurile de argument Sfat și tipul de întoarcere a rezultatului (dacă este cazul) să dispună de proceduri, funcții, metode.
Variabile de nicăieri
Sau o altă opțiune. Avem o idee, în care controlerul este transmis de la modelul $ variabila. Mai mult decât atât, acest punct de vedere este redat în clasa obiectului \ Yii \ web \ View. care va fi disponibil prin intermediul $ aceasta:
Dar IDE nu știe planurile noastre, așa că voi sublinia $ această variabilă și model de $ ca nu este definit în acest fișier. Pentru a remedia situația, putem adăuga orice număr de Doc-bloc cu adnotare @var direct în prezentarea codului:
În acest caz, puteți specifica @var pentru primul tip, apoi numele variabilei:
Ca rezultat, autosubstitution, căutare și câmpurile obiect autocorectare și metode vor câștiga pentru aceste variabile în mod automat.
Aplicarea cinci: Identificarea variabilelor în orice mod transmise din exterior.
Tipul de substituție
Noi nu întotdeauna controlere și alte componente folosesc metoda findModel. Puteți de multe ori direct în codul pentru a efectua orice interogare:
IDE-ul pune capăt lanțului de moștenire podsmotrit metoda de adnotare a ActiveRecord :: găsi:
și, deoarece acestea @inheritdoc abstracte. va merge chiar mai mare în adnotările aceleiași metode în interfața:
și lipiți totul împreună.
Sfârșitul IDE al liniei:
înțelege că, din cauza metodei de găsire trebuie să returneze o instanță a clasei \ Yii \ db \ ActiveQuery și metode, iar în cazul în care unul va fi numit deja:
Pentru a funcționa corect, trebuie să se precizeze în mod explicit tipul unei variabile folosind Doc-bloc înainte de atribuire:
sau imediat înainte de utilizare obiectului:
Este convenabil de a face acest lucru în cicluri de diferite probe:
Aplicarea Six: Substituirea tipul variabilelor existente.
Și înapoi la metodele.
conectarea impurităților
În primul rând ne-am uitat la variabilele virtuale. Acum, să presupunem că pentru modelul dvs., includem orice comportament de genul:
Este suficient pentru a adăuga la modelele de comportamente metoda:
și reprezentări ale display-ului original sau previzualizare:
Și ne amintim că IDE se plânge tot ceea ce nu este în clasă. Dar, cu adnotările ajutor @mixin. care susține IDE PhpStorm și, probabil, unele cu altele, puteți „amesteca cu“ comportament de clasă:
și toate metodele getImageFileUrl și altele vor fi disponibile în autosubstitution au modelul nostru.
Dar există un avertisment. În plus față de metodele necesare în comportamentul clasă și are o mulțime de inutile. De exemplu, auxiliar sau resolveProfilePath createThumbs. nu vom folosi.
În acest caz, în loc de întreaga clasă comportament primeshavaniya prin @mixin putem adăuga pur și simplu, o singura definitie pereche avem nevoie de metode virtuale:
În mod similar, puteți adăuga semnătura oricare dintre metodele sale de lucru prin metoda __call lui magic.
Utilizarea de șapte: clasa psevdometodov determinare.
Programarea cu adnotările
În plus, accesul facil la PHPDocumentor unele sisteme au mers mai departe și au venit cu pentru propriile lor scopuri tipuri de adnotări. Și un cod de program prin reflecție parseaza datele. Obțineți cel puțin primul exemplu disponibil al site-ului StackOverflow:
În mod similar, puteți obține $ r-> getMethods de () și le analiza deja.
Ca urmare, această abordare a găsit o nouă utilizare. De exemplu, în Cadrul Symfony cu propriile adnotări (în plus față de configurația într-un YAML sau XML-fișiere) pot fi configurate aceleași entități direct în codul:
sau aceleași controlerele de rutare:
Iar cadrul este ușor datele analizează și cache-uri într-un simplu PHP-matrice, care nu le parsează din nou și din nou, de fiecare dată.
De asemenea, în testarea de clasă ne-am uitat ca adnotări și @dataProvider @group pentru testele efectuate în pachetul PHPUnit.
Această abordare are puțin de a face cu phpdoc originală, pentru că folosește pur și simplu ideea lui. Dar, în timp ce unul de altul unul nu și puteți utiliza în condiții de siguranță chei diferite împreună:
Multe astfel de abordare a adnotări în configurarea Symfony nu le place, deoarece încalcă principiul responsabilității unice, cod și configurația de amestec într-un singur fișier. Deci, utilizați la discreția ta.
Al optulea motiv: Apariția unor sisteme software pentru a sprijini adnotări specifice.
După aceea vor exista probleme cu autosubstitution, ortografierea mismatches tipul de variabile incerte pentru a redenumi automat câmpuri sau metode de orice clasă, și alte refactoring automate.
Asigurați-vă prieteni cu IDE și face viața mai ușoară.
Ei bine, un fel de, o vacanță în curând, așa că nu a dormit pomul de Crăciun: