Her yerde katı tür kullanımı

Spec Spec: ISO 32000-2, §7.5.5 ISO 32000-2 §7.5.5 Evidence { } Code-backed Evidence: Code-backed PHPStan Level 10, no src baseline PHPStan: Level 10, no src baseline

Bir bakışta

NextPDF, motor kaynağını herhangi bir bastırma temel çizgisi kullanmadan PHPStan ile Level 10’da çalıştırır. Bu sayfa, “temel çizgi yok” yaklaşımının neden bir araç ayrıntısından ibaret değil, bir tasarım kararı olduğunu ve verileri sessizce yanlış işlememesi gereken bir işlem hattına bu katılığın somut olarak ne kazandırdığını açıklar.

Bunun neden önemli olduğu

Çoğu uygulamada katı tür kullanımı bir hijyen önlemidir. Bir PDF motorunda ise daha çok bir doğruluk mekanizmasıdır. Bu biçim hatayı affetmez. Bir okuyucunun, dosyanın sonundan başlayarak treyler ve çapraz başvuru tablosu üzerinden okuyup içeriği bulması beklenir; dolayısıyla yazıcı tarafındaki bayt uzaklıkları tam olmalıdır. Sessizce mixed türüne genişleyen bir türü, bir int değerinin sessizce bir string hâline gelmesini ya da denetlenmeden başvurusu çözülen, null olabilen bir değeri düşünün. Bunların herhangi biri, bir görüntüleyicide sorunsuz açılan ancak haftalar sonra başka bir görüntüleyicide doğrulamadan geçemeyen ve nedenini gösteren hiçbir yığın izi bırakmayan bir dosya üretebilir.

Bu alandaki pahalı hatalar, sessiz olanlardır. Katı tür kullanımıyla katı bir çözümleyicinin birleşimi, motorun sessiz çalışma zamanı hatalarının bir bölümünü gürültülü derleme zamanı hatalarına dönüştürme yöntemidir.

Kısa özet

• Motor kaynağı en katı düzey olan PHPStan Level 10 ile çözümlenir ve bu, phpstan.neon.dist içinde doğrulanır.
• Burada kaynak bastırma temel çizgisi yoktur. Yapılandırma, kaynak çözümlemesini sıfır hatada kilitler. Bir gerileme, büyüyen bir yok sayma dosyasına soğurulmak yerine derlemeyi başarısız kılar.
• Var olan birkaç ignoreErrors girdisi yapılandırmada dar kapsamlıdır, tanımlayıcı ve yol bazında sınırlıdır ve teker teker gerekçelendirilmiştir (paketler arası gevşek bağımlılık sınırları ve yansıma hedefli test kesişimleri) — toplu bir temel çizgi değildir.
• Ayrı bir katı profil, level: max ile çalışır ve herhangi bir yeni yok sayma girdisini yasaklar; böylece yeni kod daha da sıkı bir standarda tabi tutulur.
• Amaçlanan etki tasarım baskısıdır: tür açısından dürüst biçimde ifade edilemeyen kod geçemez, dolayısıyla bastırılmak yerine yeniden tasarlanır.

NextPDF buna nasıl yaklaşır

“Katı bir çözümleyici kullanıyoruz” ile “temel çizgisi olmayan katı bir çözümleyici kullanıyoruz” arasındaki fark işin tüm özüdür; bu nedenle ifadeyi kesinleştirmek gerekir.

Bir temel çizgi, var olan her ihlali kaydeder ve çözümleyiciye tam olarak bunları yok saymasını söyler. Bu, eski bir kod tabanında statik çözümlemeyi benimsemenin pratik bir yoludur, ancak bir bedeli vardır. Temel çizgi, tür sisteminin bakmamaya karar verdiği sessiz bir borç defterine dönüşür. Aynı türden yeni ihlaller, var olanların yanına fark edilmeden sızabilir. Çözümleyicinin verdiği güvence, “bu kod tür açısından temizdir”den “bu kod eskisinden daha kötü değildir”e zayıflar.

NextPDF, motor kaynağı için bu ödünleşimi yapmaz. Yapılandırma, kaynak çözümlemesini sıfır hatada sabitler ve reportUnmatchedIgnoredErrors ayarını açar; böylece eskimiş bir bastırma — artık hiçbir şeyle eşleşmeyen bir bastırma — bile derlemeyi başarısız kılar. Geriye kalan dar kapsamlı yok saymalar, belirli bir hata tanımlayıcısı ve dosyayla sınırlandırılmıştır. Her biri, sınırın neden kasıtlı olduğuna dair satır içi bir açıklama taşır (örneğin, çekirdeğin bilinçli olarak somut bağımlılık kurmadığı bir Pro/Enterprise arabirimine göre programlanması). Bir inceleyici her birini okuyabilir ve değerlendirebilir. Takibi kaybedilecek belirsiz bir liste yoktur.

