Blade-extensies van packages en de compilatiecache

Wanneer je vanuit een package Blade-syntaxis aanbiedt, scheid je het omzetten van de template naar PHP van het uitvoeren van de gegenereerde PHP. Als je de huidige configuratiewaarde tijdens het compileren insluit, kan een gecachte view oude waarden blijven tonen. Deze pagina verwijst naar de officiële Laravel-documentatie voor 13.x en de implementatie van Framework v13.37.0, en gaat dieper in op de basis van packageontwikkeling. Zie Blade voor de gewone templatesyntaxis en Views van packages overschrijven en bijwerken voor namespaces en het publiceren van views.

Scheid registreren, compileren en uitvoeren

De callback die je aan Blade::directive() doorgeeft, retourneert niet de waarde die getoond wordt, maar een string met de te genereren PHP-code. Ook het argument $expression is geen geëvalueerde waarde, maar de PHP-expressie zoals die in de template staat.

API	Rol van de geregistreerde callback	Moment van uitvoering
`Blade::directive()`	Genereert een string met PHP-code	Wanneer de betreffende directive wordt gecompileerd
`Blade::if()`	Beoordeelt de voorwaarde	Wanneer de gegenereerde PHP `Blade::check()` aanroept

Ook view:cache compileert. Ontwerp de genererende callback van een directive zo dat hij niet de huidige gebruiker ophaalt, niet naar de database schrijft en geen externe API’s aanroept.

Registreren onder een packagespecifieke naam

Als voorbeeld bieden we @acmeCourierLabel($code) aan, dat een geconfigureerd label vóór de verzendcode toont. We gaan ervan uit dat Acme\Courier\ via Composer PSR-4 aan src/ is gekoppeld en dat de provider via auto-discovery of handmatig wordt geregistreerd.

src/CourierServiceProvider.php

<?php

namespace Acme\Courier;

use Illuminate\Support\Facades\Blade;
use Illuminate\Support\ServiceProvider;

class CourierServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Blade::directive('acmeCourierLabel', function (string $expression): string {
            return "<?php echo e((string) config('courier.label', 'Tracking').': '.({$expression})); ?>";
        });

        Blade::if('acmeCourierEnabled', function (): bool {
            return (bool) config('courier.enabled', false);
        });
    }
}

In dit voorbeeld is het configuratiecontract dat courier.label een string is en courier.enabled een boolean. Zie Packageconfiguratie samenvoegen en cachen voor het distribueren en samenvoegen van configuratiebestanden. Registreer in de gewone boot() van de provider en plaats de registratie niet binnen een runningInConsole()-voorwaarde. Dezelfde extensies zijn nodig bij het renderen via HTTP en bij view:cache van Artisan. Maak een provider die alleen Blade-extensies registreert ook geen deferred provider die pas opstart wanneer een andere service wordt geresolved.

Argumenten komen binnen als expressie, niet als waarde

@acmeCourierLabel($code)

Bij deze template ontvangt de callback de string $code. De gegenereerde PHP ziet er als volgt uit.

<?php echo e((string) config('courier.label', 'Tracking').': '.($code)); ?>

config() en $code worden geëvalueerd op het moment dat deze PHP wordt uitgevoerd. Dat verschilt van een implementatie waarin de callback zelf config() leest en een vaste string retourneert. De onderzochte callCustomDirective() verwijdert de buitenste haakjes, trimt de expressie en geeft die door aan de callback. De argumenten worden niet naar PHP-waarden omgezet en ook niet in afzonderlijke argumenten opgesplitst. Dit voorbeeld wordt gepubliceerd als syntaxis die precies één verplichte expressie accepteert. Splits meerdere argumenten niet simpelweg met explode() op komma’s. Ook arrays, methodeaanroepen en stringliterals kunnen komma’s bevatten. Als je attributen of complexe HTML wilt verwerken, kun je de verantwoordelijkheden beter scheiden door een Blade-component aan te bieden.

Expressies in templates zijn PHP die door vertrouwde ontwikkelaars wordt geschreven. Stel templatebroncode niet samen uit gebruikersinvoer. Bovendien krijgt de echo van een eigen directive niet automatisch de escaping van de gewone {{ }}. In dit voorbeeld roept de gegenereerde PHP expliciet e() aan.

Naamconflicten zijn ook een compatibiliteitsprobleem

directive() slaat de handler op in een array met de naam als sleutel. Bij dezelfde naam wordt de vorige registratie overschreven, en compileStatement() kiest eigen directives vóór de ingebouwde conversiemethoden. De officiële tests bevatten ook een geval waarin foreach met een eigen registratie wordt overschreven. Vermijd algemene namen zoals label of enabled en ingebouwde namen, en gebruik een packagespecifiek prefix. Behandel de namen en argumenten die gebruikers in templates gebruiken als publieke API en lever een migratieprocedure bij wijzigingen.

Voorwaarden tijdens uitvoering beoordelen met Blade::if

De voorwaarde die in de bovenstaande provider is geregistreerd, kun je als volgt gebruiken.

@acmeCourierEnabled
    @acmeCourierLabel($code)
@else
    Verzendtracking is uitgeschakeld.
@endacmeCourierEnabled

Blade::if() slaat de voorwaardecallback op en registreert directives voor het begin, unless, else en het einde. Het begin in dit voorbeeld wordt omgezet naar de volgende PHP.

<?php if (\Illuminate\Support\Facades\Blade::check('acmeCourierEnabled')): ?>

De voorwaardecallback die de configuratie controleert, wordt tijdens de uitvoering vanuit check() aangeroepen. Het resultaat true of false wordt niet tijdens het compileren vastgelegd. Ook een HTTP-proces dat gecompileerde views gebruikt, moet de voorwaardecallback geregistreerd hebben. Deze syntaxis schakelt alleen de weergave om en is geen autorisatie voor verzendbewerkingen. Voer toegangscontrole ook uit op de route of bij de bewerking zelf.

