> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Blade-extensies van packages en de compilatiecache

> Op basis van de BladeCompiler van Laravel 13: eigen directives en voorwaarden registreren, compilatietijd en uitvoeringstijd scheiden en de viewcache controleren bij package-updates.

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](/nl/advanced/package-development). Zie [Blade](/nl/blade) voor de gewone templatesyntaxis en [Views van packages overschrijven en bijwerken](/nl/advanced/package-views) 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.

```mermaid theme={null}
flowchart TD
    A["Extensie registreren<br>in boot van de provider"] --> B["View renderen"]
    B --> C{"Compileren nodig?"}
    C -->|Yes| D["PHP-code genereren<br>met de callback van directive"]
    D --> E["Compilatieresultaat opslaan"]
    C -->|No| F["Opgeslagen PHP gebruiken"]
    E --> G["PHP uitvoeren en HTML genereren"]
    F --> G
    G --> H["Configuratie en argumenten<br>tijdens uitvoering raadplegen"]
```

| 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](/nl/advanced/package-discovery) of handmatig wordt geregistreerd.

```php src/CourierServiceProvider.php theme={null}
<?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](/nl/advanced/package-config-merging) 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

```blade theme={null}
@acmeCourierLabel($code)
```

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

```php theme={null}
<?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](/nl/blade) aan te bieden.

<Warning>
  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.
</Warning>

### 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.

```blade theme={null}
@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 theme={null}
<?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.

```bash theme={null}
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.

```php theme={null}
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

<Columns cols={2}>
  <Card title="Views van packages overschrijven en bijwerken" icon="eye" href="/nl/advanced/package-views">
    Bekijk de zoekvolgorde van namespaces en hoe je gepubliceerde templates onderhoudt.
  </Card>

  <Card title="Packagecaches integreren in optimize" icon="gears" href="/nl/advanced/package-optimization">
    Bekijk hoe je het opbouwen en wissen van eigen caches integreert in de deploymentstappen.
  </Card>
</Columns>

## Geraadpleegde primaire bronnen

* [Officiële Laravel-documentatie: Extending Blade en Custom if statements](https://github.com/laravel/docs/blob/12080c72699b99ec6573f7e79ff4834d9001b6bc/blade.md#extending-blade)
* [Officiële Laravel-documentatie: views en componenten van packages](https://github.com/laravel/docs/blob/12080c72699b99ec6573f7e79ff4834d9001b6bc/packages.md#views)
* [BladeCompiler: directive(), callCustomDirective(), compileStatement(), if() en check()](https://github.com/laravel/framework/blob/v13.37.0/src/Illuminate/View/Compilers/BladeCompiler.php)
* [Compiler: cachebeoordeling met isExpired()](https://github.com/laravel/framework/blob/v13.37.0/src/Illuminate/View/Compilers/Compiler.php)
* [BladeCustomTest: eigen directives, voorwaarden en het overschrijven van ingebouwde syntaxis](https://github.com/laravel/framework/blob/v13.37.0/tests/View/Blade/BladeCustomTest.php)


## Related topics

- [Geavanceerde onderwerpen](/nl/advanced/index.md)
- [Views van packages overschrijven en bijwerken](/nl/advanced/package-views.md)
- [Laravel Cloud Hibernation (automatische slaapstand)](/nl/blog/laravel-cloud-hibernation.md)
- [Laravel Sail](/nl/sail.md)
- [Publieke assets van packages publiceren en bijwerken](/nl/advanced/package-assets.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.