Bunu dürüst tutan akış:

1. Change proposed New or modified engine code.
2. Level 10 analysis Strictest PHPStan level over src/, treatPhpDocTypesAsCertain on.
3. Zero-error gate No source baseline; unmatched ignores also fail.
4. Strict profile level: max; no new ignore entries permitted.
5. Redesign, not suppress If it cannot be expressed honestly, the design changes.

Bir değişikliğin motor kaynağına nasıl ulaştığı: tür açısından dürüst olmayan bir değişiklik kapıdan geçemez, dolayısıyla bastırılmak yerine yeniden tasarlanır.

treatPhpDocTypesAsCertain bunun bir parçasıdır. PHPDoc ek açıklamaları kesin doğrular olarak ele alınır; bu nedenle bir @param list<T> veya @return non-empty-string, çözümleyicinin nazikçe yok saydığı bir yorum değildir. Bu, denetlenen bir taahhüttür. Ek açıklama ile çalışma zamanı türünün uyuşması zorunlu kılınır.

Kanıt ne söylüyor

Bu sayfa Evidence { } Code-backed Evidence: Code-backed niteliğindedir. Kanıt, yapılandırmanın kendisidir:

• phpstan.neon.dist, level: 10 ve phpVersion: 80400 değerlerini ayarlar, src dizinini çözümler ve hiçbir baseline: anahtarı içermez — kaynak çözümlemesi için bir phpstan-baseline.neon yoktur.
• Aynı dosya, L10 kaynak çözümlemesinin sıfır hatada kilitli olduğunu ve herhangi bir gerilemenin CI’yı başarısız kılması gerektiğini belirten satır içi bir notla birlikte treatPhpDocTypesAsCertain: true ve reportUnmatchedIgnoredErrors: true değerlerini ayarlar.
• Geriye kalan ignoreErrors girdilerinin her biri identifier ve çoğu kez path ile sınırlandırılmıştır ve gevşek bağımlılık ile yansıma hedefi gerekçesini açıklayan yorumlar içerir — toplu olarak üretilmiş bir temel çizgi değildir.
• phpstan-strict.neon.dist, bu yapılandırmayı devralır, düzeyi max değerine yükseltir ve yok sayma listesini dondurur; böylece katı profil altında hiçbir yeni girdi eklenemez.

Standartlar açısından bakıldığında durum nettir. Motor, bir okuyucunun treyler ve çapraz başvuru tablosu üzerinden gezinebileceği dosyalar üretmelidir; bunun dayanağı şudur: Spec Spec: ISO 32000-2, §7.5.5 ISO 32000-2 §7.5.5 . Tam bayt uzaklıkları, bir serileştirme sorunu olmadan önce bir tür sorunudur. Bir uzaklık, asla sessizce başka bir şeye dönüşmemesi gereken bir tam sayıdır. Level 10’da tür açısından temiz olan bir işlem hattı, aritmetiğin sessizce yanlış gidebileceği yolların çoğunu zaten ortadan kaldırmıştır.

Pratik örnek

Katı tür kullanımı en çok, bir alan kuralı, çalışma zamanı denetimi yerine tür olarak kodlandığında görünür. Uygunluk ayırt edicisi, spesifikasyon düzeyindeki soruları kapsamlı bir match ile yanıtlar; böylece işlenmeyen bir durum, yanlış bir PDF değil, bir tür hatasıdır:

declare(strict_types=1);

enum ConformanceMode: string
{
    case Plain  = 'plain';
    case PdfUa2 = 'pdfua2';
    case PdfA4  = 'pdfa4';

    /** @return 2|3|4|null */
    public function pdfaPart(): ?int
    {
        return match ($this) {
            self::PdfA4 => 4,
            default     => null,
        };
    }
}

Bu @return 2|3|4|null yalnızca belge niteliğinde değildir. Bu sözleşme treatPhpDocTypesAsCertain altında denetlenir. Sonucun her zaman bir int olduğunu varsayan çağıran kod, uyumlu olmayan bir PDF/A parça numarasının tek bir baytı bile yazılmadan önce, çözümleme sırasında bu konuda uyarılır.