Een package-update genereert views niet altijd automatisch opnieuw

De onderzochte Compiler::isExpired() controleert of er een cache bestaat en, afhankelijk van de configuratie, de wijzigingstijden van de bronview en het gecompileerde bestand. Wijzigingen aan directives in de provider worden niet als afhankelijk bestand gevolgd.

Wijziging	Gevolg voor de gecompileerde PHP
De code die `directive()` retourneert wijzigen	De oude PHP blijft staan, dus opnieuw compileren is nodig
Alleen de logica van de voorwaardecallback van `Blade::if()` wijzigen	De gegenereerde `check()` kan de nieuwe logica aanroepen, maar de nieuwe code moet geladen worden
De naam of het argumentcontract van een directive wijzigen	Gebruikers moeten hun templates aanpassen en opnieuw compileren
Views al naar de applicatie gepubliceerd	Alleen de views in het package bijwerken werkt de gepubliceerde kopieën niet bij

Ook de officiële documentatie adviseert om na het wijzigen van de logica van een directive de cache te verwijderen met view:clear. Voer dit uit in de deploymentstap van de gebruikende applicatie, nadat het bijgewerkte package en de views van de gebruiker op elkaar zijn afgestemd.

php artisan view:clear
php artisan view:cache

Voer view:cache uit wanneer je in productie vooraf compileert. Wis de cache niet bij elke boot() van het package en pas de deploymentstappen van de gebruikende applicatie bij de installatie niet zonder toestemming aan. Volg ook voor het vernieuwen van de configuratiecache en het herladen van langlevende processen de normale deploymentprocedure van de omgeving.

Compilatieresultaat en renderresultaat afzonderlijk controleren

Controleer eerst de gegenereerde PHP in een Laravel-testapplicatie waarin de bovenstaande provider is geregistreerd. Hieronder staat een methode die je toevoegt aan een Feature-test die Tests\TestCase uitbreidt.

public function test_label_directive_compiles_to_runtime_lookup(): void
{
    $compiled = \Illuminate\Support\Facades\Blade::compileString(
        '@acmeCourierLabel($code)',
    );

    $this->assertSame(
        "<?php echo e((string) config('courier.label', 'Tracking').': '.(\$code)); ?>",
        $compiled,
    );
}

Met deze test controleer je het contract voor het genereren van PHP, maar niet de escaping of de voorwaarden tijdens uitvoering. Voeg aan een echt package ook controles voor het renderen van views en voor updates toe.

Testgeval	Verwacht resultaat
Tekens die als HTML worden geïnterpreteerd in de verzendcode doorgeven	Worden geëscaped door de gegenereerde `e()`
Dezelfde gecompileerde view gebruiken en de labelconfiguratie vóór het renderen wijzigen	De volgende render toont de nieuwe configuratiewaarde
Renderen met `courier.enabled` op true en false	Alleen de bijbehorende tak wordt getoond
Een nieuwe applicatie opstarten na `view:cache`	De extensies zijn geregistreerd en het resultaat is hetzelfde als zonder vooraf compileren
De gegenereerde code van een directive wijzigen en deployen	Na het opnieuw opbouwen van de cache wordt de nieuwe PHP gebruikt
De ondersteunde Laravel-versie bijwerken	De tests voor gegenereerde code, renderen en cachegebruik slagen allemaal

Gerelateerde pagina’s

Views van packages overschrijven en bijwerken

Bekijk de zoekvolgorde van namespaces en hoe je gepubliceerde templates onderhoudt.

Packagecaches integreren in optimize

Bekijk hoe je het opbouwen en wissen van eigen caches integreert in de deploymentstappen.

AI-ontwikkeling

Design patterns

Package-ontwikkeling

Applicatiestructuur

Nieuwe functies in Laravel 13

Eloquent in detail

Validatie-uitbreidingen

Authenticatie uitbreiden

Beveiliging

Queues

Testen

Realtime

Blade-extensies van packages en de compilatiecache

Scheid registreren, compileren en uitvoeren

Registreren onder een packagespecifieke naam

Argumenten komen binnen als expressie, niet als waarde

Naamconflicten zijn ook een compatibiliteitsprobleem

Voorwaarden tijdens uitvoering beoordelen met Blade::if

Een package-update genereert views niet altijd automatisch opnieuw

Compilatieresultaat en renderresultaat afzonderlijk controleren

Gerelateerde pagina’s

Views van packages overschrijven en bijwerken

Packagecaches integreren in optimize

Geraadpleegde primaire bronnen

​Scheid registreren, compileren en uitvoeren

​Registreren onder een packagespecifieke naam

​Argumenten komen binnen als expressie, niet als waarde

​Naamconflicten zijn ook een compatibiliteitsprobleem

​Voorwaarden tijdens uitvoering beoordelen met Blade::if

​Een package-update genereert views niet altijd automatisch opnieuw

​Compilatieresultaat en renderresultaat afzonderlijk controleren

​Gerelateerde pagina’s

Views van packages overschrijven en bijwerken

Packagecaches integreren in optimize

​Geraadpleegde primaire bronnen

Scheid registreren, compileren en uitvoeren

Registreren onder een packagespecifieke naam

Argumenten komen binnen als expressie, niet als waarde

Naamconflicten zijn ook een compatibiliteitsprobleem

Voorwaarden tijdens uitvoering beoordelen met Blade::if

Een package-update genereert views niet altijd automatisch opnieuw

Compilatieresultaat en renderresultaat afzonderlijk controleren

Gerelateerde pagina’s

Geraadpleegde primaire bronnen