Folosiți PHP NoDiscard pentru rezultate care contează în contract

Unele funcții își fac treaba utilă prin valoarea returnată. Apelarea lor urmată de eliminarea rezultatului poate lăsa impresia unei activități, deși starea dorită a programului nu se schimbă. Atributul NoDiscard din PHP le permite autorilor de API să semnaleze această greșeală. Este util mai ales când pierderea rezultatului încalcă obligațiile apelantului, nu ca ornament pentru orice metodă care returnează ceva.

PHP 8.5 a fost lansat la 20 noiembrie 2025. Anunțul lansării include NoDiscard printre noutăți. Data contează: anunțul anterior din aceeași lună, destinat testării versiunii candidate, nu era lansarea stabilă. Arhiva PHP pentru 2025 consemnează anunțurile separat.

Mecanismul are un scop precis. Marcați o funcție sau o metodă cu #[\NoDiscard], iar PHP emite un avertisment dacă valoarea returnată nu este folosită. O conversie explicită (void) suprimă avertismentul când eliminarea este intenționată. Manualul PHP documentează ambele comportamente. Niciunul nu dovedește că apelantul a interpretat corect valoarea sau că operațiunea a reușit.

Porniți de la consecința pierderii valorii

Un obiect imutabil oferă un exemplu ipotetic util. O metodă care returnează o copie modificată lasă originalul neschimbat. Dacă apelantul presupune modificarea originalului și ignoră copia, schimbarea cerută dispare din operațiunile sale ulterioare. Contează contractul dintre metodă și apelant, nu faptul că tipul returnat este un obiect.

Un rezultat care cuprinde erori individuale este alt candidat. Funcția își poate încheia activitatea și poate returna informații pe care apelantul trebuie să le inspecteze. Pierderea lor neobservată poate ascunde lucrări incomplete. Aici atributul atrage atenția asupra unei obligații care ar trebui explicată și în documentația API. Un mesaj de diagnostic nu poate înlocui explicația sensului rezultatului.

Întrebarea de selecție este concretă: ce poate merge prost dacă un apelant rezonabil trece cu vederea acest rezultat? Dacă răspunsul identifică un defect probabil, marcajul poate face greșeala vizibilă mai devreme. Dacă răspunsul spune doar că folosirea valorilor returnate arată în general ordine, marcajul poate aduce puțin. Consecința este un criteriu mai bun decât numărul metodelor de citire dintr-o clasă.

Avertismentul lasă obligații în seama apelantului

Atribuirea rezultatului unei variabile se consideră folosire, dar atribuirea singură nu poate stabili că apelantul verifică o eroare sau păstrează valoarea transformată. Programatorul poate și să trimită valoarea unei alte funcții care îi ignoră semnificația. NoDiscard detectează un singur tipar sintactic de pierdere. Tratarea corectă a rezultatului rămâne o proprietate semantică a programului.

Această limită ar trebui să ghideze răspunsul echipei la avertismente. Corectați presupunerea greșită a apelantului. Nu creați o variabilă altfel nefolosită doar pentru a ascunde mesajul și a declara apoi API-ul sigur. Variabila poate elimina simptomul vizibil, păstrând lipsa inițială de atenție față de rezultat.

Avertismentul emis nu stabilește un contract de excepții. Aplicațiile pot avea propriile reguli de tratare a erorilor, dar acelea alcătuiesc un nivel separat. Autorul unui API nu ar trebui să promită că NoDiscard va opri operațiunea, va anula modificările sau va impune o ramură de recuperare. Garanția documentată privește mesajul pentru un rezultat nefolosit.

Eliminarea deliberată ar trebui să arate intenția

Conversia (void) face explicită eliminarea intenționată în PHP 8.5. Poate fi potrivită când apelul are un efect secundar dorit de apelant și un rezultat de care acesta chiar nu are nevoie. Conversia îi oferă celui care verifică programul un loc în care să examineze alegerea. Prezența ei nu dovedește că alegerea a fost corectă.

O verificare utilă întreabă dacă informația ignorată ar putea schimba ce urmează. Dacă descrie o eroare parțială, justificarea eliminării trebuie să țină cont de acea eroare. Dacă altă parte a programului răspunde deja de rezultat, clarificați responsabilitatea în structura aplicației. Intenția are nevoie de un motiv legat de operațiune, nu de o exceptare generală.

Compatibilitatea contează când biblioteca acceptă versiuni PHP mai vechi. Manualul actual spune că atributul nu are efect înainte de PHP 8.5, iar conversia (void) nu este acceptată acolo. Documentează și comportamentul legat de declarația concretă a metodelor implementate și suprascrise. Aceste note actuale ale manualului ar trebui verificate față de versiunile de execuție acceptate; ele nu dovedesc că toate detaliile apăreau în anunțul lansării.

Marcarea generală poate slăbi semnalul

Cel mai puternic contraargument este obișnuirea cu avertismentele. Dacă orice metodă de citire primește atributul, apelanții pot învăța să suprime mecanic mesajele. Unele API-uri permit legitim ignorarea unui rezultat, iar un avertisment apărut în utilizarea obișnuită acceptată poate reduce atenția acordată greșelilor importante. Selecția contribuie la utilitatea avertismentului.

Aceasta nu înseamnă că metodele de citire sunt nepotrivite în toate cazurile. Numele sau categoria metodei nu poate decide singură. O citire aparent simplă poate fi utilă doar prin rezultatul ei, ceea ce face suspect un apel ignorat. Altă metodă poate returna informații opționale de confort pe lângă efectul ei principal. Evaluați contractele individual, fără să impuneți o regulă întregii clase.

Pentru bibliotecile existente, adăugarea mesajelor schimbă și experiența apelanților. Începeți cu un grup restrâns de metode ale căror rezultate impun obligații clare. Documentați de ce contează fiecare și inspectați moduri reprezentative de apelare înainte de extindere. Aceasta este o recomandare de adoptare, nu afirmația unei reduceri măsurate a avertismentelor sau a unei migrări încheiate.

Atributul oferă și ocazia de a reevalua API-urile ambigue. Dacă apelanții înțeleg frecvent diferit modificarea obiectelor sau informațiile returnate despre erori, un nume mai clar ori alt contract al rezultatului poate rezolva mai mult decât un avertisment. NoDiscard poate scoate confuzia la iveală, dar nu ar trebui folosit pentru a păstra la nesfârșit o structură neclară.

În mentenanța software, rezultatul util este un apelant care ține cont de o valoare importantă. Aplicați atributul acolo unde pierderea accidentală are o semnificație precisă, permiteți eliminarea explicită când operațiunea o justifică și evaluați separat comportamentul din jur. Mai puține avertismente ajută doar dacă obligațiile programului continuă să fie îndeplinite.