Yaygın yanlış anlama

Tuzak, “temel çizgi yok” ifadesini “kodda tesadüfen hiçbir ihlal bulunmuyor” şeklinde okumaktır. Bu, durumu tersinden okumaktır. Bir temel çizginin bulunmaması, şanslı bir sonuç değil, nedendir. Bir ihlali bırakacak hiçbir yer olmadığından, böyle bir ihlal üretecek kodun farklı biçimde yazılması gerekir. Kaynak temel çizgisi olmayan Level 10, tasarımı sonradan betimleyen bir karne değil, tasarımı biçimlendiren bir kısıttır.

İkinci bir yanlış anlama: birkaç ignoreErrors girdisinin başka bir adla bir temel çizgi olduğu sanısı. Değildir. Bir temel çizgi, toplu olarak üretilir ve belirsizdir. Bunlar ise teker teker yazılmış, tanımlayıcı bazında sınırlı, açıklanmış ve reportUnmatchedIgnoredErrors ile korunduğundan fark edilmeden çürüyemezler.

Human-factors note: Human-factors note

“Temel çizgi yok” ve “Level 10” birlikte, en üste yakın bir yerde belirtilir ve metin boyunca aynı sözcüklerle yinelenir — çünkü en önemli tek mesajın önce gelmesi ve tutarlı kalması gerekir. Dar kapsamlı, açıklanmış, kendiliğinden geçerliliğini yitiren bir yok sayma ile belirsiz bir borç defteri arasındaki ayrım, bu sayfanın taşıyıcı fikridir; bu nedenle okuyucunun çıkarımına bırakılmak yerine açıkça adlandırılmıştır.

Sınırlar ve kapsam

Bu sayfa, motor kaynağı çözümlemesiyle ilgilidir. Test paketi, ayrı ve bilinçli olarak farklı bir kapsam ve yapılandırmayla çözümlenir; buradaki “temel çizgi yok” ifadesi src/ için geçerlidir, depodaki her yardımcı çözümlemenin temel çizgisiz olduğu iddiası değildir. PHPStan, davranışsal doğruluğu değil, tür sağlamlığını kanıtlar. Test piramidinin yerini almaz; yalnızca testlerin aksi takdirde peşine düşmesi gereken bir hata kategorisini ortadan kaldırır. Kullanılan düzey, bayraklar ve yok sayma kümesi, bu sayfanın inceleme tarihi itibarıyla doğrudur. Yetkili kaynak her zaman çekirdek deposundaki phpstan.neon.dist ve phpstan-strict.neon.dist dosyalarıdır.

Sürüm, bu disiplini değiştirmez. Her sürüm aynı Level 10 kaynağından derlenir:

Level 10 source analysis — edition availability

Edition	Availability
Core	○ Çekirdek kaynağı, kaynak temel çizgisi olmadan Level 10’da çözümlenir.
Pro	○ Pro, aynı Level 10 kaynak disiplini üzerine kuruludur.
Enterprise	○ Enterprise, aynı Level 10 kaynak disiplini üzerine kuruludur.

İlgili belgeler

• PHP 8.4 temelleri — tür sisteminin dayandığı dil özellikleri.
• Bir özellik olarak hatalar — katı tür kullanımının ortaya çıkardığı hatalara ne olduğu.
• İşlem hattı modeli — bu disiplinin koruduğu mimari.

Sözlük

• PHPStan Level 10 — türsüz ve gevşek türlenmiş değerleri uyarı yerine hata olarak ele alan en katı çözümleme düzeyi.
• Temel çizgi — çözümleyiciye yok sayması söylenen, var olan ihlallerin üretilmiş bir kaydı. NextPDF, motor kaynağı için hiçbirini kullanmaz.
• treatPhpDocTypesAsCertain — PHPDoc tür ek açıklamalarını öneri niteliğindeki yorumlar olarak değil, denetlenmiş gerçekler olarak ele alan bir PHPStan ayarı.
• reportUnmatchedIgnoredErrors — bir yok sayma girdisi artık hiçbir şeyle eşleşmediğinde derlemeyi başarısız kılan ve eskimiş bastırmaları önleyen bir ayar.
• Tasarım baskısı — kodu yalnızca ölçen bir denetimin aksine, kodun belirli bir biçimde yazılmasını zorunlu kılan bir kısıtlamanın etkisi.