| name | blade-ui-kit-bootstrap |
| description | Usage patterns for blade-ui-kit-bootstrap components. Activate when working with form, input, button, modal, alert, or badge components from this package, or when extending/customizing components via config or artisan command. |
| license | MIT |
| metadata | {"author":"forxer"} |
blade-ui-kit-bootstrap — Patterns détaillés
Patterns d'usage Blade
{{-- Form avec validation --}}
<x-form :action="route('posts.store')">
<x-label for="title" />
<x-input name="title" />
<x-error field="title" />
<x-btn-save />
</x-form>
{{-- PUT/PATCH --}}
<x-form :action="route('posts.update', $post)" method="PUT">...</x-form>
{{-- Upload de fichier --}}
<x-form :action="route('posts.store')" has-files>...</x-form>
{{-- Bouton de suppression avec confirmation --}}
<x-btn-delete
:url="route('posts.destroy', $post)"
confirm="Supprimer cet élément ?"
:confirm-id="'confirm-delete-'.$post->id"
/>
<x-confirm-modal :id="'confirm-delete-'.$post->id" />
{{-- Modal classique --}}
<x-btn data-bs-toggle="modal" data-bs-target="#my-modal">Ouvrir</x-btn>
<x-modal id="my-modal" title="Titre">
Contenu
<x-slot:footer><x-btn-cancel data-bs-dismiss="modal" /></x-slot>
</x-modal>
{{-- Modal avec formulaire --}}
<x-form-modal id="edit-modal" title="Modifier" :action="route('posts.update', $post)" method="PUT">
...
</x-form-modal>
Extension de composants
php artisan make:blade-ui-kit-bs-component MonBouton --extends=btn-save
- Hook
onAttributesSet() : personnaliser les valeurs par défaut et ajouter de la logique post-hydratation
- Toujours
??= pour que les props passées en template priment sur les defaults
- Pas de
parent::onAttributesSet() — le package appelle initAttributes() automatiquement après
protected function onAttributesSet(): void
{
$this->variant ??= 'danger';
$this->text ??= 'Mon libellé';
}
Propriétés custom (extra properties)
Pour ajouter une propriété typée sans redéclarer le constructeur parent :
class Archives extends Base
{
public ?int $itemsInArchives = null;
protected function onAttributesSet(): void
{
if ($this->itemsInArchives !== null) {
$badge = '<span class="badge text-bg-light">'.$this->itemsInArchives.'</span>';
$this->endContent = $this->endContent !== null
? $this->endContent.' '.$badge
: $badge;
}
}
}
<x-btn-archives :url="route('archives')" :items-in-archives="$count" />
- Coercion de type automatique (
int, float, bool, string)
- Conversion kebab-case → camelCase transparente
- Voir
docs/extending-components.md section "Adding Custom Properties" pour le détail complet
Enregistrement dans config/blade-ui-kit-bootstrap.php :
'components' => ServiceProvider::defaultComponents()
->merge(['mon-bouton' => MonBouton::class])
->replace(['btn-save' => MonBouton::class])
->replaceAlias(['btn-save' => 'save'])
->except(['date', 'time'])
->components(),
Stacks layout
À inclure dans le layout de l'application :
@stack('blade-ui-kit-bs-styles') {{-- dans <head> --}}
@stack('blade-ui-kit-bs-html') {{-- avant </body> --}}
@stack('blade-ui-kit-bs-scripts') {{-- avant </body> --}}
Config keys
| Clé | Valeur par défaut | Description |
|---|
bootstrap_version | BootstrapVersion::V5 | Version Bootstrap (V4 ou V5) |
prefix | '' | Préfixe composants (ex: 'bs' → <x-bs-input>) |
all_forms_with_novalidate | true | Attribut novalidate sur tous les formulaires |
all_buttons_outline | false | Tous les boutons en style outline |
alert_icon_format | null | Format sprintf pour icône dans les alertes |
btn_start_icon_format | null | Format sprintf pour icône avant le texte |
btn_end_icon_format | null | Format sprintf pour icône après le texte |
enable_test_routes | APP_DEBUG | Active les routes de test/démo des composants |
Valeurs contraintes & support IDE
Les valeurs contraintes (variant, size, type, méthode HTTP, taille de modale) sont définies par des enums référentiels dans BladeUIKitBootstrap\Enums (BtnVariant, AlertVariant, BadgeVariant, BtnSize, BtnType, HttpMethod, ModalSize) : ils sont la source de vérité de la validation (valeur invalide → InvalidArgumentException) et sont documentés en PHPDoc @var/@param sur les composants (IntelliSense au niveau PHP). Note : les IDE complètent les noms de composants/attributs dans les balises <x-…>, mais ne remontent pas la complétion des valeurs ni les descriptions PHPDoc à l'intérieur des balises Blade.
Liste complète des action buttons
btn-save, btn-create, btn-edit, btn-duplicate, btn-delete, btn-destroy, btn-cancel,
btn-back, btn-back-list, btn-back-home, btn-show, btn-copy, btn-preview,
btn-logout, btn-email, btn-phone, btn-website, btn-archive, btn-archives,
btn-restore, btn-recycle-bin, btn-enable, btn-enabled, btn-disable, btn-disabled,
btn-move-up, btn-move-down, btn-confirm-modal-yes, btn-confirm-modal-no
btn-copy (props target ou string — exactement une des deux, sinon
InvalidArgumentException) utilise l'API native navigator.clipboard via des attributs
data-buk-copy-target/data-buk-copy-text et un listener délégué sur document — aucune
dépendance JS externe, fonctionne avec les boutons injectés après coup (Livewire). Nécessite un
contexte sécurisé (HTTPS ou localhost). Émet les CustomEvent buk-copy:success /
buk-copy:error (event.detail.text). Pour une vue livrée en fragment AJAX (modale chargée à la
demande), terminer la vue par @stack('blade-ui-kit-bs-scripts') — le script est idempotent.
Règles
- ❌
initAttributes() — supprimé en v2, utiliser onAttributesSet()
- ❌
onConstructing() — supprimé en v2, utiliser onAttributesSet()
- ❌ Hardcoder
is-invalid — géré automatiquement par le package
- ❌
Blade::component() dans un ServiceProvider — utiliser le fichier de config
- ✅
onAttributesSet() + ??= pour toute extension (pas de parent:: nécessaire)
- ✅ Enregistrer via
config/blade-ui-kit-bootstrap.php
- ✅ Échapper soi-même les données non sûres passées aux attributs de contenu (
title, text, confirm, startContent, endContent, content) avec e() — rendus en brut (HTML autorisé), le composant ne les auto-échappe pas
Génération de métadonnées IDE
php artisan blade-ui-kit-bs:ide
php artisan blade-ui-kit-bs:ide --no-interaction
Fichiers générés :
| Fichier | Emplacement | Consommateur | Rôle |
|---|
blade-ui-kit-bootstrap.code-snippets | .vscode/ | VS Code (natif) | Snippets — fallback sans installation d'extension |
blade-ui-kit-bootstrap.html-data.json | .vscode/ | Extension VS Code dédiée (à venir) | Complétion attributs/valeurs + hover en mode Blade |
ide.json | ide-helper/blade-ui-kit-bootstrap/ | PhpStorm / Laravel Idea | Mapping alias→classe (auto-détecté, scan récursif + fusion ; coexiste avec un ide.json racine de l'app) |
- La commande respecte le
prefix configuré et les personnalisations merge()/replace().
- Committer les fichiers générés pour que toute l'équipe en bénéficie.
- Automatiser via
composer.json post-update-cmd : @php artisan blade-ui-kit-bs:ide --no-interaction.
- Voir
docs/ide-autocomplete.md pour la documentation complète.
Références internes
docs/forms.md — form, label, errordocs/inputs/ — tous les inputsdocs/buttons/ — boutons et action buttonsdocs/modals.md — modal, form-modal, confirm-modaldocs/extending-components.md — guide complet d'extensiondocs/configuration.md — toutes les options de configdocs/ide-autocomplete.md — commande blade-ui-kit-bs:ide, snippets VS Code, Custom Data, PhpStorm
